From ac1df310c84f03e6dc8b1e640098d6928dffd660 Mon Sep 17 00:00:00 2001 From: Aaron Gyes Date: Fri, 12 Nov 2021 04:20:51 -0800 Subject: [PATCH] Long march towards more structured text --- CHANGELOG.rst | 2 +- doc_src/cmds/exit.rst | 10 ++++------ doc_src/cmds/false.rst | 4 +--- doc_src/cmds/fish.rst | 2 +- doc_src/cmds/fish_add_path.rst | 10 ++++------ doc_src/cmds/fish_indent.rst | 10 ++++------ doc_src/cmds/realpath.rst | 20 ++++++-------------- doc_src/cmds/return.rst | 23 +++++++++-------------- doc_src/commands.rst | 4 ++-- doc_src/language.rst | 6 +++--- 10 files changed, 35 insertions(+), 56 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 8575fc3f2..e08e7da4e 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -42,7 +42,7 @@ Scripting improvements 'blue ' - ``$fish_user_paths`` is now automatically deduplicated to fix a common user error of appending to it in config.fish when it is universal (:issue:`8117`). :ref:`fish_add_path ` remains the recommended way to add to $PATH. -- ``return`` can now be used outside of functions. In scripts it does the same thing as :ref:`exit `, in the commandline it sets ``$status`` without exiting (:issue:`8148`). +- ``return`` can now be used outside of functions. In scripts it does the same thing as :program:`cmd`, in the commandline it sets ``$status`` without exiting (:issue:`8148`). - An oversight prevented all syntax checks from running on commands given to ``fish -c`` (:issue:`8171`). This includes checks like e.g. ``exec`` not being allowed in a pipeline and ``$$`` not being a valid variable. Most of these would have triggered an assert or other error before. - ``fish_indent`` now correctly reformats tokens that end with a backslash followed by a newline (:issue:`8197`). - ``set`` learned a new option ``--function`` to set a variable in the function's top scope. This should be a more familiar way of scoping variables and avoids issues with ``--local``, which is actually block-scoped (:issue:`565`, :issue:`8145`):: diff --git a/doc_src/cmds/exit.rst b/doc_src/cmds/exit.rst index 47df52a75..aa9cac767 100644 --- a/doc_src/cmds/exit.rst +++ b/doc_src/cmds/exit.rst @@ -1,4 +1,4 @@ -.. _cmd-exit: +.. program::exit: exit - exit the shell ===================== @@ -6,13 +6,11 @@ exit - exit the shell Synopsis -------- -:: - - exit [STATUS] +**exit** [*code*] Description ----------- -``exit`` causes fish to exit. If ``STATUS`` is supplied, it will be converted to an integer and used as the exit status. Otherwise, the exit status will be that of the last command executed. +``exit`` is a special builtin that causes the shell to exit. If ``code`` is specified, the exit status is the eight least significant bits of ``n``. Otherwise, the exit status will be that of the last command executed. -If exit is called while sourcing a file (using the :ref:`source ` builtin) the rest of the file will be skipped, but the shell itself will not exit. +If exit is called while sourcing a file (using the :program:`source` builtin) the rest of the file will be skipped, but the shell itself will not exit. diff --git a/doc_src/cmds/false.rst b/doc_src/cmds/false.rst index 40da9a6af..e7c5ec9f6 100644 --- a/doc_src/cmds/false.rst +++ b/doc_src/cmds/false.rst @@ -6,9 +6,7 @@ false - return an unsuccessful result Synopsis -------- -:: - - false +**false** Description ----------- diff --git a/doc_src/cmds/fish.rst b/doc_src/cmds/fish.rst index 6d3ff8cdc..077336c14 100644 --- a/doc_src/cmds/fish.rst +++ b/doc_src/cmds/fish.rst @@ -1,4 +1,4 @@ -.. _cmd-fish: +.. program::fish fish - the friendly interactive shell ===================================== diff --git a/doc_src/cmds/fish_add_path.rst b/doc_src/cmds/fish_add_path.rst index 12bf3d0cd..6268e6b84 100644 --- a/doc_src/cmds/fish_add_path.rst +++ b/doc_src/cmds/fish_add_path.rst @@ -6,21 +6,19 @@ fish_add_path - add to the path Synopsis -------- -:: +**fish_add_path** *path*... - fish_add_path [paths...] - fish_add_path (-h | --help) - fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] [paths...] +**fish_add_path** [(*-g* | *--global*) | (*-U* | *--universal*) | (*-P* | *--path*)] [(*-m* | *--move*)] [(*-a* | *--append*) | (*-p* | *--prepend*)] [(*-v* | *--verbose*) | (*-n* | *--dry-run*)] *paths*... Description ----------- -``fish_add_path`` is a simple way to add more components to fish's $PATH. It does this by adding the components either to $fish_user_paths or directly to $PATH (if the ``--path`` switch is given). +:program:`fish_add_path` is a simple way to add more components to fish's :envvar:`PATH`. It does this by adding the components either to $fish_user_paths or directly to $PATH (if the ``--path`` switch is given). It is (by default) safe to use ``fish_add_path`` in config.fish, or it can be used once, interactively, and the paths will stay in future because of :ref:`universal variables `. This is a "do what I mean" style command, if you need more control, consider modifying the variable yourself. -Components are normalized by :ref:`realpath `. This means that trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a component already exists, it is not added again and stays in the same place unless the ``--move`` switch is given. +Components are normalized by :program:`realpath`. Trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a component already exists, it is not added again and stays in the same place unless the ``--move`` switch is given. Components are added in the order they are given, and they are prepended to the path unless ``--append`` is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths). diff --git a/doc_src/cmds/fish_indent.rst b/doc_src/cmds/fish_indent.rst index fa5a23eb8..cc4f665e6 100644 --- a/doc_src/cmds/fish_indent.rst +++ b/doc_src/cmds/fish_indent.rst @@ -1,4 +1,4 @@ -.. _cmd-fish_indent: +.. program::fish_indent fish_indent - indenter and prettifier ===================================== @@ -6,15 +6,13 @@ fish_indent - indenter and prettifier Synopsis -------- -:: - - fish_indent [OPTIONS] [FILE...] +**fish_indent** [*OPTIONS*] [*FILE*...] Description ----------- -``fish_indent`` is used to indent a piece of fish code. ``fish_indent`` reads commands from standard input or the given filenames and outputs them to standard output or a specified file (if ``-w`` is given). +:program:`fish_indent` is used to indent a piece of fish code. :program:`fish_indent` reads commands from standard input or the given filenames and outputs them to standard output or a specified file (if ``-w`` is given). The following options are available: @@ -30,7 +28,7 @@ The following options are available: - ``--html`` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``. -- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging ` in :ref:`fish(1) ` for details. +- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging ` in :program:`fish` (1) 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. diff --git a/doc_src/cmds/realpath.rst b/doc_src/cmds/realpath.rst index 9e96d2f17..4c8f1150f 100644 --- a/doc_src/cmds/realpath.rst +++ b/doc_src/cmds/realpath.rst @@ -1,4 +1,4 @@ -.. _cmd-realpath: +.. program::realpath realpath - convert a path to an absolute path without symlinks ============================================================== @@ -6,24 +6,16 @@ realpath - convert a path to an absolute path without symlinks Synopsis -------- -:: - - realpath PATH +**realpath** [*options*] *PATH* Description ----------- -.. only:: builder_man +:program:`realpath` follows all symbolic links encountered for the provided ``PATH``, printing the absolute path resolved. :program:`fish` provides a :command:`realpath`-alike builtin intended to be enrich systems where no such command is installed +by default. - NOTE: This page documents the fish builtin ``realpath``. - To see the documentation on the ``realpath`` command you might have, - use ``command man realpath``. - -``realpath`` resolves a path to its absolute path. - -fish provides a ``realpath`` builtin as a fallback for systems where there is no ``realpath`` command, your OS might provide a version with more features. - -If a ``realpath`` command exists, it will be preferred, so if you want to use the builtin you should use ``builtin realpath`` explicitly. +If a :command:`realpath` command exists, it will be preferred. +``builtin realpath`` will eplicitly use this implementation. The following options are available: diff --git a/doc_src/cmds/return.rst b/doc_src/cmds/return.rst index 0867a52be..361f78eab 100644 --- a/doc_src/cmds/return.rst +++ b/doc_src/cmds/return.rst @@ -1,4 +1,4 @@ -.. _cmd-return: +.. proggram::return: return - stop the current inner function ======================================== @@ -6,31 +6,26 @@ return - stop the current inner function Synopsis -------- -:: - - function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end +**return** [*n*] Description ----------- -``return`` halts a currently running function. The exit status is set to ``STATUS`` if it is given. +:program:`return` halts a currently running function. +The exit status is set to ``n`` if it is given. +If :program:`return` is invoked outside of a function or dot script it is equivalent to exit. -It is usually added inside of a conditional block such as an :ref:`if ` statement or a :ref:`switch ` statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function. +It is often added inside of a conditional block such as an :program:`if` statement or a :program:`switch` statement to conditionally stop the executing function and return to the caller; it can also be used to specify the exit status of a function. -If run at the top level of a script, it exits that script and returns the given status, like :ref:`exit `. If run at the top level in an interactive session, it will set ``$status``, but not exit the shell. +If at the top level of a script, it exits with the given status, like :program:`exit`. +If at the top level in an interactive session, it will set :envvar:`status`, but not exit the shell. Example ------- -The following code is an implementation of the false command as a fish function - - - +An implementation of the false command as a fish function: :: function false return 1 end - - - diff --git a/doc_src/commands.rst b/doc_src/commands.rst index 8f3191543..5ef6d5fdb 100644 --- a/doc_src/commands.rst +++ b/doc_src/commands.rst @@ -16,7 +16,7 @@ Core language keywords that make up the syntax, like - :ref:`for ` and :ref:`while ` for loops. - :ref:`break ` and :ref:`continue ` to control loops. - :ref:`function ` to define functions. -- :ref:`return ` to return a status from a function. +- :program:`return` to return a status from a function. - :ref:`begin ` to begin a block and :ref:`end ` to end any block (including ifs and loops). - :ref:`and `, :ref:`or ` and :ref:`not ` to combine commands logically. - :ref:`switch ` and :ref:`case ` to make multiple blocks depending on the value of a variable. @@ -81,7 +81,7 @@ Helper commands fish also ships some things as external commands so they can be easily called from elsewhere. -This includes :ref:`fish_indent ` to format fish code and :ref:`fish_key_reader ` to show you what escape sequence a keypress produces. +This includes :program:`fish_indent` to format fish code and :ref:`fish_key_reader ` to show you what escape sequence a keypress produces. The full list ^^^^^^^^^^^^^ diff --git a/doc_src/language.rst b/doc_src/language.rst index 62474b78b..117cf48a4 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -17,7 +17,7 @@ Shells like fish are used by giving them commands. A command is executed by writ echo hello world -This calls the :ref:`echo ` command. ``echo`` writes its arguments to the screen. In this example the output is ``hello world``. +:program:`echo` command writes its arguments to the screen. In this example the output is ``hello world``. Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax. @@ -1299,7 +1299,7 @@ You can change the settings of fish by changing the values of certain variables. empty string, history is not saved to disk (but is still available within the interactive session). -- ``fish_trace``, if set and not empty, will cause fish to print commands before they execute, similar to ``set -x`` in bash. The trace is printed to the path given by the :ref:`--debug-output ` option to fish or the :envvar:`FISH_DEBUG_OUTPUT` variable. It goes to stderr by default. +- ``fish_trace``, if set and not empty, will cause fish to print commands before they execute, similar to ``set -x`` in bash. The trace is printed to the path given by the `--debug-output` option to fish or the :envvar:`FISH_DEBUG_OUTPUT` variable. It goes to stderr by default. - ``fish_user_paths``, a list of directories that are prepended to :envvar:`PATH`. This can be a universal variable. @@ -1571,6 +1571,6 @@ For more information on how to define new event handlers, see the documentation Debugging fish scripts ---------------------- -Fish includes a built in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using :ref:`printf ` and :ref:`set `. As another example, you can run :ref:`status print-stack-trace ` to see how this breakpoint was reached. To resume normal execution of the script, simply type :ref:`exit ` or :kbd:`Control`\ +\ :kbd:`D`. +Fish includes a built in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using :ref:`printf ` and :ref:`set `. As another example, you can run :ref:`status print-stack-trace ` to see how this breakpoint was reached. To resume normal execution of the script, simply type :program:`exit` or :kbd:`Control`\ +\ :kbd:`D`. To start a debug session simply run the builtin command :ref:`breakpoint ` at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the ``kill`` command. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function.