description of command-line options:

* describe --foo as standard long-option syntax, with -foo deprecated
* also describe other syntax rules


git-svn-id: http://svn.cactuscode.org/flesh/trunk@4333 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 62 insertions, 34 deletions

diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex
index 3ce4f1bf..43205cc9 100644
--- a/doc/UsersGuide/RunningCactus.tex
+++ b/doc/UsersGuide/RunningCactus.tex
@@ -1017,7 +1017,7 @@ by configure and the \texttt{ThornList} file remain.
 configuration using its previous configuration options from the file
 \texttt{configs/<\var{config}>/config-info}.
 
-\item [\texttt{gmake <\var{config}>-testsuite}] runs the test programs
+\item [\texttt{gmake <\var{config}>--testsuite}] runs the test programs
 associated with each thorn in the configuration. See section
 \ref{sec:testing} for information about the test suite mechanism.
 
@@ -1190,7 +1190,7 @@ Some thorns come with a test suite, consisting of example parameter files
 and the output files generated by running these. To run the test suite
 for the thorns you have compiled use
 
-\texttt{gmake <\var{configuration}>-testsuite}
+\texttt{gmake <\var{configuration}>--testsuite}
 
 These test suite serve the dual purpose of
 
@@ -1235,83 +1235,111 @@ creating thorn documentation.
 \section{Command Line Options}
 \label{sec:command_line_options}
 
-The Cactus executable accepts these command line arguments:
+Cactus uses the standard GNU style of long-named command-line options;
+many of these options also have traditional Unix single-letter short forms.
+The options follow the usual GNU rules:
+\begin{itemize}
+\item	A long-named option \verb|--foo| which takes an argument \verb|bar|
+	may be written as either \verb|--foo bar| or as \verb|--foo=bar|.
+\item	A long-named option may be abbreviated so long as the abbreviation
+	is unambiguous.
+\item	The preferred way of spelling a long-named option is \verb|--foo|,
+	but \verb|-foo| also accepted, though this is deprecated
+	(we plan to remove it after the next beta release).
+\item	A short option \verb|-X| which takes an argument \verb|bar|
+	may be written as either \verb|-Xbar| or as \verb|-X=bar|.
+\item	An option which can be interpreted as either a short option,
+	or as an abbreviated \verb|-foo|-style long option, is interpreted
+	as the former.  In particularl, \verb|-re| is interpreted as
+	an abbreviation for \verb|-redirect|, rather than as \verb|-r=e|.
+\end{itemize}
 
+The Cactus command line options are specified in
+table~\ref{tab:command-line-options}, and are as follows:
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{table}
 \texttt{
 \begin{tabular}{|l|l|}
 \hline
 Short Version & Long Version \\
 \hline
- -O[v] & -describe-all-parameters \\
+ -O[v] & --describe-all-parameters \\
 \hline
- -o<\var{param}> & -describe-parameter=<\var{param}> \\
+ -o<\var{param}> & --describe-parameter=<\var{param}> \\
 \hline
- -S & -print-schedule\\
+ -S & --print-schedule\\
 \hline
- -T & -list-thorns\\
+ -T & --list-thorns\\
 \hline
- -t<\var{arrangement/thorn}>& -test-thorn-compiled=<\var{arrangement/thorn}>\\
+ -t<\var{arrangement/thorn}>& --test-thorn-compiled=<\var{arrangement/thorn}>\\
 \hline
- -h,-? & -help\\
+ -h,-? & --help\\
 \hline
- -v & -version \\
+ -v & --version \\
 \hline
-% -x [<nprocs>] & -test-parameters [<nprocs>] \\
+% -x [<nprocs>] & --test-parameters [<nprocs>] \\
 %\hline
- -L<\var{level}> & -logging-level=<\var{level}> \\
+ -L<\var{level}> & --logging-level=<\var{level}> \\
 \hline
- -W<\var{level}> & -warning-level=<\var{level}> \\
+ -W<\var{level}> & --warning-level=<\var{level}> \\
 \hline
- -E<\var{level}> & -error-level=<\var{level}> \\
+ -E<\var{level}> & --error-level=<\var{level}> \\
 \hline
- -r[o|e|oe|eo] & -redirect=[o|e|oe|eo]\\
+ -r[o|e|oe|eo] & --redirect=[o|e|oe|eo]\\
 \hline
- -b <\var{mode}> & -buffering=<\var{mode}>\\
+ -b <\var{mode}> & --buffering=<\var{mode}>\\
 \hline
- -i & -ignore-next \\
+ -i & --ignore-next \\
 \hline
-    & -parameter-level=<\var{level}> \\
+    & --parameter-level=<\var{level}> \\
 \hline
 \end{tabular}
 }
+\caption[Command-Line Options]
+	{This table shows all the Cactus command-line options.}
+\label{tab:command-line-options}
+\end{table}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 
 \begin{Lentry}
-\item [\texttt{-O} or \texttt{-describe-all-parameters}]
+\item [\texttt{-O} or \texttt{--describe-all-parameters}]
 Prints a full list of all parameters from all thorns which were compiled,
 along with descriptions and allowed values.  This can take an optional extra
 parameter \texttt{v}  (i.e. \texttt{-Ov} to give verbose information about
 all parameters).
