diff options
105 files changed, 9381 insertions, 4807 deletions
diff --git a/doc/build-aux/pandoc-filters/myst-reader/roles.lua b/doc/build-aux/pandoc-filters/myst-reader/roles.lua index c33a688eeba7..f4ef6d390b40 100644 --- a/doc/build-aux/pandoc-filters/myst-reader/roles.lua +++ b/doc/build-aux/pandoc-filters/myst-reader/roles.lua @@ -17,9 +17,16 @@ function Inlines(inlines) if correct_tags then -- docutils supports alphanumeric strings separated by [-._:] -- We are slightly more liberal for simplicity. - local role = first.text:match('^{([-._+:%w]+)}$') - if role ~= nil then - inlines:remove(i) + -- Allow preceding punctuation (eg '('), otherwise '({file}`...`)' + -- does not match. Also allow anything followed by a non-breaking space + -- since pandoc emits those after certain abbreviations (e.g. e.g.). + local prefix, role = first.text:match('^(.*){([-._+:%w]+)}$') + if role ~= nil and (prefix == '' or prefix:match("^.*[%p ]$") ~= nil) then + if prefix == '' then + inlines:remove(i) + else + first.text = prefix + end second.attributes['role'] = role second.classes:insert('interpreted-text') end diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md index 946c08efd0a3..7129cf8723e6 100644 --- a/nixos/doc/manual/development/meta-attributes.section.md +++ b/nixos/doc/manual/development/meta-attributes.section.md @@ -40,6 +40,26 @@ file. $ nix-build nixos/release.nix -A manual.x86_64-linux ``` + This file should *not* usually be written by hand. Instead it is preferred + to write documentation using CommonMark and converting it to CommonMark + using pandoc. The simplest documentation can be converted using just + + ```ShellSession + $ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml + ``` + + More elaborate documentation may wish to add one or more of the pandoc + filters used to build the remainder of the manual, for example the GNOME + desktop uses + + ```ShellSession + $ pandoc gnome.md -t docbook --top-level-division=chapter \ + --extract-media=media -f markdown+smart \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \ + > gnome.xml + ``` + - `buildDocsInSandbox` indicates whether the option documentation for the module can be built in a derivation sandbox. This option is currently only honored for modules shipped by nixpkgs. User modules and modules taken from diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml index 9cc58afa1fdd..450a5f670f3a 100644 --- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml +++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml @@ -51,6 +51,27 @@ <programlisting> $ nix-build nixos/release.nix -A manual.x86_64-linux </programlisting> + <para> + This file should <emphasis>not</emphasis> usually be written by + hand. Instead it is preferred to write documentation using + CommonMark and converting it to CommonMark using pandoc. The + simplest documentation can be converted using just + </para> + <programlisting> +$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml +</programlisting> + <para> + More elaborate documentation may wish to add one or more of the + pandoc filters used to build the remainder of the manual, for + example the GNOME desktop uses + </para> + <programlisting> +$ pandoc gnome.md -t docbook --top-level-division=chapter \ + --extract-media=media -f markdown+smart \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \ + > gnome.xml +</programlisting> </listitem> <listitem> <para> diff --git a/nixos/doc/manual/md-to-db.sh b/nixos/doc/manual/md-to-db.sh index 4698e94f508b..a7421bed532e 100755 --- a/nixos/doc/manual/md-to-db.sh +++ b/nixos/doc/manual/md-to-db.sh @@ -50,3 +50,21 @@ for mf in ${MD_FILES[*]}; do done popd + +# now handle module chapters. we'll need extra checks to ensure that we don't process +# markdown files we're not interested in, so we'll require an x.nix file for ever x.md +# that we'll convert to xml. +pushd "$DIR/../../modules" + +mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$') + +for mf in ${MD_FILES[*]}; do + [ -f "${mf%.md}.nix" ] || continue + + pandoc --top-level-division=chapter "$mf" "${pandoc_flags[@]}" -o "${mf%.md}.xml" + sed -i -e '1 i <!-- Do not edit this file directly, edit its companion .md instead\ + and regenerate this file using nixos/doc/manual/md-to-db.sh -->' \ + "${mf%.md}.xml" +done + +popd diff --git a/nixos/modules/i18n/input-method/default.md b/nixos/modules/i18n/input-method/default.md new file mode 100644 index 000000000000..05ae12065c34 --- /dev/null +++ b/nixos/modules/i18n/input-method |