Merge branch 'master' into major

CONTRIBUTING.md

@@ -31,6 +31,8 @@ To make linting the code easy there are two make targets: `lint` and `lint-all`.
 
 Fish has custom cppcheck rules in the file `.cppcheck.rule`. These help catch mistakes such as using `wcwidth()` rather than `fish_wcwidth()`. Please add a new rule if you find similar mistakes being made.
 
+Fish also depends on `diff` and `expect` for its tests.
+
 ### Dealing With Lint Warnings
 
 You are strongly encouraged to address a lint warning by refactoring the code, changing variable names, or whatever action is implied by the warning.

README.md

@@ -13,17 +13,31 @@ Detailed user documentation is available by running `help` within fish, and also
 
 ## Building
 
-fish requires a C++11 compiler. It builds successfully with g++ 4.8 or later, or with clang 3.3 or later.
+### Dependencies
 
-fish can be built using autotools or Xcode. autoconf 2.60 or later, as well as automake 1.13 or later, are required to build from git versions. These are not required to build from released tarballs.
+Compiling fish requires:
 
-fish depends on a curses implementation, such as ncurses. The headers and libraries are required for building.
+* a C++11 compiler. It builds successfully with g++ 4.8 or later, or with clang 3.3 or later. fish can be built using autotools or Xcode. autoconf 2.60 or later, as well as automake 1.13 or later, are required to build from git versions, but these are not required to build from the officially released tarballs.
+* the headers and libraries of a curses implementation such as ncurses.
+* gettext, for translation support.
+* Doxygen 1.8.7 or newer, for building the documentation.
 
-fish requires PCRE2 due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system.
+At runtime, fish requires:
 
-fish requires gettext for translation support.
+* a curses implementation, such as ncurses.
+* gettext, if you need the localizations.
+* PCRE2, due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system.
+* a number of common UNIX utilities: coreutils (at least ls, seq, rm, mktemp), hostname, grep, awk, sed, and getopt.
+* bc, the "basic calculator" program.
 
-Building the documentation requires Doxygen 1.8.7 or newer.
+Optional functionality should degrade gracefully. (If fish ever threw a syntax error or a core dump due to missing dependencies for an optional feature, it would be a bug in fish and should be reported on our GitHub.) Optional features and dependencies include:
+
+* dynamically generating usage tips for builtin functions, which requires man, apropos, nroff, and ul.
+* manual page parsing for auto-completion for external commands, which also requires the above man tools, plus Python 2.6+ or Python 3.3+. Python 2 will also need the backports.lzma package; Python 3.3+ should include the required module by default.
+* the web configuration tool, which requires Python 2.6+ or 3.3+.
+* the fish_clipboard_* functions (bound to \cv and \cx), which require xsel or pbcopy/pbpaste.
+
+fish can also show VCS information in the prompt, when the current working directory is in a VCS-tracked project, with support for Git, Mercurial, and Subversion. This is one of the weakest dependencies, though: if you don't use git, for example, you don't need git information in the prompt, and if you do use git, you already have it. Similarly, fish comes with a variety of auto-completion scripts to help with command-line usage of a variety of applications; these scripts call the application in question, but you should only need these applications if you use them.
 
 ### Autotools Build
 
@@ -55,22 +69,6 @@ On RedHat, CentOS, or Amazon EC2:
 
     sudo yum install ncurses-devel
 
-## Runtime Dependencies
-
-fish requires a curses implementation, such as ncurses, to run.
-
-fish requires PCRE2 due to the regular expression support contained in the `string` builtin. A bundled version will be compiled in automatically at build time if required.
-
-fish requires a number of utilities to operate, which should be present on any Unix, GNU/Linux or OS X system. These include (but are not limited to) hostname, grep, awk, sed, and getopt. fish also requires the bc program.
-
-Translation support requires the gettext program.
-
-Usage output for builtin functions is generated on-demand from the installed manpages using `nroff` and `ul`.
-
-Some optional features of fish, such as the manual page completion parser and the web configuration tool, require Python.
-
-In order to generate completions from man pages compressed with either lzma or xz, you may need to install an extra Python package. Python versions prior to 2.6 are not supported.  To process lzma-compresed manpages, backports.lzma is needed for Python 3.2 or older. From version 3.3 onwards, Python already includes the required module.
-
 ## Packages for Linux
 
 Instructions on how to find builds for several Linux distros are at <https://github.com/fish-shell/fish-shell/wiki/Nightly-builds>

doc_src/and.txt

@@ -11,7 +11,7 @@ COMMAND1; and COMMAND2
 
 `and` statements may be used as part of the condition in an <a href="#if">`if`</a> or <a href="#while">`while`</a> block. See the documentation for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.
 
-`and` does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
+`and` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
 
 \subsection and-example Example
 

doc_src/begin.txt

@@ -13,7 +13,7 @@ The block is unconditionally executed. `begin; ...; end` is equivalent to `if tr
 
 `begin` is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`.
 
-`begin` does not change the current exit status.
+`begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command.
 
 
 \subsection begin-example Example

doc_src/end.txt

@@ -16,4 +16,4 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 For more information, read the
 documentation for the block constructs, such as `if`, `for` and `while`.
 
-The `end` command does not change the current exit status.
+The `end` command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command.

doc_src/or.txt

@@ -12,7 +12,7 @@ COMMAND1; or COMMAND2
 `or` statements may be used as part of the condition in an <a href="#if">`and`</a> or <a href="#while">`while`</a> block. See the documentation
 for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.
 
-`or` does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
+`or` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
 
 \subsection or-example Example
 

share/functions/help.fish

@@ -100,7 +100,7 @@ function help --description 'Show help for the fish shell'
         case "*"
             # If $fish_help_item is empty, this will fail,
             # and $fish_help_page will end up as index.html
-            if type -q -f $fish_help_item
+            if type -q -f "$fish_help_item"
                 # Prefer to use fish's man pages, to avoid
                 # the annoying useless "builtin" man page bash
                 # installs on OS X