nixos/doc: Synchronize the Markdown generator with Nixpkgs

Switch to CommonMark with our extensions.
This commit is contained in:
Jan Tojnar 2021-06-18 00:07:00 +02:00
parent b26545db7e
commit f07dcbef64
No known key found for this signature in database
GPG key ID: 7FAB2A15F7A607A4
5 changed files with 35 additions and 28 deletions

View file

@ -3,6 +3,7 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$'
PANDOC ?= pandoc PANDOC ?= pandoc
pandoc_media_dir = media 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. # 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_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
pandoc_flags = --extract-media=$(pandoc_media_dir) \ pandoc_flags = --extract-media=$(pandoc_media_dir) \
@ -101,10 +102,10 @@ functions/library/generated: doc-support/result
%.section.xml: %.section.md %.section.xml: %.section.md
$(PANDOC) $^ -t docbook \ $(PANDOC) $^ -t docbook \
$(pandoc_flags) \ $(pandoc_flags) \
| cat > $@ -o $@
%.chapter.xml: %.chapter.md %.chapter.xml: %.chapter.md
$(PANDOC) $^ -t docbook \ $(PANDOC) $^ -t docbook \
--top-level-division=chapter \ --top-level-division=chapter \
$(pandoc_flags) \ $(pandoc_flags) \
| cat > $@ -o $@

View file

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

View file

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

View file

@ -8,25 +8,31 @@
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
pushd $DIR 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" OUT="$DIR/from_md"
mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$') mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$')
for mf in ${MD_FILES[*]}; do for mf in ${MD_FILES[*]}; do
if [ "${mf: -11}" == ".section.md" ]; then if [ "${mf: -11}" == ".section.md" ]; then
mkdir -p $(dirname "$OUT/$mf") mkdir -p $(dirname "$OUT/$mf")
pandoc "$mf" -t docbook \ pandoc "$mf" "${pandoc_flags[@]}" \
--extract-media=media \ -o "$OUT/${mf%".section.md"}.section.xml"
-f markdown+smart \
| cat > "$OUT/${mf%".section.md"}.section.xml"
fi fi
if [ "${mf: -11}" == ".chapter.md" ]; then if [ "${mf: -11}" == ".chapter.md" ]; then
mkdir -p $(dirname "$OUT/$mf") mkdir -p $(dirname "$OUT/$mf")
pandoc "$mf" -t docbook \ pandoc "$mf" "${pandoc_flags[@]}" \
--top-level-division=chapter \ --top-level-division=chapter \
--extract-media=media \ -o "$OUT/${mf%".chapter.md"}.chapter.xml"
-f markdown+smart \
| cat > "$OUT/${mf%".chapter.md"}.chapter.xml"
fi fi
done done

View file

@ -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: 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. * 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. * 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 * [geoipupdate](https://github.com/maxmind/geoipupdate), a GeoIP
database updater from MaxMind. Available as 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 implementation of the Common Address Redundancy Protocol (CARP). Available as
[networking.ucarp](options.html#opt-networking.ucarp.enable). [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 * 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 - GitVersionTree
- NDeskOptions - NDeskOptions
## Other Notable Changes ## Other Notable Changes {#sec-release-21.11-notable-changes}