Documentation update

Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.

doc_src/functions.txt

@@ -1,51 +1,53 @@
 \section functions functions - print or erase functions
 
-\subsection function-synopsis Synopsis
-<pre>functions [-n]
+\subsection functions-synopsis Synopsis
+\fish{syn}
+functions [-a|--all] [-n|--names]
 functions -c OLDNAME NEWNAME
 functions -d DESCRIPTION FUNCTION
-functions [-eq] FUNCTIONS...</pre>
+functions [-eq] FUNCTIONS...
+\endfish
 
 \subsection functions-description Description
 
-\c functions prints or erases functions.
+`functions` prints or erases functions.
 
 The following options are available:
 
-- <code>-a</code> or <code>--all</code> lists all functions, even those whose name start with an underscore.
-- <code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function.
-- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> changes the description of this function.
-- <code>-e</code> or <code>--erase</code> causes the specified functions to be erased.
-- <code>-h</code> or <code>--help</code> displays a help message and exits.
-- <code>-n</code> or <code>--names</code> lists the names of all defined functions.
-- <code>-q</code> or <code>--query</code> tests if the specified functions exist.
+- `-a` or `--all` lists all functions, even those whose name start with an underscore.
+- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.
+- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.
+- `-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.
 
-The default behavior of <code>functions</code>, when called with no arguments,
-is to print the names of all defined functions. Unless the \c -a option is
+The default behavior of `functions`, when called with no arguments,
+is to print the names of all defined functions. Unless the `-a` option is
 given, no functions starting with underscores are not included in the output.
 
 If any non-option parameters are given, the definition of the specified
 functions are printed.
 
-Automatically loaded functions cannot be removed using <code>functions
--e</code>. Either remove the definition file or change the
+Automatically loaded functions cannot be removed using `functions
+-e`. Either remove the definition file or change the
 $fish_function_path variable to remove autoloaded functions.
 
-Copying a function using \c -c copies only the body of the function, and
+Copying a function using `-c` copies only the body of the function, and
 does not attach any event notifications from the original function.
 
 Only one function's description can be changed in a single invocation
-of <code>functions -d</code>.
+of `functions -d`.
 
-The exit status of \c functions is the number of functions
+The exit status of `functions` is the number of functions
 specified in the argument list that do not exist, which can be used in
-concert with the \c -q option.
+concert with the `-q` option.
 
 \subsection functions-example Examples
 
-<code>functions -n</code> displays a list of currently-defined functions.
+`functions -n` displays a list of currently-defined functions.
 
-<code>functions -c foo bar</code> copies the \c foo function to a new function called
-<code>bar</code>.
+`functions -c foo bar` copies the `foo` function to a new function called
+`bar`.
 
-<code>functions -e bar</code> erases the function <code>bar</code>.
+`functions -e bar` erases the function `bar`.