Various additions and fixes

doc_src/FORMATTING.md

@@ -102,4 +102,8 @@ Some useful Unicode/HTML5 entities:
 
 ### Lists
 
+### Synopsis rules
+
+### Prompts and cursor
+
 #### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)

doc_src/command.txt

@@ -10,7 +10,7 @@ command [OPTIONS] COMMANDNAME [ARGS...]
 `command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
 
 The following options are available:
-- `-h` or `--help` prints help and then exits.
+
 - `-s` or `--search` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the `$PATH`.
 
 With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found.

doc_src/commands.hdr.in

@@ -14,6 +14,21 @@
 \endhtmlonly
 `fish` ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.
 
+Almost all fish commands respond to the `-h` or `--help` options to display their relevant help, also accessible using the `help` and `man` commands, like so:
+
+\fish
+echo -h
+echo --help
+# Prints help to the terminal window
+
+man echo
+# Displays the man page in the system pager
+# (normally 'less', 'more' or 'most').
+
+help echo
+# Open a web browser to show the relevant documentation
+\endfish
+
 @command_list@
 
 \htmlonly[block]

doc_src/contains.txt

@@ -12,7 +12,6 @@ contains [OPTIONS] KEY [VALUES...]
 The following options are available:
 
 - `-i` or `--index` print the word index
-- `-h` or `--help` display this message
 
 
 \subsection contains-example Example

doc_src/count.txt

@@ -9,7 +9,7 @@ count $VARIABLE
 
 `count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
 
-`count` does not accept any options, including '`-h`'.
+`count` does not accept any options, including `-h` or `--help`.
 
 `count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.
 

doc_src/echo.txt

@@ -19,8 +19,6 @@ The following options are available:
 
 - `-e`, Enable interpretation of backslash escapes
 
-- `-h`, `--help` Display this help
-
 \subsection echo-escapes Escape Sequences
 
 If `-e` is used, the following sequences are recognized:

doc_src/fish.txt

@@ -15,8 +15,6 @@ The following options are available:
 
 - `-d` or `--debug-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
 
-- `-h` or `--help` display help and exit
-
 - `-i` or `--interactive` specify that fish is to run in interactive mode
 
 - `-l` or `--login` specify that fish is to run as a login shell

doc_src/fish_indent.txt

@@ -11,8 +11,6 @@ fish_indent [OPTIONS]
 
 The following options are available:
 
-- `-h` or `--help` displays this help message and then exits
-
 - `-i` or `--no-indent` do not indent commands
 
 - `-v` or `--version` displays the current fish version and then exits

doc_src/functions.txt

@@ -22,8 +22,6 @@ The following options are available:
 
 - `-e` or `--erase` causes the specified functions to be erased.
 
-- `-h` or `--help` displays a help message and exits.
-
 - `-n` or `--names` lists the names of all defined functions.
 
 - `-q` or `--query` tests if the specified functions exist.
@@ -42,9 +40,13 @@ The exit status of `functions` is the number of functions specified in the argum
 
 
 \subsection functions-example Examples
+\fish
+functions -n
+# Displays a list of currently-defined functions
 
-`functions -n` displays a list of currently-defined functions.
+functions -c foo bar
+# Copies the 'foo' function to a new function called 'bar'
 
-`functions -c foo bar` copies the `foo` function to a new function called `bar`.
-
-`functions -e bar` erases the function `bar`.
+functions -e bar
+# Erases the function `bar`
+\endfish

doc_src/index.hdr.in

@@ -430,11 +430,12 @@ echo (basename image.jpg .jpg).png
 for i in *.jpg; convert $i (basename $i .jpg).png; end
 # Convert all JPEG files in the current directory to the
 # PNG format using the 'convert' program.
+
+begin; set -l IFS; set data (cat data.txt); end
+# Set the `data` variable to the contents of 'data.txt'
+# without splitting it into an array.
 \endfish
 
-The command `begin; set -l IFS; set data (cat data.txt); end`
-will set the `data` variable to the contents of 'data.txt' without
-splitting it into an array.
 
 \subsection expand-brace Brace expansion
 
