index.hdr.in: (hopefully) non-controversial edits

1 files changed, 76 insertions, 75 deletions

diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index a703e7ab..6c6fccce 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -147,9 +147,9 @@ these characters, so called escape sequences are provided. These are:
 - <code>'\\U<i>xxxxxxxx</i>'</code>, where <code><i>xxxxxxxx</i></code> is a hexadecimal number, escapes the 32-bit Unicode character with the specified value. For example, \\U9 is the tab character.
 - <code>'\\c<i>x</i>'</code>, where <code><i>x</i></code> is a letter of the alphabet, escapes the control sequence generated by pressing the control key and the specified letter. For example, \\ci is the tab character
 
-\subsection redirects IO redirection
+\subsection redirects Input/Output (IO) redirection
 
-Most program use three types of input/output (IO), each represented by
+Most programs use three types of input/output (IO) methods, each represented by
 a number called a file descriptor (FD). These are:
 
 - Standard input, FD 0, for reading, defaults to reading from the keyboard.
@@ -244,7 +244,7 @@ control to \c fish by pressing ^Z (press and hold the Control key and
 press 'z'). Once back at the \c fish commandline, you can start other
 programs and do anything you want. If you then want you can go back to
 the suspended command by using the <a href="commands.html#fg">fg</a>
-command.
+(foreground) command.
 
 If you instead want to put a suspended job into the background, use
 the <a href="commands.html#bg">bg</a> command.
@@ -299,9 +299,9 @@ functions:
 Functions can be defined on the commandline or in a configuration
 file, but they can also be automatically loaded. This method of
 defining functions has several advantages. An autoloaded function
-becomes available automatically to all running shells, if the function
+becomes available automatically to all running shells. If the function
 definition is changed, all running shells will automatically reload
-the altered version, startup time and memory usage is improved, etc.
+the altered version. Startup time and memory usage is improved, etc.
 
 Fish automatically searches through any directories in the array
 variable \c $fish_function_path, and any functions defined are
@@ -321,9 +321,9 @@ administrator can override default fish functions, and the user can
 override functions defined by the system administrator.
 
 It is very important that function definition files only contain the
-definition for the specified function and nothing else, otherwise it
+definition for the specified function and nothing else. Otherwise, it
 is possible that autoloading a function files requires that the
-function already be loaded, i.e. a circular dependency.
+function already be loaded, which creates a circular dependency.
 
 \subsection syntax-conditional Conditional execution of code
 
@@ -387,7 +387,7 @@ command line.
 
 These are the general purpose tab completions that \c fish provides:
 
-- Completion of commands, both builtins, functions and regular programs.
+- Completion of commands (builtins, functions and regular programs).
 - Completion of environment variable names.
 - Completion of usernames for tilde expansion.
 - Completion of filenames, even on strings with wildcards such as '*', '**' and '?'.
@@ -523,16 +523,16 @@ user specific completions, the second one is for system-wide
 completions and the last one is for default fish completions.
 
 If you have written new completions for a common
-Unix command, please consider sharing your work by sending it to <a
-href='mailto: fish-users@lists.sf.net'>the fish mailing list</a>.
+Unix command, please consider sharing your work by submitting it via
+the instructions in <a href="#more-help">Further help and development</a>.
 
 
 \section expand Parameter expansion (Globbing)
 
 When an argument for a program is given on the commandline, it
 undergoes the process of parameter expansion before it is sent on to
-the command. Parameter expansion is a powerful set of mechanisms that
-allow you to expand the parameter in various ways, including
+the command. Parameter expansion is a powerful mechanism that
+allows you to expand the parameter in various ways, including
 performing wildcard matching on files, inserting the value of
 environment variables into the parameter or even using the output of
 another command as a parameter list.
@@ -564,7 +564,7 @@ Examples:
 
 <code>**</code> matches any files and directories in the current directory and all of its subdirectories.
 
-If no matches are found for a specific wildcard, it will expand into
+Note that if no matches are found for a specific wildcard, it will expand into
 zero arguments, i.e. to nothing. If none of the wildcarded arguments
 sent to a command result in any matches, the command will not be
 executed. If this happens when using the shell interactively, a
@@ -572,7 +572,8 @@ warning will also be printed.
 
 \subsection expand-command-substitution Command substitution
 
-If a parameter contains a set of parenthesis, the text enclosed by the
+The output of a series of commands can be used as the parameters to another
+command. If a parameter contains a set of parenthesis, the text enclosed by the
 parenthesis will be interpreted as a list of commands. On expansion,
 this list is executed, and substituted by the output. If the output is
 more than one line long, each line will be expanded to a new
