build.py

@@ -1,34 +1,28 @@
 #!/usr/bin/env python3
 
-import sys
 from pathlib import Path
 from ruamel.yaml import YAML
 from ansi2html import Ansi2HTMLConverter
 
-from rougail import Rougail
-from rougail.config import get_rougail_config
+from rougail import RougailConfig, Rougail
 from rougail.output_exporter import RougailOutputExporter
 from rougail.user_data_file import RougailUserDataFile
 from rougail.output_doc import RougailOutputDoc
 
 
+NUM="50"
+
+
 if __name__ == "__main__":
-    version = sys.argv[1]
-#    rougailconfig = RougailConfig.copy()
-    rougailconfig = get_rougail_config(backward_compatibility=False, add_extra_options=False)
+    rougailconfig = RougailConfig.copy()
     rougailconfig['main_dictionaries'] = ['firefox']
-    rougailconfig['default_dictionary_format_version'] = version
-    if Path('config/namespace').is_file():
-        has_namespace = True
+    rougailconfig['default_dictionary_format_version'] = '1.1'
+    if Path('foxyproxy').is_dir():
         has_foxyproxy = False
-    elif Path('foxyproxy').is_dir():
-        has_foxyproxy = True
-        has_namespace = True
         rougailconfig['main_namespace'] = 'Firefox'
         rougailconfig['extra_dictionaries'] = {'FoxyProxy': ['foxyproxy']}
     else:
-        has_foxyproxy = False
-        has_namespace = False
+        has_foxyproxy = True
         rougailconfig['main_namespace'] = None
 #    rougailconfig['tiramisu_cache'] = "cache.py"
 #    rougail = Rougail(rougailconfig)
@@ -37,33 +31,19 @@ if __name__ == "__main__":
     rougailconfig['step.output'] = 'doc'
     rougailconfig['doc.output_format'] = 'github'
     rougailconfig['doc.title_level'] = 3
-    if Path('mode').is_file():
-        rougailconfig['modes_level'] = ['basic', 'standard', 'advanced']
-        has_mode = True
-    else:
-        has_mode = False
-    inventory = RougailOutputDoc(rougailconfig=rougailconfig.copy())
+    inventory = RougailOutputDoc(rougailconfig=rougailconfig)
     rougailconfig['step.output'] = 'exporter'
     header = inventory.formater.header()
-    summary = Path('summary_before.md')
-    if summary.is_file():
-        with summary.open('r') as sfh:
-            doc = sfh.read() + '\n\n'
-    else:
     doc = ''
     yaml = YAML()
     namespace = 'firefox'
     file_found = False
+    subdoc = ''
     if rougailconfig['main_namespace']:
         all_dirs = [[rougailconfig['main_dictionaries']], rougailconfig['extra_dictionaries'].values()]
     else:
         all_dirs = [[rougailconfig['main_dictionaries']]]
 
-    doc += inventory.formater.title('Screenshot', 2) + '\n'
-    doc += f'<img src="{namespace}.png" width=50% height=50% alt="{namespace.capitalize()} Proxy setting"/>\n\n'
-#    with doc_file.open('r') as docfh:
-#        doc += docfh.read()
-    doc += '\n' + inventory.formater.title('Structure', 2) + '\n'
     for r in all_dirs:
         for dirs in r:
             for d in dirs:
@@ -73,97 +53,80 @@ if __name__ == "__main__":
                     namespace = f.parent.name
                     file_found = True
                     if f.name.endswith('.yml') or f.name.endswith('.yaml'):
-                        doc += inventory.formater.title(str(f), 3)
-                        doc += '\n```yml\n'
+                        subdoc += inventory.formater.title(str(f), 2)
                         with f.open(encoding="utf8") as file_fh:
-                            doc += file_fh.read()
-                        doc += '\n```\n'
-    inv_doc = inventory.gen_doc()
-    if file_found and inv_doc:
-        doc += inventory.formater.title('Generated documentation', 3)
-        CMD = f"foo@bar:~$ rougail -v {version} -m firefox/ "
-        if has_namespace:
-            CMD += "-s Firefox "
+                            objects = yaml.load(file_fh)
+                        subdoc += inventory.formater.yaml(objects)
+#    doc += f'![{namespace.capitalize()} Proxy setting]({namespace}.png)\n'
+    doc += f'<img src="{namespace}.png" width=50% height=50% alt="{namespace.capitalize()} Proxy setting"/>\n\n'
+    with Path('summary.md').open('r') as sfh:
+        summary = sfh.read()
+    doc_file = Path('README.md')
+    doc = header + inventory.formater.title('Summary', 1) + '\n' + summary + '\n\n' + inventory.formater.title('Structural files', 1) + doc + '\n' + subdoc
+    with doc_file.open('r') as docfh:
+        doc += inventory.formater.title('Description', 2) + docfh.read()
+    if file_found:
+        doc += inventory.formater.title('Generated documentation', 2)
         if has_foxyproxy:
-            CMD += "-xn FoxyProxy -xd 0 foxyproxy/ "
-        if has_mode:
-            CMD += "--modes_level basic standard advanced "
-        cmd = CMD + "-o doc -do github"
+            cmd = f"foo@bar:~$ rougail -v 1.1 -m firefox -o doc -do github"
+        else:
+            cmd = f"foo@bar:~$ rougail -v 1.1 -m firefox -n Firefox -e FoxyProxy -d 1 foxyproxy -o doc -do github"
         doc += f'```console\n{cmd}\n```\n'
-        doc += inv_doc
+        doc += inventory.gen_doc()
     #
     config = Path('config')
     if config.is_dir():
-        doc += inventory.formater.title('User data', 2)
+        doc += inventory.formater.title('User data', 1)
         configs = list(config.iterdir())
         configs.sort()
         for idx, dirname in enumerate(configs):
-            if dirname.is_file():
-                continue
             for filename in dirname.iterdir():
                 if filename.name.endswith('.yml') or filename.name.endswith('.yaml'):
-                    doc += inventory.formater.title(f'Example {idx + 1}', 3)
-                    doc += inventory.formater.title(str(filename), 4)
-                    doc += '\n```yml\n'
+                    doc += inventory.formater.title(f'Example {idx + 1}', 2)
                     with filename.open(encoding="utf8") as file_fh:
-                        doc += file_fh.read()
-                    doc += '\n```\n'
-#                    with filename.open(encoding="utf8") as file_fh:
-#                        objects = yaml.load(file_fh)
-#                    doc += inventory.formater.yaml(objects)
-                    #readme = dirname / 'README.md'
-                    #if readme.is_file():
-                    #    doc += inventory.formater.title('Description', 4)
-                    #    with readme.open() as fh:
-                    #        doc += fh.read() + '\n\n'
+                        objects = yaml.load(file_fh)
+                    doc += inventory.formater.title(str(filename), 3)
+                    doc += inventory.formater.yaml(objects)
+                    readme = dirname / 'README.md'
+                    if readme.is_file():
+                        doc += inventory.formater.title('Description', 3)
+                        with readme.open() as fh:
+                            doc += fh.read() + '\n\n'
                     rougail = Rougail(rougailconfig)
                     tiramisu_config = rougail.get_config()
                     rougailconfig['step.user_data'] = ['file']
-                    rougailconfig['file.filename'] = [str(filename.absolute())]
+                    rougailconfig['file.filename'] = str(filename.absolute())
                     data = RougailUserDataFile(tiramisu_config, rougailconfig=rougailconfig)
-                    ret = data.run()
-                    errors = rougail.user_datas(ret)
-                    export = RougailOutputExporter(tiramisu_config,
-                                                   rougailconfig=rougailconfig,
-                                                   user_data_errors=errors['errors'],
-                                                   user_data_warnings=errors['warnings'],
-                                                   )
+                    data.read()
+                    export = RougailOutputExporter(tiramisu_config, rougailconfig=rougailconfig)
+                    export.errors = data.errors
+                    export.warnings = data.warnings
                     export.exporter()
                     with export.formater.console.capture() as capture:
                         export.print()
                     conv = Ansi2HTMLConverter(inline=True)
-                    doc += inventory.formater.title('Output', 4)
-                    cmd = CMD + f"-u file -ff {filename}"
+                    doc += inventory.formater.title('Output', 3)
+                    if has_foxyproxy:
+                        cmd = f"foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff {filename}"
+                    else:
+                        cmd = f"foo@bar:~$ rougail -v 1.1 -m firefox -n Firefox -e FoxyProxy -d 1 foxyproxy -u file -ff {filename}"
                     doc += f"```console\n{cmd}\n```\n"
-                    conv_data = '<pre>' + conv.convert(capture.get(), full=False) + "</pre>\n"
-                    doc += conv_data
-                    with open(dirname / 'output_ro.html', 'w') as fh_output:
-                        fh_output.write(conv_data)
-                    if (config / 'read_write').is_file():
+                    doc += '<pre>' + conv.convert(capture.get(), full=False) + "</pre>\n"
+                    if (dirname / 'read_write').is_file():
                         rougailconfig['exporter.read_write'] = True
