version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.51"
+
@node Running LilyPond
@chapter Running LilyPond
@menu
* Normal usage::
-* Command-line usage::
-* Error messages::
-* Updating files with convert-ly::
-* Reporting bugs::
+* 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 @ruser{First steps} if
+Most users run LilyPond through a GUI; see @rlearning{First steps} if
you have not read this already.
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{MacOS X
+@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}.
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::
+* Environment variables::
+@end menu
+@node Invoking lilypond
@subsection Invoking lilypond
@cindex Invoking LilyPond
@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{}
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
+the basename and the number. An input file containing
@example
#(define output-suffix "violin")
-\book @{ @dots{} @}
+\book @{ @dots{} @}
#(define output-suffix "cello")
-\book @{ @dots{} @}
+\book @{ @dots{} @}
@end example
@noindent
@var{base}@file{-cello-1.ps}.
-
+@node Command line options
@subsection Command line options
The following options are supported:
@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
available.
@item paper-size
-This option sets the default paper-size,
+This option sets the default paper-size,
@example
-dpaper-size=\"letter\"
@end example
@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}
+ 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
@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 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
-@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
-@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
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}.
@strong{NO WARRANTY}!)
@end table
-
+@node Environment variables
@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
@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
-uses more CPU time. The default value is @code{70}.
+uses more CPU time. The default value is @code{70}.
@end table
@end example
@noindent
-MacOS X users may execute this command under the menu entry
-@samp{Compile > Update syntax}.
+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.
@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
@subsection Problems with @code{convert-ly}
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.
-
-@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
+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:
+>}. 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
+ 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 '> }'.
- 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")
@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://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.
projects / lilypond.git / blobdiff