···

       
21
       
21
       
 
       
approach, containers are configured and updated independently from the

     

       
22
       
22
       
 
       
host system.

     

       
23
       
23
       
 
       


     

       
24
       
24
       
-
       
```{=docbook}

     

       
25
       
25
       
-
       
<xi:include href="imperative-containers.section.xml" />

     

       
26
       
26
       
-
       
<xi:include href="declarative-containers.section.xml" />

     

       
27
       
27
       
-
       
<xi:include href="container-networking.section.xml" />

     

       
24
       
24
       
+
       
```{=include=} sections

     

       
25
       
25
       
+
       
imperative-containers.section.md

     

       
26
       
26
       
+
       
declarative-containers.section.md

     

       
27
       
27
       
+
       
container-networking.section.md

     

       
28
       
28
       
 
       
```

     

···

       
1
       
1
       
+
       
# Administration {#ch-running}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This chapter describes various aspects of managing a running NixOS system, such as how to use the {command}`systemd` service manager.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} chapters

     

       
6
       
6
       
+
       
service-mgmt.chapter.md

     

       
7
       
7
       
+
       
rebooting.chapter.md

     

       
8
       
8
       
+
       
user-sessions.chapter.md

     

       
9
       
9
       
+
       
control-groups.chapter.md

     

       
10
       
10
       
+
       
logging.chapter.md

     

       
11
       
11
       
+
       
cleaning-store.chapter.md

     

       
12
       
12
       
+
       
containers.chapter.md

     

       
13
       
13
       
+
       
troubleshooting.chapter.md

     

       
14
       
14
       
+
       
```

     

···

       
1
       
1
       
-
       
<part 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
       
-
       
      version="5.0"

     

       
5
       
5
       
-
       
      xml:id="ch-running">

     

       
6
       
6
       
-
       
 <title>Administration</title>

     

       
7
       
7
       
-
       
 <partintro xml:id="ch-running-intro">

     

       
8
       
8
       
-
       
  <para>

     

       
9
       
9
       
-
       
   This chapter describes various aspects of managing a running NixOS system,

     

       
10
       
10
       
-
       
   such as how to use the <command>systemd</command> service manager.

     

       
11
       
11
       
-
       
  </para>

     

       
12
       
12
       
-
       
 </partintro>

     

       
13
       
13
       
-
       
 <xi:include href="../from_md/administration/service-mgmt.chapter.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="../from_md/administration/rebooting.chapter.xml" />

     

       
15
       
15
       
-
       
 <xi:include href="../from_md/administration/user-sessions.chapter.xml" />

     

       
16
       
16
       
-
       
 <xi:include href="../from_md/administration/control-groups.chapter.xml" />

     

       
17
       
17
       
-
       
 <xi:include href="../from_md/administration/logging.chapter.xml" />

     

       
18
       
18
       
-
       
 <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />

     

       
19
       
19
       
-
       
 <xi:include href="../from_md/administration/containers.chapter.xml" />

     

       
20
       
20
       
-
       
 <xi:include href="../from_md/administration/troubleshooting.chapter.xml" />

     

       
21
       
21
       
-
       
</part>

     

···

       
3
       
3
       
 
       
This chapter describes solutions to common problems you might encounter

     

       
4
       
4
       
 
       
when you manage your NixOS system.

     

       
5
       
5
       
 
       


     

       
6
       
6
       
-
       
```{=docbook}

     

       
7
       
7
       
-
       
<xi:include href="boot-problems.section.xml" />

     

       
8
       
8
       
-
       
<xi:include href="maintenance-mode.section.xml" />

     

       
9
       
9
       
-
       
<xi:include href="rollback.section.xml" />

     

       
10
       
10
       
-
       
<xi:include href="store-corruption.section.xml" />

     

       
11
       
11
       
-
       
<xi:include href="network-problems.section.xml" />

     

       
6
       
6
       
+
       
```{=include=} sections

     

       
7
       
7
       
+
       
boot-problems.section.md

     

       
8
       
8
       
+
       
maintenance-mode.section.md

     

       
9
       
9
       
+
       
rollback.section.md

     

       
10
       
10
       
+
       
store-corruption.section.md

     

       
11
       
11
       
+
       
network-problems.section.md

     

       
12
       
12
       
 
       
```

     

···

       
11
       
11
       
 
       
here we give a short overview of the most important constructs useful in

     

       
12
       
12
       
 
       
NixOS configuration files.

     

       
13
       
13
       
 
       


     

       
14
       
14
       
-
       
```{=docbook}

     

       
15
       
15
       
-
       
<xi:include href="config-file.section.xml" />

     

       
16
       
16
       
-
       
<xi:include href="abstractions.section.xml" />

     

       
17
       
17
       
-
       
<xi:include href="modularity.section.xml" />

     

       
14
       
14
       
+
       
```{=include=} sections

     

       
15
       
15
       
+
       
config-file.section.md

     

       
16
       
16
       
+
       
abstractions.section.md

     

       
17
       
17
       
+
       
modularity.section.md

     

       
18
       
18
       
 
       
```

     

···

       
1
       
1
       
+
       
# Configuration {#ch-configuration}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This chapter describes how to configure various aspects of a NixOS machine through the configuration file {file}`/etc/nixos/configuration.nix`. As described in [](#sec-changing-config), changes to this file only take effect after you run {command}`nixos-rebuild`.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} chapters

     

       
6
       
6
       
+
       
config-syntax.chapter.md

     

       
7
       
7
       
+
       
package-mgmt.chapter.md

     

       
8
       
8
       
+
       
user-mgmt.chapter.md

     

       
9
       
9
       
+
       
file-systems.chapter.md

     

       
10
       
10
       
+
       
x-windows.chapter.md

     

       
11
       
11
       
+
       
wayland.chapter.md

     

       
12
       
12
       
+
       
gpu-accel.chapter.md

     

       
13
       
13
       
+
       
xfce.chapter.md

     

       
14
       
14
       
+
       
networking.chapter.md

     

       
15
       
15
       
+
       
linux-kernel.chapter.md

     

       
16
       
16
       
+
       
subversion.chapter.md

     

       
17
       
17
       
+
       
```

     

       
18
       
18
       
+
       


     

       
19
       
19
       
+
       
```{=include=} chapters

     

       
20
       
20
       
+
       
@MODULE_CHAPTERS@

     

       
21
       
21
       
+
       
```

     

       
22
       
22
       
+
       


     

       
23
       
23
       
+
       
```{=include=} chapters

     

       
24
       
24
       
+
       
profiles.chapter.md

     

       
25
       
25
       
+
       
kubernetes.chapter.md

     

       
26
       
26
       
+
       
```

     

       
27
       
27
       
+
       
<!-- Apache; libvirtd virtualisation -->

     

···

       
1
       
1
       
-
       
<part 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
       
-
       
      version="5.0"

     

       
5
       
5
       
-
       
      xml:id="ch-configuration">

     

       
6
       
6
       
-
       
 <title>Configuration</title>

     

       
7
       
7
       
-
       
 <partintro xml:id="ch-configuration-intro">

     

       
8
       
8
       
-
       
  <para>

     

       
9
       
9
       
-
       
   This chapter describes how to configure various aspects of a NixOS machine

     

       
10
       
10
       
-
       
   through the configuration file

     

       
11
       
11
       
-
       
   <filename>/etc/nixos/configuration.nix</filename>. As described in

     

       
12
       
12
       
-
       
   <xref linkend="sec-changing-config" />, changes to this file only take

     

       
13
       
13
       
-
       
   effect after you run <command>nixos-rebuild</command>.

     

       
14
       
14
       
-
       
  </para>

     

       
15
       
15
       
-
       
 </partintro>

     

       
16
       
16
       
-
       
 <xi:include href="../from_md/configuration/config-syntax.chapter.xml" />

     

       
17
       
17
       
-
       
 <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />

     

       
18
       
18
       
-
       
 <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />

     

       
19
       
19
       
-
       
 <xi:include href="../from_md/configuration/file-systems.chapter.xml" />

     

       
20
       
20
       
-
       
 <xi:include href="../from_md/configuration/x-windows.chapter.xml" />

     

       
21
       
21
       
-
       
 <xi:include href="../from_md/configuration/wayland.chapter.xml" />

     

       
22
       
22
       
-
       
 <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />

     

       
23
       
23
       
-
       
 <xi:include href="../from_md/configuration/xfce.chapter.xml" />

     

       
24
       
24
       
-
       
 <xi:include href="../from_md/configuration/networking.chapter.xml" />

     

       
25
       
25
       
-
       
 <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />

     

       
26
       
26
       
-
       
 <xi:include href="../from_md/configuration/subversion.chapter.xml" />

     

       
27
       
27
       
-
       
 <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />

     

       
28
       
28
       
-
       
 <xi:include href="../from_md/configuration/profiles.chapter.xml" />

     

       
29
       
29
       
-
       
 <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />

     

       
30
       
30
       
-
       
<!-- Apache; libvirtd virtualisation -->

     

       
31
       
31
       
-
       
</part>

     

···

       
40
       
40
       
 
       
To "uninstall" a package, simply remove it from

     

       
41
       
41
       
 
       
[](#opt-environment.systemPackages) and run `nixos-rebuild switch`.

     

       
42
       
42
       
 
       


     

       
43
       
43
       
-
       
```{=docbook}

     

       
44
       
