@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
-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::
-* Syntactic details::
+* Scheme integration::
+* Music storage format::
* Lexical details::
* Output details::
@end menu
@menu
* Creating contexts::
* Default contexts::
-* Context evaluation::
* 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
-@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 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?
@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}
@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 {
@end lilypond
@noindent
-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.
+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:
-
-First, every top level music is interpreted by the Score context; in other
-words, you may think of @code{\score} working like
+Every top level music is interpreted by the @code{Score} context; in
+other words, you may think of @code{\score} working like
@example
\score @{
@}
@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
-@noindent
-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 context 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.
-
-@node Context evaluation
-@subsection Context evaluation
-
-Scheme code can be used to modify contexts. 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 with. The following code will print the
-current bar number on the standard output during the compile.
-
-@example
- \applycontext
- #(lambda (tr)
- (format #t "\nWe were called in barnumber ~a.\n"
- (ly:get-context-property tr 'currentBarNumber)))
-@end example
-
+Second, contexts are created automatically to be able to interpret the
+music expressions. Consider the following example:
+@lilypond[verbatim, singleline]
+ \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}
@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
(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
+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
+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
@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
the inverse of @code{\property \set}.
-@node Engravers and performers
-@subsection Engravers and performers
+@node Context evaluation
+@subsection Context evaluation
-[TODO]
+Contexts can be modified during interpretation with Scheme code. The
+syntax for this is
+@example
+ \applycontext @var{function}
+@end example
-Basic building blocks of translation are called engravers; they are
-special C++ classes.
+@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 @{
@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}.
+The context can then be modified by setting or changing properties,
+e.g.
+@example
+\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
+
+@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.
+
+
+
+@cindex engraver
+@cindex plug-in
+
+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}.
-
+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
-
-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{
+\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 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 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
+@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.
+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 (e.g. 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 won't 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 paper types, engravers, and pre-defined translators
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+@cindex accessing Scheme
+@cindex evaluating Scheme
+@cindex LISP
-
-@node Syntactic details
-@section Syntactic details
-@cindex Syntactic details
+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.
-This section describes details that were too boring to be put elsewhere.
+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.
+
+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::
+* 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
+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. Produced by some Grob functions.
+including dimensions.
-@item Translator: An object that produces audio objects or Grobs. This is
-not yet user-accessible.
+@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 itemize
+@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 @code{\simultaneous}
The two basic compound music expressions are simultaneous and
-sequential music.
+sequential music:
@example
\sequential @code{@{} @var{musicexprlist} @code{@}}
produce music is not relevant. In the following example, three chords
are expressed in two different ways:
-@lilypond[fragment,verbatim,center]
+@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 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{<< >>}.
-Other compound music expressions include
+Other compound music expressions include:
@example
\repeat @var{expr}
\transpose @var{from} @var{to} @var{expr}
\times @var{fraction} @var{expr}
@end example
+@node Internal music representation
+@subsection Internal music representation
-@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
-@example
-\apply #@var{func} @var{music}
-@end example
-@noindent
-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.
-@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)
+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 {
- \notes
- \apply #testfunc { c'4_"foo" }
-}
-@end lilypond
+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
-For more information on what is possible, see the automatically
-generated documentation.
+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}.
-Directly accessing internal representations is dangerous: The
-implementation is subject to changes, so you should avoid this feature
-if possible.
+@node Manipulating music expressions
+@subsection Manipulating music expressions
-A final example is a function that reverses a piece of music in time:
+Music objects and their properties can be accessed and manipulated
+directly, through the @code{\apply} mechanism.
+The syntax for @code{\apply} is
+@example
+\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!}.
+
+An example is a function that reverses the order of elements in
+its argument:
@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 (ly: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 }
-
-\score {
- \context Voice {
- \music
- \apply #reverse-music \music
- }
-}
+ #(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
-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.
-
-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.
+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
-\paper @{
- foo = 1.0
- \paperIdent % wrong and invalid
-@}
+ \apply #rev-music-1 \grace @{ c4 d4 @}
@end example
+@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.
+
+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
-\paper @{
- \paperIdent % correct
- foo = 1.0
-@}
-@end example
-
-
-@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}
-
-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.
+#(define (reverse-music music)
+ (let* ((elements (ly:get-mus-property music 'elements))
+ (child (ly:get-mus-property music 'element))
+ (reversed (reverse elements)))
-A mode switch is entered as a compound music expression
+ ; set children
+ (ly:set-mus-property! music 'elements reversed)
-@example
-@code{\notes} @var{musicexpr}
-@code{\chords} @var{musicexpr}
-@code{\lyrics} @var{musicexpr}
+ ; recurse
+ (if (ly:music? child) (reverse-music child))
+ (map reverse-music reversed)
+
+ music))
@end example
-@noindent
-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
-
-@example
-foo = bar
-@end example
-
-@noindent
-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.
-
-@item If you do a nested repeat like
-
-@example
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end example
-
-@noindent
-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.
-@end itemize
-
-
-@c . {Lexical details}
-@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,
+A slightly more elaborate example is in
+@inputfileref{input/test,reverse-music.ly}.
+Some of the input syntax is also implemented as recursive music
+functions. For example, the syntax for polyphony
@example
-#@var{scheme}
+ < a \\ b>
@end example
@noindent
-evaluates the specified Scheme code. Example:
-
+is actually implemented as a recursive function that replaces the
+above by the internal equivalent of
@example
-\property Staff.TestObject \override #'foobar = #(+ 1 2)
+ < \context Voice = "1" @{ \voiceOne a @}
+ \context Voice = "2" @{ \voiceTwo b @} >
@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.
-
+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})
-@node Reals
-@subsection Reals
-@cindex real numbers
+@seealso
-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.
+@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}.
-@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 Lexical details
+@section Lexical details
-@node Strings
-@subsection Strings
@cindex string
@cindex concatenate
be concatenated with the @code{+} operator.
-@c . {Output details}
+
@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 reliably work.
+currently none of them work reliably.
At the beginning of the output file, various global parameters are defined.
It also contains a large @code{\special} call to define PostScript routines
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 (using the
-natural line width if its value is@w{ }@minus{}1).
-
-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
+@code{linewidth} parameter from LilyPond's @code{\paper} block.
-@example
-\def\lilypondpaperlastpagefill@{1@}
-@end example
-@noindent
-or by setting the variable @code{lastpagefill} in LilyPond's @code{\paper}
-block.
+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.
It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}. Example:
+macro @code{\lilypondscoreshift}:
@example
\def\lilypondscoreshift@{0.25\baselineskip@}
@end example
@noindent
-@code{\baselineskip} is the distance from one text line to the next.
+where @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
-(@pxref{Integrating text and music with lilypond-book}).
+(@pxref{lilypond-book manual}):
@example
\documentclass@{article@}
projects / lilypond.git / blobdiff