-\item [\texttt{-o<\var{param}>} or \texttt{-describe-parameter=<\var{param}>}]
+\item [\texttt{-o<\var{param}>} or \texttt{--describe-parameter=<\var{param}>}]
 Prints the description and allowed values for a given parameter --- takes one
 argument.
-\item [\texttt{-S} or \texttt{-print-schedule}]
+\item [\texttt{-S} or \texttt{--print-schedule}]
 Print only the schedule tree.
-\item [\texttt{-T} or \texttt{-list-thorns}]
+\item [\texttt{-T} or \texttt{--list-thorns}]
 Prints a list of all the thorns which were compiled in.
-\item [\texttt{-t<\var{arrangement or thorn}>} or \texttt{-test-thorn-compiled=<\var{arrangement or thorn>}} ]
+\item [\texttt{-t<\var{arrangement or thorn}>} or \texttt{--test-thorn-compiled=<\var{arrangement or thorn>}} ]
 Checks if a given thorn was compiled in --- takes one argument.
-\item [\texttt{-h}, \texttt{-?} or \texttt{-help}]
+\item [\texttt{-h}, \texttt{-?} or \texttt{--help}]
 Prints a help message.
-\item [\texttt{-v} or \texttt{-version}]
+\item [\texttt{-v} or \texttt{--version}]
 Prints version information of the code.
-%\item [\texttt{-x <nprocs>} or \texttt{-test-parameters <nprocs>}]
+%\item [\texttt{-x <nprocs>} or \texttt{--test-parameters <nprocs>}]
 %Runs the code far enough to check the consistency of the parameters.  If
 %given a numeric argument it will attempt to simulate being on that number
 %of processors. [To be implemented.]
-\item [\texttt{-L<\var{level}>} or \texttt{-logging-level=<\var{level}>}]
+\item [\texttt{-L<\var{level}>} or \texttt{--logging-level=<\var{level}>}]
 Sets the logging level of the code.  All warning messages are given a
 level --- the lower the level the greater the severity.  This
 parameter \texttt{-L} controls the level of messages to be seen, with all
 warnings of level $\le$ \texttt{<\var{level}>} printed to standard output.  The
 default is a logging level of~0, meaning that only level~0 messages
 should be printed to standard output.
-\item [\texttt{-W<\var{level}>} or \texttt{-warning-level=<\var{level}>}]
+\item [\texttt{-W<\var{level}>} or \texttt{--warning-level=<\var{level}>}]
 Similar to \texttt{-W}, but for standard error instead of
 standard output.  All warnings of level $\le$ \texttt{<\var{level}>} are
 printed to standard error.  The default is a warning level of~1,
 meaning that level~0 and level~1 messages should be printed to
 standard error.
-\item [\texttt{-E<\var{level}>} or \texttt{-error-level=<\var{level}>}]
+\item [\texttt{-E<\var{level}>} or \texttt{--error-level=<\var{level}>}]
 Similar to \texttt{-W}, but for fatal errors: Cactus treats all
 warnings with level $\le$ \texttt{<\var{level}>} as fatal errors, and aborts
 the Cactus run immediately (after printing the warning message%%%
@@ -1322,12 +1350,12 @@ the Cactus run immediately (after printing the warning message%%%
          }%%%
 ).  The default value is zero, \ie{} only level~0 warnings
 will abort the Cactus run.
-\item [\texttt{-r[o|e|oe|eo]} or \texttt{-redirect=[o|e|oe|eo]}]
+\item [\texttt{-r[o|e|oe|eo]} or \texttt{--redirect=[o|e|oe|eo]}]
 Redirects the standard output (`\texttt{o}') and/or standard error
 (`\texttt{e}') of each processor to a file.  By default
 the standard outputs from processors other than processor 0 are discarded.
 
-\item [\texttt{-b <\var{mode}>} or \texttt{-buffering=<\var{mode}>}]
+\item [\texttt{-b <\var{mode}>} or \texttt{--buffering=<\var{mode}>}]
   Set the \texttt{stdout} buffering mode.  \var{mode} can be one of
   \texttt{no}, \texttt{line}, and \texttt{full}.  Buffered I/O is a
   standard feature of C programmes.  This delays writing the actual
@@ -1342,9 +1370,9 @@ the standard outputs from processors other than processor 0 are discarded.
   messages, i.e.\ the \texttt{stderr} stream, is always unbuffered
   (and hence usually slower than \texttt{stdout}).
 
-\item [\texttt{-i} or \texttt{-ignore-next}]
+\item [\texttt{-i} or \texttt{--ignore-next}]
 Causes the next argument on the command line to be ignored.
-\item [\texttt{-parameter-level=<\var{level}>}]
+\item [\texttt{--parameter-level=<\var{level}>}]
 Sets the level of parameter checking to be used, one of \texttt{strict},
 \texttt{normal} (the default), or \texttt{relaxed}.
 See Section~\ref{sec:Parameter_File}.
@@ -1406,7 +1434,7 @@ that the above convention be followed.
 
 The Cactus Flesh performs checks for consistency and range of parameters.
 The severity of these checks is controlled by the command line argument
-\texttt{-parameter-level} which can take the following values
+\texttt{--parameter-level} which can take the following values
 \begin{Lentry}
 \item[\texttt{relaxed}] Cactus will issue a level 0 warning (that is the
 default behaviour will be to terminate) if