Merge branch 'master' into lilypond/translation

[lilypond.git] / Documentation / usage / running.itely

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 263a7e8c9b76a8489a3a496cc5480c679f82d4fa..147bc84c6720737698a69ed46e9f079af004c0dc 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.12.0"
+@c \version "2.14.0"

 
 
 @node Running lilypond
 
 
 @node Running lilypond


@@ -97,6 +97,30 @@ will output @var{base}@file{-violin.pdf} and
 @var{base}@file{-cello-1.pdf}.
 
 
 @var{base}@file{-cello-1.pdf}.
 
 

+@unnumberedsubsubsec Standard shell commands
+
+If your shell (i.e. command window) supports normal redirects,
+then you might find it useful to use the following commands to
+redirect console output to a file:
+
+@itemize
+
+@item
+@code{lilypond file.ly 1>stdout.log} to redirect normal output
+
+@item
+@code{lilypond file.ly 2>stderr.log} to redirect error messages
+
+@item
+@code{lilypond file.ly &>all.log} to redirect all output
+
+@end itemize
+
+Consult the documentation for your shell to see if it supports these
+options, or if the syntax is different.  Note that these are shell
+commands and have nothing to do with lilypond.
+
+

 @node Command line options for lilypond
 @unnumberedsubsec Command line options for @command{lilypond}
 
 @node Command line options for lilypond
 @unnumberedsubsec Command line options for @command{lilypond}
 


@@ -111,7 +135,7 @@ The following options are supported:
 
 @item -e,--evaluate=@var{expr}
 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
 
 @item -e,--evaluate=@var{expr}
 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.

-Multiple @code{-e} options may be given, they will be evaluated
+Multiple @option{-e} options may be given, they will be evaluated

 sequentially.
 
 The expression will be evaluated in the @code{guile-user} module, so
 sequentially.
 
 The expression will be evaluated in the @code{guile-user} module, so


@@ -162,7 +186,7 @@ Here are a few interesting options.
 
 @table @samp
 @item help
 
 @table @samp
 @item help

-Running @code{lilypond -dhelp} will print all of the @code{-d} options
+Running @code{lilypond -dhelp} will print all of the @option{-d} options

 available.
 
 @cindex paper-size, command line
 available.
 
 @cindex paper-size, command line


