-@node Using LilyPond
-@chapter Using LilyPond
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-program.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-@menu
-* Setting variables::
-* Fine tuning layout::
-* Tuning output::
-* Text markup::
-* Global layout::
-* Sound::
-@end menu
-
-@node Setting variables
-@section Setting variables
-
-When the music is converted from notes to print it is interpreted
-in left-to-right order. This is similar to what happens when we read
-music. During this step context-sensitive information such as the
-accidentals to print, and where bar lines must be placed, are stored in
-variables. These variables are called @emph{context properties}.
-The properties can also be manipulated from input files. Consider this input:
-@example
-\set Staff.autoBeaming = ##f
-@end example
-
-@noindent
-It sets the property named @code{autoBeaming} in the current staff at
-this point in the music to @code{##f}, which means `false'. This
-property controls whether beams are printed automatically:
-@c
-@lilypond[relative=1,fragment,verbatim]
- c8 c c c
- \set Staff.autoBeaming = ##f
- c8 c c c
-@end lilypond
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
-@noindent
-LilyPond includes a built-in programming language, namely, a dialect
-of Scheme. The argument to @code{\set}, @code{##f}, is an
-expression in that language. The first hash-mark signals that a piece
-of Scheme code follows. The second hash character is part of the
-boolean value true (@code{#t}). Values of other types may be
-entered as follows:
-@itemize @bullet
-@item a string, enclosed in double quotes, for example,
-@example
- \set Staff.instrument = #"French Horn"
-@end example
-@item a boolean: either @code{#t} or @code{#f}, for true and false
-respectively, e.g.
-@example
- \set autoBeaming = ##f
- \set Score.skipBars = ##t
-@end example
-@item a number, such as
-@example
- \set Score.currentBarNumber = #20
-@end example
+@node Running LilyPond
+@chapter Running LilyPond
-@item a symbol, which is introduced by a quote character, as in
-@example
- \set Staff.crescendoSpanner = #'dashed-line
-@end example
+This chapter details the technicalities of running LilyPond.
-@item a pair, which is also introduced by a quote character, like in
-the following statements, which set properties to the pairs (-7.5, 6)
-and (3, 4) respectively:
-
-@example
- \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
- \set Staff.timeSignatureFraction = #'(3 . 4)
-@end example
-
-@item a list, which is also introduced by a quote character. In the
-following example, the @code{breakAlignOrder} property is set to a
-list of symbols:
-@example
- \set Score.breakAlignOrder =
- #'(left-edge time-signature key-signatures)
-@end example
-
-
-@end itemize
-
-There are many different properties. Not all of them are listed in
-this manual. However, the program reference lists them all in the
-section @internalsref{Context-properties}, and most properties are
-demonstrated in one of the
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
-
-
-@node Fine tuning layout
-@section Fine tuning layout
-
-Sometimes it is necessary to change music layout by hand. When music
-is formatted, layout objects are created for each symbol. For
-example, every clef and every note head is represented by a layout
-object. These layout objects also carry variables, which we call
-@emph{layout properties}. By changing these variables from their
-values, we can alter the look of a formatted score:
-
-@lilypond[verbatim,relative]
- c4
- \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
-
-@noindent
-In the example shown here, the layout property @code{thickness} (a
-symbol) is set to 3 in the @code{Stem} layout objects of the current
-As a result, the notes following @code{\override} have thicker
-stems.
+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}.
-For the most part, a manual override is needed only on a case by
-case basis and not for all subsequent instances of the altered
-property. To accomplish this, simply prefix @code{\once} to the
-@code{\override} statement and the override will apply only once,
-immediately reverting to its default setting, i.e.
-
-@example
- \once \override Stem #'thickness = #3.0
-@end example
-
-@lilypond[relative]
- c4
- \once \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
-
-@noindent
-Some overrides are so common that predefined commands are provided as
-a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@ref{Notation manual}, under the sections for slurs and stems
-respectively.
-
-The exact tuning possibilities for each type of layout object are
-documented in the program reference of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a couple of these:
-
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves around objects in the printout.
-The first number controls left-right movement; a positive number will
-move the object to the right. The second number controls up-down
-movement; a positive number will move it higher. The units of these
-offsets are staff-spaces. The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
-
-In the following example, the second fingering is moved a little to
-the left, and 1.8 staff space downwards:
-
-@cindex setting object properties
-
-@lilypond[relative=1,verbatim]
-\stemUp
-f-5
-\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
-
-@item
-Setting the @code{transparent} property will cause an object to be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes up space, it takes part in
-collisions, and slurs, and ties and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
-The following example demonstrates how to connect different voices
-using ties. Normally, ties only connect two notes in the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices:
-
-@lilypond[fragment,relative=1,verbatim]
- c4 << {
- \once \override Stem #'transparent = ##t
- b8~ b8
- } \\ {
- b[ g8]
- } >>
-@end lilypond
-
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[relative=1,verbatim]
- c2\fermata
- \override Script #'padding = #3
- b2\fermata
-@end lilypond
-
-@end itemize
-
-More specific overrides are also possible. The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
-
-
-
-
-@node Tuning output
-@section Tuning output
-
-There are situations where default layout decisions are not
-sufficient. In this section we discuss ways to override these
-defaults.
-
-Formatting is internally done by manipulating so called objects
-(graphic objects). Each object carries with it a set of properties
-(object or layout properties) specific to that object. For example, a
-stem object has properties that specify its direction, length and
-thickness.
-
-The most direct way of tuning the output is by altering the values of
-these properties. There are two ways of doing that: first, you can
-temporarily change the definition of one type of object, thus
-affecting a whole set of objects. Second, you can select one specific
-object, and set a layout property in that object.
-
-Do not confuse layout properties with translation
-properties. Translation properties always use a mixed caps style
-naming, and are manipulated using @code{\set} and @code{\unset}:
-@example
- \set Context.propertyName = @var{value}
-@end example
-
-Layout properties are use Scheme style variable naming, i.e. lower
-case words separated with dashes. They are symbols, and should always
-be quoted using @code{#'}. For example, this could be an imaginary
-layout property name:
-@example
- #'layout-property-name
-@end example
-
-@seealso
-
-The introduction of the @ref{Technical manual} gives a more in-depth
-treatment of the difference between translation and layout.
+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
-* Tuning objects::
-* Constructing a tweak::
-* Applyoutput::
-* Font selection::
+* Invoking lilypond::
+* Updating files with convert-ly::
+* Reporting bugs::
+* Error messages::
@end menu
+@node Invoking lilypond
+@section Invoking lilypond
+@cindex Invoking LilyPond
+@cindex command line options
+@cindex options, command line
+@cindex switches
-@node Tuning objects
-@subsection Tuning objects
-
-@cindex object description
-
-The definition of an object is a list of default object
-properties. For example, the definition of the Stem object (available
-in @file{scm/define-grobs.scm}), includes the following definitions
-for @internalsref{Stem}:
+The @code{lilypond} executable may be called as follows from the command line.
@example
- (thickness . 1.3)
- (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
- (Y-extent-callback . ,Stem::height)
- @var{...}
+lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example
-Adding variables on top of this existing definition overrides the
-system default, and alters the resulting appearance of the layout
-object.
+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}.
-@syntax
+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;
+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.}
+In addition, the value of @code{output-suffix} will be inserted between
+the basename and the number. An input file containing
-Changing a variable for only one object is commonly achieved with
-@code{\once}:
-
-@example
-\once \override @var{context}.@var{objectname}
- @var{symbol} = @var{value}
-@end example
-Here @var{symbol} is a Scheme expression of symbol type, @var{context}
-and @var{objectname} is a string and @var{value} is a Scheme expression.
-This command applies a setting only during one moment in the score.
-
-In the following example, only one @internalsref{Stem} object is
-changed from its original setting:
-
-@lilypond[verbatim,fragment,relative=1]
- c4
- \once \override Voice.Stem #'thickness = #4
- c4
- c4
-@end lilypond
-@cindex @code{\once}
-
-For changing more objects, the same command, without @code{\once} can
-be used:
-@example
-\override @var{context}.@var{objectname} @var{symbol} = @var{value}
-@end example
-This command adds @code{@var{symbol} = @var{value}} to the definition
-of @var{objectname} in the context @var{context}, and this definition
-stays in place until it is removed.
-
-An existing definition may be removed by the following command:
-@c
@example
-\property @var{context}.@var{objectname} \revert @var{symbol}
+#(define output-suffix "violin")
+\book @{ @dots{} @}
+#(define output-suffix "cello")
+\book @{ @dots{} @}
@end example
-@c
-
-Some examples:
-@lilypond[verbatim]
-c'4 \override Stem #'thickness = #4.0
-c'4
-c'4 \revert Stem #'thickness
-c'4
-@end lilypond
-
-The following example gives exactly the same result as the previous
-one (assuming the system default for stem thickness is 1.3):
-@c
-@lilypond[verbatim]
- c'4 \override Stem #'thickness = #4.0
- c'4
- c'4 \override Stem #'thickness = #1.3
- c'4
-@end lilypond
-
-Reverting a setting which was not set in the first place has no
-effect.
-
-
-@seealso
-
-Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
-@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
-@internalsref{All-layout-objects}.
-
-
-@refbugs
-The back-end is not very strict in type-checking object properties.
-Cyclic references in Scheme values for properties can cause hangs
-and/or crashes.
-
-@menu
-* Constructing a tweak::
-* Applyoutput::
-* Font selection::
-* Text markup::
-@end menu
-
-@node Constructing a tweak
-@subsection Constructing a tweak
-
-
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions
-@cindex tweaking
-@cindex @code{\override}
-@cindex @code{\set}
-@cindex internal documentation
-
-
-
-Three pieces of information are required to use @code{\override} and
-@code{\set}: the name of the layout object, the context and the name
-of the property. We demonstrate how to glean this information from
-the notation manual and the generated documentation.
-
-The generated documentation is a set of HTML pages which should be
-included if you installed a binary distribution, typically in
-@file{/usr/share/doc/lilypond}. They are also available on the web:
-go to the @uref{http://lilypond.org,LilyPond website}, click
-``Documentation'', select the correct version, and click then
-``Program reference.'' It is advisable to bookmark the local HTML
-files. They will load faster than the ones on the web. If you use the
-version from the web, you must check whether the documentation matches
-the program version: it is generated from the definitions that the
-program uses, and therefore it is strongly tied to the LilyPond
-version.
-
-
-@c [TODO: revise for new site.]
-
-Suppose we want to move the fingering indication in the fragment below:
+@noindent
+will output @var{base}@file{-violin.ps} and
+@var{base}@file{-cello-1.ps}.
-@lilypond[relative=2,verbatim]
-c-2
-\stemUp
-f
-@end lilypond
-If you visit the documentation of @code{Fingering} (in @ref{Fingering
-instructions}), you will notice that there is written:
-@quotation
-@seealso
+@subsection Command line options
-Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
+The following options are supported:
-@end quotation
+@table @code
-@separate
+@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.
-@noindent
-In other words, the fingerings once entered, are internally stored as
-@code{FingerEvent} music objects. When printed, a @code{Fingering}
-layout object is created for every @code{FingerEvent}.
-
-The Fingering object has a number of different functions, and each of
-those is captured in an interface. The interfaces are listed under
-@internalsref{Fingering} in the program reference.
-
-
-
-The @code{Fingering} object has a fixed size
-(@internalsref{item-interface}), the symbol is a piece of text
-(@internalsref{text-interface}), whose font can be set
-(@internalsref{font-interface}). It is centered horizontally
-(@internalsref{self-alignment-interface}), it is placed next to other
-objects (@internalsref{side-position-interface}) vertically, and its
-placement is coordinated with other scripts
-(@internalsref{text-script-interface}). It also has the standard
-@internalsref{grob-interface} (grob stands for Graphical object)
-@cindex grob
-@cindex graphical object
-@cindex layout object
-@cindex object, layout
-with all the variables that come with
-it. Finally, it denotes a fingering instruction, so it has
-@internalsref{finger-interface}.
-
-For the vertical placement, we have to look under
-@code{side-position-interface}:
-@quotation
-@code{side-position-interface}
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
- Position a victim object (this one) next to other objects (the
- support). In this case, the property @code{direction} signifies where to put the
- victim object relative to the support (left or right, up or down?)
-@end quotation
+@example
+lilypond -e '(define-public a 42)'
+@end example
-@cindex padding
@noindent
-below this description, the variable @code{padding} is described as
-@quotation
-@table @code
-@item padding
- (dimension, in staff space)
+on the command-line, and include
- add this much extra space between objects that are next to each
-other. Default value: @code{0.6}
-@end table
-@end quotation
-
-By increasing the value of @code{padding}, we can move away the
-fingering. The following command inserts 3 staff spaces of white
-between the note and the fingering:
@example
-\once \override Fingering #'padding = #3
+#(use-modules (guile-user))
@end example
-Inserting this command before the Fingering object is created,
-i.e. before @code{c2}, yields the following result:
-
-@lilypond[relative=2,fragment,verbatim]
-\once \override Fingering
- #'padding = #3
-c-2
-\stemUp
-f
-@end lilypond
-
-The context name @code{Voice} in the example above can be determined
-as follows. In the documentation for @internalsref{Fingering}, it says
-@quotation
-Fingering grobs are created by: @internalsref{Fingering_engraver} @c
-@end quotation
+@noindent
+at the top of the @code{.ly} file.
-Clicking @code{Fingering_engraver} shows the documentation of
-the module responsible for interpreting the fingering instructions and
-translating them to a @code{Fingering} object. Such a module is called
-an @emph{engraver}. The documentation of the @code{Fingering_engraver}
-says
-@example
-Fingering_engraver is part of contexts: Voice
-@end example
-so tuning the settings for Fingering should be done with
-@example
- \override Fingering @dots{}
-@end example
+@item -f,--format=@var{format}
+which formats should be written. Choices for @code{format} are
+@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
-Of course, the tweak may also done in a larger context than
-@code{Voice}, for example, @internalsref{Staff} or
-@internalsref{Score}.
+Example: @code{lilypond -fpng filename.ly}
-@seealso
-Internals: the program reference also contains alphabetical lists of
-@internalsref{Contexts}, @internalsref{All-layout-objects} and
-@internalsref{Music-expressions}, so you can also find which objects
-to tweak by browsing the internals document.
+@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}, e.g.
-@node Applyoutput
-@subsection Applyoutput
+@cindex point and click, command line
-The most versatile way of tuning an object is @code{\applyoutput}. Its
-syntax is
@example
-\applyoutput @var{proc}
+-dno-point-and-click
@end example
@noindent
-where @var{proc} is a Scheme function, taking three arguments.
-
-When interpreted, the function @var{proc} is called for every layout
-object found in the context, with the following arguments:
-@itemize @bullet
-@item the layout object itself,
-@item the context where the layout object was created, and
-@item the context where @code{\applyoutput} is processed.
-@end itemize
-
-
-In addition, the cause of the layout object, i.e. the music
-expression or object that was responsible for creating it, is in the
-object property @code{cause}. For example, for a note head, this is a
-@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
-this is a @internalsref{NoteHead} object.
-
-Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
-center-line:
+is the same as
@example
-(define (blanker grob grob-origin context)
- (if (and (memq (ly:grob-property grob 'interfaces)
- note-head-interface)
- (eq? (ly:grob-property grob 'staff-position) 0))
-
- (ly:grob-set-property! grob 'transparent #t)))
+-dpoint-and-click='#f'
@end example
+Here are a few interesting options.
+@table @samp
+@item help
+Running @code{lilypond -dhelp} will print all of the @code{-d} options
+available.
-@node Font selection
-@subsection Font selection
-
-The most common thing to change about the appearance of fonts is their
-size. The font size of any context can be easily changed by setting
-the @code{fontSize} property for that context. Its value is a number:
-negative numbers make the font smaller, positive numbers larger. An
-example is given below:
-@c
-@lilypond[fragment,relative=1,verbatim]
- c4 c4 \set fontSize = #-1
- f4 g4
-@end lilypond
-This command will set @code{font-size} (see below), and does
-not change the size of variable symbols, such as beams or slurs.
-
-One of the uses of @code{fontSize} is to get smaller symbols for cue
-notes. An elaborate example of those is in
-@inputfileref{input/test,cue-notes.ly}.
-
-@cindex magnification
-@cindex cue notes
-
-The font used for printing a object can be selected by setting
-@code{font-name}, e.g.
+@item paper-size
+This option sets the default paper-size,
@example
- \override Staff.TimeSignature
- #'font-name = #"cmr17"
+-dpaper-size=\"letter\"
@end example
@noindent
-Any font can be used, as long as it is available to @TeX{}. Possible
-fonts include foreign fonts or fonts that do not belong to the
-Computer Modern font family. The size of fonts selected in this way
-can be changed with the @code{font-magnification} property. For
-example, @code{2.0} blows up all letters by a factor 2 in both
-directions.
-
-@cindex font size
-@cindex font magnification
+Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
-can also be adjusted with a more fine-grained mechanism. By setting
-the object properties described below, you can select a different font;
-all three mechanisms work for every object that supports
-@code{font-interface}:
+@item safe
+Do not trust the @code{.ly} input.
-@table @code
-@item font-family
- is a symbol indicating the general class of the typeface. Supported are
-@code{roman} (Computer Modern), @code{braces} (for piano staff
-braces), @code{music} (the standard music font, including ancient
-glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}.
-
-@item font-shape
- is a symbol indicating the shape of the font, there are typically several
- font shapes available for each font family. Choices are @code{italic},
- @code{caps} and @code{upright}.
-
-@item font-series
-is a symbol indicating the series of the font. There are typically several
-font series for each font family and shape. Choices are @code{medium}
-and @code{bold}.
+When LilyPond formatting is available through a web server, either the
+@code{--safe} or the @code{--jail} option @b{MUST} be passed. The
+@code{--safe} option will prevent inline Scheme code from wreaking
+havoc, for example
-@end table
+@quotation
+@verbatim
+#(system "rm -rf /")
+{
+ c4^#(ly:export (ly:gulp-file "/etc/passwd"))
+}
+@end verbatim
+@end quotation
-For any of these properties, the value @code{*} (i.e. the symbol
-@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
-to override default setting, which are always present. For example:
-@example
- \override Lyrics .LyricText #'font-series = #'bold
- \override Lyrics .LyricText #'font-family = #'typewriter
- \override Lyrics .LyricText #'font-shape = #'*
-@end example
+The @code{-dsafe} option works by evaluating in-line Scheme
+expressions in a special safe module. This safe module is derived from
+GUILE @file{safe-r5rs} module, but adds a number of functions of the
+LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
-@cindex @code{font-style}
+In addition, safe mode disallows @code{\include} directives and
+disables the use of backslashes in @TeX{} strings.
-The font size is set by modifying the @code{font-size} property. Its
-value is a number indicating the size relative to the standard size.
-Each step up is an increase of approximately 12% of the font size. Six
-steps is exactly a factor two. The Scheme function @code{magstep}
-converts a @code{font-size} number to a scaling factor.
+In safe mode, it is not possible to import LilyPond variables
+into Scheme.
-LilyPond has fonts in different design sizes: the music fonts for
-smaller sizes are chubbier, while the text fonts are relatively wider.
-Font size changes are achieved by scaling the design size that is
-closest to the desired size.
+safe 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
+CPU and memory usage.
-The @code{font-size} mechanism does not work for fonts selected
-through @code{font-name}. These may be scaled with
-@code{font-magnification}.
+The safe mode will prevent many useful LilyPond snippets from being
+compiled. The @code{--jail} is a more secure alternative, but
+requires more work to set up.
-@refcommands
+@item backend
+the output format to use for the back-end. Choices for @code{format} are
+@table @code
+@item tex
+for @TeX{} output, to be processed with La@TeX{}. If present, the file
+@file{file.textmetrics} is read to determine text extents.
+@item texstr
+dump text strings to @file{.texstr} file, which can be run through
+(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
+extents of strings of text. @strong{Warning:} this functionality is
+currently missing due to heavy restructuring of the source code.
+@item ps
+ for PostScript.
+@cindex PostScript output
+
+ 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.
+
+@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
+all pages (systems) including fonts.
+
+This mode is used by default by lilypond-book.
+
+@item svg
+ 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
-The following commands set @code{fontSize} for the current voice.
+Example: @code{lilypond -dbackend=svg filename.ly}
-@cindex @code{\tiny}
-@code{\tiny},
-@cindex @code{\small}
-@code{\small},
-@cindex @code{\normalsize}
-@code{\normalsize}.
+@cindex output format, setting
-@seealso
+@item preview
+Generate an output file containing the titles and the first system
-Init files: @file{ly/declarations-init.ly} contains hints how new
-fonts may be added to LilyPond.
+@item print-pages
+Generate the full pages, the default. @code{-dno-print-pages} is
+useful in combination with @code{-dpreview}.
-@refbugs
+@end table
-There is no style sheet provided for other fonts besides the @TeX{}
-Computer Modern family.
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
+@item -h,--help
+Show a summary of usage.
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
+@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
+@cindex search path
-@cindex typeset text
+@item -i,--init=@var{file}
+Set init file to @var{file} (default: @file{init.ly}).
-LilyPond has an internal mechanism to typeset texts. You can access it
-with the keyword @code{\markup}. Within markup mode, you can enter texts
-similar to lyrics: simply enter them, surrounded by spaces:
-@cindex markup
+@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}
+for tex, etc).
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { hello }
- c1_\markup { hi there }
- c1^\markup { hi \bold there, is \italic anyone home? }
-@end lilypond
+@item --ps
+Generate PostScript.
-@cindex font switching
+@item --dvi
+Generate DVI files. In this case, the @TeX{} backend should be
+specified, i.e., @code{-dbackend=tex}.
-The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} only apply to the first
-following word; enclose a set of texts with braces to apply a command
-to more words:
+@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
- \markup @{ \bold @{ hi there @} @}
+-dresolution=110
@end example
-@noindent
-For clarity, you can also do this for single arguments, e.g.
+@item --pdf
+Generate PDF. This implies @code{--ps}.
-@verbatim
- \markup { is \italic { anyone } home }
-@end verbatim
-
-@cindex font size, texts
-
-
-In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents and music expressions. The braces group
-notes into horizontal lines. Other types of lists also exist: you can
-stack expressions grouped with @code{<}, and @code{>} vertically with
-the command @code{\column}. Similarly, @code{\center-align} aligns
-texts by their center lines:
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { \column < a bbbb c > }
- c1^\markup { \center-align < a bbbb c > }
- c1^\markup { \line < a b c > }
-@end lilypond
+@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+Run LilyPond in a chroot jail.
-Markups can be stored in variables, and these variables
-may be attached to notes, like
-@verbatim
-allegro = \markup { \bold \large { Allegro } }
-\notes { a^\allegro b c d }
-@end verbatim
+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
+@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
+accomplished in a safe way using @command{sudo}.
-Some objects have alignment procedures of their own, which cancel out
-any effects of alignments applied to their markup arguments as a
-whole. For example, the @internalsref{RehearsalMark} is horizontally
-centered, so using @code{\mark \markup @{ \left-align .. @}} has no
-effect. Similarly, whole texts over notes cannot be moved vertically
-with @code{\raise}. For moving and aligning complete objects, grob
-properties should be used.
+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:
+@table @asis
+@item Setting up a separate filesystem
+A separate filesystem should be created for LilyPond, so that it can be
+mounted with safe options such as @code{noexec}, @code{nodev}, and
+@code{nosuid}. In this way, it is impossible to run executables or to
+write directly to a device from LilyPond. If you do not want to create a
+separate partition, just create a file of reasonable size and use it to
+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
+A separate user and group (say, @samp{lily}/@samp{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}.
-@seealso
+@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 appear in the
+real root filesystem. The entire content of the LilyPond installation
+(e.g., @file{/usr/share/lilypond})
+should be copied.
-Init files: @file{scm/new-markup.scm}.
+If problems arise, the simplest way to trace them down is to run
+LilyPond using @command{strace}, which will allow you to determine which
+files are missing.
+@item Running LilyPond
+In a jail mounted with @code{noexec} it is impossible to execute any external
+program. Therefore LilyPond must be run with a backend that does not
+require any such program. As we already mentioned, it must be also run
+with superuser privileges (which, of course, it will lose immediately),
+possibly using @command{sudo}. It is a good idea to limit the number of
+seconds of CPU time LilyPond can use (e.g., using @command{ulimit
+-t}), and, if your operating system supports it, the amount of memory
+that can be allocated.
+@end table
-@refbugs
-
-Text layout is ultimately done by @TeX{}, which does kerning of
-letters. LilyPond does not account for kerning, so texts will be
-spaced slightly too wide.
-Syntax errors for markup mode are confusing.
+@item -v,--version
+Show version information.
-Markup texts cannot be used in the titling of the @code{\header}
-field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
-for formatting.
+@item -V,--verbose
+Be verbose: show full paths of all files read, and give timing
+information.
+@item -w,--warranty
+Show the warranty with which GNU LilyPond comes. (It comes with
+@strong{NO WARRANTY}!)
+@end table
-@menu
-* Overview of text markup commands::
-* Markup construction in scheme::
-* Markup command definition::
-@end menu
+@subsection Environment variables
-@node Overview of text markup commands
-@subsection Overview of text markup commands
-@include markup-commands.tely
+@cindex LANG
+@cindex LILYPOND_DATADIR
-@node Markup construction in scheme
-@subsection Markup construction in scheme
+@code{Lilypond} recognizes the following environment variables:
+@table @code
+@item LILYPOND_DATADIR
+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 defining markup commands
+@item LANG
+This selects the language for the warning messages.
-The @code{markup} macro builds markup expressions in Scheme while
-providing a LilyPond-like syntax. For example,
-@example
-(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
- #:bigger #:line ("foo" "bar" "baz")))
-@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}.
-@noindent
-is equivalent to:
-@example
-\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
- \bigger @{ foo bar baz @} >
-@end example
+@end table
-@noindent
-This example exposes the main translation rules between regular
-LilyPond markup syntax and scheme markup syntax, which are summed up
-is this table:
-@multitable @columnfractions .5 .5
-@item @b{LilyPond} @tab @b{Scheme}
-@item @code{\command} @tab @code{#:command}
-@item @code{\variable} @tab @code{variable}
-@item @code{@{ ... @}} @tab @code{#:line ( ... )}
-@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
-@item @code{string} @tab @code{"string"}
-@item @code{#scheme-arg} @tab @code{scheme-arg}
-@end multitable
-
-Besides, the whole scheme language is accessible inside the
-@code{markup} macro: thus, one may use function calls inside
-@code{markup} in order to manipulate character strings for
-instance. This proves useful when defining new markup commands (see
-@ref{Markup command definition}).
-@refbugs
+@node Updating files with convert-ly
+@section Updating with @command{convert-ly}
-One can not feed the @code{#:line} (resp @code{#:center},
-@code{#:column}) command with a variable or the result of a function
-call. Eg:
-@lisp
-(markup #:line (fun-that-returns-markups))
-@end lisp
-is illegal. One should use the @code{make-line-markup} (resp
-@code{make-center-markup}, @code{make-column-markup}) function
-instead:
-@lisp
-(markup (make-line-markup (fun-that-returns-markups)))
-@end lisp
-
-@node Markup command definition
-@subsection Markup command definition
-
-New markup commands can be defined thanks to the @code{def-markup-command} scheme macro.
-@lisp
-(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
- (@var{arg1-type?} @var{arg2-type?} ...)
- ..command body..)
-
- @var{argi}: i@var{th} command argument
- @var{argi-type?}: a type predicate for the i@var{th} argument
- @var{paper}: the `paper' definition
- @var{props}: a list of alists, containing all active properties.
-@end lisp
-
-As a simple example, we show how to add a @code{\smallcaps} command,
-which selects @TeX{}'s small caps font. Normally, we could select the
-small caps font as follows:
+@cindex Updating a LilyPond file
+@cindex convert-ly
-@verbatim
- \markup { \override #'(font-shape . caps) Text-in-caps }
-@end verbatim
+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.
-This selects the caps font by setting the @code{font-shape} property to
-@code{#'caps} for interpreting @code{Text-in-caps}.
+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}.}
-To make the above available as @code{\smallcaps} command, we have to
-define a function using @code{def-markup-command}. The command should
-take a single argument, of markup type. Therefore, the start of the
-definition should read
@example
- (def-markup-command (smallcaps paper props argument) (markup?)
+convert-ly -e myfile.ly
@end example
-@noindent
+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.
-What follows is the content of the command: we should interpret
-the @code{argument} as a markup, i.e.
+To upgrade LilyPond fragments in texinfo files, use
@example
- (interpret-markup paper @dots{} argument)
+convert-ly --from=... --to=... --no-version *.itely
@end example
-@noindent
-This interpretation should add @code{'(font-shape . caps)} to the active
-properties, so we substitute the the following for the @dots{} in the
-above example:
+To see the changes in the LilyPond syntax between two versions, use
@example
- (cons (list '(font-shape . caps) ) props)
+convert-ly --from=... --to=... -s
@end example
-@noindent
-The variable @code{props} is a list of alists, and we prepend to it by
-consing a list with the extra setting.
-
-However, suppose that we are using a font that does not have a
-small-caps variant. In that case, we have to fake the small caps font,
-by setting a string in upcase, with the first letter a little larger:
+To upgrade many files at once, combine @code{convert-ly} with
+standard unix commands. This example will upgrade all @code{.ly}
+files in the current directory
@example
-#(def-markup-command (smallcaps paper props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
- (interpret-markup paper props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
+for f in *.ly; do convert-ly -e $f; done;
@end example
-The @code{smallcaps} command first splits its string argument into
-tokens separated by spaces (@code{(string-split str #\Space)}); for
-each token, a markup is built with the first letter made large and
-upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
-second markup built with the following letters made tiny and upcased
-(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
-introduces a space between markups on a line, the second markup is
-translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
-the markups built for each token are put in a line
-(@code{(make-line-markup ...)}). Finally, the resulting markup is
-passed to the @code{interpret-markup} function, with the @code{paper}
-and @code{props} arguments.
-
-Finally, suppose that we are typesetting a recitative in an opera, and
-we would like to define a command that will show character names in a
-custom manner. Names should be printed with small caps and translated a
-bit to the left and top. We will define a @code{\character} command
-that takes into account the needed translation, and uses the newly
-defined @code{\smallcaps} command:
+In general, the program is invoked as follows:
-@verbatim
-#(def-markup-command (character paper props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
- (interpret-markup paper props
- (markup "" #:translate (cons -4 2) #:smallcaps name)))
-@end verbatim
-
-There is one complication that needs explanation: texts above and below
-the staff are moved vertically to be at a certain distance (the
-@code{padding} property) from the staff and the notes. To make sure
-that this mechanism does not annihilate the vertical effect of our
-@code{#:translate}, we add an empty string (@code{""}) before the
-translated text. Now the @code{""} will be put above the notes, and the
-@code{name} is moved in relation to that empty string. The net effect is
-that the text is moved to the upper left.
-
-The final result is as follows:
-@verbatim
-\score {
- \notes { \fatText
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
- }
-}
-@end verbatim
-
-@lilypond[raggedright]
-#(def-markup-command (smallcaps paper props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
- (interpret-markup paper props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-
-#(def-markup-command (character paper props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
- (interpret-markup paper props
- (markup "" #:translate (cons -4 0) #:smallcaps name)))
-
-\score {
- \notes { \fatText
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
- }
-}
-@end lilypond
-
-
-
-@node Global layout
-@section Global layout
-
-The global layout determined by three factors: the page layout, the
-line breaks and the spacing. These all influence each other. The
-choice of spacing determines how densely each system of music is set,
-which influences where line breaks breaks are chosen, and thus
-ultimately how many pages a piece of music takes. This section
-explains how to tune the algorithm for spacing.
-
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combination are tried, and the one with the
-best results---a layout that has uniform density and requires as
-little stretching or cramping as possible---is chosen. When the score
-is processed by @TeX{}, each page is filled with systems, and page breaks
-are chosen whenever the page gets full.
-
-
-
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Font Size::
-* Line breaking::
-* Page layout::
-@end menu
-
-
-@node Vertical spacing
-@subsection Vertical spacing
-
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staffs per page
-@cindex space between staves
-
-The height of each system is determined automatically by LilyPond, to
-keep systems from bumping into each other, some minimum distances are
-set. By changing these, you can put staves closer together, and thus
-put more systems onto one page.
-
-Normally staves are stacked vertically. To make
-staves maintain a distance, their vertical size is padded. This is
-done with the property @code{minimumVerticalExtent}. It takes a pair
-of numbers, so if you want to make it smaller from its, then you could
-set
@example
- \set Staff.minimumVerticalExtent = #'(-4 . 4)
+convert-ly [@var{option}]@dots{} @var{file}@dots{}
@end example
-This sets the vertical size of the current staff to 4 staff spaces on
-either side of the center staff line. The argument of
-@code{minimumVerticalExtent} is interpreted as an interval, where the
-center line is the 0, so the first number is generally negative. The
-staff can be made larger at the bottom by setting it to @code{(-6
-. 4)}.
-
-The piano staves are handled a little differently: to make cross-staff
-beaming work correctly, it is necessary that the distance between staves
-is fixed beforehand. This is also done with a
-@internalsref{VerticalAlignment} object, created in
-@internalsref{PianoStaff}. In this object the distance between the
-staves is fixed by setting @code{forced-distance}. If you want to
-override this, use a @code{\translator} block as follows:
-@example
- \paper @{
- \translator @{
- \PianoStaffContext
- \override VerticalAlignment #'forced-distance = #9
- @}
- @dots{}
- @}
-@end example
-This would bring the staves together at a distance of 9 staff spaces,
-measured from the center line of each staff.
-
-@seealso
-
-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
-
-
-
-
-@node Horizontal spacing
-@subsection Horizontal Spacing
-
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differing lengths. Longer
-durations get more space, shorter durations get less. The shortest
-durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
-The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
-
-For example, the following piece contains lots of half, quarter and
-8th notes, the eighth note is followed by 1 note head width (NHW).
-The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-@lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
-@end lilypond
-
-Normally, @code{shortest-duration-space} is set to 1.2, which is the
-width of a note head, and @code{shortest-duration-space} is set to
-2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
-@code{shortest-duration-space}) of space. For normal notes, this space
-is always counted from the left edge of the symbol, so the shortest
-notes are generally followed by one NHW of space.
-
-If one would follow the above procedure exactly, then adding a single
-32th note to a score that uses 8th and 16th notes, would widen up the
-entire score a lot. The shortest note is no longer a 16th, but a 32nd,
-thus adding 1 NHW to every note. To prevent this, the
-shortest duration for spacing is not the shortest note in the score,
-but the most commonly found shortest note. Notes that are even
-shorter this are followed by a space that is proportional to their
-duration relative to the common shortest note. So if we were to add
-only a few 16th notes to the example above, they would be followed by
-half a NHW:
-
-@lilypond[fragment,verbatim,relative=2]
- c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
-
-The most common shortest duration is determined as follows: in every
-measure, the shortest duration is determined. The most common short
-duration, is taken as the basis for the spacing, with the stipulation
-that this shortest duration should always be equal to or shorter than
-1/8th note. The shortest duration is printed when you run lilypond
-with @code{--verbose}. These durations may also be customized. If you
-set the @code{common-shortest-duration} in
-@internalsref{SpacingSpanner}, then this sets the base duration for
-spacing. The maximum duration for this base (normally 1/8th), is set
-through @code{base-shortest-duration}.
-
-@cindex @code{common-shortest-duration}
-@cindex @code{base-shortest-duration}
-@cindex @code{stem-spacing-correction}
-@cindex @code{spacing}
-
-In the introduction it was explained that stem directions influence
-spacing. This is controlled with @code{stem-spacing-correction}
-property in @internalsref{NoteSpacing}, which are generated for every
-@internalsref{Voice} context. The @code{StaffSpacing} object
-(generated at @internalsref{Staff} context) contains the same property
-for controlling the stem/bar line spacing. The following example
-shows these corrections, once with default settings, and once with
-exaggerated corrections:
-
-@lilypond
- \score { \notes {
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
- \override Staff.NoteSpacing #'stem-spacing-correction
- = #1.5
- \override Staff.StaffSpacing #'stem-spacing-correction
- = #1.5
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
- }
- \paper { raggedright = ##t } }
-@end lilypond
-
-@cindex SpacingSpanner, overriding properties
-
-Properties of the @internalsref{SpacingSpanner} must be overridden
-from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
-created before any property commands are interpreted.
-@example
-\paper @{ \translator @{
- \ScoreContext
- SpacingSpanner \override #'spacing-increment = #3.0
-@} @}
-@end example
-
-@seealso
-
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
-
-@refbugs
-Spacing is determined on a score wide basis. If you have a score that
-changes its character (measured in durations) halfway during the
-score, the part containing the longer durations will be spaced too
-widely.
+The following options can be given:
-There is no convenient mechanism to manually override spacing.
-
-
-
-@node Font Size
-@subsection Font size
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{paper} file
-
-The Feta font provides musical symbols at eight seven different
-sizes. Each font is tuned for a different staff size: at smaller sizes
-the font gets heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
-
-@multitable @columnfractions .25 .25 .25 .25
-
-@item @b{name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60pt
-@tab 4.4mm
-@tab
-
-@item feta14
-@tab 14.14pt
-@tab 5.0mm
-@tab
-
-@item feta16
-@tab 15.87pt
-@tab 5.6mm
-@tab
+@table @code
+@item -e,--edit
+Do an inline edit of the input file. Overrides @code{--output}.
-@item feta18
-@tab 17.82pt
-@tab 6.3mm
-@tab song books
+@item -f,--from=@var{from-patchlevel}
+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 feta20
-@tab 17.82pt
-@tab 7.0mm
-@tab standard parts
+@item -n,--no-version
+Normally, @command{convert-ly} adds a @code{\version} indicator
+to the output. Specifying this option suppresses this.
-@item feta23
-@tab 22.45 pt
-@tab 7.9mm
-@tab
+@item -s, --show-rules
+Show all known conversions and exit.
-@item feta20
-@tab 25.2 pt
-@tab 8.9mm
-@tab
-@c modern rental material ?
+@item --to=@var{to-patchlevel}
+Set the goal version of the conversion. It defaults to the latest
+available version.
-@end multitable
+@item -h, --help
+Print usage help.
+@end table
-These fonts are available in any sizes. The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@internalsref{StaffSymbol}) can be used to tune size for individual
-staffs. The size of individual staffs are relative to the global size,
-which can be set in the following manner:
-@example
- #(set-global-staff-size 14)
-@end example
+@refbugs
-This sets the global default size to 14pt staff height, and scales all
-fonts accordingly.
+Not all language changes are handled. Only one output option can be
+specified. Automatically updating scheme and lilypond scheme
+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
-@node Line breaking
-@subsection Line breaking
+@ignore
+Copy and paste from CVS, last updated
+Aug 18, 2005
-@cindex line breaks
-@cindex breaking lines
+http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
+convert-ly.txt?rev=HEAD&content-type=text/plain
-Line breaks are normally computed automatically. They are chosen such
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
+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
-Occasionally you might want to override the automatic breaks; you can
-do this by specifying @code{\break}. This will force a line break at
-this point. Line breaks can only occur at places where there are bar
-lines. If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar
-""}. Similarly, @code{\noBreak} forbids a line break at a
-point.
+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.
+
+1.6->2.0:
+ 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.
+ -#'((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 => print-first-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.
+2.8
+ \score{} must now begin with a music expression. Anything else
+ (particularly \header{}) must come after the music.
+@end verbatim
-@cindex regular line breaks
-@cindex four bar music.
+@node Reporting bugs
+@section Reporting bugs
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:
-@example
-<< \repeat unfold 7 @{
- s1 \noBreak s1 \noBreak
- s1 \noBreak s1 \break @}
- @emph{the real music}
->>
-@end example
+@cindex bugs
+@cindex reporting bugs
-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
+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,
-@refcommands
+@uref{http://code.google.com/p/lilypond/issues/list}
-@code{\break}, @code{\noBreak}
-@cindex @code{\break}
-@cindex @code{\noBreak}
+If you have discovered a bug which is not listed, please report the
+bug by following the directions on
-@seealso
+@uref{http://lilypond.org/web/devel/participating/bugs}
-Internals: @internalsref{BreakEvent}.
+Please construct submit @ruser{Minimal examples}, of bug reports. We do not
+have the resources to investigate reports which are not as small as possible.
-@node Page layout
-@subsection Page layout
+@node Error messages
+@section Error messages
-@cindex page breaks
-@cindex breaking pages
+@cindex error messages
+Different error messages can appear while compiling a file:
-@cindex @code{indent}
-@cindex @code{linewidth}
+@table @emph
+@cindex warning
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\paper} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
+@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.
-If @code{raggedright} is set to true in the @code{\paper}
-block, then the lines are justified at their natural length. This
-useful for short fragments, and for checking how tight the natural
-spacing is.
+@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 page layout
-@cindex vertical spacing
+@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.
-The page layout process happens outside the LilyPond formatting
-engine: variables controlling page layout are passed to the output,
-and are further interpreted by @code{lilypond} wrapper program. It
-responds to the following variables in the @code{\paper} block. The
-variable @code{textheight} sets the total height of the music on each
-page. The spacing between systems is controlled with
-@code{interscoreline}, its default is 16pt. The distance between the
-score lines will stretch in order to fill the full page
-@code{interscorelinefill} is set to a positive number. In that case
-@code{interscoreline} specifies the minimum spacing.
+@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 @code{textheight}
-@cindex @code{interscoreline}
-@cindex @code{interscorelinefill}
+@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.
-If the variable @code{lastpagefill} is defined,
-@c fixme: this should only be done if lastpagefill= #t
-systems are evenly distributed vertically on the last page. This
-might produce ugly results in case there are not enough systems on the
-last page. The @command{lilypond-book} command ignores
-@code{lastpagefill}. See @ref{lilypond-book manual} for more
-information.
+@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.
-@cindex @code{lastpagefill}
-Page breaks are normally computed by @TeX{}, so they are not under
-direct control of LilyPond. However, you can insert a commands into
-the @file{.tex} output to instruct @TeX{} where to break pages. This
-is done by setting the @code{between-systems-strings} on the
-@internalsref{NonMusicalPaperColumn} where the system is broken.
-An example is shown in @inputfileref{input/regression,between-systems.ly}.
-The predefined command @code{\newpage} also does this.
+@end table
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+@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
-To change the paper size, use the following Scheme code:
@example
- \paper@{
- #(set-paper-size "a4")
- @}
+@var{filename}:@var{lineno}:@var{columnno}: @var{message}
+@var{offending input line}
@end example
-
-@refcommands
-
-@cindex @code{\newpage}
-@code{\newpage}.
-
-
-@seealso
-
-In this manual: @ref{Invoking lilypond}.
-
-Examples: @inputfileref{input/regression,between-systems.ly}.
-
-Internals: @internalsref{NonMusicalPaperColumn}.
-
-@refbugs
-
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
-
-
-
-
-@node Sound
-@section Sound
-@cindex Sound
-
-Entered music can also be converted to MIDI output. The performance
-is good enough for proof-hearing the music for errors.
-
-Ties, dynamics and tempo changes are interpreted. Dynamic marks,
-crescendi and decrescendi translate into MIDI volume levels. Dynamic
-marks translate to a fixed fraction of the available MIDI volume
-range, crescendi and decrescendi make the volume vary linearly between
-their two extremities. The fractions can be adjusted by
-@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
-For each type of MIDI instrument, a volume range can be defined. This
-gives a basic equalizer control, which can enhance the quality of
-the MIDI output remarkably. The equalizer can be controlled by
-setting @code{instrumentEqualizer}.
-
-@refbugs
-
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to MIDI.
-
-Since slurs are not interpreted, @code{\lyricsto} and
-@code{\addlyrics} sections will be interpreted wrongly.
-
-The MIDI output allocates a channel for each Staff, and one for global
-settings. Hence, the MIDI file should not have more than 15 staves
-(or 14 if you do not use drums).
-
-
-@menu
-* MIDI block::
-* MIDI instrument names::
-@end menu
-
-
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
-
-
-The MIDI block is analogous to the paper block, but it is somewhat
-simpler. The @code{\midi} block can contain:
-@cindex MIDI block
-
-@itemize @bullet
- @item a @code{\tempo} definition, and
- @item context definitions.
-@end itemize
-
-Assignments in the @code{\midi} block are not allowed.
-
-A number followed by a period is interpreted as a real number, so
-for setting the tempo for dotted notes, an extra space should be
-inserted, for example:
+A line-break is inserted in the offending line to indicate the column
+where the error was found. For example,
@example
- \midi @{ \tempo 4 . = 120 @}
+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.
-@cindex context definition
-
-Context definitions follow precisely the same syntax as within the
-\paper block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
-
-
-@node MIDI instrument names
-@subsection MIDI instrument names
-
-@cindex instrument names
-@cindex @code{Staff.midiInstrument}
-
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property. The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
-
-@refbugs
-If the selected string does not exactly match, then the default is
-used, which is the Grand Piano.
projects / lilypond.git / blobdiff