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.

1 files changed, 55 insertions, 53 deletions

diff --git a/doc_src/test.txt b/doc_src/test.txt
index 809c3eaf..ba0eb0eb 100644
--- a/doc_src/test.txt
+++ b/doc_src/test.txt
@@ -1,7 +1,9 @@
 \section test test - perform tests on files and text
 
 \subsection test-synopsis Synopsis
- <tt>test [EXPRESSION]</tt>
+\fish{syn}
+test [EXPRESSION]
+\endfish
 
 \subsection test-description Description
 
@@ -10,68 +12,68 @@ and 1 if false. An expression is made up of one or more operators
 and their arguments.
 
 The following operators are available to examine files and directories:
-- <tt>-b FILE</tt> returns true if \c FILE is a block device.
-- <tt>-c FILE</tt> returns true if \c FILE is a character device.
-- <tt>-d FILE</tt> returns true if \c FILE is a directory.
-- <tt>-e FILE</tt> returns true if \c FILE exists.
-- <tt>-f FILE</tt> returns true if \c FILE is a regular file.
-- <tt>-g FILE</tt> returns true if \c FILE has the set-group-ID bit set.
-- <tt>-G FILE</tt> returns true if \c FILE exists and has the same group ID
+- `-b FILE` returns true if `FILE` is a block device.
+- `-c FILE` returns true if `FILE` is a character device.
+- `-d FILE` returns true if `FILE` is a directory.
+- `-e FILE` returns true if `FILE` exists.
+- `-f FILE` returns true if `FILE` is a regular file.
+- `-g FILE` returns true if `FILE` has the set-group-ID bit set.
+- `-G FILE` returns true if `FILE` exists and has the same group ID
 as the current user.
-- <tt>-L FILE</tt> returns true if \c FILE is a symbolic link.
-- <tt>-O FILE</tt> returns true if \c FILE exists and is owned by the current
+- `-L FILE` returns true if `FILE` is a symbolic link.
+- `-O FILE` returns true if `FILE` exists and is owned by the current
 user.
-- <tt>-p FILE</tt> returns true if \c FILE is a named pipe.
-- <tt>-r FILE</tt> returns true if \c FILE is marked as readable.
-- <tt>-s FILE</tt> returns true if the size of \c FILE is greater than zero.
-- <tt>-S FILE</tt> returns true if \c FILE is a socket.
-- <tt>-t FD</tt> returns true if the file descriptor \c FD is a terminal (TTY).
-- <tt>-u FILE</tt> returns true if \c FILE has the set-user-ID bit set.
-- <tt>-w FILE</tt> returns true if \c FILE is marked as writable; note that this does not check if the filesystem is read-only.
-- <tt>-x FILE</tt> returns true if \c FILE is marked as executable.
+- `-p FILE` returns true if `FILE` is a named pipe.
+- `-r FILE` returns true if `FILE` is marked as readable.
+- `-s FILE` returns true if the size of `FILE` is greater than zero.
+- `-S FILE` returns true if `FILE` is a socket.
+- `-t FD` returns true if the file descriptor `FD` is a terminal (TTY).
+- `-u FILE` returns true if `FILE` has the set-user-ID bit set.
+- `-w FILE` returns true if `FILE` is marked as writable; note that this does not check if the filesystem is read-only.
+- `-x FILE` returns true if `FILE` is marked as executable.
 
 The following operators are available to compare and examine text strings:
-- <tt>STRING1 = STRING2</tt> returns true if the strings \c STRING1 and
-\c STRING2 are identical.
-- <tt>STRING1 != STRING2</tt> returns true if the strings \c STRING1 and
-\c STRING2 are not identical.
-- <tt>-n STRING</tt> returns true if the length of \c STRING is non-zero.
-- <tt>-z STRING</tt> returns true if the length of \c STRING is zero.
+- `STRING1 = STRING2` returns true if the strings `STRING1` and
+`STRING2` are identical.
+- `STRING1 != STRING2` returns true if the strings `STRING1` and
+`STRING2` are not identical.
+- `-n STRING` returns true if the length of `STRING` is non-zero.
+- `-z STRING` returns true if the length of `STRING` is zero.
 
 The following operators are available to compare and examine numbers:
