Doc: Usage --include option layout consistency

Tracker 2135

Made description arguments consistent with others,
so also had to swap two paras around so that '-i' came
before '-I'.

Also some minor blank line deletion (tidy up) to keep layout
in tex file consistent.

Added and hopfully improved some @cindex entries

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 4cc95d990ae2e86056bab18610557b584df902f1..7f49e9802df45fc33c3b6f6befe22c9313ab6198 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -133,38 +133,6 @@ The following options are supported:
 
 @table @code
 
-@item -e,--evaluate=@var{expr}
-Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
-Multiple @option{-e} options may be given, they will be evaluated
-sequentially.
-
-The expression will be evaluated in the @code{guile-user} module, so
-if you want to use definitions in @var{expr}, use
-
-@example
-lilypond -e '(define-public a 42)'
-@end example
-
-@noindent
-on the command-line, and include
-
-@example
-#(use-modules (guile-user))
-@end example
-
-@warning{Windows users must use double quotes instead of single quotes.}
-
-@noindent
-at the top of the @code{.ly} file.
-
-@item -f,--format=@var{format}
-which formats should be written.  Choices for @code{format} are
-@code{ps}, @code{pdf}, and @code{png}.
-
-Example: @code{lilypond -fpng @var{filename}.ly}
-
-
-
 @item -d,--define-default=@var{var}=@var{val}
 This sets the internal program option @var{var} to the Scheme value
 @var{val}.  If @var{val} is not supplied, then @var{#t} is used.  To
@@ -288,12 +256,14 @@ SVG output should be compatible with any SVG editor or user agent.
 @item scm
 
 @cindex Scheme dump
+@cindex output, Scheme dump
 
 for a dump of the raw, internal Scheme-based drawing commands.
 
 @item null
 do not output a printed score; has the same effect as
 @option{-dno-print-pages}.
+
 @end table
 
 Example: @code{lilypond -dbackend=svg @var{filename}.ly}
@@ -327,86 +297,62 @@ useful in combination with @option{-dpreview}.
 
 @end table
 
-@item -h,--help
-Show a summary of usage.
-
-@item -H,--header=@var{FIELD}
-Dump a header field to file @file{BASENAME.@var{FIELD}}.
-
-@cindex file searching
-@cindex search path
-
-@item --include, -I=@var{directory}
-Add @var{directory} to the search path for input files.
-
-Multiple -I options may be given.  The search will start in the first
-defined directory, and if the file to be included is not found the
-search will continue in subsequent directories.
-
-@item -i,--init=@var{file}
-Set init file to @var{file} (default: @file{init.ly}).
-
-@cindex loglevel
-@cindex output verbosity, setting
-
-@item -l,--loglevel=@var{LEVEL}
-Set the verbosity of the console output to @var{LEVEL}. Possible values
-are:
+@cindex Scheme, expression evaluation
+@cindex expression evalusation, Scheme
 
-@table @code
-
-@item NONE
-No output at all, not even error messages.
-
-@item ERROR
-Only error messages, no warnings or progress messages.
+@item -e,--evaluate=@var{expr}
+Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
+Multiple @option{-e} options may be given, they will be evaluated
+sequentially.
 
-@item WARN
-Warnings and error messages, no progress.
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
 
-@item BASIC_PROGRESS
-Basic progress messages (success), warnings and errors.
+@example
+lilypond -e '(define-public a 42)'
+@end example
 
-@item PROGRESS
-All progress messages, warnings and errors.
+@noindent
+on the command-line, and include
 
-@item INFO (default)
-Progress messages, warnings, errors and further execution information.
+@example
+#(use-modules (guile-user))
+@end example
 
-@item DEBUG
-All possible messages, including verbose debug output.
-@end table
+@warning{Windows users must use double quotes instead of single quotes.}
 
-@cindex folder, directing output to
-@cindex output filename, setting
+@noindent
+at the top of the @code{.ly} file.
 
-@item -o,--output=@var{FILE} or @var{FOLDER}
-Set the default output file to @var{FILE} or, if a folder with that name
-exists, direct the output to @var{FOLDER}, taking the file name from the
-input file.  The appropriate suffix will be added (e.g. @code{.pdf} for
-pdf) in both cases.
+@cindex output, format
+@cindex format, output
 
+@item -f,--format=@var{format}
+which formats should be written.  Choices for @code{format} are
+@code{ps}, @code{pdf}, and @code{png}.
 
-@cindex PostScript output
+Example: @code{lilypond -fpng @var{filename}.ly}
 
-@item --ps
-Generate PostScript.
+@item -h,--help
+Show a summary of usage.
 
-@cindex Portable Network Graphics (PNG) output
+@item -H,--header=@var{FIELD}
+Dump a header field to file @file{BASENAME.@var{FIELD}}.
 
-@item --png
-Generate pictures of each page, in PNG format.  This implies
-@option{--ps}.  The resolution in DPI of the image may be set with
-@example
--dresolution=110
-@end example
+@item -i,--init=@var{file}
+Set init file to @var{file} (default: @file{init.ly}).
 
-@cindex Portable Document Format (PDF) output
+@cindex file searching
+@cindex search path
 
-@item --pdf
-Generate PDF.  This implies @option{--ps}.
+@item -I, --include=@var{directory}
+Add @var{directory} to the search path for input files.
 
+Multiple -I options may be given.  The search will start in the first
+defined directory, and if the file to be included is not found the
+search will continue in subsequent directories.
 
+@cindex chroot jail, running inside
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
 Run @command{lilypond} in a chroot jail.
@@ -430,6 +376,7 @@ LilyPond is able to find whatever it needs to compile the source
 @emph{inside the jail}.  A typical setup comprises the following items:
 
 @table @asis
+
 @item Setting up a separate filesystem
 A separate filesystem should be created for LilyPond, so that it can be
 mounted with safe options such as @code{noexec}, @code{nodev}, and
@@ -465,8 +412,73 @@ possibly using @command{sudo}.  It is a good idea to limit the number of
 seconds of CPU time LilyPond can use (e.g., using @command{ulimit
 -t}), and, if your operating system supports it, the amount of memory
 that can be allocated.
+
 @end table
 
+@cindex loglevel
+@cindex output, verbosity
+
+@item -l,--loglevel=@var{LEVEL}
+Set the verbosity of the console output to @var{LEVEL}. Possible values
+are:
+
+@table @code
+
+@item NONE
+No output at all, not even error messages.
+
+@item ERROR
+Only error messages, no warnings or progress messages.
+
+@item WARN
+Warnings and error messages, no progress.
+
+@item BASIC_PROGRESS
+Basic progress messages (success), warnings and errors.
+
+@item PROGRESS
+All progress messages, warnings and errors.
+
+@item INFO (default)
+Progress messages, warnings, errors and further execution information.
+
+@item DEBUG
+All possible messages, including verbose debug output.
+
+@end table
+
+@cindex directory, redirect output
+@cindex output, setting filename
+@cindex output, directory
+
+@item -o,--output=@var{FILE} or @var{FOLDER}
+Set the default output file to @var{FILE} or, if a folder with that name
+exists, direct the output to @var{FOLDER}, taking the file name from the
+input file.  The appropriate suffix will be added (e.g. @code{.pdf} for
+pdf) in both cases.
+
+@cindex PS (Postscript), output
+@cindex Postscript (PS), output
+@cindex output, PS (Postscript)
+
+@item --ps
+Generate PostScript.
+
+@cindex PNG (Portable Network Graphics), output
+@cindex output, PNG (Portable Network Graphics)
+
+@item --png
+Generate pictures of each page, in PNG format.  This implies
+@option{--ps}.  The resolution in DPI of the image may be set with
+@example
+-dresolution=110
+@end example
+
+@cindex PDF (Portable Document Format), output
+@cindex output, PDF (Portable Document Format)
+
+@item --pdf
+Generate PDF.  This implies @option{--ps}.
 
 @item -v,--version
 Show version information.
@@ -478,6 +490,7 @@ information.
 @item -w,--warranty
 Show the warranty with which GNU LilyPond comes.  (It comes with
 @strong{NO WARRANTY}!)
+
 @end table