From 42239d4dd828631708528b99bd88988948439ea5 Mon Sep 17 00:00:00 2001 From: Aaron Gyes Date: Thu, 4 Nov 2021 13:07:30 -0700 Subject: [PATCH] fish.rst: do better This fixes the indentation problem for the SYNOPSIS section by not inserting the :: literal block. Format it the same way Sphinx does their own manpages for commands. Use more semantic markup, like :command:, so that commands are highlighted in the man pages. Split by sentence to give `man` a chance to ascertain lines. Long-term, it should be possible to teach Sphinx to turn :command:s into references and get us automatic links to articles for matching cmds/*. --- doc_src/cmds/fish.rst | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/doc_src/cmds/fish.rst b/doc_src/cmds/fish.rst index 579195f14..03bcc4e9c 100644 --- a/doc_src/cmds/fish.rst +++ b/doc_src/cmds/fish.rst @@ -6,24 +6,29 @@ fish - the friendly interactive shell Synopsis -------- -:: +**fish** [*OPTIONS*] [*FILE* [*ARGS* ...]] - fish [OPTIONS] [-c command] [FILE] [ARGUMENTS...] +**fish** [*OPTIONS*] [**-c** *COMMAND* [*ARGS* ...]] Description ----------- -fish is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The :ref:`full manual ` is available in HTML by using the :ref:`help ` command from inside fish, and in the `fish-doc(1)` man page. The :ref:`tutorial ` is available as HTML via ``help tutorial`` or in `fish-tutorial(1)`. +:command:`fish` is a command-line shell written mainly with interactive use in mind. +This page briefly describes the options for invoking :command:`fish`. +The :ref:`full manual ` is available in HTML by using the :command:`help` command from inside fish, and in the `fish-doc(1)` man page. +The :ref:`tutorial ` is available as HTML via ``help tutorial`` or in `man fish-tutorial`. + The following options are available: -- ``-c`` or ``--command=COMMANDS`` evaluate the specified commands instead of reading from the commandline, passing any additional positional arguments via :ref:`$argv `. Note that, unlike other shells, the first argument is *not* the name of the program (``$0``), but simply the first normal argument. +- ``-c`` or ``--command=COMMANDS`` evaluate the specified commands instead of reading from the commandline, passing any additional positional arguments via :envvar:`$argv`. + Note that, unlike other shells, the first argument is *not* the name of the program (``$0``), but simply the first normal argument. -- ``-C`` or ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the command specified by ``-c`` or reading interactive input +- ``-C`` or ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the command specified by ``-c`` or reading interactive input. - ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging ` below for details. -- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr. +- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and :envvar:`fish_trace`. The default is stderr. - ``-i`` or ``--interactive`` specify that fish is to run in interactive mode @@ -45,7 +50,8 @@ The following options are available: - ``-v`` or ``--version`` display version and exit -- ``-f`` or ``--features=FEATURES`` enables one or more :ref:`feature flags ` (separated by a comma). These are how fish stages changes that might break scripts. +- ``-f`` or ``--features=FEATURES`` enables one or more :ref:`feature flags ` (separated by a comma). + These are how fish stages changes that might break scripts. The fish exit status is generally the :ref:`exit status of the last foreground command `. @@ -54,18 +60,25 @@ The fish exit status is generally the :ref:`exit status of the last foreground c Debugging --------- -While fish provides extensive support for :ref:`debugging fish scripts `, it is also possible to debug and instrument its internals. Debugging can be enabled by passing the ``--debug`` option. For example, the following command turns on debugging for background IO thread events, in addition to the default categories, i.e. *debug*, *error*, *warning*, and *warning-path*:: +While fish provides extensive support for :ref:`debugging fish scripts `, it is also possible to debug and instrument its internals. +Debugging can be enabled by passing the ``--debug`` option. +For example, the following command turns on debugging for background IO thread events, in addition to the default categories, i.e. *debug*, *error*, *warning*, and *warning-path*: +:: > fish --debug=iothread -Available categories are listed by ``fish --print-debug-categories``. The ``--debug`` option accepts a comma-separated list of categories, and supports glob syntax. The following command turns on debugging for *complete*, *history*, *history-file*, and *profile-history*, as well as the default categories:: +Available categories are listed by ``fish --print-debug-categories``. The ``--debug`` option accepts a comma-separated list of categories, and supports glob syntax. +The following command turns on debugging for *complete*, *history*, *history-file*, and *profile-history*, as well as the default categories: +:: > fish --debug='complete,*history*' -Debug messages output to stderr by default. Note that if ``fish_trace`` is set, execution tracing also outputs to stderr by default. You can output to a file using the ``--debug-output`` option:: +Debug messages output to stderr by default. Note that if ``fish_trace`` is set, execution tracing also outputs to stderr by default. You can output to a file using the ``--debug-output`` option: +:: > fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on' -These options can also be changed via the $FISH_DEBUG and $FISH_DEBUG_OUTPUT variables. The categories enabled via ``--debug`` are *added* to the ones enabled by $FISH_DEBUG, so they can be disabled by prefixing them with ``-`` (``reader-*,-ast*`` enables reader debugging and disables ast debugging). +These options can also be changed via the :envvar:`$FISH_DEBUG` and :envvar:`$FISH_DEBUG_OUTPUT` variables. +The categories enabled via ``--debug`` are *added* to the ones enabled by $FISH_DEBUG, so they can be disabled by prefixing them with ``-`` (``reader-*,-ast*`` enables reader debugging and disables ast debugging). -The file given in ``--debug-output`` takes precedence over the file in $FISH_DEBUG_OUTPUT. +The file given in ``--debug-output`` takes precedence over the file in :envvar:`$FISH_DEBUG_OUTPUT`.