lilypond-book robustness: ensure EOL at the end of @verbatim

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

diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely
index 91510f12d0f86d81dfcf0447531fb9c7b1bc9319..cdcd136f258a63dc055e09c23e1b865a0e5a25e1 100644 (file)
--- a/Documentation/user/running.itely
+++ b/Documentation/user/running.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

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

 
 
 @node Running LilyPond
 
 
 @node Running LilyPond


@@ -16,18 +16,18 @@
 This chapter details the technicalities of running LilyPond.
 
 @menu
 This chapter details the technicalities of running LilyPond.
 
 @menu

-* Normal usage::                
-* Command-line usage::          
-* Error messages::              
-* Updating files with convert-ly::  
-* Reporting bugs::              
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Updating files with convert-ly::
+* Reporting bugs::

 @end menu
 
 
 @node Normal usage
 @section Normal usage
 
 @end menu
 
 
 @node Normal usage
 @section Normal usage
 

-Most users run LilyPond through a GUI; see @ruser{First steps} if
+Most users run LilyPond through a GUI; see @rlearning{First steps} if

 you have not read this already.
 
 
 you have not read this already.
 
 


@@ -42,18 +42,24 @@ as @code{midi2ly}) which are only available on the command-line.
 By @q{command-line}, we mean the command line in the operating system.
 Windows users might be more familiar with the terms @q{DOS shell} or
 @q{command shell}; MacOS@tie{}X users might be more familiar with the terms
 By @q{command-line}, we mean the command line in the operating system.
 Windows users might be more familiar with the terms @q{DOS shell} or
 @q{command shell}; MacOS@tie{}X users might be more familiar with the terms

-@q{terminal} or @q{console}.  They should also consult @ref{MacOS X
-on the command-line}.
+@q{terminal} or @q{console}.  They should also consult @ref{Setup
+for MacOS X}.

 
 Describing how to use this part of an operating system is outside the
 scope of this manual; please consult other documentation on this topic
 if you are unfamiliar with the command-line.
 
 
 Describing how to use this part of an operating system is outside the
 scope of this manual; please consult other documentation on this topic
 if you are unfamiliar with the command-line.
 

+@menu
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::
+@end menu

 
 

-@subsection Invoking lilypond
+@node Invoking lilypond
+@subsection Invoking @command{lilypond}

 
 

-@cindex Invoking LilyPond
-@cindex command line options
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}

 @cindex options, command line
 @cindex switches
 
 @cindex options, command line
 @cindex switches
 


@@ -69,32 +75,32 @@ When invoked with a filename that has no extension, the @file{.ly}
 extension is tried first.  To read input from stdin, use a
 dash (@code{-}) for @var{file}.
 
 extension is tried first.  To read input from stdin, use a
 dash (@code{-}) for @var{file}.
 

-When @file{filename.ly} is processed it will produce
-@file{filename.tex} as output (or @file{filename.ps} for PostScript
-output).  If @file{filename.ly} contains more than one @code{\score}
-block, then the rest of the scores will be output in numbered files,
-starting with @file{filename-1.tex}.  Several files can be specified;
+When @file{filename.ly} is processed it will produce @file{filename.ps}
+and @file{filename.pdf} as output.  Several files can be specified;

 they will each be processed independently.  @footnote{The status of
 GUILE is not reset after processing a @code{.ly} file, so be careful
 not to change any system defaults from within Scheme.}
 
 they will each be processed independently.  @footnote{The status of
 GUILE is not reset after processing a @code{.ly} file, so be careful
 not to change any system defaults from within Scheme.}
 

-In addition, the value of @code{output-suffix} will be inserted between
-the basename and the number.  An input file containing 
+If @file{filename.ly} contains more than one @code{\score}
+block, then the rest of the scores will be output in numbered files,
+starting with @file{filename-1.pdf}.  In addition, the value of
+@code{output-suffix} will be inserted between the basename and the
+number.  An input file containing

 
 @example
 #(define output-suffix "violin")
 
 @example
 #(define output-suffix "violin")

-\book @{ @dots{} @} 
+\score @{ @dots{} @}

 #(define output-suffix "cello")
 #(define output-suffix "cello")

-\book @{ @dots{} @} 
+\score @{ @dots{} @}

 @end example
 
 @noindent
 @end example
 
 @noindent

-will output @var{base}@file{-violin.ps} and
-@var{base}@file{-cello-1.ps}.
+will output @var{base}@file{-violin.pdf} and
+@var{base}@file{-cello-1.pdf}.

 
 
 
 