@@ -584,14 +585,14 @@ href='#variables-status'>status</a> variable.
 Only part of the output can be used, see <a href='#expand-index-range'>index
 range expansion</a> for details.
 
-Example:
+Examples:
 
 The command <code>echo (basename image.jpg .jpg).png</code> will
 output 'image.png'.
 
 The command <code>for i in *.jpg; convert $i (basename $i .jpg).png;
-end</code> will convert all Jpeg files in the current directory to the
-PNG format.
+end</code> will convert all JPEG files in the current directory to the
+PNG format using the \c convert program.
 
 
 \subsection expand-brace Brace expansion
@@ -611,7 +612,7 @@ The command <code>mv *.{c,h} src/</code> moves all files with the suffix
 A dollar sign followed by a string of characters is expanded into the
 value of the environment variable with the same name. For an
 introduction to the concept of environment variables, read the <a
-href="#variables"> Environment variables</a> section.
+href="#variables">Environment variables</a> section.
 
 Example:
 
@@ -718,8 +719,8 @@ set n -3
 echo $PATH[$n..-1]
 </pre>
 
-NOTE: Currently variables are allowed inside variables index expansion, but not in indices, 
-used for command substitution.
+Note that variables can be used as indices for expansion of variables, but not
+command substitution.
 
 \subsection expand-home Home directory expansion
 
@@ -731,19 +732,20 @@ directory of the process owner.
 \subsection expand-process Process expansion
 
 The \% (percent) character at the beginning of a parameter followed by
-a string is expanded into a process id. The following expansions are
+a string is expanded into a process ID (PID). The following expansions are
 performed:
 
-- If the string is the entire word \c self, the shells pid is the result.
-- Otherwise, if the string is the id of a job, the result is the process
-group id of the job.
+- If the string is the entire word \c self, the shell's PID is the result.
+- Otherwise, if the string is the ID of a job, the result is the process
+group ID of the job.
 - Otherwise, if any child processes match the specified string, their
-pids are the result of the expansion.
+PIDs are the result of the expansion.
 - Otherwise, if any processes owned by the user match the specified
-string, their pids are the result of the expansion.
+string, their PIDs are the result of the expansion.
+- If none of these matches apply, an error is produced.
 
 This form of expansion is useful for commands like kill and fg, which
-take the process ids as an argument.
+take process IDs as arguments.
 
 Example:
 
@@ -752,7 +754,7 @@ with the letters 'ema', such as emacs, and if found, put it in the
 foreground.
 
 <code>kill -s SIGINT \%3</code> will send the SIGINT signal to the job
-with job id 3.
+with job ID 3.
 
 \subsection  combine Combining different expansions
 
@@ -806,7 +808,7 @@ usually blue'.
 
 \subsection variables-scope Variable scope
 
-There are three kinds of variables in fish, universal, global and
+There are three kinds of variables in fish: universal, global and
 local variables. Universal variables are shared between all fish
 sessions a user is running on one computer. Global variables are
 specific to the current fish session, but are not associated with any
@@ -865,7 +867,7 @@ prompt will instantly change to blue on both terminals.
 
 \subsection variables-functions Variable scope for functions
 
-When calling a function, all non-global variables temporarily
+When calling a function, all current local variables temporarily
 disappear. This shadowing of the local scope is needed since the
 variable namespace would become cluttered, making it very easy to
 accidentally overwrite variables from another function.
@@ -964,26 +966,26 @@ range expansion</a> for details.
 The user can change the settings of \c fish by changing the values of
 certain environment variables.
 
-- \c BROWSER, which is the users preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
-- \c CDPATH, which is an array of directories in which to search for the new directory for the \c cd builtin. The fish init files defined CDPATH to be a universal variable with the values . and ~.
+- \c BROWSER, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
+- \c CDPATH, an array of directories in which to search for the new directory for the \c cd builtin. By default, the fish configuration defines \c CDPATH to be a universal variable with the values \c . and \c ~.
 - A large number of variable starting with the prefixes \c fish_color and \c fish_pager_color. See <a href='#variables-color'>Variables for changing highlighting colors</a> for more information.
