@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+
@node Running LilyPond
@chapter Running LilyPond
@menu
* Invoking lilypond::
* Notes for the MacOS X app::
-* Error messages::
* Updating files with convert-ly::
* Reporting bugs::
+* Error messages::
* Editor support::
+* 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
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
+ 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
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
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.
+invoking them directly, e.g.
@example
@var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
-@end example
-
-@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,
+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
-@cindex @code{convert-ly}
+@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
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)
- \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 via
+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.7.32"
-\relative c''@{
+\layout { ragged-right = ##t }
+\relative c'' {
a4 b cis d
-@}
-@end example
+}
+@end verbatim
@lilypond[quote]
-\version "2.7.32"
+\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
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
projects / lilypond.git / blobdiff