nixos/oh-my-zsh: convert manual chapter to MD

3 files changed, 223 insertions, 115 deletions

diff --git a/nixos/modules/programs/zsh/oh-my-zsh.md b/nixos/modules/programs/zsh/oh-my-zsh.md
new file mode 100644
index 0000000000000..73d425244ce79
--- /dev/null
+++ b/nixos/modules/programs/zsh/oh-my-zsh.md
@@ -0,0 +1,109 @@
+# Oh my ZSH {#module-programs-zsh-ohmyzsh}
+
+[`oh-my-zsh`](https://ohmyz.sh/) is a framework to manage your [ZSH](https://www.zsh.org/)
+configuration including completion scripts for several CLI tools or custom
+prompt themes.
+
+## Basic usage {#module-programs-oh-my-zsh-usage}
+
+The module uses the `oh-my-zsh` package with all available
+features. The initial setup using Nix expressions is fairly similar to the
+configuration format of `oh-my-zsh`.
+```
+{
+  programs.zsh.ohMyZsh = {
+    enable = true;
+    plugins = [ "git" "python" "man" ];
+    theme = "agnoster";
+  };
+}
+```
+For a detailed explanation of these arguments please refer to the
+[`oh-my-zsh` docs](https://github.com/robbyrussell/oh-my-zsh/wiki).
+
+The expression generates the needed configuration and writes it into your
+`/etc/zshrc`.
+
+## Custom additions {#module-programs-oh-my-zsh-additions}
+
+Sometimes third-party or custom scripts such as a modified theme may be
+needed. `oh-my-zsh` provides the
+[`ZSH_CUSTOM`](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals)
+environment variable for this which points to a directory with additional
+scripts.
+
+The module can do this as well:
+```
+{
+  programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
+}
+```
+
+## Custom environments {#module-programs-oh-my-zsh-environments}
+
+There are several extensions for `oh-my-zsh` packaged in
+`nixpkgs`. One of them is
+[nix-zsh-completions](https://github.com/spwhitt/nix-zsh-completions)
+which bundles completion scripts and a plugin for `oh-my-zsh`.
+
+Rather than using a single mutable path for `ZSH_CUSTOM`,
+it's also possible to generate this path from a list of Nix packages:
+```
+{ pkgs, ... }:
+{
+  programs.zsh.ohMyZsh.customPkgs = [
+    pkgs.nix-zsh-completions
+    # and even more...
+  ];
+}
+```
+Internally a single store path will be created using
+`buildEnv`. Please refer to the docs of
+[`buildEnv`](https://nixos.org/nixpkgs/manual/#sec-building-environment)
+for further reference.
+
+*Please keep in mind that this is not compatible with
+`programs.zsh.ohMyZsh.custom` as it requires an immutable
+store path while `custom` shall remain mutable! An
+evaluation failure will be thrown if both `custom` and
+`customPkgs` are set.*
+
+## Package your own customizations {#module-programs-oh-my-zsh-packaging-customizations}
+
+If third-party customizations (e.g. new themes) are supposed to be added to
+`oh-my-zsh` there are several pitfalls to keep in mind:
+
+  - To comply with the default structure of `ZSH` the entire
+    output needs to be written to `$out/share/zsh.`
+
+  - Completion scripts are supposed to be stored at
+    `$out/share/zsh/site-functions`. This directory is part of the
+    [`fpath`](http://zsh.sourceforge.net/Doc/Release/Functions.html)
+    and the package should be compatible with pure `ZSH`
+    setups. The module will automatically link the contents of
+    `site-functions` to completions directory in the proper
+    store path.
+
+  - The `plugins` directory needs the structure
+    `pluginname/pluginname.plugin.zsh` as structured in the
+    [upstream repo.](https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins)
+
+A derivation for `oh-my-zsh` may look like this:
+```
+{ stdenv, fetchFromGitHub }:
+
+stdenv.mkDerivation rec {
+  name = "exemplary-zsh-customization-${version}";
+  version = "1.0.0";
+  src = fetchFromGitHub {
+    # path to the upstream repository
+  };
+
+  dontBuild = true;
+  installPhase = ''
+    mkdir -p $out/share/zsh/site-functions
+    cp {themes,plugins} $out/share/zsh
+    cp completions $out/share/zsh/site-functions
+  '';
+}
+```
diff --git a/nixos/modules/programs/zsh/oh-my-zsh.nix b/nixos/modules/programs/zsh/oh-my-zsh.nix
index 41ea31b0f122c..88b293bdfc62a 100644
--- a/nixos/modules/programs/zsh/oh-my-zsh.nix
+++ b/nixos/modules/programs/zsh/oh-my-zsh.nix
@@ -142,5 +142,7 @@ 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`
     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 9917dd022b9f7..c20659e83ccd5 100644
--- a/nixos/modules/programs/zsh/oh-my-zsh.xml
+++ b/nixos/modules/programs/zsh/oh-my-zsh.xml
@@ -1,76 +1,72 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="module-programs-zsh-ohmyzsh">
- <title>Oh my ZSH</title>
- <para>
-  <link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link> is a
-  framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link>
-  configuration including completion scripts for several CLI tools or custom
-  prompt themes.
- </para>
- <section xml:id="module-programs-oh-my-zsh-usage">
-  <title>Basic usage</title>
-
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-programs-zsh-ohmyzsh">
+  <title>Oh my ZSH</title>
   <para>
-   The module uses the <literal>oh-my-zsh</literal> package with all available
-   features. The initial setup using Nix expressions is fairly similar to the
-   configuration format of <literal>oh-my-zsh</literal>.
-<programlisting>
+    <link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link>
+    is a framework to manage your
+    <link xlink:href="https://www.zsh.org/">ZSH</link> configuration
+    including completion scripts for several CLI tools or custom prompt
+    themes.
+  </para>
+  <section xml:id="module-programs-oh-my-zsh-usage">
+    <title>Basic usage</title>
+    <para>
+      The module uses the <literal>oh-my-zsh</literal> package with all
+      available features. The initial setup using Nix expressions is
+      fairly similar to the configuration format of
+      <literal>oh-my-zsh</literal>.
+    </para>
+    <programlisting>
 {
   programs.zsh.ohMyZsh = {
     enable = true;
-    plugins = [ "git" "python" "man" ];
-    theme = "agnoster";
+    plugins = [ &quot;git&quot; &quot;python&quot; &quot;man&quot; ];
+    theme = &quot;agnoster&quot;;
   };
 }
 </programlisting>
-   For a detailed explanation of these arguments please refer to the
-   <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>
-   docs</link>.
-  </para>
-
-  <para>
-   The expression generates the needed configuration and writes it into your
-   <literal>/etc/zshrc</literal>.
-  </para>
- </section>
- <section xml:id="module-programs-oh-my-zsh-additions">
-  <title>Custom additions</title>
-
-  <para>
-   Sometimes third-party or custom scripts such as a modified theme may be
-   needed. <literal>oh-my-zsh</literal> provides the
-   <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>
-   environment variable for this which points to a directory with additional
-   scripts.
-  </para>
-
-  <para>
-   The module can do this as well:
-<programlisting>
+    <para>
+      For a detailed explanation of these arguments please refer to the
+      <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>
+      docs</link>.
+    </para>
+    <para>
+      The expression generates the needed configuration and writes it
+      into your <literal>/etc/zshrc</literal>.
+    </para>
+  </section>
+  <section xml:id="module-programs-oh-my-zsh-additions">
+    <title>Custom additions</title>
+    <para>
+      Sometimes third-party or custom scripts such as a modified theme
+      may be needed. <literal>oh-my-zsh</literal> provides the
+      <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>
+      environment variable for this which points to a directory with
+      additional scripts.
+    </para>
+    <para>
+      The module can do this as well:
+    </para>
+    <programlisting>
 {
-  programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
+  programs.zsh.ohMyZsh.custom = &quot;~/path/to/custom/scripts&quot;;
 }
 </programlisting>
-  </para>
- </section>
- <section xml:id="module-programs-oh-my-zsh-environments">
-  <title>Custom environments</title>
-
-  <para>
-   There are several extensions for <literal>oh-my-zsh</literal> packaged in
-   <literal>nixpkgs</literal>. One of them is
-   <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
-   which bundles completion scripts and a plugin for
-   <literal>oh-my-zsh</literal>.
-  </para>
-
-  <para>
-   Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>,
-   it's also possible to generate this path from a list of Nix packages:
-<programlisting>
+  </section>
+  <section xml:id="module-programs-oh-my-zsh-environments">
+    <title>Custom environments</title>
+    <para>
+      There are several extensions for <literal>oh-my-zsh</literal>
+      packaged in <literal>nixpkgs</literal>. One of them is
+      <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
+      which bundles completion scripts and a plugin for
+      <literal>oh-my-zsh</literal>.
+    </para>
+    <para>
+      Rather than using a single mutable path for
+      <literal>ZSH_CUSTOM</literal>, it's also possible to generate this
+      path from a list of Nix packages:
+    </para>
+    <programlisting>
 { pkgs, ... }:
 {
   programs.zsh.ohMyZsh.customPkgs = [
@@ -79,65 +75,67 @@
   ];
 }
 </programlisting>
-   Internally a single store path will be created using
-   <literal>buildEnv</literal>. Please refer to the docs of
-   <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>
-   for further reference.
-  </para>
-
-  <para>
-   <emphasis>Please keep in mind that this is not compatible with
-   <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable
-   store path while <literal>custom</literal> shall remain mutable! An
-   evaluation failure will be thrown if both <literal>custom</literal> and
-   <literal>customPkgs</literal> are set.</emphasis>
-  </para>
- </section>
- <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 added to
-   <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind:
-  </para>
-
-  <itemizedlist>
-   <listitem>
     <para>
-     To comply with the default structure of <literal>ZSH</literal> the entire
-     output needs to be written to <literal>$out/share/zsh.</literal>
+      Internally a single store path will be created using
+      <literal>buildEnv</literal>. Please refer to the docs of
+      <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>
+      for further reference.
     </para>
-   </listitem>
-   <listitem>
     <para>
-     Completion scripts are supposed to be stored at
-     <literal>$out/share/zsh/site-functions</literal>. This directory is part
-     of the
-     <link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>
-     and the package should be compatible with pure <literal>ZSH</literal>
-     setups. The module will automatically link the contents of
-     <literal>site-functions</literal> to completions directory in the proper
-     store path.
+      <emphasis>Please keep in mind that this is not compatible with
+      <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an
+      immutable store path while <literal>custom</literal> shall remain
+      mutable! An evaluation failure will be thrown if both
+      <literal>custom</literal> and <literal>customPkgs</literal> are
+      set.</emphasis>
     </para>
-   </listitem>
-   <listitem>
+  </section>
+  <section xml:id="module-programs-oh-my-zsh-packaging-customizations">
+    <title>Package your own customizations</title>
     <para>
-     The <literal>plugins</literal> directory needs the structure
-     <literal>pluginname/pluginname.plugin.zsh</literal> as structured in the
-     <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream
-     repo.</link>
+      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>
-   </listitem>
-  </itemizedlist>
-
-  <para>
-   A derivation for <literal>oh-my-zsh</literal> may look like this:
-<programlisting>
+    <itemizedlist>
+      <listitem>
+        <para>
+          To comply with the default structure of <literal>ZSH</literal>
+          the entire output needs to be written to
+          <literal>$out/share/zsh.</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Completion scripts are supposed to be stored at
+          <literal>$out/share/zsh/site-functions</literal>. This
+          directory is part of the
+          <link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>
+          and the package should be compatible with pure
+          <literal>ZSH</literal> setups. The module will automatically
+          link the contents of <literal>site-functions</literal> to
+          completions directory in the proper store path.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>plugins</literal> directory needs the structure
+          <literal>pluginname/pluginname.plugin.zsh</literal> as
+          structured in the
+          <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream
+          repo.</link>
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      A derivation for <literal>oh-my-zsh</literal> may look like this:
+    </para>
+    <programlisting>
 { stdenv, fetchFromGitHub }:
 
 stdenv.mkDerivation rec {
-  name = "exemplary-zsh-customization-${version}";
-  version = "1.0.0";
+  name = &quot;exemplary-zsh-customization-${version}&quot;;
+  version = &quot;1.0.0&quot;;
   src = fetchFromGitHub {
     # path to the upstream repository
   };
@@ -150,6 +148,5 @@ stdenv.mkDerivation rec {
   '';
 }
 </programlisting>
-  </para>
- </section>
+  </section>
 </chapter>