Doc: Two doc improvements for LP CLI in Usage

In response to Tracker Items 2114 and 2112

2112
Clarified explanation as suggested by listing the backends and added
additional options to avoid the addition files generated by -dpreview
as suggested.

Changed once instance of back-end to 'backend' as this seems to be
the standard term in the AU doc.

2114
Application Usage 1.2

Changed the way the @table is formatted so that the single quotes are
removed from the options listed.

Took some time to edit some of the linebreaks within the *.itely file so that
it follows the line lengths as per the CG.

Minor line spacing edits to make existing @cindex and @item enries
clearer to see in the source file for future editing

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 4abfcf09b13b677717081af5facce9cb36bb5fad..ba6f48b6f80aac2e274a149f9a31db70ecf2e6c7 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -180,11 +180,12 @@ is the same as
 -dpoint-and-click='#f'
 @end example
 
-Here are a few interesting options.
+The following options are supported:
 
 @cindex help, command line
 
-@table @samp
+@table @code
+
 @item help
 Running @code{lilypond -dhelp} will print all of the @option{-d} options
 available.
@@ -228,39 +229,44 @@ LilyPond API.  These functions are listed in @file{scm/safe-lily.scm}.
 In addition, safe mode disallows @code{\include} directives and
 disables the use of backslashes in @TeX{} strings.
 
-In safe mode, it is not possible to import LilyPond variables
-into Scheme.
+In safe mode, it is not possible to import LilyPond variables into
+Scheme.
 
-@option{-dsafe} does @emph{not} detect resource overuse.  It is still possible to
-make the program hang indefinitely, for example by feeding cyclic data
-structures into the backend.  Therefore, if using LilyPond on a
-publicly accessible webserver, the process should be limited in both
-CPU and memory usage.
+@option{-dsafe} does @emph{not} detect resource overuse.  It is still
+possible to make the program hang indefinitely, for example by feeding
+cyclic data structures into the backend.  Therefore, if using LilyPond
+on a publicly accessible webserver, the process should be limited in
+both CPU and memory usage.
 
-The safe mode will prevent many useful LilyPond snippets from being
+Safe mode will prevent many useful LilyPond snippets from being
 compiled.  The @option{--jail} is a more secure alternative, but
 requires more work to set up.
 
 @cindex output format, setting
+
 @item backend
-the output format to use for the back-end.  Choices for @code{format} are
+the output format to use for the backend.  Choices for @code{format}
+are:
+
 @table @code
 @item ps
+
 @cindex PostScript output
- for PostScript.
 
-  Postscript files include TTF, Type1 and OTF fonts.  No subsetting of
-  these fonts is done.  When using oriental character sets, this can
-  lead to huge files.
+for PostScript.
+
+Postscript files include TTF, Type1 and OTF fonts.  No subsetting of
+these fonts is done.  When using oriental character sets, this can lead
+to huge files.
 
 @item eps
 
 @cindex Postscript, encapsulated
 @cindex EPS (Encapsulated PostScript)
 
- for encapsulated PostScript.  This dumps every page (system) as a separate
-@file{EPS} file, without fonts, and as one collated @file{EPS} file with
-all pages (systems) including fonts.
+for encapsulated PostScript.  This dumps every page (system) as a
+separate @file{EPS} file, without fonts, and as one collated @file{EPS}
+file with all pages (systems) including fonts.
 
 This mode is used by default by @command{lilypond-book}.
 
@@ -268,36 +274,41 @@ This mode is used by default by @command{lilypond-book}.
 
 @cindex SVG (Scalable Vector Graphics)
 
- for SVG (Scalable Vector Graphics).
+for SVG (Scalable Vector Graphics).
 
- This creates a single SVG file, without embedded fonts, for every
- page of output.  It is recommended to install the Century
- Schoolbook fonts, included with your LilyPond installation, for
- optimal rendering.  Under UNIX, simply copy these fonts from the
- LilyPond directory (typically
- @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
- @file{~/.fonts/}.  The SVG output should be compatible with any
- SVG editor or user agent.
+This creates a single SVG file, without embedded fonts, for every page
+of output.  It is recommended to install the Century Schoolbook fonts,
+included with your LilyPond installation, for optimal rendering.  Under
+UNIX, simply copy these fonts from the LilyPond directory (typically
+@file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}.  The
+SVG output should be compatible with any SVG editor or user agent.
 
 @item scm
 
 @cindex Scheme dump
 
- for a dump of the raw, internal Scheme-based drawing commands.
+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}.
+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}
 
 @item preview
+
 @cindex preview, command line
-Generate an output file containing the titles and the first system
-of music.  If @code{\bookpart} blocks are used, the titles and
-first system of every @code{\bookpart} will appear in the output.
-The @code{ps}, @code{eps}, and @code{svg} backends support this
-option.
+
+This option is supported by all backends; @code{pdf}, @code{png},
+@code{ps}, @code{eps} and @code{svg}, but not @code{scm} and generates
+an output file containing the titles and the first system of music.  If
+@code{\bookpart} blocks are used, the titles and first system of every
+@code{\bookpart} will appear in the output.
+
+An additional file in the form @code{myFile.preview.extensio} is
+generated, to avoid this use the additional @option{-dprint-pages} or
+@option{-dno-print-pages} options according to your requirements.
 
 @item gui
 Runs silently and redirect all output to a log file.
@@ -308,15 +319,12 @@ does not and returns a prompt, with no progress information, immediately
 at the command line.  The @option{-dgui} option can be used in this case
 to redirect output to a log file.
 
-
 @item print-pages
 Generate the full pages, the default.  @option{-dno-print-pages} is
 useful in combination with @option{-dpreview}.
 
 @end table
 
-
-
 @item -h,--help
 Show a summary of usage.
 
@@ -325,12 +333,13 @@ 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.
+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}).
@@ -339,8 +348,11 @@ Set init file to @var{file} (default: @file{init.ly}).
 @cindex output verbosity, setting
 
 @item -l,--loglevel=@var{LEVEL}
-Set the verbosity of the console output to @var{LEVEL}. Possible values are:
+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.
 
@@ -363,15 +375,14 @@ Progress messages, warnings, errors and further execution information.
 All possible messages, including verbose debug output.
 @end table
 
-
 @cindex folder, directing output to
 @cindex output filename, setting
 
 @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.
+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 PostScript output
@@ -403,13 +414,14 @@ The @option{--jail} option provides a more flexible alternative to
 server or whenever LilyPond executes externally provided
 sources.
 
-The @option{--jail} option works by changing the root of @command{lilypond} to
-@var{jail} just before starting the actual compilation process.  The user
-and group are then changed to match those provided, and the current
-directory is changed to @var{dir}.  This setup guarantees that it is not
-possible (at least in theory) to escape from the jail.  Note that for
-@option{--jail} to work @command{lilypond} must be run as root, which is usually
-accomplished in a safe way using @command{sudo}.
+The @option{--jail} option works by changing the root of
+@command{lilypond} to @var{jail} just before starting the actual
+compilation process.  The user and group are then changed to match those
+provided, and the current directory is changed to @var{dir}.  This setup
+guarantees that it is not possible (at least in theory) to escape from
+the jail.  Note that for @option{--jail} to work @command{lilypond} must
+be run as root, which is usually accomplished in a safe way using
+@command{sudo}.
 
 Setting up a jail is a slightly delicate matter, as we must be sure that
 LilyPond is able to find whatever it needs to compile the source