+@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'> } }
+@end lilypond
+
+
+
+@node Context properties
+@subsection Context properties
+
+Notation contexts can be modified from within the @file{.ly} file. The
+following music expression does that job:
+
+@cindex @code{\property}
+@example
+ \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.
+
+Properties that are set in one context are inherited by all of the
+contained contexts. This means that a property valid for the
+@code{Voice} context can be set in the @code{Score} context (for
+example) and thus take effect in all @code{Voice} contexts.
+
+Properties can be unset using the following expression:
+@example
+ \property @var{contextname}.@var{propname} \unset
+@end example
+
+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
+
+@code{\property \unset} is not the inverse of @code{\property \set}
+
+
+
+
+@c . {Context definitions}
+@node Changing context definitions
+@subsection Changing context definitions
+
+@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:
+@example
+\paper @{
+ \translator @{
+ @var{context-identifier}
+ @} @}
+@end example
+Then you can add engravers, remove engravers.
+The syntax for these operations are respectively
+@example
+ \remove @var{engravername}
+ \consists @var{engravername}
+@end example
+
+
+Here @var{engravername} is a string, the name of an engraver in the
+system.
+@example
+ @var{propname} = @var{value}
+@end example
+
+
+@lilypond[verbatim,singleline]
+\score { \notes {
+ c'4 c'4 }
+ \paper {
+ \translator { \StaffContext
+ \remove Clef_engraver;
+ } } }
+@end lilypond
+
+@cindex engraver
+
+You can also set properties in a translator definition. The syntax is as
+follows:
+
+@var{propname} is a string and @var{value} is a Scheme
+expression.
+@example
+ @var{propname} = @var{value}
+ @var{propname} \set @var{symbol} = @var{value}
+ @var{propname} \override @var{symbol} = @var{value}
+ @var{propname} \revert @var{symbol}
+
+@end example
+
+These type of property assignments happen before interpretation starts,
+so a @code{\property} expression 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}.
+
+@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:
+@example
+\translator @code{
+ \type "Engraver_group_engraver";
+ \name "SimpleStaff";
+ \alias "Staff";
+ \consists "Staff_symbol_engraver";
+ \consists "Note_head_engraver";
+ \consistsend "Axis_group_engraver";
+}@
+@end example
+
+Basic building blocks of translation are called engravers; they are
+special C++ classes.
+
+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 toplevel context.
+
+@cindex @code{Grace_engraver_group}
+
+ @item @code{Grace_engraver_group}
+ This is a special cooperation module (resembling
+ @code{Score_engraver}) that is used to created an embedded
+ `miniscore'.
+@end table
+
+Other modifiers are
+
+@itemize @bullet
+ @item @code{\alias} @var{alternate-name} @code{;}
+ 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} @code{;}
+ 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 are put there, and stay there, if a user adds or
+ removes engravers. This command is usually not needed for
+ end-users.
+
+ @item @code{\accepts} @var{contextname} @code{;}
+ Add @var{contextname} to the list of context this context can
+ contain. 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} @code{;}
+ This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
+ the name is not specified, the translator won't 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
+
+
+@cindex paper types, engravers, and pre-defined translators
+
+
+
+
+
+
+@c . {Syntactic details}
+@node Syntactic details
+@section Syntactic details
+@cindex Syntactic details
+
+This section describes details that were too boring to be put elsewhere.
+
+@menu
+* Top level::
+* Identifiers::
+* Music expressions::
+* Manipulating music expressions::
+* Assignments::
+* Lexical modes::
+* Ambiguities::
+@end menu
+
+@c . {Top level}
+@node Top level
+@subsection Top level
+@cindex Top level
+
+This section describes what you may enter at top level.
+
+
+@c . {Score}
+@subsubsection Score
+@cindex Score
+
+@cindex score definition
+
+The output is generated combining a music expression with an output
+definition. A score block has the following syntax:
+
+@example
+ \score @{ @var{musicexpr} @var{outputdefs} @}
+@end example
+
+@var{outputdefs} are zero or more output definitions. If none is
+supplied, the default @code{\paper} block will be added.
+
+
+
+@c . {Default output}
+@subsubsection Default output
+
+Default values for the @code{\paper} and @code{\midi} block are set by
+entering such a block at top-level.
+
+@c . {Header}
+@subsubsection Header
+@cindex Header
+@cindex @code{\header}
+
+
+A header describes bibilographic information of the file's contents. It
+can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
+use this information for generating titles. Key values that are used by
+@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
+metre, arranger, piece and tagline.
+
+@cindex @code{ly2dvi}
+
+The syntax is
+@example
+ \header @{ @var{key1} = @var{val1};
+ @var{key2} = @var{val2}; @dots{} @}
+@end example
+
+It is customary to put the @code{\header} at the top of the file.
+
+@subsubsection Default output
+
+A @code{\midi} or @code{\paper} block at top-level sets the default
+
+paper block for all scores that lack an explicit paper block.
+
+@c . {Identifiers}
+@node Identifiers
+@subsection Identifiers
+@cindex Identifiers
+
+All of the information in a LilyPond input file, is 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,
+
+@itemize @bullet
+@item Input
+@item c++-function
+@item Music
+@item Identifier
+@item Translator_def
+@item Duration
+@item Pitch
+@item Score
+@item Music_output_def
+@item Moment (rational number)
+@end itemize
+
+LilyPond also includes some transient object types. Objects of these
+types are built during a LilyPond run, and do not `exist' per se within
+your input file. These objects are created as a result of your input
+file, so you can include commands in the input to manipulate them,
+during a lilypond run.
+
+@itemize @bullet
+@item Grob: short for Graphical object. See @ref{Grobs}.
+@item Molecule: device-independent page output object,
+including dimensions. Produced by some Grob functions
+See @ref{Molecules}
+@item Translator: object that produces audio objects or Grobs. This is
+not yet user accessible.
+@item Font_metric: object representing a font. (See @ref{Font metrics})
+
+@end itemize
+
+
+@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}:
+
+@example
+\sequential @{ c4 d4 @}
+@end example
+
+@cindex Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
+@cindex @code{<}
+@cindex @code{>}
+@cindex Simultaneous music
+@cindex @code{\simultaneous}
+
+The two basic compound music expressions are simultaneous and
+sequential music.
+
+@example
+ \sequential @code{@{} @var{musicexprlist} @code{@}}
+ \simultaneous @code{@{} @var{musicexprlist} @code{@}}
+@end example
+For both, there is a shorthand:
+@example
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
+for sequential and
+@example
+ @code{<} @var{musicexprlist} @code{>}
+@end example
+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' } >
+ }
+@end lilypond
+
+
+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
+@example
+ \apply #@var{func} @var{music}
+@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.
+@lilypond[verbatim]
+#(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 { c4_"foo" }
+}
+@end lilypond
+
+For more information on what is possible, see the @ref{Tricks} and the
+automatically generated documentation.
+
+
+Directly accessing internal representations is dangerous: the
+implementation is subject to changes, so you should avoid this feature
+if possible.
+
+
+
+@c . {Span requests}
+@menu
+* Span requests::
+@end menu
+
+@node Span requests
+@subsubsection Span requests
+@cindex Span requests
+
+Notational constructs that start and end on different notes can be
+entered using span requests. The syntax is as follows:
+
+
+@example
+ \spanrequest @var{startstop} @var{type}
+@end example
+
+
+@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"
+@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 preceed 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.
+
+Semicolons are forbidden after top level assignments, but mandatory in
+other places. The rules about semicolons and assignments are very
+confusing, but when LilyPond input evolves more towards Scheme, we hope
+that this problem will grow smaller.
+
+An identifier can be created with any string for its name, but you will
+only be able to refer to identifiers whose names begin with a letter,
+being entirely alphabetical. It is impossible to refer to an identifier
+whose name is the same as the name of a keyword.
+
+The right hand side of an identifier assignment is parsed completely
+before the assignment is done, so it is allowed to redefine an
+identifier in terms of its old value, e.g.
+
+@example
+foo = \foo * 2.0
+@end example
+
+When an identifier is referenced, the information it points to is
+copied. For this reason, an identifier reference must always be the
+first item in a block.
+@example
+\paper @{
+ foo = 1.0
+ \paperIdent % wrong and invalid
+@}
+
+\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 on top of 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 mode switch is entered as a compound music expressions
+@example
+@code{\notes} @var{musicexpr}
+@code{\chords} @var{musicexpr}
+@code{\lyrics} @var{musicexpr}.
+@end example
+
+In each of these cases, these expressions do not add anything to the
+meaning of their arguments. They are just a way to indicate that the
+arguments should be parsed in indicated mode. The modes are treated in
+more detail in the @ref{Note entry}, @ref{Lyrics} and
+@ref{Chords}.
+
+You may nest different input modes.
+
+@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
+
+ can be interpreted as making a string identifier @code{\foo}
+ containing @code{"bar"}, or a music identifier @code{\foo}
+ containing the syllable `bar'.
+
+ @item The assignment
+
+ @example
+foo = -6
+@end example
+
+ can be interpreted as making an integer identifier
+ containing -6, or a Request identifier containing the
+ fingering `6' (with neutral direction).
+
+ @item If you do a nested repeat like
+
+ @quotation
+
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
+
+ @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.
+
+ @item (an as yet unidentified ambiguity :-)
+@end itemize
+
+
+@c . {Lexical details}
+@node Lexical details
+@section Lexical details
+
+Even more boring details, now on lexical side of the input parser.
+
+@menu
+* Comments::
+* Direct Scheme::
+* Keywords::
+* Integers::
+* Reals::
+* Strings::
+* Main input::
+* File inclusion::
+* Version information::
+@end menu
+
+
+@node Comments
+@subsection Comments
+
+@cindex comments
+@cindex block comment
+@cindex line comment
+
+@cindex @code{%}
+
+A one line comment is introduced by a @code{%} character.
+Block comments are started by @code{%@{} and ended by @code{%@}}.
+They cannot be nested.
+
+@node Direct Scheme
+@subsection Direct Scheme
+
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+
+
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. In some places Scheme expressions also form valid syntax:
+whereever it is allowed,
+@example
+ #@var{scheme}
+@end example
+evaluates the specified Scheme code. If this is used at toplevel, then
+the result is discarded. Example:
+@example
+ \property Staff.TestObject \override #'foobar = #(+ 1 2)
+@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).
+
+Scheme is a full-blown programming language, and a full discussion is
+outside the scope of this document. Interested readers are referred to
+the website @uref{http://www.schemers.org/} for more information on
+Scheme.
+
+
+@node Keywords
+@subsection Keywords
+@cindex Keywords
+
+
+Keywords start with a backslash, followed by a number of lower case
+alphabetic characters. These are all the keywords.
+
+@example
+apply arpeggio autochange spanrequest commandspanrequest
+simultaneous sequential accepts alternative bar breathe
+char chordmodifiers chords clef cm consists consistsend
+context denies duration dynamicscript elementdescriptions
+font grace header in lyrics key mark pitch
+time times midi mm name pitchnames notes outputproperty
+override set revert partial paper penalty property pt
+relative remove repeat addlyrics partcombine score
+script stylesheet skip textscript tempo translator
+transpose type
+@end example
+
+@node Integers
+@subsection Integers
+
+@cindex integers
+@cindex @code{+}
+@cindex @code{-}
+@cindex @code{*}
+@cindex @code{/}
+
+Formed from an optional minus sign followed by digits. Arithmetic
+operations cannot be done with integers, and integers cannot be mixed
+with reals.
+
+@node Reals
+@subsection Reals
+@cindex real numbers
+
+
+
+
+
+Formed from an optional minus sign and a sequence of digits followed
+by a @emph{required} decimal point and an optional exponent such as
+@code{-1.2e3}. Reals can be built up using the usual operations:
+`@code{+}', `@code{-}', `@code{*}', and
+`@code{/}', with parentheses for grouping.
+
+@cindex @code{\mm},
+@cindex @code{\in}
+@cindex @code{\cm}
+@cindex @code{\pt}
+@cindex dimensions
+
+A real constant can be followed by one of the dimension keywords:
+@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
+points, inches and centimeters, respectively. This converts the number
+a number that is the internal representation of that dimension.
+
+
+@node Strings
+@subsection Strings
+@cindex string
+@cindex concatenate
+
+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. See
+@ref{Lexical modes} for details on unquoted strings; their
+interpretation varies depending on the situation. Strings can be
+concatenated with the @code{+} operator.
+
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
+
+
+@node Main input
+@subsection Main input
+@cindex Main input
+
+@cindex @code{\maininput}
+
+The @code{\maininput} command is used in init files to signal that the
+user file must be read. This command cannot be used in a user file.
+
+@node File inclusion
+@subsection File inclusion
+@cindex @code{\include}
+@example
+ \include @var{filename}
+@end example
+
+Include @var{filename}. The argument @var{filename} may be a quoted string (an
+unquoted string will not work here!) or a string identifier. The full
+filename including the @file{.ly} extension must be given,
+
+
+@node Version information
+@subsection Version information
+@cindex @code{\version}
+@example
+ \version @var{string} ;
+@end example
+
+Specify the version of LilyPond that a file was written for. The
+argument is a version string in quotes, for example @code{"1.2.0"}.
+This is used to detect invalid input, and to aid
+@code{convert-ly} a tool that automatically upgrades input files. See
+See @ref{convert-ly} for more information on @code{convert-ly}.
+
+@cindex convert-ly
projects / lilypond.git / blobdiff