-- <tt>NUM1 -eq NUM2</tt> returns true if \c NUM1 and \c NUM2 are numerically equal.
-- <tt>NUM1 -ne NUM2</tt> returns true if \c NUM1 and \c NUM2 are not numerically equal.
-- <tt>NUM1 -gt NUM2</tt> returns true if \c NUM1 is greater than <tt>NUM2</tt>.
-- <tt>NUM1 -ge NUM2</tt> returns true if \c NUM1 is greater than or equal to <tt>NUM2</tt>.
-- <tt>NUM1 -lt NUM2</tt> returns true if \c NUM1 is less than <tt>NUM2</tt>.
-- <tt>NUM1 -le NUM2</tt> returns true if \c NUM1 is less than or equal to <tt>NUM2</tt>.
+- `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal.
+- `NUM1 -ne NUM2` returns true if `NUM1` and `NUM2` are not numerically equal.
+- `NUM1 -gt NUM2` returns true if `NUM1` is greater than `NUM2`.
+- `NUM1 -ge NUM2` returns true if `NUM1` is greater than or equal to `NUM2`.
+- `NUM1 -lt NUM2` returns true if `NUM1` is less than `NUM2`.
+- `NUM1 -le NUM2` returns true if `NUM1` is less than or equal to `NUM2`.
 
 Note that only integers are supported. For more complex mathematical
-operations, including fractions, the \c env program may be useful. Consult the
+operations, including fractions, the `env` program may be useful. Consult the
 documentation for your operating system.
 
 Expressions can be combined using the following operators:
-- <tt>COND1 -a COND2</tt> returns true if both \c COND1 and \c COND2 are true.
-- <tt>COND1 -o COND2</tt> returns true if either \c COND1 or \c COND2 are true.
+- `COND1 -a COND2` returns true if both `COND1` and `COND2` are true.
+- `COND1 -o COND2` returns true if either `COND1` or `COND2` are true.
 
-Expressions can be inverted using the \c ! operator:
-- <tt>! EXPRESSION</tt> returns true if \c EXPRESSION is false, and false if
-\c EXPRESSION is true.
+Expressions can be inverted using the `!` operator:
+- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if
+`EXPRESSION` is true.
 
 Expressions can be grouped using parentheses.
-- <tt>( EXPRESSION )</tt> returns the value of <tt>EXPRESSION</tt>.
-Note that parentheses will usually require escaping with <tt>\\(</tt> to avoid
+- `( EXPRESSION )` returns the value of `EXPRESSION`.
+Note that parentheses will usually require escaping with `\\(` to avoid
 being interpreted as a command substitution.
 
 \subsection test-example Examples
 
-If the \c /tmp directory exists, copy the \c /etc/motd file to it:
+If the `/tmp` directory exists, copy the `/etc/motd` file to it:
 
-<pre>
+\fish
 if test -d /tmp
     cp /etc/motd /tmp/motd
 end
-</pre>
+\endfish
 
 If the variable \c MANPATH is defined and not empty, print the contents.
 (If \c MANPATH is not defined, then it will expand to zero arguments, unless
@@ -81,29 +83,29 @@ quoted.)
 if test -n "$MANPATH"
     echo $MANPATH
 end
-</pre>
+\endfish
 
-Parentheses and the \c -o and \c -a operators can be combined to produce
+Parentheses and the `-o` and `-a` operators can be combined to produce
 more complicated expressions. In this example, success is printed if there is
-a \c /foo or \c /bar file as well as a \c /baz or \c /bat file.
+a `/foo` or `/bar` file as well as a `/baz` or `/bat` file.
 
-<pre>
-if test \\( -f /foo -o -f /bar \\) -a \\( -f /baz -o -f /bat \\)
+\fish
+if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \)
     echo Success.
 end.
-</pre>
+\endfish
 
 \subsection test-standards Standards
 
-\c test implements a subset of the
+`test` implements a subset of the
 <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008
 (POSIX.1) standard</a>. The following exceptions apply:
-- The \c < and \c > operators for comparing strings are not implemented.
+- The `<` and `>` operators for comparing strings are not implemented.
 - Because this test is a shell builtin and not a standalone utility, using
  the -c flag on a special file descriptors like standard input and output
  may not return the same result when invoked from within a pipe as one
- would expect when invoking the \c test utility in another shell.
- 
- In cases such as this, one can use \c command \c test to explicitly
- use the system's standalone \c test rather than this \c builtin \c test.
+ would expect when invoking the `test` utility in another shell.
+
+ In cases such as this, one can use `command` `test` to explicitly
+ use the system's standalone `test` rather than this `builtin` `test`.