From f07dcbef6462c3858c74aabb565892f4608ca06c Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Fri, 18 Jun 2021 00:07:00 +0200 Subject: [PATCH] nixos/doc: Synchronize the Markdown generator with Nixpkgs Switch to CommonMark with our extensions. --- doc/Makefile | 5 +++-- .../administration/boot-problems.section.xml | 14 ++++++------ .../from_md/release-notes/rl-2111.section.xml | 12 +++++----- nixos/doc/manual/md-to-db.sh | 22 ++++++++++++------- .../manual/release-notes/rl-2111.section.md | 10 ++++----- 5 files changed, 35 insertions(+), 28 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index d4f1250c4d7..1d3a0e7ccbd 100644 --- a/doc/Makefile +++ b/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 $@ diff --git a/nixos/doc/manual/from_md/administration/boot-problems.section.xml b/nixos/doc/manual/from_md/administration/boot-problems.section.xml index 89871e7aeb6..b484d075818 100644 --- a/nixos/doc/manual/from_md/administration/boot-problems.section.xml +++ b/nixos/doc/manual/from_md/administration/boot-problems.section.xml @@ -3,11 +3,11 @@ 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 - e to modify the selected boot entry and editing the - line starting with linux. 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 + linux. The following are some useful kernel + command line parameters that are recognised by the NixOS boot + scripts or by systemd: @@ -44,7 +44,7 @@ Like boot.debug1, 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. @@ -117,7 +117,7 @@ if you’d chosen ignore the error and continue. - 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 diff --git a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml index 2b0bcb4b6e5..0908fb13726 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml @@ -1,5 +1,5 @@ -
- Release 21.11 (<quote>?</quote>, 2021.11/??) +
+ Release 21.11 (“?”, 2021.11/??) In addition to numerous new and upgraded packages, this release has the following highlights: @@ -12,7 +12,7 @@ -
+
Highlights @@ -22,7 +22,7 @@
-
+
New Services @@ -50,7 +50,7 @@
-
+
Backward Incompatibilities @@ -311,7 +311,7 @@
-
+
Other Notable Changes diff --git a/nixos/doc/manual/md-to-db.sh b/nixos/doc/manual/md-to-db.sh index fc4be7da22b..7949b42e8d8 100755 --- a/nixos/doc/manual/md-to-db.sh +++ b/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 diff --git a/nixos/doc/manual/release-notes/rl-2111.section.md b/nixos/doc/manual/release-notes/rl-2111.section.md index 968fdb0f3be..a603f735829 100644 --- a/nixos/doc/manual/release-notes/rl-2111.section.md +++ b/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}