nixos/doc: Synchronize the Markdown generator with Nixpkgs
Switch to CommonMark with our extensions.
This commit is contained in:
parent
b26545db7e
commit
f07dcbef64
|
@ -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 $@
|
||||||
|
|
|
@ -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 you’d chosen <quote>ignore the error and continue</quote>.
|
if you’d 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 you’re lucky, this will
|
dependencies), you can press Alt+ArrowUp. If you’re 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
|
||||||
|
|
|
@ -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>
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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}
|
||||||
|
|
Loading…
Reference in a new issue