readme: move information on using sox into it's own file

Also minor cleanup to ydotool readme.

Author: ideasman42

nerd-dictation

@@ -1313,19 +1313,7 @@ This creates the directory used to store internal data, so other commands such a
             "- ``PAREC`` (external command, default)\n"
             "  See --pulse-device-name option to use a specific pulse-audio device.\n"
             "- ``SOX`` (external command)\n"
-            "  Set environment variable AUDIODEV to use a specific input device.\n"
-            "  Other sox options can be set (such as gain) by setting environment variable SOX_OPTS.\n"
-            "  You can test various devices by::\n"
-            "\n"
-            "     # List audio devices.\n"
-            "     arecord -l || cat /proc/asound/cards || cat /dev/sndstat \n"
-            "\n"
-            "     # Example, use card 2, subdevice 0.\n"
-            "     # Record 10 seconds and playback to default output.\n"
-            "     AUDIODEV='hw:2,0' \\\n"
-            "         sox -d --buffer 1000 -r 16000 -b 16 -e signed-integer \\\n"
-            "         -c 1 -t wav -L test.wav trim 0 10\n"
-            "     sox test.wav -d\n"
+            "  For help on setting up ydotool, see ``readme-sox.rst`` in the nerd-dictation repository.\n"
         ),
         required=False,
     )
@@ -1357,7 +1345,7 @@ This creates the directory used to store internal data, so other commands such a
             "\n"
             "- ``XDOTOOL`` Compatible with the X server only (default).\n"
             "- ``YDOTOOL`` Compatible with all Linux distributions and Wayland but requires some setup.\n"
-            "  For help on setting up ydotool, see our guide readme-ydotool.rst in the nerd-dictation repository.\n"
+            "  For help on setting up ydotool, see ``readme-ydotool.rst`` in the nerd-dictation repository.\n"
         ),
         required=False,
     )

readme-sox.rst

@@ -0,0 +1,40 @@
+#################################
+Using ``sox`` with nerd-dictation
+#################################
+
+This guide explains how to configure ``sox`` for recording audio with ``nerd-dictation``.
+
+
+When should I use ``sox``?
+==========================
+
+You may wish to configure ``sox`` if you are using a system without pulse-audio support (such as FreeBSD).
+
+
+Configuring ``sox``
+===================
+
+Set environment variable ``AUDIODEV`` to use a specific input device.
+Other sox options can be set (such as gain) by setting environment variable ``SOX_OPTS``.
+
+You can test various devices by
+
+.. code-block:: sh
+
+   # List audio devices.
+   arecord -l || cat /proc/asound/cards || cat /dev/sndstat
+
+   # Example, use card 2, subdevice 0.
+   # Record 10 seconds and playback to default output.
+   AUDIODEV='hw:2,0' sox -d --buffer 1000 -r 16000 -b 16 -e signed-integer -c 1 -t wav -L test.wav trim 0 10
+   sox test.wav -d
+
+
+Running nerd dictation with ``sox``
+===================================
+
+To run ``nerd-dictation`` with ``sox``, use the ``--input`` argument.
+
+.. code-block:: sh
+
+   nerd-dictation begin --input=SOX

readme-ydotool.rst

@@ -1,21 +1,21 @@
-#################################
-Using ydotool with nerd-dictation
-#################################
+#####################################
+Using ``ydotool`` with nerd-dictation
+#####################################
 
 This guide explains how to get and configure ``ydotool`` to simulate typing with ``nerd-dictation``,
 which brings support for typing on Wayland and languages other than English.
 
-When should I use ydotool
-=========================
+When should I use ``ydotool``?
+==============================
 
 By default, ``nerd-dictation`` uses the ``xdotool`` program to simulate writing with the keyboard.
 
 This program has two major limitations:
 
-# It is only compatible with Xorg, not with Wayland.
-  If you want to use Wayland, the program will not type anything.
-# It suffers from considerable slowdowns when writing characters not found in the English language,
-  temporarily freezing your computer's display.
+#. It is only compatible with Xorg, not with Wayland.
+   If you want to use Wayland, the program will not type anything.
+#. It suffers from considerable slowdowns when writing characters not found in the English language,
+   temporarily freezing your computer's display.
 
 There is a program named ``ydotool`` that you can use as an alternative to ``xdotool``.
 ``ydotool`` does not rely on the X server, so it is compatible with Wayland.
@@ -25,8 +25,8 @@ It also offers better performance in languages other than English.
 The flip side is that it requires some system configuration to use conveniently.
 Also, it lacks accessible documentation, which is why it is not the default.
 
-Installing ydotool
-==================
+Installing ``ydotool``
+======================
 
 You will need to download the latest version of the program found on its git repository:
 https://github.com/ReimuNotMoe/ydotool/releases/
@@ -37,8 +37,8 @@ You should then place them in a place that's available on your ``$PATH`` environ
 **Warning:** While ``ydotool`` is available on the ``apt`` package manager on Ubuntu 22.04 LTS,
 the Debian package is outdated.
 
-Configuring ydotool
-===================
+Configuring ``ydotool``
+=======================
 
 To simulate typing, the program needs access to your ``/dev/uinput`` device.
 By default, this requires root privileges every time you run ``ydotool``,
@@ -82,8 +82,8 @@ for performance reasons. You needs to run ``ydotoold`` before you start using ``
 To avoid running it every time you start the computer, you can add it to your startup programs.
 The steps depend on your distribution, so we'll let you look this up.
 
-Running nerd dictation with ydotool
-===================================
+Running nerd dictation with ``ydotool``
+=======================================
 
 To run ``nerd-dictation`` with ``ydotool``, use the ``--simulate-input-tool`` argument.
 

readme.rst

@@ -227,19 +227,7 @@ options:
                         - ``PAREC`` (external command, default)
                           See --pulse-device-name option to use a specific pulse-audio device.
                         - ``SOX`` (external command)
-                          Set environment variable AUDIODEV to use a specific input device.
-                          Other sox options can be set (such as gain) by setting environment variable SOX_OPTS.
-                          You can test various devices by::
-
-                             # List audio devices.
-                             arecord -l || cat /proc/asound/cards || cat /dev/sndstat
-
-                             # Example, use card 2, subdevice 0.
-                             # Record 10 seconds and playback to default output.
-                             AUDIODEV='hw:2,0' \
-                                 sox -d --buffer 1000 -r 16000 -b 16 -e signed-integer \
-                                 -c 1 -t wav -L test.wav trim 0 10
-                             sox test.wav -d
+                          For help on setting up ydotool, see ``readme-sox.rst`` in the nerd-dictation repository.
   --output OUTPUT_METHOD
                         Method used to at put the result of speech to text.
 
@@ -252,7 +240,7 @@ options:
 
                         - ``XDOTOOL`` Compatible with the X server only (default).
                         - ``YDOTOOL`` Compatible with all Linux distributions and Wayland but requires some setup.
-                          For help on setting up ydotool, see our guide readme-ydotool.rst in the nerd-dictation repository.
+                          For help on setting up ydotool, see ``readme-ydotool.rst`` in the nerd-dictation repository.
   ``-`` ...             End argument parsing.
                         This can be used for user defined arguments which configuration scripts may read from the ``sys.argv``.