@c before saving changes
-@node Advanced Topics
-@chapter Advanced Topics
+@node Technical manual
+@chapter Technical manual
-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 which is parsed. 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
-by `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, and
-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 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-reference 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::
-* Syntactic details::
+* Scheme integration::
+* Music storage format::
* Lexical details::
+* Output details::
@end menu
* Creating contexts::
* Default contexts::
* Context properties::
+* Context evaluation::
+* Defining contexts::
* Engravers and performers::
-* Changing context definitions::
* Defining new contexts::
@end menu
-Interpretation contexts are objects that only exist during a run of
-LilyPond. During the interpretation phase of LilyPond (when it prints
-"interpreting music"), 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.
+Interpretation contexts are objects that only exist during program
+run. During the interpretation phase (when @code{interpreting music}
+is printed on the standard output), the music expression in a
+@code{\score} block is interpreted in time order, the same order in
+which we 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?
-During this interpretation, the interpretation context holds the
-state for the current point within the music. It contains information
-like
+@item What symbols will be printed at this point?
-@itemize @bullet
- @item What notes are playing at this point?
- @item What symbols will be printed at this point?
- @item What is the current key signature, time signature, point within
- the measure, etc.?
+@item What is the current key signature, time signature, point within
+the measure, etc.?
@end itemize
Contexts are grouped hierarchically: A @internalsref{Voice} context is
contained in a @internalsref{Staff} context (because a staff can contain
multiple voices at any point), a @internalsref{Staff} context is contained in
-@internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
+@internalsref{Score}, @internalsref{StaffGroup}, or
+@internalsref{ChoirStaff} context.
Contexts associated with sheet music output are called @emph{notation
contexts}, those for sound output are called @emph{performance
-contexts}. The default definitions of the standard notation and
+contexts}. The default definitions of the standard notation and
performance contexts can be found in @file{ly/engraver-init.ly} and
@file{ly/performer-init.ly}, respectively.
+
@node Creating contexts
@subsection Creating contexts
-
@cindex @code{\context}
@cindex context selection
Contexts for a music expression can be selected manually, using the
-following music expression.
+following music expression:
@example
- \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
@end example
-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.
+@noindent
+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 {
c4 <d4 \context Staff = "another" e4> f
}
}
-
@end lilypond
-In this example, the @code{c} and @code{d} are printed on the
-default staff. For the @code{e}, a context Staff called
-@code{another} is specified; since that does not exist, a new
-context is created. Within @code{another}, a (default) Voice context
-is created for the @code{e4}. When all music referring to a
-context is finished, the context is ended as well. So after the
-third quarter, @code{another} is removed.
-
+@noindent
+In this example, the @code{c} and @code{d} are printed on the default
+staff. For the @code{e}, a context @code{Staff} called @code{another}
+is specified; since that does not exist, a new context is created.
+Within @code{another}, a (default) Voice context is created for the
+@code{e4}. A context is ended when when all music referring it has
+finished, so after the third quarter, @code{another} is removed.
@node Default contexts
@subsection Default contexts
-Most music expressions don't 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.
-
-@lilypond[verbatim,singleline]
-\score { \notes \context Voice = goUp { c'4 d' e' } }
-@end lilypond
-
-There are some quirks that you must keep in mind when dealing with
-defaults:
+Every top level music is interpreted by the @code{Score} context; in
+other words, you may think of @code{\score} working like
-First, every top level music is interpreted by the Score context, in other
-words, you may think of @code{\score} working like
@example
- \score @{
- \context Score @var{music}
- @}
+\score @{
+ \context Score @var{music}
+@}
@end example
-Second, contexts are created automatically to be able to interpret the
-music expressions. Consider the following example.
+Music expressions inherit their context from the enclosing music
+expression. Hence, it is not necessary to explicitly specify
+@code{\context} for most expressions. 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 { \context Score \notes { c'4 ( d' )e' } }
+@lilypond[verbatim,singleline]
+ \notes \context Voice = goUp { c'4 d' e' }
@end lilypond
-The sequential music is interpreted by the Score context initially
-(notice that the @code{\context} specification is redundant), but when a
-note is encountered, contexts are setup to accept that note. In this
-case, a Thread, Voice and Staff are created. The rest of the sequential
-music is also interpreted with the same Thread, Voice and Staff context,
-putting the notes on the same staff, in the same voice.
-This is a convenient mechanism, but do not expect opening chords to work
-without @code{\context}. For every note, a separate staff is
-instantiated.
-
-@cindex explicit context
-@cindex starting with chords
-@cindex chords, starting with
+Second, contexts are created automatically to be able to interpret the
+music expressions. Consider the following example:
@lilypond[verbatim, singleline]
-\score { \notes <c'4 es'> }
-@end lilypond
-
-Of course, if the chord is preceded by a normal note in sequential
-music, the chord will be interpreted by the Thread of the preceding
-note:
-@lilypond[verbatim,singleline]
-\score { \notes { c'4 <c'4 es'> } }
+ \score { \notes { c'4-( d' e'-) } }
@end lilypond
-
+@noindent
+The sequential music is interpreted by the Score context initially,
+but when a note is encountered, contexts are setup to accept that
+note. In this case, a @code{Thread}, @code{Voice}, and @code{Staff}
+context are created. The rest of the sequential music is also
+interpreted with the same @code{Thread}, @code{Voice}, and
+@code{Staff} context, putting the notes on the same staff, in the same
+voice.
@node Context properties
@subsection Context properties
-Notation contexts have properties. These properties are from
-the @file{.ly} file using the following expression:
+Contexts have properties. These properties are set 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}
+\property @var{contextname}.@var{propname} = @var{value}
@end example
-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.
+@noindent
+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 (for
-example) and thus take effect in all @internalsref{Voice} contexts.
+@internalsref{Voice} context can be set in the @internalsref{Score} context
+(for example) and thus take effect in all @internalsref{Voice} contexts.
@cindex @code{Current}
-If you don't wish to specify the name of the context in the
-@code{\property}-expression
-itself, you can refer to the abstract context name,
-@code{Current}. The @code{Current} context is the latest
-used context. This will typically mean the @internalsref{Thread}
-context, but you can force another context with the
-@code{\property}-command. Hence the expressions
+If you do not wish to specify the name of the context in the
+@code{\property}-expression itself, you can refer to the abstract context
+name, @code{Current}. The @code{Current} context is the latest
+used context. This will typically mean the @internalsref{Thread} context,
+but you can force another context with the
+@code{\property}-command. Hence the expressions
@example
- \property @var{contextname}.@var{propname} = @var{value}
+\property @var{contextname}.@var{propname} = @var{value}
@end example
+@noindent
and
@example
- \context @var{contextname}
- \property Current.@var{propname} = @var{value}
+\context @var{contextname}
+\property Current.@var{propname} = @var{value}
@end example
-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.
+@noindent
+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 expression:
+Properties can be unset using the following statement.
@example
- \property @var{contextname}.@var{propname} \unset
+\property @var{contextname}.@var{propname} \unset
@end example
@cindex properties, unsetting
@cindex @code{\unset}
-This removes the definition of @var{propname} in @var{contextname}. If
+@noindent
+This removes the definition of @var{propname} in @var{contextname}. If
@var{propname} was not defined in @var{contextname} (but was inherited
from a higher context), then this has no effect.
-
@refbugs
The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
the inverse of @code{\property \set}.
-@node Engravers and performers
-@subsection Engravers and performers
-[TODO]
+@node Context evaluation
+@subsection Context evaluation
-Basic building blocks of translation are called engravers; they are
-special C++ classes.
+Contexts can be modified during interpretation with Scheme code. The
+syntax for this is
+@example
+ \applycontext @var{function}
+@end example
+
+@var{function} should be a Scheme function taking a single argument,
+being the context to apply it to. The following code will print the
+current bar number on the standard output during the compile:
+
+@example
+ \applycontext
+ #(lambda (x)
+ (format #t "\nWe were called in barnumber ~a.\n"
+ (ly:get-context-property x 'currentBarNumber)))
+@end example
-@node Changing context definitions
-@subsection Changing context definitions
+@node Defining contexts
+@subsection Defining contexts
@cindex context definition
@cindex translator definition
-The most common way to define a context is by extending an existing
-context. You can change an existing context from the paper block, by
-first initializing a translator with an existing context identifier:
+The most common way to create a new context definition is by extending
+an existing one. An existing context from the paper block is copied
+by referencing a context identifier:
+
@example
\paper @{
\translator @{
@var{context-identifier}
- @} @}
+ @}
+@}
@end example
-Then you can add and remove engravers using the following syntax:
+
+@noindent
+Every predefined context has a standard identifier. For example, the
+@code{Staff} context can be referred to as @code{\StaffContext}.
+
+The context can then be modified by setting or changing properties,
+e.g.
@example
- \remove @var{engravername}
- \consists @var{engravername}
+\translator @{
+ \StaffContext
+ Stem \set #'thickness = #2.0
+ defaultBarType = #"||"
+@}
@end example
+These assignments happen before interpretation starts, so a @code{\property}
+command will override any predefined settings.
+@cindex engraver
-Here @var{engravername} is a string, the name of an engraver in the
-system.
+@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 Engravers and performers
+@subsection Engravers and performers
+
+
+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.
-@lilypond[verbatim,singleline]
-\score { \notes {
- c'4 c'4 }
- \paper {
- \translator { \StaffContext
- \remove Clef_engraver
- } } }
-@end lilypond
@cindex engraver
+@cindex plug-in
-You can also set properties in a translator definition. The syntax is as
-follows:
+An existing context definition can be changed by adding or removing an
+engraver. The syntax for these operations is
@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}
+\consists @var{engravername}
+\remove @var{engravername}
@end example
-@var{propname} is a string, @var{grob-propname} a symbol, @var{value}
-and @code{pvalue} are Scheme expressions. These type of property
-assignments happen before interpretation starts, so a @code{\property}
-command will override any predefined settings.
+@cindex \consists
+@cindex \remove
+
+@noindent
+Here @var{engravername} is a string, the name of an engraver in the
+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 f'4
+ }
+ \paper {
+ \translator {
+ \StaffContext
+ \remove Clef_engraver
+ }
+ }
+}
+@end lilypond
- 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}.
+A list of all engravers is in the internal documentation,
+see @internalsref{All engravers}.
@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
+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.
-This is an example:
@example
-\translator @code{
+\translator @{
\type "Engraver_group_engraver"
\name "SimpleStaff"
\alias "Staff"
\consists "Staff_symbol_engraver"
\consists "Note_head_engraver"
\consistsend "Axis_group_engraver"
-}@
+@}
@end example
+@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 cooperation module that should be in the top level context,
-and only 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 the following:
@itemize @bullet
- @item @code{\alias} @var{alternate-name}
- This specifies a different name. In the above example,
-@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
-
- @item @code{\consistsend} @var{engravername}
- Analogous to @code{\consists}, but makes sure that
- @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 don't need this command.
+@item @code{\alias} @var{alternate-name}:
+This specifies a different name. In the above example,
+@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s.
+
+@item @code{\consistsend} @var{engravername}:
+Analogous to @code{\consists}, but makes sure that
+@var{engravername} is always added to the end of the list of
+engravers.
+
+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.
-
- @item @code{\denies}. The opposite of @code{\accepts}. Added for
-completeness, but is never used in practice.
-
-
- @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 won't do
- anything.
+@item @code{\accepts} @var{contextname}:
+This context can contains @var{contextname} contexts. The first
+@code{\accepts} is created as a default context when events (e.g. notes
+or rests) are encountered.
+
+@item @code{\denies}:
+The opposite of @code{\accepts}.
+
+@item @code{\name} @var{contextname}:
+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
-@quotation
-@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
-
-@end quotation
+@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, to represent
+data throughout the whole program, and glue together different program
+modules. For advanced usage, it is sometimes necessary to access and
+program the Scheme interpreter.
-
-@node Syntactic details
-@section Syntactic details
-@cindex Syntactic details
+Scheme is a full-blown programming language, from the LISP
+family. 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.
-This section describes details that were too boring to be put elsewhere.
+The GUILE library for extension is documented at
+@uref{http://www.gnu.org/software/guile}.
+@ifinfo
+When it is installed, the following link should take you to its manual
+@ref{(guile.info)guile}
+@end ifinfo
@menu
-* Identifiers::
-* Music expressions::
-* Manipulating music expressions::
-* Span requests::
+* Inline Scheme::
+* Input variables and Scheme::
+* Scheme datatypes::
* Assignments::
-* Lexical modes::
-* Ambiguities::
@end menu
-@c . {Identifiers}
-@node Identifiers
-@subsection Identifiers
-@cindex Identifiers
+@node Inline Scheme
+@subsection Inline Scheme
-@ignore
- What has this section got to do with identifiers?
- It seems more appropriate in the introduction to Chapter 4,
- "Internals".
+Scheme expressions can be entered in the input file 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
- /MB
-@end ignore
-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,
+@node Input variables and Scheme
+@subsection Input variables and Scheme
-@itemize @bullet
+
+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
+
+@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 @code{\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.
+An 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:
+@table @code
+@item Duration
@item Input
-@item c++-function
+@item Moment
@item Music
-@item Identifier
-@item Translator_def
-@item Duration
+@item Event
+In C++ terms, an @code{Event} is a subtype of @code{Music}. However,
+both have different functions in the syntax.
+@item Music_output_def
@item Pitch
@item Score
-@item Music_output_def
-@item Moment (rational number)
-@end itemize
+@item Translator_def
+@end table
-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.
-@itemize @bullet
-@item Grob: short for Graphical object.
-@item Molecule: device-independent page output object,
-including dimensions. Produced by some Grob functions
-@item Translator: object that produces audio objects or Grobs. This is
-not yet user accessible.
-@item Font_metric: object representing a font.
-@end itemize
+During a run, transient objects are also created and destroyed.
+
+@table @code
+@item Grob: short for `Graphical object'.
+@item Scheme_hash_table
+@item Music_iterator
+
+@item Molecule: Device-independent page output object,
+including dimensions.
+
+@item Syllable_group
+
+@item Spring_smob
+
+@item Translator: An object that produces audio objects or Grobs.
+It may be accessed with @code{\applyoutput}.
+
+@item Font_metric: An object representing a font.
+@end table
+
+Many functions are defined to manipulate these data structures. They
+are all listed and documented in the internals manual, see
+@internalsref{All scheme functions}.
+
+
+@node Assignments
+@subsection Assignments
+@cindex Assignments
+Variables allow objects to be assigned to names during the parse
+stage. To assign a variable, use
+@example
+@var{name}@code{=}@var{value}
+@end example
+To refer to a variable, precede its name with a backslash:
+`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
+the input-types listed above. Variable assignments can appear at top
+level in the LilyPond file, but also in @code{\paper} blocks.
+
+A variable can be created with any string for its name, but for
+accessing it in the LilyPond syntax, its name must consist of
+alphabetic characters only, and may not be a keyword of the syntax.
+There are no restrictions for naming and accessing variables in the
+Scheme interpreter,
+
+The right hand side of a variable assignment is parsed completely
+before the assignment is done, so variables may be redefined in terms
+of its old value, e.g.
+@c
+@example
+foo = \foo * 2.0
+@end example
+
+When a variable is referenced in LilyPond syntax, the information it
+points to is copied. For this reason, an variable 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
+
+Music in LilyPond is entered as music expressions. This section
+discusses different types of music expressions, and explains how
+information is stored internally. This internal storage is accessible
+through the Scheme interpreter, so music expressions may be
+manipulated using Scheme functions.
+
+@menu
+* Music expressions::
+* Internal music representation::
+* Manipulating music expressions::
+@end menu
@node Music expressions
@subsection Music expressions
-
@cindex music expressions
-Music in LilyPond is entered as a music expression. Notes, rests, lyric
-syllables are music expressions, and you can combine music expressions
-to form new ones, for example by enclosing a list of expressions in
-@code{\sequential @{ @}} or @code{< >}. In the following example, a
-compound expression is formed out of the quarter note @code{c} and a
-quarter note @code{d}:
+Notes, rests, lyric syllables are music expressions. Small music
+expressions may be combined to form larger ones, for example, by
+enclosing a list of expressions in @code{\sequential @{ @}} or @code{<
+>}. In the following example, a compound expression is formed out of
+the quarter note @code{c} and a quarter note @code{d}:
@example
\sequential @{ c4 d4 @}
@cindex Simultaneous music
@cindex @code{\simultaneous}
-The two basic compound music expressions are simultaneous and
-sequential music.
+The two basic compound music expressions are simultaneous and
+sequential music:
@example
- \sequential @code{@{} @var{musicexprlist} @code{@}}
- \simultaneous @code{@{} @var{musicexprlist} @code{@}}
+\sequential @code{@{} @var{musicexprlist} @code{@}}
+\simultaneous @code{@{} @var{musicexprlist} @code{@}}
@end example
+
For both, there is a shorthand:
+
@example
- @code{@{} @var{musicexprlist} @code{@}}
+@code{@{} @var{musicexprlist} @code{@}}
@end example
+
+@noindent
for sequential and
+
@example
- @code{<} @var{musicexprlist} @code{>}
+@code{<} @var{musicexprlist} @code{>}
@end example
+
+@noindent
for simultaneous music.
In principle, the way in which you nest sequential and simultaneous to
produce music is not relevant. In the following example, three chords
are expressed in two different ways:
-@lilypond[fragment,verbatim,center]
- \notes \context Voice {
- <a c'> <b d' > <c' e'>
- < { a b c' } { c' d' e' } >
- }
+@lilypond[fragment,verbatim,center,quote]
+\notes \context Voice {
+ <a c'> <b d'> <c' e'>
+ < { a b c' } { c' d' e' } >
+}
@end lilypond
+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{<< >>}.
-Other compound music expressions include
-@example
- \repeat @var{expr}
- \transpose @var{pitch} @var{expr}
- \apply @var{func} @var{expr}
- \context @var{type} = @var{id} @var{expr}
- \times @var{fraction} @var{expr}
-@end example
-@c . {Manipulating music expressions}
-@node Manipulating music expressions
-@subsection Manipulating music expressions
-The @code{\apply} mechanism gives you access to the internal
-representation of music. You can write Scheme-functions that operate
-directly on it. The syntax is
+Other compound music expressions include:
@example
- \apply #@var{func} @var{music}
+\repeat @var{expr}
+\transpose @var{from} @var{to} @var{expr}
+\apply @var{func} @var{expr}
+\context @var{type} = @var{id} @var{expr}
+\times @var{fraction} @var{expr}
@end example
-This means that @var{func} is applied to @var{music}. The function
-@var{func} should return a music expression.
-This example replaces the text string of a script. It also shows a dump
-of the music it processes, which is useful if you want to know more
-about how music is stored.
+@node Internal music representation
+@subsection Internal music representation
-@lilypond[verbatim,singleline]
-#(define (testfunc x)
- (if (equal? (ly-get-mus-property x 'text) "foo")
- (ly-set-mus-property! x 'text "bar"))
- ;; recurse
- (ly-set-mus-property! x 'elements
- (map testfunc (ly-get-mus-property x 'elements)))
- (display x)
- x
-)
-\score { \notes
- \apply #testfunc { c'4_"foo" }
-}
-@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]
-#(define (reverse-music music)
- (let* ((elements (ly-get-mus-property music 'elements))
- (reversed (reverse elements))
- (span-dir (ly-get-mus-property music 'span-direction)))
- (ly-set-mus-property! music 'elements reversed)
- (if (dir? span-dir)
- (ly-set-mus-property! music 'span-direction (- span-dir)))
- (map reverse-music reversed)
- music))
-
-music = \notes { c'4 d'4( e'4 f'4 }
+When a music expression is parsed, it is converted into a set of
+Scheme music objects. The defining property of a music object is that
+it takes up time. Time is a rational number that measures the length
+of a piece of music, in whole notes.
-\score { \context Voice {
- \music
- \apply #reverse-music \music
- }
-}
-@end lilypond
-
-More examples are given in the distributed example files in
-@code{input/test/}.
-
-@c . {Span requests}
-@menu
-* Span requests::
-@end menu
-
-@node Span requests
-@subsection Span requests
-@cindex Span requests
+A music object has three kinds of types:
+@itemize @bullet
+@item
+ music name: Each music expression has a name, for example, a note
+leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
+a @internalsref{SimultaneousMusic}. A list of all expressions
+available is in the internals manual, under @internalsref{Music
+expressions}.
+
+@item
+ `type' or interface: Each music name has several `types' or interface,
+ for example, a note is an @code{event}, but it is also a @code{note-event},
+ a @code{rhythmic-event} and a @code{melodic-event}.
+
+ All classes of music are listed in the internals manual, under
+ @internalsref{Music classes}.
+@item
+C++ object: Each music object is represented by a C++ object. For technical
+reasons, different music objects may be represented by different C++
+object types. For example, a note is @code{Event} object, while
+@code{\grace} creates a @code{Grace_music} object.
+
+We expect that distinctions between different C++ types will disappear
+in the future.
+@end itemize
-Notational constructs that start and end on different notes can be
-entered using span requests. The syntax is as follows:
+The actual information of a music expression is stored in properties.
+For example, a @internalsref{NoteEvent} has @code{pitch} and
+@code{duration} properties that store the pitch and duration of that
+note. A list of all properties available is in the internals manual,
+under @internalsref{Music properties}.
+
+A compound music expression is a music object that contains other
+music objects in its properties. A list of objects can be stored in
+the @code{elements} property of a music object, or a single `child'
+music object in the @code{element} object. For example,
+@internalsref{SequentialMusic} has its children in @code{elements},
+and @internalsref{GraceMusic} has its single argument in
+@code{element}. The body of a repeat is in @code{element} property of
+@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
+@node Manipulating music expressions
+@subsection Manipulating music expressions
+Music objects and their properties can be accessed and manipulated
+directly, through the @code{\apply} mechanism.
+The syntax for @code{\apply} is
@example
- \spanrequest @var{startstop} @var{type}
+\apply #@var{func} @var{music}
@end example
+@noindent
+This means that the scheme function @var{func} is called with
+@var{music} as its argument. The return value of @var{func} is the
+result of the entire expression. @var{func} may read and write music
+properties using the functions @code{ly:get-mus-property} and
+@code{ly:set-mus-property!}.
-@cindex @code{\start}
-@cindex @code{\stop}
-
-This defines a spanning request. The @var{startstop} parameter is either
--1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
-describes what should be started. Much of the syntactic sugar is a
-shorthand for @code{\spanrequest}, for example,
-
-@lilypond[fragment,verbatim,center]
- c'4-\spanrequest \start "slur"
- c'4-\spanrequest \stop "slur"
+An example is a function that reverses the order of elements in
+its argument:
+@lilypond[verbatim,singleline]
+ #(define (rev-music-1 m)
+ (ly:set-mus-property! m 'elements (reverse
+ (ly:get-mus-property m 'elements)))
+ m)
+ \score { \notes \apply #rev-music-1 { c4 d4 } }
@end lilypond
-Among the supported types are @code{crescendo}, @code{decrescendo},
-@code{beam}, @code{slur}. This is an internal command. Users are
-encouraged to use the shorthands which are defined in the initialization
-file @file{spanners.ly}.
-
-
-@c . {Assignments}
-@node Assignments
-@subsection Assignments
-@cindex Assignments
-
-Identifiers allow objects to be assigned to names during the parse
-stage. To assign an identifier, you use @var{name}@code{=}@var{value}
-and to refer to an identifier, you 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.
+The use of such a function is very limited. The effect of this
+function is void when applied to an argument which is does not have
+multiple children. The following function application has no effect:
@example
-foo = \foo * 2.0
+ \apply #rev-music-1 \grace @{ c4 d4 @}
@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
-@}
+@noindent
+In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
+@code{elements}, only a single @code{element}. Every generally
+applicable function for @code{\apply} must -- like music expressions
+themselves -- be recursive.
-\paper @{
- \paperIdent % correct
- foo = 1.0 @}
-@end example
+The following example is such a recursive function: It first extracts
+the @code{elements} of an expression, reverses them and puts them
+back. Then it recurses, both on @code{elements} and @code{element}
+children.
+@example
+#(define (reverse-music music)
+ (let* ((elements (ly:get-mus-property music 'elements))
+ (child (ly:get-mus-property music 'element))
+ (reversed (reverse elements)))
+ ; set children
+ (ly:set-mus-property! music 'elements reversed)
-@c . {Lexical modes}
-@node Lexical modes
-@subsection Lexical modes
-@cindex Lexical modes
-@cindex input mode
-@cindex mode, input
-@cindex @code{\notes}
-@cindex @code{\chords}
-@cindex @code{\lyrics}
+ ; recurse
+ (if (ly:music? child) (reverse-music child))
+ (map reverse-music reversed)
+
+ music))
+@end example
-To simplify entering notes, lyrics, and chords, LilyPond has three
-special input modes in addition to the default mode: note, lyrics and
-chords mode. These input modes change the way that normal, unquoted
-words are interpreted: for example, the word @code{cis} may be
-interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
-major triad respectively.
+A slightly more elaborate example is in
+@inputfileref{input/test,reverse-music.ly}.
-A mode switch is entered as a compound music expression
+Some of the input syntax is also implemented as recursive music
+functions. For example, the syntax for polyphony
@example
-@code{\notes} @var{musicexpr}
-@code{\chords} @var{musicexpr}
-@code{\lyrics} @var{musicexpr}.
+ < a \\ b>
@end example
-In each of these cases, these expressions do not add anything to the
-meaning of their arguments. They just instruct the parser in what mode
-to parse their arguments.
-
-Different input modes may be nested.
-
-@c . {Ambiguities}
-@node Ambiguities
-@subsection Ambiguities
-@cindex ambiguities
-@cindex grammar
-
-
-The grammar contains a number of ambiguities. We hope to resolve them at
-some time.
-
-@itemize @bullet
- @item The assignment
+@noindent
+is actually implemented as a recursive function that replaces the
+above by the internal equivalent of
+@example
+ < \context Voice = "1" @{ \voiceOne a @}
+ \context Voice = "2" @{ \voiceTwo b @} >
+@end example
-@example
-foo = bar
-@end example
- is interpreted as the string identifier assignment. However,
-it can also be interpreted as making a string identifier @code{\foo}
-containing @code{"bar"}, or a music identifier @code{\foo} containing
-the syllable `bar'. The former interpretation is chosen.
+Other applications of @code{\apply} are writing out repeats
+automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
+saving keystrokes (@inputfileref{input/test,music-box.ly}) and
+exporting
+LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
- @item If you do a nested repeat like
+@seealso
- @quotation
+@file{scm/music-functions.scm}, @file{scm/music-types.scm},
+@inputfileref{input/test,add-staccato.ly},
+@inputfileref{input/test,unfold-all-repeats.ly}, and
+@inputfileref{input/test,music-box.ly}.
-@example
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end example
+@node Lexical details
+@section Lexical details
- @end quotation
- then it is ambiguous to which @code{\repeat} the
- @code{\alternative} belongs. This is the classic if-then-else
- dilemma. It may be solved by using braces.
+@cindex string
+@cindex concatenate
-@end itemize
+Begins and ends with the @code{"} character. To include a @code{"}
+character in a string write @code{\"}. Various other backslash
+sequences have special interpretations as in the C language. A string
+that contains no spaces can be written without the quotes. Strings can
+be concatenated with the @code{+} operator.
-@c . {Lexical details}
-@node Lexical details
-@section Lexical details
-Even more boring details, now on lexical side of the input parser.
-@menu
-* Direct Scheme::
-* Reals::
-* Strings::
-@end menu
+@node Output details
+@section Output details
+LilyPond's default output format is @TeX{}. Using the option @option{-f}
+(or @option{--format}) other output formats can be selected also, but
+currently none of them work reliably.
-@node Direct Scheme
-@subsection Direct Scheme
+At the beginning of the output file, various global parameters are defined.
+It also contains a large @code{\special} call to define PostScript routines
+to draw items not representable with @TeX{}, mainly slurs and ties. A DVI
+driver must be able to understand such embedded PostScript, or the output
+will be rendered incompletely.
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
+Then the file @file{lilyponddefs.tex} is loaded to define the macros used
+in the code which follows. @file{lilyponddefs.tex} includes various other
+files, partially depending on the global parameters.
+Now the music is output system by system (a `system' consists of all
+staves belonging together). From @TeX{}'s point of view, a system is an
+@code{\hbox} which contains a lowered @code{\vbox} so that it is centered
+vertically on the baseline of the text. Between systems,
+@code{\interscoreline} is inserted vertically to have stretchable space.
+The horizontal dimension of the @code{\hbox} is given by the
+@code{linewidth} parameter from LilyPond's @code{\paper} block.
-@cindex GUILE
-@cindex Scheme
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
+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 by setting the variable
+@code{lastpagefill} in LilyPond's @code{\paper} block.
-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}.
+It is possible to fine-tune the vertical offset further by defining the
+macro @code{\lilypondscoreshift}:
-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
-evaluates the specified Scheme code. Example:
@example
- \property Staff.TestObject \override #'foobar = #(+ 1 2)
+\def\lilypondscoreshift@{0.25\baselineskip@}
@end example
-@code{\override} expects two Scheme expressions, so there are 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.
+@noindent
+where @code{\baselineskip} is the distance from one text line to the next.
-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.
+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
+(@pxref{lilypond-book manual}):
-@node Reals
-@subsection Reals
-@cindex real numbers
+@example
+\documentclass@{article@}
-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.
+\def\lilypondpaperlastpagefill@{@}
+\lineskip 5pt
+\def\lilypondscoreshift@{0.25\baselineskip@}
-@cindex @code{\mm}
-@cindex @code{\in}
-@cindex @code{\cm}
-@cindex @code{\pt}
-@cindex dimensions
+\begin@{document@}
+This is running text which includes an example music file
+\input@{foo.tex@}
+right here.
+\end@{document@}
+@end example
-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
-a number that is the internal representation of that dimension.
+The file @file{foo.tex} has been simply produced with
+@example
+lilypond foo.ly
+@end example
-@node Strings
-@subsection Strings
-@cindex string
-@cindex concatenate
+It is important to set the @code{indent} parameter to zero in the
+@code{\paper} block of @file{foo.ly}.
-Begins and ends with the @code{"} character. To include a @code{"}
-character in a string write @code{\"}. Various other backslash
-sequences have special interpretations as in the C language. A string
-that contains no spaces can be written without the quotes. Strings can
-be concatenated with the @code{+} operator.
+The call to @code{\lineskip} assures that there is enough vertical space
+between the LilyPond box and the surrounding text lines.
+@c EOF
projects / lilypond.git / blobdiff