diff options
| author | pennae <github@quasiparticle.net> | 2023-01-05 06:16:46 +0100 |
|---|---|---|
| committer | pennae <github@quasiparticle.net> | 2023-01-10 10:32:00 +0100 |
| commit | bf92eaebe4afd03f029292f8cf5efa333fd0078a (patch) | |
| tree | 09d11e228801022c45c3edae5c609e291b3c206b /nixos | |
| parent | dc7788efb8bcbe68d1183cf7ee281186315802ca (diff) | |
| download | nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.tar nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.tar.gz nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.tar.bz2 nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.tar.lz nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.tar.xz nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.tar.zst nixpkgs-bf92eaebe4afd03f029292f8cf5efa333fd0078a.zip | |
nixos/manual: generate module chapters with md-to-db.sh
Diffstat (limited to 'nixos')
78 files changed, 271 insertions, 271 deletions
diff --git a/nixos/doc/manual/md-to-db.sh b/nixos/doc/manual/md-to-db.sh index 4698e94f508..abf9417c50a 100755 --- a/nixos/doc/manual/md-to-db.sh +++ b/nixos/doc/manual/md-to-db.sh @@ -50,3 +50,18 @@ 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" +done + +popd diff --git a/nixos/modules/i18n/input-method/default.nix b/nixos/modules/i18n/input-method/default.nix index 3fa1f4c643d..452b0d7b264 100644 --- a/nixos/modules/i18n/input-method/default.nix +++ b/nixos/modules/i18n/input-method/default.nix @@ -66,8 +66,7 @@ in meta = { maintainers = with lib.maintainers; [ ericsagnes ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc default.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 > default.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./default.xml; }; diff --git a/nixos/modules/i18n/input-method/default.xml b/nixos/modules/i18n/input-method/default.xml index 23295211980..b3706086bef 100644 --- a/nixos/modules/i18n/input-method/default.xml +++ b/nixos/modules/i18n/input-method/default.xml @@ -234,7 +234,7 @@ i18n.inputMethod = { }; </programlisting> <para> - Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"></xref> + Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar" /> option can be used to choose uim toolbar. </para> </section> diff --git a/nixos/modules/programs/digitalbitbox/doc.md b/nixos/modules/programs/digitalbitbox/default.md index 9bca14e97ff..9bca14e97ff 100644 --- a/nixos/modules/programs/digitalbitbox/doc.md +++ b/nixos/modules/programs/digitalbitbox/default.md diff --git a/nixos/modules/programs/digitalbitbox/default.nix b/nixos/modules/programs/digitalbitbox/default.nix index 2aaa307782d..fb18c52187b 100644 --- a/nixos/modules/programs/digitalbitbox/default.nix +++ b/nixos/modules/programs/digitalbitbox/default.nix @@ -33,9 +33,8 @@ in }; meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > doc.xml` - doc = ./doc.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + doc = ./default.xml; maintainers = with lib.maintainers; [ vidbina ]; }; } diff --git a/nixos/modules/programs/digitalbitbox/doc.xml b/nixos/modules/programs/digitalbitbox/default.xml index 30150640504..d5e1110bafb 100644 --- a/nixos/modules/programs/digitalbitbox/doc.xml +++ b/nixos/modules/programs/digitalbitbox/default.xml @@ -13,11 +13,11 @@ programs.digitalbitbox.enable = true; </programlisting> <para> and bundles the <literal>digitalbitbox</literal> package (see - <xref linkend="sec-digitalbitbox-package"></xref>), which contains - the <literal>dbb-app</literal> and <literal>dbb-cli</literal> - binaries, along with the hardware module (see - <xref linkend="sec-digitalbitbox-hardware-module"></xref>) which - sets up the necessary udev rules to access the device. + <xref linkend="sec-digitalbitbox-package" />), which contains the + <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, + along with the hardware module (see + <xref linkend="sec-digitalbitbox-hardware-module" />) which sets up + the necessary udev rules to access the device. </para> <para> Enabling the digitalbitbox module is pretty much the easiest way to @@ -25,7 +25,7 @@ programs.digitalbitbox.enable = true; </para> <para> For more information, see - <link xlink:href="https://digitalbitbox.com/start_linux" role="uri">https://digitalbitbox.com/start_linux</link>. + <link xlink:href="https://digitalbitbox.com/start_linux">https://digitalbitbox.com/start_linux</link>. </para> <section xml:id="sec-digitalbitbox-package"> <title>Package</title> diff --git a/nixos/modules/programs/plotinus.nix b/nixos/modules/programs/plotinus.nix index 3f7bbba42b9..cc73df2f791 100644 --- a/nixos/modules/programs/plotinus.nix +++ b/nixos/modules/programs/plotinus.nix @@ -8,8 +8,7 @@ in { meta = { maintainers = pkgs.plotinus.meta.maintainers; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc plotinus.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 > plotinus.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./plotinus.xml; }; diff --git a/nixos/modules/programs/plotinus.xml b/nixos/modules/programs/plotinus.xml index 6d5147eaa7e..eb8c65f94bc 100644 --- a/nixos/modules/programs/plotinus.xml +++ b/nixos/modules/programs/plotinus.xml @@ -6,7 +6,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://github.com/p-e-w/plotinus" role="uri">https://github.com/p-e-w/plotinus</link> + <link xlink:href="https://github.com/p-e-w/plotinus">https://github.com/p-e-w/plotinus</link> </para> <para> Plotinus is a searchable command palette in every modern GTK diff --git a/nixos/modules/programs/zsh/oh-my-zsh.nix b/nixos/modules/programs/zsh/oh-my-zsh.nix index 7a8fd88414a..a2d6eb14bdf 100644 --- a/nixos/modules/programs/zsh/oh-my-zsh.nix +++ b/nixos/modules/programs/zsh/oh-my-zsh.nix @@ -142,7 +142,6 @@ in }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc oh-my-zsh.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 > oh-my-zsh.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./oh-my-zsh.xml; } diff --git a/nixos/modules/programs/zsh/oh-my-zsh.xml b/nixos/modules/programs/zsh/oh-my-zsh.xml index 6125ba1488a..be868326c25 100644 --- a/nixos/modules/programs/zsh/oh-my-zsh.xml +++ b/nixos/modules/programs/zsh/oh-my-zsh.xml @@ -93,7 +93,7 @@ <section xml:id="module-programs-oh-my-zsh-packaging-customizations"> <title>Package your own customizations</title> <para> - If third-party customizations (e.g. new themes) are supposed to be + If third-party customizations (e.g. new themes) are supposed to be added to <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind: </para> diff --git a/nixos/modules/security/acme/doc.md b/nixos/modules/security/acme/default.md index 8ff97b55f68..8ff97b55f68 100644 --- a/nixos/modules/security/acme/doc.md +++ b/nixos/modules/security/acme/default.md diff --git a/nixos/modules/security/acme/default.nix b/nixos/modules/security/acme/default.nix index dfa3742dacc..baa7a516ce3 100644 --- a/nixos/modules/security/acme/default.nix +++ b/nixos/modules/security/acme/default.nix @@ -916,8 +916,7 @@ in { meta = { maintainers = lib.teams.acme.members; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc doc.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 > doc.xml` - doc = ./doc.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + doc = ./default.xml; }; } diff --git a/nixos/modules/security/acme/doc.xml b/nixos/modules/security/acme/default.xml index 42c73300d8b..766421c6237 100644 --- a/nixos/modules/security/acme/doc.xml +++ b/nixos/modules/security/acme/default.xml @@ -19,25 +19,24 @@ <para> To use the ACME module, you must accept the provider’s terms of service by setting - <xref linkend="opt-security.acme.acceptTerms"></xref> to + <xref linkend="opt-security.acme.acceptTerms" /> to <literal>true</literal>. The Let’s Encrypt ToS can be found <link xlink:href="https://letsencrypt.org/repository/">here</link>. </para> <para> You must also set an email address to be used when creating accounts with Let’s Encrypt. You can set this for all certs with - <xref linkend="opt-security.acme.defaults.email"></xref> and/or on - a per-cert basis with - <xref linkend="opt-security.acme.certs._name_.email"></xref>. This + <xref linkend="opt-security.acme.defaults.email" /> and/or on a + per-cert basis with + <xref linkend="opt-security.acme.certs._name_.email" />. This address is only used for registration and renewal reminders, and cannot be used to administer the certificates in any way. </para> <para> Alternatively, you can use a different ACME server by changing the - <xref linkend="opt-security.acme.defaults.server"></xref> option - to a provider of your choosing, or just change the server for one - cert with - <xref linkend="opt-security.acme.certs._name_.server"></xref>. + <xref linkend="opt-security.acme.defaults.server" /> option to a + provider of your choosing, or just change the server for one cert + with <xref linkend="opt-security.acme.certs._name_.server" />. </para> <para> You will need an HTTP server or DNS server for verification. For @@ -173,7 +172,7 @@ security.acme.certs."foo.example.com" = { <filename>/var/lib/acme/foo.example.com</filename>. </para> <para> - Refer to <xref linkend="ch-options"></xref> for all available + Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-security.acme.certs">security.acme</link> module. @@ -275,9 +274,10 @@ systemd.services.dns-rfc2136-conf = { <para> You must follow the guide above on configuring DNS-01 validation first, however instead of setting the options for one certificate - (e.g. <xref linkend="opt-security.acme.certs._name_.dnsProvider"></xref>) - you will set them as defaults - (e.g. <xref linkend="opt-security.acme.defaults.dnsProvider"></xref>). + (e.g. + <xref linkend="opt-security.acme.certs._name_.dnsProvider" />) you + will set them as defaults (e.g. + <xref linkend="opt-security.acme.defaults.dnsProvider" />). </para> <programlisting> # Configure ACME appropriately diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix index bb037fc13ee..5489aac0111 100644 --- a/nixos/modules/services/backup/borgbackup.nix +++ b/nixos/modules/services/backup/borgbackup.nix @@ -226,8 +226,7 @@ let in { meta.maintainers = with maintainers; [ dotlambda ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc borgbackup.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 > borgbackup.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./borgbackup.xml; ###### interface diff --git a/nixos/modules/services/backup/borgbackup.xml b/nixos/modules/services/backup/borgbackup.xml index 1c1233b1124..1b864d6cdd5 100644 --- a/nixos/modules/services/backup/borgbackup.xml +++ b/nixos/modules/services/backup/borgbackup.xml @@ -6,7 +6,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://borgbackup.readthedocs.io/" role="uri">https://borgbackup.readthedocs.io/</link> + <link xlink:href="https://borgbackup.readthedocs.io/">https://borgbackup.readthedocs.io/</link> </para> <para> <link xlink:href="https://www.borgbackup.org/">BorgBackup</link> @@ -200,9 +200,9 @@ sudo borg init --encryption=repokey-blake2 \ protect your data from disk failure, ransomware and theft. </para> <para> - It can be installed in NixOS e.g. by adding + It can be installed in NixOS e.g. by adding <literal>pkgs.vorta</literal> to - <xref linkend="opt-environment.systemPackages"></xref>. + <xref linkend="opt-environment.systemPackages" />. </para> <para> Details about using Vorta can be found under diff --git a/nixos/modules/services/databases/foundationdb.nix b/nixos/modules/services/databases/foundationdb.nix index 0cdb832e4bc..3d72d8ec6d2 100644 --- a/nixos/modules/services/databases/foundationdb.nix +++ b/nixos/modules/services/databases/foundationdb.nix @@ -424,8 +424,7 @@ in }; }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc foundationdb.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 > foundationdb.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./foundationdb.xml; meta.maintainers = with lib.maintainers; [ thoughtpolice ]; } diff --git a/nixos/modules/services/databases/foundationdb.xml b/nixos/modules/services/databases/foundationdb.xml index e65458779d1..e4a01260421 100644 --- a/nixos/modules/services/databases/foundationdb.xml +++ b/nixos/modules/services/databases/foundationdb.xml @@ -6,7 +6,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://apple.github.io/foundationdb/" role="uri">https://apple.github.io/foundationdb/</link> + <link xlink:href="https://apple.github.io/foundationdb/">https://apple.github.io/foundationdb/</link> </para> <para> <emphasis>Maintainer:</emphasis> Austin Seipp @@ -417,7 +417,7 @@ $ sudo -u foundationdb fdbbackup status -t default FoundationDB is a complex piece of software, and requires careful administration to properly use. Full documentation for administration can be found here: - <link xlink:href="https://apple.github.io/foundationdb/" role="uri">https://apple.github.io/foundationdb/</link>. + <link xlink:href="https://apple.github.io/foundationdb/">https://apple.github.io/foundationdb/</link>. </para> </section> </chapter> diff --git a/nixos/modules/services/databases/postgresql.nix b/nixos/modules/services/databases/postgresql.nix index 9a9a083b7c3..40a1acb39a3 100644 --- a/nixos/modules/services/databases/postgresql.nix +++ b/nixos/modules/services/databases/postgresql.nix @@ -585,8 +585,7 @@ in }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc postgresql.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 > postgresql.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./postgresql.xml; meta.maintainers = with lib.maintainers; [ thoughtpolice danbst ]; } diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml index 7ca03264e36..6aa2a3812ff 100644 --- a/nixos/modules/services/databases/postgresql.xml +++ b/nixos/modules/services/databases/postgresql.xml @@ -6,10 +6,10 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="http://www.postgresql.org/docs/" role="uri">http://www.postgresql.org/docs/</link> + <link xlink:href="http://www.postgresql.org/docs/">http://www.postgresql.org/docs/</link> </para> <para> - PostgreSQL is an advanced, free relational database. <!-- MORE --> + PostgreSQL is an advanced, free relational database. </para> <section xml:id="module-services-postgres-configuring"> <title>Configuring</title> @@ -23,17 +23,17 @@ services.postgresql.package = pkgs.postgresql_11; </programlisting> <para> Note that you are required to specify the desired version of - PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since + PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for - <xref linkend="opt-services.postgresql.package"></xref> such as - the most recent release of PostgreSQL. + <xref linkend="opt-services.postgresql.package" /> such as the + most recent release of PostgreSQL. </para> <para> By default, PostgreSQL stores its databases in <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using - <xref linkend="opt-services.postgresql.dataDir"></xref>, e.g. + <xref linkend="opt-services.postgresql.dataDir" />, e.g. </para> <programlisting> services.postgresql.dataDir = "/data/postgresql"; @@ -122,7 +122,7 @@ $ nix-instantiate --eval -A postgresql_13.psqlSchema the new one. You may supply arguments like <literal>--jobs 4</literal> and <literal>--link</literal> to speedup migration process. See - <link xlink:href="https://www.postgresql.org/docs/current/pgupgrade.html" role="uri">https://www.postgresql.org/docs/current/pgupgrade.html</link> + <link xlink:href="https://www.postgresql.org/docs/current/pgupgrade.html">https://www.postgresql.org/docs/current/pgupgrade.html</link> for details. </para> </listitem> @@ -130,10 +130,9 @@ $ nix-instantiate --eval -A postgresql_13.psqlSchema <para> Change postgresql package in NixOS configuration to the one you were upgrading to via - <xref linkend="opt-services.postgresql.package"></xref>. - Rebuild NixOS. This should start new postgres using upgraded - data directory and all services you stopped during the - upgrade. + <xref linkend="opt-services.postgresql.package" />. Rebuild + NixOS. This should start new postgres using upgraded data + directory and all services you stopped during the upgrade. </para> </listitem> <listitem> @@ -151,9 +150,8 @@ $ nix-instantiate --eval -A postgresql_13.psqlSchema <para> For PostgreSQL < 14, run (as <literal>su -l postgres</literal> in the - <xref linkend="opt-services.postgresql.dataDir"></xref>, - in this example - <filename>/var/lib/postgresql/13</filename>): + <xref linkend="opt-services.postgresql.dataDir" />, in + this example <filename>/var/lib/postgresql/13</filename>): </para> <programlisting> $ ./analyze_new_cluster.sh diff --git a/nixos/modules/services/desktops/flatpak.nix b/nixos/modules/services/desktops/flatpak.nix index 367d367d0bc..b08d7db226d 100644 --- a/nixos/modules/services/desktops/flatpak.nix +++ b/nixos/modules/services/desktops/flatpak.nix @@ -7,8 +7,7 @@ let cfg = config.services.flatpak; in { meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc flatpak.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 > flatpak.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./flatpak.xml; maintainers = pkgs.flatpak.meta.maintainers; }; diff --git a/nixos/modules/services/desktops/flatpak.xml b/nixos/modules/services/desktops/flatpak.xml index 3a4cfc5ea40..6230a7b1fa0 100644 --- a/nixos/modules/services/desktops/flatpak.xml +++ b/nixos/modules/services/desktops/flatpak.xml @@ -6,7 +6,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://github.com/flatpak/flatpak/wiki" role="uri">https://github.com/flatpak/flatpak/wiki</link> + <link xlink:href="https://github.com/flatpak/flatpak/wiki">https://github.com/flatpak/flatpak/wiki</link> </para> <para> Flatpak is a system for building, distributing, and running diff --git a/nixos/modules/services/development/blackfire.nix b/nixos/modules/services/development/blackfire.nix index 7d3365efa84..58ef75d23da 100644 --- a/nixos/modules/services/development/blackfire.nix +++ b/nixos/modules/services/development/blackfire.nix @@ -11,8 +11,7 @@ let in { meta = { maintainers = pkgs.blackfire.meta.maintainers; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc blackfire.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 > blackfire.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./blackfire.xml; }; diff --git a/nixos/modules/services/development/blackfire.xml b/nixos/modules/services/development/blackfire.xml index f5e62218632..99afaa11e04 100644 --- a/nixos/modules/services/development/blackfire.xml +++ b/nixos/modules/services/development/blackfire.xml @@ -6,7 +6,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://blackfire.io/docs/introduction" role="uri">https://blackfire.io/docs/introduction</link> + <link xlink:href="https://blackfire.io/docs/introduction">https://blackfire.io/docs/introduction</link> </para> <para> <link xlink:href="https://blackfire.io">Blackfire</link> is a diff --git a/nixos/modules/services/editors/emacs.nix b/nixos/modules/services/editors/emacs.nix index d30fd07577c..2aa38298716 100644 --- a/nixos/modules/services/editors/emacs.nix +++ b/nixos/modules/services/editors/emacs.nix @@ -99,7 +99,6 @@ in environment.variables.EDITOR = mkIf cfg.defaultEditor (mkOverride 900 "${editorScript}/bin/emacseditor"); }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc emacs.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 > emacs.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./emacs.xml; } diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml index 5e4f3e67427..d510556c29c 100644 --- a/nixos/modules/services/editors/emacs.xml +++ b/nixos/modules/services/editors/emacs.xml @@ -10,11 +10,11 @@ <para> Emacs runs within a graphical desktop environment using the X Window System, but works equally well on a text terminal. Under macOS, a - "Mac port" edition is available, which uses Apple's native - GUI frameworks. + <quote>Mac port</quote> edition is available, which uses Apple’s + native GUI frameworks. </para> <para> - Nixpkgs provides a superior environment for running Emacs. It's + Nixpkgs provides a superior environment for running Emacs. It’s simple to create custom builds by overriding the default packages. Chaotic collections of Emacs Lisp code and extensions can be brought under control using declarative package management. NixOS even @@ -25,8 +25,8 @@ <title>Installing Emacs</title> <para> Emacs can be installed in the normal way for Nix (see - <xref linkend="sec-package-management"></xref>). In addition, a - NixOS <emphasis>service</emphasis> can be enabled. + <xref linkend="sec-package-management" />). In addition, a NixOS + <emphasis>service</emphasis> can be enabled. </para> <section xml:id="module-services-emacs-releases"> <title>The Different Releases of Emacs</title> @@ -63,14 +63,14 @@ </term> <listitem> <para> - Emacs with the "Mac port" patches, providing a - more native look and feel under macOS. + Emacs with the <quote>Mac port</quote> patches, providing + a more native look and feel under macOS. </para> </listitem> </varlistentry> </variablelist> <para> - If those aren't suitable, then the following imitation Emacs + If those aren’t suitable, then the following imitation Emacs editors are also available in Nixpkgs: <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, @@ -207,9 +207,9 @@ nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages <para> If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see - <xref linkend="sec-declarative-package-mgmt"></xref>). Simply - modify your file <filename>configuration.nix</filename> to make - it contain: + <xref linkend="sec-declarative-package-mgmt" />). Simply modify + your file <filename>configuration.nix</filename> to make it + contain: <anchor xml:id="module-services-emacs-configuration-nix" /> </para> <programlisting> @@ -224,7 +224,7 @@ nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages In this case, the next <command>nixos-rebuild switch</command> will take care of adding your <command>emacs</command> to the <varname>PATH</varname> environment variable (see - <xref linkend="sec-changing-config"></xref>). + <xref linkend="sec-changing-config" />). </para> <para> If you are not on NixOS or want to install this particular Emacs @@ -292,7 +292,7 @@ in [...] NixOS provides an optional <command>systemd</command> service which launches <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">Emacs - daemon</link> with the user's login session. + daemon</link> with the user’s login session. </para> <para> <emphasis>Source:</emphasis> @@ -315,7 +315,7 @@ services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; }; <literal>emacsWithPackages</literal>. </para> <para> - Ensure that the Emacs server is enabled for your user's Emacs + Ensure that the Emacs server is enabled for your user’s Emacs configuration, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to @@ -353,7 +353,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <section xml:id="module-services-emacs-editor-variable"> <title>Configuring the <varname>EDITOR</varname> variable</title> <para> - If <xref linkend="opt-services.emacs.defaultEditor"></xref> is + If <xref linkend="opt-services.emacs.defaultEditor" /> is <literal>true</literal>, the <varname>EDITOR</varname> variable will be set to a wrapper script which launches <command>emacsclient</command>. @@ -452,7 +452,7 @@ systemctl --user enable emacs <para> To install the DocBook 5.0 schemas, either add <varname>pkgs.docbook5</varname> to - <xref linkend="opt-environment.systemPackages"></xref> + <xref linkend="opt-environment.systemPackages" /> (<link linkend="sec-declarative-package-mgmt">NixOS</link>), or run <literal>nix-env -f '<nixpkgs>' -iA docbook5</literal> (<link linkend="sec-ad-hoc-packages">Nix</link>). diff --git a/nixos/modules/services/hardware/trezord.nix b/nixos/modules/services/hardware/trezord.nix index 708f02fafc2..ae19b7f3e5b 100644 --- a/nixos/modules/services/hardware/trezord.nix +++ b/nixos/modules/services/hardware/trezord.nix @@ -8,8 +8,7 @@ in { ### docs meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc trezord.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 > trezord.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./trezord.xml; }; diff --git a/nixos/modules/services/hardware/trezord.xml b/nixos/modules/services/hardware/trezord.xml index bf9409c7d63..6cdff821980 100644 --- a/nixos/modules/services/hardware/trezord.xml +++ b/nixos/modules/services/hardware/trezord.xml @@ -12,7 +12,7 @@ <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>. For more information, guides and documentation, see - <link xlink:href="https://wiki.trezor.io" role="uri">https://wiki.trezor.io</link>. + <link xlink:href="https://wiki.trezor.io">https://wiki.trezor.io</link>. </para> <para> To enable Trezor support, add the following to your diff --git a/nixos/modules/services/mail/mailman.nix b/nixos/modules/services/mail/mailman.nix index 622efd87e7b..89c11a5d2f7 100644 --- a/nixos/modules/services/mail/mailman.nix +++ b/nixos/modules/services/mail/mailman.nix @@ -642,8 +642,7 @@ in { meta = { maintainers = with lib.maintainers; [ lheckemann qyliss ma27 ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc mailman.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 > mailman.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./mailman.xml; }; diff --git a/nixos/modules/services/matrix/mjolnir.nix b/nixos/modules/services/matrix/mjolnir.nix index 372b8ced1c2..d568beb2e7a 100644 --- a/nixos/modules/services/matrix/mjolnir.nix +++ b/nixos/modules/services/matrix/mjolnir.nix @@ -236,8 +236,7 @@ in }; meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc mjolnir.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 > mjolnir.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./mjolnir.xml; maintainers = with maintainers; [ jojosch ]; }; diff --git a/nixos/modules/services/matrix/synapse.nix b/nixos/modules/services/matrix/synapse.nix index 4f87744f8cc..fff2e31abe6 100644 --- a/nixos/modules/services/matrix/synapse.nix +++ b/nixos/modules/services/matrix/synapse.nix @@ -801,8 +801,7 @@ in { meta = { buildDocsInSandbox = false; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc synapse.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 > synapse.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./synapse.xml; maintainers = teams.matrix.members; }; diff --git a/nixos/modules/services/matrix/synapse.xml b/nixos/modules/services/matrix/synapse.xml index 822f2c324ad..62c3c62d3d1 100644 --- a/nixos/modules/services/matrix/synapse.xml +++ b/nixos/modules/services/matrix/synapse.xml @@ -131,7 +131,7 @@ in { <literal>services.matrix-synapse.settings.enable_registration = true;</literal>. Otherwise, or you can generate a registration secret with <command>pwgen -s 64 1</command> and set it with - <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret"></xref>. + <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />. To create a new user or admin, run the following after you have set the secret and have rebuilt NixOS: </para> @@ -151,7 +151,7 @@ Success! <warning> <para> When using - <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret"></xref>, + <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />, the secret will end up in the world-readable store. Instead it’s recommended to deploy the secret in an additional file like this: @@ -173,9 +173,9 @@ registration_shared_secret: your-very-secret-secret <citerefentry><refentrytitle>nixops</refentrytitle><manvolnum>1</manvolnum></citerefentry> or <link xlink:href="https://github.com/Mic92/sops-nix/">sops-nix</link> - to - e.g. <filename>/run/secrets/matrix-shared-secret</filename> - and ensure that it’s readable by + to e.g. + <filename>/run/secrets/matrix-shared-secret</filename> and + ensure that it’s readable by <literal>matrix-synapse</literal>. </para> </listitem> @@ -217,7 +217,7 @@ registration_shared_secret: your-very-secret-secret <literal>https://element.myhostname.example.org</literal> and <literal>https://element.example.org</literal>. Alternatively, you can use the hosted copy at - <link xlink:href="https://app.element.io/" role="uri">https://app.element.io/</link>, + <link xlink:href="https://app.element.io/">https://app.element.io/</link>, or use other web clients or native client applications. Due to the <literal>/.well-known</literal> urls set up done above, many clients should fill in the required connection details diff --git a/nixos/modules/services/misc/gitlab.nix b/nixos/modules/services/misc/gitlab.nix index c5eed5960e5..892e5307fef 100644 --- a/nixos/modules/services/misc/gitlab.nix +++ b/nixos/modules/services/misc/gitlab.nix @@ -1502,8 +1502,7 @@ in { }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc gitlab.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 > gitlab.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./gitlab.xml; } diff --git a/nixos/modules/services/misc/gitlab.xml b/nixos/modules/services/misc/gitlab.xml index c2c4dc895e9..69c5cd16e01 100644 --- a/nixos/modules/services/misc/gitlab.xml +++ b/nixos/modules/services/misc/gitlab.xml @@ -97,7 +97,7 @@ services.gitlab = { enabled for fetching incoming mail. </para> <para> - Refer to <xref linkend="ch-options"></xref> for all available + Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module. diff --git a/nixos/modules/services/misc/sourcehut/sourcehut.md b/nixos/modules/services/misc/sourcehut/default.md index 44d58aa0bef..44d58aa0bef 100644 --- a/nixos/modules/services/misc/sourcehut/sourcehut.md +++ b/nixos/modules/services/misc/sourcehut/default.md diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix index c95761bbe97..38531b96961 100644 --- a/nixos/modules/services/misc/sourcehut/default.nix +++ b/nixos/modules/services/misc/sourcehut/default.nix @@ -1390,8 +1390,7 @@ in '') ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc sourcehut.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 > sourcehut.xml` - meta.doc = ./sourcehut.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + meta.doc = ./default.xml; meta.maintainers = with maintainers; [ tomberek ]; } diff --git a/nixos/modules/services/misc/sourcehut/sourcehut.xml b/nixos/modules/services/misc/sourcehut/default.xml index d54a9c74417..cc309903889 100644 --- a/nixos/modules/services/misc/sourcehut/sourcehut.xml +++ b/nixos/modules/services/misc/sourcehut/default.xml @@ -97,14 +97,14 @@ in { </para> </section> <section xml:id="module-services-sourcehut-httpd"> - <title>Using an alternative webserver as reverse-proxy - (e.g. <literal>httpd</literal>)</title> + <title>Using an alternative webserver as reverse-proxy (e.g. + <literal>httpd</literal>)</title> <para> By default, <literal>nginx</literal> is used as reverse-proxy for - <literal>sourcehut</literal>. However, it’s possible to use - e.g. <literal>httpd</literal> by explicitly disabling + <literal>sourcehut</literal>. However, it’s possible to use e.g. + <literal>httpd</literal> by explicitly disabling <literal>nginx</literal> using - <xref linkend="opt-services.nginx.enable"></xref> and fixing the + <xref linkend="opt-services.nginx.enable" /> and fixing the <literal>settings</literal>. </para> </section> diff --git a/nixos/modules/services/misc/taskserver/doc.md b/nixos/modules/services/misc/taskserver/default.md index ee3b3908e2a..ee3b3908e2a 100644 --- a/nixos/modules/services/misc/taskserver/doc.md +++ b/nixos/modules/services/misc/taskserver/default.md diff --git a/nixos/modules/services/misc/taskserver/default.nix b/nixos/modules/services/misc/taskserver/default.nix index 9a97d236452..dbb3ede4010 100644 --- a/nixos/modules/services/misc/taskserver/default.nix +++ b/nixos/modules/services/misc/taskserver/default.nix @@ -566,7 +566,6 @@ in { }) ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc doc.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 > doc.xml` - meta.doc = ./doc.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + meta.doc = ./default.xml; } diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/default.xml index 06ec397661a..a4668731491 100644 --- a/nixos/modules/services/misc/taskserver/doc.xml +++ b/nixos/modules/services/misc/taskserver/default.xml @@ -7,7 +7,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://taskwarrior.org/docs/#taskd" role="uri">https://taskwarrior.org/docs/#taskd</link> + <link xlink:href="https://taskwarrior.org/docs/#taskd">https://taskwarrior.org/docs/#taskd</link> </para> <section xml:id="module-services-taskserver-configuration"> <title>Configuration</title> @@ -43,8 +43,8 @@ imperatively, the <command>nixos-taskserver</command> tool is used for addition and deletion of organisations along with users and groups defined by - <xref linkend="opt-services.taskserver.organisations"></xref> and - as well for imperative set up. + <xref linkend="opt-services.taskserver.organisations" /> and as + well for imperative set up. </para> <para> The tool is designed to not interfere if the command is used to diff --git a/nixos/modules/services/misc/weechat.nix b/nixos/modules/services/misc/weechat.nix index 3fa408d9c88..cb119f7c3fc 100644 --- a/nixos/modules/services/misc/weechat.nix +++ b/nixos/modules/services/misc/weechat.nix @@ -59,7 +59,6 @@ in }; }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc weechat.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 > weechat.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./weechat.xml; } diff --git a/nixos/modules/services/monitoring/parsedmarc.md b/nixos/modules/services/monitoring/parsedmarc.md index 5a17f79da5d..eac07e0cc9f 100644 --- a/nixos/modules/services/monitoring/parsedmarc.md +++ b/nixos/modules/services/monitoring/parsedmarc.md @@ -25,7 +25,7 @@ services.parsedmarc = { Note that GeoIP provisioning is disabled in the example for simplicity, but should be turned on for fully functional reports. -## Local mail +## Local mail {#module-services-parsedmarc-local-mail} Instead of watching an external inbox, a local inbox can be automatically provisioned. The recipient's name is by default set to `dmarc`, but can be configured in @@ -49,7 +49,7 @@ services.parsedmarc = { }; ``` -## Grafana and GeoIP +## Grafana and GeoIP {#module-services-parsedmarc-grafana-geoip} The reports can be visualized and summarized with parsedmarc's official Grafana dashboard. For all views to work, and for the data to be complete, GeoIP databases are also required. The following example diff --git a/nixos/modules/services/monitoring/parsedmarc.nix b/nixos/modules/services/monitoring/parsedmarc.nix index 40c76b80455..e663e46cf00 100644 --- a/nixos/modules/services/monitoring/parsedmarc.nix +++ b/nixos/modules/services/monitoring/parsedmarc.nix @@ -539,8 +539,7 @@ in }; }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc parsedmarc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > parsedmarc.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./parsedmarc.xml; meta.maintainers = [ lib.maintainers.talyz ]; } diff --git a/nixos/modules/services/monitoring/parsedmarc.xml b/nixos/modules/services/monitoring/parsedmarc.xml index 2db5f48d160..f34d47429d8 100644 --- a/nixos/modules/services/monitoring/parsedmarc.xml +++ b/nixos/modules/services/monitoring/parsedmarc.xml @@ -31,7 +31,7 @@ services.parsedmarc = { simplicity, but should be turned on for fully functional reports. </para> </section> - <section xml:id="local-mail"> + <section xml:id="module-services-parsedmarc-local-mail"> <title>Local mail</title> <para> Instead of watching an external inbox, a local inbox can be @@ -57,7 +57,7 @@ services.parsedmarc = { }; </programlisting> </section> - <section xml:id="grafana-and-geoip"> + <section xml:id="module-services-parsedmarc-grafana-geoip"> <title>Grafana and GeoIP</title> <para> The reports can be visualized and summarized with parsedmarc’s diff --git a/nixos/modules/services/monitoring/prometheus/exporters.nix b/nixos/modules/services/monitoring/prometheus/exporters.nix index e9401334352..33df9e37fb9 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters.nix @@ -323,8 +323,7 @@ in ); meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc exporters.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 > exporters.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./exporters.xml; maintainers = [ maintainers.willibutz ]; }; diff --git a/nixos/modules/services/network-filesystems/litestream/litestream.md b/nixos/modules/services/network-filesystems/litestream/default.md index 8d8486507b7..8d8486507b7 100644 --- a/nixos/modules/services/network-filesystems/litestream/litestream.md +++ b/nixos/modules/services/network-filesystems/litestream/default.md diff --git a/nixos/modules/services/network-filesystems/litestream/default.nix b/nixos/modules/services/network-filesystems/litestream/default.nix index 73ef81a0f56..5559198d580 100644 --- a/nixos/modules/services/network-filesystems/litestream/default.nix +++ b/nixos/modules/services/network-filesystems/litestream/default.nix @@ -95,7 +95,6 @@ in users.groups.litestream = {}; }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc litestream.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 > litestream.xml` - meta.doc = ./litestream.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + meta.doc = ./default.xml; } diff --git a/nixos/modules/services/network-filesystems/litestream/litestream.xml b/nixos/modules/services/network-filesystems/litestream/default.xml index 0a2cfc3db1e..0a2cfc3db1e 100644 --- a/nixos/modules/services/network-filesystems/litestream/litestream.xml +++ b/nixos/modules/services/network-filesystems/litestream/default.xml diff --git a/nixos/modules/services/networking/firefox-syncserver.nix b/nixos/modules/services/networking/firefox-syncserver.nix index 9733fb16d90..663010999ff 100644 --- a/nixos/modules/services/networking/firefox-syncserver.nix +++ b/nixos/modules/services/networking/firefox-syncserver.nix @@ -311,8 +311,7 @@ in meta = { maintainers = with lib.maintainers; [ pennae ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc firefox-syncserver.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > firefox-syncserver.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./firefox-syncserver.xml; }; } diff --git a/nixos/modules/services/networking/mosquitto.nix b/nixos/modules/services/networking/mosquitto.nix index 270450cb0c6..6c7e1ed720e 100644 --- a/nixos/modules/services/networking/mosquitto.nix +++ b/nixos/modules/services/networking/mosquitto.nix @@ -671,8 +671,7 @@ in meta = { maintainers = with lib.maintainers; [ pennae ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc mosquitto.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > mosquitto.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./mosquitto.xml; }; } diff --git a/nixos/modules/services/networking/pleroma.nix b/nixos/modules/services/networking/pleroma.nix index 287e189e2fe..bbd52176767 100644 --- a/nixos/modules/services/networking/pleroma.nix +++ b/nixos/modules/services/networking/pleroma.nix @@ -147,7 +147,6 @@ in { }; meta.maintainers = with lib.maintainers; [ ninjatrappeur ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc pleroma.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 > pleroma.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./pleroma.xml; } diff --git a/nixos/modules/services/networking/pleroma.xml b/nixos/modules/services/networking/pleroma.xml index 9a29512d363..2a81e166d10 100644 --- a/nixos/modules/services/networking/pleroma.xml +++ b/nixos/modules/services/networking/pleroma.xml @@ -60,9 +60,8 @@ $ sudo -u postgres psql -f setup.psql </para> <para> This is an example of configuration, where - <xref linkend="opt-services.pleroma.configs"></xref> option - contains the content of the file <literal>config.exs</literal>, - generated + <xref linkend="opt-services.pleroma.configs" /> option contains + the content of the file <literal>config.exs</literal>, generated <link linkend="module-services-pleroma-generate-config">in the first section</link>, but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is @@ -109,9 +108,9 @@ services.pleroma = { </programlisting> <para> Secrets must be moved into a file pointed by - <xref linkend="opt-services.pleroma.secretConfigFile"></xref>, in - our case <literal>/var/lib/pleroma/secrets.exs</literal>. This - file can be created copying the previously generated + <xref linkend="opt-services.pleroma.secretConfigFile" />, in our + case <literal>/var/lib/pleroma/secrets.exs</literal>. This file + can be created copying the previously generated <literal>config.exs</literal> file and then removing all the settings, except the secrets. This is an example </para> @@ -136,7 +135,7 @@ config :web_push_encryption, :vapid_details, </programlisting> <para> Note that the lines of the same configuration group are comma - separated (i.e. all the lines end with a comma, except the last + separated (i.e. all the lines end with a comma, except the last one), so when the lines with passwords are added or removed, commas must be adjusted accordingly. </para> @@ -156,7 +155,7 @@ $ ssh -L 4000:localhost:4000 myuser@example.net </programlisting> <para> and then accessing - <link xlink:href="http://localhost:4000" role="uri">http://localhost:4000</link> + <link xlink:href="http://localhost:4000">http://localhost:4000</link> from a web browser. </para> </section> diff --git a/nixos/modules/services/networking/prosody.nix b/nixos/modules/services/networking/prosody.nix index 3c685e30b03..5ef472bf9c2 100644 --- a/nixos/modules/services/networking/prosody.nix +++ b/nixos/modules/services/networking/prosody.nix @@ -905,7 +905,6 @@ in }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc prosody.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 > prosody.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./prosody.xml; } diff --git a/nixos/modules/services/networking/yggdrasil.nix b/nixos/modules/services/networking/yggdrasil.nix index 3c3ff4ce3c4..fd2dede1357 100644 --- a/nixos/modules/services/networking/yggdrasil.nix +++ b/nixos/modules/services/networking/yggdrasil.nix @@ -193,8 +193,7 @@ in { environment.systemPackages = [ cfg.package ]; }); meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc yggdrasil.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 > yggdrasil.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./yggdrasil.xml; maintainers = with lib.maintainers; [ gazally ehmry ]; }; diff --git a/nixos/modules/services/networking/yggdrasil.xml b/nixos/modules/services/networking/yggdrasil.xml index 5b6f63b3ae0..35388ea4cf4 100644 --- a/nixos/modules/services/networking/yggdrasil.xml +++ b/nixos/modules/services/networking/yggdrasil.xml @@ -6,7 +6,7 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://yggdrasil-network.github.io/" role="uri">https://yggdrasil-network.github.io/</link> + <link xlink:href="https://yggdrasil-network.github.io/">https://yggdrasil-network.github.io/</link> </para> <para> Yggdrasil is an early-stage implementation of a fully end-to-end diff --git a/nixos/modules/services/search/meilisearch.nix b/nixos/modules/services/search/meilisearch.nix index 3983b1b2c92..98364e141c2 100644 --- a/nixos/modules/services/search/meilisearch.nix +++ b/nixos/modules/services/search/meilisearch.nix @@ -9,8 +9,7 @@ in { meta.maintainers = with maintainers; [ Br1ght0ne happysalada ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc meilisearch.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > meilisearch.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./meilisearch.xml; ###### interface diff --git a/nixos/modules/services/web-apps/discourse.nix b/nixos/modules/services/web-apps/discourse.nix index 2796ba8c379..b00aeab89b0 100644 --- a/nixos/modules/services/web-apps/discourse.nix +++ b/nixos/modules/services/web-apps/discourse.nix @@ -1080,8 +1080,7 @@ in ]; }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc discourse.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 > discourse.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./discourse.xml; meta.maintainers = [ lib.maintainers.talyz ]; } diff --git a/nixos/modules/services/web-apps/discourse.xml b/nixos/modules/services/web-apps/discourse.xml index 1aec160b7b4..ff7534ba5a5 100644 --- a/nixos/modules/services/web-apps/discourse.xml +++ b/nixos/modules/services/web-apps/discourse.xml @@ -36,8 +36,8 @@ security.acme.acceptTerms = true; <title>Using a regular TLS certificate</title> <para> To set up TLS using a regular certificate and key on file, use the - <xref linkend="opt-services.discourse.sslCertificate"></xref> and - <xref linkend="opt-services.discourse.sslCertificateKey"></xref> + <xref linkend="opt-services.discourse.sslCertificate" /> and + <xref linkend="opt-services.discourse.sslCertificateKey" /> options: </para> <programlisting> @@ -61,22 +61,20 @@ services.discourse = { <para> Discourse uses PostgreSQL to store most of its data. A database will automatically be enabled and a database and role created - unless - <xref linkend="opt-services.discourse.database.host"></xref> is + unless <xref linkend="opt-services.discourse.database.host" /> is changed from its default of <literal>null</literal> or - <xref linkend="opt-services.discourse.database.createLocally"></xref> + <xref linkend="opt-services.discourse.database.createLocally" /> is set to <literal>false</literal>. </para> <para> External database access can also be configured by setting - <xref linkend="opt-services.discourse.database.host"></xref>, - <xref linkend="opt-services.discourse.database.username"></xref> - and - <xref linkend="opt-services.discourse.database.passwordFile"></xref> - as appropriate. Note that you need to manually create a database + <xref linkend="opt-services.discourse.database.host" />, + <xref linkend="opt-services.discourse.database.username" /> and + <xref linkend="opt-services.discourse.database.passwordFile" /> as + appropriate. Note that you need to manually create a database called <literal>discourse</literal> (or the name you chose in - <xref linkend="opt-services.discourse.database.name"></xref>) and - allow the configured database user full access to it. + <xref linkend="opt-services.discourse.database.name" />) and allow + the configured database user full access to it. </para> </section> <section xml:id="module-services-discourse-mail"> @@ -127,19 +125,18 @@ services.discourse = { If you want to use a different domain for your outgoing email (for example <literal>example.com</literal> instead of <literal>discourse.example.com</literal>) you should set - <xref linkend="opt-services.discourse.mail.notificationEmailAddress"></xref> + <xref linkend="opt-services.discourse.mail.notificationEmailAddress" /> and - <xref linkend="opt-services.discourse.mail.contactEmailAddress"></xref> + <xref linkend="opt-services.discourse.mail.contactEmailAddress" /> manually. </para> <note> <para> Setup of TLS for incoming email is currently only configured - automatically when a regular TLS certificate is used, i.e. when - <xref linkend="opt-services.discourse.sslCertificate"></xref> - and - <xref linkend="opt-services.discourse.sslCertificateKey"></xref> - are set. + automatically when a regular TLS certificate is used, i.e. when + <xref linkend="opt-services.discourse.sslCertificate" /> and + <xref linkend="opt-services.discourse.sslCertificateKey" /> are + set. </para> </note> </section> @@ -148,8 +145,8 @@ services.discourse = { <para> Additional site settings and backend settings, for which no explicit NixOS options are provided, can be set in - <xref linkend="opt-services.discourse.siteSettings"></xref> and - <xref linkend="opt-services.discourse.backendSettings"></xref> + <xref linkend="opt-services.discourse.siteSettings" /> and + <xref linkend="opt-services.discourse.backendSettings" /> respectively. </para> <section xml:id="module-services-discourse-site-settings"> @@ -158,15 +155,15 @@ services.discourse = { <quote>Site settings</quote> are the settings that can be changed through the Discourse UI. Their <emphasis>default</emphasis> values can be set using - <xref linkend="opt-services.discourse.siteSettings"></xref>. + <xref linkend="opt-services.discourse.siteSettings" />. </para> <para> Settings are expressed as a Nix attribute set which matches the structure of the configuration in <link xlink:href="https://github.com/discourse/discourse/blob/master/config/site_settings.yml">config/site_settings.yml</link>. To find a setting’s path, you only need to care about the first - two levels; i.e. its category (e.g. <literal>login</literal>) - and name (e.g. <literal>invite_only</literal>). + two levels; i.e. its category (e.g. <literal>login</literal>) + and name (e.g. <literal>invite_only</literal>). </para> <para> Settings containing secret data should be set to an attribute @@ -245,12 +242,12 @@ services.discourse = { <title>Plugins</title> <para> You can install Discourse plugins using the - <xref linkend="opt-services.discourse.plugins"></xref> option. + <xref linkend="opt-services.discourse.plugins" /> option. Pre-packaged plugins are provided in <literal><your_discourse_package_here>.plugins</literal>. If you want the full suite of plugins provided through <literal>nixpkgs</literal>, you can also set the - <xref linkend="opt-services.discourse.package"></xref> option to + <xref linkend="opt-services.discourse.package" /> option to <literal>pkgs.discourseAllPlugins</literal>. </para> <para> @@ -284,10 +281,10 @@ services.discourse = { Some plugins provide <link linkend="module-services-discourse-site-settings">site settings</link>. Their defaults can be configured using - <xref linkend="opt-services.discourse.siteSettings"></xref>, just - like regular site settings. To find the names of these settings, - look in the <literal>config/settings.yml</literal> file of the - plugin repo. + <xref linkend="opt-services.discourse.siteSettings" />, just like + regular site settings. To find the names of these settings, look + in the <literal>config/settings.yml</literal> file of the plugin + repo. </para> <para> For example, to add the diff --git a/nixos/modules/services/web-apps/grocy.nix b/nixos/modules/services/web-apps/grocy.nix index 187eed8f0c8..1d5244b42ce 100644 --- a/nixos/modules/services/web-apps/grocy.nix +++ b/nixos/modules/services/web-apps/grocy.nix @@ -167,8 +167,7 @@ in { meta = { maintainers = with maintainers; [ ma27 ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc grocy.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 > grocy.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./grocy.xml; }; } diff --git a/nixos/modules/services/web-apps/jitsi-meet.nix b/nixos/modules/services/web-apps/jitsi-meet.nix index 2c2d5f21319..b82138a307b 100644 --- a/nixos/modules/services/web-apps/jitsi-meet.nix +++ b/nixos/modules/services/web-apps/jitsi-meet.nix @@ -451,8 +451,7 @@ in }; }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc jitsi-meet.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 > jitsi-meet.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./jitsi-meet.xml; meta.maintainers = lib.teams.jitsi.members; } diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index 8d7f046aa11..7b3814485b9 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -674,8 +674,7 @@ in mkIf createLocalMySQL (mkDefault dbPkg); }; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc keycloak.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 > keycloak.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./keycloak.xml; meta.maintainers = [ maintainers.talyz ]; } diff --git a/nixos/modules/services/web-apps/keycloak.xml b/nixos/modules/services/web-apps/keycloak.xml index a15cd9a4188..037ae7ff75a 100644 --- a/nixos/modules/services/web-apps/keycloak.xml +++ b/nixos/modules/services/web-apps/keycloak.xml @@ -15,8 +15,8 @@ An administrative user with the username <literal>admin</literal> is automatically created in the <literal>master</literal> realm. Its initial password can be configured by setting - <xref linkend="opt-services.keycloak.initialAdminPassword"></xref> - and defaults to <literal>changeme</literal>. The password is not + <xref linkend="opt-services.keycloak.initialAdminPassword" /> and + defaults to <literal>changeme</literal>. The password is not stored safely and should be changed immediately in the admin panel. </para> @@ -32,30 +32,30 @@ <para> Keycloak can be used with either PostgreSQL, MariaDB or MySQL. Which one is used can be configured in - <xref linkend="opt-services.keycloak.database.type"></xref>. The + <xref linkend="opt-services.keycloak.database.type" />. The selected database will automatically be enabled and a database and role created unless - <xref linkend="opt-services.keycloak.database.host"></xref> is - changed from its default of <literal>localhost</literal> or - <xref linkend="opt-services.keycloak.database.createLocally"></xref> - is set to <literal>false</literal>. + <xref linkend="opt-services.keycloak.database.host" /> is changed + from its default of <literal>localhost</literal> or + <xref linkend="opt-services.keycloak.database.createLocally" /> is + set to <literal>false</literal>. </para> <para> External database access can also be configured by setting - <xref linkend="opt-services.keycloak.database.host"></xref>, - <xref linkend="opt-services.keycloak.database.name"></xref>, - <xref linkend="opt-services.keycloak.database.username"></xref>, - <xref linkend="opt-services.keycloak.database.useSSL"></xref> and - <xref linkend="opt-services.keycloak.database.caCert"></xref> as + <xref linkend="opt-services.keycloak.database.host" />, + <xref linkend="opt-services.keycloak.database.name" />, + <xref linkend="opt-services.keycloak.database.username" />, + <xref linkend="opt-services.keycloak.database.useSSL" /> and + <xref linkend="opt-services.keycloak.database.caCert" /> as appropriate. Note that you need to manually create the database and allow the configured database user full access to it. </para> <para> - <xref linkend="opt-services.keycloak.database.passwordFile"></xref> + <xref linkend="opt-services.keycloak.database.passwordFile" /> must be set to the path to a file containing the password used to log in to the database. If - <xref linkend="opt-services.keycloak.database.host"></xref> and - <xref linkend="opt-services.keycloak.database.createLocally"></xref> + <xref linkend="opt-services.keycloak.database.host" /> and + <xref linkend="opt-services.keycloak.database.createLocally" /> are kept at their defaults, the database role <literal>keycloak</literal> with that password is provisioned on the local database instance. @@ -72,20 +72,20 @@ <para> The hostname is used to build the public URL used as base for all frontend requests and must be configured through - <xref linkend="opt-services.keycloak.settings.hostname"></xref>. + <xref linkend="opt-services.keycloak.settings.hostname" />. </para> <note> <para> If you’re migrating an old Wildfly based Keycloak instance and want to keep compatibility with your current clients, you’ll likely want to set - <xref linkend="opt-services.keycloak.settings.http-relative-path"></xref> + <xref linkend="opt-services.keycloak.settings.http-relative-path" /> to <literal>/auth</literal>. See the option description for more details. </para> </note> <para> - <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel"></xref> + <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel" /> determines whether Keycloak should force all requests to go through the frontend URL. By default, Keycloak allows backend requests to instead use its local hostname or IP address and may @@ -110,8 +110,8 @@ both <link xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM formatted</link>. Their paths should be set through - <xref linkend="opt-services.keycloak.sslCertificate"></xref> and - <xref linkend="opt-services.keycloak.sslCertificateKey"></xref>. + <xref linkend="opt-services.keycloak.sslCertificate" /> and + <xref linkend="opt-services.keycloak.sslCertificateKey" />. </para> <warning> <para> @@ -124,8 +124,7 @@ <title>Themes</title> <para> You can package custom themes and make them visible to Keycloak - through <xref linkend="opt-services.keycloak.themes"></xref>. See - the + through <xref linkend="opt-services.keycloak.themes" />. See the <link xlink:href="https://www.keycloak.org/docs/latest/server_development/#_themes">Themes section of the Keycloak Server Development Guide</link> and the description of the aforementioned NixOS option for more @@ -136,7 +135,7 @@ <title>Configuration file settings</title> <para> Keycloak server configuration parameters can be set in - <xref linkend="opt-services.keycloak.settings"></xref>. These + <xref linkend="opt-services.keycloak.settings" />. These correspond directly to options in <filename>conf/keycloak.conf</filename>. Some of the most important parameters are documented as suboptions, the rest can be @@ -150,8 +149,7 @@ containing the attribute <literal>_secret</literal> - a string pointing to a file containing the value the option should be set to. See the description of - <xref linkend="opt-services.keycloak.settings"></xref> for an - example. + <xref linkend="opt-services.keycloak.settings" /> for an example. </para> </section> <section xml:id="module-services-keycloak-example-config"> diff --git a/nixos/modules/services/web-apps/lemmy.nix b/nixos/modules/services/web-apps/lemmy.nix index 267584dd0ca..db1518ec293 100644 --- a/nixos/modules/services/web-apps/lemmy.nix +++ b/nixos/modules/services/web-apps/lemmy.nix @@ -6,8 +6,7 @@ let in { meta.maintainers = with maintainers; [ happysalada ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc lemmy.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > lemmy.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./lemmy.xml; imports = [ diff --git a/nixos/modules/services/web-apps/matomo-doc.md b/nixos/modules/services/web-apps/matomo.md index f5536a35f7a..f5536a35f7a 100644 --- a/nixos/modules/services/web-apps/matomo-doc.md +++ b/nixos/modules/services/web-apps/matomo.md diff --git a/nixos/modules/services/web-apps/matomo.nix b/nixos/modules/services/web-apps/matomo.nix index eb204eb3f3d..706e41cbed0 100644 --- a/nixos/modules/services/web-apps/matomo.nix +++ b/nixos/modules/services/web-apps/matomo.nix @@ -325,9 +325,8 @@ in { }; meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc matomo-doc.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 > matomo-doc.xml` - doc = ./matomo-doc.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + doc = ./matomo.xml; maintainers = with lib.maintainers; [ florianjacob ]; }; } diff --git a/nixos/modules/services/web-apps/matomo-doc.xml b/nixos/modules/services/web-apps/matomo.xml index 0254d978698..0d76e4d7e59 100644 --- a/nixos/modules/services/web-apps/matomo-doc.xml +++ b/nixos/modules/services/web-apps/matomo.xml @@ -38,11 +38,11 @@ GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; <literal>matomo</literal> database user (without needing a password), but no other users. For more information on passwordless login, see - <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" role="uri">https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/</link>. + <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/">https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/</link>. </para> <para> - Of course, you can use password based authentication as well, - e.g. when the database is not on the same host. + Of course, you can use password based authentication as well, e.g. + when the database is not on the same host. </para> </section> <section xml:id="module-services-matomo-archive-processing"> @@ -75,7 +75,7 @@ GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user in the <literal>matomo</literal> group or root to access the file. For more information, see - <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" role="uri">https://matomo.org/faq/how-to-install/faq_138/</link>. + <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/">https://matomo.org/faq/how-to-install/faq_138/</link>. </para> </section> <section xml:id="module-services-matomo-issues"> diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix index 3d30c712f67..64e8e4ed5d6 100644 --- a/nixos/modules/services/web-apps/nextcloud.nix +++ b/nixos/modules/services/web-apps/nextcloud.nix @@ -1146,7 +1146,6 @@ in { } ]); - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc nextcloud.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 > nextcloud.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./nextcloud.xml; } diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml index 0998f29bac2..40d94cb5858 100644 --- a/nixos/modules/services/web-apps/nextcloud.xml +++ b/nixos/modules/services/web-apps/nextcloud.xml @@ -192,24 +192,24 @@ external storage such as S3. Please note that this won’t work anymore when using OpenSSL 3 for PHP’s openssl extension because this is implemented using the legacy cipher RC4. If - <xref linkend="opt-system.stateVersion"></xref> is + <xref linkend="opt-system.stateVersion" /> is <emphasis>above</emphasis> <literal>22.05</literal>, this is disabled by default. To turn it on again and for further information please refer to - <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE"></xref>. + <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE" />. </para> </listitem> </itemizedlist> </section> <section xml:id="module-services-nextcloud-httpd"> - <title>Using an alternative webserver as reverse-proxy - (e.g. <literal>httpd</literal>)</title> + <title>Using an alternative webserver as reverse-proxy (e.g. + <literal>httpd</literal>)</title> <para> By default, <literal>nginx</literal> is used as reverse-proxy for - <literal>nextcloud</literal>. However, it’s possible to use - e.g. <literal>httpd</literal> by explicitly disabling + <literal>nextcloud</literal>. However, it’s possible to use e.g. + <literal>httpd</literal> by explicitly disabling <literal>nginx</literal> using - <xref linkend="opt-services.nginx.enable"></xref> and fixing the + <xref linkend="opt-services.nginx.enable" /> and fixing the settings <literal>listen.owner</literal> & <literal>listen.group</literal> in the <link linkend="opt-services.phpfpm.pools">corresponding @@ -268,13 +268,13 @@ Nextcloud apps are installed statefully through the web interface. Some apps may require extra PHP extensions to be installed. This can be configured with the - <xref linkend="opt-services.nextcloud.phpExtraExtensions"></xref> + <xref linkend="opt-services.nextcloud.phpExtraExtensions" /> setting. </para> <para> Alternatively, extra apps can also be declared with the - <xref linkend="opt-services.nextcloud.extraApps"></xref> setting. - When using this setting, apps can no longer be managed statefully + <xref linkend="opt-services.nextcloud.extraApps" /> setting. When + using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps. @@ -292,7 +292,7 @@ While minor and patch-level updates are no problem and can be done directly in the package-expression (and should be backported to supported stable branches after that), major-releases should be - added in a new attribute (e.g. Nextcloud + added in a new attribute (e.g. Nextcloud <literal>v19.0.0</literal> should be available in <literal>nixpkgs</literal> as <literal>pkgs.nextcloud19</literal>). To provide simple upgrade @@ -323,8 +323,8 @@ </programlisting> <para> Ideally we should make sure that it’s possible to jump two NixOS - versions forward: i.e. the warnings and the logic in the module - should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a + versions forward: i.e. the warnings and the logic in the module + should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a Nextcloud on 20.09. </para> </section> diff --git a/nixos/modules/services/web-apps/pict-rs.nix b/nixos/modules/services/web-apps/pict-rs.nix index ee9ff9b484f..5f02bce3a0a 100644 --- a/nixos/modules/services/web-apps/pict-rs.nix +++ b/nixos/modules/services/web-apps/pict-rs.nix @@ -5,8 +5,7 @@ let in { meta.maintainers = with maintainers; [ happysalada ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc pict-rs.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > pict-rs.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./pict-rs.xml; options.services.pict-rs = { diff --git a/nixos/modules/services/web-apps/pict-rs.xml b/nixos/modules/services/web-apps/pict-rs.xml index 6cae82e01ec..511da8012b7 100644 --- a/nixos/modules/services/web-apps/pict-rs.xml +++ b/nixos/modules/services/web-apps/pict-rs.xml @@ -30,8 +30,26 @@ services.pict-rs.enable = true; <para> This endpoint returns the following JSON structure on success with a 201 Created status - <literal>json { "files": [ { "delete_token": "JFvFhqJA98", "file": "lkWZDRvugm.jpg" }, { "delete_token": "kAYy9nk2WK", "file": "8qFS0QooAn.jpg" }, { "delete_token": "OxRpM3sf0Y", "file": "1hJaYfGE01.jpg" } ], "msg": "ok" }</literal> </para> + <programlisting language="json"> +{ + "files": [ + { + "delete_token": "JFvFhqJA98", + "file": "lkWZDRvugm.jpg" + }, + { + "delete_token": "kAYy9nk2WK", + "file": "8qFS0QooAn.jpg" + }, + { + "delete_token": "OxRpM3sf0Y", + "file": "1hJaYfGE01.jpg" + } + ], + "msg": "ok" +} +</programlisting> </listitem> <listitem> <para> @@ -53,8 +71,20 @@ services.pict-rs.enable = true; <literal>GET /image/details/original/{file}</literal> for getting the details of a full-resolution image. The returned JSON is structured like so: - <literal>json { "width": 800, "height": 537, "content_type": "image/webp", "created_at": [ 2020, 345, 67376, 394363487 ] }</literal> </para> + <programlisting language="json"> +{ + "width": 800, + "height": 537, + "content_type": "image/webp", + "created_at": [ + 2020, + 345, + 67376, + 394363487 + ] +} +</programlisting> </listitem> <listitem> <para> @@ -111,7 +141,11 @@ services.pict-rs.enable = true; </para> <para> An example of usage could be - <literal>GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0</literal> + </para> + <programlisting> +GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0 +</programlisting> + <para> which would create a 256x256px JPEG thumbnail and blur it </para> </listitem> diff --git a/nixos/modules/services/web-apps/plausible.nix b/nixos/modules/services/web-apps/plausible.nix index cb46a88cd9f..0475bb796cd 100644 --- a/nixos/modules/services/web-apps/plausible.nix +++ b/nixos/modules/services/web-apps/plausible.nix @@ -292,7 +292,6 @@ in { }; meta.maintainers = with maintainers; [ ma27 ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc plausible.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 > plausible.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh meta.doc = ./plausible.xml; } diff --git a/nixos/modules/services/web-servers/garage-doc.md b/nixos/modules/services/web-servers/garage.md index b1003e5dae1..b1003e5dae1 100644 --- a/nixos/modules/services/web-servers/garage-doc.md +++ b/nixos/modules/services/web-servers/garage.md diff --git a/nixos/modules/services/web-servers/garage.nix b/nixos/modules/services/web-servers/garage.nix index ed5b89f916c..afdb8044c29 100644 --- a/nixos/modules/services/web-servers/garage.nix +++ b/nixos/modules/services/web-servers/garage.nix @@ -9,9 +9,8 @@ let in { meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc garage-doc.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 > garage-doc.xml` - doc = ./garage-doc.xml; + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh + doc = ./garage.xml; maintainers = with pkgs.lib.maintainers; [ raitobezarius ]; }; diff --git a/nixos/modules/services/web-servers/garage-doc.xml b/nixos/modules/services/web-servers/garage.xml index 447a27d2bf8..cb9d50a2aa1 100644 --- a/nixos/modules/services/web-servers/garage-doc.xml +++ b/nixos/modules/services/web-servers/garage.xml @@ -16,7 +16,7 @@ <title>General considerations on upgrades</title> <para> Garage provides a cookbook documentation on how to upgrade: - <link xlink:href="https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/" role="uri">https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/</link> + <link xlink:href="https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/">https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/</link> </para> <warning> <para> @@ -36,7 +36,7 @@ <para> Until 1.0 is released, patch-level upgrades are considered as minor version upgrades. Minor version upgrades are considered as - major version upgrades. i.e. 0.6 to 0.7 is a major version + major version upgrades. i.e. 0.6 to 0.7 is a major version upgrade. </para> </warning> @@ -45,7 +45,7 @@ <para> <emphasis role="strong">Straightforward upgrades (patch-level upgrades).</emphasis> Upgrades must be performed one by one, - i.e. for each node, stop it, upgrade it : change + i.e. for each node, stop it, upgrade it : change <link linkend="opt-system.stateVersion">stateVersion</link> or <link linkend="opt-services.garage.package">services.garage.package</link>, restart it if it was not already by switching. @@ -110,7 +110,7 @@ </listitem> <listitem> <para> - Backup the metadata folder of ALL your nodes, e.g. for a + Backup the metadata folder of ALL your nodes, e.g. for a metadata directory (the default one) in <literal>/var/lib/garage/meta</literal>, you can run <literal>pushd /var/lib/garage; tar -acf meta-v0.7.tar.zst meta/; popd</literal>. @@ -166,7 +166,7 @@ While patch-level updates are no problem and can be done directly in the package-expression (and should be backported to supported stable branches after that), major-releases should be added in a - new attribute (e.g. Garage <literal>v0.8.0</literal> should be + new attribute (e.g. Garage <literal>v0.8.0</literal> should be available in <literal>nixpkgs</literal> as <literal>pkgs.garage_0_8_0</literal>). To provide simple upgrade paths it’s generally useful to backport those as well to stable @@ -196,8 +196,8 @@ </programlisting> <para> Ideally we should make sure that it’s possible to jump two NixOS - versions forward: i.e. the warnings and the logic in the module - should guard a user to upgrade from a Garage on e.g. 22.11 to a + versions forward: i.e. the warnings and the logic in the module + should guard a user to upgrade from a Garage on e.g. 22.11 to a Garage on 23.11. </para> </section> diff --git a/nixos/modules/services/x11/desktop-managers/gnome.nix b/nixos/modules/services/x11/desktop-managers/gnome.nix index 62535e996bb..63de2159476 100644 --- a/nixos/modules/services/x11/desktop-managers/gnome.nix +++ b/nixos/modules/services/x11/desktop-managers/gnome.nix @@ -66,8 +66,7 @@ in { meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `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` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./gnome.xml; maintainers = teams.gnome.members; }; diff --git a/nixos/modules/services/x11/desktop-managers/gnome.xml b/nixos/modules/services/x11/desktop-managers/gnome.xml index d1038bded00..2c46b39ead1 100644 --- a/nixos/modules/services/x11/desktop-managers/gnome.xml +++ b/nixos/modules/services/x11/desktop-managers/gnome.xml @@ -48,9 +48,9 @@ services.gnome.core-utilities.enable = false; <para> If you’d only like to omit a subset of the core utilities, you can use - <xref linkend="opt-environment.gnome.excludePackages"></xref>. - Note that this mechanism can only exclude core utilities, games - and core developer tools. + <xref linkend="opt-environment.gnome.excludePackages" />. Note + that this mechanism can only exclude core utilities, games and + core developer tools. </para> </section> <section xml:id="sec-gnome-disabling-services"> @@ -103,7 +103,7 @@ services.xserver.desktopManager.gnome.flashback.enableMetacity = true; <para> It is also possible to create custom sessions that replace Metacity with a different window manager using - <xref linkend="opt-services.xserver.desktopManager.gnome.flashback.customSessions"></xref>. + <xref linkend="opt-services.xserver.desktopManager.gnome.flashback.customSessions" />. </para> <para> The following example uses <literal>xmonad</literal> window @@ -128,8 +128,8 @@ services.xserver.desktopManager.gnome.flashback.customSessions = [ </para> <para> You can add them to - <xref linkend="opt-environment.systemPackages"></xref> and switch - to them with GNOME Tweaks. If you’d like to do this manually in + <xref linkend="opt-environment.systemPackages" /> and switch to + them with GNOME Tweaks. If you’d like to do this manually in dconf, change the values of the following keys: </para> <programlisting> @@ -204,13 +204,13 @@ environment.systemPackages = [ </warning> <para> You can override the default GSettings values using the - <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverrides"></xref> + <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverrides" /> option. </para> <para> Take note that whatever packages you want to override GSettings for, you need to add them to - <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverridePackages"></xref>. + <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverridePackages" />. </para> <para> You can use <literal>dconf-editor</literal> tool to explore which diff --git a/nixos/modules/services/x11/desktop-managers/pantheon.nix b/nixos/modules/services/x11/desktop-managers/pantheon.nix index 14a03c0408e..90990cd54da 100644 --- a/nixos/modules/services/x11/desktop-managers/pantheon.nix +++ b/nixos/modules/services/x11/desktop-managers/pantheon.nix @@ -17,8 +17,7 @@ in { meta = { - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc pantheon.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 > pantheon.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./pantheon.xml; maintainers = teams.pantheon.members; }; diff --git a/nixos/modules/services/x11/desktop-managers/pantheon.xml b/nixos/modules/services/x11/desktop-managers/pantheon.xml index 5aa575aeec4..1377927fe6a 100644 --- a/nixos/modules/services/x11/desktop-managers/pantheon.xml +++ b/nixos/modules/services/x11/desktop-managers/pantheon.xml @@ -35,8 +35,8 @@ services.pantheon.apps.enable = false; </programlisting> <para> You can also use - <xref linkend="opt-environment.pantheon.excludePackages"></xref> - to remove any other app (like <literal>elementary-mail</literal>). + <xref linkend="opt-environment.pantheon.excludePackages" /> to + remove any other app (like <literal>elementary-mail</literal>). </para> </section> <section xml:id="sec-pantheon-wingpanel-switchboard"> @@ -51,12 +51,12 @@ services.pantheon.apps.enable = false; <itemizedlist spacing="compact"> <listitem> <para> - <xref linkend="opt-services.xserver.desktopManager.pantheon.extraWingpanelIndicators"></xref> + <xref linkend="opt-services.xserver.desktopManager.pantheon.extraWingpanelIndicators" /> </para> </listitem> <listitem> <para> - <xref linkend="opt-services.xserver.desktopManager.pantheon.extraSwitchboardPlugs"></xref> + <xref linkend="opt-services.xserver.desktopManager.pantheon.extraSwitchboardPlugs" /> </para> </listitem> </itemizedlist> @@ -108,7 +108,7 @@ switchboard-with-plugs.override { </section> <section xml:id="sec-pantheon-faq"> <title>FAQ</title> - <variablelist> + <variablelist spacing="compact"> <varlistentry> <term> <anchor xml:id="sec-pantheon-faq-messed-up-theme" />I have diff --git a/nixos/modules/system/boot/loader/external/external.nix b/nixos/modules/system/boot/loader/external/external.nix index 5cf478e6c83..0f4f82da693 100644 --- a/nixos/modules/system/boot/loader/external/external.nix +++ b/nixos/modules/system/boot/loader/external/external.nix @@ -8,8 +8,7 @@ in { meta = { maintainers = with maintainers; [ cole-h grahamc raitobezarius ]; - # Don't edit the docbook xml directly, edit the md and generate it: - # `pandoc external.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > external.xml` + # Don't edit the docbook xml directly, edit the md and generate it using md-to-db.sh doc = ./external.xml; }; |