diff options
Diffstat (limited to 'nixos/doc/manual/from_md/development/meta-attributes.section.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/development/meta-attributes.section.xml | 21 |
1 files changed, 21 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml index 9cc58afa1fdd..450a5f670f3a 100644 --- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml +++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml @@ -51,6 +51,27 @@ <programlisting> $ nix-build nixos/release.nix -A manual.x86_64-linux </programlisting> + <para> + This file should <emphasis>not</emphasis> usually be written by + hand. Instead it is preferred to write documentation using + CommonMark and converting it to CommonMark using pandoc. The + simplest documentation can be converted using just + </para> + <programlisting> +$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml +</programlisting> + <para> + More elaborate documentation may wish to add one or more of the + pandoc filters used to build the remainder of the manual, for + example the GNOME desktop uses + </para> + <programlisting> +$ pandoc gnome.md -t docbook --top-level-division=chapter \ + --extract-media=media -f markdown+smart \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \ + > gnome.xml +</programlisting> </listitem> <listitem> <para> |