-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Running LilyPond
@chapter Running LilyPond
@menu
-* Invoking lilypond::
-* Error messages::
-* Updating files with convert-ly::
-* Reporting bugs::
-* Editor support::
+* Invoking lilypond::
+* Notes for the MacOS X app::
+* Error messages::
+* Updating files with convert-ly::
+* Reporting bugs::
+* Editor support::
@end menu
@node Invoking lilypond
@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. The function @code{ly:set-option} allows access to
-some internal variables. Use @code{-e '(ly:option-usage)'} for more
-information.
+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},
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
@cindex output format, setting
@item -d,--define-default=@var{var}=@var{val}
-This defines an internal variable @var{var} as the Scheme value
-@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.
+@example
+-dno-point-and-click
+@end example
-Supported values include:
-@table @code
-@item resolution
-set PNG resolution
-@item preview-include-book-title
-include book-titles in preview
-@end table
+@noindent
+is the same as
+@example
+-dpoint-and-click='#f'
+@end example
+
+@cindex point and click
-These settings are returned when calling
-@code{(ly:get-option 'command-line-settings)} from Scheme.
+Setting the @code{help} 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}.
+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
+@end example
@item --pdf
Generate PDF. This implies @code{--ps}.
@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
-Run LilyPond in a jail.
+Run 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
@section Environment variables
-For processing both the @TeX{} and the PostScript output, the
-appropriate environment variables must be set. The following scripts
-do this:
-@itemize @bullet
-@item @file{buildscripts/@/out/@/lilypond@/-profile}
-(for SH shells)
-@item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
-@end itemize
+@cindex LANG
+@cindex LILYPONDPREFIX
-They should normally be sourced as part of the login process. If these
-scripts are not run from the system wide login process, then you must
-run them yourself.
+@code{Lilypond} recognizes the following environment variables:
+@table @code
+@item LILYPONDPREFIX
+This specifies a directory where locale messages and
+data files will be looked up by default. The directory should contain
+subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
-@cindex installing LilyPond
+@item LANG
+This selects the language for the warning messages.
-If you use sh, bash, or a similar shell, then add the following to
-your @file{.profile}:
-@example
-. @var{/the/path/to/}lilypond-profile
-@end example
+@item LILYPOND_GC_YIELD
+With this variable the memory footprint and performance can be
+adjusted. It is a percentage tunes memory management behavior. With
+higher values, the program uses more memory, with smaller values, it
+uses more CPU time. The default value is @code{70}.
-If you use csh, tcsh or a similar shell, then add the following to
-your @file{~/.login}:
-@example
-source @var{/the/path/to/}lilypond-login
-@end example
+@end table
-Of course, in both cases, you should substitute the proper location of
-either script.
-These scripts set the following variables:
-@table @code
-@item TEXMF
-To make sure that @TeX{} and lilypond find data files (among
-others @file{.tex}, @file{.mf}, and @file{.tfm}),
-you have to set @code{TEXMF} to point to the lilypond data
-file tree. A typical setting would be
-@example
-@{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
-@end example
+@node Notes for the MacOS X app
+@section Notes for the MacOS X app
-@end table
+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{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
+@end example
-@cindex PostScript
-@cindex TEXMF
-@cindex printing postscript
+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
-The binary itself recognizes the following environment variables:
-@table @code
-@item LILYPONDPREFIX
-This specifies a directory where locale messages and
-data files will be looked up by default. The directory should contain
-subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
+@example
+export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
+@end example
-@item LANG
-This selects the language for the warning messages.
-@end table
+@noindent
+This file should end with a blank line.
+
+Note that @var{path/to} will generally be @code{/Applications/}.
-@cindex LANG
-@cindex LILYPONDPREFIX
@node Error messages
@section Error messages
@node Updating files with convert-ly
@section Updating with @command{convert-ly}
+@cindex Updating a LilyPond file
+@cindex @code{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,
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
+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}.}
@example
convert-ly -e myfile.ly
If there are no changes to myfile.ly and file called myfile.ly.NEW
is created, then myfile.ly is already updated.
+@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
@example
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 -o,--output=@var{file}
-Set the output file to write.
-
@item -n,--no-version
Normally, @command{convert-ly} adds a @code{\version} indicator
to the output. Specifying this option suppresses this.
Print usage help.
@end table
-@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.
@refbugs
@ignore
Copy and paste from CVS, last updated
-Feb 14, 2005
+Aug 18, 2005
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 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 {< >}. Mats' comment on working around this:
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. Only very simple cases are fixed.
+ 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")
+ This will incorrectly be converted into
+ -\markup{{\bold italic} "string"}
+ instead of the correct
+ -\markup{\bold \italic "string"}
2.0->2.2:
Doesn't handle \partcombine
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 #'. . .
+ 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" >
+ Crescendo and decrescendo terminators aren't converted.
+ - \rced => \!
+ - \rc => \!
2.2->2.4:
\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 { ... }} }
but now, \line is missing.
+2.4->2.6
+ Special LaTeX characters such as $~$ in text are not converted to UTF8.
+
@end verbatim
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.
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.5, fink package lilypond-unstable
+Using Mac OSX 10.3.7, fink package lilypond-devel
-\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
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}.
+
projects / lilypond.git / blobdiff