@chapter Advanced Topics
-When translating the input to notation, there are number of distinct
-phases. We list them here:
+When LilyPond is run, it reads an input file. During parsing, Music
+objects are created. This music is interpreted, which is done by
+contexts, that produce graphical objects. This section discusses
+details of these three concepts, and how they are glued together with
+the embedded Scheme interpreter.
-@c todo: moved from refman.
-
-The purpose of LilyPond is explained informally by the term `music
-typesetter'. This is not a fully correct name: Not only does the
-program print musical symbols, it also makes aesthetic decisions.
-Symbols and their placements are @emph{generated} from a high-level
-musical description. In other words, LilyPond would be best described
-to be a `music compiler' or `music to notation compiler'.
-
-LilyPond is linked to GUILE, GNU's Scheme library for extension
-programming. The Scheme library provides the glue that holds together
-the low-level routines and separate modules which are written in C++.
-
-When lilypond is run to typeset sheet music, the following happens:
-
-@itemize @bullet
-@item GUILE initialization: Various scheme files are read.
-
-@item Parsing: First standard @code{ly} initialization files are read,
-then the user @file{ly} file is read.
-
-@item Interpretation: The music in the file is processed `in playing
-order', i.e., the order that you use to read sheet music, or the
-order in which notes are played. The result of this step is a
-typesetting specification.
-
-@item Typesetting: The typesetting specification is solved: positions
-and formatting is calculated.
-
-@item The visible results ("virtual ink") are written to the output file.
-@end itemize
-
-During these stages different types of data play the the main role:
-During parsing, @strong{Music} objects are created. During the
-interpretation, @strong{contexts} are constructed, and with these
-contexts a network of @strong{graphical objects} (`grobs') is
-created. These grobs contain unknown variables, and the network forms a
-set of equations. After solving the equations and filling in these
-variables, the printed output is written to an output file.
-
-These threemanship of tasks (parsing, translating, typesetting) and
-data-structures (music, context, graphical objects) permeates the entire
-design of the program.
-
-
-@table @b
-
-@item Parsing
-
-The @code{ly} file is read and converted to a list of @code{Scores}, which
-each contain @code{Music} and paper/midi-definitions. Here @code{Music},
-@code{Pitch}, and @code{Duration} objects are created.
-
-@item Interpreting music
-@cindex interpreting music
-
-All music events are `read' in the same order as they would be played
-(or read from paper). At every step of the interpretation, musical
-events are delivered to interpretation contexts,
-@cindex engraver
-which use them to build @code{Grob}s (or MIDI objects for MIDI output).
-
-In this stage @code{Music_iterators} do a traversal of the @code{Music}
-structure. The music events thus encountered are reported to
-@code{Translator}s, a set of objects that collectively form interpretation
-contexts.
-
-@item Prebreaking
-@cindex prebreaking
-
-At places where line breaks may occur, clefs and bars are prepared for
-a possible line break.
-
-@item Preprocessing
-@cindex preprocessing
-
-In this stage, all information that is needed to determine line breaking
-is computed.
-
-@item Break calculation
-
-The lines and horizontal positions of the columns are determined.
-
-@item Breaking
-
-Relations between all grobs are modified to reflect line breaks: When a
-spanner, e.g. a slur, crosses a line break, then the spanner is `broken
-into pieces'; for every line that the spanner is in, a copy of the grob
-is made. A substitution process redirects all grob references so that
-each spanner grob will only reference other grobs in the same line.
-
-@item Outputting
-
-All vertical dimensions and spanning objects are computed, and all grobs
-are output, line by line. The output is encoded in the form of
-@code{Molecule}s
-
-@end table
-
-The data types that are mentioned here are all discussed in this
-section.
-
-
-@c FIXME: Note entry vs Music entry at top level menu is confusing.
-@c . {Music entry}
@menu
* Interpretation context::
+* Scheme integration::
+* Music storage format::
* Syntactic details::
* Lexical details::
* Output details::
@end menu
-Interpretation contexts are objects that only exist during a run of
-LilyPond. During the interpretation phase of LilyPond (when it prints
-@code{interpreting music} to standard output), the music expression in
-a @code{\score} block is interpreted in time order. This is the same
-order that humans hear and play the music.
-
-During this interpretation, the interpretation context holds the
-state for the current point within the music. It contains information
-like
-
+Interpretation contexts are objects that only exist during program
+run. During the interpretation phase (when @code{interpreting music}
+is interpreted to standard output), the music expression in a
+@code{\score} block is interpreted in time order, the same order in
+which hear and play the music. During this phase, the interpretation
+context holds the state for the current point within the music, for example
@itemize @bullet
@item What notes are playing at this point?
@end example
@noindent
-This instructs lilypond to interpret @var{musicexpr} within the context
-of type @var{contexttype} and with name @var{contextname}. If this
-context does not exist, it will be created.
+This means that @var{musicexpr} should be interpreted within a context
+of type @var{contexttype} (with name @var{contextname} if specified).
+If no such context exists, it will be created.
@lilypond[verbatim,singleline]
\score {
@subsection Default contexts
Most music expressions do not need an explicit @code{\context}
-declaration: they inherit the notation context from their parent. Each
-note is a music expression, and as you can see in the following example,
-only the sequential music enclosing the three notes has an explicit context.
+declaration: they inherit the notation context from their parent. In
+the following example, only the sequential expression has an explicit
+context. The notes contained therein inherit the @code{goUp} context
+from the enclosing music expression.
@lilypond[verbatim,singleline]
-\score { \notes \context Voice = goUp { c'4 d' e' } }
+ \notes \context Voice = goUp { c'4 d' e' }
@end lilypond
There are some quirks that you must keep in mind when dealing with
music expressions. Consider the following example.
@lilypond[verbatim, singleline]
-\score { \context Score \notes { c'4-( d' e'-) } }
+ \score { \notes { c'4-( d' e'-) } }
@end lilypond
@noindent
@example
\applycontext
- #(lambda (tr)
+ #(lambda (x)
(format #t "\nWe were called in barnumber ~a.\n"
- (ly:get-context-property tr 'currentBarNumber)))
+ (ly:get-context-property x 'currentBarNumber)))
@end example
-
-
-
@node Context properties
@subsection Context properties
Notation contexts have properties. These properties are from
the @file{.ly} file using the following expression:
@cindex @code{\property}
+@cindex context properties
+@cindex properties, context
@example
\property @var{contextname}.@var{propname} = @var{value}
@end example
@noindent
-Sets the @var{propname} property of the context @var{contextname} to the
-specified Scheme expression @var{value}. All @var{propname} and
-@var{contextname} are strings, which are typically unquoted.
+Sets the @var{propname} property of the context @var{contextname} to
+the specified Scheme expression @var{value}. Both @var{propname} and
+@var{contextname} are strings, which can often be written unquoted.
+@cindex inheriting
Properties that are set in one context are inherited by all of the
contained contexts. This means that a property valid for the
@internalsref{Voice} context can be set in the @internalsref{Score} context
@end example
@noindent
-do the same thing.
-The main use for this is in macros -- allowing the specification of a
-property-setting without restriction to a specific context.
-
-Properties can be unset using the following expression:
+do the same thing. The main use for this is in predefined variables.
+This construction allows the specification of a property-setting
+without restriction to a specific context.
+Properties can be unset using the following statement.
@example
\property @var{contextname}.@var{propname} \unset
@end example
@node Engravers and performers
@subsection Engravers and performers
-[TODO]
-
-Basic building blocks of translation are called engravers; they are
-special C++ classes.
-
-
@node Changing context definitions
@subsection Changing context definitions
@cindex context definition
@end example
@noindent
-Then you can add and remove engravers using the following syntax:
+Every predefined context has a standard identifier. For example, the
+@code{Staff} context can be referred to as @code{\StaffContext}.
+@noindent
+The context can then be modified by setting or changing properties,
+e.g.
+@example
+\translator @{
+ \StaffContext
+ Stem \set #'thickness = #1.2
+ defaultBarType = #"||"
+@}
+@end example
+These assignments happen before interpretation starts, so a @code{\property}
+command will override any predefined settings.
+
+@cindex engraver
+
+@refbugs
+
+It is not possible to collect multiple property assignments in a
+variable, and apply to one @code{\translator} definition by
+referencing that variable.
+
+@node Defining new contexts
+@subsection Defining new contexts
+
+@cindex engraver
+@cindex plug-in
+
+Each context is composed of a number of building blocks, or plug-ins
+called engravers. An engraver is a specialized C++ class that is
+compiled into the executable. Typically, an engraver is responsible
+for one function: the @code{Slur_engraver} creates only @code{Slur}
+objects, and the @code{Skip_event_swallow_translator} only swallows
+(silently gobbles) @code{SkipEvent}s.
+
+An existing context definition can be changed by adding or removing an
+engraver. The syntax for these operations is
@example
-\remove @var{engravername}
\consists @var{engravername}
+\remove @var{engravername}
@end example
+@cindex \consists
+@cindex \remove
+
@noindent
Here @var{engravername} is a string, the name of an engraver in the
-system.
+system. In the following example, the @code{Clef_engraver} is removed
+from the Staff context. The result is a staff without a clef, where
+the central C is at its default position, the center line.
@lilypond[verbatim,singleline]
\score {
\notes {
- c'4 c'4
+ c'4 f'4
}
\paper {
\translator {
}
@end lilypond
-@cindex engraver
-
-You can also set properties in a translator definition. The syntax is as
-follows:
-
-@example
-@var{propname} = @var{value}
-@var{propname} \set @var{grob-propname} = @var{pvalue}
-@var{propname} \override @var{grob-propname} = @var{pvalue}
-@var{propname} \revert @var{grob-propname}
-@end example
-
-@noindent
-@var{propname} is a string, @var{grob-propname} a symbol, @var{value}
-and @code{pvalue} are Scheme expressions. These types of property
-assignments happen before interpretation starts, so a @code{\property}
-command will override any predefined settings.
-
-To simplify editing translators, all standard contexts have standard
-identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
-@code{VoiceContext}; see @file{ly/engraver-init.ly}.
-
-
-@node Defining new contexts
-@subsection Defining new contexts
-
-If you want to build a context from scratch, you must also supply the
-following extra information:
-
-@itemize @bullet
-@item A name, specified by @code{\name @var{contextname}}.
-
-@item A cooperation module. This is specified by @code{\type
-@var{typename}}.
-@end itemize
+A list of all engravers is in the internal documentation,
+@internalsref{All engravers}.
-This is an example:
+It is also possible to define new contexts from scratch. To do this,
+you must define give the new context a name. In the following
+example, a very simple Staff context is created: one that will put
+note heads on a staff symbol.
@example
\translator @code{
@noindent
The argument of @code{\type} is the name for a special engraver that
handles cooperation between simple engravers such as
-@code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
-for this engraver are the following:
-
-@table @code
-@cindex @code{Engraver_group_engraver}
-
-@item @code{Engraver_group_engraver}
-The standard cooperation engraver.
-
-@cindex @code{Score_engraver}
-@item @code{Score_engraver}
-This is a cooperation module that should be in the top level context.
-@end table
-
-Other modifiers are
+@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
+should always be @code{Engraver_group_engraver} (unless you are
+defining a Score context from scratch, in which case
+@code{Score_engraver} must be used).
+The complete list of context modifiers is as follows:
@itemize @bullet
@item @code{\alias} @var{alternate-name}:
This specifies a different name. In the above example,
@var{engravername} is always added to the end of the list of
engravers.
-Some engraver types need to be at the end of the list; this
-insures they stay there even if a user adds or removes engravers.
-End-users generally do not need this command.
+Engravers that group context objects into axis groups or alignments
+need to be at the end of the list. @code{\consistsend} insures that
+engravers stay at the end even if a user adds or removes engravers.
@item @code{\accepts} @var{contextname}:
-Add @var{contextname} to the list of contexts this context can
-contain in the context hierarchy. The first listed context is the
-context to create by default.
+This context can contains @var{contextname} contexts. The first
+@code{\accepts} is created as a default context when events (eg. notes
+or rests) are encountered.
@item @code{\denies}:
-The opposite of @code{\accepts}. Added for
-completeness, but is never used in practice.
+The opposite of @code{\accepts}.
@item @code{\name} @var{contextname}:
-This sets the type name of the context, e.g. @internalsref{Staff},
-@internalsref{Voice}. If the name is not specified, the translator will not do
-anything.
+This sets the type name of the context, e.g. @code{Staff},
+@code{Voice}. If the name is not specified, the translator will not
+do anything.
@end itemize
-In the @code{\paper} block, it is also possible to define translator
-identifiers. Like other block identifiers, the identifier can only
-be used as the very first item of a translator. In order to define
-such an identifier outside of @code{\score}, you must do
-@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
+@node Scheme integration
+@section Scheme integration
+
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+@cindex accessing Scheme
+@cindex evaluating Scheme
+@cindex LISP
-@cindex paper types, engravers, and pre-defined translators
+LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
+language from the LISP family. You can learn more about Scheme at
+@uref{http://www.scheme.org}. It is used to represent data throughout
+the whole program.
+
+In some places of the input file, Scheme expressions also form valid
+syntax: wherever it is allowed, GUILE can be accessed directly by
+entering a hash-sign (@code{#}). The expression following the
+hash-sign is evaluated as Scheme. For example, the boolean value @var{true} is
+@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
+and can be used in property assignments:
+@example
+ \property Staff.autoBeaming = ##f
+@end example
+
+Scheme is a full-blown programming language, and a full discussion is
+outside the scope of this document. Interested readers are referred to
+the website @uref{http://www.schemers.org/} for more information on
+Scheme.
-
-@node Syntactic details
-@section Syntactic details
-@cindex Syntactic details
-This section describes details that were too boring to be put elsewhere.
@menu
-* Identifiers::
-* Music expressions::
-* Manipulating music expressions::
+* Input variables and Scheme::
+* Scheme datatypes::
* Assignments::
-* Lexical modes::
-* Ambiguities::
@end menu
-@c . {Identifiers}
-@node Identifiers
-@subsection Identifiers
-@cindex Identifiers
+@node Input variables and Scheme
+@subsection Input variables and Scheme
-@ignore
-What has this section got to do with identifiers?
-It seems more appropriate in the introduction to Chapter 4,
-"Internals".
- /MB
-@end ignore
+The input format supports the notion of variable: in the following
+example, a music expression is assigned to a variable with the name
+@code{traLaLa}.
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+@end example
-All of the information in a LilyPond input file is internally
-represented as a Scheme value. In addition to normal Scheme data types
-(such as pair, number, boolean, etc.), LilyPond has a number of
-specialized data types,
+@noindent
+
+There is also a form of scoping: in the following example, the
+@code{\paper} block also contains a @code{traLaLa} variable, which is
+independent of the outer \traLaLa.
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+ \paper @{ traLaLa = 1.0 @}
+@end example
+@c
+In effect, each input file is a scope, and all @code{\header},
+@code{\midi} and @code{\paper} blocks are scopes nested inside that
+toplevel scope.
+
+Both variables and scoping are implemented in the GUILE module system.
+A anonymous Scheme module is attached to each scope. An assignment of
+the form
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+@end example
+
+@noindent
+is internally converted to a Scheme definition
+@example
+ (define traLaLa @var{Scheme value of @code{\notes ... }})
+@end example
+This means that input variables and Scheme variables may be freely
+mixed. In the following example, a music fragment is stored in the
+variable @code{traLaLa}, and duplicated using Scheme. The result is
+imported in a @code{\score} by means of a second variable
+@code{twice}
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+
+ #(define newLa (map ly:music-deep-copy
+ (list traLaLa traLaLa)))
+ #(define twice
+ (make-sequential-music newLa))
+
+ \score @{ \twice @}
+@end example
+
+In the above example, music expressions can be `exported' from the
+input to the Scheme interpreter. The opposite is also possible. By
+wrapping a Scheme value in the function @code{ly:export}, a Scheme
+value is interpreted as if it were entered in LilyPond syntax: instead
+of defining @code{\twice}, the example above could also have been
+written as
+@example
+ @dots{}
+ \score @{ #(ly:export (make-sequential-music newLa)) @}
+@end example
+
+
+
+
+
+@node Scheme datatypes
+@subsection Scheme datatypes
+
+Scheme is used to glue together different program modules. To aid this
+glue function, many lilypond specific object types can be passed as
+Scheme value.
+
+The following list are all lilypond specific types, that
+can exist during parsing:
@itemize @bullet
+@item Duration
+@item Identifier
@item Input
-@item c++-function
+@item Moment
@item Music
-@item Identifier
-@item Translator_def
-@item Duration
+@item Music_output_def
@item Pitch
@item Score
-@item Music_output_def
-@item Moment (rational number)
+@item Translator_def
@end itemize
-LilyPond also includes some transient object types. Objects of these
-types are built during a LilyPond run, and do not `exist' per se within
-your input file. These objects are created as a result of your input
-file, so you can include commands in the input to manipulate them,
-during a LilyPond run.
+
+During a run, transient objects are also created and destroyed.
@itemize @bullet
@item Grob: short for `Graphical object'.
+@item Scheme_hash_table
+@item Music_iterator
@item Molecule: Device-independent page output object,
-including dimensions. Produced by some Grob functions.
+including dimensions.
+
+@item Syllable_group
+
+@item Spring_smob
@item Translator: An object that produces audio objects or Grobs. This is
not yet user-accessible.
@item Font_metric: An object representing a font.
@end itemize
+Many functions are defined to manipulate these data structures. They
+are all listed and documented in @internalsref{All scheme functions}.
+
+@c . {Assignments}
+@node Assignments
+@subsection Assignments
+@cindex Assignments
+
+Identifiers allow objects to be assigned to names during the parse
+stage. To assign an identifier, use @var{name}@code{=}@var{value}.
+To refer to an identifier, precede its name with a backslash:
+`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
+the input-types listed above. Identifier assignments can appear at top
+level in the LilyPond file, but also in @code{\paper} blocks.
+
+An identifier can be created with any string for its name, but you will
+only be able to refer to identifiers whose names begin with a letter,
+being entirely alphabetical. It is impossible to refer to an identifier
+whose name is the same as the name of a keyword.
+
+The right hand side of an identifier assignment is parsed completely
+before the assignment is done, so it is allowed to redefine an
+identifier in terms of its old value, e.g.
+
+@example
+foo = \foo * 2.0
+@end example
+
+When an identifier is referenced, the information it points to is
+copied. For this reason, an identifier reference must always be the
+first item in a block.
+
+@example
+\paper @{
+ foo = 1.0
+ \paperIdent % wrong and invalid
+@}
+@end example
+
+@example
+\paper @{
+ \paperIdent % correct
+ foo = 1.0
+@}
+@end example
+
+
+
+@node Music storage format
+@section Music storage format
+
+@menu
+* Music expressions::
+* Manipulating music expressions::
+@end menu
@node Music expressions
@subsection Music expressions
< { a b c' } { c' d' e' } >
}
@end lilypond
-However, using @code{<} and @code{>} for chords turns up various
-syntactical peculiarities. For this reason, a special syntax for
-chords was introduced in version 1.7: @code{<< >>}.
+However, using @code{<} and @code{>} for entering chords leads to
+various peculiarities. For this reason, a special syntax
+for chords was introduced in version 1.7: @code{<< >>}.
@lilypond[verbatim,singleline]
#(define (testfunc x)
- (if (equal? (ly:get-mus-property x 'text) "foo")
- (ly:set-mus-property! x 'text "bar"))
+ (if (equal? (ly:get-mus-property x 'text) (make-simple-markup "foo"))
+ (ly:set-mus-property! x 'text (make-simple-markup "bar")))
;; recurse
(ly:set-mus-property! x 'elements
(map testfunc (ly:get-mus-property x 'elements)))
}
@end lilypond
-For more information on what is possible, see the automatically
-generated documentation.
-
-Directly accessing internal representations is dangerous: The
-implementation is subject to changes, so you should avoid this feature
-if possible.
-
A final example is a function that reverses a piece of music in time:
@lilypond[verbatim,singleline]
}
@end lilypond
+@seealso
+
More examples are given in the distributed example files in
@code{input/test/}.
-@c . {Assignments}
-@node Assignments
-@subsection Assignments
-@cindex Assignments
-
-Identifiers allow objects to be assigned to names during the parse
-stage. To assign an identifier, use @var{name}@code{=}@var{value}.
-To refer to an identifier, precede its name with a backslash:
-`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
-the input-types listed above. Identifier assignments can appear at top
-level in the LilyPond file, but also in @code{\paper} blocks.
-An identifier can be created with any string for its name, but you will
-only be able to refer to identifiers whose names begin with a letter,
-being entirely alphabetical. It is impossible to refer to an identifier
-whose name is the same as the name of a keyword.
+@refbugs
-The right hand side of an identifier assignment is parsed completely
-before the assignment is done, so it is allowed to redefine an
-identifier in terms of its old value, e.g.
+Directly accessing internal representations is dangerous: The
+implementation is subject to changes, so you should avoid this feature
+if possible.
-@example
-foo = \foo * 2.0
-@end example
-When an identifier is referenced, the information it points to is
-copied. For this reason, an identifier reference must always be the
-first item in a block.
+@node Syntactic details
+@section Syntactic details
+@cindex Syntactic details
-@example
-\paper @{
- foo = 1.0
- \paperIdent % wrong and invalid
-@}
-@end example
+This section describes details that were too boring to be put elsewhere.
-@example
-\paper @{
- \paperIdent % correct
- foo = 1.0
-@}
-@end example
+@menu
+* Lexical modes::
+* Ambiguities::
+@end menu
@c . {Lexical modes}
@code{\notes} @var{musicexpr}
@code{\chords} @var{musicexpr}
@code{\lyrics} @var{musicexpr}
+@code{\figures} @var{musicexpr}
+@code{\markup} @var{markupexpr}
@end example
@noindent
meaning of their arguments. They just instruct the parser in what mode
to parse their arguments.
-Different input modes may be nested.
+Different input modes for music expressions may be nested.
@c . {Ambiguities}
@cindex ambiguities
@cindex grammar
-The grammar contains a number of ambiguities. We hope to resolve them at
-some time.
+The grammar contains two ambiguities.
@itemize @bullet
@item The assignment
@node Lexical details
@section Lexical details
-Even more boring details, now on the lexical side of the input parser.
-
@menu
-* Direct Scheme::
-* Reals::
* Strings::
@end menu
-
-@node Direct Scheme
-@subsection Direct Scheme
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
-language from the LISP family. You can learn more about Scheme at
-@uref{http://www.scheme.org}. It is used to represent data throughout
-the whole program. The hash-sign (@code{#}) accesses GUILE directly: The
-code following the hash-sign is evaluated as Scheme. The boolean value
-@var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
-@code{##t}.
-
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. In some places, Scheme expressions also form valid syntax:
-Wherever it is allowed,
-
-@example
-#@var{scheme}
-@end example
-
-@noindent
-evaluates the specified Scheme code. Example:
-
-@example
-\property Staff.TestObject \override #'foobar = #(+ 1 2)
-@end example
-
-@code{\override} expects two Scheme expressions.
-The first one is a symbol (@code{foobar}), the second one
-an integer (namely, 3).
-
-In-line Scheme may be used at the top level. In this case the result is
-discarded.
-
-Scheme is a full-blown programming language, and a full discussion is
-outside the scope of this document. Interested readers are referred to
-the website @uref{http://www.schemers.org/} for more information on
-Scheme.
-
-
-@node Reals
-@subsection Reals
-@cindex real numbers
-
-Formed from an optional minus sign and a sequence of digits followed
-by a @emph{required} decimal point and an optional exponent such as
-@code{-1.2e3}. Reals can be built up using the usual operations:
-`@code{+}', `@code{-}', `@code{*}', and
-`@code{/}', with parentheses for grouping.
-
-@cindex @code{\mm}
-@cindex @code{\in}
-@cindex @code{\cm}
-@cindex @code{\pt}
-@cindex dimensions
-
-A real constant can be followed by one of the dimension keywords:
-@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
-points, inches and centimeters, respectively. This converts the number
-that is the internal representation of that dimension.
-
-
@node Strings
@subsection Strings
@cindex string
After the last system LilyPond emits a stronger variant of
-@code{\interscoreline} only if the macro @code{\lilypondpaperlastpagefill}
-is not defined (flushing the systems to the top of the page). You can
-avoid that manually by saying
-
-@example
-\def\lilypondpaperlastpagefill@{1@}
-@end example
-
-@noindent
-or by setting the variable @code{lastpagefill} in LilyPond's @code{\paper}
-block.
+@code{\interscoreline} only if the macro
+@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
+to the top of the page). You can avoid that by setting the variable
+@code{lastpagefill} in LilyPond's @code{\paper} block.
It is possible to fine-tune the vertical offset further by defining the
macro @code{\lilypondscoreshift}. Example:
@noindent
@code{\baselineskip} is the distance from one text line to the next.
-The code produced by LilyPond can be used by both @TeX{} and La@TeX{}.
+The code produced by LilyPond should be run through La@TeX{}, not
+plain @TeX{}.
Here an example how to embed a small LilyPond file @code{foo.ly} into
running La@TeX{} text without using the @code{lilypond-book} script
@subsection Non-guitar tablatures
@cindex Non-guitar tablatures
- You can change the number of strings, by setting the number of lines
+You can change the number of strings, by setting the number of lines
in the @internalsref{TabStaff} (the @code{line-count} property of
@internalsref{TabStaff} can only be changed using
-@code{\outputproperty}, for more information, see @ref{Tuning
-objects}.
+@code{\outputproperty}, for more information, see @ref{Tuning objects}.
You can change the tuning of the strings. A string tuning is given as
a Scheme list with one integer number for each string, the number
@node Ancient clefs
@subsection Ancient clefs
+[TODO: condense clef lists in a convenient chart]
+
LilyPond supports a variety of clefs, many of them ancient.
For modern clefs, see section @ref{Clef}. For the percussion clef, see
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 a certain type of object, thus
+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 object property in that object.
@cindex kerning
-LilyPond does not account for kerning in its text formatting, so it
-spaces texts slightly too wide.
+
+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.
@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
+line breaks and the spacing. These all influence each other. The
choice of spacing determines how densely each system of music is set,
-where line breaks breaks are chosen, and thus ultimately how many
-pages a piece of music takes. In this section we will explain how the
-lilypond spacing engine works, and how you can tune its results.
+which influences where line breaks breaks are chosen, and thus
+ultimately how many pages a piece of music takes. In this section we
+will explain how the lilypond spacing engine works, and how you can
+tune its results.
Globally spoken, this procedure happens in three steps: first,
flexible distances (``springs'') are chosen, based on durations. All
is processed by @TeX{}, page are filled with systems, and page breaks
are chosen whenever the page gets full.
+
+
@menu
* Vertical spacing::
* Horizontal spacing::
This sets the vertical size of the current staff to 4 staff-space 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. you
-could also make the staff larger at the bottom by setting it to
-@code{(-6 . 4)}. The default value is @code{(-6 . 6)}.
-
-Vertical aligment of staves is handled by the
-@internalsref{VerticalAlignment} object, which lives at
-@internalsref{Score} level.
+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 necessary that the distance between staves
is fixed. This is also done with a @internalsref{VerticalAlignment}
-object, created in @internalsref{PianoStaff}, but a forced distance is
-set. This is done with the object property #'forced-distance. If you
-want to override this, use a @code{\translator} block as follows:
+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
\translator @{
\PianoStaffContext
@}
@end example
This would bring the staves together at a distance of 9 staff spaces,
-and again this is measured from the center line of each staff.
+measured from the center line of each staff.
+
+@seealso
+
+Vertical aligment of staves is handled by the
+@internalsref{VerticalAlignment} object.
The spacing engine translates differences in durations into
stretchable distances (``springs'') of differing lengths. Longer
-durations get more space, shorter durations get less. The basis for
-assigning spaces to durations, is that the shortest durations get a
-fixed amount of space, and the longer durations get more: doubling a
-duration adds a fixed amount of space to the note.
+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. The 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
+8th notes, the eighth note is followed by 1 note head width (NHW). The
+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
-These two amounts of space are @code{shortest-duration-space}
-@code{spacing-increment}, object properties of
-@internalsref{SpacingSpanner}. Normally @code{spacing-increment} 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 noteheads of space. For normal notes, this space
-is always counted from the left edge of the symbol, so the short notes
-in a score is generally followed by one note head width of space.
+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 (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 64th,
+entire score a lot. The shortest note is no longer a 16th, but a 32nd,
thus adding 2 noteheads of space 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
only a few 16th notes to the example above, they would be followed by
half a NHW:
-@lilypond[fragment, verbatim, relative=1]
+@lilypond[fragment, verbatim, relative=2]
c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4
@end lilypond
@cindex @code{spacing}
In the introduction it was explained that stem directions influence
-spacing. This is controlled with @code{stem-spacing-correction} in
-@internalsref{NoteSpacing}. The @code{StaffSpacing} object contains the
-same property for controlling the stem/barline spacing. In the
-following example shows these corrections, once with default settings,
-and once with exaggerated corrections.
+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/barline spacing. In the following example
+shows these corrections, once with default settings, and once with
+exaggerated corrections.
@lilypond
\score { \notes {
@cindex SpacingSpanner, overriding properties
-The @internalsref{SpacingSpanner}, is score wide, so its properties
-must be overriden from the @code{\paper} block, e.g.
+Properties of the @internalsref{SpacingSpanner} must be overriden
+from the @code{\paper} block, since the @internalsref{SpacingSpanner}
+is created before any @code{\property} statements are interpreted.
@example
\paper @{ \translator @{
\ScoreContext
score, the part containing the longer durations will be spaced too
widely.
-Generating optically pleasing spacing is black magic. LilyPond tries
-to deal with a number of frequent cases. Here is an example that is
-not handled correctly, due to the combination of chord collisions and
-kneed stems.
-
-@lilypond
-\score {
- \context PianoStaff \notes \transpose c c'' <
- \context Staff = up { s1 }
- \context Staff = down { [c8 c \translator Staff=up <<c d>> c
-\translator Staff=down c c c] }
- >
- \paper { raggedright = ##t }
-}
-@end lilypond
-
+There is no convenient mechanism to manually override spacing.
@cindex breaking lines
Line breaks are normally computed automatically. They are chosen such
-that it looks neither cramped nor loose, and that consecutive lines have
-similar density.
+that lines look neither cramped nor loose, and that consecutive lines
+have similar density.
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 certain
+""}. Similarly, @code{\noBreak} forbids a line break at a
point.
If you want linebreaks at regular intervals, you can use the following:
@example
< \repeat 7 unfold @{ s1 * 4 \break @}
- @emph{real music}
+ @emph{the real music}
>
@end example
This makes the following 28 measures (assuming 4/4 time) be broken every
@cindex page layout
@cindex vertical spacing
-The page layout process happens outside lilypond. Ly2dvi sets page
-layout instructions. Ly2dvi 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 page layout process happens outside lilypond: variables
+controlling page layout are passed to the output, and are further
+interpreted by @code{ly2dvi}. @code{ly2dvi} 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 @code{interscoreline}
@cindex @code{interscorelinefill}
-If the variable @code{lastpagefill} is defined (that is, it gets any
-value assigned in the @code{\paper} block), 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. Note
-that @command{lilypond-book} ignores @code{lastpagefill}. See
-@ref{Integrating text and music with lilypond-book} for
-more information.
+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. Note that @command{lilypond-book} ignores
+@code{lastpagefill}. See @ref{Integrating text and music with
+lilypond-book} for more information.
@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. You
-can insert a @code{\newpage} from within lilypond. This is done by
-setting the @code{between-systems-strings} on the
+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}.
@cindex paper size
@cindex page size
Lilypond and @code{ly2dvi})
+@seealso
+
+@ref{Invoking ly2dvi},
+@inputfileref{input/regression,between-systems.ly},
+@internalsref{NonMusicalPaperColumn}.
+
+@refbugs
+
+There is no concept of page breaking, which makes it difficult to
+choose sensible page breaks in multi-page pieces.
+
@section Sound
@cindex Sound
-LilyPond can produce MIDI output. The performance lacks lots of
-interesting effects, such as swing, articulation, slurring, etc., but it
-is good enough for proof-hearing the music you have entered. Ties,
-dynamics and tempo changes are interpreted.
+Entered music can also be converted to MIDI output. The performance
+is good enough for proof-hearing the music for errors.
-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 the volume vary
-linearly between their two extremities. The fractions be adjusted by
-overriding the @code{absolute-volume-alist} defined in
-@file{scm/midi.scm}.
+
+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 the volume vary linearly
+between their two extremities. The fractions be adjusted by
+@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
For each type of musical instrument (that MIDI supports), a volume range
can be defined. This gives you basic equalizer control, which can
-enhance the quality of the MIDI output remarkably. You can add
-instruments and ranges or change the default settings by overriding the
-@code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
+enhance the quality of the MIDI output remarkably. The equalizer
+can be controlled by setting @code{instrumentEqualizer}.
Both loudness controls are combined to produce the final MIDI volume.
+@refbugs
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are translated to MIDI.
+
+
@menu
* MIDI block::
* MIDI instrument names::
projects / lilypond.git / commitdiff