pyrox.dev
lol
nixos/manual: mention that module chapters should use markdown
+41
+20
nixos/doc/manual/development/meta-attributes.section.md
+20
nixos/doc/manual/development/meta-attributes.section.md
···
40
40
$ nix-build nixos/release.nix -A manual.x86_64-linux
41
41
```
42
42
43
+
This file should *not* usually be written by hand. Instead it is preferred
44
+
to write documentation using CommonMark and converting it to CommonMark
45
+
using pandoc. The simplest documentation can be converted using just
46
+
47
+
```ShellSession
48
+
$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml
49
+
```
50
+
51
+
More elaborate documentation may wish to add one or more of the pandoc
52
+
filters used to build the remainder of the manual, for example the GNOME
53
+
desktop uses
54
+
55
+
```ShellSession
56
+
$ pandoc gnome.md -t docbook --top-level-division=chapter \
57
+
--extract-media=media -f markdown+smart \
58
+
--lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \
59
+
--lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
60
+
> gnome.xml
61
+
```
62
+
43
63
- `buildDocsInSandbox` indicates whether the option documentation for the
44
64
module can be built in a derivation sandbox. This option is currently only
45
65
honored for modules shipped by nixpkgs. User modules and modules taken from
+21
nixos/doc/manual/from_md/development/meta-attributes.section.xml
+21
nixos/doc/manual/from_md/development/meta-attributes.section.xml
···
51
51
<programlisting>
52
52
$ nix-build nixos/release.nix -A manual.x86_64-linux
53
53
</programlisting>
54
+
<para>
55
+
This file should <emphasis>not</emphasis> usually be written by
56
+
hand. Instead it is preferred to write documentation using
57
+
CommonMark and converting it to CommonMark using pandoc. The
58
+
simplest documentation can be converted using just
59
+
</para>
60
+
<programlisting>
61
+
$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml
62
+
</programlisting>
63
+
<para>
64
+
More elaborate documentation may wish to add one or more of the
65
+
pandoc filters used to build the remainder of the manual, for
66
+
example the GNOME desktop uses
67
+
</para>
68
+
<programlisting>
69
+
$ pandoc gnome.md -t docbook --top-level-division=chapter \
70
+
--extract-media=media -f markdown+smart \
71
+
--lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \
72
+
--lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
73
+
> gnome.xml
74
+
</programlisting>
54
75
</listitem>
55
76
<listitem>
56
77
<para>