[tutorial v1.1_022] Putting a variable inside of a family or a sub family (config and doc)

2025-12-02 16:18:27 +01:00 · 2025-12-02 16:18:27 +01:00 · 9e55aba5b7
commit 9e55aba5b7
parent f945353fcb
11 changed files with 168 additions and 17 deletions
--- a/README.md
+++ b/README.md
@ -1,11 +1,11 @@
 - [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial v1.1_020] Creating a new family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_020/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_020~1..v1.1_020))
+- [[tutorial v1.1_021] Or a sub family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_021~1..v1.1_021))

-# [tutorial v1.1_021] Or a sub family
+# [tutorial v1.1_022] Putting a variable inside of a family or a sub family

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

-[Read the documentation](https://pedago.gwenaelremond.fr/bribes/rougail/tutorial/proxymode.html#or-a-sub-family)
+[Read the documentation](https://pedago.gwenaelremond.fr/bribes/rougail/tutorial/proxymode.html#putting-a-variable-inside-of-a-family-or-a-sub-family)


 ## Screenshot
@ -31,7 +31,7 @@ pip install rougail-cli rougail-output-exporter rougail-output-doc rougail-user-
 Then switch to the tutorial page:

 ```shell
-git switch --detach v1.1_021
+git switch --detach v1.1_022
 ```

 ## Structure
@ -39,10 +39,10 @@ git switch --detach v1.1_021


 <p>
-<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./">.</a><br/>
-	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./firefox/">firefox</a><br/>
-	    ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./firefox/00-proxy.yml">00-proxy.yml</a><br/>
-	    └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./firefox/10-manual.yml">10-manual.yml</a><br/>
+<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./">.</a><br/>
+	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./firefox/">firefox</a><br/>
+	    ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./firefox/00-proxy.yml">00-proxy.yml</a><br/>
+	    └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./firefox/10-manual.yml">10-manual.yml</a><br/>
 <br/><br/></p>

 Contents of the firefox/10-manual.yml file
@ -54,9 +54,9 @@ version: 1.1

 manual:  # Manual proxy configuration

-  http_proxy:
-    description: HTTP Proxy
-    type: family
+  http_proxy:  # HTTP Proxy
+
+    address:  # HTTP address
 ...

 ```
@ -69,6 +69,113 @@ rougail -m firefox/ -o doc
 |------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | **<a id="proxy_mode" name="proxy_mode">proxy_mode</a>**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | Configure Proxy Access to the Internet.<br/>**Choices**: <br/>•&nbsp;No proxy **← (default)**<br/>•&nbsp;Auto-detect proxy settings for this network<br/>•&nbsp;Use system proxy settings<br/>•&nbsp;Manual proxy configuration<br/>•&nbsp;Automatic proxy configuration URL |

+#### Manual proxy configuration
+
+> **🛈 Informations**
+> 
+> **Path**: manual
+
+##### HTTP Proxy
+
+> **🛈 Informations**
+> 
+> **Path**: manual.http_proxy
+
+| Variable                                                                                                                                                                                                | Description   |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| **<a id="manual.http_proxy.address" name="manual.http_proxy.address">manual.http_proxy.address</a>**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP address. |
+
+### Let's generate the changelog
+
+```shell
+rougail -m firefox/ -o doc --doc.contents changelog
+```
+#### New variable
+
+| Variable                                                                                                                                                                                                | Description   |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| **<a id="manual.http_proxy.address" name="manual.http_proxy.address">manual.http_proxy.address</a>**<br/>[`string`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP address. |


- [[tutorial v1.1_022] Putting a variable inside of a family or a sub family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_022~1..v1.1_022))
+## User datas
+
+### Example 1
+
+#### config/01/config.yml
+
+
+```yml
+---
+```
+#### Output
+
+```shell
+rougail -m firefox/ -u yaml -yf config/01/config.yml
+```
+<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>Manual proxy configuration
+<span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>HTTP Proxy
+<span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>HTTP address
+</pre>
+### Example 2
+
+#### config/02/config.yml
+
+
+```yml
+---
+manual:
+  http_proxy:
+    address: example.net
+```
+#### Output
+
+```shell
+rougail -m firefox/ -u yaml -yf config/02/config.yml
+```
+<pre>╭───────────────────── Caption ─────────────────────╮
+│ Variable                           <span style="color: #ffd700">Default value</span>  │
+│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #00aa00">Modified value</span> │
+╰───────────────────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
+<span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">HTTP address</span>: <span style="color: #00aa00">example.net</span> ◀ loaded from the YAML file 
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span>"config/02/config.yml"
+</pre>
+### Example 3
+
+#### config/03/config.yml
+
+
+```yml
+---
+manual:
+  http_proxy:
+    address: example.net
+    port: 3128
+```
+#### Output
+
+```shell
+rougail -m firefox/ -u yaml -yf config/03/config.yml
+```
+<pre><span style="font-weight: bold; color: #ffff00">🔔 WARNINGS</span>
+<span style="color: #ffff00">┗━━ </span>variable or family "manual.http_proxy.port" does not exist, it will be 
+<span style="color: #ffff00">    </span>ignored when loading from the YAML file "config/03/config.yml"
+╭───────────────────── Caption ─────────────────────╮
+│ Variable                           <span style="color: #ffd700">Default value</span>  │
+│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #00aa00">Modified value</span> │
+╰───────────────────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
+<span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">HTTP address</span>: <span style="color: #00aa00">example.net</span> ◀ loaded from the YAML file 
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span>"config/03/config.yml"
+</pre>
+
+
+- [[tutorial v1.1_030] A variable with type "domainname"](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_030/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_030~1..v1.1_030))
--- a/config/01/cmd_ro.txt
+++ b/config/01/cmd_ro.txt
@ -0,0 +1 @@
+rougail -m firefox/ -u yaml -yf config/01/config.yml
--- a/config/01/config.yml
+++ b/config/01/config.yml
@ -0,0 +1 @@
+---
--- a/config/01/output_ro.html
+++ b/config/01/output_ro.html
@ -0,0 +1,6 @@
+<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>Manual proxy configuration
+<span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>HTTP Proxy
+<span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>HTTP address
+</pre>
--- a/config/02/cmd_ro.txt
+++ b/config/02/cmd_ro.txt
@ -0,0 +1 @@
+rougail -m firefox/ -u yaml -yf config/02/config.yml
--- a/config/02/config.yml
+++ b/config/02/config.yml
@ -0,0 +1,4 @@
+---
+manual:
+  http_proxy:
+    address: example.net
--- a/config/02/output_ro.html
+++ b/config/02/output_ro.html
@ -0,0 +1,11 @@
+<pre>╭───────────────────── Caption ─────────────────────╮
+│ Variable                           <span style="color: #ffd700">Default value</span>  │
+│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #00aa00">Modified value</span> │
+╰───────────────────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
+<span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">HTTP address</span>: <span style="color: #00aa00">example.net</span> ◀ loaded from the YAML file 
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span>"config/02/config.yml"
+</pre>
--- a/config/03/cmd_ro.txt
+++ b/config/03/cmd_ro.txt
@ -0,0 +1 @@
+rougail -m firefox/ -u yaml -yf config/03/config.yml
--- a/config/03/config.yml
+++ b/config/03/config.yml
@ -0,0 +1,5 @@
+---
+manual:
+  http_proxy:
+    address: example.net
+    port: 3128
--- a/config/03/output_ro.html
+++ b/config/03/output_ro.html
@ -0,0 +1,14 @@
+<pre><span style="font-weight: bold; color: #ffff00">🔔 WARNINGS</span>
+<span style="color: #ffff00">┗━━ </span>variable or family "manual.http_proxy.port" does not exist, it will be 
+<span style="color: #ffff00">    </span>ignored when loading from the YAML file "config/03/config.yml"
+╭───────────────────── Caption ─────────────────────╮
+│ Variable                           <span style="color: #ffd700">Default value</span>  │
+│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #00aa00">Modified value</span> │
+╰───────────────────────────────────────────────────╯
+Variables:
+<span style="color: #5c5cff">┣━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
+<span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">HTTP address</span>: <span style="color: #00aa00">example.net</span> ◀ loaded from the YAML file 
+<span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span>"config/03/config.yml"
+</pre>
--- a/tree.html
+++ b/tree.html
@ -25,10 +25,10 @@
 </head>
 <body>
 	<h1>Directory Tree</h1><p>
-	<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./">.</a><br>
-	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./firefox/">firefox</a><br>
-	&nbsp;&nbsp;&nbsp; ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./firefox/00-proxy.yml">00-proxy.yml</a><br>
-	&nbsp;&nbsp;&nbsp; └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_021/./firefox/10-manual.yml">10-manual.yml</a><br>
+	<a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./">.</a><br>
+	└── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./firefox/">firefox</a><br>
+	&nbsp;&nbsp;&nbsp; ├── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./firefox/00-proxy.yml">00-proxy.yml</a><br>
+	&nbsp;&nbsp;&nbsp; └── <a href="https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_022/./firefox/10-manual.yml">10-manual.yml</a><br>
 <br><br><p>

 2 directories, 2 files
				`@ -0,0 +1 @@`
				`rougail -m firefox/ -u yaml -yf config/01/config.yml`