[tutorial v1.1_060)] A variable with type "web_address" (config and doc)

2025-11-07 06:37:27 +01:00 · 2025-11-07 06:37:27 +01:00 · e9787ca56f
commit e9787ca56f
parent 9ba18213f1
8 changed files with 125 additions and 9 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_053] Jinja with a description](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_053/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_053~1..v1.1_053))
+- [[tutorial v1.1_054] A conditional disabled variable with identifier](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_054/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_054~1..v1.1_054))

-# [tutorial v1.1_054)] A conditional disabled variable with identifier
+# [tutorial v1.1_060)] A variable with type "web_address"

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


 ## Screenshot
@ -112,11 +112,25 @@ manual:
        when: HTTPS
 ...

+```
+### firefox/30-auto.yml
+
+
+```yml
+%YAML 1.2
+---
+version: 1.1
+
+auto:
+  description: Automatic proxy configuration URL
+  type: web_address
+...
+
 ```
 ### Let's generate the documentation

 ```console
-foo@bar:~$ git switch --detach v1.1_054
+foo@bar:~$ git switch --detach v1.1_060
 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;   |
@ -164,19 +178,94 @@ This family builds families dynamically
 | **manual.*https*_proxy.port**<br/>**manual.*socks*_proxy.port**<br/>[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | *HTTPS* or *SOCKS* port.<br/>**Validators**: <br/>- well-known ports (1 to 1023) are allowed<br/>- registred ports (1024 to 49151) are allowed<br/>- private ports (greater than 49152) are allowed<br/>**Default**: the value of the variable "manual.http_proxy.port"                                                                                                                                                                                                                                                                                                                                             |
 | **manual.*https*_proxy.version**<br/>**manual.*socks*_proxy.version**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` *`disabled`*                                                                                                                                                                                                                                                                                                                                                                                                                                              | SOCKS host version used by proxy.<br/>**Choices**: <br/>- v4<br/>- v5 **← (default)**<br/>**Disabled**: when the identifier is "HTTPS"                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

+| 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;   | 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;   |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **auto**<br/>[`web_address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Automatic proxy configuration URL.<br/>**Validator**: the domain name in web address can be only a hostname                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
 ### Let's generate the changelog

 ```console
-foo@bar:~$ git switch --detach v1.1_054
+foo@bar:~$ git switch --detach v1.1_060
 foo@bar:~$ rougail -m firefox/ -o doc --doc.contents changelog
 ```
 #### New 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;   | 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;   |
-|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **manual.*https*_proxy.version**<br/>**manual.*socks*_proxy.version**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` *`disabled`*                                                                                                                                                                                                                                                                                                                                                                                                                                              | SOCKS host version used by proxy.<br/>**Choices**: <br/>- v4<br/>- v5 **← (default)**<br/>**Disabled**: when the identifier is "HTTPS"                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| 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;   | 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;   |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **auto**<br/>[`web_address`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Automatic proxy configuration URL.<br/>**Validator**: the domain name in web address can be only a hostname                                                                                                                                                                                                                                                                                                                                                                                                                                                         |


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


- [[tutorial v1.1_060] A variable with type "web_address"](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_060/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_060~1..v1.1_060))
+```yml
+---
+auto: https://auto.proxy.net/wpad.dat
+
+```
+#### Output
+
+```console
+foo@bar:~$ git switch --detach v1.1_060
+foo@bar:~$ rougail -m firefox/ -u yaml -ff config/01/config.yaml
+```
+<pre>╭──────── Caption ────────╮
+│ Variable <span style="color: #ffd700">Default value</span>  │
+│          Modified value │
+╰─────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
+<span style="color: #5c5cff">┗━━ </span>📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/01/config.yaml"
+</pre>
+### Example 2
+
+#### config/02/config.yaml
+
+
+```yml
+---
+proxy_mode: Automatic proxy configuration URL
+
+```
+#### Output
+
+```console
+foo@bar:~$ git switch --detach v1.1_060
+foo@bar:~$ rougail -m firefox/ -u yaml -ff config/02/config.yaml
+```
+<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
+<span style="color: #ff0000">┗━━ </span>The following variables are mandatory but have no value:
+<span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>Automatic proxy configuration URL
+</pre>
+### Example 3
+
+#### config/03/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_060
+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"
+</pre>
+
+
+- [[tutorial v1.1_061] A conditional disabled variable](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_061/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_061~1..v1.1_061))
--- a/config/01/config.yaml
+++ b/config/01/config.yaml
@ -0,0 +1,2 @@
+---
+auto: https://auto.proxy.net/wpad.dat
--- a/config/01/output_ro.html
+++ b/config/01/output_ro.html
@ -0,0 +1,8 @@
+<pre>╭──────── Caption ────────╮
+│ Variable <span style="color: #ffd700">Default value</span>  │
+│          Modified value │
+╰─────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
+<span style="color: #5c5cff">┗━━ </span>📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/01/config.yaml"
+</pre>
--- a/config/02/config.yaml
+++ b/config/02/config.yaml
@ -0,0 +1,2 @@
+---
+proxy_mode: Automatic proxy configuration URL
--- a/config/02/output_ro.html
+++ b/config/02/output_ro.html
@ -0,0 +1,4 @@
+<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
+<span style="color: #ff0000">┗━━ </span>The following variables are mandatory but have no value:
+<span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>Automatic proxy configuration URL
+</pre>
--- a/config/03/config.yaml
+++ b/config/03/config.yaml
@ -0,0 +1,3 @@
+---
+proxy_mode: Automatic proxy configuration URL
+auto: https://auto.proxy.net/wpad.dat
--- a/config/03/output_ro.html
+++ b/config/03/output_ro.html
@ -0,0 +1,8 @@
+<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"
+</pre>
--- a/firefox.png
+++ b/firefox.png