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_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 $@

View file

@ -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 youd 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 youre 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

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">
<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>

View file

@ -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

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:
* 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}