diff --git a/sphinx_doc_src/cmds/argparse.rst b/sphinx_doc_src/cmds/argparse.rst index e714a3150..071757170 100644 --- a/sphinx_doc_src/cmds/argparse.rst +++ b/sphinx_doc_src/cmds/argparse.rst @@ -12,9 +12,9 @@ argparse [OPTIONS] OPTION_SPEC... -- [ARG...] Description ----------- -This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). More on this in the `usage <#argparse-usage>`__ section below. +This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). More on this in the `usage <#usage>`__ section below. -Each OPTION_SPEC can be written in the `domain specific language <#argparse-option-specs>`__ described below or created using the companion :ref:`fish_opt ` command. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed. +Each OPTION_SPEC can be written in the `domain specific language <#option-specifications>`__ described below or created using the companion :ref:`fish_opt ` command. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed. Each option that is seen in the ARG list will result in a var name of the form ``_flag_X``, where ``X`` is the short flag letter and the long flag name. The OPTION_SPEC always requires a short flag even if it can't be used. So there will always be ``_flag_X`` var set using the short flag letter if the corresponding short or long flag is seen. The long flag name var (e.g., ``_flag_help``) will only be defined, obviously, if the OPTION_SPEC includes a long flag name. @@ -50,7 +50,7 @@ Using this command involves passing two sets of arguments separated by ``--``. T or return -If ``$argv`` is empty then there is nothing to parse and ``argparse`` returns zero to indicate success. If ``$argv`` is not empty then it is checked for flags ``-h``, ``--help``, ``-n`` and ``--name``. If they are found they are removed from the arguments and local variables (more on this `below `__) are set so the script can determine which options were seen. Assuming ``$argv`` doesn't have any errors, such as a missing mandatory value for an option, then ``argparse`` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one. +If ``$argv`` is empty then there is nothing to parse and ``argparse`` returns zero to indicate success. If ``$argv`` is not empty then it is checked for flags ``-h``, ``--help``, ``-n`` and ``--name``. If they are found they are removed from the arguments and local variables are set so the script can determine which options were seen. Assuming ``$argv`` doesn't have any errors, such as a missing mandatory value for an option, then ``argparse`` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one. The ``--`` argument is required. You do not have to include any arguments after the ``--`` but you must include the ``--``. For example, this is acceptable: @@ -93,7 +93,7 @@ Each option specification is a string composed of - ``=+`` if it requires a value and each instance of the flag is saved. -- Optionally a ``!`` followed by fish script to validate the value. Typically this will be a function to run. If the return status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the section on `Flag Value Validation <#arparse-validation>`__ for more information. +- Optionally a ``!`` followed by fish script to validate the value. Typically this will be a function to run. If the return status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the section on `Flag Value Validation <#flag-value-validation>`__ for more information. See the :ref:`fish_opt ` command for a friendlier but more verbose way to create option specifications.