···

       
1
       
1
       
-
       
#!/usr/bin/env nix-shell

     

       
2
       
2
       
-
       
#! nix-shell -i bash -p html-tidy

     

       
3
       
3
       
-
       


     

       
4
       
4
       
-
       
set -euo pipefail

     

       
5
       
5
       
-
       
shopt -s inherit_errexit

     

       
6
       
6
       
-
       


     

       
7
       
7
       
-
       
normalize() {

     

       
8
       
8
       
-
       
  tidy \

     

       
9
       
9
       
-
       
      --anchor-as-name no \

     

       
10
       
10
       
-
       
      --coerce-endtags no \

     

       
11
       
11
       
-
       
      --escape-scripts no \

     

       
12
       
12
       
-
       
      --fix-backslash no \

     

       
13
       
13
       
-
       
      --fix-style-tags no \

     

       
14
       
14
       
-
       
      --fix-uri no \

     

       
15
       
15
       
-
       
      --indent yes \

     

       
16
       
16
       
-
       
      --wrap 0 \

     

       
17
       
17
       
-
       
      < "$1" \

     

       
18
       
18
       
-
       
      2> /dev/null

     

       
19
       
19
       
-
       
}

     

       
20
       
20
       
-
       


     

       
21
       
21
       
-
       
diff -U3 <(normalize "$1") <(normalize "$2")

     

···

       
27
       
27
       
 
       
          # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.

     

       
28
       
28
       
 
       
          name: nixpkgs-ci

     

       
29
       
29
       
 
       
          signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'

     

       
30
       
30
       
-
       
      - name: Building NixOS manual with DocBook options

     

       
30
       
30
       
+
       
      - name: Building NixOS manual

     

       
31
       
31
       
 
       
        run: NIX_PATH=nixpkgs=$(pwd) nix-build --option restrict-eval true nixos/release.nix -A manual.x86_64-linux

     

       
32
       
32
       
-
       
      - name: Building NixOS manual with Markdown options

     

       
33
       
33
       
-
       
        run: |

     

       
34
       
34
       
-
       
          export NIX_PATH=nixpkgs=$(pwd)

     

       
35
       
35
       
-
       
          nix-build \

     

       
36
       
36
       
-
       
            --option restrict-eval true \

     

       
37
       
37
       
-
       
            --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \

     

       
38
       
38
       
-
       
            nixos/release.nix \

     

       
39
       
39
       
-
       
            -A manual.x86_64-linux

     

···

       
1
       
1
       
-
       
name: "Check NixOS Manual DocBook rendering against MD rendering"

     

       
2
       
2
       
-
       


     

       
3
       
3
       
-
       


     

       
4
       
4
       
-
       
on:

     

       
5
       
5
       
-
       
  schedule:

     

       
6
       
6
       
-
       
    # * is a special character in YAML so you have to quote this string

     

       
7
       
7
       
-
       
    # Check every 24 hours

     

       
8
       
8
       
-
       
    - cron:  '0 0 * * *'

     

       
9
       
9
       
-
       


     

       
10
       
10
       
-
       
permissions:

     

       
11
       
11
       
-
       
  contents: read

     

       
12
       
12
       
-
       


     

       
13
       
13
       
-
       
jobs:

     

       
14
       
14
       
-
       
  check-rendering-equivalence:

     

       
15
       
15
       
-
       
    permissions:

     

       
16
       
16
       
-
       
      pull-requests: write  # for peter-evans/create-or-update-comment to create or update comment

     

       
17
       
17
       
-
       
    if: github.repository_owner == 'NixOS'

     

       
18
       
18
       
-
       
    runs-on: ubuntu-latest

     

       
19
       
19
       
-
       
    steps:

     

       
20
       
20
       
-
       
      - uses: actions/checkout@v3

     

       
21
       
21
       
-
       
      - uses: cachix/install-nix-action@v21

     

       
22
       
22
       
-
       
        with:

     

       
23
       
23
       
-
       
          # explicitly enable sandbox

     

       
24
       
24
       
-
       
          extra_nix_config: sandbox = true

     

       
25
       
25
       
-
       
      - uses: cachix/cachix-action@v12

     

       
26
       
26
       
-
       
        with:

     

       
27
       
27
       
-
       
          # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.

     

       
28
       
28
       
-
       
          name: nixpkgs-ci

     

       
29
       
29
       
-
       
          signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'

     

       
30
       
30
       
-
       


     

       
31
       
31
       
-
       
      - name: Build DocBook and MD manuals

     

       
32
       
32
       
-
       
        run: |

     

       
33
       
33
       
-
       
          export NIX_PATH=nixpkgs=$(pwd)

     

       
34
       
34
       
-
       
          nix-build \

     

       
35
       
35
       
-
       
            --option restrict-eval true \

     

       
36
       
36
       
-
       
            -o docbook nixos/release.nix \

     

       
37
       
37
       
-
       
            -A manual.x86_64-linux

     

       
38
       
38
       
-
       
          nix-build \

     

       
39
       
39
       
-
       
            --option restrict-eval true \

     

       
40
       
40
       
-
       
            --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \

     

       
41
       
41
       
-
       
            -o md nixos/release.nix \

     

       
42
       
42
       
-
       
            -A manual.x86_64-linux

     

       
43
       
43
       
-
       


     

       
44
       
44
       
-
       
      - name: Compare DocBook and MD manuals

     

       
45
       
45
       
-
       
        id: check

     

       
46
       
46
       
-
       
        run: |

     

       
47
       
47
       
-
       
          export NIX_PATH=nixpkgs=$(pwd)

     

       
48
       
48
       
-
       
          .github/workflows/compare-manuals.sh \

     

       
49
       
49
       
-
       
            docbook/share/doc/nixos/options.html \

     

       
50
       
50
       
-
       
            md/share/doc/nixos/options.html

     

       
51
       
51
       
-
       


     

       
52
       
52
       
-
       
      # if the manual can't be built we don't want to notify anyone.

     

       
53
       
53
       
-
       
      # while this may temporarily hide rendering failures it will be a lot

     

       
54
       
54
       
-
       
      # less noisy until all nixpkgs pull requests have stopped using

     

       
55
       
55
       
-
       
      # docbook for option docs.

     

       
56
       
56
       
-
       
      - name: Comment on failure

     

       
57
       
57
       
-
       
        uses: peter-evans/create-or-update-comment@v3

     

       
58
       
58
       
-
       
        if: ${{ failure() && steps.check.conclusion == 'failure' }}

     

       
59
       
59
       
-
       
        with:

     

       
60
       
60
       
-
       
          issue-number: 189318

     

       
61
       
61
       
-
       
          body: |

     

       
62
       
62
       
-
       
            Markdown and DocBook manuals do not agree.

     

       
63
       
63
       
-
       


     

       
64
       
64
       
-
       
            Check https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }} for details.

     

···

       
138
       
138
       
 
       
      mergeDefaultOption mergeOneOption mergeEqualOption mergeUniqueOption

     

       
139
       
139
       
 
       
      getValues getFiles

     

       
140
       
140
       
 
       
      optionAttrSetToDocList optionAttrSetToDocList'

     

       
141
       
141
       
-
       
      scrubOptionValue literalExpression literalExample literalDocBook

     

       
141
       
141
       
+
       
      scrubOptionValue literalExpression literalExample

     

       
142
       
142
       
 
       
      showOption showOptionWithDefLocs showFiles

     

       
143
       
143
       
 
       
      unknownModule mkOption mkPackageOption mkPackageOptionMD

     

       
144
       
144
       
 
       
      mdDoc literalMD;

     

···

       
134
       
134
       
 
       
            ${if prefix == []

     

       
135
       
135
       
 
       
              then null  # unset => visible

     

       
136
       
136
       
 
       
              else "internal"} = true;

     

       
137
       
137
       
-
       
            # TODO: hidden during the markdown transition to not expose downstream

     

       
138
       
138
       
-
       
            # users of the docs infra to markdown if they're not ready for it.

     

       
139
       
139
       
-
       
            # we don't make this visible conditionally because it can impact

     

       
140
       
140
       
-
       
            # performance (https://github.com/NixOS/nixpkgs/pull/208407#issuecomment-1368246192)

     

       
141
       
141
       
-
       
            visible = false;

     

       
142
       
137
       
 
       
            # TODO: Change the type of this option to a submodule with a

     

       
143
       
138
       
 
       
            # freeformType, so that individual arguments can be documented

     

       
144
       
139
       
 
       
            # separately

     
···

       
1146
       
1141
       
 
       
    use = id;

     

       
1147
       
1142
       
 
       
  };

     

       
1148
       
1143
       
 
       


     

       
1149
       
1149
       
-
       
  /* Transitional version of mkAliasOptionModule that uses MD docs. */

     

       
1150
       
1150
       
-
       
  mkAliasOptionModuleMD = from: to: doRename {

     

       
1151
       
1151
       
-
       
    inherit from to;

     

       
1152
       
1152
       
-
       
    visible = true;

     

       
1153
       
1153
       
-
       
    warn = false;

     

       
1154
       
1154
       
-
       
    use = id;

     

       
1155
       
1155
       
-
       
    markdown = true;

     

       
1156
       
1156
       
-
       
  };

     

       
1144
       
1144
       
+
       
  /* Transitional version of mkAliasOptionModule that uses MD docs.

     

       
1145
       
1145
       
+
       


     

       
1146
       
1146
       
+
       
     This function is no longer necessary and merely an alias of `mkAliasOptionModule`.

     

       
1147
       
1147
       
+
       
  */

     

       
1148
       
1148
       
+
       
  mkAliasOptionModuleMD = mkAliasOptionModule;

     

       
1157
       
1149
       
 
       


     

       
1158
       
1150
       
 
       
  /* mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b

     

       
1159
       
1151
       
 
       


     
···

       
1175
       
1167
       
 
       
      (opt.highestPrio or defaultOverridePriority)

     

       
1176
       
1168
       
 
       
      (f opt.value);

     

       
1177
       
1169
       
 
       


     

       
1178
       
1178
       
-
       
  doRename = { from, to, visible, warn, use, withPriority ? true, markdown ? false }:

     

       
1170
       
1170
       
+
       
  doRename = { from, to, visible, warn, use, withPriority ? true }:

     

       
1179
       
1171
       
 
       
    { config, options, ... }:

     

       
1180
       
1172
       
 
       
    let

     

       
1181
       
1173
       
 
       
      fromOpt = getAttrFromPath from options;

     
···

       
1186
       
1178
       
 
       
    {

     

       
1187
       
1179
       
 
       
      options = setAttrByPath from (mkOption {

     

       
1188
       
1180
       
 
       
        inherit visible;

     

       
1189
       
1189
       
-
       
        description = if markdown

     

       
1190
       
1190
       
-
       
          then lib.mdDoc "Alias of {option}`${showOption to}`."

     

       
1191
       
1191
       
-
       
          else "Alias of <option>${showOption to}</option>.";

     

       
1181
       
1181
       
+
       
        description = "Alias of {option}`${showOption to}`.";

     

       
1192
       
1182
       
 
       
        apply = x: use (toOf config);

     

       
1193
       
1183
       
 
       
      } // optionalAttrs (toType != null) {

     

       
1194
       
1184
       
 
       
        type = toType;

     

···

       
100
       
100
       
 
       
    name: mkOption {

     

       
101
       
101
       
 
       
    default = false;

     

       
102
       
102
       
 
       
    example = true;

     

       
103
       
103
       
-
       
    description =

     

       
104
       
104
       
-
       
      if name ? _type && name._type == "mdDoc"

     

       
105
       
105
       
-
       
      then lib.mdDoc "Whether to enable ${name.text}."

     

       
106
       
106
       
-
       
      else "Whether to enable ${name}.";

     

       
103
       
103
       
+
       
    description = "Whether to enable ${name}.";

     

       
107
       
104
       
 
       
    type = lib.types.bool;

     

       
108
       
105
       
 
       
  };

     

       
109
       
106
       
 
       


     
···

       
185
       
182
       
 
       
          (if isList example then "pkgs." + concatStringsSep "." example else example);

     

       
186
       
183
       
 
       
      });

     

       
187
       
184
       
 
       


     

       
188
       
188
       
-
       
  /* Like mkPackageOption, but emit an mdDoc description instead of DocBook. */

     

       
