Merge master into nested-bookparts

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

diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely
index 0644f342205cbc878f03f7f367bf07feb97be852..0bbd4d14bb75befa94fc4b698639a762658b2e33 100644 (file)
--- a/Documentation/user/running.itely
+++ b/Documentation/user/running.itely
@@ -1,5 +1,5 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c -*- coding: utf-8; mode: texinfo; -*-

-@c This file is part of lilypond.tely
+@c This file is part of lilypond-program.tely

 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 


@@ -7,44 +7,64 @@
     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.61"
+

 
 @node Running LilyPond
 @chapter Running LilyPond
 
 This chapter details the technicalities of running LilyPond.
 
 
 @node Running LilyPond
 @chapter Running LilyPond
 
 This chapter details the technicalities of running LilyPond.
 

-Some of these commands are run from 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}; OSX users might be more familiar with the
-terms @q{terminal} or @q{console}.  OSX users should also
-consult @ref{Notes for the MacOS X app}.
+@menu
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Updating files with convert-ly::
+* Reporting bugs::
+@end menu
+
+
+@node Normal usage
+@section Normal usage
+
+Most users run LilyPond through a GUI; see @rlearning{First steps} if
+you have not read this already.
+

 
 

-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.
+@node Command-line usage
+@section Command-line usage
+
+This section contains extra information about using LilyPond on the
+command-line.  This may be desirable to pass extra options to the
+program.  In addition, there are certain extra @q{helper} programs (such
+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
+@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.

 
 @menu
 
 @menu

-* Invoking lilypond::           
-* Notes for the MacOS X app::   
-* Updating files with convert-ly::  
-* Reporting bugs::              
-* Error messages::              
-* Editor support::              
-* Point and click::             
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::

 @end menu
 
 @node Invoking lilypond
 @end menu
 
 @node Invoking lilypond

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

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

-The @code{lilypond} executable may be called as follows from the command line.
+The @command{lilypond} executable may be called as follows from the command line.

 
 @example
 lilypond [@var{option}]@dots{} @var{file}@dots{}
 
 @example
 lilypond [@var{option}]@dots{} @var{file}@dots{}


@@ -55,17 +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.}
 

+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")
+\book @{ @dots{} @}
+#(define output-suffix "cello")
+\book @{ @dots{} @}
+@end example
+
+@noindent
+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:
 


@@ -97,13 +132,13 @@ at the top of the @code{.ly} file.
 which formats should be written.  Choices for @code{format} are
 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
 
 which formats should be written.  Choices for @code{format} are
 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
 

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

 
 
 
 @item -d,--define-default=@var{var}=@var{val}
 This sets the internal program option @var{var} to the Scheme value
 
 
 
 @item -d,--define-default=@var{var}=@var{val}
 This sets the internal program option @var{var} to the Scheme value

-@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
+@var{val}.  If @var{val} is not supplied, then @var{#t} is used.  To

 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
 
 @cindex point and click, command line
 switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
 
 @cindex point and click, command line


@@ -126,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.


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


@@ -197,7 +232,7 @@ 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
  for SVG (Scalable Vector Graphics).  This dumps every page as a separate
 
 @item svg
  for SVG (Scalable Vector Graphics).  This dumps every page as a separate


@@ -205,15 +240,15 @@ This mode is used by default by lilypond-book.
 @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.
 @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/}.
+  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
  for a dump of the raw, internal Scheme-based drawing commands.
 @cindex Scheme dump
 @end table
 
 @item scm
  for a dump of the raw, internal Scheme-based drawing commands.
 @cindex Scheme dump
 @end table
 

-Example: @code{lilypond -dbackend=svg filename.ly}
+Example: @code{lilypond -dbackend=svg @var{filename}.ly}

 
 @cindex output format, setting
 
 
 @cindex output format, setting
 


@@ -231,8 +266,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.


@@ -244,7 +279,7 @@ 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}
+suffix will be added (i.e. @code{.pdf} for pdf, @code{.tex}

 for tex, etc).
 
 @item --ps
 for tex, etc).
 
 @item --ps