@@ -183,8 +207,8 @@ Note that the string must be enclosed in escaped quotes ( @code{\"} ).
 Do not trust the @code{.ly} input.
 
 When LilyPond formatting is available through a web server, either the
 Do not trust the @code{.ly} input.
 
 When LilyPond formatting is available through a web server, either the

-@code{--safe} or the @code{--jail} option @b{MUST} be passed.  The
-@code{--safe} option will prevent inline Scheme code from wreaking
+@option{--safe} or the @option{--jail} option @b{MUST} be passed.  The
+@option{--safe} option will prevent inline Scheme code from wreaking

 havoc, for example
 
 @quotation
 havoc, for example
 
 @quotation


@@ -196,10 +220,10 @@ havoc, for example
 @end verbatim
 @end quotation
 
 @end verbatim
 @end quotation
 

-The @code{-dsafe} option works by evaluating in-line Scheme
+The @option{-dsafe} option works by evaluating in-line Scheme

 expressions in a special safe module.  This safe module is derived from
 GUILE @file{safe-r5rs} module, but adds a number of functions of the
 expressions in a special safe module.  This safe module is derived from
 GUILE @file{safe-r5rs} module, but adds a number of functions of the

-LilyPond API.  These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
+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 addition, safe mode disallows @code{\include} directives and
 disables the use of backslashes in @TeX{} strings.


@@ -207,14 +231,14 @@ 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.
 

-@code{-dsafe} does @emph{not} detect resource overuse.  It is still possible to
+@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
 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

-compiled.  The @code{--jail} is a more secure alternative, but
+compiled.  The @option{--jail} is a more secure alternative, but

 requires more work to set up.
 
 @cindex output format, setting
 requires more work to set up.
 
 @cindex output format, setting


@@ -262,7 +286,7 @@ This mode is used by default by @command{lilypond-book}.
  for a dump of the raw, internal Scheme-based drawing commands.
 
 @item null
  for a dump of the raw, internal Scheme-based drawing commands.
 
 @item null

- do not output a printed score; has the same effect as @code{-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}
 @end table
 
 Example: @code{lilypond -dbackend=svg @var{filename}.ly}


@@ -275,9 +299,19 @@ first system of every @code{\bookpart} will appear in the output.
 The @code{ps}, @code{eps}, and @code{svg} backends support this
 option.
 
 The @code{ps}, @code{eps}, and @code{svg} backends support this
 option.
 

+@item gui
+Runs silently and redirect all output to a log file.
+
+Note to Windows users: By default @code{lilypond.exe} outputs all
+progress information to the command window, @code{lilypond-windows.exe}
+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
 @item print-pages

-Generate the full pages, the default.  @code{-dno-print-pages} is
-useful in combination with @code{-dpreview}.
+Generate the full pages, the default.  @option{-dno-print-pages} is
+useful in combination with @option{-dpreview}.

 
 @end table
 
 
 @end table
 


@@ -301,6 +335,35 @@ found the search will continue in subsequent directories.
 @item -i,--init=@var{file}
 Set init file to @var{file} (default: @file{init.ly}).
 
 @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:
+@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 folder, directing output to
 @cindex output filename, setting
 
 @cindex folder, directing output to
 @cindex output filename, setting
 


@@ -320,7 +383,7 @@ Generate PostScript.
 
 @item --png
 Generate pictures of each page, in PNG format.  This implies
 
 @item --png
 Generate pictures of each page, in PNG format.  This implies

-@code{--ps}.  The resolution in DPI of the image may be set with
+@option{--ps}.  The resolution in DPI of the image may be set with

 @example
 -dresolution=110
 @end example
 @example
 -dresolution=110
 @end example


@@ -328,24 +391,24 @@ Generate pictures of each page, in PNG format.  This implies
 @cindex Portable Document Format (PDF) output
 
 @item --pdf
 @cindex Portable Document Format (PDF) output
 
 @item --pdf

-Generate PDF.  This implies @code{--ps}.
+Generate PDF.  This implies @option{--ps}.

 
 
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
 Run @command{lilypond} in a chroot jail.
 
 
 
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
 Run @command{lilypond} in a chroot jail.
 

-The @code{--jail} option provides a more flexible alternative to
-@code{--safe} when LilyPond formatting is available through a web
+The @option{--jail} option provides a more flexible alternative to
+@option{--safe} when LilyPond formatting is available through a web

 server or whenever LilyPond executes externally provided
 sources.
 
 server or whenever LilyPond executes externally provided
 sources.
 

-The @code{--jail} option works by changing the root of @command{lilypond} to
+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
 @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

-@code{--jail} to work @command{lilypond} must be run as root, which is usually
+@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
 accomplished in a safe way using @command{sudo}.
 
 Setting up a jail is a slightly delicate matter, as we must be sure that


@@ -421,11 +484,15 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 @item LANG
 This selects the language for the warning messages.
 
 @item LANG
 This selects the language for the warning messages.
 

+@item LILYPOND_LOGLEVEL
+The default loglevel. If LilyPond is called without an explicit loglevel (i.e.
+no @option{--loglevel} command line option), this value is used.
+

 @item LILYPOND_GC_YIELD
 @item LILYPOND_GC_YIELD

-With this variable the memory footprint and performance can be
-adjusted.  It is a percentage tunes memory management behavior.  With
-higher values, the program uses more memory, with smaller values, it
-uses more CPU time.  The default value is @code{70}.
+A variable, as a percentage, that tunes memory management
+behavior.  A higher values means the program uses more memory, a
+smaller value means more CPU time is used.  The default value is
+@code{70}.

 
 @end table
 
 
 @end table
 


@@ -483,7 +550,10 @@ You can use @code{sed} to create the necessary copy commands for a given
 executable:
 
 @example
 executable:
 
 @example

-for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done
+for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
+  do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
+    cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
+      \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done

 @end example
 
 @end itemize
 @end example
 
 @end itemize


@@ -524,18 +594,25 @@ cp -L /usr/bin/convert /usr/bin/gs usr/bin
 cp -L /usr/share/fonts/truetype usr/share/fonts
 
 # Now the library copying magic
 cp -L /usr/share/fonts/truetype usr/share/fonts
 
 # Now the library copying magic

-for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done | sh -s
+for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
+  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
+    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
+      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
+        | sed '/.*=>.*/d'; done | sh -s

 
 # The shared files for ghostscript...
       cp -L -r /usr/share/ghostscript usr/share
 # The shared files for ImageMagick
       cp -L -r /usr/lib/ImageMagick* usr/lib
 
 
 # The shared files for ghostscript...
       cp -L -r /usr/share/ghostscript usr/share
 # The shared files for ImageMagick
       cp -L -r /usr/lib/ImageMagick* usr/lib
 

-### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome, you should be able to run:
-### Note that /$lilyprefix/bin/lilypond is a script, which sets the LD_LIBRARY_PATH - this is crucial
+### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
+### you should be able to run:
+### Note that /$lilyprefix/bin/lilypond is a script, which sets the
+### LD_LIBRARY_PATH - this is crucial

       /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
 @end example
 
       /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
 @end example
 

+@c " keep quote signs balanced for context-sensitive editors

 
 @node Error messages
 @section Error messages
 
 @node Error messages
 @section Error messages


@@ -568,8 +645,8 @@ happens rarely.  The most usual cause is misinstalled fonts.
 @cindex call trace
 @cindex Scheme error
 Errors that occur while executing Scheme code are caught by the Scheme
 @cindex call trace
 @cindex Scheme error
 Errors that occur while executing Scheme code are caught by the Scheme

-interpreter.  If running with the verbose option (@code{-V} or
-@code{--verbose}) then a call trace of the offending
+interpreter.  If running with the verbose option (@option{-V} or
+@option{--verbose}) then a call trace of the offending

 function call is printed.
 
 @item Programming error
 function call is printed.
 
 @item Programming error


@@ -628,6 +705,7 @@ are easily handled.
 * Apparent error in ../ly/init.ly::
 * Error message Unbound variable %::
 * Error message FT_Get_Glyph_Name::
 * Apparent error in ../ly/init.ly::
 * Error message Unbound variable %::
 * Error message FT_Get_Glyph_Name::

+* Warning staff affinities should only decrease::

 @end menu
 
 @node Music runs off the page
 @end menu
 
 @node Music runs off the page


@@ -717,7 +795,7 @@ problem:
 @unnumberedsubsec Apparent error in @code{../ly/init.ly}
 
 Various obscure error messages may appear about syntax errors in
 @unnumberedsubsec Apparent error in @code{../ly/init.ly}
 
 Various obscure error messages may appear about syntax errors in

-@code{../ly/init.ly} if the input file is not correctly formed,
+@file{../ly/init.ly} if the input file is not correctly formed,

 for example, if it does not contain correctly
 matched braces or quote signs.
 
 for example, if it does not contain correctly
 matched braces or quote signs.
 


@@ -733,7 +811,7 @@ of a lyrics block and the terminating brace, (@code{@}}).  Without
 this separation the brace is taken to be part of the syllable.  It
 is always advisable to ensure there is white space before and after
 @emph{every} brace.  For the importance of this when using lyrics,
 this separation the brace is taken to be part of the syllable.  It
 is always advisable to ensure there is white space before and after
 @emph{every} brace.  For the importance of this when using lyrics,

-see @ruser{Lyrics explained}.
+see @ruser{Entering lyrics}.

 
 This error message can also appear if a terminating quote sign,
 (@code{"}), is omitted.  In this case an accompanying error message
 
 This error message can also appear if a terminating quote sign,
 (@code{"}), is omitted.  In this case an accompanying error message


@@ -761,4 +839,18 @@ an input file contains a non-ASCII character and was not saved in
 UTF-8 encoding.  For details, see @ruser{Text encoding}.
 
 
 UTF-8 encoding.  For details, see @ruser{Text encoding}.
 
 

+@node Warning staff affinities should only decrease
+@unnumberedsubsec Warning staff affinities should only decrease
+This warning can appear if there are no staves in the printed
+output, for example if there are just a @code{ChordName} context
+and a @code{Lyrics} context as in a lead sheet.  The warning
+messages can be avoided by making one of the contexts behave as a
+staff by inserting

 
 

+@example
+\override VerticalAxisGroup #'staff-affinity = ##f
+@end example
+
+@noindent
+at its start.  For details, see @qq{Spacing of non-staff lines} in
+@ruser{Flexible vertical spacing within systems}.