docs: Link CLI option references

- Change: Use the `option` role for all CLI option references.
- Change: Update CLI help text markup stripping for CLI options.

docs/source/cli.rst

@@ -29,9 +29,9 @@ Options and Arguments
 .. [#] See :ref:`render-styles`.
 
 .. [#] In CLI mode, only image sources are used, directory sources are skipped.
-   Animated images are displayed only when animation is disabled (with ``--no-anim``),
-   when there's only one image source or when using native animation of some render
-   styles.
+   Animated images are displayed only when animation is disabled (with
+   :option:`--no-anim <termvisage --no-anim>`), when there's only one image source
+   or when using native animation of some render styles.
 
 .. [#]  Frames will not be cached for any animation with more frames than this value.
    Memory usage depends on the frame count **per image**, not this maximum count.
@@ -42,12 +42,13 @@ Options and Arguments
 .. [#] Width and height are in units of columns and lines repectively.
 
    By default (i.e if none of the sizing options is specified), the equivalent of
-   ``--original-size`` is used if not larger than the :term:`available size`, else
-   ``--fit``.
+   :option:`--original-size <termvisage --original-size>` is used if not larger than
+   the :term:`available size`, else :option:`--fit <termvisage --fit>`.
 
 .. [#] Any image having more pixels than the specified maximum will be:
 
-   - skipped, in CLI mode, if ``--max-pixels-cli`` is specified.
+   - skipped, in CLI mode, if :option:`--max-pixels-cli <termvisage --max-pixels-cli>`
+     is specified.
    - replaced, in TUI mode, with a placeholder when displayed but can still be
      explicitly made to display.
 
@@ -67,12 +68,13 @@ Options and Arguments
      terminal's end but at the cost of image quality and color reproduction.
    - is useful for animations with high resolution and/or sparse color distribution.
    - only applies when an image is re-encoded and not read directly from file
-     (see ``--itnrff | --iterm2-no-read-from-file``).
+     (see :option:`--itnrff | --iterm2-no-read-from-file <termvisage --itnrff>`).
    - can only be used for non-transparent images but the transparency status
      of some images can not be correctly determined in an efficient way at render time.
 
      Thus, to ensure the JPEG format is always used for re-encoded images, disable
-     transparency (``--no-alpha``) or set a background color (``-b | --alpha-bg``).
+     transparency (:option:`--no-alpha <termvisage --no-alpha>`) or set a background
+     color (:option:`-b | --alpha-bg <termvisage -b>`).
 
 .. [#] By default, image data is used directly from file when no image manipulation is
    required. Otherwise, it's re-encoded in PNG (or JPEG, if enabled) format.

docs/source/concepts.rst

@@ -29,9 +29,9 @@ The viewer can be used in two modes:
 
    In this mode, images are directly printed to standard output. It is used when
 
-   * output is not a terminal (even if ``--tui`` is specified)
+   * output is not a terminal (even if :option:`--tui <termvisage --tui>` is specified)
    * there is only a single image source
-   * the ``--cli`` option is specified
+   * :option:`--cli <termvisage --cli>` is specified
 
 2. **TUI mode**
 
@@ -40,7 +40,7 @@ The viewer can be used in two modes:
 
    * there is at least one non-empty directory source
    * there are multiple image sources
-   * the ``--tui`` option is specified
+   * :option:`--tui <termvisage --tui>` is specified
 
 
 .. _render-styles:
@@ -51,8 +51,8 @@ Render Styles
 See :term:`render style`.
 
 By default, the best style supported by the :term:`active terminal` is automatically detected.
-A particular render style can be specified using :confval:`style` or the ``-S | --style``
-command-line option.
+A particular render style can be specified using :confval:`style` or
+:option:`-S | --style <termvisage -S>`.
 
 If the specified render style is:
 
@@ -86,8 +86,8 @@ The available render styles are:
    with a density of two pixels per character cell.
 
 Using a render style not supported by the :term:`active terminal` is not allowed by
-default. To force the usage of a style that is normally unsupported, add the
-``--force-style`` flag.
+default. To force the usage of a style that is normally unsupported, add
+:option:`--force-style <termvisage --force-style>`.
 
 
 .. _cell-ratio:
@@ -99,8 +99,9 @@ The :term:`cell ratio` is taken into consideration when setting image sizes for
 **text-based** render styles, in order to preserve the aspect ratio of images drawn to
 the terminal.
 
-This value is determined by :confval:`cell ratio` OR either of the command-line options
-``-C | --cell-ratio`` or ``--auto-cell-ratio``.
+This value is determined by :confval:`cell ratio` OR either of
+:option:`-C | --cell-ratio <termvisage -C>` or
+:option:`--auto-cell-ratio <termvisage --auto-cell-ratio>`.
 The command-line options are mutually exclusive and override the config option.
 
 By default (i.e without changing the config option value or specifying either
@@ -145,10 +146,11 @@ Logging
 
 Logs are more detailed event reports meant for troubleshooting and debugging purporses.
 
-Logs are written to a file on a local filesystem. The default log file is ``~/.termvisage/termvisage.log`` but a different file can be specified:
+Logs are written to a file on a local filesystem. The default log file is
+``~/.termvisage/termvisage.log`` but a different file can be specified:
 
 * for all sessions, using :confval:`log file`
-* per session, using the ``-l | --log-file`` command-line option
+* per session, using :option:`-l | --log-file <termvisage -l>`
 
 A log entry has the following format:
 
@@ -160,13 +162,17 @@ A log entry has the following format:
 * *date* and *time*: Current system date and time in the format ``%Y-%m-%d %H:%M:%S,<ms>``, where ``<ms>`` is in milliseconds.
 * *process* and *thread*: The names of the python process and thread that produced the log record.
 
-  * Only present when the *logging level* is set to ``DEBUG`` (either by ``--debug`` or ``--log-level=DEBUG``).
+  * Only present when the *logging level* is set to ``DEBUG`` (either by
+    :option:`--debug <termvisage --debug>` or
+    :option:`--log-level=DEBUG <termvisage --log-level>`).
 
 * *level*: The level of the log entry, this indicates it's importance.
 * *module*: The package sub-module from which it originated.
 * *function*: The function from which it originated.
 
-  * Only present when running on **Python 3.8+** and *logging level* is set to ``DEBUG`` (either by ``--debug`` or ``--log-level=DEBUG``).
+  * Only present when running on **Python 3.8+** and *logging level* is set to ``DEBUG``
+    (either by :option:`--debug <termvisage --debug>` or
+    :option:`--log-level=DEBUG <termvisage --log-level>`).
 
 * *message*: The actual report describing the event that occured.
 

docs/source/config.rst

@@ -22,16 +22,16 @@ If multiple config files are found (i.e in different locations), they're applied
 one another **in the order in which they were found**. Hence, a field present in the
 latter, if valid, will override the same field also present in the former.
 
-An alternative config file can be specified per-session using the ``--config`` command-line
-option.
+An alternative config file can be specified per-session using
+:option:`--config <termvisage --config>`.
 
-To use the default configuration and not load any config file, use the ``--no-config``
-command-line option.
+To use the default configuration and not load any config file, use
+:option:`--no-config <termvisage --no-config>`.
 
 .. hint::
    ``termvisage`` performs [quite] thorough validation on the values specified in a config
    file and reports any errors. To see information about how the errors are resolved
-   (if resolvable), use the ``-v | --verbose`` command-line option.
+   (if resolvable), use :option:`-v | --verbose <termvisage -v>`.
 
 `This <https://raw.githubusercontent.com/AnonymouX47/termvisage/main/default_config.json>`_
 is a sample config file with all options and keybindings at their defaults.
@@ -133,7 +133,8 @@ These are top-level fields whose values control various settings of the viewer.
 
    Any image having more pixels than the specified value will be:
 
-   * skipped, in CLI mode, if ``--max-pixels-cli`` is specified.
+   * skipped, in CLI mode, if :option:`--max-pixels-cli <termvisage --max-pixels-cli>`
+     is specified.
    * replaced, in TUI mode, with a placeholder when displayed but can still be forced
      to display or viewed externally.
 
@@ -162,8 +163,9 @@ These are top-level fields whose values control various settings of the viewer.
    :valid: ``"auto"``, ``"block"``, ``"iterm2"``, ``"kitty"``
    :default: ``"auto"``
 
-   If set to any value other than ``"auto"`` and is not overriden by the ``-S | --style``
-   command-line option, the style is used regardless of whether it's supported or not.
+   If set to any value other than ``"auto"`` and is not overriden by
+   :option:`-S | --style <termvisage -S>`, the style is used regardless of whether
+   it's supported or not.
 
 .. confval:: swap win size
    :synopsis: A workaround for some terminal emulators (e.g older VTE-based ones) that

docs/source/faqs.rst

@@ -18,12 +18,13 @@ Why are colours not properly reproduced?
 Why are images out of scale?
    - If *auto* :term:`cell ratio` is supported and enabled,
 
-     - Use :confval:`swap win size` or the ``--swap-win-size`` command-line option.
+     - Use :confval:`swap win size` or :option:`--swap-win-size <termvisage --swap-win-size>`.
      - If the above doesn't work, then open a new issue `here <https://github.com/AnonymouX47/termvisage/issues/new/choose>`_ with adequate details.
 
    - Otherwise,
 
-     - Adjust the :term:`cell ratio` using :confval:`cell ratio` or the ``-C | --cell-ratio`` command-line option.
+     - Adjust the :term:`cell ratio` using :confval:`cell ratio` or
+       :option:`-C | --cell-ratio <termvisage -C>`.
 
 Why is the TUI unresponsive or slow in drawing images?
    - Drawing (not rendering) speed is **entirely** dependent on the terminal emulator itself.

docs/source/glossary.rst

@@ -21,30 +21,30 @@ Below are definitions of terms used in the CLI help text, info/warning/error mes
    horizontal alignment
       The horizontal position of a primary :term:`render` output within its :term:`padding width`.
 
-      .. seealso:: ``--h-align``
+      .. seealso:: :option:`--h-align <termvisage --h-align>`
 
    vertical alignment
       The vertical position of a primary :term:`render` output within its :term:`padding height`.
 
-      .. seealso:: ``--v-align``
+      .. seealso:: :option:`--v-align <termvisage --v-align>`
 
    allowance
       The amount of space to be left unused on the terminal screen.
 
    horizontal allowance
       The amount of **columns** to be left unused on the terminal screen.
 
-      .. seealso:: ``--h-allow``
+      .. seealso:: :option:`--h-allow <termvisage --h-allow>`
 
    vertical allowance
       The amount of **lines** to be left unused on the terminal screen.
 
-      .. seealso:: ``--v-allow``
+      .. seealso:: :option:`--v-allow <termvisage --v-allow>`
 
    alpha threshold
       Alpha ratio/value above which a pixel is taken as **opaque** (applies only to text-based render styles).
 
-      .. seealso:: ``--alpha``
+      .. seealso:: :option:`-A | --alpha <termvisage -A>`
 
    animated
       Having multiple frames.
@@ -89,14 +89,14 @@ Below are definitions of terms used in the CLI help text, info/warning/error mes
 
       Excess columns on either or both sides of the render output (depending on the :term:`horizontal alignment`) will be filled with spaces.
 
-      .. seealso:: ``--pad-width``
+      .. seealso:: :option:`--pad-width <termvisage --pad-width>`
 
    padding height
       Amount of **lines** within which to fit a primary :term:`render` output.
 
       Excess lines on either or both sides of the render output (depending on the :term:`vertical alignment`) will be filled with spaces.
 
-      .. seealso:: ``--pad-height``
+      .. seealso:: :option:`--pad-height <termvisage --pad-height>`
 
    render style
    render styles

docs/source/issues.rst

@@ -6,7 +6,7 @@ Known Issues
    (tested in Windows Terminal and MinTTY).
    See the `library`_\'s :external+term_image:doc:`issues` for details.
 
-   In CLI mode, use the ``--h-allow`` option to specify a horizontal allowance.
+   In CLI mode, use :option:`--h-allow <termvisage --h-allow>` to specify a horizontal allowance.
 
 3. Some animations with the **kitty** render style within the **Kitty terminal emulator**
    might be glitchy at the moment.

docs/source/tui.rst

@@ -52,7 +52,7 @@ The following are the key components that make up the UI.
   * Immediately above the *Action/Key Bar*.
   * Notifications about various events are displayed here.
   * Hidden in full image views.
-  * Hidden in all views, in QUIET mode (``--quiet``).
+  * Hidden in all views, in QUIET mode (:option:`-q | --quiet <termvisage -q>`).
 
 * **Action/Key Bar**:
 
@@ -69,7 +69,7 @@ The following are the key components that make up the UI.
 
   * Used for debugging.
   * This is a 1-line bar immediately above the action/key bar.
-  * Only shows (in all views) when the ``--debug`` option is specified.
+  * Only shows (in all views) when :option:`--debug <termvisage --debug>` is specified.
 
 Full/Maximized image views consist of only the *view* and *action/key bar* components.