-                        export = RougailOutputExporter(tiramisu_config,
-                                                       rougailconfig=rougailconfig,
-                                                       user_data_errors=data.errors,
-                                                       user_data_warnings=data.warnings,
-                                                       )
+                        export = RougailOutputExporter(tiramisu_config, rougailconfig=rougailconfig)
                         export.exporter()
                         with export.formater.console.capture() as capture:
                             export.print()
                         conv = Ansi2HTMLConverter(inline=True)
-                        doc += inventory.formater.title('Output in read write mode', 4)
-                        cmd = cmd + " --exporter.read_write"
+                        doc += inventory.formater.title('Output in read write mode', 3)
+                        if has_foxyproxy:
+                            cmd = f"foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff {filename} --exporter.read_write"
+                        else:
+                            cmd = f"foo@bar:~$ rougail -v 1.1 -m firefox -n Firefox -e FoxyProxy -d 1 foxyproxy -u file -ff {filename} --exporter.read_write"
                         doc += f"```console\n{cmd}\n```\n"
-                        conv_data = '<pre>' + conv.convert(capture.get(), full=False) + "</pre>\n"
-                        doc += '<pre>' + conv_data + "</pre>\n"
-                        with open(dirname / 'output_rw.html', 'w') as fh_output:
-                            fh_output.write(conv_data)
+                        doc += '<pre>' + conv.convert(capture.get(), full=False) + "</pre>\n"
     #
-    summary = Path('summary_after.md')
-    if summary.is_file():
-        with summary.open('r') as sfh:
-            doc += '\n\n' + sfh.read()
-    #
-    doc_file = Path('README.md')
     with doc_file.open('w') as docfh:
         docfh.write(doc)
     with doc_file.open('w') as docfh:

build.sh

@@ -1,8 +1,4 @@
 #!/bin/bash -e
-
-#-----------------------
-VERSION=1.1
-#-----------------------
 set -x
 DEST=../rougail-tutorials
 
@@ -17,8 +13,6 @@ BUILDER="$(pwd)"
 mkdir -p $DEST/firefox
 rm -f summary.md
 touch summary.md
-rm -f summary_total.md
-touch summary_total.md
 cd "$DEST"
 DEST="$(pwd)"
 
@@ -27,40 +21,20 @@ cp "$BUILDER"/firefox.png .
 cp "$BUILDER"/foxyproxy.png .
 cp "$BUILDER"/summary.md .
 touch README.md
-"$BUILDER"/build.py "$VERSION"
+"$BUILDER"/build.py
 rm -rf summary.md
-rm -rf summary_total.md
 rm -rf jinja_caches
-git init -b "$VERSION"
+git init -b 1.1
 git add .
 git commit -am"$(cat $BUILDER/TITLE)"
