From 785c0f2afaa326f45e6c2cfc83e257278f80a001 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Wed, 4 Jan 2023 09:02:21 +0100
Subject: [PATCH] nixos/manual: mention that module chapters should use
 markdown

---
 .../development/meta-attributes.section.md    | 20 ++++++++++++++++++
 .../development/meta-attributes.section.xml   | 21 +++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md
index 946c08efd0a..7129cf8723e 100644
--- a/nixos/doc/manual/development/meta-attributes.section.md
+++ b/nixos/doc/manual/development/meta-attributes.section.md
@@ -40,6 +40,26 @@ file.
     $ nix-build nixos/release.nix -A manual.x86_64-linux
     ```
 
+    This file should *not* 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
+
+    ```ShellSession
+    $ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml
+    ```
+
+    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
+
+    ```ShellSession
+    $ 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
+    ```
+
 -  `buildDocsInSandbox` indicates whether the option documentation for the
    module can be built in a derivation sandbox. This option is currently only
    honored for modules shipped by nixpkgs. User modules and modules taken from
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 9cc58afa1fd..450a5f670f3 100644
--- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml
+++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml
@@ -50,6 +50,27 @@
       </para>
       <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 &gt; 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 \
+    &gt; gnome.xml
 </programlisting>
     </listitem>
     <listitem>