189
       
189
       
-
       
  mkPackageOptionMD = pkgs: name: extra:

     

       
190
       
190
       
-
       
    let option = mkPackageOption pkgs name extra;

     

       
191
       
191
       
-
       
    in option // { description = lib.mdDoc option.description; };

     

       
185
       
185
       
+
       
  /* Alias of mkPackageOption. Previously used to create options with markdown

     

       
186
       
186
       
+
       
     documentation, which is no longer required.

     

       
187
       
187
       
+
       
  */

     

       
188
       
188
       
+
       
  mkPackageOptionMD = mkPackageOption;

     

       
192
       
189
       
 
       


     

       
193
       
190
       
 
       
  /* This option accepts anything, but it does not produce any result.

     

       
194
       
191
       
 
       


     
···

       
344
       
341
       
 
       
    if ! isString text then throw "literalExpression expects a string."

     

       
345
       
342
       
 
       
    else { _type = "literalExpression"; inherit text; };

     

       
346
       
343
       
 
       


     

       
347
       
347
       
-
       
  literalExample = lib.warn "literalExample is deprecated, use literalExpression instead, or use literalDocBook for a non-Nix description." literalExpression;

     

       
348
       
348
       
-
       


     

       
349
       
349
       
-
       


     

       
350
       
350
       
-
       
  /* For use in the `defaultText` and `example` option attributes. Causes the

     

       
351
       
351
       
-
       
     given DocBook text to be inserted verbatim in the documentation, for when

     

       
352
       
352
       
-
       
     a `literalExpression` would be too hard to read.

     

       
353
       
353
       
-
       
  */

     

       
354
       
354
       
-
       
  literalDocBook = text:

     

       
355
       
355
       
-
       
    if ! isString text then throw "literalDocBook expects a string."

     

       
356
       
356
       
-
       
    else

     

       
357
       
357
       
-
       
      lib.warnIf (lib.isInOldestRelease 2211)

     

       
358
       
358
       
-
       
        "literalDocBook is deprecated, use literalMD instead"

     

       
359
       
359
       
-
       
        { _type = "literalDocBook"; inherit text; };

     

       
344
       
344
       
+
       
  literalExample = lib.warn "literalExample is deprecated, use literalExpression instead, or use literalMD for a non-Nix description." literalExpression;

     

       
360
       
345
       
 
       


     

       
361
       
346
       
 
       
  /* Transition marker for documentation that's already migrated to markdown

     

       
362
       
362
       
-
       
     syntax.

     

       
347
       
347
       
+
       
     syntax. This is a no-op and no longer needed.

     

       
363
       
348
       
 
       
  */

     

       
364
       
364
       
-
       
  mdDoc = text:

     

       
365
       
365
       
-
       
    if ! isString text then throw "mdDoc expects a string."

     

       
366
       
366
       
-
       
    else { _type = "mdDoc"; inherit text; };

     

       
349
       
349
       
+
       
  mdDoc = lib.id;

     

       
367
       
350
       
 
       


     

       
368
       