@@ -267,24 +302,24 @@ Generate PDF.  This implies @code{--ps}.
 
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
 
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}

-Run LilyPond in a chroot jail.
+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
 server or whenever LilyPond executes externally provided
 sources.
 
 
 The @code{--jail} option provides a more flexible alternative to
 @code{--safe} when LilyPond formatting is available through a web
 server or whenever LilyPond executes externally provided
 sources.
 

-The @code{--jail} option works by changing the root of LilyPond to
+The @code{--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 LilyPond must be run as root, which is usually
+@code{--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
 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

-@emph{inside the jail}. A typical setup comprises the following items:
+@emph{inside the jail}.  A typical setup comprises the following items:

 
 @table @asis
 @item Setting up a separate filesystem
 
 @table @asis
 @item Setting up a separate filesystem


@@ -297,7 +332,7 @@ mount a loop device.  A separate filesystem also guarantees that LilyPond
 cannot write more space than it is allowed.
 
 @item Setting up a separate user
 cannot write more space than it is allowed.
 
 @item Setting up a separate user

-A separate user and group (say, @samp{lily}/@samp{lily}) with low
+A separate user and group (say, @code{lily}/@code{lily}) with low

 privileges should be used to run LilyPond inside the jail.  There should
 be a single directory writable by this user, which should be passed in
 @var{dir}.
 privileges should be used to run LilyPond inside the jail.  There should
 be a single directory writable by this user, which should be passed in
 @var{dir}.


@@ -337,14 +372,14 @@ 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
 
 
 @cindex LANG
 @cindex LILYPOND_DATADIR
 
 @subsection Environment variables
 
 
 @cindex LANG
 @cindex LILYPOND_DATADIR
 

-@code{Lilypond} recognizes the following environment variables:
+@command{lilypond} recognizes the following environment variables:

 @table @code
 @item LILYPOND_DATADIR
 This specifies a directory where locale messages and
 @table @code
 @item LILYPOND_DATADIR
 This specifies a directory where locale messages and


@@ -356,72 +391,92 @@ This selects the language for the warning messages.
 
 @item LILYPOND_GC_YIELD
 With this variable the memory footprint and performance can be
 
 @item LILYPOND_GC_YIELD
 With this variable the memory footprint and performance can be

-adjusted. It is a percentage tunes memory management behavior. With
+adjusted.  It is a percentage tunes memory management behavior.  With

 higher values, the program uses more memory, with smaller values, it
 higher values, the program uses more memory, with smaller values, it

-uses more CPU time. The default value is @code{70}.
+uses more CPU time.  The default value is @code{70}.

 
 @end table
 
 
 
 @end table
 
 

-@node Notes for the MacOS X app
-@section Notes for the MacOS X app
+@node Error messages
+@section Error messages

 
 

-The scripts (such as lilypond-book, convert-ly, abc2ly, and even
-lilypond itself) are also
-included inside MacOS X .app. They can be run from the command line by
-invoking them directly, e.g.
+@cindex error messages
+Different error messages can appear while compiling a file:

 
 

-@example
-@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
-@end example
+@table @emph

 
 

-@noindent
-The same is true of the other scripts in that directory, including
-lilypond-book, convert-ly, abc2ly, etc.
+@item Warning
+@cindex warning
+Something looks suspect.  If you are requesting something out of the
+ordinary then you will understand the message, and can ignore it.
+However, warnings usually indicate that something is wrong with the
+input file.

 
 

-Alternatively, you may create scripts which add the path
-automatically.  Create a directory to store these scripts,
+@item Error
+Something is definitely wrong.  The current processing step (parsing,
+interpreting, or formatting) will be finished, but the next step will
+be skipped.

 
 

-@example
-mkdir -p ~/bin
-cd ~/bin
-@end example
+@item Fatal error
+@cindex error
+@cindex fatal error
+Something is definitely wrong, and LilyPond cannot continue.  This
+happens rarely.  The most usual cause is misinstalled fonts.

 
 

-Create a file called @code{lilypond} which contains
+@item Scheme error
+@cindex trace, 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
+function call is printed.

 
 

-@example
-exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
-@end example
+@item Programming error
+@cindex Programming error
+There was some internal inconsistency.  These error messages are
+intended to help the programmers and debuggers.  Usually, they can be
+ignored.  Sometimes, they come in such big quantities that they obscure
+other output.

 
 

-Create similar files @code{lilypond-book}, @code{convert-ly}, and
-any other helper programs you use (@code{abc2ly}, @code{midi2ly},
-etc).  Simply replace the @code{bin/lilypond} with
-@code{bin/convert-ly} (or other program name) in the above file.
+@item Aborted (core dumped)
+This signals a serious programming error that caused the program to
+crash.  Such errors are considered critical.  If you stumble on one,
+send a bug-report.
+@end table

 
 

-Make the file executable,
+@cindex errors, message format
+If warnings and errors can
+be linked to some part of the input file, then error messages have the
+following form

 
 @example
 
 @example

-chmod u+x lilypond
+@var{filename}:@var{lineno}:@var{columnno}: @var{message}
+@var{offending input line}

 @end example
 
 @end example
 

-Now, add this directory to your path.  Modify (or create)
-a file called @code{.profile} in your home directory such that it contains
+A line-break is inserted in the offending line to indicate the column
+where the error was found.  For example,

 
 @example
 
 @example

-export PATH=$PATH:~/bin
+test.ly:2:19: error: not a duration: 5
+  @{ c'4 e'
+           5 g' @}

 @end example
 
 @end example
 

-@noindent
-This file should end with a blank line.
-
-Note that @var{path/to} will generally be @code{/Applications/}.
+These locations are LilyPond's best guess about where the warning or
+error occurred, but (by their very nature) warnings and errors occur
+when something unexpected happens.  If you can't see an error in the
+indicated line of your input file, try checking one or two lines
+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 Updating a LilyPond file

-@funindex convert-ly
+@cindex convert-ly

 
 The LilyPond input syntax is routinely changed to simplify it or improve
 it in different ways.  As a side effect of this, the LilyPond interpreter
 
 The LilyPond input syntax is routinely changed to simplify it or improve
 it in different ways.  As a side effect of this, the LilyPond interpreter


@@ -431,16 +486,27 @@ 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
 
 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@footnote{MacOS X users may execute this command
-under the menu entry @samp{Compile > Update syntax}.}
+sufficient to run

 
 @example
 convert-ly -e myfile.ly
 @end example
 
 
 @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.
 
 If there are no changes to myfile.ly and file called myfile.ly.NEW
 is created, then myfile.ly is already updated.
 

+@menu
+* Command line options for convert-ly::
+* Problems with convert-ly::
+@end menu
+
+@node Command line options for convert-ly
+@subsection Command line options for @command{convert-ly}
+

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


@@ -458,7 +524,7 @@ convert-ly --from=... --to=... -s
 @end example
 
 To upgrade many files at once, combine @code{convert-ly} with
 @end example
 
 To upgrade many files at once, combine @code{convert-ly} with

-standard unix commands.  This example will upgrade all @code{.ly}
+standard UNIX commands.  This example will upgrade all @code{.ly}

 files in the current directory
 
 @example
 files in the current directory
 
 @example


@@ -498,48 +564,30 @@ Print usage help.
 @end table
 
 
 @end table
 
 

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

 
 Not all language changes are handled.  Only one output option can be
 
 Not all language changes are handled.  Only one output option can be

-specified.  Automatically updating scheme and lilypond scheme
+specified.  Automatically updating scheme and LilyPond scheme

 interfaces is quite unlikely; be prepared to tweak scheme code
 manually.
 
 interfaces is quite unlikely; be prepared to tweak scheme code
 manually.
 

-
-@c  We might want to make this a completely new section, along with more
-@c  info about how to upgrade old input files.  -gp
-
-@ignore
-Copy and paste from CVS, last updated
-Aug 18, 2005
-
-http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
-convert-ly.txt?rev=HEAD&content-type=text/plain
-
-NEW: not exactly copied; this list has been modified.  Since we're
-changing the bug system, it doesn't make sense to copy from
-the bug CVS any more.  I'll figure out something else.  -gp
-@end ignore

 @verbatim
 @verbatim

+There are a few things that the convert-ly cannot handle.  Here's a list
+of limitations that the community has complained about.

 
 

-There are a few things that the convert-ly cannot handle. Here's a list of
-limitations
-that the community has complained about.
-
-This bug report structure has been chosen because convert-ly has a structure
-that doesn't
-allow to smoothly implement all needed changes. Thus this is just a wishlist,
-placed
-here for reference.
+This bug report structure has been chosen because convert-ly has a
+structure that doesn't allow to smoothly implement all needed changes.
+Thus this is just a wishlist, placed here for reference.

 
 1.6->2.0:
  Doesn't always convert figured bass correctly, specifically things like {<
 
 1.6->2.0:
  Doesn't always convert figured bass correctly, specifically things like {<

->}. Mats' comment on working around this:
+>}.  Mats' comment on working around this:

    To be able to run convert-ly
    To be able to run convert-ly

-   on it, I first replaced all occurencies of '{<' to some dummy like '{#'
-   and similarly I replaced '>}' with '&}'. After the conversion, I could
+   on it, I first replaced all occurrences of '{<' to some dummy like '{#'
+   and similarly I replaced '>}' with '&}'.  After the conversion, I could

    then change back from '{ #' to '{ <' and from '& }' to '> }'.
    then change back from '{ #' to '{ <' and from '& }' to '> }'.

- Doesn't convert all text markup correctly. In the old markup syntax,
+ Doesn't convert all text markup correctly.  In the old markup syntax,

  it was possible to group a number of markup commands together within
 parentheses, e.g.
    -#'((bold italic) "string")
  it was possible to group a number of markup commands together within
 parentheses, e.g.
    -#'((bold italic) "string")


@@ -586,7 +634,7 @@ converted.
 @cindex reporting bugs
 
 If you have input that results in a crash or an erroneous output, then
 @cindex reporting bugs
 
 If you have input that results in a crash or an erroneous output, then

-that is a bug. There is a list of current bugs on our google bug tracker,
+that is a bug.  There is a list of current bugs on our Google bug tracker,

 
 @uref{http://code.google.com/p/lilypond/issues/list}
 
 
 @uref{http://code.google.com/p/lilypond/issues/list}
 


@@ -595,217 +643,8 @@ 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 @ref{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.
 
 

-@node Error messages
-@section Error messages
-
-@cindex error messages
-Different error messages can appear while compiling a file:
-
-@table @emph
-@cindex warning
-
-@item Warning
-Something looks suspect.  If you are requesting something out of the
-ordinary then you will understand the message, and can ignore it.
-However, warnings usually indicate that something is wrong with the
-input file.
-
-@item Error
-Something is definitely wrong.  The current processing step (parsing,
-interpreting, or formatting) will be finished, but the next step will
-be skipped.
-
-@cindex error
-@cindex fatal error
-@item Fatal error
-Something is definitely wrong, and LilyPond cannot continue.  This
-happens rarely.  The most usual cause is misinstalled fonts.
-
-@cindex trace, Scheme
-@cindex call trace
-@cindex Scheme error
-@item 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
-function call is printed.
-
-@cindex Programming error
-@item Programming error
-There was some internal inconsistency.  These error messages are
-intended to help the programmers and debuggers.  Usually, they can be
-ignored.  Sometimes, they come in such big quantities that they obscure
-other output.  In this case, file a bug-report.
-
-@item Aborted (core dumped)
-This signals a serious programming error that caused the program to
-crash.  Such errors are considered critical.  If you stumble on one,
-send a bug-report.
-
-
-@end table
-
-@cindex errors, message format
-If warnings and errors can
-be linked to some part of the input file, then error messages have the
-following form
-
-@example
-@var{filename}:@var{lineno}:@var{columnno}: @var{message}
-@var{offending input line}
-@end example
-
-A line-break is inserted in the offending line to indicate the column
-where the error was found.  For example,
-
-@example
-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
-error occurred, but (by their very nature) warnings and errors occur
-when something unexpected happens.  If you can't see an error in the
-indicated line of your input file, try checking one or two lines
-above the indicated position.
-
-
-@node Editor support
-@section Editor support
-
-@cindex editors
-@cindex vim
-@cindex emacs
-@cindex modes, editor
-@cindex syntax coloring
-@cindex coloring, syntax
-
-There is support from different editors for LilyPond.
-
-@table @asis
-@item Emacs
-Emacs has a @file{lilypond-mode}, which provides keyword
-autocompletion, indentation, LilyPond specific parenthesis matching
-and syntax coloring, handy compile short-cuts and reading LilyPond
-manuals using Info.  If @file{lilypond-mode} is not installed on your
-platform, then read the
-@ifhtml
-@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
-@end ifhtml
-@ifnothtml
-installation instructions.
-@end ifnothtml
-
-@item VIM
-
-For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
-with syntax coloring tools.  For more information, refer to the
-@ifhtml
-@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
-@end ifhtml
-@ifnothtml
-installation instructions.
-@end ifnothtml
-
-
-@item LilyPondTool
-
-Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text
-editor, LilyPondTool is the most feature-rich text-based tool for editing
-LilyPond scores.  Its features include a Document Wizard with lyrics
-support to set up documents easier, and embedded PDF viewer with advanced
-point-and-click support.  For screenshots, demos and installation
-instructions, visit @uref{http://lilypondtool@/.organum@/.hu}
-
-@end table
-
-All these editors can be made to jump into the input file to the source
-of a symbol in the graphical output.  See @ref{Point and click}.
-
-
-@node Point and click
-@section Point and click
-@cindex point and click
-
-
-Point and click lets you find notes in the input by clicking on them
-in the PDF viewer.  This makes it easier to find input that causes
-some error in the sheet music.
-
-When this functionality is active, LilyPond adds hyperlinks to the PDF
-file. These hyperlinks are sent to the web-browser, which opens a
-text-editor with the cursor in the right place.
-
-To make this chain work, you should configure your PDF viewer to
-follow hyperlinks using the @file{lilypond-invoke-editor} script
-supplied with LilyPond.
-
-For Xpdf on Unix, the following should be present in
-@file{xpdfrc}@footnote{On unix, this file is found either in
-@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
-
-@example
-urlCommand     "lilypond-invoke-editor %s"
-@end example
-
-The program @file{lilypond-invoke-editor} is a small helper
-program. It will invoke an editor for the special @code{textedit}
-URIs, and run a web browser for others.  It tests the environment
-variable @code{EDITOR} for the following patterns,
-
-@table @code
-@item emacs
-  this will invoke
-@example
-emacsclient --no-wait +@var{line}:@var{column} @var{file}
-@end example
-@item vim
-  this will invoke
-@example
-gvim --remote +:@var{line}:norm@var{char} @var{file}
-@end example
-
-@item nedit
-this will invoke
-@example
-  nc -noask +@var{line} @var{file}'
-@end example
-@end table
-
-The environment variable @code{LYEDITOR} is used to override this. It
-contains the command line to start the editor, where @code{%(file)s},
-@code{%(column)s}, @code{%(line)s} is replaced with the file, column
-and line respectively. The  setting
-
-@example
-emacsclient --no-wait +%(line)s:%(column)s %(file)s
-@end example
-
-@noindent
-for @code{LYEDITOR} is equivalent to the standard emacsclient
-invocation.
-
-
-@cindex file size, output
-
-The point and click links enlarge the output files significantly. For
-reducing the size of PDF and PS files, point and click may be switched
-off by issuing
-
-@example
-#(ly:set-option 'point-and-click #f)
-@end example
-
-@noindent
-in a @file{.ly} file.  Alternately, you may pass this as an command-line
-option
-
-@example
-lilypond -dno-point-and-click file.ly
-@end example