-
+@c -*-texinfo-*-
+@c TODO:
+@c - Reinsert subsection commands that were lost in the
+@c ancient conversion from YODL! /MB
+@c - Restructure! Separate internal commands from user level commands. /MB
+@c - Add some words about Guile. /MB
+@c - Fix indexing (keyindex) so it doesn't add line breaks /MB
@node Reference Manual, , , Top
+@chapter Reference Manual
+
@menu
-* Overview:: Overview
-* Top level:: Top level
-* notenames:: notenames
-* Lexical conventions:: Lexical conventions
-* Other languages:: notelang
-* modes:: modes
-* Types:: Types
-* Music expressions:: Music expressions
-* Atomic music expressions:: Atomic music expressions
-* Note specification:: notedesc
-* barlines:: barlines
-* Manual beams:: Manual beam
-* tremolo:: tremolo
-* Compound music expressions:: Compound music expressions
-* relative:: relative
-* Repeats:: Repeats
-* transpose:: transpose
-* Ambiguities:: Ambiguities
-* Notation conversion specifics:: Notation conversion specifics
-* autobeam:: autobeam
-* lyricprint:: lyricprint
-* Notation Contexts:: Notation Contexts
-* Properties:: Changing formatting
-* Notation output definitions:: Notation output definitions
-* paper:: paper
-* Paper variables:: papervars
-* contextdefs:: contextdefs
-* engravers:: engravers
-* Sound output:: Sound output
-* midilist:: midilist
-* Pre-defined Identifiers:: Pre-defined Identifiers
+* Overview:: Overview
+* Top level:: Top level
+* Pitch names:: Pitch names
+* Lexical conventions:: Lexical conventions
+* Other languages:: Note names in various languages
+* Lexical modes:: modes
+* Types:: Types
+* Music expressions:: Music expressions
+* Atomic music expressions:: Atomic music expressions
+* Note specification:: notedesc
+* barlines:: barlines
+* Manual beams:: Manual beam
+* stem tremolo:: tremolo
+* Compound music expressions:: Compound music expressions
+* relative:: relative
+* Repeats:: Repeats
+* transpose:: transpose
+* Ambiguities:: Ambiguities
+* Notation conversion specifics:: Notation conversion specifics
+* autobeam:: autobeam
+* lyricprint:: lyricprint
+* Notation Contexts:: Notation Contexts
+* Properties:: Changing formatting
+* Notation output definitions:: Notation output definitions
+* paper:: paper
+* Paper variables:: papervars
+* contextdefs:: contextdefs
+* Sound output:: Sound output
+* midilist:: midilist
+* Grobs:: Graphical objects
+* Molecule:: Molecules
+* Pre-defined Identifiers:: Pre-defined Identifiers
+@c May be fragile. Better make single link to generated doco?
+* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
+* Engravers:(lilypond-internals)LilyPond engravers.
+* Backend:(lilypond-internals)LilyPond backend.
@end menu
-@chapter Reference Manual
-
@node Overview, , , Reference Manual
@section Overview
-This document@footnote{This document has been revised for
-LilyPond 1.2.} describes the the GNU LilyPond input format, which is
-a language for defining music. We call this language @emph{Music
-Definition Language} or @emph{Mudela}, for short.@footnote{If anybody
-comes up with a better name, we'd gladly take this. Gourlay already
-uses a ``Musical Description Language,'' ISO standard 10743 defines a
-``Standard Music Description Language.'' We're not being original
-here.}
-
-@emph{Mudela} is a language that allows you to
+This document@footnote{This document has been revised for LilyPond 1.2.}
+describes the the GNU LilyPond input format This format represents a
+piece of music in an elegant way, but contains enough information for
+both automatic typesetting and automatic performances.
+LilyPond input can be classified into three types:
@itemize @bullet
- @item create musical expressions by combining pitches, durations
- @item output those musical expressions to various formats
- @item give those musical expressions and output definitions names, so
- you can enter them in manageable chunks.
-@end itemize
+ @item musical expressions: a musical expression is some combination of
+rest, notes, lyrics
+ @item output definitions: recipes for translating those musical
+expressions into performances (MIDI) or graphics (eg. PostScript).
-@emph{Mudela} aims to define a piece of music completely, both from
-typesetting and from a performance point of view.
+ @item declarations: by declaring and naming musical expressions, you
+can enter and edit them in manageable chunks.
+@end itemize
@var{outputdefs} are zero or more output definitions. If no output
definition is supplied, the default @code{\paper} block will be added.
-
-
@cindex header
@keyindex{header}
@example
\header @{ @var{key1} = @var{val1};
- @var{key2} = @var{val2}; @dots{} @}
+ @var{key2} = @var{val2}; @dots{} @}
@end example
A header describes the file's contents. It can also appear in a
It is customary to put the @code{\header} at the top of the file.
-@node notenames, , , Reference Manual
-
-Note name tables can be specified using
-
-@example
- \notenames@keyindex{notenames}
- @{ @var{assignmentlist} @}
-@end example
-
-@var{assignmentlist} is a list of definitions of the form
+@node Pitch names, , , Reference Manual
+Note names and chord modifiers can be customised for nationalities.
+languages and conventions. The syntax is as follows.
@example
- @var{name} = @var{pitch}
+ \pitchnames @keyindex{pitchnames} @var{scheme-alist}
+ \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
@end example
-Chord modifiers can be set analogously, with
-@code{\chordmodifiers}@keyindex{chordmodifiers}.
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+specific examples how to do this. tables can be tailored specified
+using. Some national note names have been provided, see @ref{Other
+languages}.
A @code{\paper} block at top level sets the default paper block. A
@code{\midi} block at top level works similarly.
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. The following commands access the interpreter
-directly.
-
-@example
- \scm @keyindex{scm} @var{scheme} ;
-@end example
-
-Evaluates the specified Scheme code. The result is discarded.
-
-@example
-\scmfile@keyindex{scmfile} @var{filename};
-@end example
-
-Reads Scheme code from the specified file. The result is discarded.
-
-
-
Identifier assignments may appear at top level. Semicolons are
forbidden after top level assignments.
+@unnumberedsubsec Comments
+
@cindex comment
@indexcode{%}
Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
They cannot be nested.
+@unnumberedsubsec Scheme
+
+@indexcode{#}
+
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. The interpreter is accessed by the pound sign:
+
+Whereever the syntax allows Scheme expressions, you may enter one as
+@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 #'symbol = #(+ 1 2)
+@end example
+
+(in this case, @code{\override} expects two Scheme expressions.
+
+[refer appendix/ online intro on Scheme]
+
+@unnumberedsubsec Keywords
@cindex keyword
alphabetic characters. These are all the keywords.
@example
- \accepts
- \addlyrics
- \alternative
- \bar
- \breathe
- \chordmodifiers
- \chords
- \clef
- \cm
- \consists
- \consistsend
- \context
- \duration
- \font
- \grace
- \header
- \in
- \key
- \keysignature
- \lyrics
- \mark
- \midi
- \mm
- \musicalpitch
- \name
- \notenames
- \notes
- \paper
- \partial
- \penalty
- \property
- \pt
- \relative
- \remove
- \repeat
- \repetitions
- \scm
- \scmfile
- \score
- \script
- \sequential
- \simultaneous
- \skip
- \spanrequest
- \tempo
- \textscript
- \time
- \times
- \translator
- \transpose
- \type
+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 musicalpitch
+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
-
-
+@unnumberedsubsec Integers
@cindex integer
operations cannot be done with integers, and integers cannot be mixed
with reals.
-
+@unnumberedsubsec Reals
@cindex real
is the internal representation of dimensions.
-
+@unnumberedsubsec
@cindex string
-
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 section XREF-modes [FIXME] for details on unquoted strings; their
-interpretation varies depending on the situation. Strings can be
-concatenated with the `@code{+}' operator.
+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 can appear
-anywhere.
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
@example
\maininput@keyindex{maininput}
This command is used in init files to signal that the user file must
be read. This command cannot be used in a user file.
+@unnumberedsubsec file inclusion
+
@example
\include@keyindex{include} @var{file}
@end example
unquoted string will not work here!) or a string identifier. The full
filename including the @file{.ly} extension must be given,
+@unnumberedsubsec Version information
+
@example
\version@keyindex{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-mudela}, a tool that automatically upgrades input files.
+@code{convert-ly}, a tool that automatically upgrades input files.
deutsch.ly c d e f g a b h -is -es
norsk.ly c d e f g a b h -iss/-is -ess/-es
svenska.ly c d e f g a b h -iss -ess
-italiano.ly do re mi fa sol la sid si -d -b
-catalan.ly do re mi fa sol la sid si -d/-s -b
+italiano.ly do re mi fa sol la sib si -d -b
+catalan.ly do re mi fa sol la sib si -d/-s -b
@end example
-Pitch names can be redefined using the
-@code{\notenames}@keyindex{notenames} command, see
-subsection XREF-notenames [FIXME].
-
+Pitch names can be redefined using the @code{\pitchnames} command, see
+@ref{Pitch names}.
-
-@cindex lexical modes
+@cindex Lexical Modes
@cindex modes
-@node modes, , , Reference Manual
+@node Lexical modes, , , Reference Manual
-To simplify entering notes, lyrics, and chords, @emph{Mudela} has three
+To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
special input modes on top of the default mode. In each mode, words
are identified on the input. If @code{"word"} is encountered, it is
treated as a string. If @code{\word} is encountered, it is treated as
@item Normal mode.
@cindex mode!normal
- At the start of parsing, @emph{Mudela} is in Normal mode. In Normal
+ At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal
mode, a word is an alphabetic character followed by alphanumeric
characters. If @code{word} is encountered on the input it is
treated as a string.
is that a word can end with `@code{@}}', which may be confusing if
you thought the closing brace was going to terminate Lyrics
mode.@footnote{LilyPond will issue a warning, though.} Any
- `@code{_}' characters which appear in an unquoted word are
- converted to spaces. This provides a mechanism for introducing
+ `@code{_}' character which appears in an unquoted word is
+ converted to a space. This provides a mechanism for introducing
spaces into words without using quotes. Quoted words can also be
used in Lyrics mode to specify words that cannot be written with
the above rules. Here are some examples. Not all of these words
durations, you can not enter real numbers in this mode.
@end table
-It is possible to create words that break the rules by prefixing them
-with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a
-word beginning with `@code{$}' extends until the next white space
-character. Such words can contain numbers (even in Note mode), or
-other forbidden characters. The dollar sign can be used to create
-and access identifiers that could not otherwise be used.@footnote{Use
-of `@code{$}' hampers readability and portability to future LilyPond
-versions, thus the use of the dollar sign is discouraged.}
-
-
+[todo: include short table showign differences]
@node Types, , , Reference Manual
@section Types
-@cindex types and identifiers
+@cindex Identifiers
+
+[say something about types]
+
+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: see @ref{Music expressions}
+ @item Identifier
+ @item Translator_def:
+See section @ref{contextdefs} for more information
+
+ @item Duration
+ @item Pitch
+ @item Score (TODO, smobme)
+@item Music_output_def (TODO, smobme)
+
+ @item Moment (rational number)
+@end itemize
-@emph{Mudela} has a limited set of types:
+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 integers
- @item reals
- @item strings
- @item music expressions
- @item durations of notes and rests (specified with
- @code{\notenames}@keyindex{notenames})
- @item note name tables
- @item context definitions, part of output definitions. See
- section XREF-contextdefs [FIXME] for more information
- @item output definitions (like @code{\paper}@keyindex{paper} blocks
- and @code{\midi}@keyindex{midi} blocks)
- @item score definitions (@code{\score}@keyindex{score} blocks)
+ @item Grob: short for Graphical object. See @ref{Grobs}.
+ @item Molecule: device-independent paper output object,
+ including dimensions. Produced by some Grob functions
+ @item Translator: object that produces audio objects or Grobs
+
+ @item Font_metric: object representing a font. (Not yet user accessible.)
+ @item Audio_element: (TODO, smobme)
@end itemize
-Type is a syntactical property: @emph{Mudela} has no real type system,
-so there is no support for generic expressions, functions, or user
-defined types. For the same reason, it is not possible to mix reals
-and integers in arithmetic expressions, and ``type
-errors''
-@cindex type error
- (e.g., using a string identifier to
-initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse
-error''.
-
-Identifiers allow objects to be assigned to names. To assign an
-identifier, you use `@var{name}=@var{value}' and to refer to an
-identifier, you preceed its name with a backslash:
+Identifiers allow objects to be assigned to names during the parse
+stage. To assign an identifier, you use `@var{name}=@var{value}' and to
+refer to an identifier, you preceed its name with a backslash:
`@code{\}@var{name}'. Identifier assignments must appear at top level
-in the @emph{Mudela} file. Semicolons are forbidden after assignments
+in the @emph{Lilypond} file. Semicolons are forbidden after assignments
appearing at top level but they are obligatory after assignments
-appearing in the @code{\paper} block, see Section XREF-paper [FIXME].
+appearing in the @code{\paper} block, see Section @ref{paper}.
-@var{value} is any of the types listed above.
+@var{value} is any valid Scheme value or any of the input-types listed
+above.
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
@end example
When an identifier is referenced, the information it points to is
-copied. Therefore it only makes sense to put identifiers for
-translators, output definitions, and @code{\score}@keyindex{score}
-blocks as the first item in a block. For this reason, if you
-reference a @code{\foo} variable in a @code{\foo} block, it must be the
-first item in the list following @code{\foo}.@footnote{@code{\paper@{\one
-\two@}} does not make sense, because the information of @code{\two}
-would overwrite the information of @code{\one}, thereby making the
-reference to the first identifier useless.}
+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
@node Music expressions, , , Reference Manual
@cindex music expressions
-Music in @emph{Mudela} is entered as a music expression. Notes, rests,
+Music in @emph{Lilypond} is entered as a music expression. Notes, rests,
lyric syllables are music expressions (the atomic
expressions)
@cindex atomic music expressions
simultaneously, for instance).
Atomic music expression are discussed in
-subsection XREF-atomicmusic [FIXME]. Compound music expressions are
-discussed in subsection XREF-compoundmusic [FIXME].
+subsection @ref{Atomic music expressions}. Compound music expressions are
+discussed in subsection @ref{Compound music expressions}.
natural, negative to add flats, or positive to add sharps.
In Note and Chord mode, pitches may be designated by names. See
-section XREF-notelang [FIXME] for pitch names in different languages.
+section @ref{Other languages} for pitch names in different languages.
The syntax for duration specification is
@var{dotcount}.
In Note, Chord, and Lyrics mode, durations may be designated by
-numbers and dots. See Section XREF-notelang [FIXME] for details.
+numbers and dots.
@node Note specification, , , Reference Manual
The default names are the Dutch note names. The notes are specified
by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
octave below middle C and the letters span the octave above that C.
-In Dutchcindex(notenames!Dutch), a sharp is formed by adding
-`@code{-is}' to the end of a pitch name. A flat is formed by adding
-`@code{-es}'. Double sharps and double flats are obtained by adding
-`@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are
-contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will
-be accepted.
+In Dutch,
+@cindex notenames!Dutch
+a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
+flat is formed by adding `@code{-es}'. Double sharps and double flats
+are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
+and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
+but both forms will be accepted.
LilyPond has predefined sets of notenames for various languages. See
-section XREF-notelang [FIXME] for details.
+@ref{Other languages}.
+
The optional octave specification takes the form of a series of
(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
octave; each @code{,} lowers the pitch by an octave.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c' d' e' f' g' a' b' c''
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
cis' dis' eis' fis' gis' ais' bis'
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
ces' des' es' fes' ges' as' bes'
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
cisis' eisis' gisis' aisis' beses'
-@end mudela
+@end lilypond
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
ceses' eses' geses' ases' beses'
-@end mudela
+@end lilypond
Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
will determine what accidentals to typeset depending on the key and
accidental within parentheses can be obtained by adding the question
mark `@code{?}@indexcode{?}' after the pitch.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
cis' d' e' cis' c'? d' e' c'!
-@end mudela
+@end lilypond
@cindex duration
@quotation
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
a\longa a\breve
} %}
}
}
-@end mudela
+@end lilypond
@end quotation
@quotation
@quotation
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64
}
\paper {
- loose_column_distance = 2.5 * \interline;
+ loose_column_distance = 2.5 * \staffspace;
linewidth = -1.0;
\translator {
- \type "Score_engraver";
- \name "Score";
- \consists "Rest_engraver";
- \consists "Stem_engraver";
- \consists "Rhythmic_column_engraver";
+ \StaffContext
+ \remove "Clef_engraver";
+ \remove "Staff_symbol_engraver";
+ \remove "Bar_engraver";
}
}
}
-@end mudela
+@end lilypond
@end quotation
If the duration is omitted then it is set equal to the previous
assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
to obtain dotted note lengths.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
a'4. b'4.
-@end mudela
+@end lilypond
You can alter the length of duration by writing
`@code{*}@var{fraction}' after it. This will not affect the
Rests are entered like notes, with note name `@code{r}@indexcode{r}',
-or `@code{R}@indexcode{R}'. There is also a note name `@code{s}@indexcode{s}',
-which produces a space of the specified duration.
-`@code{R}' is specifically meant for entering parts: the @code{R} rest
-can expand to fill a score with rests, or it can be printed as a
-single multimeasure rest.
+or `@code{R}@indexcode{R}'. There is also a note name
+`@code{s}@indexcode{s}', which produces a space of the specified
+duration. `@code{R}' is specifically meant for entering parts: the
+@code{R} rest can expand to fill a score with rests, or it can be
+printed as a single multimeasure rest.
+
+You can control the expansion by setting the property
+@code{Score.skipBars}. If this is set to true, Lily will not expand
+empty measures, and the multimeasure rests automatically adds the
+appropriate number.
@cindex lyrics expressions
example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
with quarter note duration. Note that the hyphen has no special
meaning for lyrics, and does not introduce special symbols. See
-section XREF-modes [FIXME] for a description of what is interpreted as
+section @ref{Lexical modes} for a description of what is interpreted as
lyrics.
Spaces can be introduced into a lyric either by using quotes
(`@code{"}') or by using an underscore without quotes: `@code{He_could4
not4}'. All unquoted underscores are converted to spaces. Printing
-lyrics is discussed in section XREF-lyricprint [FIXME].
+lyrics is discussed in section @ref{lyricprint}.
you need to know exactly how the backend works. Example:
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\relative c'' { c4
\context Staff \outputproperty
#(make-type-checker 'Note_head)
#'extra-offset = #'(5.0 . 7.5)
<c8 e g> }
-@end mudela
+@end lilypond
This selects all note heads occurring at current staff level, and sets
the extra-offset of those heads to (5,7.5), shifting them up and
right.
Use of this feature is entirely on your own risk: if you use this, the
-result will depend very heavily on the implentation of the backend,
-which we change unscrupulously.
-
-
+result will depend very heavily on the implementation of the backend,
+which we change regularly and unscrupulously.
@cindex commands
are also defined.
@example
-
@code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
@end example
Specify an arbitrary key signature. The pitches from @var{pitch} will
be printed in the key signature in the order that they appear on the
list.
-
@example
\mark@keyindex{mark} @var{unsigned};
\mark @var{string};
@end example
-Prints a mark over or under (depending on the
-@code{markDirection}@indexcode{markDirection} property) the staff. You must add
-@code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for
+Prints a mark over or under the staff. You must add
+@code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
this to work.
@node barlines, , , Reference Manual
\bar@keyindex{bar} @var{bartype};
@end example
-This is a request to print a special bar symbol. It replaces the
-regular bar symbol with a special
-symbol. The argument @var{bartype} is a string which specifies the
-kind of bar to print. Options are @code{":|"}
-@cindex "|A@@@code{:|}
-,
-@code{"|:"}
-@cindex "|B@@@code{|:}
-, @code{":|:"}
-@cindex "|C@@@code{:|:}
-,
-@code{"||"}
-@cindex "|D@@@code{||}
-, @code{"|."}
-@cindex "|E@@@code{|.}
-,
-@code{".|"}
-@cindex "|F@@@code{.|}
-, and @code{".|."}
-@cindex "|G@@@code{.|.}
-.
-These produce, respectively, a right repeat, a left repeat, a double
-repeat, a double bar, a start bar, an end bar, and a thick double
-bar. If @var{bartype} is set to @code{"empty"} then nothing is
-printed, but a line break is allowed at that spot.
-
-You are encouraged to use @code{\repeat} for repetitions.
-See section XREF-sec-repeats [FIXME].
+This is a short-cut for doing
+@example
+ \property Score.whichBar = @var{bartype}
+@end example
-
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeats}, and the documentation of @code{whichBar}.
@example
-
\time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
@end example
-Change the time signature. The default time signature is 4/4.
-The time signature is used to generate bar lines.
+A short-cut for doing
+@example
+ \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
+@end example
+
+See the documentation of @code{timeSignatureFraction}
@example
requests output with 76 quarter notes per minute.
@example
-
\partial@keyindex{partial} @var{duration} @code{;}
@end example
+Short cut for
+
+@example
+ \property Score.measurePosition = @var{length of duration}
+@end example
+
+See the documentation of @code{measurePosition}.
+
@cindex anacrusis
@cindex upstep
-This creates an incomplete measure (anacrusis, upbeat) at the start of
-the music, e.g., `@code{\partial 8*2;}' creates a starting measure
-lasting two eighth notes.
-
@example
@code{|}@indexcode{|}
@cindex upstep
-`@code{|}' is a barcheck. Whenever a barcheck is encountered during
+`@code{|}' is a bar check. Whenever a bar check is encountered during
interpretation, a warning message is issued if it doesn't fall at a
-measure boundary. This can help you finding errors in the input.
-The beginning of the measure will be relocated, so this can also
-be used to shorten measures.
+measure boundary. This can help you finding errors in the input.
+Depending on the value of @code{barCheckNoSynchronize}
+@indexcode{barCheckNoSynchronize} The beginning of the measure will be
+relocated, so this can also be used to shorten measures.
@example
section [on identifiers] [FIXME].
@example
-
\clef@keyindex{clef} @var{clefname} @code{;}
@end example
-Music expression that sets the current clef. The argument is a
-string which specifies the name of the clef. Several clef names are
-supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef
-name, then the clef lowered or raised an octave will be generated.
-Here are the supported clef names with middle C shown in each
-clef:
-
-@quotation
-
-@mudela[]
-\score {
- \notes {
- \cadenzaOn
- %\property Voice.textStyle = typewriter
- \clef subbass; c'4-"\kern -5mm subbass"
- \clef bass; c'4^"\kern -2mm bass"
- \clef baritone; c'4_"\kern -5mm baritone"
- \clef varbaritone; c'4^"\kern -6mm varbaritone"
- \clef tenor; c'4_"\kern -3mm tenor"
- \clef "G_8"; c'4^"\kern -2mm G\\_8"
- }
- \paper {
- linewidth = -1.0;
- }
-}
-@end mudela
-@end quotation
+Short-cut for
-@quotation
+@example
+ \property Clef.clefGlyph = @var{symbol associated with clefname}
+ \property Clef.clefPosition = @var{clef Y-position for clefname}
+ \property Clef.clefOctavation = @var{extra pitch of clefname}
+@end example
-@mudela[]
-\score {
- \notes {
- \cadenzaOn
- \clef alto; c'4_"\kern -2mm alto"
- \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano"
- \clef soprano; c'4_"\kern -6mm soprano"
- \clef treble; c'4^"\kern -4mm treble"
- \clef french; c'4_"\kern -4mm french"
- }
- \paper {
- linewidth = 4.5 \in;
- }
-}
-@end mudela
-@end quotation
+Supported clef-names include
-The three clef symbols can also be obtained using the names `@code{G}',
-`@code{C}' or `@code{F}', optionally followed by an integer which
-indicates at which note line the clef is located. An as example, the
-@code{mezzosoprano} clef can also be given as `@code{C2}'.
+[todo]
@example
A beam is specified by surrounding the beamed notes with brackets
`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
[a'8 a'] [a'16 a' a' a']
-@end mudela
+@end lilypond
Some more elaborate constructions:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
[a'16 <a' c''> c'' <a' c''>]
\times 2/3 { [e'8 f' g'] }
-@end mudela
+@end lilypond
-Beaming can be generated automatically; see section XREF-autobeam [FIXME].
+Beaming can be generated automatically; see section @ref{autobeam}.
[OUTDATED, FIXME]
-To place tremolo marks
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
@cindex tremolo beams
- between two notes, begin
-with `@code{[:}@var{length}' and end with `@code{]}'. Tremolo marks
-will appear instead of beams. Putting more than two notes in such a
-construction will produce odd effects. To create tremolo beams on a
-single note, simply attach `@code{:}@var{length}' to the note itself
-(see also section XREF-tremolo [FIXME]).
-
-@ignore
-@mu dela[fragment,verbatim,center]
- [:16 e'1 g'] [:8 e'4 f']
-@end mudela
-
-@mud ela[fragment,verbatim,center]
- c'4:32 [:16 c'8 d'8]
-@end mudela
-@end ignore
+To create tremolo beams on a single note, simply attach
+`@code{:}@var{length}' to the note itself.
+
+@lilypond[fragment,verbatim,center]
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+@end lilypond
+
+@lilypond[fragment,verbatim,center]
+ c'4:32
+@end lilypond
+
@cindex --@@@code{-}@code{-}
If you try to tie together chords which have no common pitches, a
warning message will appear and no ties will be created.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
e' ~ e' <c' e' g'> ~ <c' e' g'>
-@end mudela
+@end lilypond
respectively. Here is a chart showing symbols above notes, with the
name of the corresponding symbol appearing underneath.
-@mudela[]
+@lilypond[]
\score {
< \notes {
}
}
-@end mudela
+@end lilypond
In addition, it is possible to place arbitrary strings of text or
@TeX{} above or below notes by using a string instead of an
supported) and single characters shorthands exist for a few
common symbols
-@mudela[]
+@lilypond[]
\score {
\notes {
}
}
-@end mudela
+@end lilypond
Dynamic marks are specified by using an identifier after a note:
`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
first note in the slur. This makes it possible to put a note in
slurs from both sides:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
-@end mudela
+@end lilypond
@cindex crescendo
bound to notes, if you want to get several marks during one note, you
must use spacer notes.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c'' \< \! c'' d'' \decr e'' \rced
< f''1 { s4 \< \! s2 \> \! s4 } >
-@end mudela
+@end lilypond
@example
You can attach a (general) span request to a note using
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
c'4-\spanrequest \start "slur"
c'4-\spanrequest \stop "slur"
-@end mudela
+@end lilypond
The slur syntax with parentheses is a shorthand for this.
used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
no last value.
-@mudela[verbatim,fragment,center]
+@lilypond[verbatim,fragment,center]
c'2:8 c':32
-@end mudela
+@end lilypond
expressions any way you like. This simple example shows how three
chords can be expressed in two different ways:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\notes \context Staff {
\cadenzaOn
<a c'> <b d' > <c' e'>
< { a b c' } { c' d' e' } >
}
-@end mudela
+@end lilypond
@cindex context selection
@c @keyindex{context}
Interpret @var{musicexpr} within a context of type @var{contexttype}.
If the context does not exist, it will be created. The new context
-can optionally be given a name. See
-section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more
-information on interpretation contexts.
-
-
+can optionally be given a name.
@cindex input modes
@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
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. See section XREF-modes [FIXME] for more
+be parsed in indicated mode. See @ref{Lexical modes} for more
information on modes.
-More information on context selection can be found in
-section XREF-contextselection [FIXME].
-
-
-
@cindex sequential music
If you try to use a chord as the first thing in your score, you might
get multiple staffs instead of a chord.
-@mudela[verbatim,center]
+@lilypond[verbatim,center]
\score {
\notes <c''4 e''>
\paper {
linewidth = -1.;
}
}
-@end mudela
+@end lilypond
This happens because the chord is interpreted by a score context.
Each time a note is encountered a default Voice context (along with a
Staff context) is created. The solution is to explicitly instantiate
a Voice context:
-@mudela[verbatim,center]
+@lilypond[verbatim,center]
\score {
\notes\context Voice <c''4 e''>
\paper {
linewidth = -1.;
}
}
-@end mudela
+@end lilypond
Entering scales is straightforward in relative mode.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\relative c' {
c d e f g a b c c,
}
-@end mudela
+@end lilypond
And octave changing marks are used for intervals greater than a fourth.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\relative c'' {
c g c f, c' a, e'' }
-@end mudela
+@end lilypond
If the preceding item is a chord, the first note of the chord is used
to determine the first note of the next chord. But other notes
within the second chord are determined by looking at the immediately
preceding note.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\relative c' {
c <c e g>
<c' e g>
<c, e' g>
}
-@end mudela
+@end lilypond
The pitch after the @code{\relative} contains a notename. To parse
the pitch as a notename, you have to be in note mode, so there must
Chord names are a way to generate simultaneous music expressions that
correspond with traditional chord names. It can only be used in
-Chord mode (see section XREF-modes [FIXME]).
+Chord mode (see section @ref{Lexical modes}).
@example
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\transpose c'' {
\chords {
c1 c:3- c:7 c:8
}
}
-@end mudela
+@end lilypond
@end quotation
The second type of modifier that may appear after the `@code{:}' is a
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\transpose c'' {
\chords {
c1:m c:min7 c:maj c:aug c:dim c:sus
}
}
-@end mudela
+@end lilypond
@end quotation
notes to be subtracted are listed after a `@code{^}' character,
separated by dots.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\transpose c'' {
\chords {
c1^3 c:7^5.3 c:8^7
}
}
-@end mudela
+@end lilypond
Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
the name of a single note to a chord. This has the effect of
note in the chord. If the specified note is not in the chord, a
warning will be printed.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\transpose c''' {
\chords {
c1 c/e c/g c:7/e
}
}
-@end mudela
+@end lilypond
Bass notes can be added by `@code{/+}@indexcode{/+}' and
the name of a single note to a chord. This has the effect of
adding the specified note to the chord, lowered by an octave,
so it becomes the lowest note in the chord.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
\transpose c''' {
\chords {
c1 c/+c c/+g c:7/+b
}
}
-@end mudela
+@end lilypond
Throughout these examples, chords have been shifted around the staff
using @code{\transpose}.
which 3 notes have the length of 2, so the notes are 2/3 of
their written length:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
g'4 \times 2/3 {c'4 c' c'} d'4 d'4
-@end mudela
+@end lilypond
this score-within-a-score, you can create notes, beams, slurs, etc.
Unbeamed eighth notes and shorter by default have a slash through the
stem. This behavior can be controlled with the
-@code{stemStyle}@indexcode{stemStyle} property.
+@code{flagStyle}@indexcode{flagStyle} property.
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\relative c'' {
\grace c8 c4 \grace { [c16 c16] } c4
- \grace { \property Grace.stemStyle = "" c16 } c4
+ \grace { \property Grace.flagStyle = "" c16 } c4
}
-@end mudela
+@end lilypond
@end quotation
At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
c'1
\repeat volta 2 { c'4 d' e' f' }
\repeat volta 2 { f' e' d' c' }
-@end mudela
+@end lilypond
@end quotation
With alternative endings:
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
c'1
\repeat volta 2 {c'4 d' e' f'}
\alternative { {d'2 d'} {f' f} }
-@end mudela
+@end lilypond
@end quotation
Folded repeats look like this:@footnote{Folded repeats offer little
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
c'1
\repeat fold 2 {c'4 d' e' f'}
\alternative { {d'2 d'} {f' f} }
-@end mudela
+@end lilypond
@end quotation
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\context Staff {
\relative c' {
\partial 4;
}
}
-@end mudela
+@end lilypond
@end quotation
If you don't give enough alternatives for all of the repeats, then
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\context Staff {
\relative c' {
\repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
}
}
-@end mudela
+@end lilypond
@end quotation
It is possible to nest @code{\repeat}. This is not entirely
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
\context Staff {
\clef "F";
- { \key e; c d e f }
+ { \key e \major; c d e f }
\clef "G";
- \transpose des'' { \key e; c d e f }
- \transpose cis'' { \key e; c d e f }
+ \transpose des'' { \key e \major; c d e f }
+ \transpose cis'' { \key e \major; c d e f }
}
-@end mudela
+@end lilypond
@end quotation
If you want to use both @code{\transpose} and @code{\relative}, then
@quotation
-@mudela[verbatim,fragment]
+@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
- \property Voice.automaticMelismata = "1"
+ \property Voice.automaticMelismata = ##t
c8 () cis d8. e16 f2
}
\context Lyrics \lyrics {
do4 re mi fa }
-@end mudela
+@end lilypond
@end quotation
You should use a single rhythm melody, and single rhythm lyrics (a
@quotation
-@mudela[verbatim,fragment]
+@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
c8 () cis d8. e16 f2
< { do4 re mi fa }
{ do8 re mi fa } >
-@end mudela
+@end lilypond
@end quotation
It is valid (but probably not very useful) to use notes instead of
By default, LilyPond will generate beams automatically. This feature
can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
property to 1. It can be overridden for specific cases by
-specifying explicit beams as described in
-section XREF-manualbeam [FIXME].
+specifying explicit beams.
+
A large number of Voice properties are used to decide how to generate
beams. Their default values appear in @file{auto-beam-settings.ly}.
@quotation
-@mudela[fragment,verbatim]
+@lilypond[fragment,verbatim]
<
\context ChordNames {
\chords{a b c} \notes{<d f g> <e g b>}
}
>
-@end mudela
+@end lilypond
@end quotation
LilyPond examines chords specified as lists of notes to determine a
name to give the chord. By default, LilyPond will not try to
identify chord inversions:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
<
\context ChordNameVoice \notes {
<e'1 g' c''>
<e'1 g' c''>
}
>
-@end mudela
+@end lilypond
If you want inversions to be recognized, you must set the property
@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
<
- \property Score.chordInversion = 1
+ \property Score.chordInversion = ##t
\context ChordNameVoice \notes {
<e'1 g' c''>
}
<e'1 g' c''>
}
>
-@end mudela
+@end lilypond
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
<
\notes \transpose c'' {
>
}
-@end mudela
+@end lilypond
@end quotation
You may want a continuous line after the syllables to show melismata.
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
<
\notes \relative c'' {
>
}
-@end mudela
+@end lilypond
@end quotation
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
<
\notes \transpose c'' {
>
}
-@end mudela
+@end lilypond
@end quotation
@quotation
-@mudela[verbatim]
+@lilypond[verbatim]
\score {
\notes \relative c'' {
c4 <d4 \context Staff = "another" e4> f
}
}
-@end mudela
+@end lilypond
@end quotation
In this example, the @code{c} and @code{d} are printed on the
doesn't result in this:
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
}
}
-@end mudela
+@end lilypond
For the @code{c4}, a default @code{Staff} (with a contained
@code{Voice}) context is created. After the @code{c4} ends, no
in the initialization file @file{ly/engraver.ly}.
@table @samp
- @item @code{Grace}@indexcode{Grace}
- The context for handling grace notes. It is instantiated
- automatically when you use @code{\grace}. Basically, it is an
- `embedded' miniature of the Score context. Since this context
- needs special interaction with the rest of LilyPond, you should
- not explicitly instantiate it.
-
- @item @code{LyricVoice}@indexcode{LyricVoice}
- Corresponds to a voice with lyrics. Handles the printing of a
- single line of lyrics.
-
- @item @code{Thread}@indexcode{Thread}
- Handles note heads, and is contained in the Voice context. You
- have to instantiate this explicitly if you want to adjust the
- style of individual note heads.
-
- @item @code{Voice}@indexcode{Voice}
- Corresponds to a voice on a staff. This context handles the
- conversion of dynamic signs, stems, beams, super- and subscripts,
- slurs, ties, and rests.
-
- You have to instantiate this explicitly if you want to have
- multiple voices on the same staff.
-
- @item @code{ChordNamesVoice}@indexcode{ChordNamesVoice}
- A voice with chord names. Handles printing of a line of chord
- names.
-
- @item @code{ChordNames}@indexcode{ChordNames}
- Typesets chord names. Can contain @code{ChordNamesVoice}
- contexts.
-
- @item @code{Lyrics}@indexcode{Lyrics}
- Typesets lyrics. It can contain @code{LyricVoice} contexts.
-
- @item @code{Staff}@indexcode{Staff}
- Handles clefs, bar lines, keys, accidentals. It can contain
- @code{Voice} contexts.
-
- @item @code{RhythmicStaff}@indexcode{RhythmicStaff}
- A context like @code{Staff} but for printing rhythms. Pitches are
- ignored; the notes are printed on one line. It can contain
- @code{Voice} contexts.
-
- @item @code{GrandStaff}@indexcode{GrandStaff}
- Contains @code{Staff} or @code{RhythmicStaff} contexts. It adds a
- brace on the left side, grouping the staffs together. The bar
- lines of the contained staffs are connected vertically. It can
- contain @code{Staff} contexts.
-
- @item @code{PianoStaff}@indexcode{PianoStaff}
- Just like @code{GrandStaff} but with @code{minVerticalAlign} set
- equal to @code{maxVerticalAlign} so that interstaff beaming and
- slurring can be used.
-
- @item @code{StaffGroup}@indexcode{StaffGroup}
- Contains @code{Staff} or @code{RhythmicStaff} contexts. Adds a
- bracket on the left side, grouping the staffs together. The bar
- lines of the contained staffs are connected vertically. It can
- contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
- @code{Lyrics} contexts.
-
- @item @code{ChoirStaff}@indexcode{ChoirStaff}
- Identical to @code{StaffGroup} except that the contained staffs
- are not connected vertically.
-
- @item @code{Score}@indexcode{Score}
- This is the top level notation context. No other context can
- contain a @code{Score} context. This context handles the
- administration of time signatures. It also makes sure that items
- such as clefs, time signatures, and key-signatures are aligned
- across staffs. It can contain @code{Lyrics}, @code{Staff},
- @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
- @code{ChoirStaff} contexts.
-
- You cannot explicitly instantiate a Score context (since it is
- not contained in any other context). It is instantiated
- automatically when an output definition (a @code{\score} or
- @code{\paper} block) is processed.
@end table
@itemize @bullet
@item An assignment. The assignment must be terminated by a
- semicolon. See section XREF-papervars [FIXME] for information on
- paper variables.
+ semicolon.
- @item A context definition. See section XREF-contextdefs [FIXME] for
+ @item A context definition. See section @ref{contextdefs} for
more information on context definitions.
@item
dimensions will define the characeristics of all lines beyond
those explicitly specified.
- @item A font declaration. Its syntax is
+ @item \stylesheet declaration. Its syntax is
@example
-
- @var{fontsize} @code{=} \font@keyindex{font} @var{fontname}
+ \stylesheet @var{scm}
@end example
- @var{fontsize} is an integer describing the font to be used.
- 0 is the default font. @var{fontname} is the basename of
- a font (usually a member of the Feta family).
+
+ See font.scm for details of @var{scm}
@end itemize
@item @code{indent}@indexcode{indent}
The indentation of the first line of music.
- @item @code{interline}@indexcode{interline}
+ @item @code{staffspace}@indexcode{staffspace}
The distance between two staff lines, calculated from the center
of the lines. You should use either this or @code{rulethickness}
as a unit for distances you modify.
Sets the width of the lines. If set to -1.0, a single
unjustified line is produced.
- @item @code{output}@indexcode{output}
- Specifies an alternate name for the the output @file{s}.
- A @file{.tex}, @file{.midi} or @file{.ps} extension will be
- added to the string you specify.
+ @item @code{textheight}@indexcode{textheight}
+ Sets the total height of the music on each page. Only used by
+ ly2dvi.
+
+ @item @code{interscoreline}@indexcode{interscoreline}
+ Sets the spacing between the score lines. Defaults to 16 pt.
- @item @code{rulethickness}@indexcode{rulethickness}
+ @item @code{interscorelinefill}@indexcode{interscorelinefill}
+ If set to a positive number, the distance between the score
+ lines will stretch in order to fill the full page. In that
+ case @code{interscoreline} specifies the minimum spacing.
+ Defaults to 0.
+
+ @item @code{stafflinethickness}@indexcode{stafflinethickness}
Determines the thickness of staff and bar lines.
@end table
@itemize @bullet
@item @code{\consists} @var{engravername} @code{;}
Add @var{engravername} to the list of modules in this context.
- Section XREF-engravers [FIXME] contains an overview of the engravers
- available. The order of engravers added with @code{\consists} is
+ The order of engravers added with @code{\consists} is
significant.
@item @code{\consistsend} @var{engravername} @code{;}
@end quotation
-
-@node engravers, , , Reference Manual
-
-The engravers for paper output are:
-
-[incomplete, FIXME]
-
-@table @samp
- @item @code{Bar_engraver}@indexcode{Bar_engraver}
- Engraves bar lines. Normally in @code{Staff} and
- @code{RhythmicStaff}.
-
- @item @code{Bar_number_engraver}@indexcode{Bar_number_engraver}
- Engrave bar numbers. These numbers appear at the start of each
- line. Not normally in any translator. Can be added to
- @code{Score} for score-wide numbering or to @code{Staff} for
- numbering on each staff.
-
- @item @code{Beam_engraver}@indexcode{Beam_engraver}
- Handles beam requests by engraving beams. Normally appears in
- the @code{Voice} translator. If omitted, then notes will be
- printed with flags instead of beams.
-
- @item @code{Beam_req_swallow_translator}
- @indexcode{Beam_req_swallow_translator}
- Swallows beam requests. In @code{LyricVoice}.
-
- @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver}
- Engraves chord names. Normally in @code{ChordNameVoice} .
-
- @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver}
-
- @item @code{Clef_engraver}@indexcode{Clef_engraver}
- Engraves the clef symbol. Normally in @code{Staff}.
-
- @item @code{Collision_engraver}@indexcode{Collision_engraver}
-
- @item @code{Dot_column_engraver}@indexcode{Dot_column_engraver}
- Engraves dots on dotted notes shifted to the right of the note.
- Normally in @code{Voice}. If omitted, then dots appear on top of
- the notes.
-
- @item @code{Dynamic_engraver}@indexcode{Dynamic_engraver}
- Engraves dynamics symbols. Normally in @code{Voice}.
-
- @item @code{Font_size_engraver}@indexcode{Font_size_engraver}
-
- @item @code{Key_engraver}@indexcode{Key_engraver}
- Engraves the key signature. Normally in @code{Staff}.
-
- @item @code{Local_key_engraver}@indexcode{Local_key_engraver}
-
- @item @code{Lyric_engraver}@indexcode{Lyric_engraver}
- Engraves lyrics. Normally in @code{LyricVoice}.
-
- @item @code{Multi_measure_rest_engraver}
- @indexcode{Multi_measure_rest_engraver}
- Engraves multi-measure rests that are produced with @code{R}.
- Normally in @code{Voice}.
-
- @item @code{Piano_bar_engraver}@indexcode{Piano_bar_engraver}
-
- @item @code{Pitch_squash_engraver}@indexcode{Pitch_squash_engraver}
- Treat all pitches as middle C. Used in @code{RhythmicStaff}.
- Note that the notes move, but the locations of accidentals stay
- the same.
-
- @item @code{Priority_horizontal_align_engraver}
- @indexcode{Priority_horizontal_align_engraver}
-
- @item @code{Repeat_engraver}@indexcode{Repeat_engraver}
- Handles repeats? In @code{Staff} and @code{RhythmicStaff}.
-
- @item @code{Rest_collision_engraver}@indexcode{Rest_collision_engraver}
- Handles collisions of rests. In @code{Staff}.
-
- @item @code{Rest_engraver}@indexcode{Rest_engraver}
- Engraves rests. Normally in @code{Voice}.
-
- @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver}
-
- @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver}
-
- @item @code{Script_engraver}@indexcode{Script_engraver}
- Handles note ornaments generated by @code{\script}. Normally in
- @code{Voice}.
-
- @item @code{Separating_line_group_engraver}
- @indexcode{Separating_line_group_engraver}
-
- @item @code{Skip_req_swallow_translator}
- @indexcode{Skip_req_swallow_translator}
-
- @item @code{Slur_engraver}@indexcode{Slur_engraver}
- Engraves slurs. Normally in @code{Voice}.
-
- @item @code{Span_bar_engraver}@indexcode{Span_bar_engraver}
- Engraves lines across multiple staffs. Normally in
- @code{Staffgroup} and @code{GrandStaff}. Removing this from
- @code{StaffGroup} gives the definition of @code{ChoirStaff}.
-
- @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver}
-
- @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver}
-
- @item @code{Staff_margin_engraver}@indexcode{Staff_margin_engraver}
- Prints the name of the instrument (specified by
- @code{Staff.instrument} and @code{Staff.instr}) at the left of the
- staff.
-
- @item @code{Staff_sym_engraver}@indexcode{Staff_sym_engraver}
-
- @item @code{Stem_engraver}@indexcode{Stem_engraver}
- Engraves stems. Normally in @code{Voice}.
-
- @item @code{Ties_engraver}@indexcode{Ties_engraver}
- Engraves ties. Normally in @code{Voice}.
-
- @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver}
- Engraves the time signature. Normally in @code{Staff} and
- @code{RhythmicStaff}.
-
- @item @code{Timing_engraver}@indexcode{Timing_engraver}
- Responsible for synchronizing timing information from staffs.
- Normally in @code{Score}. In order to create polyrhythmic music,
- this engraver should be removed from @code{Score} and placed in
- @code{Staff}.
-
- @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver}
- Engraves tuplet brackets? In @code{Staff}.
-
- @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver}
-@end table
-
-
-
@node Sound output, , , Reference Manual
@section Sound output
@c @end quotation
-@cindex MIDI types and performers
-
-The types available for MIDI translators are:
-
-@table @samp
- @item @code{Performer_group_performer}@indexcode{Performer_group_performer}
- @item @code{Score_performer}@indexcode{Score_performer}
- @item @code{Staff_performer}@indexcode{Staff_performer}
-@end table
-
-The performers for MIDI translators are:
-
-@table @samp
- @item @code{Key_performer}@indexcode{Key_performer}
- @item @code{Time_signature_performer}@indexcode{Time_signature_performer}
- @item @code{Note_performer}@indexcode{Note_performer}
- @item @code{Lyric_performer}@indexcode{Lyric_performer}
- @item @code{Swallow_performer}@indexcode{Swallow_performer}
-@end table
-
-
@node Pre-defined Identifiers, , , Reference Manual
Force a line break in music by using a large argument for the
keyword @code{\penalty}.
- @item @code{\center}@keyindex{center}
- Used for setting direction properties. Equals 0.
-
- @item @code{\down}@keyindex{down}
- Used for setting direction setting properties. Is equal
- to -1.
-
- @item @code{\free}@keyindex{free}
- Used for setting direction setting properties. Is equal
- to 0.
-
- @item @code{\left}@keyindex{left}
- Used for setting text alignment property. Is equal to -1.
-
@item @code{\nobreak}@keyindex{nobreak}
Prevent a line break in music by using a large negative argument
for the keyword @code{\penalty}.
- @item @code{\none}@keyindex{none}
- Used for setting @code{Score.beamslopedamping} and
- @code{Score.beamquantisation} properties. Is equal to 0.
-
- @item @code{\normal}@keyindex{normal}
- Used for setting @code{Score.beamslopedamping} and
- @code{Score.beamquantisation} properties. Is equal to 1.
-
@item @code{\normalkey}@keyindex{normalkey}
Select normal key signatures where each octave has the same key
signature. This sets the @code{Staff.keyoctaviation} property.
- @item @code{\right}@keyindex{right}
- Used for setting text alignment property. Is set to 1.
-
- @item @code{\shiftoff}@keyindex{shiftoff}
- Disable horizontal shifting of note heads that collide. Sets the
- @code{Voice.horizontalNoteShift} property.
+ @item @code{\shiftoff}@keyindex{shiftOff}
+ Disable horizontal shifting of note heads that collide.
- @item @code{\shifton}@keyindex{shifton}
+ @item @code{\shiftOn}@keyindex{shiftOn}
Enable note heads that collide with other note heads to be
- shifted horiztonally. Sets the @code{Voice.horizontalNoteShift}
- property.
+ shifted horiztonally.
- @item @code{\slurboth}@keyindex{slurboth}
- Allow slurs to be above or below notes. This sets the
- @code{Voice.slurVerticalDirection} property.
+ @item @code{\slurBoth}@keyindex{slurBoth}
+ Allow slurs to be above or below notes.
- @item @code{\slurdown}@keyindex{slurdown}
- Force slurs to be below notes. This sets the
- @code{Voice.slurVerticalDirection} property.
+ @item @code{\slurDown}@keyindex{slurDown}
+ Force slurs to be below notes.
- @item @code{\slurup}@keyindex{slurup}
- Force slurs to be above notes. This sets the
- @code{Voice.slurVerticalDirection} property.
+ @item @code{\slurUp}@keyindex{slurUp}
+ Force slurs to be above notes.
@item @code{\specialkey}@keyindex{specialkey}
Allow key signatures do differ in different octaves. This sets
the @code{Staff.keyoctaviation} property.
- @item @code{\stemboth}@keyindex{stemboth}
+ @item @code{\stemBoth}@keyindex{stemBoth}
Allow stems, beams, and slurs to point either upwards or
- downwards, decided automatically by LilyPond. This sets the
- @code{Voice.verticalDirection} property.
+ downwards, decided automatically by LilyPond.
@item @code{\stemdown}@keyindex{stemdown}
- Force stems, beams, and slurs to point down. This sets the
- @code{Voice.verticalDirection} property.
+ Force stems, beams, and slurs to point down.
- @item @code{\stemup}@keyindex{stemup}
- Force stems, beams and slurs to point up. This sets the
- @code{Voice.verticalDirection} property.
+ @item @code{\stemUp}@keyindex{stemUp}
+ Force stems, beams and slurs to point up.
- @item @code{\traditional}@keyindex{traditional}
- Used for setting the @code{Score.beamquantisation} property. Is
- equal to 2.
-
- @item @code{\up}@keyindex{up}
- Used for setting various direction properties. Is equal
- to 1.
@end table
+
+@node Grobs, , , Reference Manual
+@section Grobs
+
+This section is about Grobs (short for Graphical Objects), which are
+formatting objects used to create the final output. This material is
+normally the domain of LilyPond gurus, but occasionally, a normal user
+also has to deal with grobs.
+
+The most simple interaction with Grobs are when you use
+@code{\override}:
+
+@example
+ \property Voice.Stem \override #'direction = #1
+@end example
+
+This piece of lily input causes all stem objects to be stem-up
+henceforth. In effect, you are telling lilypond to extend the defintion
+of the "Stem" grob with the setting @code{direction := 1}. Of course
+there are many more ways of customizing Lily output, and since most of
+them involve Grobs in some form, this section explains some details of
+how grobs work.
+
+@menu
+* What is a grob?::
+* Callbacks::
+* Setting grob properties::
+* Items and Spanners::
+* Pointer substitution::
+@end menu
+
+@node What is a grob?, , , Grobs
+
+All grobs have an X and Y-position on the page. These X and Y positions
+are stored in a relative format, so they can easily be combined by
+stacking them, hanging one grob to the side of another, and coupling
+them into a grouping-grob.
+
+Each grob has a reference point, or parent: the position of a grob is
+stored relative to that reference point. For example the X-reference
+point of a staccato dot usually is the note head that it applies
+to. Whenever the note head is moved, the staccato dot moves along
+automatically.
+
+If you keep following offset reference points, you will always end up at
+the root-object. This root object is called @code{Line_of_score}
+@ref{(lilypond-internals)Element Line_of_score}, and it represents a
+system (ie. a line of music).
+
+All grobs carry a set of grob-properties. In the Stem example above,
+the property @code{direction} is set to value @code{1}. The function
+that draws the symbol (@code{Stem::brew_molecule}) uses the value of
+@code{direction} to determine how to print the stem and the flag. The
+appearance of a grob is determined solely by the values of its
+properties.
+
+Often, a grob also is associated with a symbol. On the other hand, Some
+grobs do not print any symbols, but take care of grouping objects. For
+example, there is a separate grob that stacks staffs vertically, so they
+are not printed in overstrike. The NoteCollision @ref{(lilypond-internals)Element
+NoteCollision} is another example of an abstract grob. It only moves
+around chords, but doesn't print anything.
+
+A complete list of grob types is found in @ref{(lilypond-internals)Elements}
+
+Grobs are created in the "Interpreting music" phase, by things in
+LilyPond called engravers. In this phase of the translation, a load of
+grobs are created, and they are linked into a giant network of objects.
+This network of grobs forms the "specification" of the print
+problem. This problem is then solved: configurations, directions,
+dimensions, line breaks, etc. are calculated. Finally, the printing
+description in the form of Molecules (@ref{Molecule}) is extracted from
+the network. These are then dumped into the output file
+
+@node Callbacks, , , Grobs
+
+Offsets of grobs are relative to a parent reference point. Most
+positions are not known when an object is created, so these are
+calculated as needed. This is done by adding a callback for a specific
+direction.
+
+Suppose you have the following code in a .ly file.
+@example
+ #(define (my-callback gr axis)
+ (* 2.0 (get-gr-property grob 'direction))
+ )
+
+....
+
+ \property Voice.Stem \override #'Y-offset-callbacks = #(list
+ my-callback)
+@end example
+
+When the Y-offset of a Stem object is needed, LilyPond will
+automatically execute all callbacks for that object. In this case, it
+will find @code{my-callback}, and execute that. The result is that the
+stem is translated by two staff spaces in its direction.
+
+(note: Y-offset-callbacks is also a property)
+
+
+Offset callbacks can be stacked, ie.
+
+@example
+ \property .... \override #'Y-offset-callbacks = #(list
+ callback1 callback2 callback3)
+
+@end example
+
+The callbacks will be executed in the order callback3 callback2
+callback1. This is used for quantized positioning: the staccato dot is
+above or below a note head, and it must not be on a staff-line.
+
+To achieve this, for the staccato there are two callbacks: one callback
+that positions the grob above or below the note head, and one callback
+that rounds the Y-position of the grob to the nearest open space.
+
+Similarly, the size of a grob are determined through callbacks, settable
+with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
+There can be only one extent-callback for each axis. No callback (value #f)
+means: "empty in this direction". If you fill in a pair, that pair
+hard-codes the extent in that coordinate.
+
+
+@node Setting grob properties, , , Grobs
+
+Grob properties are stored as GUILE association lists, with symbols as
+keys. From C++, element properties can be accessed using the functions
+
+@example
+ SCM get_grob_property (SCM) const;
+ void set_grob_property (const char * , SCM val);
+ void set_immutable_grob_property (const char * , SCM val);
+ void set_immutable_grob_property (SCM key, SCM val);
+ void set_grob_property (SCM , SCM val);
+ void set_grob_pointer (const char*, SCM val);
+ SCM remove_grob_property (const char* nm);
+@end example
+
+In GUILE, LilyPond provides
+
+@example
+ ly-get-grob-property GROB SYMBOL
+ ly-set-grob-property GROB SYMBOL VALUE
+@end example
+
+All lookup functions identify undefined properties with
+end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
+
+Properties are stored in two ways:
+@itemize @bullet
+@item mutable properties:
+element properties that change from object to object. The storage of
+these are private to a grob. Typically this is used to store lists of
+pointers to other grobs
+
+@item immutable properties:
+element properties that are shared across different grobs of the same
+type. The storage is shared, and hence it is read-only. Typically, this
+is used to store function callbacks, and values for shared element
+properties are read from @file{scm/element-description.scm}.
+@end itemize
+
+There are two ways to manually set grob properties.
+
+You can change immutable grob properties. This is done with the
+\override syntax:
+
+@example
+ \property Voice.Stem \override #'direction = #1
+@end example
+
+This will push the entry @code{'(direction . 1)} on the immutable
+property list for stems, in effect overriding the setting from
+@file{scm/element-description.scm}. This can be undone by
+
+@example
+ \property Voice.stem \revert #'direction
+@end example
+
+If you use this a lot, this gets old quickly. So we also have a
+shorthand,
+
+@example
+ \property Context.GrobType \set #'prop = #VAL
+@end example
+
+this does a @code{\revert} followed by a @code{\override}
+
+The second way is \outputproperty. This construct looks like
+
+@example
+ \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
+@end example
+
+In this case, in every grob that satisfies @var{pred}, the property
+assignment @var{sym} = @var{val} is done. For example
+
+@example
+ \outputproperty
+ #(lambda (gr) (string? (ly-get-grob-property gr
+ 'text)))
+ #'extra-offset = #'(-1.0 . 0.0)
+@end example
+
+This shifts all elements that have a @code{text} property one staff
+space to the left.
+
+@node Items and Spanners, , , Grobs
+
+Grobs can also be distinguished in their role in the horizontal spacing.
+A lot of grobs define constraints on the spacing by their sizes. For
+example, note heads, clefs, stems, and all other symbols with a fixed
+shape. These grobs form a subtype called @code{Item}.
+
+Other grobs have a shape that depends on the horizontal spacing. For
+example, slur, beam, tie, etc. These grobs form a subtype called
+@code{Spanner}. All spanners have two span-points (these must be
+@code{Item}s), one on the left and one on the right. The left bound is
+also the X-reference point.
+
+Some items need special treatment for line breaking. For example, a
+clef is normally only printed at the start of a line (ie. after a line
+break). To model this, `breakable' items (clef, key signature, bar lines,
+etc.) are copied twice. Then we have three versions of each breakable
+item: one version if there is no line break, one version that is printed
+before the line break (at the end of a system), one version that is
+printed after the line break.
+
+Whether these versions are visible and take up space, is determined by
+the outcome of the visibility-lambda. This is a function taking a
+direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
+this grob should be transparent and invisible.
+
+@node Pointer substitution, , , Grobs
+
+
+@node Molecule, , , Reference Manual
+
+The objective of any typesetting system is to put ink on paper in the
+right places. For LilyPond, this final stage is left to the TeX and the
+printer subsystem. For lily, the last stage in processing a score is
+outputting a description of what to put where. This description roughly
+looks like
+
+@example
+ PUT glyph AT (x,y)
+ PUT glyph AT (x,y)
+ PUT glyph AT (x,y)
+@end example
+
+you merely have to look at the tex output of lily to see this.
+Internally these instructions are encoded in Molecules:@footnote{At some
+point LilyPond also contained Atom-objects, but they have been replaced
+by Scheme expressions.}. A molecule is an object that combines
+dimension information (how large is this glyph ?) with
+what-to-print-where.
+
+Conceptually, Molecules can be constructed from Scheme code, by
+translating a Molecule and by combining two molecules. In BNF notation:
+
+@example
+ Molecule = COMBINE Molecule Molecule
+ | TRANSLATE Offset Molecule
+ | GLYPH-DESCRIPTION
+ ;
+@end example
+
+(refer to the C++ code for more details). All visible,
+ie. non-transparent, grobs have a callback to create a Molecule. The
+name of the property is @code{molecule-callback}, and its value should
+be a Scheme function taking one argument (the grob) and returning a
+Molecule.
projects / lilypond.git / blobdiff