rougail-tutorials/README.md

- [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial 013] A sub family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_013/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_013~1..v1.1_013))

# [tutorial 014] Family in "shorthand" mode

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


## Screenshot


<img src="firefox.png" width=50% height=50% alt="Firefox Proxy setting"/>


## Structure


### firefox/00-proxy.yml


```yml
---
proxy_mode:
  description: Configure Proxy Access to the Internet
  choices:
    - No proxy
    - Auto-detect proxy settings for this network
    - Use system proxy settings
    - Manual proxy configuration
    - Automatic proxy configuration URL
  default: No proxy

```
### firefox/10-manual.yml


```yml
---
manual:
  description: Manual proxy configuration
  type: family
  disabled:
    variable: proxy_mode
    when_not: 'Manual proxy configuration'

  http_proxy:
    description: HTTP Proxy
    type: family

    address:
      description: HTTP address
      type: domainname

```
### Generated documentation

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -o doc -do github
```
### Variables

| 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;   | 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;   |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **proxy_mode**<br/>[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Configure Proxy Access to the Internet.<br/>**Choices**: <br/>- No proxy ← (default)<br/>- Auto-detect proxy settings for this network<br/>- Use system proxy settings<br/>- Manual proxy configuration<br/>- Automatic proxy configuration URL                                                                                                                                                                                                                                                                                                               |

#### Manual proxy configuration

_`disabled`_

**Disabled**: proxy_mode.

##### HTTP Proxy

| 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;   | 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;   |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual.http_proxy.address**<br/>[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory`                                                                                                                                                                                                                                                                                                                                                                                                                                         | HTTP address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |


## User data

### Example 1

#### config/01/config.yaml


```yml
---

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/01/config.yaml
```
<pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
│ <span style="color: #ffaf00">Unmodifiable variable</span>                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
</pre>
#### Output in read write mode

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/01/config.yaml --exporter.read_write
```
<pre><pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
</pre>
</pre>
### Example 2

#### config/02/config.yaml


```yml
---
proxy_mode: Manual proxy configuration

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/02/config.yaml
```
<pre>🛑 ERRORS
<span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
<span style="color: #ff0000">┗━━ </span>  - manual.http_proxy.address (HTTP address)
</pre>
#### Output in read write mode

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/02/config.yaml --exporter.read_write
```
<pre><pre>🛑 ERRORS
<span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
<span style="color: #ff0000">┗━━ </span>  - manual.http_proxy.address (HTTP address)
</pre>
</pre>
### Example 3

#### config/03/config.yaml


```yml
---
proxy_mode: Manual proxy configuration
manual:
  http_proxy:
    address: example.net

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml
```
<pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
<span style="color: #5c5cff">┗━━ </span>📂 manual
<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>📓 address: example.net
</pre>
#### Output in read write mode

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml --exporter.read_write
```
<pre><pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
<span style="color: #5c5cff">┗━━ </span>📂 manual
<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>📓 address: example.net
</pre>
</pre>
### Example 4

#### config/04/config.yaml


```yml
---
proxy_mode: Manual proxy configuration
manual:
  http_proxy:
    address: example.net
    port: '3128'

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/04/config.yaml
```
<pre>🛑 ERRORS
<span style="color: #ff0000">┗━━ </span>unknown option "port" in optiondescription "manual.http_proxy" (HTTP Proxy)
╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
<span style="color: #5c5cff">┗━━ </span>📂 manual
<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>📓 address: example.net
</pre>
#### Output in read write mode

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/04/config.yaml --exporter.read_write
```
<pre><pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
<span style="color: #5c5cff">┗━━ </span>📂 manual
<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>📓 address: example.net
</pre>
</pre>
### Example 5

#### config/05/config.yaml


```yml
---
proxy_mode: Manual proxy configuration
manual:
  http_proxy:
    address: http.proxy.net
    port: '3128'
  use_for_https: false
  https_proxy:
    address: https.proxy.net

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/05/config.yaml
```
<pre>🛑 ERRORS
<span style="color: #ff0000">┣━━ </span>unknown option "port" in optiondescription "manual.http_proxy" (HTTP Proxy)
<span style="color: #ff0000">┣━━ </span>unknown option "use_for_https" in optiondescription "manual" (Manual proxy configuration)
<span style="color: #ff0000">┗━━ </span>unknown option "https_proxy" in optiondescription "manual" (Manual proxy configuration)
╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
<span style="color: #5c5cff">┗━━ </span>📂 manual
<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>📓 address: http.proxy.net
</pre>
#### Output in read write mode

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/05/config.yaml --exporter.read_write
```
<pre><pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
<span style="color: #5c5cff">┗━━ </span>📂 manual
<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>📓 address: http.proxy.net
</pre>
</pre>


- [[tutorial 015] Family in "shorthand" mode](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_015/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_015~1..v1.1_015))