Add Changes entry for -dstrokeadjust and "Usage" entry.

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

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 76d6823b9ec7b77feb64e99c143febd088f5bc13..7e7692c86dff6d536474f45c3a507457c1263af9 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -134,13 +134,13 @@ The following options are supported:
 
 @table @code
 
-@item -d,--define-default=@var{var}=@var{val}
+@item -d, --define-default=@var{var}=@var{val}
 See @ref{Advanced command line options for LilyPond}.
 
 @cindex Scheme, expression evaluation
 @cindex expression evaluation, Scheme
 
-@item -e,--evaluate=@var{expr}
+@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.
@@ -167,19 +167,19 @@ at the top of the @code{.ly} file.
 @cindex output, format
 @cindex format, output
 
-@item -f,--format=@var{format}
+@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 -h,--help
+@item -h, --help
 Show a summary of usage.
 
-@item -H,--header=@var{FIELD}
+@item -H, --header=@var{FIELD}
 Dump a header field to file @file{BASENAME.@var{FIELD}}.
 
-@item -i,--init=@var{file}
+@item -i, --init=@var{file}
 Set init file to @var{file} (default: @file{init.ly}).
 
 @cindex file searching
@@ -194,7 +194,7 @@ search will continue in subsequent directories.
 
 @cindex chroot jail, running inside
 
-@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+@item -j, --jail=@var{user},@var{group},@var{jail},@var{dir}
 Run @command{lilypond} in a chroot jail.
 
 The @option{--jail} option provides a more flexible alternative to
@@ -257,7 +257,7 @@ the amount of memory that can be allocated.  Also see
 @cindex loglevel
 @cindex output, verbosity
 
-@item -l,--loglevel=@var{LEVEL}
+@item -l, --loglevel=@var{LEVEL}
 Set the verbosity of the console output to @var{LEVEL}. Possible values
 are:
 
@@ -290,7 +290,7 @@ All possible messages, including verbose debug output.
 @cindex output, setting filename
 @cindex output, directory
 
-@item -o,--output=@var{FILE} or @var{FOLDER}
+@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
@@ -319,14 +319,14 @@ Generate pictures of each page, in PNG format.  This implies
 @item --pdf
 Generate PDF.  This implies @option{--ps}.
 
-@item -v,--version
+@item -v, --version
 Show version information.
 
-@item -V,--verbose
+@item -V, --verbose
 Be verbose: show full paths of all files read, and give timing
 information.
 
-@item -w,--warranty
+@item -w, --warranty
 Show the warranty with which GNU LilyPond comes.  (It comes with
 @strong{NO WARRANTY}!)
 
@@ -648,7 +648,7 @@ more work to set up. See @ref{Basic command line options for LilyPond}.
 @item @code{separate-log-files}
 @tab @code{#f}
 @tab For input files @code{FILE1.ly}, @code{FILE2.ly}, etc. output log
-data to files @code{FILE1.log}, @code{FILE2.log}, ...
+data to files @code{FILE1.log}, @code{FILE2.log}@dots{}
 
 @item @code{show-available-fonts}
 @tab @code{#f}
@@ -664,6 +664,17 @@ point exceptions.
 @tab Don't use directories from input files while constructing output
 file names.
 
+@item @code{strokeadjust}
+@tab @code{#f}
+@tab Force PostScript stroke adjustment.  This option is mostly
+relevant when @code{PDF} is generated from PostScript output
+(stroke adjustment is usually enabled automatically for
+low-resolution bitmap devices).  Without this option,
+@code{PDF}@tie{}previewers tend to produce widely inconsistent
+stem widths at resolutions typical for screen display.  The option
+does not noticeably affect print quality and causes large file
+size increases in @code{PDF} files.
+
 @item @code{svg-woff}
 @tab @code{#f}
 @tab Use woff font files in SVG backend.
@@ -923,6 +934,7 @@ are easily handled.
 * Error message Unbound variable %::
 * Error message FT_Get_Glyph_Name::
 * Warning staff affinities should only decrease::
+* Error message unexpected new::
 @end menu
 
 @node Music runs off the page
@@ -1043,3 +1055,53 @@ staff by inserting
 @noindent
 at its start.  For details, see @qq{Spacing of non-staff lines} in
 @ruser{Flexible vertical spacing within systems}.
+
+
+@node Error message unexpected new
+@unnumberedsubsec Error message unexpected @code{@bs{}new}
+
+A @code{\score} block must contain a @emph{single} music expression.
+If instead it contains several @code{\new Staff},
+@code{\new StaffGroup} or similar contexts introduced with @code{\new}
+without them being enclosed in either curly brackets,
+@code{@{ @dots{} @}}, or double angle brackets, @code{<< @dots{} >>},
+like this:
+
+@example
+\score @{
+  % Invalid! Generates error: syntax error, unexpected \new
+  \new Staff @{ @dots{} @}
+  \new Staff @{ @dots{} @}
+@}
+@end example
+
+@noindent
+the error message will be produced.
+
+To avoid the error, enclose all the @code{\new} statements in
+curly or double angle brackets.
+
+Using curly brackets will introduce the @code{\new} statements
+sequentially:
+
+@lilypond[quote,verbatim]
+\score {
+  {
+    \new Staff { a' a' a' a' }
+    \new Staff { g' g' g' g' }
+  }
+}
+@end lilypond
+
+@noindent
+but more likely you should be using double angle brackets so the new
+staves are introduced in parallel, i.e. simultaneously:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff { a' a' a' a' }
+    \new Staff { g' g' g' g' }
+  >>
+}
+@end lilypond