351
       
 
       
  /* For use in the `defaultText` and `example` option attributes. Causes the

     

       
369
       
352
       
 
       
     given MD text to be inserted verbatim in the documentation, for when

     

···

       
6
       
6
       
 
       
, extraSources ? []

     

       
7
       
7
       
 
       
, baseOptionsJSON ? null

     

       
8
       
8
       
 
       
, warningsAreErrors ? true

     

       
9
       
9
       
-
       
, allowDocBook ? true

     

       
10
       
9
       
 
       
, prefix ? ../../..

     

       
11
       
10
       
 
       
}:

     

       
12
       
11
       
 
       


     
···

       
17
       
16
       
 
       


     

       
18
       
17
       
 
       
  lib = pkgs.lib;

     

       
19
       
18
       
 
       


     

       
20
       
20
       
-
       
  docbook_xsl_ns = pkgs.docbook-xsl-ns.override {

     

       
21
       
21
       
-
       
    withManOptDedupPatch = true;

     

       
22
       
22
       
-
       
  };

     

       
23
       
23
       
-
       


     

       
24
       
19
       
 
       
  manpageUrls = pkgs.path + "/doc/manpage-urls.json";

     

       
25
       
20
       
 
       


     

       
26
       
21
       
 
       
  # We need to strip references to /nix/store/* from options,

     
···

       
33
       
28
       
 
       
  stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;

     

       
34
       
29
       
 
       


     

       
35
       
30
       
 
       
  optionsDoc = buildPackages.nixosOptionsDoc {

     

       
36
       
36
       
-
       
    inherit options revision baseOptionsJSON warningsAreErrors allowDocBook;

     

       
31
       
31
       
+
       
    inherit options revision baseOptionsJSON warningsAreErrors;

     

       
37
       
32
       
 
       
    transformOptions = opt: opt // {

     

       
38
       
33
       
 
       
      # Clean up declaration sites to not refer to the NixOS source tree.

     

       
39
       
34
       
 
       
      declarations = map stripAnyPrefixes opt.declarations;

     
···

       
68
       
63
       
 
       
      optionIdPrefix = "test-opt-";

     

       
69
       
64
       
 
       
    };

     

       
70
       
65
       
 
       


     

       
71
       
71
       
-
       
  toc = builtins.toFile "toc.xml"

     

       
72
       
72
       
-
       
    ''

     

       
73
       
73
       
-
       
      <toc role="chunk-toc">

     

       
74
       
74
       
-
       
        <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-nixos-manual"><?dbhtml filename="index.html"?>

     

       
75
       
75
       
-
       
          <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry>

     

       
76
       
76
       
-
       
          <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry>

     

       
77
       
77
       
-
       
        </d:tocentry>

     

       
78
       
78
       
-
       
      </toc>

     

       
79
       
79
       
-
       
    '';

     

       
80
       
80
       
-
       


     

       
81
       
81
       
-
       
  manualXsltprocOptions = toString [

     

       
82
       
82
       
-
       
    "--param chapter.autolabel 0"

     

       
83
       
83
       
-
       
    "--param part.autolabel 0"

     

       
84
       
84
       
-
       
    "--param preface.autolabel 0"

     

       
85
       
85
       
-
       
    "--param reference.autolabel 0"

     

       
86
       
86
       
-
       
    "--param section.autolabel 0"

     

       
87
       
87
       
-
       
    "--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'"

     

       
88
       
88
       
-
       
    "--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'"

     

       
89
       
89
       
-
       
    "--param xref.with.number.and.title 0"

     

       
90
       
90
       
-
       
    "--param toc.section.depth 0"

     

       
91
       
91
       
-
       
    "--param generate.consistent.ids 1"

     

       
92
       
92
       
-
       
    "--stringparam admon.style ''"

     

       
93
       
93
       
-
       
    "--stringparam callout.graphics.extension .svg"

     

       
94
       
94
       
-
       
    "--stringparam current.docid manual"

     

       
95
       
95
       
-
       
    "--param chunk.section.depth 0"

     

       
96
       
96
       
-
       
    "--param chunk.first.sections 1"

     

       
97
       
97
       
-
       
    "--param use.id.as.filename 1"

     

       
98
       
98
       
-
       
    "--stringparam chunk.toc ${toc}"

     

       
99
       
99
       
-
       
  ];

     

       
100
       
100
       
-
       


     

       
101
       
101
       
-
       
  linterFunctions = ''

     

       
102
       
102
       
-
       
    # outputs the context of an xmllint error output

     

       
103
       
103
       
-
       
    # LEN lines around the failing line are printed

     

       
104
       
104
       
-
       
    function context {

     

       
105
       
105
       
-
       
      # length of context

     

       
106
       
106
       
-
       
      local LEN=6

     

       
107
       
107
       
-
       
      # lines to print before error line

     

       
108
       
108
       
-
       
      local BEFORE=4

     

       
109
       
109
       
-
       


     

       
110
       
110
       
-
       
      # xmllint output lines are:

     

       
111
       
111
       
-
       
      # file.xml:1234: there was an error on line 1234

     

       
112
       
112
       
-
       
      while IFS=':' read -r file line rest; do

     

       
113
       
113
       
-
       
        echo

     

       
114
       
114
       
-
       
        if [[ -n "$rest" ]]; then

     

       
115
       
115
       
-
       
          echo "$file:$line:$rest"

     

       
116
       
116
       
-
       
          local FROM=$(($line>$BEFORE ? $line - $BEFORE : 1))

     

       
117
       
117
       
-
       
          # number lines & filter context

     

       
118
       
118
       
-
       
          nl --body-numbering=a "$file" | sed -n "$FROM,+$LEN p"

     

       
119
       
119
       
-
       
        else

     

       
120
       
120
       
-
       
          if [[ -n "$line" ]]; then

     

       
121
       
121
       
-
       
            echo "$file:$line"

     

       
122
       
122
       
-
       
          else

     

       
123
       
123
       
-
       
            echo "$file"

     

       
124
       
124
       
-
       
          fi

     

       
125
       
125
       
-
       
        fi

     

       
126
       
126
       
-
       
      done

     

       
127
       
127
       
-
       
    }

     

       
128
       
128
       
-
       


     

       
129
       
129
       
-
       
    function lintrng {

     

       
130
       
130
       
-
       
      xmllint --debug --noout --nonet \

     

       
131
       
131
       
-
       
        --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \

     

       
132
       
132
       
-
       
        "$1" \

     

       
133
       
133
       
-
       
        2>&1 | context 1>&2

     

       
134
       
134
       
-
       
        # ^ redirect assumes xmllint doesn’t print to stdout

     

       
135
       
135
       
-
       
    }

     

       
136
       
136
       
-
       
  '';

     

       
137
       
137
       
-
       


     

       
138
       
66
       
 
       
  prepareManualFromMD = ''

     

       
139
       
67
       
 
       
    cp -r --no-preserve=all $inputs/* .

     

       
140
       
68
       
 
       


     
···

       
154
       
82
       
 
       
        ${testOptionsDoc.optionsJSON}/share/doc/nixos/options.json

     

       
155
       
83
       
 
       
  '';

     

       
156
       
84
       
 
       


     

       
157
       
157
       
-
       
  manual-combined = runCommand "nixos-manual-combined"

     

       
158
       
158
       
-
       
    { inputs = lib.sourceFilesBySuffices ./. [ ".xml" ".md" ];

     

       
159
       
159
       
-
       
      nativeBuildInputs = [ pkgs.nixos-render-docs pkgs.libxml2.bin pkgs.libxslt.bin ];

     

       
160
       
160
       
-
       
      meta.description = "The NixOS manual as plain docbook XML";

     

       
161
       
161
       
-
       
    }

     

       
162
       
162
       
-
       
    ''

     

       
163
       
163
       
-
       
      ${prepareManualFromMD}

     

       
164
       
164
       
-
       


     

       
165
       
165
       
-
       
      nixos-render-docs -j $NIX_BUILD_CORES manual docbook \

     

       
166
       
166
       
-
       
        --manpage-urls ${manpageUrls} \

     

       
167
       
167
       
-
       
        --revision ${lib.escapeShellArg revision} \

     

       
168
       
168
       
-
       
        ./manual.md \

     

       
169
       
169
       
-
       
        ./manual-combined-pre.xml

     

       
170
       
170
       
-
       


     

       
171
       
171
       
-
       
      xsltproc \

     

       
172
       
172
       
-
       
        -o manual-combined.xml ${./../../lib/make-options-doc/postprocess-option-descriptions.xsl} \

     

       
173
       
173
       
-
       
        manual-combined-pre.xml

     

       
174
       
174
       
-
       


     

       
175
       
175
       
-
       
      ${linterFunctions}

     

       
176
       
176
       
-
       


     

       
177
       
177
       
-
       
      mkdir $out

     

       
178
       
178
       
-
       
      cp manual-combined.xml $out/

     

       
179
       
179
       
-
       


     

       
180
       
180
       
-
       
      lintrng $out/manual-combined.xml

     

       
181
       
181
       
-
       
    '';

     

       
182
       
182
       
-
       


     

       
183
       
183
       
-
       
  manpages-combined = runCommand "nixos-manpages-combined.xml"

     

       
184
       
184
       
-
       
    { nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];

     

       
185
       
185
       
-
       
      meta.description = "The NixOS manpages as plain docbook XML";

     

       
186
       
186
       
-
       
    }

     

       
187
       
187
       
-
       
    ''

     

       
188
       
188
       
-
       
      mkdir generated

     

       
189
       
189
       
-
       
      cp -prd ${./man-pages.xml} man-pages.xml

     

       
190
       
190
       
-
       
      ln -s ${optionsDoc.optionsDocBook} generated/options-db.xml

     

       
191
       
191
       
-
       


     

       
192
       
192
       
-
       
      xmllint --xinclude --noxincludenode --output $out ./man-pages.xml

     

       
193
       
193
       
-
       


     

       
194
       
194
       
-
       
      ${linterFunctions}

     

       
195
       
195
       
-
       


     

       
196
       
196
       
-
       
      lintrng $out

     

       
197
       
197
       
-
       
    '';

     

       
198
       
198
       
-
       


     

       
199
       
85
       
 
       
in rec {

     

       
200
       
200
       
-
       
  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook optionsUsedDocbook;

     

       
86
       
86
       
+
       
  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;

     

       
201
       
87
       
 
       


     

       
202
       
88
       
 
       
  # Generate the NixOS manual.

     

       
203
       
89
       
 
       
  manualHTML = runCommand "nixos-manual-html"

     

       
204
       
204
       
-
       
    { nativeBuildInputs =

     

       
205
       
205
       
-
       
        if allowDocBook then [

     

       
206
       
206
       
-
       
          buildPackages.libxml2.bin

     

       
207
       
207
       
-
       
          buildPackages.libxslt.bin

     

       
208
       
208
       
-
       
        ] else [

     

       
209
       
209
       
-
       
          buildPackages.nixos-render-docs

     

       
210
       
210
       
-
       
        ];

     

       
211
       
211
       
-
       
      inputs = lib.optionals (! allowDocBook) (lib.sourceFilesBySuffices ./. [ ".md" ]);

     

       
90
       
90
       
+
       
    { nativeBuildInputs = [ buildPackages.nixos-render-docs ];

     

       
91
       
91
       
+
       
      inputs = lib.sourceFilesBySuffices ./. [ ".md" ];

     

       
212
       
92
       
 
       
      meta.description = "The NixOS manual in HTML format";

     

       
213
       
93
       
 
       
      allowedReferences = ["out"];

     

       
214
       
94
       
 
       
    }

     
···

       
221
       
101
       
 
       
      cp ${../../../doc/overrides.css} $dst/overrides.css

     

       
222
       
102
       
 
       
      cp -r ${pkgs.documentation-highlighter} $dst/highlightjs

     

       
223
       
103
       
 
       


     

       
224
       
224
       
-
       
      ${if allowDocBook then ''

     

       
225
       
225
       
-
       
          xsltproc \

     

       
226
       
226
       
-
       
            ${manualXsltprocOptions} \

     

       
227
       
227
       
-
       
            --stringparam id.warnings "1" \

     

       
228
       
228
       
-
       
            --nonet --output $dst/ \

     

       
229
       
229
       
-
       
            ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \

     

       
230
       
230
       
-
       
            ${manual-combined}/manual-combined.xml \

     

       
231
       
231
       
-
       
            |& tee xsltproc.out

     

       
232
       
232
       
-
       
          grep "^ID recommended on" xsltproc.out &>/dev/null && echo "error: some IDs are missing" && false

     

       
233
       
233
       
-
       
          rm xsltproc.out

     

       
104
       
104
       
+
       
      ${prepareManualFromMD}

     

       
234
       
105
       
 
       


     

       
235
       
235
       
-
       
          mkdir -p $dst/images/callouts

     

       
236
       
236
       
-
       
          cp ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/

     

       
237
       
237
       
-
       
        '' else ''

     

       
238
       
238
       
-
       
          ${prepareManualFromMD}

     

       
239
       
239
       
-
       


     

       
240
       
240
       
-
       
          # TODO generator is set like this because the docbook/md manual compare workflow will

     

       
241
       
241
       
-
       
          # trigger if it's different

     

       
242
       
242
       
-
       
          nixos-render-docs -j $NIX_BUILD_CORES manual html \

     

       
243
       
243
       
-
       
            --manpage-urls ${manpageUrls} \

     

       
244
       
244
       
-
       
            --revision ${lib.escapeShellArg revision} \

     

       
245
       
245
       
-
       
            --generator "DocBook XSL Stylesheets V${docbook_xsl_ns.version}" \

     

       
246
       
246
       
-
       
            --stylesheet style.css \

     

       
247
       
247
       
-
       
            --stylesheet overrides.css \

     

       
248
       
248
       
-
       
            --stylesheet highlightjs/mono-blue.css \

     

       
249
       
249
       
-
       
            --script ./highlightjs/highlight.pack.js \

     

       
250
       
250
       
-
       
            --script ./highlightjs/loader.js \

     

       
251
       
251
       
-
       
            --toc-depth 1 \

     

       
252
       
252
       
-
       
            --chunk-toc-depth 1 \

     

       
253
       
253
       
-
       
            ./manual.md \

     

       
254
       
254
       
-
       
            $dst/index.html

     

       
255
       
255
       
-
       
        ''}

     

       
106
       
106
       
+
       
      nixos-render-docs -j $NIX_BUILD_CORES manual html \

     

       
107
       
107
       
+
       
        --manpage-urls ${manpageUrls} \

     

       
108
       
108
       
+
       
        --revision ${lib.escapeShellArg revision} \

     

       
109
       
109
       
+
       
        --generator "nixos-render-docs ${lib.version}" \

     

       
110
       
110
       
+
       
        --stylesheet style.css \

     

       
111
       
111
       
+
       
        --stylesheet overrides.css \

     

       
112
       
112
       
+
       
        --stylesheet highlightjs/mono-blue.css \

     

       
113
       
113
       
+
       
        --script ./highlightjs/highlight.pack.js \

     

       
114
       
114
       
+
       
        --script ./highlightjs/loader.js \

     

       
115
       
115
       
+
       
        --toc-depth 1 \

     

       
116
       
116
       
+
       
        --chunk-toc-depth 1 \

     

       
117
       
117
       
+
       
        ./manual.md \

     

       
118
       
118
       
+
       
        $dst/index.html

     

       
256
       
119
       
 
       


     

       
257
       
120
       
 
       
      mkdir -p $out/nix-support

     

       
258
       
121
       
 
       
      echo "nix-build out $out" >> $out/nix-support/hydra-build-products

     
···

       
318
       
181
       
 
       
  manpages = runCommand "nixos-manpages"

     

       
319
       
182
       
 
       
    { nativeBuildInputs = [

     

       
320
       
183
       
 
       
        buildPackages.installShellFiles

     

       
321
       
321
       
-
       
      ] ++ lib.optionals allowDocBook [

     

       
322
       
322
       
-
       
        buildPackages.libxml2.bin

     

       
323
       
323
       
-
       
        buildPackages.libxslt.bin

     

       
324
       
324
       
-
       
      ] ++ lib.optionals (! allowDocBook) [

     

       
325
       
184
       
 
       
        buildPackages.nixos-render-docs

     

       
326
       
185
       
 
       
      ];

     

       
327
       
186
       
 
       
      allowedReferences = ["out"];

     
···

       
330
       
189
       
 
       
      # Generate manpages.

     

       
331
       
190
       
 
       
      mkdir -p $out/share/man/man8

     

       
332
       
191
       
 
       
      installManPage ${./manpages}/*

     

       
333
       
333
       
-
       
      ${if allowDocBook

     

       
334
       
334
       
-
       
        then ''

     

       
335
       
335
       
-
       
          xsltproc --nonet \

     

       
336
       
336
       
-
       
            --maxdepth 6000 \

     

       
337
       
337
       
-
       
            --param man.output.in.separate.dir 1 \

     

       
338
       
338
       
-
       
            --param man.output.base.dir "'$out/share/man/'" \

     

       
339
       
339
       
-
       
            --param man.endnotes.are.numbered 0 \

     

       
340
       
340
       
-
       
            --param man.break.after.slash 1 \

     

       
341
       
341
       
-
       
            ${docbook_xsl_ns}/xml/xsl/docbook/manpages/docbook.xsl \

     

       
342
       
342
       
-
       
            ${manpages-combined}

     

       
343
       
343
       
-
       
        ''

     

       
344
       
344
       
-
       
        else ''

     

       
345
       
345
       
-
       
          mkdir -p $out/share/man/man5

     

       
346
       
346
       
-
       
          nixos-render-docs -j $NIX_BUILD_CORES options manpage \

     

       
347
       
347
       
-
       
            --revision ${lib.escapeShellArg revision} \

     

       
348
       
348
       
-
       
            ${optionsJSON}/share/doc/nixos/options.json \

     

       
349
       
349
       
-
       
            $out/share/man/man5/configuration.nix.5

     

       
350
       
350
       
-
       
        ''}

     

       
192
       
192
       
+
       
      mkdir -p $out/share/man/man5

     

       
193
       
193
       
+
       
      nixos-render-docs -j $NIX_BUILD_CORES options manpage \

     

       
194
       
194
       
+
       
        --revision ${lib.escapeShellArg revision} \

     

       
195
       
195
       
+
       
        ${optionsJSON}/share/doc/nixos/options.json \

     

       
196
       
196
       
+
       
        $out/share/man/man5/configuration.nix.5

     

       
351
       
197
       
 
       
    '';

     

       
352
       
198
       
 
       


     

       
353
       
199
       
 
       
}

     

···

       
1
       
1
       
-
       
<reference xmlns="http://docbook.org/ns/docbook"

     

       
2
       
2
       
-
       
           xmlns:xlink="http://www.w3.org/1999/xlink"

     

       
3
       
3
       
-
       
           xmlns:xi="http://www.w3.org/2001/XInclude">

     

       
4
       
4
       
-
       
 <title>NixOS Reference Pages</title>

     

       
5
       
5
       
-
       
 <info>

     

       
6
       
6
       
-
       
  <author>

     

       
7
       
7
       
-
       
   <personname><firstname>Eelco</firstname><surname>Dolstra</surname></personname>

     

       
8
       
8
       
-
       
   <contrib>Author</contrib>

     

       
9
       
9
       
-
       
  </author>

     

       
10
       
10
       
-
       
  <author>

     

       
11
       
11
       
-
       
   <personname><othername>The Nixpkgs/NixOS contributors</othername></personname>

     

       
12
       
12
       
-
       
   <contrib>Author</contrib>

     

       
13
       
13
       
-
       
  </author>

     

       
14
       
14
       
-
       
  <copyright><year>2007-2022</year><holder>Eelco Dolstra and the Nixpkgs/NixOS contributors</holder>

     

       
15
       
15
       
-
       
  </copyright>

     

       
16
       
16
       
-
       
 </info>

     

       
17
       
17
       
-
       
 <refentry>

     

       
18
       
18
       
-
       
  <refmeta>

     

       
19
       
19
       
-
       
   <refentrytitle><filename>configuration.nix</filename>

     

       
20
       
20
       
-
       
   </refentrytitle><manvolnum>5</manvolnum>

     

       
21
       
21
       
-
       
   <refmiscinfo class="source">NixOS</refmiscinfo>

     

       
22
       
22
       
-
       
 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->

     

       
23
       
23
       
-
       
  </refmeta>

     

       
24
       
24
       
-
       
  <refnamediv>

     

       
25
       
25
       
-
       
   <refname><filename>configuration.nix</filename></refname>

     

       
26
       
26
       
-
       
   <refpurpose>NixOS system configuration specification</refpurpose>

     

       
27
       
27
       
-
       
  </refnamediv>

     

       
28
       
28
       
-
       
  <refsection>

     

       
29
       
29
       
-
       
   <title>Description</title>

     

       
30
       
30
       
-
       
   <para>

     

       
31
       
31
       
-
       
    The file <filename>/etc/nixos/configuration.nix</filename> contains the

     

       
32
       
32
       
-
       
    declarative specification of your NixOS system configuration. The command

     

       
33
       
33
       
-
       
    <command>nixos-rebuild</command> takes this file and realises the system

     

       
34
       
34
       
-
       
    configuration specified therein.

     

       
35
       
35
       
-
       
   </para>

     

       
36
       
36
       
-
       
  </refsection>

     

       
37
       
37
       
-
       
  <refsection>

     

       
38
       
38
       
-
       
   <title>Options</title>

     

       
39
       
39
       
-
       
   <para>

     

       
40
       
40
       
-
       
    You can use the following options in <filename>configuration.nix</filename>.

     

       
41
       
41
       
-
       
   </para>

     

       
42
       
42
       
-
       
   <xi:include href="./generated/options-db.xml"

     

       
43
       
43
       
-
       
             xpointer="configuration-variable-list" />

     

       
44
       
44
       
-
       
  </refsection>

     

       
45
       
45
       
-
       
 </refentry>

     

       
46
       
46
       
-
       
</reference>

     

···

       
58
       
58
       
 
       


     

       
59
       
59
       
 
       
- A new option was added to the virtualisation module that enables specifying explicitly named network interfaces in QEMU VMs. The existing `virtualisation.vlans` is still supported for cases where the name of the network interface is irrelevant.

     

       
60
       
60
       
 
       


     

       
61
       
61
       
+
       
- DocBook option documentation is no longer supported, all module documentation now uses markdown.

     

       
62
       
62
       
+
       


     

       
61
       
63
       
 
       
- `services.nginx` gained a `defaultListen` option at server-level with support for PROXY protocol listeners, also `proxyProtocol` is now exposed in `services.nginx.virtualHosts.<name>.listen` option. It is now possible to run PROXY listeners and non-PROXY listeners at a server-level, see [#213510](https://github.com/NixOS/nixpkgs/pull/213510/) for more details.

     

       
62
       
64
       
 
       


     

       
63
       
65
       
 
       
## Nixpkgs internals {#sec-release-23.11-nixpkgs-internals}

     

···

       
39
       
39
       
 
       
# allow docbook option docs if `true`. only markdown documentation is allowed when set to

     

       
40
       
40
       
 
       
# `false`, and a different renderer may be used with different bugs and performance

     

       
41
       
41
       
 
       
# characteristics but (hopefully) indistinguishable output.

     

       
42
       
42
       
-
       
, allowDocBook ? true

     

       
42
       
42
       
+
       
# deprecated since 23.11.

     

       
43
       
43
       
+
       
# TODO remove in a while.

     

       
44
       
44
       
+
       
, allowDocBook ? false

     

       
43
       
45
       
 
       
# whether lib.mdDoc is required for descriptions to be read as markdown.

     

       
44
       
44
       
-
       
# !!! when this is eventually flipped to true, `lib.doRename` should also default to emitting Markdown

     

       
45
       
45
       
-
       
, markdownByDefault ? false

     

       
46
       
46
       
+
       
# deprecated since 23.11.

     

       
47
       
47
       
+
       
# TODO remove in a while.

     

       
48
       
48
       
+
       
, markdownByDefault ? true

     

       
46
       
49
       
 
       
}:

     

       
50
       
50
       
+
       


     

       
51
       
51
       
+
       
assert markdownByDefault && ! allowDocBook;

     

       
47
       
52
       
 
       


     

       
48
       
53
       
 
       
let

     

       
49
       
54
       
 
       
  rawOpts = lib.optionAttrSetToDocList options;

     
···

       
134
       
139
       
 
       
      TOUCH_IF_DB=$dst/.used-docbook \

     

       
135
       
140
       
 
       
      python ${./mergeJSON.py} \

     

       
136
       
141
       
 
       
        ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \

     

       
137
       
137
       
-
       
        ${if allowDocBook then "--warn-on-docbook" else "--error-on-docbook"} \

     

       
138
       
142
       
 
       
        $baseJSON $options \

     

       
139
       
143
       
 
       
        > $dst/options.json

     

       
140
       
144
       
 
       


     

       
141
       
141
       
-
       
      brotli -9 < $dst/options.json > $dst/options.json.br

     

       
142
       
142
       
-
       


     

       
143
       
143
       
-
       
      mkdir -p $out/nix-support

     

       
144
       
144
       
-
       
      echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products

     

       
145
       
145
       
-
       
      echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products

     

       
146
       
146
       
-
       
    '';

     

       
147
       
147
       
-
       


     

       
148
       
148
       
-
       
  optionsUsedDocbook = pkgs.runCommand "options-used-docbook" {} ''

     

       
149
       
149
       
-
       
    if [ -e ${optionsJSON}/share/doc/nixos/.used-docbook ]; then

     

       
150
       
150
       
-
       
      echo 1

     

       
151
       
151
       
-
       
    else

     

       
152
       
152
       
-
       
      echo 0

     

       
153
       
153
       
-
       
    fi >"$out"

     

       
154
       
154
       
-
       
  '';

     

       
155
       
155
       
-
       


     

       
156
       
156
       
-
       
  optionsDocBook = pkgs.runCommand "options-docbook.xml" {

     

       
157
       
157
       
-
       
    nativeBuildInputs = [

     

       
158
       
158
       
-
       
      pkgs.nixos-render-docs

     

       
159
       
159
       
-
       
    ];

     

       
160
       
160
       
-
       
  } ''

     

       
161
       
161
       
-
       
    nixos-render-docs -j $NIX_BUILD_CORES options docbook \

     

       
162
       
162
       
-
       
      --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \

     

       
163
       
163
       
-
       
      --revision ${lib.escapeShellArg revision} \

     

       
164
       
164
       
-
       
      --document-type ${lib.escapeShellArg documentType} \

     

       
165
       
165
       
-
       
      --varlist-id ${lib.escapeShellArg variablelistId} \

     

       
166
       
166
       
-
       
      --id-prefix ${lib.escapeShellArg optionIdPrefix} \

     

       
167
       
167
       
-
       
      ${lib.optionalString markdownByDefault "--markdown-by-default"} \

     

       
168
       
168
       
-
       
      ${optionsJSON}/share/doc/nixos/options.json \

     

       
169
       
169
       
-
       
      options.xml

     

       
170
       
170
       
-
       


     

       
171
       
171
       
-
       
    if grep /nixpkgs/nixos/modules options.xml; then

     

       
145
       
145
       
+
       
    if grep /nixpkgs/nixos/modules $dst/options.json; then

     

       
172
       
146
       
 
       
      echo "The manual appears to depend on the location of Nixpkgs, which is bad"

     

       
173
       
147
       
 
       
      echo "since this prevents sharing via the NixOS channel.  This is typically"

     

       
174
       
148
       
 
       
      echo "caused by an option default that refers to a relative path (see above"

     
···

       
176
       
150
       
 
       
      exit 1

     

       
177
       
151
       
 
       
    fi

     

       
178
       
152
       
 
       


     

       
179
       
179
       
-
       
    ${pkgs.libxslt.bin}/bin/xsltproc \

     

       
180
       
180
       
-
       
      -o "$out" ${./postprocess-option-descriptions.xsl} options.xml

     

       
181
       
181
       
-
       
  '';

     

       
153
       
153
       
+
       
      brotli -9 < $dst/options.json > $dst/options.json.br

     

       
154
       
154
       
+
       


     

       
155
       
155
       
+
       
      mkdir -p $out/nix-support

     

       
156
       
156
       
+
       
      echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products

     

       
157
       
157
       
+
       
      echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products

     

       
158
       
158
       
+
       
    '';

     

       
159
       
159
       
+
       


     

       
160
       
160
       
+
       
  optionsDocBook = lib.warn "optionsDocBook is deprecated since 23.11 and will be removed in 24.05"

     

       
161
       
161
       
+
       
    (pkgs.runCommand "options-docbook.xml" {

     

       
162
       
162
       
+
       
      nativeBuildInputs = [

     

       
163
       
163
       
+
       
        pkgs.nixos-render-docs

     

       
164
       
164
       
+
       
      ];

     

       
165
       
165
       
+
       
    } ''

     

       
166
       
166
       
+
       
      nixos-render-docs -j $NIX_BUILD_CORES options docbook \

     

       
167
       
167
       
+
       
        --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \

     

       
168
       
168
       
+
       
        --revision ${lib.escapeShellArg revision} \

     

       
169
       
169
       
+
       
        --document-type ${lib.escapeShellArg documentType} \

     

       
170
       
170
       
+
       
        --varlist-id ${lib.escapeShellArg variablelistId} \

     

       
171
       
171
       
+
       
        --id-prefix ${lib.escapeShellArg optionIdPrefix} \

     

       
172
       
172
       
+
       
        ${optionsJSON}/share/doc/nixos/options.json \

     

       
173
       
173
       
+
       
        "$out"

     

       
174
       
174
       
+
       
    '');

     

       
182
       
175
       
 
       
}

     

···

       
43
       
43
       
 
       
    return result

     

       
44
       
44
       
 
       


     

       
45
       
45
       
 
       
warningsAreErrors = False

     

       
46
       
46
       
-
       
warnOnDocbook = False

     

       
47
       
47
       
-
       
errorOnDocbook = False

     

       
48
       
46
       
 
       
optOffset = 0

     

       
49
       
47
       
 
       
for arg in sys.argv[1:]:

     

       
50
       
48
       
 
       
    if arg == "--warnings-are-errors":

     

       
51
       
49
       
 
       
        optOffset += 1

     

       
52
       
50
       
 
       
        warningsAreErrors = True

     

       
53
       
53
       
-
       
    if arg == "--warn-on-docbook":

     

       
54
       
54
       
-
       
        optOffset += 1

     

       
55
       
55
       
-
       
        warnOnDocbook = True

     

       
56
       
56
       
-
       
    elif arg == "--error-on-docbook":

     

       
57
       
57
       
-
       
        optOffset += 1

     

       
58
       
58
       
-
       
        errorOnDocbook = True

     

       
59
       
51
       
 
       


     

       
60
       
52
       
 
       
options = pivot(json.load(open(sys.argv[1 + optOffset], 'r')))

     

       
61
       
53
       
 
       
overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))

     
···

       
84
       
76
       
 
       


     

       
85
       
77
       
 
       
severity = "error" if warningsAreErrors else "warning"

     

       
86
       
78
       
 
       


     

       
87
       
87
       
-
       
def is_docbook(o, key):

     

       
88
       
88
       
-
       
    val = o.get(key, {})

     

       
89
       
89
       
-
       
    if not isinstance(val, dict):

     

       
90
       
90
       
-
       
        return False

     

       
91
       
91
       
-
       
    return val.get('_type', '') == 'literalDocBook'

     

       
92
       
92
       
-
       


     

       
93
       
79
       
 
       
# check that every option has a description

     

       
94
       
80
       
 
       
hasWarnings = False

     

       
95
       
81
       
 
       
hasErrors = False

     

       
96
       
96
       
-
       
hasDocBook = False

     

       
97
       
82
       
 
       
for (k, v) in options.items():

     

       
98
       
98
       
-
       
    if warnOnDocbook or errorOnDocbook:

     

       
99
       
99
       
-
       
        kind = "error" if errorOnDocbook else "warning"

     

       
100
       
100
       
-
       
        if isinstance(v.value.get('description', {}), str):

     

       
101
       
101
       
-
       
            hasErrors |= errorOnDocbook

     

       
102
       
102
       
-
       
            hasDocBook = True

     

       
103
       
103
       
-
       
            print(

     

       
104
       
104
       
-
       
                f"\x1b[1;31m{kind}: option {v.name} description uses DocBook\x1b[0m",

     

       
105
       
105
       
-
       
                file=sys.stderr)

     

       
106
       
106
       
-
       
        elif is_docbook(v.value, 'defaultText'):

     

       
107
       
107
       
-
       
            hasErrors |= errorOnDocbook

     

       
108
       
108
       
-
       
            hasDocBook = True

     

       
109
       
109
       
-
       
            print(

     

       
110
       
110
       
-
       
                f"\x1b[1;31m{kind}: option {v.name} default uses DocBook\x1b[0m",

     

       
111
       
111
       
-
       
                file=sys.stderr)

     

       
112
       
112
       
-
       
        elif is_docbook(v.value, 'example'):

     

       
113
       
113
       
-
       
            hasErrors |= errorOnDocbook

     

       
114
       
114
       
-
       
            hasDocBook = True

     

       
115
       
115
       
-
       
            print(

     

       
116
       
116
       
-
       
                f"\x1b[1;31m{kind}: option {v.name} example uses DocBook\x1b[0m",

     

       
117
       
117
       
-
       
                file=sys.stderr)

     

       
118
       
118
       
-
       


     

       
119
       
83
       
 
       
    if v.value.get('description', None) is None:

     

       
120
       
84
       
 
       
        hasWarnings = True

     

       
121
       
85
       
 
       
        print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr)

     
···

       
125
       
89
       
 
       
        print(

     

       
126
       
90
       
 
       
            f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +

     

       
127
       
91
       
 
       
            "https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)

     

       
128
       
128
       
-
       


     

       
129
       
129
       
-
       
if hasDocBook:

     

       
130
       
130
       
-
       
    (why, what) = (

     

       
131
       
131
       
-
       
        ("disallowed for in-tree modules", "contribution") if errorOnDocbook

     

       
132
       
132
       
-
       
        else ("deprecated for option documentation", "module")

     

       
133
       
133
       
-
       
    )

     

       
134
       
134
       
-
       
    print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +

     

       
135
       
135
       
-
       
        "NixOS is in the process of migrating from DocBook to Markdown, and " +

     

       
136
       
136
       
-
       
        f"DocBook is {why}. To change your {what} to "+

     

       
137
       
137
       
-
       
        "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " +

     

       
138
       
138
       
-
       
        "functions where they are available. For example:\n" +

     

       
139
       
139
       
-
       
        "\n" +

     

       
140
       
140
       
-
       
        "  example.foo = mkOption {\n" +

     

       
141
       
141
       
-
       
        "    description = lib.mdDoc ''your description'';\n" +

     

       
142
       
142
       
-
       
        "    defaultText = lib.literalMD ''your description of default'';\n" +

     

       
143
       
143
       
-
       
        "  };\n" +

     

       
144
       
144
       
-
       
        "\n" +

     

       
145
       
145
       
-
       
        "  example.enable = mkEnableOption (lib.mdDoc ''your thing'');\n" +

     

       
146
       
146
       
-
       
        "  example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" +

     

       
147
       
147
       
-
       
        "  imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];",

     

       
148
       
148
       
-
       
        file = sys.stderr)

     

       
149
       
149
       
-
       
    with open(os.getenv('TOUCH_IF_DB'), 'x'):

     

       
150
       
150
       
-
       
        # just make sure it exists

     

       
151
       
151
       
-
       
        pass

     

       
152
       
92
       
 
       


     

       
153
       
93
       
 
       
if hasErrors:

     

       
154
       
94
       
 
       
    sys.exit(1)

     

···

       
1
       
1
       
-
       
<?xml version="1.0"?>

     

       
2
       
2
       
-
       


     

       
3
       
3
       
-
       
<xsl:stylesheet version="1.0"

     

       
4
       
4
       
-
       
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     

       
5
       
5
       
-
       
                xmlns:str="http://exslt.org/strings"

     

       
6
       
6
       
-
       
                xmlns:exsl="http://exslt.org/common"

     

       
7
       
7
       
-
       
                xmlns:db="http://docbook.org/ns/docbook"

     

       
8
       
8
       
-
       
                xmlns:nixos="tag:nixos.org"

     

       
9
       
9
       
-
       
                extension-element-prefixes="str exsl">

     

       
10
       
10
       
-
       
  <xsl:output method='xml' encoding="UTF-8" />

     

       
11
       
11
       
-
       


     

       
12
       
12
       
-
       
  <xsl:template match="@*|node()">

     

       
13
       
13
       
-
       
    <xsl:copy>

     

       
14
       
14
       
-
       
      <xsl:apply-templates select="@*|node()" />

     

       
15
       
15
       
-
       
    </xsl:copy>

     

       
16
       
16
       
-
       
  </xsl:template>

     

       
17
       
17
       
-
       


     

       
18
       
18
       
-
       
  <xsl:template name="break-up-description">

     

       
19
       
19
       
-
       
    <xsl:param name="input" />

     

       
20
       
20
       
-
       
    <xsl:param name="buffer" />

     

       
21
       
21
       
-
       


     

       
22
       
22
       
-
       
    <!-- Every time we have two newlines following each other, we want to

     

       
23
       
23
       
-
       
         break it into </para><para>. -->

     

       
24
       
24
       
-
       
    <xsl:variable name="parbreak" select="'&#xa;&#xa;'" />

     

       
25
       
25
       
-
       


     

       
26
       
26
       
-
       
    <!-- Similar to "(head:tail) = input" in Haskell. -->

     

       
27
       
27
       
-
       
    <xsl:variable name="head" select="$input[1]" />

     

       
28
       
28
       
-
       
    <xsl:variable name="tail" select="$input[position() &gt; 1]" />

     

       
29
       
29
       
-
       


     

       
30
       
30
       
-
       
    <xsl:choose>

     

       
31
       
31
       
-
       
      <xsl:when test="$head/self::text() and contains($head, $parbreak)">

     

       
32
       
32
       
-
       
        <!-- If the haystack provided to str:split() directly starts or

     

       
33
       
33
       
-
       
             ends with $parbreak, it doesn't generate a <token/> for that,

     

       
34
       
34
       
-
       
             so we are doing this here. -->

     

       
35
       
35
       
-
       
        <xsl:variable name="splitted-raw">

     

       
36
       
36
       
-
       
          <xsl:if test="starts-with($head, $parbreak)"><token /></xsl:if>

     

       
37
       
37
       
-
       
          <xsl:for-each select="str:split($head, $parbreak)">

     

       
38
       
38
       
-
       
            <token><xsl:value-of select="node()" /></token>

     

       
39
       
39
       
-
       
          </xsl:for-each>

     

       
40
       
40
       
-
       
          <!-- Something like ends-with($head, $parbreak), but there is

     

       
41
       
41
       
-
       
               no ends-with() in XSLT, so we need to use substring(). -->

     

       
42
       
42
       
-
       
          <xsl:if test="

     

       
43
       
43
       
-
       
            substring($head, string-length($head) -

     

       
44
       
44
       
-
       
                             string-length($parbreak) + 1) = $parbreak

     

       
45
       
45
       
-
       
          "><token /></xsl:if>

     

       
46
       
46
       
-
       
        </xsl:variable>

     

       
47
       
47
       
-
       
        <xsl:variable name="splitted"

     

       
48
       
48
       
-
       
                      select="exsl:node-set($splitted-raw)/token" />

     

       
49
       
49
       
-
       
        <!-- The buffer we had so far didn't contain any text nodes that

     

       
50
       
50
       
-
       
             contain a $parbreak, so we can put the buffer along with the

     

       
51
       
51
       
-
       
             first token of $splitted into a para element. -->

     

       
52
       
52
       
-
       
        <para xmlns="http://docbook.org/ns/docbook">

     

       
53
       
53
       
-
       
          <xsl:apply-templates select="exsl:node-set($buffer)" />

     

       
54
       
54
       
-
       
          <xsl:apply-templates select="$splitted[1]/node()" />

     

       
55
       
55
       
-
       
        </para>

     

       
56
       
56
       
-
       
        <!-- We have already emitted the first splitted result, so the

     

       
57
       
57
       
-
       
             last result is going to be set as the new $buffer later

     

       
58
       
58
       
-
       
             because its contents may not be directly followed up by a

     

       
59
       
59
       
-
       
             $parbreak. -->

     

       
60
       
60
       
-
       
        <xsl:for-each select="$splitted[position() &gt; 1

     

       
61
       
61
       
-
       
                              and position() &lt; last()]">

     

       
62
       
62
       
-
       
          <para xmlns="http://docbook.org/ns/docbook">

     

       
63
       
63
       
-
       
            <xsl:apply-templates select="node()" />

     

       
64
       
64
       
-
       
          </para>

     

       
65
       
65
       
-
       
        </xsl:for-each>

     

       
66
       
66
       
-
       
        <xsl:call-template name="break-up-description">

     

       
67
       
67
       
-
       
          <xsl:with-param name="input" select="$tail" />

     

       
68
       
68
       
-
       
          <xsl:with-param name="buffer" select="$splitted[last()]/node()" />

     

       
69
       
69
       
-
       
        </xsl:call-template>

     

       
70
       
70
       
-
       
      </xsl:when>

     

       
71
       
71
       
-
       
      <!-- Either non-text node or one without $parbreak, which we just

     

       
72
       
72
       
-
       
           want to buffer and continue recursing. -->

     

       
73
       
73
       
-
       
      <xsl:when test="$input">

     

       
74
       
74
       
-
       
        <xsl:call-template name="break-up-description">

     

       
75
       
75
       
-
       
          <xsl:with-param name="input" select="$tail" />

     

       
76
       
76
       
-
       
          <!-- This essentially appends $head to $buffer. -->

     

       
77
       
77
       
-
       
          <xsl:with-param name="buffer">

     

       
78
       
78
       
-
       
            <xsl:if test="$buffer">

     

       
79
       
79
       
-
       
              <xsl:for-each select="exsl:node-set($buffer)">

     

       
80
       
80
       
-
       
                <xsl:apply-templates select="." />

     

       
81
       
81
       
-
       
              </xsl:for-each>

     

       
82
       
82
       
-
       
            </xsl:if>

     

       
83
       
83
       
-
       
            <xsl:apply-templates select="$head" />

     

       
84
       
84
       
-
       
          </xsl:with-param>

     

       
85
       
85
       
-
       
        </xsl:call-template>

     

       
86
       
86
       
-
       
      </xsl:when>

     

       
87
       
87
       
-
       
      <!-- No more $input, just put the remaining $buffer in a para. -->

     

       
88
       
88
       
-
       
      <xsl:otherwise>

     

       
89
       
89
       
-
       
        <para xmlns="http://docbook.org/ns/docbook">

     

       
90
       
90
       
-
       
          <xsl:apply-templates select="exsl:node-set($buffer)" />

     

       
91
       
91
       
-
       
        </para>

     

       
92
       
92
       
-
       
      </xsl:otherwise>

     

       
93
       
93
       
-
       
    </xsl:choose>

     

       
94
       
94
       
-
       
  </xsl:template>

     

       
95
       
95
       
-
       


     

       
96
       
96
       
-
       
  <xsl:template match="nixos:option-description">

     

       
97
       
97
       
-
       
    <xsl:choose>

     

       
98
       
98
       
-
       
      <!--

     

       
99
       
99
       
-
       
        Only process nodes that are comprised of a single <para/> element,

     

       
100
       
100
       
-
       
        because if that's not the case the description already contains

     

       
101
       
101
       
-
       
        </para><para> in between and we need no further processing.

     

       
102
       
102
       
-
       
      -->

     

       
103
       
103
       
-
       
      <xsl:when test="count(db:para) > 1">

     

       
104
       
104
       
-
       
        <xsl:apply-templates select="node()" />

     

       
105
       
105
       
-
       
      </xsl:when>

     

       
106
       
106
       
-
       
      <xsl:otherwise>

     

       
107
       
107
       
-
       
        <xsl:call-template name="break-up-description">

     

       
108
       
108
       
-
       
          <xsl:with-param name="input"

     

       
109
       
109
       
-
       
                          select="exsl:node-set(db:para/node())" />

     

       
110
       
110
       
-
       
        </xsl:call-template>

     

       
111
       
111
       
-
       
      </xsl:otherwise>

     

       
112
       
112
       
-
       
    </xsl:choose>

     

       
113
       
113
       
-
       
  </xsl:template>

     

       
114
       
114
       
-
       


     

       
115
       
115
       
-
       
</xsl:stylesheet>

     

···

       
107
       
107
       
 
       
            } >&2

     

       
108
       
108
       
 
       
        '';

     

       
109
       
109
       
 
       


     

       
110
       
110
       
-
       
    inherit (cfg.nixos.options) warningsAreErrors allowDocBook;

     

       
110
       
110
       
+
       
    inherit (cfg.nixos.options) warningsAreErrors;

     

       
111
       
111
       
 
       
  };

     

       
112
       
112
       
 
       


     

       
113
       
113
       
 
       


     
···

       
160
       
160
       
 
       
    (mkRenamedOptionModule [ "programs" "info" "enable" ] [ "documentation" "info" "enable" ])

     

       
161
       
161
       
 
       
    (mkRenamedOptionModule [ "programs" "man"  "enable" ] [ "documentation" "man"  "enable" ])

     

       
162
       
162
       
 
       
    (mkRenamedOptionModule [ "services" "nixosManual" "enable" ] [ "documentation" "nixos" "enable" ])

     

       
163
       
163
       
+
       
    (mkRemovedOptionModule

     

       
164
       
164
       
+
       
      [ "documentation" "nixos" "options" "allowDocBook" ]

     

       
165
       
165
       
+
       
      "DocBook option documentation is no longer supported")

     

       
163
       
166
       
 
       
  ];

     

       
164
       
167
       
 
       


     

       
165
       
168
       
 
       
  options = {

     
···

       
264
       
267
       
 
       
        '';

     

       
265
       
268
       
 
       
      };

     

       
266
       
269
       
 
       


     

       
267
       
267
       
-
       
      nixos.options.allowDocBook = mkOption {

     

       
268
       
268
       
-
       
        type = types.bool;

     

       
269
       
269
       
-
       
        default = true;

     

       
270
       
270
       
-
       
        description = lib.mdDoc ''

     

       
271
       
271
       
-
       
          Whether to allow DocBook option docs. When set to `false` all option using

     

       
272
       
272
       
-
       
          DocBook documentation will cause a manual build error; additionally a new

     

       
273
       
273
       
-
       
          renderer may be used.

     

       
274
       
274
       
-
       


     

       
275
       
275
       
-
       
          ::: {.note}

     

       
276
       
276
       
-
       
          The `false` setting for this option is not yet fully supported. While it

     

       
277
       
277
       
-
       
          should work fine and produce the same output as the previous toolchain

     

       
278
       
278
       
-
       
          using DocBook it may not work in all circumstances. Whether markdown option

     

       
279
       
279
       
-
       
          documentation is allowed is independent of this option.

     

       
280
       
280
       
-
       
          :::

     

       
281
       
281
       
-
       
        '';

     

       
282
       
282
       
-
       
      };

     

       
283
       
283
       
-
       


     

       
284
       
270
       
 
       
      nixos.options.warningsAreErrors = mkOption {

     

       
285
       
271
       
 
       
        type = types.bool;

     

       
286
       
272
       
 
       
        default = true;

     
···

       
358
       
344
       
 
       


     

       
359
       
345
       
 
       
    (mkIf cfg.nixos.enable {

     

       
360
       
346
       
 
       
      system.build.manual = manual;

     

       
361
       
361
       
-
       


     

       
362
       
362
       
-
       
      system.activationScripts.check-manual-docbook = ''

     

       
363
       
363
       
-
       
        if [[ $(cat ${manual.optionsUsedDocbook}) = 1 ]]; then

     

       
364
       
364
       
-
       
          echo -e "\e[31;1mwarning\e[0m: This configuration contains option documentation in docbook." \

     

       
365
       
365
       
-
       
                  "Support for docbook is deprecated and will be removed after NixOS 23.05." \

     

       
366
       
366
       
-
       
                  "See nix-store --read-log ${builtins.unsafeDiscardStringContext manual.optionsJSON.drvPath}"

     

       
367
       
367
       
-
       
        fi

     

       
368
       
368
       
-
       
      '';

     

       
369
       
347
       
 
       


     

       
370
       
348
       
 
       
      environment.systemPackages = []

     

       
371
       
349
       
 
       
        ++ optional cfg.man.enable manual.manpages

     

···

       
1
       
1
       
-
       
{ lib, stdenv, substituteAll, fetchurl, fetchpatch, findXMLCatalogs, writeScriptBin, ruby, bash, withManOptDedupPatch ? false }:

     

       
1
       
1
       
+
       
{ lib, stdenv, substituteAll, fetchurl, fetchpatch, findXMLCatalogs, writeScriptBin, ruby, bash }:

     

       
2
       
2
       
 
       


     

       
3
       
3
       
 
       
let

     

       
4
       
4
       
 
       


     
···

       
36
       
36
       
 
       
          src = ./catalog-legacy-uris.patch;

     

       
37
       
37
       
 
       
          inherit legacySuffix suffix version;

     

       
38
       
38
       
 
       
        })

     

       
39
       
39
       
-
       
      ] ++ lib.optionals withManOptDedupPatch [

     

       
40
       
40
       
-
       
        # Fixes https://github.com/NixOS/nixpkgs/issues/166304

     

       
41
       
41
       
-
       
        # https://github.com/docbook/xslt10-stylesheets/pull/241

     

       
42
       
42
       
-
       
        ./fix-man-options-duplication.patch

     

       
43
       
39
       
 
       
      ];

     

       
44
       
40
       
 
       


     

       
45
       
41
       
 
       
      propagatedBuildInputs = [ findXMLCatalogs ];

     

···

       
1
       
1
       
-
       
--- a/manpages/lists.xsl

     

       
2
       
2
       
-
       
+++ b/manpages/lists.xsl

     

       
3
       
3
       
-
       
@@ -110,7 +110,7 @@

     

       
4
       
4
       
-
       
   <xsl:text>.RE&#10;</xsl:text>

     

       
5
       
5
       
-
       
 </xsl:template>

     

       
6
       
6
       
-
       
 

     

       
7
       
7
       
-
       
-<xsl:template match="d:varlistentry/d:term"/>

     

       
8
       
8
       
-
       
+<xsl:template match="d:varlistentry/d:term" priority="1"/>

     

       
9
       
9
       
-
       
 <xsl:template match="d:glossentry/d:glossterm"/>

     

       
10
       
10
       
-
       
 

     

       
11
       
11
       
-
       
 <xsl:template match="d:variablelist[ancestor::d:listitem or ancestor::d:step or ancestor::d:glossdef]|

     

···

       
207
       
207
       
 
       
                raise RuntimeError(f"rendering {path}") from e

     

       
208
       
208
       
 
       
        return "".join(result)

     

       
209
       
209
       
 
       
    def included_options(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
210
       
210
       
-
       
        conv = options.DocBookConverter(self._manpage_urls, self._revision, False, 'fragment',

     

       
210
       
210
       
+
       
        conv = options.DocBookConverter(self._manpage_urls, self._revision, 'fragment',

     

       
211
       
211
       
 
       
                                        token.meta['list-id'], token.meta['id-prefix'])

     

       
212
       
212
       
 
       
        conv.add_options(token.meta['source'])

     

       
213
       
213
       
 
       
        return conv.finalize(fragment=True)

     
···

       
469
       
469
       
 
       
        return "".join(outer)

     

       
470
       
470
       
 
       


     

       
471
       
471
       
 
       
    def included_options(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
472
       
472
       
-
       
        conv = options.HTMLConverter(self._manpage_urls, self._revision, False,

     

       
472
       
472
       
+
       
        conv = options.HTMLConverter(self._manpage_urls, self._revision,

     

       
473
       
473
       
 
       
                                     token.meta['list-id'], token.meta['id-prefix'],

     

       
474
       
474
       
 
       
                                     self._xref_targets)

     

       
475
       
475
       
 
       
        conv.add_options(token.meta['source'])

     

···

       
37
       
37
       
 
       


     

       
38
       
38
       
 
       
    _options: dict[str, RenderedOption]

     

       
39
       
39
       
 
       


     

       
40
       
40
       
-
       
    def __init__(self, revision: str, markdown_by_default: bool):

     

       
40
       
40
       
+
       
    def __init__(self, revision: str):

     

       
41
       
41
       
 
       
        super().__init__()

     

       
42
       
42
       
 
       
        self._options = {}

     

       
43
       
43
       
 
       
        self._revision = revision

     

       
44
       
44
       
-
       
        self._markdown_by_default = markdown_by_default

     

       
45
       
44
       
 
       


     

       
46
       
45
       
 
       
    def _sorted_options(self) -> list[tuple[str, RenderedOption]]:

     

       
47
       
46
       
 
       
        keys = list(self._options.keys())

     
···

       
106
       
105
       
 
       
            return []

     

       
107
       
106
       
 
       


     

       
108
       
107
       
 
       
    def _render_description(self, desc: str | dict[str, str]) -> list[str]:

     

       
109
       
109
       
-
       
        if isinstance(desc, str) and self._markdown_by_default:

     

       
108
       
108
       
+
       
        if isinstance(desc, str):

     

       
110
       
109
       
 
       
            return [ self._render(desc) ] if desc else []

     

       
111
       
110
       
 
       
        elif isinstance(desc, dict) and desc.get('_type') == 'mdDoc':

     

       
112
       
111
       
 
       
            return [ self._render(desc['text']) ] if desc['text'] else []

     
···

       
198
       
197
       
 
       


     

       
199
       
198
       
 
       
    def __init__(self, manpage_urls: Mapping[str, str],

     

       
200
       
199
       
 
       
                 revision: str,

     

       
201
       
201
       
-
       
                 markdown_by_default: bool,

     

       
202
       
200
       
 
       
                 document_type: str,

     

       
203
       
201
       
 
       
                 varlist_id: str,

     

       
204
       
202
       
 
       
                 id_prefix: str):

     

       
205
       
205
       
-
       
        super().__init__(revision, markdown_by_default)

     

       
203
       
203
       
+
       
        super().__init__(revision)

     

       
206
       
204
       
 
       
        self._renderer = OptionsDocBookRenderer(manpage_urls)

     

       
207
       
205
       
 
       
        self._document_type = document_type

     

       
208
       
206
       
 
       
        self._varlist_id = varlist_id

     

       
209
       
207
       
 
       
        self._id_prefix = id_prefix

     

       
210
       
208
       
 
       


     

       
211
       
209
       
 
       
    def _parallel_render_prepare(self) -> Any:

     

       
212
       
212
       
-
       
        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default, self._document_type,

     

       
210
       
210
       
+
       
        return (self._renderer._manpage_urls, self._revision, self._document_type,

     

       
213
       
211
       
 
       
                self._varlist_id, self._id_prefix)

     

       
214
       
212
       
 
       
    @classmethod

     

       
215
       
213
       
 
       
    def _parallel_render_init_worker(cls, a: Any) -> DocBookConverter:

     

       
216
       
214
       
 
       
        return cls(*a)

     

       
217
       
215
       
 
       


     

       
218
       
218
       
-
       
    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:

     

       
219
       
219
       
-
       
        if lit := option_is(option, key, 'literalDocBook'):

     

       
220
       
220
       
-
       
            return [ f"<para><emphasis>{key.capitalize()}:</emphasis> {lit['text']}</para>" ]

     

       
221
       
221
       
-
       
        else:

     

       
222
       
222
       
-
       
            return super()._render_code(option, key)

     

       
223
       
223
       
-
       


     

       
224
       
224
       
-
       
    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:

     

       
225
       
225
       
-
       
        if isinstance(desc, str) and not self._markdown_by_default:

     

       
226
       
226
       
-
       
            return [ f"<nixos:option-description><para>{desc}</para></nixos:option-description>" ]

     

       
227
       
227
       
-
       
        else:

     

       
228
       
228
       
-
       
            return super()._render_description(desc)

     

       
229
       
229
       
-
       


     

       
230
       
216
       
 
       
    def _related_packages_header(self) -> list[str]:

     

       
231
       
217
       
 
       
        return [

     

       
232
       
218
       
 
       
            "<para>",

     
···

       
300
       
286
       
 
       
    _options_by_id: dict[str, str]

     

       
301
       
287
       
 
       
    _links_in_last_description: Optional[list[str]] = None

     

       
302
       
288
       
 
       


     

       
303
       
303
       
-
       
    def __init__(self, revision: str, markdown_by_default: bool,

     

       
289
       
289
       
+
       
    def __init__(self, revision: str,

     

       
304
       
290
       
 
       
                 *,

     

       
305
       
291
       
 
       
                 # only for parallel rendering

     

       
306
       
292
       
 
       
                 _options_by_id: Optional[dict[str, str]] = None):

     

       
307
       
307
       
-
       
        super().__init__(revision, markdown_by_default)

     

       
293
       
293
       
+
       
        super().__init__(revision)

     

       
308
       
294
       
 
       
        self._options_by_id = _options_by_id or {}

     

       
309
       
295
       
 
       
        self._renderer = OptionsManpageRenderer({}, self._options_by_id)

     

       
310
       
296
       
 
       


     

       
311
       
297
       
 
       
    def _parallel_render_prepare(self) -> Any:

     

       
312
       
312
       
-
       
        return ((self._revision, self._markdown_by_default), { '_options_by_id': self._options_by_id })

     

       
298
       
298
       
+
       
        return (self._revision, { '_options_by_id': self._options_by_id })

     

       
313
       
299
       
 
       
    @classmethod

     

       
314
       
300
       
 
       
    def _parallel_render_init_worker(cls, a: Any) -> ManpageConverter:

     

       
315
       
315
       
-
       
        return cls(*a[0], **a[1])

     

       
301
       
301
       
+
       
        return cls(a[0], **a[1])

     

       
316
       
302
       
 
       


     

       
317
       
303
       
 
       
    def _render_option(self, name: str, option: dict[str, Any]) -> RenderedOption:

     

       
318
       
304
       
 
       
        links = self._renderer.link_footnotes = []

     
···

       
326
       
312
       
 
       
        return super().add_options(options)

     

       
327
       
313
       
 
       


     

       
328
       
314
       
 
       
    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:

     

       
329
       
329
       
-
       
        if lit := option_is(option, key, 'literalDocBook'):

     

       
330
       
330
       
-
       
            raise RuntimeError("can't render manpages in the presence of docbook")

     

       
331
       
331
       
-
       
        else:

     

       
332
       
332
       
-
       
            try:

     

       
333
       
333
       
-
       
                self._renderer.inline_code_is_quoted = False

     

       
334
       
334
       
-
       
                return super()._render_code(option, key)

     

       
335
       
335
       
-
       
            finally:

     

       
336
       
336
       
-
       
                self._renderer.inline_code_is_quoted = True

     

       
337
       
337
       
-
       


     

       
338
       
338
       
-
       
    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:

     

       
339
       
339
       
-
       
        if isinstance(desc, str) and not self._markdown_by_default:

     

       
340
       
340
       
-
       
            raise RuntimeError("can't render manpages in the presence of docbook")

     

       
341
       
341
       
-
       
        else:

     

       
342
       
342
       
-
       
            return super()._render_description(desc)

     

       
315
       
315
       
+
       
        try:

     

       
316
       
316
       
+
       
            self._renderer.inline_code_is_quoted = False

     

       
317
       
317
       
+
       
            return super()._render_code(option, key)

     

       
318
       
318
       
+
       
        finally:

     

       
319
       
319
       
+
       
            self._renderer.inline_code_is_quoted = True

     

       
343
       
320
       
 
       


     

       
344
       
321
       
 
       
    def _related_packages_header(self) -> list[str]:

     

       
345
       
322
       
 
       
        return [

     
···

       
420
       
397
       
 
       
class CommonMarkConverter(BaseConverter[OptionsCommonMarkRenderer]):

     

       
421
       
398
       
 
       
    __option_block_separator__ = ""

     

       
422
       
399
       
 
       


     

       
423
       
423
       
-
       
    def __init__(self, manpage_urls: Mapping[str, str], revision: str, markdown_by_default: bool):

     

       
424
       
424
       
-
       
        super().__init__(revision, markdown_by_default)

     

       
400
       
400
       
+
       
    def __init__(self, manpage_urls: Mapping[str, str], revision: str):

     

       
401
       
401
       
+
       
        super().__init__(revision)

     

       
425
       
402
       
 
       
        self._renderer = OptionsCommonMarkRenderer(manpage_urls)

     

       
426
       
403
       
 
       


     

       
427
       
404
       
 
       
    def _parallel_render_prepare(self) -> Any:

     

       
428
       
428
       
-
       
        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default)

     

       
405
       
405
       
+
       
        return (self._renderer._manpage_urls, self._revision)

     

       
429
       
406
       
 
       
    @classmethod

     

       
430
       
407
       
 
       
    def _parallel_render_init_worker(cls, a: Any) -> CommonMarkConverter:

     

       
431
       
408
       
 
       
        return cls(*a)

     

       
432
       
409
       
 
       


     

       
433
       
433
       
-
       
    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:

     

       
434
       
434
       
-
       
        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat

     

       
435
       
435
       
-
       
        # incorrect, since users rely on it.

     

       
436
       
436
       
-
       
        if lit := option_is(option, key, 'literalDocBook'):

     

       
437
       
437
       
-
       
            return [ f"*{key.capitalize()}:* {lit['text']}" ]

     

       
438
       
438
       
-
       
        else:

     

       
439
       
439
       
-
       
            return super()._render_code(option, key)

     

       
440
       
440
       
-
       


     

       
441
       
441
       
-
       
    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:

     

       
442
       
442
       
-
       
        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat

     

       
443
       
443
       
-
       
        # incorrect, since users rely on it.

     

       
444
       
444
       
-
       
        if isinstance(desc, str) and not self._markdown_by_default:

     

       
445
       
445
       
-
       
            return [ desc ]

     

       
446
       
446
       
-
       
        else:

     

       
447
       
447
       
-
       
            return super()._render_description(desc)

     

       
448
       
448
       
-
       


     

       
449
       
410
       
 
       
    def _related_packages_header(self) -> list[str]:

     

       
450
       
411
       
 
       
        return [ "*Related packages:*" ]

     

       
451
       
412
       
 
       


     
···

       
476
       
437
       
 
       
class AsciiDocConverter(BaseConverter[OptionsAsciiDocRenderer]):

     

       
477
       
438
       
 
       
    __option_block_separator__ = ""

     

       
478
       
439
       
 
       


     

       
479
       
479
       
-
       
    def __init__(self, manpage_urls: Mapping[str, str], revision: str, markdown_by_default: bool):

     

       
480
       
480
       
-
       
        super().__init__(revision, markdown_by_default)

     

       
440
       
440
       
+
       
    def __init__(self, manpage_urls: Mapping[str, str], revision: str):

     

       
441
       
441
       
+
       
        super().__init__(revision)

     

       
481
       
442
       
 
       
        self._renderer = OptionsAsciiDocRenderer(manpage_urls)

     

       
482
       
443
       
 
       


     

       
483
       
444
       
 
       
    def _parallel_render_prepare(self) -> Any:

     

       
484
       
484
       
-
       
        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default)

     

       
445
       
445
       
+
       
        return (self._renderer._manpage_urls, self._revision)

     

       
485
       
446
       
 
       
    @classmethod

     

       
486
       
447
       
 
       
    def _parallel_render_init_worker(cls, a: Any) -> AsciiDocConverter:

     

       
487
       
448
       
 
       
        return cls(*a)

     

       
488
       
449
       
 
       


     

       
489
       
489
       
-
       
    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:

     

       
490
       
490
       
-
       
        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat

     

       
491
       
491
       
-
       
        # incorrect, since users rely on it.

     

       
492
       
492
       
-
       
        if lit := option_is(option, key, 'literalDocBook'):

     

       
493
       
493
       
-
       
            return [ f"*{key.capitalize()}:* {lit['text']}" ]

     

       
494
       
494
       
-
       
        else:

     

       
495
       
495
       
-
       
            return super()._render_code(option, key)

     

       
496
       
496
       
-
       


     

       
497
       
497
       
-
       
    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:

     

       
498
       
498
       
-
       
        # NOTE this duplicates the old direct-paste behavior, even if it is somewhat

     

       
499
       
499
       
-
       
        # incorrect, since users rely on it.

     

       
500
       
500
       
-
       
        if isinstance(desc, str) and not self._markdown_by_default:

     

       
501
       
501
       
-
       
            return [ desc ]

     

       
502
       
502
       
-
       
        else:

     

       
503
       
503
       
-
       
            return super()._render_description(desc)

     

       
504
       
504
       
-
       


     

       
505
       
450
       
 
       
    def _related_packages_header(self) -> list[str]:

     

       
506
       
451
       
 
       
        return [ "__Related packages:__" ]

     

       
507
       
452
       
 
       


     
···

       
541
       
486
       
 
       
class HTMLConverter(BaseConverter[OptionsHTMLRenderer]):

     

       
542
       
487
       
 
       
    __option_block_separator__ = ""

     

       
543
       
488
       
 
       


     

       
544
       
544
       
-
       
    def __init__(self, manpage_urls: Mapping[str, str], revision: str, markdown_by_default: bool,

     

       
489
       
489
       
+
       
    def __init__(self, manpage_urls: Mapping[str, str], revision: str,

     

       
545
       
490
       
 
       
                 varlist_id: str, id_prefix: str, xref_targets: Mapping[str, XrefTarget]):

     

       
546
       
546
       
-
       
        super().__init__(revision, markdown_by_default)

     

       
491
       
491
       
+
       
        super().__init__(revision)

     

       
547
       
492
       
 
       
        self._xref_targets = xref_targets

     

       
548
       
493
       
 
       
        self._varlist_id = varlist_id

     

       
549
       
494
       
 
       
        self._id_prefix = id_prefix

     

       
550
       
495
       
 
       
        self._renderer = OptionsHTMLRenderer(manpage_urls, self._xref_targets)

     

       
551
       
496
       
 
       


     

       
552
       
497
       
 
       
    def _parallel_render_prepare(self) -> Any:

     

       
553
       
553
       
-
       
        return (self._renderer._manpage_urls, self._revision, self._markdown_by_default,

     

       
498
       
498
       
+
       
        return (self._renderer._manpage_urls, self._revision,

     

       
554
       
499
       
 
       
                self._varlist_id, self._id_prefix, self._xref_targets)

     

       
555
       
500
       
 
       
    @classmethod

     

       
556
       
501
       
 
       
    def _parallel_render_init_worker(cls, a: Any) -> HTMLConverter:

     

       
557
       
502
       
 
       
        return cls(*a)

     

       
558
       
503
       
 
       


     

       
559
       
559
       
-
       
    def _render_code(self, option: dict[str, Any], key: str) -> list[str]:

     

       
560
       
560
       
-
       
        if lit := option_is(option, key, 'literalDocBook'):

     

       
561
       
561
       
-
       
            raise RuntimeError("can't render html in the presence of docbook")

     

       
562
       
562
       
-
       
        else:

     

       
563
       
563
       
-
       
            return super()._render_code(option, key)

     

       
564
       
564
       
-
       


     

       
565
       
565
       
-
       
    def _render_description(self, desc: str | dict[str, Any]) -> list[str]:

     

       
566
       
566
       
-
       
        if isinstance(desc, str) and not self._markdown_by_default:

     

       
567
       
567
       
-
       
            raise RuntimeError("can't render html in the presence of docbook")

     

       
568
       
568
       
-
       
        else:

     

       
569
       
569
       
-
       
            return super()._render_description(desc)

     

       
570
       
570
       
-
       


     

       
571
       
504
       
 
       
    def _related_packages_header(self) -> list[str]:

     

       
572
       
505
       
 
       
        return [

     

       
573
       
506
       
 
       
            '<p><span class="emphasis"><em>Related packages:</em></span></p>',

     
···

       
635
       
568
       
 
       
    p.add_argument('--document-type', required=True)

     

       
636
       
569
       
 
       
    p.add_argument('--varlist-id', required=True)

     

       
637
       
570
       
 
       
    p.add_argument('--id-prefix', required=True)

     

       
638
       
638
       
-
       
    p.add_argument('--markdown-by-default', default=False, action='store_true')

     

       
639
       
571
       
 
       
    p.add_argument("infile")

     

       
640
       
572
       
 
       
    p.add_argument("outfile")

     

       
641
       
573
       
 
       


     
···

       
647
       
579
       
 
       
def _build_cli_commonmark(p: argparse.ArgumentParser) -> None:

     

       
648
       
580
       
 
       
    p.add_argument('--manpage-urls', required=True)

     

       
649
       
581
       
 
       
    p.add_argument('--revision', required=True)

     

       
650
       
650
       
-
       
    p.add_argument('--markdown-by-default', default=False, action='store_true')

     

       
651
       
582
       
 
       
    p.add_argument("infile")

     

       
652
       
583
       
 
       
    p.add_argument("outfile")

     

       
653
       
584
       
 
       


     

       
654
       
585
       
 
       
def _build_cli_asciidoc(p: argparse.ArgumentParser) -> None:

     

       
655
       
586
       
 
       
    p.add_argument('--manpage-urls', required=True)

     

       
656
       
587
       
 
       
    p.add_argument('--revision', required=True)

     

       
657
       
657
       
-
       
    p.add_argument('--markdown-by-default', default=False, action='store_true')

     

       
658
       
588
       
 
       
    p.add_argument("infile")

     

       
659
       
589
       
 
       
    p.add_argument("outfile")

     

       
660
       
590
       
 
       


     
···

       
663
       
593
       
 
       
        md = DocBookConverter(

     

       
664
       
594
       
 
       
            json.load(manpage_urls),

     

       
665
       
595
       
 
       
            revision = args.revision,

     

       
666
       
666
       
-
       
            markdown_by_default = args.markdown_by_default,

     

       
667
       
596
       
 
       
            document_type = args.document_type,

     

       
668
       
597
       
 
       
            varlist_id = args.varlist_id,

     

       
669
       
598
       
 
       
            id_prefix = args.id_prefix)

     
···

       
674
       
603
       
 
       
            f.write(md.finalize())

     

       
675
       
604
       
 
       


     

       
676
       
605
       
 
       
def _run_cli_manpage(args: argparse.Namespace) -> None:

     

       
677
       
677
       
-
       
    md = ManpageConverter(

     

       
678
       
678
       
-
       
        revision = args.revision,

     

       
679
       
679
       
-
       
        # manpage rendering only works if there's no docbook, so we can

     

       
680
       
680
       
-
       
        # also set markdown_by_default with no ill effects.

     

       
681
       
681
       
-
       
        markdown_by_default = True)

     

       
606
       
606
       
+
       
    md = ManpageConverter(revision = args.revision)

     

       
682
       
607
       
 
       


     

       
683
       
608
       
 
       
    with open(args.infile, 'r') as f:

     

       
684
       
609
       
 
       
        md.add_options(json.load(f))

     
···

       
687
       
612
       
 
       


     

       
688
       
613
       
 
       
def _run_cli_commonmark(args: argparse.Namespace) -> None:

     

       
689
       
614
       
 
       
    with open(args.manpage_urls, 'r') as manpage_urls:

     

       
690
       
690
       
-
       
        md = CommonMarkConverter(

     

       
691
       
691
       
-
       
            json.load(manpage_urls),

     

       
692
       
692
       
-
       
            revision = args.revision,

     

       
693
       
693
       
-
       
            markdown_by_default = args.markdown_by_default)

     

       
615
       
615
       
+
       
        md = CommonMarkConverter(json.load(manpage_urls), revision = args.revision)

     

       
694
       
616
       
 
       


     

       
695
       
617
       
 
       
        with open(args.infile, 'r') as f:

     

       
696
       
618
       
 
       
            md.add_options(json.load(f))

     
···

       
699
       
621
       
 
       


     

       
700
       
622
       
 
       
def _run_cli_asciidoc(args: argparse.Namespace) -> None:

     

       
701
       
623
       
 
       
    with open(args.manpage_urls, 'r') as manpage_urls:

     

       
702
       
702
       
-
       
        md = AsciiDocConverter(

     

       
703
       
703
       
-
       
            json.load(manpage_urls),

     

       
704
       
704
       
-
       
            revision = args.revision,

     

       
705
       
705
       
-
       
            markdown_by_default = args.markdown_by_default)

     

       
624
       
624
       
+
       
        md = AsciiDocConverter(json.load(manpage_urls), revision = args.revision)

     

       
706
       
625
       
 
       


     

       
707
       
626
       
 
       
        with open(args.infile, 'r') as f:

     

       
708
       
627
       
 
       
            md.add_options(json.load(f))