Docs: Usage: add warning about 'staff-affinities

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

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 263a7e8c9b76a8489a3a496cc5480c679f82d4fa..c0835ac21b63f25904caa15cc85575ce9bb6e77b 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -97,6 +97,30 @@ will output @var{base}@file{-violin.pdf} and
 @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}
 
@@ -483,7 +507,10 @@ You can use @code{sed} to create the necessary copy commands for a given
 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
@@ -524,18 +551,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
-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
 
-### 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
 
+@c " keep quote signs balanced for context-sensitive editors
 
 @node Error messages
 @section Error messages
@@ -628,6 +662,7 @@ are easily handled.
 * 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
@@ -761,4 +796,17 @@ an input file contains a non-ASCII character and was not saved in
 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 @ruser{Spacing of non-staff lines}.