nixos/input-method: convert manual chapter to MD

3 files changed, 389 insertions, 247 deletions

diff --git a/nixos/modules/i18n/input-method/default.md b/nixos/modules/i18n/input-method/default.md
new file mode 100644
index 00000000000..05ae12065c3
--- /dev/null
+++ b/nixos/modules/i18n/input-method/default.md
@@ -0,0 +1,158 @@
+# Input Methods {#module-services-input-methods}
+
+Input methods are an operating system component that allows any data, such as
+keyboard strokes or mouse movements, to be received as input. In this way
+users can enter characters and symbols not found on their input devices.
+Using an input method is obligatory for any language that has more graphemes
+than there are keys on the keyboard.
+
+The following input methods are available in NixOS:
+
+  - IBus: The intelligent input bus.
+  - Fcitx: A customizable lightweight input method.
+  - Nabi: A Korean input method based on XIM.
+  - Uim: The universal input method, is a library with a XIM bridge.
+  - Hime: An extremely easy-to-use input method framework.
+  - Kime: Korean IME
+
+## IBus {#module-services-input-methods-ibus}
+
+IBus is an Intelligent Input Bus. It provides full featured and user
+friendly input method user interface.
+
+The following snippet can be used to configure IBus:
+
+```
+i18n.inputMethod = {
+  enabled = "ibus";
+  ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
+};
+```
+
+`i18n.inputMethod.ibus.engines` is optional and can be used
+to add extra IBus engines.
+
+Available extra IBus engines are:
+
+  - Anthy (`ibus-engines.anthy`): Anthy is a system for
+    Japanese input method. It converts Hiragana text to Kana Kanji mixed text.
+  - Hangul (`ibus-engines.hangul`): Korean input method.
+  - m17n (`ibus-engines.m17n`): m17n is an input method that
+    uses input methods and corresponding icons in the m17n database.
+  - mozc (`ibus-engines.mozc`): A Japanese input method from
+    Google.
+  - Table (`ibus-engines.table`): An input method that load
+    tables of input methods.
+  - table-others (`ibus-engines.table-others`): Various
+    table-based input methods. To use this, and any other table-based input
+    methods, it must appear in the list of engines along with
+    `table`. For example:
+
+    ```
+    ibus.engines = with pkgs.ibus-engines; [ table table-others ];
+    ```
+
+To use any input method, the package must be added in the configuration, as
+shown above, and also (after running `nixos-rebuild`) the
+input method must be added from IBus' preference dialog.
+
+### Troubleshooting {#module-services-input-methods-troubleshooting}
+
+If IBus works in some applications but not others, a likely cause of this
+is that IBus is depending on a different version of `glib`
+to what the applications are depending on. This can be checked by running
+`nix-store -q --requisites <path> | grep glib`,
+where `<path>` is the path of either IBus or an
+application in the Nix store. The `glib` packages must
+match exactly. If they do not, uninstalling and reinstalling the
+application is a likely fix.
+
+## Fcitx {#module-services-input-methods-fcitx}
+
+Fcitx is an input method framework with extension support. It has three
+built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.
+
+The following snippet can be used to configure Fcitx:
+
+```
+i18n.inputMethod = {
+  enabled = "fcitx";
+  fcitx.engines = with pkgs.fcitx-engines; [ mozc hangul m17n ];
+};
+```
+
+`i18n.inputMethod.fcitx.engines` is optional and can be
+used to add extra Fcitx engines.
+
+Available extra Fcitx engines are:
+
+  - Anthy (`fcitx-engines.anthy`): Anthy is a system for
+    Japanese input method. It converts Hiragana text to Kana Kanji mixed text.
+  - Chewing (`fcitx-engines.chewing`): Chewing is an
+    intelligent Zhuyin input method. It is one of the most popular input
+    methods among Traditional Chinese Unix users.
+  - Hangul (`fcitx-engines.hangul`): Korean input method.
+  - Unikey (`fcitx-engines.unikey`): Vietnamese input method.
+  - m17n (`fcitx-engines.m17n`): m17n is an input method that
+    uses input methods and corresponding icons in the m17n database.
+  - mozc (`fcitx-engines.mozc`): A Japanese input method from
+    Google.
+  - table-others (`fcitx-engines.table-others`): Various
+    table-based input methods.
+
+## Nabi {#module-services-input-methods-nabi}
+
+Nabi is an easy to use Korean X input method. It allows you to enter
+phonetic Korean characters (hangul) and pictographic Korean characters
+(hanja).
+
+The following snippet can be used to configure Nabi:
+
+```
+i18n.inputMethod = {
+  enabled = "nabi";
+};
+```
+
+## Uim {#module-services-input-methods-uim}
+
+Uim (short for "universal input method") is a multilingual input method
+framework. Applications can use it through so-called bridges.
+
+The following snippet can be used to configure uim:
+
+```
+i18n.inputMethod = {
+  enabled = "uim";
+};
+```
+
+Note: The [](#opt-i18n.inputMethod.uim.toolbar) option can be
+used to choose uim toolbar.
+
+## Hime {#module-services-input-methods-hime}
+
+Hime is an extremely easy-to-use input method framework. It is lightweight,
+stable, powerful and supports many commonly used input methods, including
+Cangjie, Zhuyin, Dayi, Rank, Shrimp, Greek, Korean Pinyin, Latin Alphabet,
+etc...
+
+The following snippet can be used to configure Hime:
+
+```
+i18n.inputMethod = {
+  enabled = "hime";
+};
+```
+
+## Kime {#module-services-input-methods-kime}
+
+Kime is Korean IME. it's built with Rust language and let you get simple, safe, fast Korean typing
+
+The following snippet can be used to configure Kime:
+
+```
+i18n.inputMethod = {
+  enabled = "kime";
+};
+```
diff --git a/nixos/modules/i18n/input-method/default.nix b/nixos/modules/i18n/input-method/default.nix
index 07fb86bcc25..987e5be2833 100644
--- a/nixos/modules/i18n/input-method/default.nix
+++ b/nixos/modules/i18n/input-method/default.nix
@@ -66,6 +66,8 @@ 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`
     doc = ./default.xml;
   };
 
diff --git a/nixos/modules/i18n/input-method/default.xml b/nixos/modules/i18n/input-method/default.xml
index ba621baf441..c6fda9a7c57 100644
--- a/nixos/modules/i18n/input-method/default.xml
+++ b/nixos/modules/i18n/input-method/default.xml
@@ -1,291 +1,273 @@
-<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-services-input-methods">
- <title>Input Methods</title>
- <para>
-  Input methods are an operating system component that allows any data, such as
-  keyboard strokes or mouse movements, to be received as input. In this way
-  users can enter characters and symbols not found on their input devices.
-  Using an input method is obligatory for any language that has more graphemes
-  than there are keys on the keyboard.
- </para>
- <para>
-  The following input methods are available in NixOS:
- </para>
- <itemizedlist>
-  <listitem>
-   <para>
-    IBus: The intelligent input bus.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Fcitx: A customizable lightweight input method.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Nabi: A Korean input method based on XIM.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Uim: The universal input method, is a library with a XIM bridge.
-   </para>
-  </listitem>
-  <listitem>
-   <para>
-    Hime: An extremely easy-to-use input method framework.
-   </para>
-  </listitem>
-  <listitem>
-    <para>
-     Kime: Korean IME
-    </para>
-  </listitem>
- </itemizedlist>
- <section xml:id="module-services-input-methods-ibus">
-  <title>IBus</title>
-
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-input-methods">
+  <title>Input Methods</title>
   <para>
-   IBus is an Intelligent Input Bus. It provides full featured and user
-   friendly input method user interface.
+    Input methods are an operating system component that allows any
+    data, such as keyboard strokes or mouse movements, to be received as
+    input. In this way users can enter characters and symbols not found
+    on their input devices. Using an input method is obligatory for any
+    language that has more graphemes than there are keys on the
+    keyboard.
   </para>
-
   <para>
-   The following snippet can be used to configure IBus:
+    The following input methods are available in NixOS:
   </para>
-
-<programlisting>
+  <itemizedlist spacing="compact">
+    <listitem>
+      <para>
+        IBus: The intelligent input bus.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Fcitx: A customizable lightweight input method.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Nabi: A Korean input method based on XIM.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Uim: The universal input method, is a library with a XIM bridge.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Hime: An extremely easy-to-use input method framework.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Kime: Korean IME
+      </para>
+    </listitem>
+  </itemizedlist>
+  <section xml:id="module-services-input-methods-ibus">
+    <title>IBus</title>
+    <para>
+      IBus is an Intelligent Input Bus. It provides full featured and
+      user friendly input method user interface.
+    </para>
+    <para>
+      The following snippet can be used to configure IBus:
+    </para>
+    <programlisting>
 i18n.inputMethod = {
-  enabled = "ibus";
+  enabled = &quot;ibus&quot;;
   ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
 };
 </programlisting>
-
-  <para>
-   <literal>i18n.inputMethod.ibus.engines</literal> is optional and can be used
-   to add extra IBus engines.
-  </para>
-
-  <para>
-   Available extra IBus engines are:
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a system for
-     Japanese input method. It converts Hiragana text to Kana Kanji mixed text.
-    </para>
-   </listitem>
-   <listitem>
     <para>
-     Hangul (<literal>ibus-engines.hangul</literal>): Korean input method.
+      <literal>i18n.inputMethod.ibus.engines</literal> is optional and
+      can be used to add extra IBus engines.
     </para>
-   </listitem>
-   <listitem>
     <para>
-     m17n (<literal>ibus-engines.m17n</literal>): m17n is an input method that
-     uses input methods and corresponding icons in the m17n database.
+      Available extra IBus engines are:
     </para>
-   </listitem>
-   <listitem>
+    <itemizedlist>
+      <listitem>
+        <para>
+          Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a
+          system for Japanese input method. It converts Hiragana text to
+          Kana Kanji mixed text.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Hangul (<literal>ibus-engines.hangul</literal>): Korean input
+          method.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          m17n (<literal>ibus-engines.m17n</literal>): m17n is an input
+          method that uses input methods and corresponding icons in the
+          m17n database.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          mozc (<literal>ibus-engines.mozc</literal>): A Japanese input
+          method from Google.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Table (<literal>ibus-engines.table</literal>): An input method
+          that load tables of input methods.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          table-others (<literal>ibus-engines.table-others</literal>):
+          Various table-based input methods. To use this, and any other
+          table-based input methods, it must appear in the list of
+          engines along with <literal>table</literal>. For example:
+        </para>
+        <programlisting>
+ibus.engines = with pkgs.ibus-engines; [ table table-others ];
+</programlisting>
+      </listitem>
+    </itemizedlist>
     <para>
-     mozc (<literal>ibus-engines.mozc</literal>): A Japanese input method from
-     Google.
+      To use any input method, the package must be added in the
+      configuration, as shown above, and also (after running
+      <literal>nixos-rebuild</literal>) the input method must be added
+      from IBus' preference dialog.
     </para>
-   </listitem>
-   <listitem>
+    <section xml:id="module-services-input-methods-troubleshooting">
+      <title>Troubleshooting</title>
+      <para>
+        If IBus works in some applications but not others, a likely
+        cause of this is that IBus is depending on a different version
+        of <literal>glib</literal> to what the applications are
+        depending on. This can be checked by running
+        <literal>nix-store -q --requisites &lt;path&gt; | grep glib</literal>,
+        where <literal>&lt;path&gt;</literal> is the path of either IBus
+        or an application in the Nix store. The <literal>glib</literal>
+        packages must match exactly. If they do not, uninstalling and
+        reinstalling the application is a likely fix.
+      </para>
+    </section>
+  </section>
+  <section xml:id="module-services-input-methods-fcitx">
+    <title>Fcitx</title>
     <para>
-     Table (<literal>ibus-engines.table</literal>): An input method that load
-     tables of input methods.
+      Fcitx is an input method framework with extension support. It has
+      three built-in Input Method Engine, Pinyin, QuWei and Table-based
+      input methods.
     </para>
-   </listitem>
-   <listitem>
     <para>
-     table-others (<literal>ibus-engines.table-others</literal>): Various
-     table-based input methods. To use this, and any other table-based input
-     methods, it must appear in the list of engines along with
-     <literal>table</literal>. For example:
-<programlisting>
-ibus.engines = with pkgs.ibus-engines; [ table table-others ];
-</programlisting>
+      The following snippet can be used to configure Fcitx:
     </para>
-   </listitem>
-  </itemizedlist>
-
-  <para>
-   To use any input method, the package must be added in the configuration, as
-   shown above, and also (after running <literal>nixos-rebuild</literal>) the
-   input method must be added from IBus' preference dialog.
-  </para>
-
-  <simplesect xml:id="module-services-input-methods-troubleshooting">
-   <title>Troubleshooting</title>
-   <para>
-    If IBus works in some applications but not others, a likely cause of this
-    is that IBus is depending on a different version of <literal>glib</literal>
-    to what the applications are depending on. This can be checked by running
-    <literal>nix-store -q --requisites &lt;path&gt; | grep glib</literal>,
-    where <literal>&lt;path&gt;</literal> is the path of either IBus or an
-    application in the Nix store. The <literal>glib</literal> packages must
-    match exactly. If they do not, uninstalling and reinstalling the
-    application is a likely fix.
-   </para>
-  </simplesect>
- </section>
- <section xml:id="module-services-input-methods-fcitx">
-  <title>Fcitx</title>
-
-  <para>
-   Fcitx is an input method framework with extension support. It has three
-   built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.
-  </para>
-
-  <para>
-   The following snippet can be used to configure Fcitx:
-  </para>
-
-<programlisting>
+    <programlisting>
 i18n.inputMethod = {
-  enabled = "fcitx";
+  enabled = &quot;fcitx&quot;;
   fcitx.engines = with pkgs.fcitx-engines; [ mozc hangul m17n ];
 };
 </programlisting>
-
-  <para>
-   <literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be
-   used to add extra Fcitx engines.
-  </para>
-
-  <para>
-   Available extra Fcitx engines are:
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a system for
-     Japanese input method. It converts Hiragana text to Kana Kanji mixed text.
-    </para>
-   </listitem>
-   <listitem>
     <para>
-     Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is an
-     intelligent Zhuyin input method. It is one of the most popular input
-     methods among Traditional Chinese Unix users.
+      <literal>i18n.inputMethod.fcitx.engines</literal> is optional and
+      can be used to add extra Fcitx engines.
     </para>
-   </listitem>
-   <listitem>
     <para>
-     Hangul (<literal>fcitx-engines.hangul</literal>): Korean input method.
+      Available extra Fcitx engines are:
     </para>
-   </listitem>
-   <listitem>
+    <itemizedlist spacing="compact">
+      <listitem>
+        <para>
+          Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a
+          system for Japanese input method. It converts Hiragana text to
+          Kana Kanji mixed text.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is
+          an intelligent Zhuyin input method. It is one of the most
+          popular input methods among Traditional Chinese Unix users.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Hangul (<literal>fcitx-engines.hangul</literal>): Korean input
+          method.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Unikey (<literal>fcitx-engines.unikey</literal>): Vietnamese
+          input method.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input
+          method that uses input methods and corresponding icons in the
+          m17n database.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input
+          method from Google.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          table-others (<literal>fcitx-engines.table-others</literal>):
+          Various table-based input methods.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="module-services-input-methods-nabi">
+    <title>Nabi</title>
     <para>
-     Unikey (<literal>fcitx-engines.unikey</literal>): Vietnamese input method.
+      Nabi is an easy to use Korean X input method. It allows you to
+      enter phonetic Korean characters (hangul) and pictographic Korean
+      characters (hanja).
     </para>
-   </listitem>
-   <listitem>
     <para>
-     m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input method that
-     uses input methods and corresponding icons in the m17n database.
+      The following snippet can be used to configure Nabi:
     </para>
-   </listitem>
-   <listitem>
+    <programlisting>
+i18n.inputMethod = {
+  enabled = &quot;nabi&quot;;
+};
+</programlisting>
+  </section>
+  <section xml:id="module-services-input-methods-uim">
+    <title>Uim</title>
     <para>
-     mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input method from
-     Google.
+      Uim (short for &quot;universal input method&quot;) is a
+      multilingual input method framework. Applications can use it
+      through so-called bridges.
     </para>
-   </listitem>
-   <listitem>
     <para>
-     table-others (<literal>fcitx-engines.table-others</literal>): Various
-     table-based input methods.
+      The following snippet can be used to configure uim:
     </para>
-   </listitem>
-  </itemizedlist>
- </section>
- <section xml:id="module-services-input-methods-nabi">
-  <title>Nabi</title>
-
-  <para>
-   Nabi is an easy to use Korean X input method. It allows you to enter
-   phonetic Korean characters (hangul) and pictographic Korean characters
-   (hanja).
-  </para>
-
-  <para>
-   The following snippet can be used to configure Nabi:
-  </para>
-
-<programlisting>
-i18n.inputMethod = {
-  enabled = "nabi";
-};
-</programlisting>
- </section>
- <section xml:id="module-services-input-methods-uim">
-  <title>Uim</title>
-
-  <para>
-   Uim (short for "universal input method") is a multilingual input method
-   framework. Applications can use it through so-called bridges.
-  </para>
-
-  <para>
-   The following snippet can be used to configure uim:
-  </para>
-
-<programlisting>
+    <programlisting>
 i18n.inputMethod = {
-  enabled = "uim";
+  enabled = &quot;uim&quot;;
 };
 </programlisting>
-
-  <para>
-   Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be
-   used to choose uim toolbar.
-  </para>
- </section>
- <section xml:id="module-services-input-methods-hime">
-  <title>Hime</title>
-
-  <para>
-   Hime is an extremely easy-to-use input method framework. It is lightweight,
-   stable, powerful and supports many commonly used input methods, including
-   Cangjie, Zhuyin, Dayi, Rank, Shrimp, Greek, Korean Pinyin, Latin Alphabet,
-   etc...
-  </para>
-
-  <para>
-   The following snippet can be used to configure Hime:
-  </para>
-
-<programlisting>
+    <para>
+      Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"></xref>
+      option can be used to choose uim toolbar.
+    </para>
+  </section>
+  <section xml:id="module-services-input-methods-hime">
+    <title>Hime</title>
+    <para>
+      Hime is an extremely easy-to-use input method framework. It is
+      lightweight, stable, powerful and supports many commonly used
+      input methods, including Cangjie, Zhuyin, Dayi, Rank, Shrimp,
+      Greek, Korean Pinyin, Latin Alphabet, etc...
+    </para>
+    <para>
+      The following snippet can be used to configure Hime:
+    </para>
+    <programlisting>
 i18n.inputMethod = {
-  enabled = "hime";
+  enabled = &quot;hime&quot;;
 };
 </programlisting>
- </section>
- <section xml:id="module-services-input-methods-kime">
-  <title>Kime</title>
-
-  <para>
-   Kime is Korean IME. it's built with Rust language and let you get simple, safe, fast Korean typing
-  </para>
-
-  <para>
-   The following snippet can be used to configure Kime:
-  </para>
-
-<programlisting>
+  </section>
+  <section xml:id="module-services-input-methods-kime">
+    <title>Kime</title>
+    <para>
+      Kime is Korean IME. it's built with Rust language and let you get
+      simple, safe, fast Korean typing
+    </para>
+    <para>
+      The following snippet can be used to configure Kime:
+    </para>
+    <programlisting>
 i18n.inputMethod = {
-  enabled = "kime";
+  enabled = &quot;kime&quot;;
 };
 </programlisting>
- </section>
+  </section>
 </chapter>