diff --git a/docs/tutorial/customtype.rst b/docs/tutorial/customtype.rst index bd30f3394..2e2dbaba0 100644 --- a/docs/tutorial/customtype.rst +++ b/docs/tutorial/customtype.rst @@ -16,7 +16,7 @@ Custom type Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, - this workshop page corresponds to the tags :tutorial:`v1.1_080 ` to :tutorial:`v1.1_083 ` + this workshop page corresponds to the tags :tutorial:`v1.1_080 ` to :tutorial:`v1.1_085 ` in the repository. :: @@ -175,7 +175,9 @@ With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a Now we have two families with the `proxy` type: `https_proxy` and `socks_proxy`. -FIXME expliqué qu'on n'a pas encore tout ce qu'on avait avant ! +But we haven't recovered everything we had before. +Using a type definition is fine, but we still need to find exactly the configuration situation +we had before using the type definition. Add a variable in a family with custom type -------------------------------------------- @@ -383,14 +385,13 @@ Redefine other parameter in custom type for HTTP In this sections we are going to make explicit :term:`redefinitions `. -The type definition didn't change, what we're talking about here is modifiying what has been previously defined -in the type definition file: -FIXME : en fait si ! on supprime la description, de address et port qui n'a pas de sens dans le type (suivant le type il faut le redéfinir). -et on modifie ici le type pour HTTP. +Note here that, in order to allow for the genericity of a type declaration, +we have omitted to specify the variable descriptions in the type declaration. +We will therefore need to enter these descriptions in the structure file. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_084/types/proxy/00-type.yml :language: yaml - :caption: The :file:`types/proxy/00-type.yml` type definition file with the default definitions + :caption: The :file:`types/proxy/00-type.yml` type definition file with the default definitions and no description .. %YAML 1.2 @@ -412,9 +413,9 @@ et on modifie ici le type pour HTTP. variable: __.http_proxy.port ... -We can see here, for example, that the `address` and `port` variables don't have -any `description` attribute. We need to add one, so we need to extend the type -definitions. +So, as the `address` and `port` variables don't have any `description` attribute, +we need to add one. It is something like an extension of the type definitions here +in the structure file: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_084/firefox/10-manual.yml :language: yaml @@ -488,6 +489,69 @@ We can see in the output that the `address` and `port` variables have default va and descriptions ("HTTP proxy address", "HTTP proxy port") that weren't present in the type definition file. +Redefine other parameter in custom type for HTTPS and SOCKS +----------------------------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_085` version:: + + git switch --detach v1.1_085 + +We're going to do exactly the same modification with the `socks_proxy` family, +that is we will base the `socks_proxy` family on the type definition. + +Following the same reasoning, we add a in the structure file some `description` attributes to the `socks_proxy` family +and also add some explicit redefinition attribute (`redefine: true`). + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_085/firefox/20-manual.yml + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with the `redefine` and the `description` attribute + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + https_proxy: + description: HTTPS Proxy + type: proxy + hidden: + variable: _.use_for_https + + address: + redefine: true + description: HTTPS proxy address + + port: + redefine: true + description: HTTPS proxy port + + socks_proxy: + description: SOCKS Proxy + type: proxy + + address: + redefine: true + description: SOCKS proxy address + + port: + redefine: true + description: SOCKS proxy port + + version: + description: SOCKS host version used by proxy + choices: + - v4 + - v5 + default: v5 + ... + + .. keypoints:: Key points - the very practical aspects of type declaration @@ -499,14 +563,3 @@ type definition file. We have seen how the definition of type, used effectively, allows for a new expressiveness. - -Redefine other parameter in custom type for HTTPS and SOCKS ------------------------------------------------------------ - -.. type-along:: For those who follow the tutorial with the help of the git repository - - Now you need to checkout the `v1.1_084` version:: - - git switch --detach v1.1_084 - -FIXME pareil pour https et socks