@@ -1036,8 +1037,11 @@ When the cursor is over a parenthesis or a quote, `fish` also highlights its mat
 
 To customize the syntax highlighting, you can set the environment variables `fish_color_normal`, `fish_color_command`, `fish_color_substitution`, `fish_color_redirection`, `fish_color_end`, `fish_color_error`, `fish_color_param`, `fish_color_comment`, `fish_color_match`, `fish_color_search_match`, `fish_color_cwd`, `fish_pager_color_prefix`, `fish_pager_color_completion`, `fish_pager_color_description`, `fish_pager_color_progress` and `fish_pager_color_secondary`. Usually, the value of these variables will be one of `black`, `red`, `green`, `brown`, `yellow`, `blue`, `magenta`, `purple`, `cyan`, `white` or `normal`, but they can be an array containing any color options for the `set_color` command.
 
-Issuing `set fish_color_error black --background=red --bold` will make all commandline errors be written in a black, bold font, with a red background.
-
+\fish
+set fish_color_error black --background=red --bold
+# Make all commandline errors be written in a black,
+# bold font, with a red background.
+\endfish
 
 \subsection title Programmable title
 

doc_src/jobs.txt

@@ -15,8 +15,6 @@ jobs accepts the following switches:
 
 - `-g` or `--group` only prints the group ID of each job.
 
-- `-h` or `--help` displays a help message and exits.
-
 - `-l` or `--last` prints only the last job to be started.
 
 - `-p` or `--pid` prints the process ID for each process in all jobs.

doc_src/mimedb.txt

@@ -25,6 +25,4 @@ The following options are available:
 
 - `-l`, `--launch` launches the default action for the specified files.
 
-- `-h`, `--help` displays a help message and exit.
-
 - `-v`, `--version` displays the version number and exits.

doc_src/read.txt

@@ -19,7 +19,7 @@ The following options are available:
 
 - `-m NAME` or `--mode-name=NAME` specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
 
-- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is `set_color green; echo read; set_color normal; echo "> "`.
+- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is <code>set_color green; echo read; set_color normal; echo "> "</code>.
 
 - `-s` or `--shell` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
 

doc_src/set_color.txt

@@ -17,8 +17,6 @@ The following options are available:
 
 - `-c`, `--print-colors` prints a list of all valid color names.
 
-- `-h`, `--help` displays a help message and exit.
-
 - `-o`, `--bold` sets bold or extra bright mode.
 
 - `-u`, `--underline` sets underlined mode.
@@ -38,6 +36,6 @@ Not all terminal emulators support all these features.
 \fish
 set_color red; echo "Roses are red"
 set_color blue; echo "Violets are blue"
-set_color 62A ; echo "Eggplants are dark purple"
+set_color 62A; echo "Eggplants are dark purple"
 set_color normal; echo "Normal is nice too"
 \endfish

doc_src/status.txt

@@ -32,5 +32,3 @@ The following options are available:
 - `-j CONTROLTYPE` or `--job-control=CONTROLTYPE` sets the job control type, which can be `none`, `full`, or `interactive`.
 
 - `-t` or `--print-stack-trace` prints a stack trace of all function calls on the call stack.
-
-- `-h` or `--help` displays a help message and exit.

doc_src/trap.txt

@@ -15,8 +15,6 @@ The following parameters are available:
 
 - `SIGSPEC` is the name of the signal to trap.
 
-- `-h` or `--help` displays help and exits.
-
 - `-l` or `--list-signals` prints a list of signal names.
 
 - `-p` or `--print` prints all defined signal handlers.

doc_src/tutorial.hdr

@@ -581,7 +581,7 @@ vim
 
 \section tut-more  Ready for more?
 
-If you want to learn more about fish, there is <a href="index.html">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel \#fish on `irc.oftc.net`, and the <a href="http://github.com/fish-shell/fish-shell/">github page</a>.
+If you want to learn more about fish, there is <a href="index.html">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel \#fish on `irc.oftc.net`, and the <a href="https://github.com/fish-shell/fish-shell/">github page</a>.
 
 \htmlonly[block]
 </div>

doc_src/type.txt

@@ -11,8 +11,6 @@ With no options, `type` indicates how each `NAME` would be interpreted if used a
 
 The following options are available:
 
-- `-h` or `--help` prints help and then exits.
-
 - `-a` or `--all` prints all of possible definitions of the specified names.
 
 - `-f` or `--no-functions` suppresses function and builtin lookup.

doc_src/ulimit.txt

@@ -49,8 +49,6 @@ The following additional options are also understood by `ulimit`:
 
 - `-a` or `--all` prints all current limits
 
-- `-h` or `--help` displays help and exits.
-
 The `fish` implementation of `ulimit` should behave identically to the implementation in bash, except for these differences:
 
 - Fish `ulimit` supports GNU-style long options for all switches