-
-@subsection Command line options
+@node Command line options for lilypond
+@subsection Command line options for @command{lilypond}

 
 The following options are supported:
 
 
 The following options are supported:
 


@@ -124,9 +130,9 @@ at the top of the @code{.ly} file.
 
 @item -f,--format=@var{format}
 which formats should be written.  Choices for @code{format} are
 
 @item -f,--format=@var{format}
 which formats should be written.  Choices for @code{format} are

-@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+@code{svg}, @code{ps}, @code{pdf}, and @code{png}.

 
 

-Example: @code{lilypond -fpng filename.ly}
+Example: @code{lilypond -fpng @var{filename}.ly}

 
 
 
 
 
 


@@ -155,14 +161,14 @@ Running @code{lilypond -dhelp} will print all of the @code{-d} options
 available.
 
 @item paper-size
 available.
 
 @item paper-size

-This option sets the default paper-size, 
+This option sets the default paper-size,

 @example
 -dpaper-size=\"letter\"
 @end example
 
 @noindent
 Note that the string must be enclosed in escaped quotes ( @code{\"} ).
 @example
 -dpaper-size=\"letter\"
 @end example
 
 @noindent
 Note that the string must be enclosed in escaped quotes ( @code{\"} ).

-
+@c Match " in previous line to help context-sensitive editors

 
 @item safe
 Do not trust the @code{.ly} input.
 
 @item safe
 Do not trust the @code{.ly} input.


@@ -192,7 +198,7 @@ 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.
 

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


@@ -202,20 +208,13 @@ The safe mode will prevent many useful LilyPond snippets from being
 compiled.  The @code{--jail} is a more secure alternative, but
 requires more work to set up.
 
 compiled.  The @code{--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
 @table @code
 @item backend
 the output format to use for the back-end.  Choices for @code{format} are
 @table @code

-@item tex
-for @TeX{} output, to be processed with La@TeX{}.  If present, the file
-@file{file.textmetrics} is read to determine text extents.
-@item texstr
-dump text strings to @file{.texstr} file, which can be run through
-(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
-extents of strings of text.  @strong{Warning:} this functionality is
-currently missing due to heavy restructuring of the source code.

 @item ps
 @item ps

- for PostScript.

 @cindex PostScript output
 @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
 
   Postscript files include TTF, Type1 and OTF fonts.  No subsetting of
   these fonts is done.  When using oriental character sets, this can


@@ -226,25 +225,30 @@ currently missing due to heavy restructuring of the source code.
 @file{EPS} file, without fonts, and as one collated @file{EPS} file with
 all pages (systems) including fonts.
 
 @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 lilypond-book.
+This mode is used by default by @command{lilypond-book}.

 
 @item svg
 
 @item svg

- for SVG (Scalable Vector Graphics).  This dumps every page as a separate
-@file{SVG} file, with embedded fonts.

 @cindex SVG (Scalable Vector Graphics)
 @cindex SVG (Scalable Vector Graphics)

-  You need a SVG viewer which supports embedded fonts, or a SVG
-  viewer which is able to replace the embedded fonts with OTF fonts.
-  Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape}
-  (version 0.42 or later), after copying the OTF fonts in directory
-  @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
+ for SVG (Scalable Vector Graphics).
+
+ This creates a single SVG file containing the entire music
+ output, with embedded fonts.  You need an SVG viewer that
+ supports embedded fonts, or an SVG viewer that can replace the
+ embedded fonts with OTF fonts.  Under UNIX, you may use
+ @uref{http://www.inkscape.org,Inkscape} (version 0.42 or later),
+ after copying the OTF fonts from the LilyPond directory
+ (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
+ @file{~/.fonts/}.
+

 @item scm
 @item scm

- for a dump of the raw, internal Scheme-based drawing commands.

 @cindex Scheme dump
 @cindex Scheme dump

-@end table
+ for a dump of the raw, internal Scheme-based drawing commands.

 
 

-Example: @code{lilypond -dbackend=svg filename.ly}
+@item null
+ do not output a printed score; has the same effect as @code{-dno-print-pages}.
+@end table

 
 

-@cindex output format, setting
+Example: @code{lilypond -dbackend=svg @var{filename}.ly}

 
 @item preview
 Generate an output file containing the titles and the first system
 
 @item preview
 Generate an output file containing the titles and the first system


@@ -260,8 +264,8 @@ useful in combination with @code{-dpreview}.
 @item -h,--help
 Show a summary of usage.
 
 @item -h,--help
 Show a summary of usage.
 

-@item -H,--header=FIELD
-Dump a header field to file BASENAME.FIELD
+@item -H,--header=@var{FIELD}
+Dump a header field to file @file{BASENAME.@var{FIELD}}.

 
 @item --include, -I=@var{directory}
 Add @var{directory} to the search path for input files.
 
 @item --include, -I=@var{directory}
 Add @var{directory} to the search path for input files.


@@ -273,16 +277,11 @@ Set init file to @var{file} (default: @file{init.ly}).
 
 @item -o,--output=@var{FILE}
 Set the default output file to @var{FILE}.  The appropriate
 
 @item -o,--output=@var{FILE}
 Set the default output file to @var{FILE}.  The appropriate

-suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
-for tex, etc).
+suffix will be added (e.g. @code{.pdf} for pdf)

 
 @item --ps
 Generate PostScript.
 
 
 @item --ps
 Generate PostScript.
 

-@item --dvi
-Generate DVI files.  In this case, the @TeX{} backend should be
-specified, i.e., @code{-dbackend=tex}.
-

 @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
 @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


@@ -366,7 +365,7 @@ Show the warranty with which GNU LilyPond comes. (It comes with
 @strong{NO WARRANTY}!)
 @end table
 
 @strong{NO WARRANTY}!)
 @end table
 

-
+@node Environment variables

 @subsection Environment variables
 
 
 @subsection Environment variables
 
 


@@ -454,9 +453,9 @@ A line-break is inserted in the offending line to indicate the column
 where the error was found.  For example,
 
 @example
 where the error was found.  For example,
 
 @example

-test.ly:2:19: error: not a duration: 5:
-  @{ c'4 e'5
-             g' @}
+test.ly:2:19: error: not a duration: 5
+  @{ c'4 e'
+           5 g' @}

 @end example
 
 These locations are LilyPond's best guess about where the warning or
 @end example
 
 These locations are LilyPond's best guess about where the warning or


@@ -467,7 +466,7 @@ above the indicated position.
 
 
 @node Updating files with convert-ly
 
 
 @node Updating files with convert-ly

-@section Updating with @command{convert-ly}
+@section Updating files with @command{convert-ly}

 
 @cindex Updating a LilyPond file
 @cindex convert-ly
 
 @cindex Updating a LilyPond file
 @cindex convert-ly


@@ -478,51 +477,66 @@ often is no longer compatible with older input files.  To remedy this,
 the program @command{convert-ly} can be used to deal with most of the
 syntax changes between LilyPond versions.
 
 the program @command{convert-ly} can be used to deal with most of the
 syntax changes between LilyPond versions.
 

-It uses @code{\version} statements in the input files to detect the
-old version number.  In most cases, to upgrade your input file it is
-sufficient to run
+@menu
+* Invoking convert-ly::
+* Command line options for convert-ly::
+* Problems with convert-ly::
+@end menu
+
+@node Invoking convert-ly
+@subsection Invoking @command{convert-ly}
+
+@command{convert-ly} uses @code{\version} statements in the input
+file to detect the old version number.  In most cases, to upgrade
+your input file it is sufficient to run

 
 @example
 convert-ly -e myfile.ly
 @end example
 
 @noindent
 
 @example
 convert-ly -e myfile.ly
 @end example
 
 @noindent

-MacOS@tie{}X users may execute this command under the menu entry
-@code{Compile > Update syntax}.
-
-If there are no changes to myfile.ly and file called myfile.ly.NEW
-is created, then myfile.ly is already updated.
+in the directory containing the file.  This will upgrade
+@code{myfile.ly} in-place and preserve the original file in
+@code{myfile.ly~}.

 
 

-@subsection Command line options
-
-@command{convert-ly} always converts up to the last syntax change handled by
-it.  This means that the @code{\version} number left in the file is
-usually lower than the version of @command{convert-ly} itself.
-
-To upgrade LilyPond fragments in texinfo files, use
+To convert all the input files in a directory together use

 
 @example
 
 @example

-convert-ly --from=... --to=... --no-version *.itely
+convert-ly -e *.ly

 @end example
 
 @end example
 

-To see the changes in the LilyPond syntax between two versions, use
+Alternatively, if you want to specify a different name for the
+upgraded file, preserving the original file and name unchanged,
+use

 
 @example
 
 @example

-convert-ly --from=... --to=... -s
+convert-ly myfile.ly > mynewfile.ly

 @end example
 
 @end example
 

-To upgrade many files at once, combine @code{convert-ly} with
-standard UNIX commands.  This example will upgrade all @code{.ly}
-files in the current directory
+@command{convert-ly} always converts up to the last syntax change
+handled by it.  This means that the @code{\version} number left in
+the file is usually lower than the version of @command{convert-ly}
+itself.

 
 

-@example
-for f in *.ly; do convert-ly -e $f; done;
-@end example
+The program will list the version numbers for which conversions
+have been made.  If no version numbers are listed the file is
+already up to date.
+
+@noindent
+MacOS@tie{}X users may execute these commands under the menu entry
+@code{Compile > Update syntax}.
+
+Windows users should enter these commands in a Command Prompt window,
+which is usually found under
+@code{Start > Accessories > Command Prompt}.
+
+@node Command line options for convert-ly
+@subsection Command line options for @command{convert-ly}

 
 In general, the program is invoked as follows:
 
 @example
 
 In general, the program is invoked as follows:
 
 @example

-convert-ly [@var{option}]@dots{} @var{file}@dots{}
+convert-ly [@var{option}]@dots{} @var{filename}@dots{}

 @end example
 
 
 @end example
 
 


@@ -530,11 +544,13 @@ The following options can be given:
 
 @table @code
 @item -e,--edit
 
 @table @code
 @item -e,--edit

-Do an inline edit of the input file.  Overrides @code{--output}.
+Apply the conversions direct to the input file, modifying it
+in-place.

 
 @item -f,--from=@var{from-patchlevel}
 Set the version to convert from.  If this is not set, @command{convert-ly}
 will guess this, on the basis of @code{\version} strings in the file.
 
 @item -f,--from=@var{from-patchlevel}
 Set the version to convert from.  If this is not set, @command{convert-ly}
 will guess this, on the basis of @code{\version} strings in the file.

+E.g. @code{--from=2.10.25}

 
 @item -n,--no-version
 Normally, @command{convert-ly} adds a @code{\version} indicator
 
 @item -n,--no-version
 Normally, @command{convert-ly} adds a @code{\version} indicator


@@ -545,21 +561,52 @@ Show all known conversions and exit.
 
 @item --to=@var{to-patchlevel}
 Set the goal version of the conversion.  It defaults to the latest
 
 @item --to=@var{to-patchlevel}
 Set the goal version of the conversion.  It defaults to the latest

-available version.
+available version.  E.g. @code{--to=2.12.2}

 
 @item -h, --help
 Print usage help.
 @end table
 
 
 @item -h, --help
 Print usage help.
 @end table
 

+To upgrade LilyPond fragments in texinfo files, use

 
 

-@menu
-* Problems with convert-ly::    
-@end menu
+@example
+convert-ly --from=... --to=... --no-version *.itely
+@end example
+
+To see the changes in the LilyPond syntax between two versions, use
+
+@example
+convert-ly --from=... --to=... -s
+@end example

 
 
 @node Problems with convert-ly
 @subsection Problems with @code{convert-ly}
 
 
 
 @node Problems with convert-ly
 @subsection Problems with @code{convert-ly}
 

+When running convert-ly in a Command Prompt window under Windows
+on a file which has spaces in the filename or in the path to it,
+it is necessary to surround the entire input file name with three
+(!) sets of double quotes:
+
+@example
+convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
+@end example
+
+If the simple @command{convert-ly -e *.ly} command fails because the
+expanded command line becomes too long, the @command{convert-ly}
+command may be placed in a loop instead.  This example for UNIX
+will upgrade all @code{.ly} files in the current directory
+
+@example
+for f in *.ly; do convert-ly -e $f; done;
+@end example
+
+In the Windows Command Prompt window the corresponding command is
+
+@example
+for %x in (*.ly) do convert-ly -e """%x"""
+@end example
+

 Not all language changes are handled.  Only one output option can be
 specified.  Automatically updating scheme and LilyPond scheme
 interfaces is quite unlikely; be prepared to tweak scheme code
 Not all language changes are handled.  Only one output option can be
 specified.  Automatically updating scheme and LilyPond scheme
 interfaces is quite unlikely; be prepared to tweak scheme code


@@ -636,7 +683,7 @@ bug by following the directions on
 
 @uref{http://lilypond.org/web/devel/participating/bugs}
 
 
 @uref{http://lilypond.org/web/devel/participating/bugs}
 

-Please construct submit @ruser{Minimal examples}, of bug reports.  We do not
+Please construct and submit minimal examples of bugs in reports.  We do not

 have the resources to investigate reports which are not as small as possible.
 
 
 have the resources to investigate reports which are not as small as possible.