[tutorial v1.1_074)] Help (config and doc)

2025-11-07 06:37:34 +01:00 · 2025-11-07 06:37:34 +01:00 · 5adba25c94
commit 5adba25c94
parent ded507d19f
7 changed files with 125 additions and 8 deletions
--- a/README.md
+++ b/README.md
@ -1,9 +1,9 @@
 - [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial v1.1_072] A non mandatory variable](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_072/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_072~1..v1.1_072))
+- [[tutorial v1.1_073] Examples](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_073/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_073~1..v1.1_073))

-# [tutorial v1.1_073)] Examples
+# [tutorial v1.1_074)] Help

-[View the diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_073~1..v1.1_073)
+[View the diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_074~1..v1.1_074)


 ## Screenshot
@ -140,6 +140,7 @@ version: 1.1

 no_proxy:
  description: Address for which proxy will be desactivated
+  help: Connections to localhost, 127.0.0.1/8 and ::1 are never proxied
  examples:
    - .mozilla.org
    - .net.nz
@ -161,7 +162,7 @@ no_proxy:
 ### Let's generate the documentation

 ```console
-foo@bar:~$ git switch --detach v1.1_073
+foo@bar:~$ git switch --detach v1.1_074
 foo@bar:~$ rougail -m firefox/ -o doc
 ```
 | Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   | Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |
@ -212,21 +213,101 @@ This family builds families dynamically
 | Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   | Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |
 |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | **auto**<br/>[`web_address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` *`disabled`*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Automatic proxy configuration URL.<br/>**Validator**: the domain name in web address can be only a hostname<br/>**Disabled**: when the variable "proxy_mode" hasn't the value "Automatic proxy configuration URL"                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| **no_proxy**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) *`disabled`* `unique` `multiple`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Address for which proxy will be desactivated.<br/>**Validators**: <br/>- the domain name can starts by a dot<br/>- the domain name can be a hostname<br/>- the domain name can be an IP<br/>- the domain name can be network in CIDR format<br/>**Examples**: <br/>- .mozilla.org<br/>- .net.nz<br/>- 192.168.1.0/24<br/>**Disabled**: when the variable "proxy_mode" has the value "No proxy"                                                                                                                                                                                                                                                                                              |
+| **no_proxy**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) *`disabled`* `unique` `multiple`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Address for which proxy will be desactivated.<br/>Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.<br/>**Validators**: <br/>- the domain name can starts by a dot<br/>- the domain name can be a hostname<br/>- the domain name can be an IP<br/>- the domain name can be network in CIDR format<br/>**Examples**: <br/>- .mozilla.org<br/>- .net.nz<br/>- 192.168.1.0/24<br/>**Disabled**: when the variable "proxy_mode" has the value "No proxy"                                                                                                                                                                                                                         |

 ### Let's generate the changelog

 ```console
-foo@bar:~$ git switch --detach v1.1_073
+foo@bar:~$ git switch --detach v1.1_074
 foo@bar:~$ rougail -m firefox/ -o doc --doc.contents changelog
 ```
 #### Modified variable

 | Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   | Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |
 |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **no_proxy**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) *`disabled`* `unique` `multiple`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Address for which proxy will be desactivated.<br/>**Validators**: <br/>- the domain name can starts by a dot<br/>- the domain name can be a hostname<br/>- the domain name can be an IP<br/>- the domain name can be network in CIDR format<br/>**Examples**: <br/>- <ins>.mozilla.org</ins><br/>- <ins>.net.nz</ins><br/>- <ins>192.168.1.0/24</ins><br/>**Disabled**: when the variable "proxy_mode" has the value "No proxy"                                                                                                                                                                                                                                                             |
+| **no_proxy**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) *`disabled`* `unique` `multiple`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Address for which proxy will be desactivated.<br/><ins>Connections to localhost, 127.0.0.1/8 and ::1 are never proxied.</ins><br/>**Validators**: <br/>- the domain name can starts by a dot<br/>- the domain name can be a hostname<br/>- the domain name can be an IP<br/>- the domain name can be network in CIDR format<br/>**Examples**: <br/>- .mozilla.org<br/>- .net.nz<br/>- 192.168.1.0/24<br/>**Disabled**: when the variable "proxy_mode" has the value "No proxy"                                                                                                                                                                                                              |


+## User datas
+
+### Example 1
+
+#### config/01/config.yaml


