Merge pull request #127270 from jtojnar/doc-md-helper

nixos/doc: Synchronize the Markdown generator with Nixpkgs

doc/Makefile

@@ -3,6 +3,7 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$'
 PANDOC ?= pandoc
 
 pandoc_media_dir = media
+# NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh).
 # TODO: Remove raw-attribute when we can get rid of DocBook altogether.
 pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
 pandoc_flags = --extract-media=$(pandoc_media_dir) \
@@ -101,10 +102,10 @@ functions/library/generated: doc-support/result
 %.section.xml: %.section.md
 	$(PANDOC) $^ -t docbook \
 		$(pandoc_flags) \
-	| cat  > $@
+		-o $@
 
 %.chapter.xml: %.chapter.md
 	$(PANDOC) $^ -t docbook \
 		--top-level-division=chapter \
 		$(pandoc_flags) \
-	| cat  > $@
+		-o $@

nixos/doc/manual/from_md/administration/boot-problems.section.xml

@@ -3,11 +3,11 @@
   <para>
     If NixOS fails to boot, there are a number of kernel command line
     parameters that may help you to identify or fix the issue. You can
-    add these parameters in the GRUB boot menu by pressing
-    <quote>e</quote> to modify the selected boot entry and editing the
-    line starting with <literal>linux</literal>. The following are some
-    useful kernel command line parameters that are recognised by the
-    NixOS boot scripts or by systemd:
+    add these parameters in the GRUB boot menu by pressing “e” to modify
+    the selected boot entry and editing the line starting with
+    <literal>linux</literal>. The following are some useful kernel
+    command line parameters that are recognised by the NixOS boot
+    scripts or by systemd:
   </para>
   <variablelist>
     <varlistentry>
@@ -44,7 +44,7 @@
         <para>
           Like <literal>boot.debug1</literal>, but runs stage1 until
           kernel modules are loaded and device nodes are created. This
-          may help with e.g. making the keyboard work.
+          may help with e.g. making the keyboard work.
         </para>
       </listitem>
     </varlistentry>
@@ -117,7 +117,7 @@
     if you’d chosen <quote>ignore the error and continue</quote>.
   </para>
   <para>
-    If no login prompts or X11 login screens appear (e.g. due to hanging
+    If no login prompts or X11 login screens appear (e.g. due to hanging
     dependencies), you can press Alt+ArrowUp. If you’re lucky, this will
     start rescue mode (described above). (Also note that since most
     units have a 90-second timeout before systemd gives up on them, the

nixos/doc/manual/from_md/release-notes/rl-2111.section.xml

@@ -1,5 +1,5 @@
-<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="release-21.11">
-  <title>Release 21.11 (<quote>?</quote>, 2021.11/??)</title>
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-release-21.11">
+  <title>Release 21.11 (“?”, 2021.11/??)</title>
   <para>
     In addition to numerous new and upgraded packages, this release has
     the following highlights:
@@ -12,7 +12,7 @@
       </para>
     </listitem>
   </itemizedlist>
-  <section xml:id="highlights">
+  <section xml:id="sec-release-21.11-highlights">
     <title>Highlights</title>
     <itemizedlist spacing="compact">
       <listitem>
@@ -22,7 +22,7 @@
       </listitem>
     </itemizedlist>
   </section>
-  <section xml:id="new-services">
+  <section xml:id="sec-release-21.11-new-services">
     <title>New Services</title>
     <itemizedlist>
       <listitem>
@@ -50,7 +50,7 @@
       </listitem>
     </itemizedlist>
   </section>
-  <section xml:id="backward-incompatibilities">
+  <section xml:id="sec-release-21.11-incompatibilities">
     <title>Backward Incompatibilities</title>
     <itemizedlist>
       <listitem>
@@ -311,7 +311,7 @@
       </listitem>
     </itemizedlist>
   </section>
-  <section xml:id="other-notable-changes">
+  <section xml:id="sec-release-21.11-notable-changes">
     <title>Other Notable Changes</title>
     <para>
     </para>

nixos/doc/manual/md-to-db.sh

@@ -8,25 +8,31 @@
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 pushd $DIR
 
+# NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).
+# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
+pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
+pandoc_flags=(
+  # media extraction and diagram-generator.lua not needed
+  "--lua-filter=$DIR/../../../doc/labelless-link-is-xref.lua"
+  -f "commonmark${pandoc_commonmark_enabled_extensions}+smart"
+  -t docbook
+)
+
 OUT="$DIR/from_md"
 mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$')
 
 for mf in ${MD_FILES[*]}; do
   if [ "${mf: -11}" == ".section.md" ]; then
     mkdir -p $(dirname "$OUT/$mf")
-    pandoc "$mf" -t docbook \
-      --extract-media=media \
-      -f markdown+smart \
-    | cat  > "$OUT/${mf%".section.md"}.section.xml"
+    pandoc "$mf" "${pandoc_flags[@]}" \
+      -o "$OUT/${mf%".section.md"}.section.xml"
   fi
 
   if [ "${mf: -11}" == ".chapter.md" ]; then
     mkdir -p $(dirname "$OUT/$mf")
-    pandoc "$mf" -t docbook \
+    pandoc "$mf" "${pandoc_flags[@]}" \
       --top-level-division=chapter \
-      --extract-media=media \
-      -f markdown+smart \
-    | cat  > "$OUT/${mf%".chapter.md"}.chapter.xml"
+      -o "$OUT/${mf%".chapter.md"}.chapter.xml"
   fi
 done
 

nixos/doc/manual/release-notes/rl-2111.section.md

@@ -1,14 +1,14 @@
-# Release 21.11 (“?”, 2021.11/??) {#release-21.11}
+# Release 21.11 (“?”, 2021.11/??) {#sec-release-21.11}
 
 In addition to numerous new and upgraded packages, this release has the following highlights:
 
 * Support is planned until the end of April 2022, handing over to 22.05.
 
-## Highlights
+## Highlights {#sec-release-21.11-highlights}
 
 * PHP now defaults to PHP 8.0, updated from 7.4.
 
-## New Services
+## New Services {#sec-release-21.11-new-services}
 
 * [geoipupdate](https://github.com/maxmind/geoipupdate), a GeoIP
   database updater from MaxMind. Available as
@@ -22,7 +22,7 @@ In addition to numerous new and upgraded packages, this release has the followin
   implementation of the Common Address Redundancy Protocol (CARP). Available as
   [networking.ucarp](options.html#opt-networking.ucarp.enable).
 
-## Backward Incompatibilities
+## Backward Incompatibilities {#sec-release-21.11-incompatibilities}
 
 * The `staticjinja` package has been upgraded from 1.0.4 to 2.0.0
 
@@ -85,4 +85,4 @@ In addition to numerous new and upgraded packages, this release has the followin
   - GitVersionTree
   - NDeskOptions
 
-## Other Notable Changes
+## Other Notable Changes {#sec-release-21.11-notable-changes}