-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+
@node Running LilyPond
@chapter Running LilyPond
@menu
* Invoking lilypond::
-* Error messages::
+* Notes for the MacOS X app::
* Updating files with convert-ly::
* Reporting bugs::
+* Error messages::
* Editor support::
-* File structure::
-* Including LilyPond files::
+* Point and click::
@end menu
@node Invoking lilypond
not to change any system defaults from within Scheme.}
-@section Command line options
+@subsection Command line options
The following options are supported:
@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
-sequentially.
+sequentially.
+
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
+
+@example
+lilypond -e '(define-public a 42)'
+@end example
+
+@noindent
+on the command-line, and include
+
+@example
+#(use-modules (guile-user))
+@end example
+
+@noindent
+at the top of the @code{.ly} file.
@item -f,--format=@var{format}
which formats should be written. Choices are @code{svg}, @code{ps},
Postscript files include TTF, Type1 and OTF fonts. No subsetting of
these fonts is done. When using oriental character sets, this can
- lead to huge files.
-
+ lead to huge files.
+
@item eps
for encapsulated PostScript. This dumps every page (system) as a separate
@file{EPS} file, without fonts, and as one collated @file{EPS} file with
This mode is used by default by lilypond-book.
@item svg
- for SVG (Scalable Vector Graphics)
+ for SVG (Scalable Vector Graphics). This dumps every page as a separate
+@file{SVG} file, with embedded 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/}.
@item scm
for a dump of the raw, internal Scheme-based drawing commands.
@cindex Scheme dump
@end table
-
+
@cindex output format, setting
@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
-switch off an option, @code{no-} may be prefixed to @var{var}, eg.
+switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
+
+@cindex point and click, command line
+
@example
-dno-point-and-click
@end example
-dpoint-and-click='#f'
@end example
-@cindex point and click
+Another notable option is
-Setting the @code{help} option will print a summary of the options
+@example
+-dpaper-size=\"letter\"
+@end example
+
+@noindent
+Note that the string must be enclosed in escaped quotes ( @code{\"} ).
+
+Setting the @code{-dhelp} option will print a summary of the options
available, and exit.
@item -h,--help
Show a summary of usage.
+@item -H,--header=FIELD
+Dump a header field to file BASENAME.FIELD
+
@item --include, -I=@var{directory}
Add @var{directory} to the search path for input files.
@cindex file searching
@item --dvi
Generate DVI files. In this case, the @TeX{} backend should be
-specified, i.e., @code{-f tex}.
+specified, i.e., @code{-b 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
@example
--dresolution=110
+-dresolution=110
@end example
@item --pdf
@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
Run LilyPond in a chroot jail.
-The @code{--jail} option provides a more flexible alternative to
+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.
@item Preparing the jail
LilyPond needs to read a number of files while running. All these files
-are to be copied into the jail, under the same path they apper in the
+are to be copied into the jail, under the same path they appear in the
real root filesystem. The entire content of the LilyPond installation
(e.g., @file{/usr/share/lilypond})
should be copied.
@end table
-@section Environment variables
+@subsection Environment variables
@cindex LANG
@end table
-@node Error messages
-@section Error messages
+@node Notes for the MacOS X app
+@section Notes for the MacOS X app
-@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
+The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
+included inside MacOS X .app. They can be run from the command line by
+invoking them directly, e.g.
@example
-@var{filename}:@var{lineno}:@var{columnno}: @var{message}
-@var{offending input line}
+@var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
@end example
-A line-break is inserted in the offending line to indicate the column
-where the error was found. For example,
+Alternatively, you may add this directory to your path. Modify (or create)
+a file called @code{.profile} in your home directory such that it contains
@example
-test.ly:2:19: error: not a duration: 5:
- @{ c'4 e'5
- g' @}
+export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
@end example
-These locations are LilyPond's best guess about where the warning or
-error occured, 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.
+@noindent
+This file should end with a blank line.
+
+Note that @var{path/to} will generally be @code{/Applications/}.
@node Updating files with convert-ly
@section Updating with @command{convert-ly}
+@cindex Updating a LilyPond file
+@findex 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
often is no longer compatible with older input files. To remedy this,
will guess this, on the basis of @code{\version} strings in the file.
@item -n,--no-version
-Normally, @command{convert-ly} adds a @code{\version} indicator
-to the output. Specifying this option suppresses this.
+Normally, @command{convert-ly} adds a @code{\version} indicator
+to the output. Specifying this option suppresses this.
@item -s, --show-rules
Show all known conversions and exit.
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
+http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
+convert-ly.txt?rev=HEAD&content-type=text/plain
@end ignore
@verbatim
-There are a few things that the convert-ly cannot handle. Here's a list of limitations
+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
+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 {< >}. Mats' comment on working around this:
+ Doesn't always convert figured bass correctly, specifically things like {<
+>}. Mats' comment on working around this:
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
then change back from '{ #' to '{ <' and from '& }' to '> }'.
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.
+ it was possible to group a number of markup commands together within
+parentheses, e.g.
-#'((bold italic) "string")
This will incorrectly be converted into
-\markup{{\bold italic} "string"}
-\markup{\bold \italic "string"}
2.0->2.2:
Doesn't handle \partcombine
- Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
+stanzas.
2.0->2.4:
\magnify isn't changed to \fontsize.
- \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
remove-tag isn't changed.
- - \applymusic #(remove-tag '. . .) => \keepWithTag #'. . .
- firstpagenumber isn't changed.
- - firstpagenumber no => printfirstpagenumber = ##f
+ - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
+ first-page-number isn't changed.
+ - first-page-number no => printfirst-page-number = ##f
Line breaks in header strings aren't converted.
- \\\\ as line break in \header strings => \markup \center-align <
"First Line" "Second Line" >
- \rced => \!
- \rc => \!
2.2->2.4:
- \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
+ \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
+converted.
2.4.2->2.5.9
\markup{ \center-align <{ ... }> } should be converted to:
\markup{ \center-align {\line { ... }} }
If you have input that results in a crash or an erroneous output, then
that is a bug. We try to respond to bug-reports promptly, and fix them as
soon as possible. Help us by sending a defective input file, so we can
-reproduce the problem. Make it small, so we can easily debug the
-problem. Don't forget to tell which version of LilyPond you use! Send
-the report to @email{bug-lilypond@@gnu.org}.
+reproduce the problem. Send the report via:
+
+@example
+@uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
+@end example
+
+A few tips:
+@itemize @bullet
+
+@item Try to produce a very small input file which demonstrates the problem;
+one or two bars is often sufficient to reproduce a bug. The smaller the
+input file is, the easier it is for us to debug the problem.
+
+@item Don't forget to tell which version of LilyPond you use!
+
+@item If possible, use @code{ragged-right} in your example. This makes sure
+that the bug can be reproduced in all paper sizes.
+@end itemize
@ignore
-@c the bug database is not up to date enough.
+@c the bug database is not up to date enough.
When you've found a bug, have a look at our
-@uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
+@uref{http://@/lilypond@/.org/@/bugs/@/v2.8/@/,bug database} to see if
it has already been reported. You could also try to do a few searches
on the mailing list for the bug. Sometimes the bug will have already
been reported and a fix or workaround is already known.
Here is an example of a good bug report:
-@example
+@verbatim
It seems that placement of accidentals is broken. In the
following example, the accidental touches the note head.
-Using Mac OSX 10.3.7, fink package lilypond-devel
+Using Mac OSX 10.3.7, lilypond 2.7.32
-\version "2.5.18"
-\relative c''@{
+\version "2.7.32"
+\layout { ragged-right = ##t }
+\relative c'' {
a4 b cis d
-@}
-@end example
+}
+@end verbatim
@lilypond[quote]
-\version "2.5.18"
+\layout { ragged-right = ##t }
\relative c''{
\override Accidental #'extra-offset = #'(1.0 . 0)
a4 b cis d
}
@end lilypond
+@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
manuals using Info. If @file{lilypond-mode} is not installed on your
platform, then read the
@ifhtml
-@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
+@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
@end ifhtml
@ifnothtml
installation instructions.
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/out-www/INSTALL.html,installation instructions}.
+@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
@end ifhtml
@ifnothtml
installation instructions.
of a symbol in the graphical output. See @ref{Point and click}.
-@node File structure
-@section File structure
+@node Point and click
+@section Point and click
+@cindex point and click
-The major part of this manual is concerned with entering various
-forms of music in LilyPond. However, many music expressions are not
-valid input on their own, for example, a @code{.ly} file containing
-only a note
-@example
-c'4
-@end example
-@noindent
-will result in a parsing error. Instead, music should be inside other
-expressions, which may be put in a file by themselves. Such
-expressions are called toplevel expressions. This section enumerates
-them all.
+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.
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
+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.
-@itemize @bullet
-@item
-An output definition, such as @code{\paper}, @code{\midi}, and
-@code{\layout}. Such a definition at the toplevel changes the default
-settings for the block entered.
-
-@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
-
-@item
-An @code{\addquote} statement. See @ref{Quoting other voices}
-for more information.
-
-@item
-A @code{\score} block. This score will be collected with other
-toplevel scores, and combined as a single @code{\book}.
-
-This behavior can be changed by setting the variable
-@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-The @code{\score} must begin with music, and may contain only
-one music block.
-
-@item
-A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
-
-This behavior can be changed by setting the variable
-@code{toplevel-book-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@item
-A compound music expression, such as
-@example
-@{ c'4 d' e'2 @}
-@end example
+To make this chain work, you should configure your PDF viewer to
+follow hyperlinks using the @file{lilypond-invoke-editor} script
+supplied with LilyPond.
-This will add the piece in a @code{\score} and format it in a
-single book together with all other toplevel @code{\score}s and music
-expressions.
-
-This behavior can be changed by setting the variable
-@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+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.}
-@item
-A markup text, a verse for example
@example
-\markup @{
- 2. The first line verse two.
-@}
+urlCommand "lilypond-invoke-editor %s"
@end example
-Markup texts are rendered above, between or below the scores or music
-expressions, wherever they appear.
+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,
-@item
-An indentifier, such as
+@table @code
+@item emacs
+ this will invoke
@example
-foo = @{ c4 d e d @}
+emacsclient --no-wait +@var{line}:@var{column} @var{file}
@end example
-
-This can be used later on in the file by entering @code{\foo}. The
-name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes.
-
-@end itemize
-
-The following example shows three things that may be entered at
-toplevel
-
+@item vim
+ this will invoke
@example
-\layout @{
- % movements are non-justified by default
- raggedright = ##t
-@}
-
-\header @{
- title = "Do-re-mi"
-@}
-
-@{ c'4 d' e2 @}
+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
-At any point in a file, any of the following lexical instructions can
-be entered:
+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
-@itemize @bullet
-@item @code{\version}
-@item @code{\include}
-@item @code{\renameinput}
-@end itemize
+@example
+emacsclient --no-wait +%(line)s:%(column)s %(file)s
+@end example
+@noindent
+for @code{LYEDITOR} is equivalent to the standard emacsclient
+invocation.
-@node Including LilyPond files
-@section Including LilyPond files
-@cindex @code{\include}
-@cindex including files
+@cindex file size, output
-A large project may be split up into separate files. To refer to another
-file, use
+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
-\include "otherfile.ly"
+#(ly:set-option 'point-and-click #f)
@end example
-The line @code{\include "file.ly"} is equivalent to pasting the contents
-of file.ly into the current file at the place where you have the
-\include. For example, for a large project you might write separate files
-for each instrument part and create a ``full score'' file which brings
-together the individual instrument files.
-
-The initialization of LilyPond is done in a number of files that are
-included by default when you start the program, normally transparent to the
-user. Run lilypond --verbose to see a list of paths and files that Lily
-finds.
-
-Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
-VERSION is in the form ``2.6.1'') are on the path and available to
-@code{\include}. Files in the
-current working directory are available to \include, but a file of the same
-name in LilyPond's installation takes precedence. Files are
-available to \include from directories in the search path specified as an
-option when invoking @code{lilypond --include=DIR} which adds DIR to the search
-path.
-
-The @code{\include} statement can use full path information, but with the Unix
-convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
-if @file{stuff.ly} is located one directory higher than the current working
-directory, use
+@noindent
+in a @file{.ly} file. Alternately, you may pass this as an command-line
+option
@example
-\include "../stuff.ly"
+lilypond -dno-point-and-click file.ly
@end example
projects / lilypond.git / blobdiff