From 591105e8383cfdc5c47cc82fc2eed9551bd83eb5 Mon Sep 17 00:00:00 2001 From: Ryan Mulligan Date: Thu, 3 Jun 2021 20:26:57 -0700 Subject: [PATCH] nixos/doc: convert abstractions section to CommonMark --- .../configuration/abstractions.section.md | 80 ++++++++++++++ .../doc/manual/configuration/abstractions.xml | 101 ------------------ .../manual/configuration/config-syntax.xml | 2 +- .../configuration/abstractions.section.xml | 101 ++++++++++++++++++ 4 files changed, 182 insertions(+), 102 deletions(-) create mode 100644 nixos/doc/manual/configuration/abstractions.section.md delete mode 100644 nixos/doc/manual/configuration/abstractions.xml create mode 100644 nixos/doc/manual/from_md/configuration/abstractions.section.xml diff --git a/nixos/doc/manual/configuration/abstractions.section.md b/nixos/doc/manual/configuration/abstractions.section.md new file mode 100644 index 00000000000..bf26e4c51ed --- /dev/null +++ b/nixos/doc/manual/configuration/abstractions.section.md @@ -0,0 +1,80 @@ +# Abstractions {#sec-module-abstractions} + +If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration: + +```nix +{ + services.httpd.virtualHosts = + { "blog.example.org" = { + documentRoot = "/webroot/blog.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + "wiki.example.org" = { + documentRoot = "/webroot/wiki.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + }; +} +``` + +It defines two virtual hosts with nearly identical configuration; the only difference is the document root directories. To prevent this duplication, we can use a `let`: +```nix +let + commonConfig = + { adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; +in +{ + services.httpd.virtualHosts = + { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; }); + "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; }); + }; +} +``` + +The `let commonConfig = ...` defines a variable named `commonConfig`. The `//` operator merges two attribute sets, so the configuration of the second virtual host is the set `commonConfig` extended with the document root option. + +You can write a `let` wherever an expression is allowed. Thus, you also could have written: + +```nix +{ + services.httpd.virtualHosts = + let commonConfig = ...; in + { "blog.example.org" = (commonConfig // { ... }) + "wiki.example.org" = (commonConfig // { ... }) + }; +} +``` + +but not `{ let commonConfig = ...; in ...; }` since attributes (as opposed to attribute values) are not expressions. + +**Functions** provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the document root. This can be done as follows: + +```nix +{ + services.httpd.virtualHosts = + let + makeVirtualHost = webroot: + { documentRoot = webroot; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; + in + { "example.org" = (makeVirtualHost "/webroot/example.org"); + "example.com" = (makeVirtualHost "/webroot/example.com"); + "example.gov" = (makeVirtualHost "/webroot/example.gov"); + "example.nl" = (makeVirtualHost "/webroot/example.nl"); + }; +} +``` + +Here, `makeVirtualHost` is a function that takes a single argument `webroot` and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations. diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml deleted file mode 100644 index df9ff2615e1..00000000000 --- a/nixos/doc/manual/configuration/abstractions.xml +++ /dev/null @@ -1,101 +0,0 @@ -
- Abstractions - - - If you find yourself repeating yourself over and over, it’s time to - abstract. Take, for instance, this Apache HTTP Server configuration: - -{ - = - { "blog.example.org" = { - documentRoot = "/webroot/blog.example.org"; - adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - enablePHP = true; - }; - "wiki.example.org" = { - documentRoot = "/webroot/wiki.example.org"; - adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - enablePHP = true; - }; - }; -} - - It defines two virtual hosts with nearly identical configuration; the only - difference is the document root directories. To prevent this - duplication, we can use a let: - -let - commonConfig = - { adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - }; -in -{ - = - { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; }); - "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; }); - }; -} - - The let commonConfig = ... - defines a variable named commonConfig. The - // operator merges two attribute sets, so the - configuration of the second virtual host is the set - commonConfig extended with the document root option. - - - - You can write a let wherever an expression is allowed. - Thus, you also could have written: - -{ - = - let commonConfig = ...; in - { "blog.example.org" = (commonConfig // { ... }) - "wiki.example.org" = (commonConfig // { ... }) - }; -} - - but not { let commonConfig = ...; in - ...; } since attributes (as opposed to - attribute values) are not expressions. - - - - Functions provide another method of abstraction. For - instance, suppose that we want to generate lots of different virtual hosts, - all with identical configuration except for the document root. This can be done - as follows: - -{ - = - let - makeVirtualHost = webroot: - { documentRoot = webroot; - adminAddr = "alice@example.org"; - forceSSL = true; - enableACME = true; - }; - in - { "example.org" = (makeVirtualHost "/webroot/example.org"); - "example.com" = (makeVirtualHost "/webroot/example.com"); - "example.gov" = (makeVirtualHost "/webroot/example.gov"); - "example.nl" = (makeVirtualHost "/webroot/example.nl"); - }; -} - - Here, makeVirtualHost is a function that takes a single - argument webroot and returns the configuration for a virtual - host. That function is then called for several names to produce the list of - virtual host configurations. - -
diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml index 5526dea247c..a374c6a8707 100644 --- a/nixos/doc/manual/configuration/config-syntax.xml +++ b/nixos/doc/manual/configuration/config-syntax.xml @@ -19,7 +19,7 @@ xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix constructs useful in NixOS configuration files. - + diff --git a/nixos/doc/manual/from_md/configuration/abstractions.section.xml b/nixos/doc/manual/from_md/configuration/abstractions.section.xml new file mode 100644 index 00000000000..c71e23e34ad --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/abstractions.section.xml @@ -0,0 +1,101 @@ +
+ Abstractions + + If you find yourself repeating yourself over and over, it’s time to + abstract. Take, for instance, this Apache HTTP Server configuration: + + +{ + services.httpd.virtualHosts = + { "blog.example.org" = { + documentRoot = "/webroot/blog.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + "wiki.example.org" = { + documentRoot = "/webroot/wiki.example.org"; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + enablePHP = true; + }; + }; +} + + + It defines two virtual hosts with nearly identical configuration; + the only difference is the document root directories. To prevent + this duplication, we can use a let: + + +let + commonConfig = + { adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; +in +{ + services.httpd.virtualHosts = + { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; }); + "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; }); + }; +} + + + The let commonConfig = ... defines a variable + named commonConfig. The // + operator merges two attribute sets, so the configuration of the + second virtual host is the set commonConfig + extended with the document root option. + + + You can write a let wherever an expression is + allowed. Thus, you also could have written: + + +{ + services.httpd.virtualHosts = + let commonConfig = ...; in + { "blog.example.org" = (commonConfig // { ... }) + "wiki.example.org" = (commonConfig // { ... }) + }; +} + + + but not { let commonConfig = ...; in ...; } since + attributes (as opposed to attribute values) are not expressions. + + + Functions provide another method + of abstraction. For instance, suppose that we want to generate lots + of different virtual hosts, all with identical configuration except + for the document root. This can be done as follows: + + +{ + services.httpd.virtualHosts = + let + makeVirtualHost = webroot: + { documentRoot = webroot; + adminAddr = "alice@example.org"; + forceSSL = true; + enableACME = true; + }; + in + { "example.org" = (makeVirtualHost "/webroot/example.org"); + "example.com" = (makeVirtualHost "/webroot/example.com"); + "example.gov" = (makeVirtualHost "/webroot/example.gov"); + "example.nl" = (makeVirtualHost "/webroot/example.nl"); + }; +} + + + Here, makeVirtualHost is a function that takes a + single argument webroot and returns the + configuration for a virtual host. That function is then called for + several names to produce the list of virtual host configurations. + +