- [[tutorial v1.1_074] Help](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_074/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_074~1..v1.1_074))
+```yml
+---
+
+```
+#### Output
+
+```console
+foo@bar:~$ git switch --detach v1.1_074
+foo@bar:~$ rougail -m firefox/ -u yaml -ff config/01/config.yaml
+```
+<pre>╭─────── Caption ────────╮
+│ Variable <span style="color: #ffd700">Default value</span> │
+╰────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
+</pre>
+### Example 2
+
+#### config/02/config.yaml
+
+
+```yml
+---
+proxy_mode: Automatic proxy configuration URL
+auto: https://auto.proxy.net/wpad.dat
+
+```
+#### Output
+
+```console
+foo@bar:~$ git switch --detach v1.1_074
+foo@bar:~$ rougail -m firefox/ -u yaml -ff config/02/config.yaml
+```
+<pre>╭────────────── Caption ───────────────╮
+│ Variable Modified value              │
+│          (<span style="color: #00aa00">⏳ Original default value</span>) │
+╰──────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/02/config.yaml" (⏳ <span style="color: #00aa00">No proxy</span>)
+<span style="color: #5c5cff">┣━━ </span>📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/02/config.yaml"
+<span style="color: #5c5cff">┗━━ </span>📓 Address for which proxy will be desactivated: 
+</pre>
+### Example 3
+
+#### config/03/config.yaml
+
+
+```yml
+---
+proxy_mode: Automatic proxy configuration URL
+auto: https://auto.proxy.net/wpad.dat
+no_proxy:
+  - .example.net
+  - 192.168.1.0/24
+
+```
+#### Output
+
+```console
+foo@bar:~$ git switch --detach v1.1_074
+foo@bar:~$ rougail -m firefox/ -u yaml -ff config/03/config.yaml
+```
+<pre>╭────────────── Caption ───────────────╮
+│ Variable Modified value              │
+│          (<span style="color: #00aa00">⏳ Original default value</span>) │
+╰──────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/03/config.yaml" (⏳ <span style="color: #00aa00">No proxy</span>)
+<span style="color: #5c5cff">┣━━ </span>📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/03/config.yaml"
+<span style="color: #5c5cff">┗━━ </span>📓 Address for which proxy will be desactivated:
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>.example.net ◀ loaded from the YAML file "config/03/config.yaml"
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>192.168.1.0/24 ◀ loaded from the YAML file "config/03/config.yaml"
+</pre>
+
+
+- [[tutorial v1.1_075] A variable](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_075/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_075~1..v1.1_075))
--- a/config/01/config.yaml
+++ b/config/01/config.yaml
@ -0,0 +1 @@
+---
--- a/config/01/output_ro.html
+++ b/config/01/output_ro.html
@ -0,0 +1,6 @@
+<pre>╭─────── Caption ────────╮
+│ Variable <span style="color: #ffd700">Default value</span> │
+╰────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
+</pre>
--- a/config/02/config.yaml
+++ b/config/02/config.yaml
@ -0,0 +1,3 @@
+---
+proxy_mode: Automatic proxy configuration URL
+auto: https://auto.proxy.net/wpad.dat
--- a/config/02/output_ro.html
+++ b/config/02/output_ro.html
@ -0,0 +1,9 @@
+<pre>╭────────────── Caption ───────────────╮
+│ Variable Modified value              │
+│          (<span style="color: #00aa00">⏳ Original default value</span>) │
+╰──────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/02/config.yaml" (⏳ <span style="color: #00aa00">No proxy</span>)
+<span style="color: #5c5cff">┣━━ </span>📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/02/config.yaml"
+<span style="color: #5c5cff">┗━━ </span>📓 Address for which proxy will be desactivated: 
+</pre>
--- a/config/03/config.yaml
+++ b/config/03/config.yaml
@ -0,0 +1,6 @@
+---
+proxy_mode: Automatic proxy configuration URL
+auto: https://auto.proxy.net/wpad.dat
+no_proxy:
+  - .example.net
+  - 192.168.1.0/24
--- a/config/03/output_ro.html
+++ b/config/03/output_ro.html
@ -0,0 +1,11 @@
+<pre>╭────────────── Caption ───────────────╮
+│ Variable Modified value              │
+│          (<span style="color: #00aa00">⏳ Original default value</span>) │
+╰──────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/03/config.yaml" (⏳ <span style="color: #00aa00">No proxy</span>)
+<span style="color: #5c5cff">┣━━ </span>📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/03/config.yaml"
+<span style="color: #5c5cff">┗━━ </span>📓 Address for which proxy will be desactivated:
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>.example.net ◀ loaded from the YAML file "config/03/config.yaml"
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>192.168.1.0/24 ◀ loaded from the YAML file "config/03/config.yaml"
+</pre>