-- \c fish_greeting, which is the greeting message printed on startup.
+- \c fish_greeting, the greeting message printed on startup.
 - \c LANG, \c LC_ALL, \c LC_COLLATE, \c LC_CTYPE, \c LC_MESSAGES, \c LC_MONETARY, \c LC_NUMERIC and \c LC_TIME set the language option for the shell and subprograms. See the section <a href='#variables-locale'>Locale variables</a> for more information.
-- \c fish_user_paths, which is an array of directories that are appended to PATH. This can be a universal variable.
-- \c PATH, which is an array of directories in which to search for commands
-- \c umask, which is the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask shellscript function</a>. An attempt to set umask to an invalid value will always fail.
+- \c fish_user_paths, an array of directories that are appended to PATH. This can be a universal variable.
+- \c PATH, an array of directories in which to search for commands
+- \c umask, the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask function</a>. An attempt to set umask to an invalid value will always fail.
 
 \c fish also sends additional information to the user through the
-values of certain environment variables. The user can not change the
+values of certain environment variables. The user cannot change the
 values of most of these variables.
 
-- \c _, which is the name of the currently running command.
-- \c argv, which is an array of arguments to the shell or function. \c argv is only defined when inside a function call, or if fish was invoked with a list of arguments, like 'fish myscript.fish foo bar'. This variable can be changed by the user.
-- \c history, which is an array containing the last commands that where entered.
-- \c HOME, which is the users home directory. This variable can only be changed by the root user.
-- \c PWD, which is the current working directory.
-- \c status, which is the exit status of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.
-- \c USER, which is the username. This variable can only be changed by the root user.
+- \c _, the name of the currently running command.
+- \c argv, an array of arguments to the shell or function. \c argv is only defined when inside a function call, or if fish was invoked with a list of arguments, like 'fish myscript.fish foo bar'. This variable can be changed by the user.
+- \c history, an array containing the last commands that where entered.
+- \c HOME, the user's home directory. This variable can only be changed by the root user.
+- \c PWD, the current working directory.
+- \c status, the <a href="#variables-status">exit status</a> of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.
+- \c USER, the current username. This variable can only be changed by the root user.
 
 The names of these variables are mostly derived from the csh family of
 shells and differ from the ones used by Bourne style shells such as
@@ -993,7 +995,7 @@ discoverability problems, and given the existence of tab completion,
 the keystroke savings are minimal.
 
 Variables whose name are in uppercase are exported to the commands
-started by fish, those in lowercase are not exported. This rule is not
+started by fish, while those in lowercase are not exported. This rule is not
 enforced by fish, but it is good coding practice to use casing to
 distinguish between exported and unexported variables. \c fish also
 uses several variables internally. Such variables are prefixed with
@@ -1015,7 +1017,7 @@ exit in the \c status variable.
 If \c fish encounters a problem while executing a command, the status
 variable may also be set to a specific value:
 
-- 1 is the generally the exit status from fish builtins if they where supplied with invalid arguments
+- 1 is the generally the exit status from fish builtin commands if they were supplied with invalid arguments
 - 124 means that the command was not executed because none of the wildcards in the command produced any matches
 - 125 means that while an executable with the specified name was located, the operating system could not actually execute the command
 - 126 means that while a file with the specified name was located, it was not executable
@@ -1093,31 +1095,31 @@ see the <a href="#toc-commands">table of contents</a>. The
 documentation is also available by using the <code>--help</code>
 switch of the command.
 
-\section editor Command Line editor
+\section editor Command line editor
 
 The \c fish editor features copy and paste, a searchable history and
 many editor functions that can be bound to special keyboard
 shortcuts. The most important keybinding is probably the tab key, which is bound to the complete function.
 Here are some of the commands available in the editor:
 
