X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=34eca21c202eb9af69c60b9a7938fe159cbb9f80;hb=eb452cb7c7e6c35b8d60700fca2f9de69822a4a9;hp=e0395c30afa020eb7f7f25016607d00b15156c28;hpb=969b3b0a27bbdaa721cb6b78a9ce82a9b0300277;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index e0395c30af..34eca21c20 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -1,1484 +1,636 @@ -@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.