Merge branch 'master' into intro-doc

doc_src/cmds/argparse.rst

@@ -18,9 +18,9 @@ This command makes it easy for fish scripts and functions to handle arguments li
 
 Each option specification (``OPTION_SPEC``) is written in the `domain specific language <#option-specifications>`__ described below. 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.
+Each option that is seen in the ARG list will result in variables named ``_flag_X``, where ``X`` is the short flag letter and the long flag name (if they are defined). For example a ``--help`` option could cause argparse to define one variable called ``_flag_h`` and another called ``_flag_help``.
 
-For example ``_flag_h`` and ``_flag_help`` if ``-h`` or ``--help`` is seen. The var will be set with local scope (i.e., as if the script had done ``set -l _flag_X``). If the flag is a boolean (that is, it just is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag var will not be set.
+The variables will be set with local scope (i.e., as if the script had done ``set -l _flag_X``). If the flag is a boolean (that is, it just is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag variable will not be set.
 
 Options
 -------
@@ -74,13 +74,11 @@ Option Specifications
 
 Each option specification consists of:
 
-- A short flag letter (which is mandatory). It must be an alphanumeric or "#". The "#" character is special and means that a flag of the form ``-123`` is valid. The short flag "#" must be followed by "-" (since the short name isn't otherwise valid since ``_flag_#`` is not a valid var name) and must be followed by a long flag name with no modifiers.
+- An optional alphanumeric short flag letter, followed by a ``/`` if the short flag can be used by someone invoking your command or, for backwards compatibility, a ``-`` if it should not be exposed as a valid short flag (in which case it will also not be exposed as a flag variable).
 
-- A ``/`` if the short flag can be used by someone invoking your command else ``-`` if it should not be exposed as a valid short flag. If there is no long flag name these characters should be omitted. You can also specify a '#' to indicate the short and long flag names can be used and the value can be specified as an implicit int; i.e., a flag of the form ``-NNN``.
+- An optional long flag name. If not present then only the short flag letter can be used, and if that is not present either it's an error.
 
-- A long flag name which is optional. If not present then only the short flag letter can be used.
-
-- Nothing if the flag is a boolean that takes no argument or is an implicit int flag, or
+- Nothing if the flag is a boolean that takes no argument or is an integer flag, or
 
 - ``=`` if it requires a value and only the last instance of the flag is saved, or
 
@@ -94,6 +92,17 @@ See the :ref:`fish_opt <cmd-fish_opt>` command for a friendlier but more verbose
 
 If a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set.
 
+Integer flag
+------------
+
+Sometimes commands take numbers directly as options, like ``foo -55``. To allow this one option spec can have the ``#`` modifier so that any integer will be understood as this flag, and the last number will be given as its value (as if ``=`` was used).
+
+The ``#`` must follow the short flag letter (if any), and other modifiers like ``=`` are not allowed, except for ``-`` (for backwards compatibility)::
+
+  m#maximum
+
+This does not read numbers given as ``+NNN``, only those that look like flags - ``-NNN``.
+
 Note: Optional arguments
 ------------------------
 
@@ -149,6 +158,10 @@ Some OPTION_SPEC examples:
 
 - ``h-help`` means that only ``--help`` is valid. The flag is a boolean and can be used more than once. If the long flag is used then ``_flag_h`` and ``_flag_help`` will be set to the count of how many times the long flag was seen.
 
+- ``help`` means that only ``--help`` is valid and only ``_flag_help`` will be set.
+
+- ``longonly=`` is a flag ``--longonly`` that requires an option, there is no short flag or even short flag variable.
+
 - ``n/name=`` means that both ``-n`` and ``--name`` are valid. It requires a value and can be used at most once. If the flag is seen then ``_flag_n`` and ``_flag_name`` will be set with the single mandatory value associated with the flag.
 
 - ``n/name=?`` means that both ``-n`` and ``--name`` are valid. It accepts an optional value and can be used at most once. If the flag is seen then ``_flag_n`` and ``_flag_name`` will be set with the value associated with the flag if one was provided else it will be set with no values.
@@ -165,6 +178,8 @@ Some OPTION_SPEC examples:
 
 - ``n#max`` means that flags matching the regex "^--?\\d+$" are valid. When seen they are assigned to the variables ``_flag_n`` and ``_flag_max``. This allows any valid positive or negative integer to be specified by prefixing it with a single "-". Many commands support this idiom. For example ``head -3 /a/file`` to emit only the first three lines of /a/file. You can also specify the value using either flag: ``-n NNN`` or ``--max NNN`` in this example.
 
-After parsing the arguments the ``argv`` var is set with local scope to any values not already consumed during flag processing. If there are not unbound values the var is set but ``count $argv`` will be zero.
+- ``#longonly`` causes the last integer option to be stored in ``_flag_longonly``.
+
+After parsing the arguments the ``argv`` variable is set with local scope to any values not already consumed during flag processing. If there are no unbound values the variable is set but ``count $argv`` will be zero.
 
 If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.

doc_src/cmds/bind.rst

@@ -28,6 +28,8 @@ The generic key binding that matches if no other binding does can be set by spec
 
 If the ``-k`` switch is used, the name of a key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key\_' prefix. (See ``terminfo(5)`` for more information, or use ``bind --key-names`` for a list of all available named keys). Normally this will print an error if the current ``$TERM`` entry doesn't have a given key, unless the ``-s`` switch is given.
 
+To find out what sequence a key combination sends, you can use :ref:`fish_key_reader <cmd-fish_key_reader>`.
+
 ``COMMAND`` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use ``bind --function-names`` for a complete list of these input functions.
 
 When ``COMMAND`` is a shellscript command, it is a good practice to put the actual code into a `function <#function>`__ and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.
@@ -126,6 +128,8 @@ The following special input functions are available:
 
 - ``execute``, run the current commandline
 
+- ``exit``, exit the shell
+
 - ``forward-bigword``, move one whitespace-delimited word to the right
 
 - ``forward-char``, move one character to the right

doc_src/cmds/fish_hg_prompt.rst

@@ -19,7 +19,7 @@ The fish_hg_prompt function displays information about the current Mercurial rep
 
 `Mercurial <https://www.mercurial-scm.org/>`_ (``hg``) must be installed.
 
-By default, only the current branch is shown because ``hg status`` can take be slow on large repository. You can enable a more informative prompt by setting the variable ``$fish_prompt_hg_show_informative_status``, for example::
+By default, only the current branch is shown because ``hg status`` can be slow on a large repository. You can enable a more informative prompt by setting the variable ``$fish_prompt_hg_show_informative_status``, for example::
 
 	set --universal fish_prompt_hg_show_informative_status
 

doc_src/cmds/fish_status_to_signal.rst

@@ -0,0 +1,29 @@
+.. _cmd-fish_status_to_signal:
+
+fish_status_to_signal - Convert exit codes to human-friendly signals
+====================================================================
+
+Synopsis
+--------
+
+::
+
+    function fish_prompt
+        echo -n (fish_status_to_signal $pipestatus | string join '|') (prompt_pwd) '$ '
+    end
+
+Description
+-----------
+
+``fish_status_to_signal`` converts exit codes to their corresponding human-friendly signals if one exists.
+This is likely to be useful for prompts in conjunction with the ``$status`` and ``$pipestatus`` variables.
+
+Example
+-------
+
+::
+
+    >_ sleep 5
+    ^C⏎
+    >_ fish_status_to_signal $status
+    SIGINT

doc_src/cmds/string-match.rst

@@ -27,7 +27,7 @@ If ``--index`` or ``-n`` is given, each match is reported as a 1-based start pos
 
 If ``--regex`` or ``-r`` is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the STRING will be reported, unless ``--entire`` is given.
 
-When matching via regular expressions, ``string match`` automatically imports all named capturing groups (``(?<name>expression)``) as fish variables of the same name. It will create a variable in the default scope for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like ``set var ""``). If it did not match, the variable will be set to nothing (like ``set var``).  When ``--regex`` is used with ``--all``, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.
+When matching via regular expressions, ``string match`` automatically sets variables for all named capturing groups (``(?<name>expression)``). It will create a variable with the name of the group, in the default scope, for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like ``set var ""``). If it did not match, the variable will be set to nothing (like ``set var``).  When ``--regex`` is used with ``--all``, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.
 
 If ``--invert`` or ``-v`` is used the selected lines will be only those which do not match the given glob pattern or regular expression.
 

doc_src/index.rst

@@ -479,6 +479,7 @@ When fish is given a commandline, it expands the parameters before sending them
 - :ref:`Brace expansion <expand-brace>`, to write lists with common pre- or suffixes in a shorter way
 - :ref:`Tilde expansion <expand-home>`, to turn the ``~`` at the beginning of paths into the path to the home directory
 
+Parameter expansion is limited to 524288 items.
 
 .. _expand-wildcard:
 
@@ -487,9 +488,9 @@ Wildcards ("Globbing")
 
 When a parameter includes an :ref:`unquoted <quotes>` ``*`` star (or "asterisk") or a ``?`` question mark, fish uses it as a wildcard to match files.
 
-- ``*`` can match any string of characters not containing ``/``. This includes matching an empty string.
+- ``*`` matches any number of characters (including zero) in a file name, not including ``/``.
 
-- ``**`` matches any string of characters. This includes matching an empty string. The matched string can include the ``/`` character; that is, it goes into subdirectories. If a wildcard string with ``**`` contains a ``/``, that ``/`` still needs to be matched. For example, ``**\/*.fish`` won't match ``.fish`` files directly in the PWD, only in subdirectories. In fish you should type ``**.fish`` to match files in the PWD as well as subdirectories. [#]_
+- ``**`` matches any number of characters (including zero), and also descends into subdirectories. If ``**`` is a segment by itself, that segment may match zero times, for compatibility with other shells.
 
 - ``?`` can match any single character except ``/``. This is deprecated and can be disabled via the ``qmark-noglob`` :ref:`feature flag<featureflags>`, so ``?`` will just be an ordinary character.
 
@@ -530,7 +531,6 @@ Examples::
     end
     # Lists the .foo files, if any.
 
-.. [#] Unlike other shells, notably zsh.
 .. [#] Technically, unix allows filenames with newlines, and this splits the ``find`` output on newlines. If you want to avoid that, use find's ``-print0`` option and :ref:`string split0<cmd-string-split0>`.
 
 .. _expand-command-substitution:
@@ -1993,7 +1993,11 @@ If a function named :ref:`fish_greeting <cmd-fish_greeting>` exists, it will be
 Private mode
 -------------
 
-fish supports launching in private mode via ``fish --private`` (or ``fish -P`` for short). In private mode, old history is not available and any interactive commands you execute will not be appended to the global history file, making it useful both for avoiding inadvertently leaking personal information (e.g. for screencasts) and when dealing with sensitive information to prevent it being persisted to disk. You can query the global variable ``fish_private_mode`` (``if set -q fish_private_mode ...``) if you would like to respect the user's wish for privacy and alter the behavior of your own fish scripts.
+If ``$fish_private_mode`` is set to a non-empty value, commands will not be written to the history file on disk.
+
+You can also launch with ``fish --private`` (or ``fish -P`` for short). This both hides old history and prevents writing history to disk. This is useful to avoid leaking personal information (e.g. for screencasts) or when dealing with sensitive information.
+
+You can query the variable ``fish_private_mode`` (``if set -q fish_private_mode ...``) if you would like to respect the user's wish for privacy and alter the behavior of your own fish scripts.
 
 .. _event:
 

doc_src/python_docs_theme/static/pydoctheme.css

@@ -59,7 +59,8 @@ div.sphinxsidebar {
     float: none;
 }
 
-/* On screens that are less than 700px wide remove the sidebar */
+/* On screens that are less than 700px wide remove anything non-essential
+   - the sidebar, the gradient background, ... */
 @media screen and (max-width: 700px) {
   div.sphinxsidebar {
     width: 100%;
@@ -68,6 +69,13 @@ div.sphinxsidebar {
   }
   div.content {margin-left: 0;}
   div.bodywrapper { margin: 0; }
+  div#fmain {
+    border-radius: 0px;
+    margin: 0;
+    -moz-box-shadow: 0;
+    -webkit-box-shadow: 0;
+    box-shadow: 0;
+  }
 }
 
 div.sphinxsidebar h3, div.sphinxsidebar h4 {

doc_src/tutorial.rst

@@ -275,6 +275,8 @@ You can erase (or "delete") a variable with ``-e`` or ``--erase``
     > env | grep MyVariable
     (no output)
 
+.. _tut-exports:
+
 Exports (Shell Variables)
 -------------------------
 
@@ -290,6 +292,7 @@ To give a variable to an external command, it needs to be "exported". Unlike oth
 
 It can also be unexported with ``--unexport`` or ``-u``.
 
+This works the other way around as well! If fish is started by something else, it inherits that parents exported variables. So if your terminal emulator starts fish, and it exports ``$LANG`` set to ``en_US.UTF-8``, fish will receive that setting. And whatever started your terminal emulator also gave *it* some variables that it will then pass on unless it specifically decides not to. This is how fish usually receives the values for things like ``$LANG``, ``$PATH`` and ``$TERM``, without you having to specify them again.
 
 .. _tut-lists:
 
@@ -641,6 +644,8 @@ $PATH
 
 ``$PATH`` is an environment variable containing the directories that fish searches for commands. Unlike other shells, $PATH is a :ref:`list <tut-lists>`, not a colon-delimited string.
 
+Fish takes care to set ``$PATH`` to a default, but typically it is just inherited from fish's parent process and is set to a value that makes sense for the system - see :ref:`Exports <tut-exports>`.
+
 To prepend /usr/local/bin and /usr/sbin to ``$PATH``, you can write::
 
     > set PATH /usr/local/bin /usr/sbin $PATH