-- Tab completes the current token
-- Home or Ctrl-a moves to the beginning of the line
-- End or Ctrl-e moves to the end of line
-- Left and right moves one character left or right
-- Alt-left and Alt-right moves one word left or right, or moves forward/backward in the directory history if the commandline is empty
-- Up and down search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the <a href='#history'>history </a>section for more information on history searching.
-- Alt-up and Alt-down search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the <a href='#history'>history </a>section for more information on history searching.
-- Delete and backspace removes one character forwards or backwards respectively
-- Ctrl-c deletes entire line
-- Ctrl-d delete one character to the right of the cursor, unless the buffer is empty, in which case the shell will exit
-- Ctrl-k move contents from the cursor to the end of line to the <a href="#killring">killring</a>
-- Ctrl-u move contents from the beginning of line to the cursor to the <a href="#killring">killring</a>
-- Ctrl-l clear and repaint screen
-- Ctrl-w move previous word to the <a href="#killring">killring</a>
-- Alt-d move next word to the <a href="#killring">killring</a>
-- Alt-w prints a short description of the command under the cursor
-- Alt-l lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed
-- Alt-p adds the string '| less;' to the end of the job under the cursor. The result is that the output of the command will be paged.
+- Tab <a href="#completion">completes</a> the current token
+- Home or Ctrl-A moves to the beginning of the line
+- End or Ctrl-E moves to the end of line
+- Left and Right moves one character left or right
+- Alt-Left and Alt-Right moves one word left or right, or moves forward/backward in the directory history if the commandline is empty
+- Up and Down search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the <a href='#history'>history </a>section for more information on history searching.
+- Alt-Up and Alt-Down search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the <a href='#history'>history </a>section for more information on history searching.
+- Delete and Backspace removes one character forwards or backwards respectively
+- Ctrl-C deletes entire line
+- Ctrl-D delete one character to the right of the cursor, unless the buffer is empty, in which case the shell will exit
+- Ctrl-K moves contents from the cursor to the end of line to the <a href="#killring">killring</a>
+- Ctrl-U moves contents from the beginning of line to the cursor to the <a href="#killring">killring</a>
+- Ctrl-L clears and repaints the screen
+- Ctrl-W moves the previous word to the <a href="#killring">killring</a>
+- Alt-D moves the next word to the <a href="#killring">killring</a>
+- Alt-W prints a short description of the command under the cursor
+- Alt-L lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed
+- Alt-P adds the string <code>'| less;'</code> to the end of the job under the cursor. The result is that the output of the command will be paged.
 
 You can change these key bindings using the
 <a href="commands.html#bind">bind</a> builtin command.
@@ -1160,8 +1162,8 @@ inserted into a linked list of kills, called the kill ring. To paste
 the latest value from the kill ring use Ctrl-Y. After pasting, use
 Meta-Y to rotate to the previous kill.
 
-If the environment variable DISPLAY is set, \c fish will try to
-connect to the X-windows server specified by this variable, and use
+If the environment variable DISPLAY is set and the \c xsel program is installed, \c fish will try to
+connect to the X Windows server specified by this variable, and use
 the clipboard on the X server for copying and pasting.
 
 \subsection history Searchable history
@@ -1173,7 +1175,7 @@ forwards and backwards in the history. If the current command line is
 not empty when starting a history search, only the commands containing
 the string entered into the command line are shown.
 
-By pressing Alt-up and Alt-down, a history search is also performed,
+By pressing Alt-Up and Alt-Down, a history search is also performed,
 but instead of searching for a complete commandline, each commandline
 is tokenized into separate elements just like it would be before
 execution, and each such token is matched against the token under the
@@ -1184,8 +1186,7 @@ History searches can be aborted by pressing the escape key.
 Prefixing the commandline with a space will prevent the entire line
 from being stored in the history.
 
-The history is stored in the file '~/.config/fish/fish_history'. It is automatically
-read on startup and merged on program exit.
+The history is stored in the file <code~/.config/fish/fish_history</code>.
 
 Example:
 
@@ -1198,9 +1199,9 @@ The fish commandline editor can be used to work on commands that are
 several lines long. There are three ways to make a command span more
 than a single line:
 
-- Pressing the enter key while a block of commands is unclosed, i.e. when one or more block commands such as 'for', 'begin' or 'if' do not have a corresponding 'end' command.
-- Pressing Alt-enter instead of pressing the enter key.
-- By backslash escaping a newline, i.e. by inserting a backslash (\\) character before pressing the enter key.
+- Pressing the Enter key while a block of commands is unclosed, such as when one or more block commands such as \c 'for', \c 'begin' or \c 'if' do not have a corresponding \c 'end' command.
+- Pressing Alt-Enter instead of pressing the Enter key.
+- By inserting a backslash (\\) character before pressing the Enter key, escaping the newline.
 
 The fish commandline editor works exactly the same in single line mode
 and in multiline mode. To move between lines use the left and right
@@ -1254,8 +1255,8 @@ end</pre>
 
 <a href="#variables-universal">Universal variables</a> are stored in
 the file .config/fish/fishd.MACHINE_ID, where MACHINE_ID is typically your
-MAC address. Do not edit this file directly, edit them through fish
-scripts or by using fish interactively instead.
+MAC address. Do not edit this file directly, as your edits may be overwritten.
+Edit them through fish scripts or by using fish interactively instead.
 
 \section other Other features