-#old_commit_id="$(git rev-parse HEAD)"
 cd - > /dev/null
 
 for i in $(ls -d "examples"/* | sort); do
-        num=$(echo $(basename "$i"))
-        echo "$num"
-        commit_id="v$VERSION_$num"
-        summary="[tutorial $(basename $i)] $(head -n 1 $i/README.md)"
-        echo "- [$summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/$commit_id/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/${commit_id}~1..$commit_id))" >> summary_total.md
-done
-
-for i in $(ls -d "examples"/* | sort); do
-    if [ -f "$i/TITLE.md" ]; then
-        echo "- $(head -n 1 $i/TITLE.md)" >> summary.md
-    fi
-    if [ -f "$i/SUBTITLE.md" ]; then
-        echo "  - $(head -n 1 $i/SUBTITLE.md)" >> summary.md
-    fi
     if [ -f "$i/README.md" ]; then
 	rm -rf "$DEST/config"
-        num=$(echo $(basename "$i"))
-        echo "$num"
-        commit_id="v$VERSION_$num"
-        summary="[tutorial $(basename $i)] $(head -n 1 $i/README.md)"
-        diff_url="https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/${commit_id}~1..$commit_id"
-        echo "    - [$summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/$commit_id/README.md) ([diff]($diff_url))" >> summary.md
-        cp "summary_total.md" "$DEST"
+        cp "summary.md" "$DEST"
+        echo $(basename "$i")
+        #
         cd "$i/dictionaries"
         if [ -d firefox ]; then
             for j in $(ls firefox/*.yml 2>/dev/null); do
@@ -78,52 +52,20 @@ for i in $(ls -d "examples"/* | sort); do
             cp -aL ../config "$DEST"
         fi
         msg="[tutorial $(basename $i)] $(cat ../README.md)"
+        summary="[tutorial $(basename $i)] $(head -n 1 ../README.md)"
         [ -e ../firefox.png ] && cp ../firefox.png "$DEST"
         [ -e ../foxyproxy.png ] && cp ../foxyproxy.png "$DEST"
         cd - > /dev/null
         cd "$DEST"
-        #
-        before=$(grep "commit/$commit_id/README.md" summary_total.md -B1 | wc -l)
-        echo "- [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/$VERSION/README.md)" > summary_before.md
-        if [ "$before" = "2" ]; then
-            echo $(grep "commit/$commit_id/README.md" summary_total.md -B1 | head -n 1) >> summary_before.md
-        fi
-        echo "" >> summary_before.md
-        echo "# $summary" >> summary_before.md
-        echo "" >> summary_before.md
-        echo "[View the diff]($diff_url)" >> summary_before.md
-        after=$(grep "commit/$commit_id/README.md" summary_total.md -A1 | wc -l)
-        if [ "$after" = "2" ]; then
-            echo $(grep "commit/$commit_id/README.md" summary_total.md -A1 | tail -n 1) > summary_after.md
-        fi
-        #
-        if [ -f config/mode ]; then
-            mv config/mode mode
-        fi
-        "$BUILDER"/build.py "$VERSION"
-        rm -rf config/*/README.md config/read_write config/namespace
-        rm -rf jinja_caches summary.md summary_before.md summary_after.md summary_total.md
-        if [ -f mode ]; then
-            MODE=1
-            rm -f mode
-        else
-            MODE=0
-        fi
-        git add *.png README.md
-        if [ -d config ]; then
-            git add config
-        else
-            git status |grep -q config && git add config
-        fi
-        git commit -m"$summary (config and doc)"
+        echo "- $summary" >> summary.md
+        "$BUILDER"/build.py
+	rm -rf config/*/README.md config/*/read_write
+        rm -rf jinja_caches summary.md
         git add .
         git commit -am"$msg"
-        git tag -a "$commit_id" -m"format version $VERSION: $num"
-        if [ "$MODE" = 1 ]; then
-            touch mode
-        fi
+        commit_id="$(git rev-parse HEAD)"
         cd - > /dev/null
-#        old_commit_id="$commit_id"
+        echo "- [$summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/$commit_id/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/commit/$commit_id))" >> summary.md
     fi
 done
 cd "$DEST"
@@ -143,30 +85,18 @@ This is what the page looks like:
 
 ![Foxyproxy Proxy setting](foxyproxy.png)
 " > README.md
-echo '# Installation
-
-```bash
-# python -m venv rougail
-# . rougail/bin/activate
-# pip install rougail-cli rougail-output-exporter rougail-output-doc rougail-user-data-file
-```
-' >> README.md
 echo "# Summary
 
 Each step is a separerate commit. You can navigate to history to discover different aspect to the Rougail format.
 " >> README.md
-cp "$BUILDER"/firefox.png .
-cp "$BUILDER"/foxyproxy.png .
 cat "$BUILDER"/summary.md >> README.md
 echo >> README.md
-rm -rf firefox foxyproxy mode
 git add .
+rm -rf firefox foxyproxy
 git commit -am"Summary"
 #
 git remote add origin ssh://git@forge.cloud.silique.fr:2222/stove/rougail-tutorials.git
-git push --set-upstream origin $VERSION --force
-git push --tag --force
+git push --set-upstream origin 1.1 --force
 
-rm -f summary.md summary_total.md
 echo "FAIT"
 exit 0

examples/000/README.md

@@ -1 +0,0 @@
-A structured file with format version

examples/000/SUBTITLE.md

@@ -1 +0,0 @@
-Structural file

examples/000/TITLE.md

@@ -1 +0,0 @@
-Getting started

examples/000/dictionaries/firefox/00-proxy.yml

@@ -1,2 +0,0 @@
----
-version: 1.1

examples/001/README.md

@@ -1 +1,10 @@
-The format version in commandline
+A first variable
+
+In the Firefox configuration, it is possible to define several configuration modes,
+from no proxy at all ("No proxy") to a kind of automatic configuration mode from a file 
+("Automatic proxy configuration URL").
+
+We’re gonna create a first variable called "proxy_mode":
+
+- accepts only a string as value
+- requires a value (that is, None is not an option)

examples/001/dictionaries/firefox/00-proxy.yml

@@ -1 +1,2 @@
 ---
+proxy_mode:

examples/002/README.md

@@ -0,0 +1,9 @@
+The variable description
+
+We can add a description to this first variable.
+
+This information is useful for:
+
+- documentation
+- error message
+- help user to known which value to set to this variable (for example with [the user data plugin Questionary](https://forge.cloud.silique.fr/gnunux/rougail-user-data-questionary)).

examples/002/config

@@ -0,0 +1 @@
+../001/config

examples/002/dictionaries/firefox/00-proxy.yml

@@ -1,5 +1,3 @@
-%YAML 1.2
 ---
 proxy_mode:
   description: Configure Proxy Access to the Internet
-...

examples/003/README.md

@@ -0,0 +1,7 @@
+A default value
+
+Now we can define the default value of this variable.
+
+If the user doesn't touch this variable's value, the value is "No proxy"
+
+As user intervention is no more required, so the variable change it's default mode too (from "basic" to "standard").

examples/003/config

@@ -0,0 +1 @@
+../001/config

examples/003/dictionaries/firefox/00-proxy.yml

@@ -1,6 +1,4 @@
-%YAML 1.2
 ---
 proxy_mode:
   description: Configure Proxy Access to the Internet
   default: No proxy
-...

examples/004/README.md

@@ -0,0 +1,7 @@
+A variable with type choice
+
+"Foo" should not be an option to the "proxy_mode" variable.
+
+Now the "proxy_mode" type is "choice", that means that there is a list of available values that can be selected.
+
+We say that the "proxy_mode" variable is constrained (by choices): this variable accept, in fact, only a list of choices.

examples/004/config

@@ -0,0 +1 @@
+../001/config

examples/004/dictionaries/firefox/00-proxy.yml

@@ -1,4 +1,3 @@
-%YAML 1.2
 ---
 proxy_mode:
   description: Configure Proxy Access to the Internet
@@ -10,4 +9,3 @@ proxy_mode:
     - Manual proxy configuration
     - Automatic proxy configuration URL
   default: No proxy
-...

examples/005/README.md

@@ -0,0 +1,3 @@
+Choice type is optional
+
+The type is optional in choice type (if we have choices attributes, it's a choice option).

examples/005/config

@@ -0,0 +1 @@
+../001/config

examples/005/dictionaries/firefox/00-proxy.yml

@@ -1,4 +1,3 @@
-%YAML 1.2
 ---
 proxy_mode:
   description: Configure Proxy Access to the Internet
@@ -9,4 +8,3 @@ proxy_mode:
     - Manual proxy configuration
     - Automatic proxy configuration URL
   default: No proxy
-...

examples/010/README.md

@@ -1 +1,14 @@
-A first variable with only a name
+A family
+
+The "manual" mode structural descriptions are write in a new files to separate things. But Rougail will concatenate variables and families.
+
+We create a family, which will contain other variables.
+
+This family has:
+
+- a description
+- a type
+
+As there is no variable inside this family, the type is mandatory. Without it, Rougail will create a variable.
+
+In fact, this family will be deleted by Rougail too because it is empty.

examples/010/SUBTITLE.md

@@ -1 +0,0 @@
-Variable: choice the proxy mode

examples/010/dictionaries/firefox/00-proxy.yml

@@ -1,4 +0,0 @@
-%YAML 1.2
----
-proxy_mode:
-...

examples/010/dictionaries/firefox/10-manual.yml

@@ -1,6 +1,4 @@
-%YAML 1.2
 ---
 manual:
   description: Manual proxy configuration
   type: family
-...

examples/011/README.md

@@ -1,9 +1,5 @@
-The variable description
+Conditional desactived family
 
-We can add a description to this first variable.
+This family will be desactived if "proxy_mode" is not "manual proxy configuration".
 
-This information is useful for:
-
-- documentation
-- error message
-- help user to known which value to set to this variable (for example with [the user data plugin Questionary](https://forge.cloud.silique.fr/gnunux/rougail-user-data-questionary)).
+Desactived a variable or a family means that this variable will never be accessible.

examples/011/config

@@ -1 +0,0 @@
-../010/config

examples/011/dictionaries/firefox/10-manual.yml

@@ -0,0 +1,8 @@
+---
+manual:
+  description: Manual proxy configuration
+  type: family
+  disabled:
+    type: variable
+    variable: proxy_mode
+    when_not: 'Manual proxy configuration'

examples/012/README.md

@@ -1,7 +1,7 @@
-A default value
+A sub family
 
-Now we can define the default value of this variable.
+Inside a family, we can have variables or families.
 
-If the user doesn't touch this variable's value, the value is "No proxy"
+The "type" for family "manual" became unecessary because container an other family, so it's not a variable.
 
-As user intervention is no more required, so the variable change it's default mode too (from "basic" to "standard").
+In disabled attribute, it's better tu use relative path (we will see the reason in an other slide).

examples/012/config

@@ -1 +0,0 @@
-../010/config

examples/012/dictionaries/firefox/10-manual.yml

@@ -1,10 +1,11 @@
-%YAML 1.2
 ---
 manual:
   description: Manual proxy configuration
-  type: family
+  disabled:
+    type: variable
+    variable: _.proxy_mode
+    when_not: 'Manual proxy configuration'
 
   http_proxy:
     description: HTTP Proxy
     type: family
-...

examples/013/README.md

@@ -1,7 +1,5 @@
-A variable with type "choice"
+Family in "shorthand" mode
 
-"Foo" should not be an option to the "proxy_mode" variable.
+The sub family is now in "shorthand" mode. In this mode we can only define "name" and "description" attributes.
 
-Now the "proxy_mode" type is "choice", that means that there is a list of available values that can be selected.
-
-We say that the "proxy_mode" variable is constrained (by choices): this variable accept, in fact, only a list of choices.
+Inside the sub family we add two variables (with domainname and port types).

examples/013/config

@@ -1 +0,0 @@
-../010/config

examples/013/dictionaries/firefox/10-manual.yml

@@ -1,10 +1,10 @@
-%YAML 1.2
 ---
 manual:
   description: Manual proxy configuration
   disabled:
+    type: variable
     variable: _.proxy_mode
-    when_not: Manual proxy configuration
+    when_not: 'Manual proxy configuration'
 
   http_proxy:  # HTTP Proxy
 
@@ -18,4 +18,3 @@ manual:
       description: HTTP Port
       type: port
       default: 8080
-...

examples/014/README.md

@@ -1,3 +1,3 @@
-Choice type is optional
+A boolean variable
 
-The type is optional in choice type (if we have choices attributes, it's a choice option).
+Let's create a boolean variable.

examples/014/config

@@ -1 +0,0 @@
-../010/config

examples/014/dictionaries/firefox/10-manual.yml

@@ -1,10 +1,10 @@
-%YAML 1.2
 ---
 manual:
   description: Manual proxy configuration
   disabled:
-    variable: proxy_mode
-    when_not: Manual proxy configuration
+    type: variable
+    variable: _.proxy_mode
+    when_not: 'Manual proxy configuration'
 
   http_proxy:  # HTTP Proxy
 
@@ -18,4 +18,8 @@ manual:
       description: HTTP Port
       type: port
       default: 8080
-...
+
+  use_for_https:
+    description: Also use this proxy for HTTPS
+    type: boolean
+    default: true

examples/015/README.md

@@ -0,0 +1,3 @@
+Bases type is optional if default value
+
+The type is deduct with the default value type. This is only true for "string", "number", "float" or "boolean" variables.

examples/015/config

@@ -0,0 +1 @@
+../014/config

examples/015/dictionaries/firefox/10-manual.yml

@@ -1,13 +1,12 @@
-%YAML 1.2
 ---
 manual:
   description: Manual proxy configuration
   disabled:
-    variable: proxy_mode
+    type: variable
+    variable: _.proxy_mode
     when_not: 'Manual proxy configuration'
 
-  http_proxy:
-    description: HTTP Proxy
+  http_proxy:  # HTTP Proxy
 
     address:
       description: HTTP address
@@ -19,4 +18,7 @@ manual:
       description: HTTP Port
       type: port
       default: 8080
-...
+
+  use_for_https:
+    description: Also use this proxy for HTTPS
+    default: true

examples/016/README.md

@@ -0,0 +1,9 @@
+A variable in "shorthand" mode
+
+Transform it in "shorthand" mode.
+
+In this notation we can only define:
+
+- name
+- default value (so deduct the type)
+- description

examples/016/config

@@ -0,0 +1 @@
+../014/config

examples/016/dictionaries/firefox/10-manual.yml

@@ -1,14 +1,12 @@
-%YAML 1.2
 ---
 manual:
   description: Manual proxy configuration
   disabled:
     type: variable
-    variable: proxy_mode
+    variable: _.proxy_mode
     when_not: 'Manual proxy configuration'
 
-  http_proxy:
-    description: HTTP Proxy
+  http_proxy:  # HTTP Proxy
 
     address:
       description: HTTP address
@@ -20,4 +18,5 @@ manual:
       description: HTTP Port
       type: port
       default: 8080
-...
+
+  use_for_https: true  # Also use this proxy for HTTPS

examples/017/README.md

@@ -0,0 +1,9 @@
+Conditional hidden family and calculated default value
+
+Add a sub family "https_proxy" which will be hidden if "use_for_https" is True.
+
+Hidden means that we cannot change value, but we can access to it in read only mode. Inside, we add two variable with calculated default value (with variable type).
+
+So, if user set "use_for_https" to True, the default values of HTTPS configuration will be a copy of HTTP values. The use can change HTTPS values if needed.
+
+If user set "use_for_https" to False, the default values of HTTPS configuration will only be a copy of HTTP values.

examples/017/config/01/README.md

@@ -0,0 +1 @@
+If "use_for_https" is true, HTTPS variables are visible in read only mode, but not in read write mode.

examples/017/dictionaries/firefox/10-manual.yml

@@ -0,0 +1,44 @@
+---
+manual:
+  description: Manual proxy configuration
+  disabled:
+    type: variable
+    variable: _.proxy_mode
+    when_not: 'Manual proxy configuration'
+
+  http_proxy:  # HTTP Proxy
+
+    address:
+      description: HTTP address
+      type: domainname
+      params:
+        allow_ip: true
+
+    port:
+      description: HTTP Port
+      type: port
+      default: 8080
+
+  use_for_https: true  # Also use this proxy for HTTPS
+
+  https_proxy:
+    description: HTTPS Proxy
+    hidden:
+      type: variable
+      variable: _.use_for_https
+
+    address:
+      description: HTTPS address
+      type: domainname
+      params:
+        allow_ip: true
+      default:
+        type: variable
+        variable: __.http_proxy.address
+
+    port:
+      description: HTTPS Port
+      type: port
+      default:
+        type: variable
+        variable: __.http_proxy.port

examples/018/README.md

@@ -0,0 +1,15 @@
+A dynamic family
+
+HTTPS and socks proxy are very similar. It could be interesting to do on dynamic family instead of duplicate family and variable description.
+
+First of all, we add a dynamic attribute to the family. Dynamic is here a static list of suffix. It could be a variable or jinja informations too.
+
+The dynamic family is only hidden in the HTTPs case.
+Hidden is now a Jinja calculation with a parameter named "suffix".
+
+The suffix is use in:
+
+- family name
+- family description
+- variables name
+- variables description

examples/018/dictionaries/firefox/10-manual.yml

@@ -0,0 +1,54 @@
+---
+manual:
+  description: Manual proxy configuration
+  disabled:
+    type: variable
+    variable: _.proxy_mode
+    when_not: 'Manual proxy configuration'
+
+  http_proxy:  # HTTP Proxy
+
+    address:
+      description: HTTP address
+      type: domainname
+      params:
+        allow_ip: true
+
+    port:
+      description: HTTP Port
+      type: port
+      default: 8080
+
+  use_for_https: true  # Also use this proxy for HTTPS
+
+  "{{ suffix }}_proxy":
+    description: "{{ suffix }} Proxy"
+    type: dynamic
+    dynamic:
+      - HTTPS
+      - SOCKS
+    hidden:
+      type: jinja
+      jinja: |
+        {% if suffix == 'HTTPS' and _.use_for_https %}
+        HTTPS is same has HTTP
+        {% endif %}
+      params:
+        suffix:
+          type: suffix
+
+    address:
+      description: "{{ suffix }} address"
+      type: domainname
+      params:
+        allow_ip: true
+      default:
+        type: variable
+        variable: __.http_proxy.address
+
+    port:
+      description: "{{ suffix }} port"
+      type: port
+      default:
+        type: variable
+        variable: __.http_proxy.port

examples/019/README.md

@@ -0,0 +1,5 @@
+Description of Jinja calculation
+
+By default, the Jinja calculation is generic in documentation. We can add a useful description.
+
+We add a new variable "version" only accessible in "Socks" family.

examples/019/dictionaries/firefox/10-manual.yml

@@ -0,0 +1,70 @@
+---
+manual:
+  description: Manual proxy configuration
+  disabled:
+    type: variable
+    variable: _.proxy_mode
+    when_not: 'Manual proxy configuration'
+
+  http_proxy:  # HTTP Proxy
+
+    address:
+      description: HTTP address
+      type: domainname
+      params:
+        allow_ip: true
+
+    port:
+      description: HTTP Port
+      type: port
+      default: 8080
+
+  use_for_https: true  # Also use this proxy for HTTPS
+
+  "{{ suffix }}_proxy":
+    description: "{{ suffix }} Proxy"
+    type: dynamic
+    dynamic:
+      - HTTPS
+      - SOCKS
+    hidden:
+      type: jinja
+      jinja: |
+        {% if suffix == 'HTTPS' and _.use_for_https %}
+        HTTPS is same has HTTP
+        {% endif %}
+      params:
+        suffix:
+          type: suffix
+      description: |
+        if "use_for_https" is set to True
+
+    address:
+      description: "{{ suffix }} address"
+      default:
+        type: variable
+        variable: __.http_proxy.address
+
+    port:
+      description: "{{ suffix }} port"
+      default:
+        type: variable
+        variable: __.http_proxy.port
+
+    version:
+      description: SOCKS host version used by proxy
+      choices:
+        - v4
+        - v5
+      default: v5
+      disabled:
+        type: jinja
+        jinja: |
+          {% if suffix == 'HTTPS' %}
+          if HTTPS
+          {% endif %}
+        params:
+          suffix:
+            type: suffix
+        description: |
+          if not SOCKS

examples/020/README.md

@@ -1,14 +1,3 @@
-A family
+A conditional disabled variable
 
-The "manual" mode structural descriptions are write in a new files to separate things. But Rougail will concatenate variables and families.
-
-We create a family, which will contain other variables.
-
-This family has:
-
-- a description
-- a type
-
-As there is no variable inside this family, the type is mandatory. Without it, Rougail will create a variable.
-
-In fact, this family will be deleted by Rougail too because it is empty.
+Add a new "auto" variable.

examples/020/SUBTITLE.md

@@ -1 +0,0 @@
-Family: proxy manual

examples/020/dictionaries/firefox/20-auto.yml

@@ -1,9 +1,8 @@
-%YAML 1.2
 ---
 auto:
   description: Automatic proxy configuration URL
   type: web_address
   disabled:
+    type: variable
     variable: _.proxy_mode
-    when_not: Automatic proxy configuration URL
-...
+    when: Automatic proxy configuration URL

examples/021/README.md

@@ -1,7 +0,0 @@
-A sub family
-
-Inside a family, we can have variables or families.
-
-The "type" for family "manual" became unecessary because container an other family, so it's not a variable.
-
-In disabled attribute, it's better tu use relative path (we will see the reason in an other slide).

examples/022/README.md

@@ -1 +0,0 @@
-A variable inside sub family

examples/022/dictionaries/firefox/10-manual.yml

@@ -1,13 +0,0 @@
-%YAML 1.2
----
-manual:
-  description: Manual proxy configuration
-  type: family
-
-  http_proxy:
-    description: HTTP Proxy
-    type: family
-
-    address:
-      description: HTTP address
-...

examples/023/README.md

@@ -1 +0,0 @@
-Family type is optional

examples/023/config

@@ -1 +0,0 @@
-../010/config

examples/023/dictionaries/firefox/10-manual.yml

@@ -1,11 +0,0 @@
-%YAML 1.2
----
-manual:
-  description: Manual proxy configuration
-
-  http_proxy:
-    description: HTTP Proxy
-
-    address:
-      description: HTTP address
-...

examples/024/README.md

@@ -1 +0,0 @@
-A variable with type "domainname"

examples/024/SUBTITLE.md

@@ -1 +0,0 @@
-Variable: type and type parameters

examples/024/TITLE.md

@@ -1 +0,0 @@
-HTTP Manual mode

examples/024/config/02/config.yaml

@@ -1,2 +0,0 @@
----
-proxy_mode: Manual proxy configuration

examples/024/config/03/config.yaml

@@ -1,5 +0,0 @@
----
-proxy_mode: Manual proxy configuration
-manual:
-  http_proxy:
-    address: example.net

examples/024/config/04/config.yaml

@@ -1,6 +0,0 @@
----
-proxy_mode: Manual proxy configuration
-manual:
-  http_proxy:
-    address: example.net
-    port: '3128'

examples/024/config/05/README.md

@@ -1,2 +0,0 @@
-If "use_for_https" is false, HTTPS variables are visible in read only mode and in read write mode.
-

examples/024/config/05/config.yaml

@@ -1,9 +0,0 @@
----
-proxy_mode: Manual proxy configuration
-manual:
-  http_proxy:
-    address: http.proxy.net
-    port: '3128'
-  use_for_https: false
-  https_proxy:
-    address: https.proxy.net

examples/024/dictionaries/firefox/10-manual.yml

@@ -1,12 +0,0 @@
-%YAML 1.2
----
-manual:
-  description: Manual proxy configuration
-
-  http_proxy:
-    description: HTTP Proxy
-
-    address:
-      description: HTTP address
-      type: domainname
-...

examples/025/README.md

@@ -1 +0,0 @@
-A variable with type's parameters

examples/025/config

@@ -1 +0,0 @@
-../022/config

examples/025/dictionaries/firefox/10-manual.yml

@@ -1,14 +0,0 @@
-%YAML 1.2
----
-manual:
-  description: Manual proxy configuration
-
-  http_proxy:
-    description: HTTP Proxy
-
-    address:
-      description: HTTP address
-      type: domainname
-      params:
-        allow_ip: true
-...

examples/026/README.md

@@ -1 +0,0 @@
-A variable with type "port"

examples/026/config

@@ -1 +0,0 @@
-../022/config

examples/026/dictionaries/firefox/10-manual.yml

@@ -1,19 +0,0 @@
-%YAML 1.2
----
-manual:
-  description: Manual proxy configuration
-
-  http_proxy:
-    description: HTTP Proxy
-
-    address:
-      description: HTTP address
-      type: domainname
-      params:
-        allow_ip: true
-
-    port:
-      description: HTTP Port
-      type: port
-      default: 8080
-...