44
       
-
       
<xi:include href="customizing-packages.section.xml" />

     

       
45
       
45
       
-
       
<xi:include href="adding-custom-packages.section.xml" />

     

       
43
       
43
       
+
       
```{=include=} sections

     

       
44
       
44
       
+
       
customizing-packages.section.md

     

       
45
       
45
       
+
       
adding-custom-packages.section.md

     

       
46
       
46
       
 
       
```

     

···

       
36
       
36
       
 
       
and non-critical by adding `options = [ "nofail" ];`.

     

       
37
       
37
       
 
       
:::

     

       
38
       
38
       
 
       


     

       
39
       
39
       
-
       
```{=docbook}

     

       
40
       
40
       
-
       
<xi:include href="luks-file-systems.section.xml" />

     

       
41
       
41
       
-
       
<xi:include href="sshfs-file-systems.section.xml" />

     

       
39
       
39
       
+
       
```{=include=} sections

     

       
40
       
40
       
+
       
luks-file-systems.section.md

     

       
41
       
41
       
+
       
sshfs-file-systems.section.md

     

       
42
       
42
       
 
       
```

     

···

       
3
       
3
       
 
       
This section describes how to configure networking components

     

       
4
       
4
       
 
       
on your NixOS machine.

     

       
5
       
5
       
 
       


     

       
6
       
6
       
-
       
```{=docbook}

     

       
7
       
7
       
-
       
<xi:include href="network-manager.section.xml" />

     

       
8
       
8
       
-
       
<xi:include href="ssh.section.xml" />

     

       
9
       
9
       
-
       
<xi:include href="ipv4-config.section.xml" />

     

       
10
       
10
       
-
       
<xi:include href="ipv6-config.section.xml" />

     

       
11
       
11
       
-
       
<xi:include href="firewall.section.xml" />

     

       
12
       
12
       
-
       
<xi:include href="wireless.section.xml" />

     

       
13
       
13
       
-
       
<xi:include href="ad-hoc-network-config.section.xml" />

     

       
14
       
14
       
-
       
<xi:include href="renaming-interfaces.section.xml" />

     

       
6
       
6
       
+
       
```{=include=} sections

     

       
7
       
7
       
+
       
network-manager.section.md

     

       
8
       
8
       
+
       
ssh.section.md

     

       
9
       
9
       
+
       
ipv4-config.section.md

     

       
10
       
10
       
+
       
ipv6-config.section.md

     

       
11
       
11
       
+
       
firewall.section.md

     

       
12
       
12
       
+
       
wireless.section.md

     

       
13
       
13
       
+
       
ad-hoc-network-config.section.md

     

       
14
       
14
       
+
       
renaming-interfaces.section.md

     

       
15
       
15
       
 
       
```

     

       
16
       
16
       
 
       
<!-- TODO: OpenVPN, NAT -->

     

···

       
12
       
12
       
 
       
    `nix-env` command. This style allows mixing packages from different

     

       
13
       
13
       
 
       
    Nixpkgs versions. It's the only choice for non-root users.

     

       
14
       
14
       
 
       


     

       
15
       
15
       
-
       
```{=docbook}

     

       
16
       
16
       
-
       
<xi:include href="declarative-packages.section.xml" />

     

       
17
       
17
       
-
       
<xi:include href="ad-hoc-packages.section.xml" />

     

       
15
       
15
       
+
       
```{=include=} sections

     

       
16
       
16
       
+
       
declarative-packages.section.md

     

       
17
       
17
       
+
       
ad-hoc-packages.section.md

     

       
18
       
18
       
 
       
```

     

···

       
19
       
19
       
 
       
What follows is a brief explanation on the purpose and use-case for each

     

       
20
       
20
       
 
       
profile. Detailing each option configured by each one is out of scope.

     

       
21
       
21
       
 
       


     

       
22
       
22
       
-
       
```{=docbook}

     

       
23
       
23
       
-
       
<xi:include href="profiles/all-hardware.section.xml" />

     

       
24
       
24
       
-
       
<xi:include href="profiles/base.section.xml" />

     

       
25
       
25
       
-
       
<xi:include href="profiles/clone-config.section.xml" />

     

       
26
       
26
       
-
       
<xi:include href="profiles/demo.section.xml" />

     

       
27
       
27
       
-
       
<xi:include href="profiles/docker-container.section.xml" />

     

       
28
       
28
       
-
       
<xi:include href="profiles/graphical.section.xml" />

     

       
29
       
29
       
-
       
<xi:include href="profiles/hardened.section.xml" />

     

       
30
       
30
       
-
       
<xi:include href="profiles/headless.section.xml" />

     

       
31
       
31
       
-
       
<xi:include href="profiles/installation-device.section.xml" />

     

       
32
       
32
       
-
       
<xi:include href="profiles/minimal.section.xml" />

     

       
33
       
33
       
-
       
<xi:include href="profiles/qemu-guest.section.xml" />

     

       
22
       
22
       
+
       
```{=include=} sections

     

       
23
       
23
       
+
       
profiles/all-hardware.section.md

     

       
24
       
24
       
+
       
profiles/base.section.md

     

       
25
       
25
       
+
       
profiles/clone-config.section.md

     

       
26
       
26
       
+
       
profiles/demo.section.md

     

       
27
       
27
       
+
       
profiles/docker-container.section.md

     

       
28
       
28
       
+
       
profiles/graphical.section.md

     

       
29
       
29
       
+
       
profiles/hardened.section.md

     

       
30
       
30
       
+
       
profiles/headless.section.md

     

       
31
       
31
       
+
       
profiles/installation-device.section.md

     

       
32
       
32
       
+
       
profiles/minimal.section.md

     

       
33
       
33
       
+
       
profiles/qemu-guest.section.md

     

       
34
       
34
       
 
       
```

     

···

       
143
       
143
       
 
       
    ''

     

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

     

       
145
       
145
       
 
       


     

       
146
       
146
       
-
       
      declare -a convert_args

     

       
147
       
147
       
-
       
      while read -r mf; do

     

       
148
       
148
       
-
       
        if [[ "$mf" = *.chapter.md ]]; then

     

       
149
       
149
       
-
       
          convert_args+=("--chapter")

     

       
150
       
150
       
-
       
        else

     

       
151
       
151
       
-
       
          convert_args+=("--section")

     

       
152
       
152
       
-
       
        fi

     

       
146
       
146
       
+
       
      substituteInPlace ./manual.md \

     

       
147
       
147
       
+
       
        --replace '@NIXOS_VERSION@' "${version}"

     

       
148
       
148
       
+
       
      substituteInPlace ./configuration/configuration.md \

     

       
149
       
149
       
+
       
        --replace \

     

       
150
       
150
       
+
       
            '@MODULE_CHAPTERS@' \

     

       
151
       
151
       
+
       
            ${lib.escapeShellArg (lib.concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}

     

       
152
       
152
       
+
       
      substituteInPlace ./nixos-options.md \

     

       
153
       
153
       
+
       
        --replace \

     

       
154
       
154
       
+
       
          '@NIXOS_OPTIONS_JSON@' \

     

       
155
       
155
       
+
       
          ${optionsDoc.optionsJSON}/share/doc/nixos/options.json

     

       
156
       
156
       
+
       
      substituteInPlace ./development/writing-nixos-tests.section.md \

     

       
157
       
157
       
+
       
        --replace \

     

       
158
       
158
       
+
       
          '@NIXOS_TEST_OPTIONS_JSON@' \

     

       
159
       
159
       
+
       
          ${testOptionsDoc.optionsJSON}/share/doc/nixos/options.json

     

       
153
       
160
       
 
       


     

       
154
       
154
       
-
       
        convert_args+=("from_md/''${mf%.md}.xml" "$mf")

     

       
155
       
155
       
-
       
      done < <(find . -type f -name '*.md')

     

       
156
       
156
       
-
       


     

       
157
       
157
       
-
       
      nixos-render-docs manual docbook-fragment \

     

       
161
       
161
       
+
       
      nixos-render-docs manual docbook \

     

       
158
       
162
       
 
       
        --manpage-urls ${manpageUrls} \

     

       
159
       
159
       
-
       
        "''${convert_args[@]}"

     

       
160
       
160
       
-
       


     

       
161
       
161
       
-
       
      mkdir ./generated

     

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

     

       
163
       
163
       
-
       
      ln -s ${testOptionsDoc.optionsDocBook} ./generated/test-options-db.xml

     

       
164
       
164
       
-
       
      printf "%s" "${version}" > ./generated/version

     

       
165
       
165
       
-
       
      chmod -R u+w .

     

       
166
       
166
       
-
       


     

       
167
       
167
       
-
       
      nixos-render-docs manual docbook-section \

     

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

     

       
169
       
169
       
-
       
        ./generated/modules.xml \

     

       
170
       
170
       
-
       
        --section \

     

       
171
       
171
       
-
       
          --section-id modules \

     

       
172
       
172
       
-
       
          --chapters ${lib.concatMapStrings (p: "${p.value} ") config.meta.doc}

     

       
173
       
173
       
-
       


     

       
174
       
174
       
-
       
      xmllint --xinclude --output ./manual-combined.xml ./manual.xml

     

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

     

       
164
       
164
       
+
       
        ./manual.md \

     

       
165
       
165
       
+
       
        ./manual-combined.xml

     

       
175
       
166
       
 
       


     

       
176
       
167
       
 
       
      ${linterFunctions}

     

       
177
       
168
       
 
       


     

···

       
1
       
1
       
+
       
# Development {#ch-development}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This chapter describes how you can modify and extend NixOS.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} chapters

     

       
6
       
6
       
+
       
sources.chapter.md

     

       
7
       
7
       
+
       
writing-modules.chapter.md

     

       
8
       
8
       
+
       
building-parts.chapter.md

     

       
9
       
9
       
+
       
bootspec.chapter.md

     

       
10
       
10
       
+
       
what-happens-during-a-system-switch.chapter.md

     

       
11
       
11
       
+
       
writing-documentation.chapter.md

     

       
12
       
12
       
+
       
nixos-tests.chapter.md

     

       
13
       
13
       
+
       
testing-installer.chapter.md

     

       
14
       
14
       
+
       
```

     

···

       
1
       
1
       
-
       
<part   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
       
-
       
        version="5.0"

     

       
5
       
5
       
-
       
        xml:id="ch-development">

     

       
6
       
6
       
-
       
 <title>Development</title>

     

       
7
       
7
       
-
       
 <partintro xml:id="ch-development-intro">

     

       
8
       
8
       
-
       
  <para>

     

       
9
       
9
       
-
       
   This chapter describes how you can modify and extend NixOS.

     

       
10
       
10
       
-
       
  </para>

     

       
11
       
11
       
-
       
 </partintro>

     

       
12
       
12
       
-
       
 <xi:include href="../from_md/development/sources.chapter.xml" />

     

       
13
       
13
       
-
       
 <xi:include href="../from_md/development/writing-modules.chapter.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="../from_md/development/building-parts.chapter.xml" />

     

       
15
       
15
       
-
       
 <xi:include href="../from_md/development/bootspec.chapter.xml" />

     

       
16
       
16
       
-
       
 <xi:include href="../from_md/development/what-happens-during-a-system-switch.chapter.xml" />

     

       
17
       
17
       
-
       
 <xi:include href="../from_md/development/writing-documentation.chapter.xml" />

     

       
18
       
18
       
-
       
 <xi:include href="../from_md/development/nixos-tests.chapter.xml" />

     

       
19
       
19
       
-
       
 <xi:include href="../from_md/development/testing-installer.chapter.xml" />

     

       
20
       
20
       
-
       
</part>

     

···

       
5
       
5
       
 
       
(using Nix) by a testing framework that automatically starts one or more

     

       
6
       
6
       
 
       
virtual machines containing the NixOS system(s) required for the test.

     

       
7
       
7
       
 
       


     

       
8
       
8
       
-
       
```{=docbook}

     

       
9
       
9
       
-
       
<xi:include href="writing-nixos-tests.section.xml" />

     

       
10
       
10
       
-
       
<xi:include href="running-nixos-tests.section.xml" />

     

       
11
       
11
       
-
       
<xi:include href="running-nixos-tests-interactively.section.xml" />

     

       
12
       
12
       
-
       
<xi:include href="linking-nixos-tests-to-packages.section.xml" />

     

       
8
       
8
       
+
       
```{=include=} sections

     

       
9
       
9
       
+
       
writing-nixos-tests.section.md

     

       
10
       
10
       
+
       
running-nixos-tests.section.md

     

       
11
       
11
       
+
       
running-nixos-tests-interactively.section.md

     

       
12
       
12
       
+
       
linking-nixos-tests-to-packages.section.md

     

       
13
       
13
       
 
       
```

     

···

       
47
       
47
       
 
       
with our units or the activation script. For this reason, these topics are

     

       
48
       
48
       
 
       
explained in the next sections.

     

       
49
       
49
       
 
       


     

       
50
       
50
       
-
       
```{=docbook}

     

       
51
       
51
       
-
       
<xi:include href="unit-handling.section.xml" />

     

       
52
       
52
       
-
       
<xi:include href="activation-script.section.xml" />

     

       
50
       
50
       
+
       
```{=include=} sections

     

       
51
       
51
       
+
       
unit-handling.section.md

     

       
52
       
52
       
+
       
activation-script.section.md

     

       
53
       
53
       
 
       
```

     

···

       
83
       
83
       
 
       


     

       
84
       
84
       
 
       
## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}

     

       
85
       
85
       
 
       


     

       
86
       
86
       
-
       
Open the parent XML file and add an `xi:include` element to the list of

     

       
86
       
86
       
+
       
Open the parent CommonMark file and add a line to the list of

     

       
87
       
87
       
 
       
chapters with the file name of the topic that you created. If you

     

       
88
       
88
       
 
       
created a `section`, you add the file to the `chapter` file. If you created

     

       
89
       
89
       
 
       
a `chapter`, you add the file to the `part` file.

     

···

       
189
       
189
       
 
       
```

     

       
190
       
190
       
 
       
:::

     

       
191
       
191
       
 
       


     

       
192
       
192
       
-
       
```{=docbook}

     

       
193
       
193
       
-
       
<xi:include href="option-declarations.section.xml" />

     

       
194
       
194
       
-
       
<xi:include href="option-types.section.xml" />

     

       
195
       
195
       
-
       
<xi:include href="option-def.section.xml" />

     

       
196
       
196
       
-
       
<xi:include href="assertions.section.xml" />

     

       
197
       
197
       
-
       
<xi:include href="meta-attributes.section.xml" />

     

       
198
       
198
       
-
       
<xi:include href="importing-modules.section.xml" />

     

       
199
       
199
       
-
       
<xi:include href="replace-modules.section.xml" />

     

       
200
       
200
       
-
       
<xi:include href="freeform-modules.section.xml" />

     

       
201
       
201
       
-
       
<xi:include href="settings-options.section.xml" />

     

       
192
       
192
       
+
       
```{=include=} sections

     

       
193
       
193
       
+
       
option-declarations.section.md

     

       
194
       
194
       
+
       
option-types.section.md

     

       
195
       
195
       
+
       
option-def.section.md

     

       
196
       
196
       
+
       
assertions.section.md

     

       
197
       
197
       
+
       
meta-attributes.section.md

     

       
198
       
198
       
+
       
importing-modules.section.md

     

       
199
       
199
       
+
       
replace-modules.section.md

     

       
200
       
200
       
+
       
freeform-modules.section.md

     

       
201
       
201
       
+
       
settings-options.section.md

     

       
202
       
202
       
 
       
```

     

···

       
470
       
470
       
 
       


     

       
471
       
471
       
 
       
The following options can be used when writing tests.

     

       
472
       
472
       
 
       


     

       
473
       
473
       
-
       
```{=docbook}

     

       
474
       
474
       
-
       
<xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/>

     

       
473
       
473
       
+
       
```{=include=} options

     

       
474
       
474
       
+
       
id-prefix: test-opt-

     

       
475
       
475
       
+
       
list-id: test-options-list

     

       
476
       
476
       
+
       
source: @NIXOS_TEST_OPTIONS_JSON@

     

       
475
       
477
       
 
       
```

     

···

       
1
       
1
       
+
       
# Installation {#ch-installation}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This section describes how to obtain, install, and configure NixOS for first-time use.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} chapters

     

       
6
       
6
       
+
       
obtaining.chapter.md

     

       
7
       
7
       
+
       
installing.chapter.md

     

       
8
       
8
       
+
       
changing-config.chapter.md

     

       
9
       
9
       
+
       
upgrading.chapter.md

     

       
10
       
10
       
+
       
building-nixos.chapter.md

     

       
11
       
11
       
+
       
```

     

···

       
1
       
1
       
-
       
<part 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
       
-
       
      version="5.0"

     

       
5
       
5
       
-
       
      xml:id="ch-installation">

     

       
6
       
6
       
-
       
 <title>Installation</title>

     

       
7
       
7
       
-
       
 <partintro xml:id="ch-installation-intro">

     

       
8
       
8
       
-
       
  <para>

     

       
9
       
9
       
-
       
   This section describes how to obtain, install, and configure NixOS for

     

       
10
       
10
       
-
       
   first-time use.

     

       
11
       
11
       
-
       
  </para>

     

       
12
       
12
       
-
       
 </partintro>

     

       
13
       
13
       
-
       
 <xi:include href="../from_md/installation/obtaining.chapter.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="../from_md/installation/installing.chapter.xml" />

     

       
15
       
15
       
-
       
 <xi:include href="../from_md/installation/changing-config.chapter.xml" />

     

       
16
       
16
       
-
       
 <xi:include href="../from_md/installation/upgrading.chapter.xml" />

     

       
17
       
17
       
-
       
 <xi:include href="../from_md/installation/building-nixos.chapter.xml" />

     

       
18
       
18
       
-
       
</part>

     

···

       
602
       
602
       
 
       


     

       
603
       
603
       
 
       
## Additional installation notes {#sec-installation-additional-notes}

     

       
604
       
604
       
 
       


     

       
605
       
605
       
-
       
```{=docbook}

     

       
606
       
606
       
-
       
<xi:include href="installing-usb.section.xml" />

     

       
607
       
607
       
-
       
<xi:include href="installing-pxe.section.xml" />

     

       
608
       
608
       
-
       
<xi:include href="installing-kexec.section.xml" />

     

       
609
       
609
       
-
       
<xi:include href="installing-virtualbox-guest.section.xml" />

     

       
610
       
610
       
-
       
<xi:include href="installing-from-other-distro.section.xml" />

     

       
611
       
611
       
-
       
<xi:include href="installing-behind-a-proxy.section.xml" />

     

       
605
       
605
       
+
       
```{=include=} sections

     

       
606
       
606
       
+
       
installing-usb.section.md

     

       
607
       
607
       
+
       
installing-pxe.section.md

     

       
608
       
608
       
+
       
installing-kexec.section.md

     

       
609
       
609
       
+
       
installing-virtualbox-guest.section.md

     

       
610
       
610
       
+
       
installing-from-other-distro.section.md

     

       
611
       
611
       
+
       
installing-behind-a-proxy.section.md

     

       
612
       
612
       
 
       
```

     

···

       
1
       
1
       
+
       
# NixOS Manual {#book-nixos-manual}

     

       
2
       
2
       
+
       
## Version @NIXOS_VERSION@

     

       
3
       
3
       
+
       


     

       
4
       
4
       
+
       
<!--

     

       
5
       
5
       
+
       
  this is the top-level structure file for the nixos manual.

     

       
6
       
6
       
+
       


     

       
7
       
7
       
+
       
  the manual structure extends the nixpkgs commonmark further with include

     

       
8
       
8
       
+
       
  blocks to allow better organization of input text. there are six types of

     

       
9
       
9
       
+
       
  include blocks: preface, parts, chapters, sections, appendix, and options.

     

       
10
       
10
       
+
       
  each type except `options`` corresponds to the docbook elements of (roughly)

     

       
11
       
11
       
+
       
  the same name, and can itself can further include blocks to denote its

     

       
12
       
12
       
+
       
  substructure.

     

       
13
       
13
       
+
       


     

       
14
       
14
       
+
       
  non-`options`` include blocks are fenced code blocks that list a number of

     

       
15
       
15
       
+
       
  files to include, in the form

     

       
16
       
16
       
+
       


     

       
17
       
17
       
+
       
     ```{=include=} <type>

     

       
18
       
18
       
+
       
     <file-name-1>

     

       
19
       
19
       
+
       
     <file-name-2>

     

       
20
       
20
       
+
       
     <...>

     

       
21
       
21
       
+
       
     ```

     

       
22
       
22
       
+
       


     

       
23
       
23
       
+
       
  `options` include blocks do not list file names but contain a list of key-value

     

       
24
       
24
       
+
       
  pairs that describe the options to be included and how to convert them into

     

       
25
       
25
       
+
       
  elements of the manual output type:

     

       
26
       
26
       
+
       


     

       
27
       
27
       
+
       
      ```{=include=} options

     

       
28
       
28
       
+
       
      id-prefix: <options id prefix>

     

       
29
       
29
       
+
       
      list-id: <variable list element id>

     

       
30
       
30
       
+
       
      source: <path to options.json>

     

       
31
       
31
       
+
       
      ```

     

       
32
       
32
       
+
       


     

       
33
       
33
       
+
       
-->

     

       
34
       
34
       
+
       


     

       
35
       
35
       
+
       
```{=include=} preface

     

       
36
       
36
       
+
       
preface.md

     

       
37
       
37
       
+
       
```

     

       
38
       
38
       
+
       


     

       
39
       
39
       
+
       
```{=include=} parts

     

       
40
       
40
       
+
       
installation/installation.md

     

       
41
       
41
       
+
       
configuration/configuration.md

     

       
42
       
42
       
+
       
administration/running.md

     

       
43
       
43
       
+
       
development/development.md

     

       
44
       
44
       
+
       
```

     

       
45
       
45
       
+
       


     

       
46
       
46
       
+
       
```{=include=} chapters

     

       
47
       
47
       
+
       
contributing-to-this-manual.chapter.md

     

       
48
       
48
       
+
       
```

     

       
49
       
49
       
+
       


     

       
50
       
50
       
+
       
```{=include=} appendix

     

       
51
       
51
       
+
       
nixos-options.md

     

       
52
       
52
       
+
       
release-notes/release-notes.md

     

       
53
       
53
       
+
       
```

     

···

       
1
       
1
       
-
       
<book 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
       
-
       
      version="5.0"

     

       
5
       
5
       
-
       
      xml:id="book-nixos-manual">

     

       
6
       
6
       
-
       
 <info>

     

       
7
       
7
       
-
       
  <title>NixOS Manual</title>

     

       
8
       
8
       
-
       
  <subtitle>Version <xi:include href="./generated/version" parse="text" />

     

       
9
       
9
       
-
       
  </subtitle>

     

       
10
       
10
       
-
       
 </info>

     

       
11
       
11
       
-
       
 <xi:include href="preface.xml" />

     

       
12
       
12
       
-
       
 <xi:include href="installation/installation.xml" />

     

       
13
       
13
       
-
       
 <xi:include href="configuration/configuration.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="administration/running.xml" />

     

       
15
       
15
       
-
       
 <xi:include href="development/development.xml" />

     

       
16
       
16
       
-
       
 <xi:include href="./from_md/contributing-to-this-manual.chapter.xml" />

     

       
17
       
17
       
-
       
 <appendix xml:id="ch-options">

     

       
18
       
18
       
-
       
  <title>Configuration Options</title>

     

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

     

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

     

       
21
       
21
       
-
       
 </appendix>

     

       
22
       
22
       
-
       
 <xi:include href="release-notes/release-notes.xml" />

     

       
23
       
23
       
-
       
</book>

     

···

       
1
       
1
       
+
       
# Configuration Options {#ch-options}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
```{=include=} options

     

       
4
       
4
       
+
       
id-prefix: opt-

     

       
5
       
5
       
+
       
list-id: configuration-variable-list

     

       
6
       
6
       
+
       
source: @NIXOS_OPTIONS_JSON@

     

       
7
       
7
       
+
       
```

     

···

       
1
       
1
       
+
       
# Preface {#preface}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system [Nix](https://nixos.org/nix), that is composed using modules and packages defined in the [Nixpkgs](https://nixos.org/nixpkgs) project.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
Additional information regarding the Nix package manager and the Nixpkgs project can be found in respectively the [Nix manual](https://nixos.org/nix/manual) and the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).

     

       
6
       
6
       
+
       


     

       
7
       
7
       
+
       
If you encounter problems, please report them on the [`Discourse`](https://discourse.nixos.org), the [Matrix room](https://matrix.to/#nix:nixos.org), or on the [`#nixos` channel on Libera.Chat](irc://irc.libera.chat/#nixos). Alternatively, consider [contributing to this manual](#chap-contributing). Bugs should be reported in [NixOS’ GitHub issue tracker](https://github.com/NixOS/nixpkgs/issues).

     

       
8
       
8
       
+
       


     

       
9
       
9
       
+
       
::: {.note}

     

       
10
       
10
       
+
       
Commands prefixed with `#` have to be run as root, either requiring to login as root user or temporarily switching to it using `sudo` for example.

     

       
11
       
11
       
+
       
:::

     

···

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

     

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

     

       
3
       
3
       
-
       
         xml:id="preface">

     

       
4
       
4
       
-
       
 <title>Preface</title>

     

       
5
       
5
       
-
       
 <para>

     

       
6
       
6
       
-
       
  This manual describes how to install, use and extend NixOS, a Linux

     

       
7
       
7
       
-
       
  distribution based on the purely functional package management system

     

       
8
       
8
       
-
       
  <link xlink:href="https://nixos.org/nix">Nix</link>, that is composed

     

       
9
       
9
       
-
       
  using modules and packages defined in the

     

       
10
       
10
       
-
       
  <link xlink:href="https://nixos.org/nixpkgs">Nixpkgs</link> project.

     

       
11
       
11
       
-
       
 </para>

     

       
12
       
12
       
-
       
 <para>

     

       
13
       
13
       
-
       
  Additional information regarding the Nix package manager and the Nixpkgs

     

       
14
       
14
       
-
       
  project can be found in respectively the

     

       
15
       
15
       
-
       
  <link xlink:href="https://nixos.org/nix/manual">Nix manual</link> and the

     

       
16
       
16
       
-
       
  <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.

     

       
17
       
17
       
-
       
 </para>

     

       
18
       
18
       
-
       
 <para>

     

       
19
       
19
       
-
       
  If you encounter problems, please report them on the

     

       
20
       
20
       
-
       
  <literal

     

       
21
       
21
       
-
       
   xlink:href="https://discourse.nixos.org">Discourse</literal>,

     

       
22
       
22
       
-
       
  the <link

     

       
23
       
23
       
-
       
   xlink:href="https://matrix.to/#nix:nixos.org">Matrix room</link>,

     

       
24
       
24
       
-
       
  or on the <link

     

       
25
       
25
       
-
       
   xlink:href="irc://irc.libera.chat/#nixos">

     

       
26
       
26
       
-
       
  <literal>#nixos</literal> channel on Libera.Chat</link>.

     

       
27
       
27
       
-
       
  Alternatively, consider <link

     

       
28
       
28
       
-
       
   xlink:href="#chap-contributing">

     

       
29
       
29
       
-
       
   contributing to this manual</link>. Bugs should be

     

       
30
       
30
       
-
       
  reported in

     

       
31
       
31
       
-
       
  <link

     

       
32
       
32
       
-
       
   xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’

     

       
33
       
33
       
-
       
  GitHub issue tracker</link>.

     

       
34
       
34
       
-
       
 </para>

     

       
35
       
35
       
-
       
 <note>

     

       
36
       
36
       
-
       
  <para>

     

       
37
       
37
       
-
       
   Commands prefixed with <literal>#</literal> have to be run as root, either

     

       
38
       
38
       
-
       
   requiring to login as root user or temporarily switching to it using

     

       
39
       
39
       
-
       
   <literal>sudo</literal> for example.

     

       
40
       
40
       
-
       
  </para>

     

       
41
       
41
       
-
       
 </note>

     

       
42
       
42
       
-
       
</preface>

     

···

       
1
       
1
       
+
       
# Release Notes {#ch-release-notes}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This section lists the release notes for each stable version of NixOS and current unstable revision.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} sections

     

       
6
       
6
       
+
       
rl-2305.section.md

     

       
7
       
7
       
+
       
rl-2211.section.md

     

       
8
       
8
       
+
       
rl-2205.section.md

     

       
9
       
9
       
+
       
rl-2111.section.md

     

       
10
       
10
       
+
       
rl-2105.section.md

     

       
11
       
11
       
+
       
rl-2009.section.md

     

       
12
       
12
       
+
       
rl-2003.section.md

     

       
13
       
13
       
+
       
rl-1909.section.md

     

       
14
       
14
       
+
       
rl-1903.section.md

     

       
15
       
15
       
+
       
rl-1809.section.md

     

       
16
       
16
       
+
       
rl-1803.section.md

     

       
17
       
17
       
+
       
rl-1709.section.md

     

       
18
       
18
       
+
       
rl-1703.section.md

     

       
19
       
19
       
+
       
rl-1609.section.md

     

       
20
       
20
       
+
       
rl-1603.section.md

     

       
21
       
21
       
+
       
rl-1509.section.md

     

       
22
       
22
       
+
       
rl-1412.section.md

     

       
23
       
23
       
+
       
rl-1404.section.md

     

       
24
       
24
       
+
       
rl-1310.section.md

     

       
25
       
25
       
+
       
```

     

···

       
1
       
1
       
-
       
<appendix 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
       
-
       
          version="5.0"

     

       
5
       
5
       
-
       
          xml:id="ch-release-notes">

     

       
6
       
6
       
-
       
 <title>Release Notes</title>

     

       
7
       
7
       
-
       
 <para>

     

       
8
       
8
       
-
       
  This section lists the release notes for each stable version of NixOS and

     

       
9
       
9
       
-
       
  current unstable revision.

     

       
10
       
10
       
-
       
 </para>

     

       
11
       
11
       
-
       
 <xi:include href="../from_md/release-notes/rl-2305.section.xml" />

     

       
12
       
12
       
-
       
 <xi:include href="../from_md/release-notes/rl-2211.section.xml" />

     

       
13
       
13
       
-
       
 <xi:include href="../from_md/release-notes/rl-2205.section.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="../from_md/release-notes/rl-2111.section.xml" />

     

       
15
       
15
       
-
       
 <xi:include href="../from_md/release-notes/rl-2105.section.xml" />

     

       
16
       
16
       
-
       
 <xi:include href="../from_md/release-notes/rl-2009.section.xml" />

     

       
17
       
17
       
-
       
 <xi:include href="../from_md/release-notes/rl-2003.section.xml" />

     

       
18
       
18
       
-
       
 <xi:include href="../from_md/release-notes/rl-1909.section.xml" />

     

       
19
       
19
       
-
       
 <xi:include href="../from_md/release-notes/rl-1903.section.xml" />

     

       
20
       
20
       
-
       
 <xi:include href="../from_md/release-notes/rl-1809.section.xml" />

     

       
21
       
21
       
-
       
 <xi:include href="../from_md/release-notes/rl-1803.section.xml" />

     

       
22
       
22
       
-
       
 <xi:include href="../from_md/release-notes/rl-1709.section.xml" />

     

       
23
       
23
       
-
       
 <xi:include href="../from_md/release-notes/rl-1703.section.xml" />

     

       
24
       
24
       
-
       
 <xi:include href="../from_md/release-notes/rl-1609.section.xml" />

     

       
25
       
25
       
-
       
 <xi:include href="../from_md/release-notes/rl-1603.section.xml" />

     

       
26
       
26
       
-
       
 <xi:include href="../from_md/release-notes/rl-1509.section.xml" />

     

       
27
       
27
       
-
       
 <xi:include href="../from_md/release-notes/rl-1412.section.xml" />

     

       
28
       
28
       
-
       
 <xi:include href="../from_md/release-notes/rl-1404.section.xml" />

     

       
29
       
29
       
-
       
 <xi:include href="../from_md/release-notes/rl-1310.section.xml" />

     

       
30
       
30
       
-
       
</appendix>

     

···

       
2
       
2
       
 
       
import json

     

       
3
       
3
       
 
       


     

       
4
       
4
       
 
       
from abc import abstractmethod

     

       
5
       
5
       
-
       
from collections.abc import MutableMapping, Sequence

     

       
5
       
5
       
+
       
from collections.abc import Mapping, MutableMapping, Sequence

     

       
6
       
6
       
 
       
from pathlib import Path

     

       
7
       
7
       
 
       
from typing import Any, cast, NamedTuple, Optional, Union

     

       
8
       
8
       
 
       
from xml.sax.saxutils import escape, quoteattr

     

       
9
       
9
       
+
       


     

       
10
       
10
       
+
       
import markdown_it

     

       
9
       
11
       
 
       
from markdown_it.token import Token

     

       
10
       
12
       
 
       
from markdown_it.utils import OptionsDict

     

       
11
       
13
       
 
       


     

       
12
       
12
       
-
       
from .docbook import DocBookRenderer

     

       
14
       
14
       
+
       
from . import options

     

       
15
       
15
       
+
       
from .docbook import DocBookRenderer, Heading

     

       
13
       
16
       
 
       
from .md import Converter

     

       
14
       
17
       
 
       


     

       
15
       
15
       
-
       
class RenderedSection:

     

       
16
       
16
       
-
       
    id: Optional[str]

     

       
17
       
17
       
-
       
    chapters: list[str]

     

       
18
       
18
       
+
       
class ManualDocBookRenderer(DocBookRenderer):

     

       
19
       
19
       
+
       
    _toplevel_tag: str

     

       
18
       
20
       
 
       


     

       
19
       
19
       
-
       
    def __init__(self, id: Optional[str]) -> None:

     

       
20
       
20
       
-
       
        self.id = id

     

       
21
       
21
       
-
       
        self.chapters = []

     

       
21
       
21
       
+
       
    def __init__(self, toplevel_tag: str, manpage_urls: Mapping[str, str],

     

       
22
       
22
       
+
       
                 parser: Optional[markdown_it.MarkdownIt] = None):

     

       
23
       
23
       
+
       
        super().__init__(manpage_urls, parser)

     

       
24
       
24
       
+
       
        self._toplevel_tag = toplevel_tag

     

       
25
       
25
       
+
       
        self.rules |= {

     

       
26
       
26
       
+
       
            'included_sections': lambda *args: self._included_thing("section", *args),

     

       
27
       
27
       
+
       
            'included_chapters': lambda *args: self._included_thing("chapter", *args),

     

       
28
       
28
       
+
       
            'included_preface': lambda *args: self._included_thing("preface", *args),

     

       
29
       
29
       
+
       
            'included_parts': lambda *args: self._included_thing("part", *args),

     

       
30
       
30
       
+
       
            'included_appendix': lambda *args: self._included_thing("appendix", *args),

     

       
31
       
31
       
+
       
            'included_options': self.included_options,

     

       
32
       
32
       
+
       
        }

     

       
22
       
33
       
 
       


     

       
23
       
23
       
-
       
class BaseConverter(Converter):

     

       
24
       
24
       
-
       
    _sections: list[RenderedSection]

     

       
34
       
34
       
+
       
    def render(self, tokens: Sequence[Token], options: OptionsDict,

     

       
35
       
35
       
+
       
               env: MutableMapping[str, Any]) -> str:

     

       
36
       
36
       
+
       
        wanted = { 'h1': 'title' }

     

       
37
       
37
       
+
       
        wanted |= { 'h2': 'subtitle' } if self._toplevel_tag == 'book' else {}

     

       
38
       
38
       
+
       
        for (i, (tag, kind)) in enumerate(wanted.items()):

     

       
39
       
39
       
+
       
            if len(tokens) < 3 * (i + 1):

     

       
40
       
40
       
+
       
                raise RuntimeError(f"missing {kind} ({tag}) heading")

     

       
41
       
41
       
+
       
            token = tokens[3 * i]

     

       
42
       
42
       
+
       
            if token.type != 'heading_open' or token.tag != tag:

     

       
43
       
43
       
+
       
                assert token.map

     

       
44
       
44
       
+
       
                raise RuntimeError(f"expected {kind} ({tag}) heading in line {token.map[0] + 1}", token)

     

       
45
       
45
       
+
       
        for t in tokens[3 * len(wanted):]:

     

       
46
       
46
       
+
       
            if t.type != 'heading_open' or (info := wanted.get(t.tag)) is None:

     

       
47
       
47
       
+
       
                continue

     

       
48
       
48
       
+
       
            assert t.map

     

       
49
       
49
       
+
       
            raise RuntimeError(

     

       
50
       
50
       
+
       
                f"only one {info[0]} heading ({t.markup} [text...]) allowed per "

     

       
51
       
51
       
+
       
                f"{self._toplevel_tag}, but found a second in lines [{t.map[0] + 1}..{t.map[1]}]. "

     

       
52
       
52
       
+
       
                "please remove all such headings except the first or demote the subsequent headings.",

     

       
53
       
53
       
+
       
                t)

     

       
25
       
54
       
 
       


     

       
26
       
26
       
-
       
    def __init__(self, manpage_urls: dict[str, str]):

     

       
27
       
27
       
-
       
        super().__init__(manpage_urls)

     

       
28
       
28
       
-
       
        self._sections = []

     

       
29
       
29
       
-
       


     

       
30
       
30
       
-
       
    def add_section(self, id: Optional[str], chapters: list[Path]) -> None:

     

       
31
       
31
       
-
       
        self._sections.append(RenderedSection(id))

     

       
32
       
32
       
-
       
        for chpath in chapters:

     

       
33
       
33
       
-
       
            try:

     

       
34
       
34
       
-
       
                with open(chpath, 'r') as f:

     

       
35
       
35
       
-
       
                    self._md.renderer._title_seen = False # type: ignore[attr-defined]

     

       
36
       
36
       
-
       
                    self._sections[-1].chapters.append(self._render(f.read()))

     

       
37
       
37
       
-
       
            except Exception as e:

     

       
38
       
38
       
-
       
                raise RuntimeError(f"failed to render manual chapter {chpath}") from e

     

       
39
       
39
       
-
       


     

       
40
       
40
       
-
       
    @abstractmethod

     

       
41
       
41
       
-
       
    def finalize(self) -> str: raise NotImplementedError()

     

       
55
       
55
       
+
       
        # books get special handling because they have *two* title tags. doing this with

     

       
56
       
56
       
+
       
        # generic code is more complicated than it's worth. the checks above have verified

     

       
57
       
57
       
+
       
        # that both titles actually exist.

     

       
58
       
58
       
+
       
        if self._toplevel_tag == 'book':

     

       
59
       
59
       
+
       
            assert tokens[1].children

     

       
60
       
60
       
+
       
            assert tokens[4].children

     

       
61
       
61
       
+
       
            if (maybe_id := cast(str, tokens[0].attrs.get('id', ""))):

     

       
62
       
62
       
+
       
                maybe_id = "xml:id=" + quoteattr(maybe_id)

     

       
63
       
63
       
+
       
            return (f'<book xmlns="http://docbook.org/ns/docbook"'

     

       
64
       
64
       
+
       
                    f'      xmlns:xlink="http://www.w3.org/1999/xlink"'

     

       
65
       
65
       
+
       
                    f'      {maybe_id} version="5.0">'

     

       
66
       
66
       
+
       
                    f'  <title>{self.renderInline(tokens[1].children, options, env)}</title>'

     

       
67
       
67
       
+
       
                    f'  <subtitle>{self.renderInline(tokens[4].children, options, env)}</subtitle>'

     

       
68
       
68
       
+
       
                    f'  {super().render(tokens[6:], options, env)}'

     

       
69
       
69
       
+
       
                    f'</book>')

     

       
42
       
70
       
 
       


     

       
43
       
43
       
-
       
class ManualDocBookRenderer(DocBookRenderer):

     

       
44
       
44
       
-
       
    # needed to check correctness of chapters.

     

       
45
       
45
       
-
       
    # we may want to use front matter instead of this kind of heuristic.

     

       
46
       
46
       
-
       
    _title_seen = False

     

       
71
       
71
       
+
       
        return super().render(tokens, options, env)

     

       
47
       
72
       
 
       


     

       
48
       
73
       
 
       
    def _heading_tag(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       
49
       
74
       
 
       
                     env: MutableMapping[str, Any]) -> tuple[str, dict[str, str]]:

     

       
50
       
75
       
 
       
        (tag, attrs) = super()._heading_tag(token, tokens, i, options, env)

     

       
51
       
51
       
-
       
        if self._title_seen:

     

       
52
       
52
       
-
       
            if token.tag == 'h1':

     

       
53
       
53
       
-
       
                assert token.map is not None

     

       
54
       
54
       
-
       
                raise RuntimeError(

     

       
55
       
55
       
-
       
                    "only one title heading (# [text...]) allowed per manual chapter "

     

       
56
       
56
       
-
       
                    f"but found a second in lines [{token.map[0]}..{token.map[1]}]. "

     

       
57
       
57
       
-
       
                    "please remove all such headings except the first, split your "

     

       
58
       
58
       
-
       
                    "chapters, or demote the subsequent headings to (##) or lower.",

     

       
59
       
59
       
-
       
                    token)

     

       
76
       
76
       
+
       
        # render() has already verified that we don't have supernumerary headings and since the

     

       
77
       
77
       
+
       
        # book tag is handled specially we can leave the check this simple

     

       
78
       
78
       
+
       
        if token.tag != 'h1':

     

       
60
       
79
       
 
       
            return (tag, attrs)

     

       
61
       
61
       
-
       
        self._title_seen = True

     

       
62
       
62
       
-
       
        return ("chapter", attrs | {

     

       
80
       
80
       
+
       
        return (self._toplevel_tag, attrs | {

     

       
63
       
81
       
 
       
            'xmlns': "http://docbook.org/ns/docbook",

     

       
64
       
82
       
 
       
            'xmlns:xlink': "http://www.w3.org/1999/xlink",

     

       
65
       
83
       
 
       
        })

     

       
66
       
84
       
 
       


     

       
85
       
85
       
+
       
    def _included_thing(self, tag: str, token: Token, tokens: Sequence[Token], i: int,

     

       
86
       
86
       
+
       
                        options: OptionsDict, env: MutableMapping[str, Any]) -> str:

     

       
87
       
87
       
+
       
        result = []

     

       
88
       
88
       
+
       
        # close existing partintro. the generic render doesn't really need this because

     

       
89
       
89
       
+
       
        # it doesn't have a concept of structure in the way the manual does.

     

       
90
       
90
       
+
       
        if self._headings and self._headings[-1] == Heading('part', 1):

     

       
91
       
91
       
+
       
            result.append("</partintro>")

     

       
92
       
92
       
+
       
            self._headings[-1] = self._headings[-1]._replace(partintro_closed=True)

     

       
93
       
93
       
+
       
        # must nest properly for structural includes. this requires saving at least

     

       
94
       
94
       
+
       
        # the headings stack, but creating new renderers is cheap and much easier.

     

       
95
       
95
       
+
       
        r = ManualDocBookRenderer(tag, self._manpage_urls, None)

     

       
96
       
96
       
+
       
        for (included, path) in token.meta['included']:

     

       
97
       
97
       
+
       
            try:

     

       
98
       
98
       
+
       
                result.append(r.render(included, options, env))

     

       
99
       
99
       
+
       
            except Exception as e:

     

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

     

       
101
       
101
       
+
       
        return "".join(result)

     

       
102
       
102
       
+
       
    def included_options(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       
103
       
103
       
+
       
                         env: MutableMapping[str, Any]) -> str:

     

       
104
       
104
       
+
       
        return cast(str, token.meta['rendered-options'])

     

       
105
       
105
       
+
       


     

       
67
       
106
       
 
       
    # TODO minimize docbook diffs with existing conversions. remove soon.

     

       
68
       
107
       
 
       
    def paragraph_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       
69
       
108
       
 
       
                       env: MutableMapping[str, Any]) -> str:

     
···

       
76
       
115
       
 
       
        return f"<programlisting>\n{escape(token.content)}</programlisting>"

     

       
77
       
116
       
 
       
    def fence(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       
78
       
117
       
 
       
              env: MutableMapping[str, Any]) -> str:

     

       
79
       
79
       
-
       
        # HACK for temporarily being able to replace md-to-db.sh. pandoc used this syntax to

     

       
80
       
80
       
-
       
        # allow md files to inject arbitrary docbook, and manual chapters use it.

     

       
81
       
81
       
-
       
        if token.info == '{=docbook}':

     

       
82
       
82
       
-
       
            return token.content

     

       
83
       
118
       
 
       
        info = f" language={quoteattr(token.info)}" if token.info != "" else ""

     

       
84
       
119
       
 
       
        return f"<programlisting{info}>\n{escape(token.content)}</programlisting>"

     

       
85
       
120
       
 
       


     

       
86
       
86
       
-
       
class DocBookSectionConverter(BaseConverter):

     

       
87
       
87
       
-
       
    __renderer__ = ManualDocBookRenderer

     

       
121
       
121
       
+
       
class DocBookConverter(Converter):

     

       
122
       
122
       
+
       
    def __renderer__(self, manpage_urls: Mapping[str, str],

     

       
123
       
123
       
+
       
                     parser: Optional[markdown_it.MarkdownIt]) -> ManualDocBookRenderer:

     

       
124
       
124
       
+
       
        return ManualDocBookRenderer('book', manpage_urls, parser)

     

       
88
       
125
       
 
       


     

       
89
       
89
       
-
       
    def finalize(self) -> str:

     

       
90
       
90
       
-
       
        result = []

     

       
91
       
91
       
-
       


     

       
92
       
92
       
-
       
        for section in self._sections:

     

       
93
       
93
       
-
       
            id = "id=" + quoteattr(section.id) if section.id is not None else ""

     

       
94
       
94
       
-
       
            result.append(f'<section {id}>')

     

       
95
       
95
       
-
       
            result += section.chapters

     

       
96
       
96
       
-
       
            result.append(f'</section>')

     

       
97
       
97
       
-
       


     

       
98
       
98
       
-
       
        return "\n".join(result)

     

       
126
       
126
       
+
       
    _base_paths: list[Path]

     

       
127
       
127
       
+
       
    _revision: str

     

       
99
       
128
       
 
       


     

       
100
       
100
       
-
       
class ManualFragmentDocBookRenderer(ManualDocBookRenderer):

     

       
101
       
101
       
-
       
    _tag: str = "chapter"

     

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

     

       
130
       
130
       
+
       
        super().__init__(manpage_urls)

     

       
131
       
131
       
+
       
        self._revision = revision

     

       
102
       
132
       
 
       


     

       
103
       
103
       
-
       
    def _heading_tag(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       
104
       
104
       
-
       
                     env: MutableMapping[str, Any]) -> tuple[str, dict[str, str]]:

     

       
105
       
105
       
-
       
        (tag, attrs) = super()._heading_tag(token, tokens, i, options, env)

     

       
106
       
106
       
-
       
        if token.tag == 'h1':

     

       
107
       
107
       
-
       
            return (self._tag, attrs | { 'xmlns:xi': "http://www.w3.org/2001/XInclude" })

     

       
108
       
108
       
-
       
        return (tag, attrs)

     

       
109
       
109
       
-
       


     

       
110
       
110
       
-
       
class DocBookFragmentConverter(Converter):

     

       
111
       
111
       
-
       
    __renderer__ = ManualFragmentDocBookRenderer

     

       
112
       
112
       
-
       


     

       
113
       
113
       
-
       
    def convert(self, file: Path, tag: str) -> str:

     

       
114
       
114
       
-
       
        assert isinstance(self._md.renderer, ManualFragmentDocBookRenderer)

     

       
133
       
133
       
+
       
    def convert(self, file: Path) -> str:

     

       
134
       
134
       
+
       
        self._base_paths = [ file ]

     

       
115
       
135
       
 
       
        try:

     

       
116
       
136
       
 
       
            with open(file, 'r') as f:

     

       
117
       
117
       
-
       
                self._md.renderer._title_seen = False

     

       
118
       
118
       
-
       
                self._md.renderer._tag = tag

     

       
119
       
137
       
 
       
                return self._render(f.read())

     

       
120
       
138
       
 
       
        except Exception as e:

     

       
121
       
121
       
-
       
            raise RuntimeError(f"failed to render manual {tag} {file}") from e

     

       
139
       
139
       
+
       
            raise RuntimeError(f"failed to render manual {file}") from e

     

       
122
       
140
       
 
       


     

       
141
       
141
       
+
       
    def _parse(self, src: str, env: Optional[MutableMapping[str, Any]] = None) -> list[Token]:

     

       
142
       
142
       
+
       
        tokens = super()._parse(src, env)

     

       
143
       
143
       
+
       
        for token in tokens:

     

       
144
       
144
       
+
       
            if token.type != "fence" or not token.info.startswith("{=include=} "):

     

       
145
       
145
       
+
       
                continue

     

       
146
       
146
       
+
       
            typ = token.info[12:].strip()

     

       
147
       
147
       
+
       
            if typ == 'options':

     

       
148
       
148
       
+
       
                token.type = 'included_options'

     

       
149
       
149
       
+
       
                self._parse_options(token)

     

       
150
       
150
       
+
       
            elif typ in [ 'sections', 'chapters', 'preface', 'parts', 'appendix' ]:

     

       
151
       
151
       
+
       
                token.type = 'included_' + typ

     

       
152
       
152
       
+
       
                self._parse_included_blocks(token, env)

     

       
153
       
153
       
+
       
            else:

     

       
154
       
154
       
+
       
                raise RuntimeError(f"unsupported structural include type '{typ}'")

     

       
155
       
155
       
+
       
        return tokens

     

       
123
       
156
       
 
       


     

       
157
       
157
       
+
       
    def _parse_included_blocks(self, token: Token, env: Optional[MutableMapping[str, Any]]) -> None:

     

       
158
       
158
       
+
       
        assert token.map

     

       
159
       
159
       
+
       
        included = token.meta['included'] = []

     

       
160
       
160
       
+
       
        for (lnum, line) in enumerate(token.content.splitlines(), token.map[0] + 2):

     

       
161
       
161
       
+
       
            line = line.strip()

     

       
162
       
162
       
+
       
            path = self._base_paths[-1].parent / line

     

       
163
       
163
       
+
       
            if path in self._base_paths:

     

       
164
       
164
       
+
       
                raise RuntimeError(f"circular include found in line {lnum}")

     

       
165
       
165
       
+
       
            try:

     

       
166
       
166
       
+
       
                self._base_paths.append(path)

     

       
167
       
167
       
+
       
                with open(path, 'r') as f:

     

       
168
       
168
       
+
       
                    tokens = self._parse(f.read(), env)

     

       
169
       
169
       
+
       
                    included.append((tokens, path))

     

       
170
       
170
       
+
       
                self._base_paths.pop()

     

       
171
       
171
       
+
       
            except Exception as e:

     

       
172
       
172
       
+
       
                raise RuntimeError(f"processing included file {path} from line {lnum}") from e

     

       
124
       
173
       
 
       


     

       
125
       
125
       
-
       
class Section:

     

       
126
       
126
       
-
       
    id: Optional[str] = None

     

       
127
       
127
       
-
       
    chapters: list[str]

     

       
174
       
174
       
+
       
    def _parse_options(self, token: Token) -> None:

     

       
175
       
175
       
+
       
        assert token.map

     

       
128
       
176
       
 
       


     

       
129
       
129
       
-
       
    def __init__(self) -> None:

     

       
130
       
130
       
-
       
        self.chapters = []

     

       
177
       
177
       
+
       
        items = {}

     

       
178
       
178
       
+
       
        for (lnum, line) in enumerate(token.content.splitlines(), token.map[0] + 2):

     

       
179
       
179
       
+
       
            if len(args := line.split(":", 1)) != 2:

     

       
180
       
180
       
+
       
                raise RuntimeError(f"options directive with no argument in line {lnum}")

     

       
181
       
181
       
+
       
            (k, v) = (args[0].strip(), args[1].strip())

     

       
182
       
182
       
+
       
            if k in items:

     

       
183
       
183
       
+
       
                raise RuntimeError(f"duplicate options directive {k} in line {lnum}")

     

       
184
       
184
       
+
       
            items[k] = v

     

       
185
       
185
       
+
       
        try:

     

       
186
       
186
       
+
       
            id_prefix = items.pop('id-prefix')

     

       
187
       
187
       
+
       
            varlist_id = items.pop('list-id')

     

       
188
       
188
       
+
       
            source = items.pop('source')

     

       
189
       
189
       
+
       
        except KeyError as e:

     

       
190
       
190
       
+
       
            raise RuntimeError(f"options directive {e} missing in block at line {token.map[0] + 1}")

     

       
191
       
191
       
+
       
        if items.keys():

     

       
192
       
192
       
+
       
            raise RuntimeError(

     

       
193
       
193
       
+
       
                f"unsupported options directives in block at line {token.map[0] + 1}",

     

       
194
       
194
       
+
       
                " ".join(items.keys()))

     

       
131
       
195
       
 
       


     

       
132
       
132
       
-
       
class SectionAction(argparse.Action):

     

       
133
       
133
       
-
       
    def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       
134
       
134
       
-
       
                 values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       
135
       
135
       
-
       
        sections = getattr(ns, self.dest)

     

       
136
       
136
       
-
       
        if sections is None: sections = []

     

       
137
       
137
       
-
       
        sections.append(Section())

     

       
138
       
138
       
-
       
        setattr(ns, self.dest, sections)

     

       
196
       
196
       
+
       
        try:

     

       
197
       
197
       
+
       
            conv = options.DocBookConverter(

     

       
198
       
198
       
+
       
                self._manpage_urls, self._revision, False, 'fragment', varlist_id, id_prefix)

     

       
199
       
199
       
+
       
            with open(self._base_paths[-1].parent / source, 'r') as f:

     

       
200
       
200
       
+
       
                conv.add_options(json.load(f))

     

       
201
       
201
       
+
       
            token.meta['rendered-options'] = conv.finalize(fragment=True)

     

       
202
       
202
       
+
       
        except Exception as e:

     

       
203
       
203
       
+
       
            raise RuntimeError(f"processing options block in line {token.map[0] + 1}") from e

     

       
139
       
204
       
 
       


     

       
140
       
140
       
-
       
class SectionIDAction(argparse.Action):

     

       
141
       
141
       
-
       
    def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       
142
       
142
       
-
       
                 values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       
143
       
143
       
-
       
        sections = getattr(ns, self.dest)

     

       
144
       
144
       
-
       
        if sections is None: raise argparse.ArgumentError(self, "no active section")

     

       
145
       
145
       
-
       
        sections[-1].id = cast(str, values)

     

       
146
       
205
       
 
       


     

       
147
       
147
       
-
       
class ChaptersAction(argparse.Action):

     

       
148
       
148
       
-
       
    def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       
149
       
149
       
-
       
                 values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       
150
       
150
       
-
       
        sections = getattr(ns, self.dest)

     

       
151
       
151
       
-
       
        if sections is None: raise argparse.ArgumentError(self, "no active section")

     

       
152
       
152
       
-
       
        sections[-1].chapters.extend(map(Path, cast(Sequence[str], values)))

     

       
153
       
206
       
 
       


     

       
154
       
154
       
-
       
class SingleFileAction(argparse.Action):

     

       
155
       
155
       
-
       
    def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       
156
       
156
       
-
       
                 values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       
157
       
157
       
-
       
        assert isinstance(values, Sequence)

     

       
158
       
158
       
-
       
        chapters = getattr(ns, self.dest) or []

     

       
159
       
159
       
-
       
        chapters.append((Path(values[0]), Path(values[1])))

     

       
160
       
160
       
-
       
        setattr(ns, self.dest, chapters)

     

       
161
       
161
       
-
       


     

       
162
       
162
       
-
       
def _build_cli_db_section(p: argparse.ArgumentParser) -> None:

     

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

     

       
164
       
164
       
-
       
    p.add_argument("outfile")

     

       
165
       
165
       
-
       
    p.add_argument("--section", dest="contents", action=SectionAction, nargs=0)

     

       
166
       
166
       
-
       
    p.add_argument("--section-id", dest="contents", action=SectionIDAction)

     

       
167
       
167
       
-
       
    p.add_argument("--chapters", dest="contents", action=ChaptersAction, nargs='+')

     

       
168
       
168
       
-
       


     

       
169
       
169
       
-
       
def _build_cli_db_fragment(p: argparse.ArgumentParser) -> None:

     

       
207
       
207
       
+
       
def _build_cli_db(p: argparse.ArgumentParser) -> None:

     

       
170
       
208
       
 
       
    p.add_argument('--manpage-urls', required=True)

     

       
171
       
171
       
-
       
    p.add_argument("--chapter", action=SingleFileAction, required=True, nargs=2)

     

       
172
       
172
       
-
       
    p.add_argument("--section", action=SingleFileAction, required=True, nargs=2)

     

       
209
       
209
       
+
       
    p.add_argument('--revision', required=True)

     

       
210
       
210
       
+
       
    p.add_argument('infile', type=Path)

     

       
211
       
211
       
+
       
    p.add_argument('outfile', type=Path)

     

       
173
       
212
       
 
       


     

       
174
       
174
       
-
       
def _run_cli_db_section(args: argparse.Namespace) -> None:

     

       
213
       
213
       
+
       
def _run_cli_db(args: argparse.Namespace) -> None:

     

       
175
       
214
       
 
       
    with open(args.manpage_urls, 'r') as manpage_urls:

     

       
176
       
176
       
-
       
        md = DocBookSectionConverter(json.load(manpage_urls))

     

       
177
       
177
       
-
       
        for section in args.contents:

     

       
178
       
178
       
-
       
            md.add_section(section.id, section.chapters)

     

       
179
       
179
       
-
       
        with open(args.outfile, 'w') as f:

     

       
180
       
180
       
-
       
            f.write(md.finalize())

     

       
181
       
181
       
-
       


     

       
182
       
182
       
-
       
def _run_cli_db_fragment(args: argparse.Namespace) -> None:

     

       
183
       
183
       
-
       
    with open(args.manpage_urls, 'r') as manpage_urls:

     

       
184
       
184
       
-
       
        md = DocBookFragmentConverter(json.load(manpage_urls))

     

       
185
       
185
       
-
       
        for kind in [ 'chapter', 'section' ]:

     

       
186
       
186
       
-
       
            for (target, file) in getattr(args, kind):

     

       
187
       
187
       
-
       
                converted = md.convert(file, kind)

     

       
188
       
188
       
-
       
                target.parent.mkdir(parents=True, exist_ok=True)

     

       
189
       
189
       
-
       
                target.write_text(converted)

     

       
215
       
215
       
+
       
        md = DocBookConverter(json.load(manpage_urls), args.revision)

     

       
216
       
216
       
+
       
        converted = md.convert(args.infile)

     

       
217
       
217
       
+
       
        args.outfile.write_text(converted)

     

       
190
       
218
       
 
       


     

       
191
       
219
       
 
       
def build_cli(p: argparse.ArgumentParser) -> None:

     

       
192
       
220
       
 
       
    formats = p.add_subparsers(dest='format', required=True)

     

       
193
       
193
       
-
       
    _build_cli_db_section(formats.add_parser('docbook-section'))

     

       
194
       
194
       
-
       
    _build_cli_db_fragment(formats.add_parser('docbook-fragment'))

     

       
221
       
221
       
+
       
    _build_cli_db(formats.add_parser('docbook'))

     

       
195
       
222
       
 
       


     

       
196
       
223
       
 
       
def run_cli(args: argparse.Namespace) -> None:

     

       
197
       
197
       
-
       
    if args.format == 'docbook-section':

     

       
198
       
198
       
-
       
        _run_cli_db_section(args)

     

       
199
       
199
       
-
       
    elif args.format == 'docbook-fragment':

     

       
200
       
200
       
-
       
        _run_cli_db_fragment(args)

     

       
224
       
224
       
+
       
    if args.format == 'docbook':

     

       
225
       
225
       
+
       
        _run_cli_db(args)

     

       
201
       
226
       
 
       
    else:

     

       
202
       
227
       
 
       
        raise RuntimeError('format not hooked up', args)

     

···

       
231
       
231
       
 
       
    def _decl_def_footer(self) -> list[str]:

     

       
232
       
232
       
 
       
        return [ "</simplelist>" ]

     

       
233
       
233
       
 
       


     

       
234
       
234
       
-
       
    def finalize(self) -> str:

     

       
234
       
234
       
+
       
    def finalize(self, *, fragment: bool = False) -> str:

     

       
235
       
235
       
 
       
        result = []

     

       
236
       
236
       
 
       


     

       
237
       
237
       
-
       
        result.append('<?xml version="1.0" encoding="UTF-8"?>')

     

       
237
       
237
       
+
       
        if not fragment:

     

       
238
       
238
       
+
       
            result.append('<?xml version="1.0" encoding="UTF-8"?>')

     

       
238
       
239
       
 
       
        if self._document_type == 'appendix':

     

       
239
       
240
       
 
       
            result += [

     

       
240
       
241
       
 
       
                '<appendix xmlns="http://docbook.org/ns/docbook"',