-
+@c Note:
+@c
+@c A menu is needed before every deeper *section nesting of @nodes
+@c Run M-x texinfo-all-menus-update
+@c to automagically fill in these menus
+@c before saving changes
+
+@c_{Reference Manual}
@node Reference Manual
@chapter Reference Manual
-
-
@menu
-* Overview:: Overview
-* Top level:: Top level
-* notenames::
-* Lexical conventions:: Lexical conventions
-* Other languages::
-* modes::
-* Types:: Types
-* Music expressions:: Music expressions
-* Atomic music expressions:: Atomic music expressions
-* Note specification::
-* barlines::
-* Manual beams::
-* stem tremolo::
-* Compound music expressions:: Compound music expressions
-* relative::
-* Repeats::
-* transpose::
-* Ambiguities:: Ambiguities
-* Notation conversion specifics::
-* autobeam::
-* lyricprint::
-* Notation Contexts:: Notation Contexts
-* Properties::
-* Notation output definitions:: Notation output definitions
-* paper::
-* Paper variables::
-* contextdefs::
-* engravers::
-* Sound output:: Sound output
-* midilist::
+* Overview::
+* Music constructs::
+* Modifying music::
+* Note entry::
+* Note specification::
+* Music notation::
+* Lyrics entry::
+* Chord entry::
+* Page layout::
+* Sound::
+* Music entry::
+* Engravers::
+* Lexer innards::
+* Unsorted::
@end menu
-
-
+@c_ {Overview}
@node Overview
@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.}
+This document
+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.
+
+This document has been revised for LilyPond 1.3.125
+
+[todo: ]
+
+There are two things to note here. The format contains musical
+concepts like pitches and durations, instead of symbols and positions:
+the input format tries to capture the meaning of @emph{music}, and not
+notation. Second, the format tries to be @emph{context-free}:
+a note will sound the same regardless of the current time signature,
+the key, etc.
-@emph{Mudela} is a language that allows you to
+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 esthetic decisions. All
+symbols and their placement is @emph{generated} from a high-level musical
+description. In other words, LilyPond would be best
+described by `music compiler' or `music to notation compiler'.
+LilyPond 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.
+ @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).
+
+ @item declarations: by declaring and naming musical expressions, you
+can enter and edit them in manageable chunks.
@end itemize
-@emph{Mudela} aims to define a piece of music completely, both from
-typesetting and from a performance point of view.
+@c_ {Music constructs}
+@node Music constructs
+@section Music constructs
+@cindex Music constructs
+@menu
+* Music expressions::
+* Sequential music::
+* Simultanious music::
+* Compound music expressions::
+* Grace music::
+* Explicit atomic music::
+@end menu
+@c_ {Music expressions}
+@node Music expressions
+@subsection Music expressions
-@node Top level
-@section Top level
+@cindex music expressions
-@cindex top level
+Music in LilyPond is entered as a music expression. Notes, rests,
+lyric syllables are music expressions (the atomic
+expressions),
+@cindex atomic music expressions
+and you can combine music expressions to form new ones. This example
+forms a compound expressions out of the quarter @code{c} note and a
+@code{d} note:
-This section describes what you may enter at top level.
+@example
+\sequential @{ c4 d4 @}
+@end example
+The meaning of this compound expression is to play the @code{c}
+first, and then the @code{d} (as opposed to playing them
+simultaneously, for instance).
+Atomic music expression are discussed in
+subsection @ref{Atomic music expressions}. Compound music expressions are
+discussed in subsection @ref{Compound music expressions}.
-@cindex score definition
-The output is generated combining a music expression with an output
-definition. A score block has the following syntax:
+@c_ {Sequential music}
+@node Sequential music
+@subsection Sequential music
+@cindex Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
@example
- \score @{ @var{musicexpr} @var{outputdefs} @}
+ \sequential @code{@{} @var{musicexprlist} @code{@}}
@end example
-@var{outputdefs} are zero or more output definitions. If no output
-definition is supplied, the default @code{\paper} block will be added.
-
-
+This means that list should be played or written in sequence, i.e.,
+the second after the first, the third after the second. The duration
+of sequential music is the the sum of the durations of the elements.
+There is a shorthand, which leaves out the keyword:
-@cindex header
+@example
+@cindex @code{<}
+@cindex @code{>}
-@keyindex{header}
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
-The syntax is
+@c_ {Simultanious music}
+@node Simultanious music
+@subsection Simultanious music
+@cindex Simultanious music
+@cindex @code{\simultaneous}
@example
- \header @{ @var{key1} = @var{val1};
- @var{key2} = @var{val2}; @dots{} @}
+ \simultaneous @code{@{} @var{musicexprlist} @code{@}}
@end example
-A header describes the file's contents. It can also appear in a
-@code{\score} block. Tools like @code{ly2dvi}@indexcode{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.
-
-It is customary to put the @code{\header} at the top of the file.
+It constructs a music expression where all of its arguments start at
+the same moment. The duration is the maximum of the durations of the
+elements. The following shorthand is a common idiom:
+@example
+ @code{<} @var{musicexprlist} @code{>}
+@end example
-@node notenames
-@section notenames
+If you try to use a chord as the first thing in your score, you might
+get multiple staffs instead of a chord.
-Note name tables can be specified using
+@lilypond[verbatim,center]
+ \score {
+ \notes <c''4 e''>
+ \paper {
+ linewidth = -1.;
+ }
+ }
+@end lilypond
-@example
- \notenames@keyindex{notenames}
- @{ @var{assignmentlist} @}
-@end example
+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:
-@var{assignmentlist} is a list of definitions of the form
+@lilypond[verbatim,center]
+ \score {
+ \notes\context Voice <c''4 e''>
+ \paper {
+ linewidth = -1.;
+ }
+ }
+@end lilypond
-@example
- @var{name} = @var{pitch}
-@end example
+@c_ {Compound music expressions}
+@node Compound music expressions
+@subsection Compound music expressions
-Chord modifiers can be set analogously, with
-@code{\chordmodifiers}@keyindex{chordmodifiers}.
+@cindex Compound music expressions
-A @code{\paper} block at top level sets the default paper block. A
-@code{\midi} block at top level works similarly.
+Music expressions are compound data structures. You can nest music
+expressions any way you like. This simple example shows how three
+chords can be expressed in two different ways:
+@lilypond[fragment,verbatim,center]
+ \notes \context Staff {
+ <a c'> <b d' > <c' e'>
+ < { a b c' } { c' d' e' } >
+ }
+@end lilypond
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. The following commands access the interpreter
-directly.
+@cindex @code{\context}
+@cindex context selection
@example
- \scm @keyindex{scm} @var{scheme} ;
+ \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
@end example
-Evaluates the specified Scheme code. The result is discarded.
+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.
+
+
+@c_ {Grace music} <-> Grace notes
+@node Grace music
+@subsection Grace music
+@cindex Grace music
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
+@cindex @code{graceAlignPosition}
@example
-\scmfile@keyindex{scmfile} @var{filename};
+ \grace @var{musicexpr}
@end example
-Reads Scheme code from the specified file. The result is discarded.
-
+A grace note expression has duration 0; the next real note is
+assumed to be the main note.
+You cannot have the grace note after the main note, in terms of
+duration, and main notes, but you can typeset the grace notes to the
+right of the main note using the property
+@code{graceAlignPosition}.
+@cindex @code{flagStyle}
-Identifier assignments may appear at top level. Semicolons are
-forbidden after top level assignments.
+When grace music is interpreted, a score-within-a-score is set up:
+@var{musicexpr} has its own time bookkeeping, and you could (for
+example) have a separate time signature within grace notes. While in
+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{flagStyle} property.
+@quotation
+@lilypond[fragment,verbatim]
+\relative c'' {
+ \grace c8 c4 \grace { [c16 c16] } c4
+ \grace { \property Grace.flagStyle = "" c16 } c4
+}
+@end lilypond
+@end quotation
+@cindex @code{\grace}
-@node Lexical conventions
-@section Lexical conventions
+At present, nesting @code{\grace} notes is not supported. The following
+may cause run-time errors:
+@example
+ @code{\grace @{ \grace c32 c16 @} c4}
+@end example
+Since the meaning of such a construct is unclear, we don't consider
+this a loss. Similarly, juxtaposing two @code{\grace} sections is
+syntactically valid, but makes no sense and may cause runtime errors.
-@cindex lexical conventions
+Ending a staff or score with grace notes may also generate a run-time
+error, since there will be no main note to attach the grace notes to.
+The present implementation is not robust and generally kludgy. We expect
+it to change after LilyPond 1.4
-@cindex comment
+@c_ {Explicit atomic music}
+@node Explicit atomic music
+@subsection Explicit atomic music
+@cindex Explicit atomic music
-@indexcode{%}
+@cindex pitch
-A one line comment is introduced by a `@code{%}' character.
-Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
-They cannot be nested.
+The syntax for pitch specification is
+@cindex @code{\pitch}
+@example
+ \pitch @var{scmpitch}
+@end example
+@var{scmpitch} is a pitch scheme object, see @ref{Pitch}.
-@cindex keyword
+In Note and Chord mode, pitches may be designated by names. See
+section @ref{Other languages} for pitch names in different languages.
-Keywords start with a backslash, followed by a number of lower case
-alphabetic characters. These are all the keywords.
+@cindex duration
+@cindex @code{\duration}
+The syntax for duration specification is
@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
+ \duration @var{scmduration}
@end example
+In Note, Chord, and Lyrics mode, durations may be designated by
+numbers and dots.
-@cindex integer
-Formed from an optional minus sign followed by digits. Arithmetic
-operations cannot be done with integers, and integers cannot be mixed
-with reals.
+@c_ {Modifying music}
+@node Modifying music
+@section Modifying music
+@cindex Modifying music
+@menu
+* Relative::
+* Transpose::
+* Repeat::
+* Times ::
+* Apply::
+* Transform::
+@end menu
+@c_ {Relative}
+@node Relative
+@subsection Relative
+@cindex Relative
+@cindex relative octave specification
+It is easy to get confused by octave changing marks and accidentally
+putting a pitch in the wrong octave. A much better way of entering a
+note's octave is `the relative octave' mode.
+@cindex @code{\relative}
+@example
+ \relative @var{startpitch} @var{musicexpr}
+@end example
-@cindex real
-
+The octave of notes that appear in @var{musicexpr} are calculated as
+follows: If no octave changing marks are used, the basic interval
+between this and the last note is always taken to be a fourth or
+less.@footnote{The interval is determined without regarding
+accidentals. A @code{fisis} following a @code{ceses} will be put above
+the @code{ceses}.} The octave changing marks @code{'} and @code{,}
+can then be added to raise or lower the pitch by an extra octave.
+Upon entering relative mode, an absolute starting pitch must be
+specified that will act as the predecessor of the first note of
+@var{musicexpr}.
-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{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
-`@code{/}@indexcode{/}', with parentheses for grouping.
+Entering scales is straightforward in relative mode.
-A real constant can be followed by one of the dimension
-keywords:
-@cindex dimensions
- @code{\mm}@keyindex{mm},
-@code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
-@code{\cm}@keyindex{cm}, for millimeters, points, inches and
-centimeters, respectively. This converts the number to a real that
-is the internal representation of dimensions.
+@lilypond[fragment,verbatim,center]
+ \relative c' {
+ c d e f g a b c c,
+ }
+@end lilypond
+And octave changing marks are used for intervals greater than a fourth.
+@lilypond[fragment,verbatim,center]
+ \relative c'' {
+ c g c f, c' a, e'' }
+@end lilypond
-@cindex string
-
+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.
-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.
+@lilypond[fragment,verbatim,center]
+ \relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+ }
+@end lilypond
+@cindex @code{\notes}
+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
+be a surrounding @code{\notes} keyword (which is not
+shown here).
-The tokenizer accepts the following commands. They can appear
-anywhere.
+The relative conversion will not affect @code{\transpose} or
+@code{\relative} sections in its argument. If you want to use
+relative within transposed music, you must place an additional
+@code{\relative} inside the @code{\transpose}.
-@example
- \maininput@keyindex{maininput}
-@end example
+It is strongly recommended to use relative pitch mode: less work,
+less error-prone, and more readable.
-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.
+@c_ {Transpose}
+@node Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
+A music expression can be transposed with @code{\transpose}. The syntax
+is
@example
- \include@keyindex{include} @var{file}
+ \transpose @var{pitch} @var{musicexpr}
@end example
-Include @var{file}. The argument @var{file} 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,
+This means that middle C in @var{musicexpr} is transposed to
+@var{pitch}.
-@example
- \version@keyindex{version} @var{string} ;
-@end example
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose cis'} or @code{\transpose des'} will transpose up half
+a tone. The first version will print sharps and the second version
+will print flats.
-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.
+@quotation
+@lilypond[fragment,verbatim]
+\context Staff {
+ \clef "F";
+ { \key e \major; c d e f }
+ \clef "G";
+ \transpose des'' { \key e \major; c d e f }
+ \transpose cis'' { \key e \major; c d e f }
+}
+@end lilypond
+@end quotation
+If you want to use both @code{\transpose} and @code{\relative}, then
+you must use @code{\transpose} first. @code{\relative} will have no
+effect music that appears inside a @code{\transpose}.
-@cindex other languages
+@c_ {Repeat}
+@node Repeat
+@subsection Repeat
+@cindex Repeat
+@cindex repeats
-@node Other languages
-@section Other languages
+@ref{Volta}
+[TODO: document #'repeatCommands.]
-Note name definitions have been provided in various languages.
-Simply include the language specific init file. For example:
-`@code{\include "english.ly"}'. The available language files and the
-names they define are:
+@cindex @code{\repeat}
-@example
- Note Names sharp flat
-nederlands.ly c d e f g a bes b -is -es
-english.ly c d e f g a bf b -s/-sharp -f/-flat
-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
-@end example
+In order to specify repeats, use the @code{\repeat}
+keyword. Since repeats look and sound differently when played or
+printed, there are a few different variants of repeats.
-Pitch names can be redefined using the
-@code{\notenames}@keyindex{notenames} command, see
-subsection XREF-notenames [FIXME].
+@table @asis
+@item unfolded
+Repeated music is fully written (played) out. Useful for MIDI
+output.
+@item volta
+This is the normal notation: Repeats are not written out, but
+alternative endings (voltas) are printed, left to right.
+@item folded
+Alternative endings are written stacked. Which is unfortunately not
+practical for anything right now.
-@cindex lexical modes
+@item tremolo
+Make tremolo beams.
+@end table
-@cindex modes
+The syntax for repeats is
-@node modes
-@section modes
+@example
+ \repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
-To simplify entering notes, lyrics, and chords, @emph{Mudela} 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
-a keyword or as an identifier. The behavior of the modes differs in
-two ways: Different modes treat unquoted words differently, and
-different modes have different rules for deciding what is a word.
+If you have alternative endings, you may add
-@table @code
- @item Normal mode.
-@cindex mode!normal
-
- At the start of parsing, @emph{Mudela} 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.
-
- @item Note mode.
-@cindex mode!note
-
- Note mode is introduced by the keyword
- @code{\notes}@keyindex{notes}. In Note mode, words can only
- contain alphabetic characters. If @code{word} is encountered,
- LilyPond first checks for a notename of @code{word}. If no
- notename is found, then @code{word} is treated as a string.
-
- Since combinations of numbers and dots are used for indicating
- durations, it is not possible to enter real numbers in this mode.
-
- @item Chord mode.
-@cindex mode!chord
-
- Chord mode is introduced by the keyword
- @code{\chords}@keyindex{chords}. It is similar to Note mode, but
- words are also looked up in a chord modifier table (containing
- @code{maj}, @code{dim}, etc).
-
- Since combinations of numbers and dots are used for indicating
- durations, you can not enter real numbers in this mode. Dashes
- and carets are used to indicate chord additions and subtractions,
- so scripts can not be entered in Chord mode.
-
- @item Lyrics mode.
-@cindex mode!lyric
-
- Lyrics mode is introduced by the keyword
- @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
- easy to include punctuation and diacritical marks in words. A
- word in Lyrics mode begins with: an alphabetic character,
- `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
- control characters @code{^A} through @code{^F}, @code{^Q} through
- @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
- over 127, or a two-character combination of a backslash followed
- by one of `@code{`}', `@code{'}', `@code{"}', or
- `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
- enter lyrics in @TeX{} format or a standard encoding without
- needing quotes. The precise definition of this mode indeed is
- ludicrous. This will remain so until the authors of LilyPond
- acquire a deeper understanding of character encoding, or someone
- else steps up to fix this.}
-
- Subsequent characters of a word can be any character that is not
- a digit and not white space. One important consequence of this
- 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
- 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
- are printable by @TeX{}.
+@cindex @code{\alternative}
+@example
+ \alternative @code{@{} @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @code{@}}
+@end example
-@example
-Ah! % a word
-2B_||_!2B % not a word because it starts with a digit
-``Hello'' % not a word because it starts with `
-_ _ _ _ % 4 words, each one a space
-@end example
+where each @var{alternative} is a Music expression.
- Since combinations of numbers and dots are used for indicating
- durations, you can not enter real numbers in this mode.
-@end table
+Normal notation repeats are used like this:
-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.}
+@quotation
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 { c'4 d' e' f' }
+ \repeat volta 2 { f' e' d' c' }
+@end lilypond
+@end quotation
-@node Types
-@section Types
+With alternative endings:
-@cindex types and identifiers
+@quotation
-@emph{Mudela} has a limited set of types:
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
-@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)
-@end itemize
+@end lilypond
+@end quotation
-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:
-`@code{\}@var{name}'. Identifier assignments must appear at top level
-in the @emph{Mudela} 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].
-
-@var{value} is any of the 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
-letter, being entirely alphanumeric. 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. 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.}
+Folded repeats look like this:@footnote{Folded repeats offer little
+more over simultaneous music. However, it is to be expected that
+more functionality -- especially for the MIDI backend -- will be
+implemented.}
+@quotation
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat fold 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
-@node Music expressions
-@section Music expressions
+@end lilypond
+@end quotation
-@cindex music expressions
+@quotation
-Music in @emph{Mudela} is entered as a music expression. Notes, rests,
-lyric syllables are music expressions (the atomic
-expressions)
-@cindex atomic music expressions
-, and you can combine
-music expressions to form new ones. This example forms a compound
-expressions out of the quarter @code{c} note and a @code{d}
-note:
+@lilypond[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \partial 4;
+ \repeat volta 2 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b1 } }
+ }
+}
-@example
-\sequential @{ c4 d4 @}
-@end example
+@end lilypond
+@end quotation
-The meaning of this compound expression is to play the `@code{c}'
-first, and then the `@code{d}' (as opposed to playing them
-simultaneously, for instance).
+If you don't give enough alternatives for all of the repeats, then
+the first alternative is assumed to be repeated often enough to equal
+the specified number of repeats.
-Atomic music expression are discussed in
-subsection XREF-atomicmusic [FIXME]. Compound music expressions are
-discussed in subsection XREF-compoundmusic [FIXME].
+@quotation
+@lilypond[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g }
+ {\partial 1; e4 e e }
+ {\partial 1; a a a a | b1 } }
+ }
+}
+@end lilypond
+@end quotation
+As you can see, LilyPond doesn't remember the timing information, nor
+are slurs or ties repeated. We hope to fix this after 1.4.
+It is possible to nest @code{\repeat}. This is not entirely
+supported: the notes will come be in the right places, but the repeat
+bars will not.
-@node Atomic music expressions
-@section Atomic music expressions
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
+@cindex tremolo beams
+To create tremolo beams on a single note, simply attach
+`@code{:}@var{length}' to the note itself.
+
+@lilypond[verbatim,center]
+\score {
+ \context Voice \notes\relative c' {
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+ \repeat "tremolo" 2 { c16 d16 }
+ }
+ \paper {
+ linewidth = 40*\staffspace;
+ }
+}
+@end lilypond
+@cindex @code{__}
+@lilypond[fragment,verbatim,center]
+ c'4:32
+@end lilypond
+@c_ {Times}
+@node Times
+@subsection Times
+@cindex Times
+@ref{Tuplets}
+Tuplets are made out of a music expression by multiplying their
+duration with a fraction.
-@cindex pitch
+@cindex @code{\times}
+@example
+ \times @var{fraction} @var{musicexpr}
+@end example
-@cindex duration
-
+The duration of @var{musicexpr} will be multiplied by the fraction.
+In print, the fraction's denominator will be printed over the notes,
+optionally with a bracket. The most common tuplet is the triplet in
+which 3 notes have the length of 2, so the notes are 2/3 of
+their written length:
-The syntax for pitch specification is
+@lilypond[fragment,verbatim,center]
+ g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@end lilypond
+@c_ {Apply}
+@node Apply
+@subsection Apply
+@cindex Apply
+Apply allows a Scheme-function to operate directly on the internal
+representation of music.
@example
- \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
+ \apply #@var{func} @var{music}
@end example
+The function takes two arguments, being a function and an musical
+argument for that function. The function should return a music
+expression.
-@var{octave} is specified by an integer, zero for the octave
-containing middle C. @var{note} is a number from 0 to 7, with 0
-corresponding to C and 7 corresponding to B. The shift is zero for a
-natural, negative to add flats, or positive to add sharps.
+This example replaces the text string of a script. It also shows a dump
+of the music it processes.
+@lilypond[verbatim]
+#(define (testfunc x)
+ (if (eq? (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.
+
+@c_ {Transform}
+@node Transform
+@subsection Transform
+@cindex Transform
+
+
+@c_ {Note entry}
+@node Note entry
+@section Note entry
+@cindex Note entry
-In Note and Chord mode, pitches may be designated by names. See
-section XREF-notelang [FIXME] for pitch names in different languages.
+@menu
+* Notes mode::
+* Pitch names::
+@end menu
-The syntax for duration specification is
+@c_ {Notes mode}
+@node Notes mode
+@subsection Notes mode
-@example
- \duration@keyindex{duration}
- @{ @var{length} @var{dotcount} @}
-@end example
+@cindex note mode
-@var{length} is the negative logarithm (base 2) of the duration:
-1 is a half note, 2 is a quarter note, 3 is an eighth
-note, etc. The number of dots after the note is given by
-@var{dotcount}.
+@cindex @code{\notes}
+Note mode is introduced by the keyword
+@code{\notes}. In Note mode, words can only
+contain alphabetic characters. If @code{word} is encountered,
+LilyPond first checks for a notename of @code{word}. If no
+notename is found, then @code{word} is treated as a string.
+
+Since combinations of numbers and dots are used for indicating
+durations, it is not possible to enter real numbers in this mode.
-In Note, Chord, and Lyrics mode, durations may be designated by
-numbers and dots. See Section XREF-notelang [FIXME] for details.
+@cindex Notes mode
+@c_ {Pitch names}
+@node Pitch names
+@subsection Pitch names
+@cindex Pitch names
@node Note specification
@section Note specification
-
-@cindex note specification
+@cindex Note specification
@cindex pitches
-
@cindex entering notes
A note specification has the form
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
+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 note names, 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 other languages.
+To use them, simply include the language specific init file. For
+example: @code{\include "english.ly"}. The available language files and
+the names they define are:
+
+@example
+ Note Names sharp flat
+nederlands.ly c d e f g a bes b -is -es
+english.ly c d e f g a bf b -s/-sharp -f/-flat
+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 sib si -d -b
+catalan.ly do re mi fa sol la sib si -d/-s -b
+@end example
+@cindex @code{'}
+@cindex @code{,}
+
+Pitch names can be redefined using the @code{\pitchnames} command, see
+@ref{Pitch names}.
+
-LilyPond has predefined sets of notenames for various languages. See
-section XREF-notelang [FIXME] for details.
The optional octave specification takes the form of a series of
-single quote (`@code{'}@indexcode{'}') characters or a series of comma
-(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
+single quote (`@code{'}') characters or a series of comma
+(`@code{,}') 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
-context. A reminder accidental
+LilyPond will determine what accidentals to typeset depending on the key
+and context, so alteration refer to what note is heard, not to whether
+accidentals are printed. A reminder accidental
@cindex reminder accidental
- can be
-forced by adding an exclamation mark `@code{!}' after the pitch. A
-cautionary accidental,
+@cindex @code{?}
+can be forced by adding an exclamation mark @code{!} after the pitch.
+A cautionary accidental,
@cindex cautionary accidental
- i.e., an
-accidental within parentheses can be obtained by adding the question
-mark `@code{?}@indexcode{?}' after the pitch.
-@mudela[fragment,verbatim,center]
- cis' d' e' cis' c'? d' e' c'!
-@end mudela
+i.e., an accidental within parentheses can be obtained by adding the
+question mark `@code{?}' after the pitch.
+@lilypond[fragment,verbatim,center]
+ cis' d' e' cis' c'? d' e' c'!
+@end lilypond
-@cindex duration
-Durations are entered as their reciprocal values. For notes longer
-than a whole note, use identifiers.
+@c_ {Rests}
+@menu
+* Rests::
+* Durations::
+* Multi measure rests::
+* Skip::
+@end menu
-@quotation
+@node Rests
+@subsection Rests
+@cindex Rests
-@example
-c'\longa c'\breve
-c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
-@end example
+Rests are entered like notes, with note name `@code{r}'.
+There is also a note name
+`@code{s}', which produces a space of the specified
+duration.
-@end quotation
-@quotation
+@c_ {Durations}
+@node Durations
+@subsection Durations
+@cindex Durations
-@mudela[]
-\score {
- \notes \relative c'' {
- a\longa a\breve
- a1 a2 a4 a8 a16 a32 a64 a64
- }
- \paper {
-%{ \translator {
- \StaffContext
- \remove "Clef_engraver";
- \remove "Staff_symbol_engraver";
- } %}
- }
-}
-@end mudela
-@end quotation
+Durations are entered as their reciprocal values. For notes longer
+than a whole note, use identifiers.
@quotation
@example
+c'\longa c'\breve
+c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64
@end example
-@end quotation
-
-@quotation
-@mudela[]
+@lilypond[]
\score {
\notes \relative c'' {
+ a\longa a\breve \autoBeamOff
+ a1 a2 a4 a8 a16 a32 a64 a64
r\longa r\breve
r1 r2 r4 r8 r16 r32 r64 r64
}
\paper {
- loose_column_distance = 2.5 * \interline;
- 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 "Time_signature_engraver";
+ \consists "Pitch_squash_engraver";
}
}
}
-@end mudela
+@end lilypond
@end quotation
-If the duration is omitted then it is set equal to the previous
-duration. If there is no previous duration, a quarter note is
-assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
-to obtain dotted note lengths.
-
-@mudela[fragment,verbatim,center]
- a'4. b'4.
-@end mudela
-
-You can alter the length of duration by writing
-`@code{*}@var{fraction}' after it. This will not affect the
-appearance of note heads or rests.
+As you can see, the longa is not printed. To get a longa note head, you
+have to use a different style of note heads. See [TODO].
+@cindex @code{.}
-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.
-
-
-@cindex lyrics expressions
-
-Syllables are entered like notes, with pitches replaced by text. For
-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
-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].
+If the duration is omitted then it is set equal to the previous duration
+entered. At the start of parsing there is no previous duration, so then
+a quarter note is assumed. The duration can be followed by a dot
+(`@code{.}') to obtain dotted note lengths.
-@cindex properties
+@lilypond[fragment,verbatim,center]
+ a'4. b'4.
+@end lilypond
+@cindex @code{r}
+@cindex @code{s}
-@example
- \property@keyindex{property}
- @var{contextname}.@var{propname} = @var{value}
-@end example
+You can alter the length of duration by writing `@code{*}@var{fraction}'
+after it. This will not affect the appearance of note heads or rests.
-Sets the @var{propname} property of the context @var{contextname} to
-the specified @var{value}. All three arguments are strings.
-Depending on the context, it may be necessary to quote the strings or
-to leave space on both sides of the dot.
+@c_ {Multi measure rests}
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex Multi measure rests
+@cindex @code{R}
+Multi_measure_rest are entered using `@code{R}'. It is specifically
+meant for entering parts: the rest can expand to fill a score with
+rests, or it can be printed as a single multimeasure rest This expansion
+is controlled by 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 translator switches
+@lilypond[fragment]
+ \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
+@end lilypond
-@example
- \translator@keyindex{translator}
- @var{contexttype} = @var{name}
-@end example
+Note that there is currently no way to condense multiple rests into a
+single multimeasure rest.
-A music expression indicating that the context which is a direct
-child of the a context of type @var{contexttype} should be shifted to
-a context of type @var{contexttype} and the specified name.
+@c_ {Skip}
+@node Skip
+@subsection Skip
+@cindex Skip
-Usually this is used to switch staffs in Piano music, e.g.
@example
- \translator Staff = top @var{Music}
+ \skip @var{duration} @code{;}
@end example
+@cindex @code{\skip}
+Skips the amount of time specified by @var{duration}. If no other
+music is played, a gap will be left for the skipped time with no
+notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
+this has the same effect as the spacer rest.
-@cindex output properties
-
-
-These allow you to tweak what is happening in the back-end
-directly. If you want to control every detail of the output
-formatting, this is the feature to use. The downside to this is that
-you need to know exactly how the backend works. Example:
-
-
-@mudela[fragment,verbatim]
-\relative c'' { c4
- \context Staff \outputproperty
- #(make-type-checker 'Note_head)
- #'extra-offset = #'(5.0 . 7.5)
-<c8 e g> }
-@end mudela
-
-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.
-@cindex commands
+@c_ {Music notation}
+@node Music notation
+@section Music notation
+@cindex Music notation
+@menu
+* Key::
+* Clef::
+* Time signature::
+* Spanners::
+* Ornaments::
+* Bar check::
+@end menu
-Commands are music expressions that have no duration.
+@c_ {Key}
+@node Key
+@subsection Key
+@cindex Key
+@cindex @code{\key}
@example
-
- @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
+ @code{\key} @var{pitch} @var{type} @code{;}
@end example
-
-Change the key signature. @var{type} should be
-@code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
-@var{pitch}-major or @var{pitch}-minor, respectively. The second
-argument is optional; the default is major keys. The @var{\context}
-argument can also be given as an integer, which tells the number of
-semitones that should be added to the pitch given in the subsequent
-@code{\key}@keyindex{key} commands to get the corresponding major key,
-e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
-mode names @code{\ionian}@keyindex{ionian},
-@code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
-@code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
-@code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
-are also defined.
-
+@cindex @code{\minor}
+@cindex @code{\major}
+@cindex @code{\minor}
+@cindex @code{\ionian}
+@cindex @code{\locrian}
+@cindex @code{\aeolian}
+@cindex @code{\mixolydian}
+@cindex @code{\lydian}
+@cindex @code{\phrygian}
+@cindex @code{\dorian}
+
+Change the key signature. @var{type} should be @code{\major} or
+@code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
+respectively. The second argument is optional; the default is major
+keys. The @var{\context} argument can also be given as an integer,
+which tells the number of semitones that should be added to the pitch
+given in the subsequent @code{\key} commands to get the corresponding
+major key, e.g., @code{\minor} is defined as 3. The standard mode names
+@code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
+@code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
+
+
+@c_ {Clef}
+@node Clef
+@subsection Clef
+@cindex Clef
+
+
+@c_ {Clef changes}
+@subsubsection Clef changes
+@cindex @code{\clef}
@example
-
- @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
+ \clef @var{clefname} @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.
+Short-cut for
-
@example
- \mark@keyindex{mark} @var{unsigned};
- \mark @var{string};
+ \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
-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
-this to work.
-
-@node barlines
-@section barlines
-
-@example
- \bar@keyindex{bar} @var{bartype};
-@end example
+Supported clef-names include
-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].
+[todo]
-
+@c_ {Time signature}
+@node Time signature
+@subsection Time signature
+@cindex Time signature
+@cindex meter
+@cindex @code{\time}
@example
-
- \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
+ \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
-
- \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
+ \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
@end example
-Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
-requests output with 76 quarter notes per minute.
-
-@example
+See the documentation of @code{timeSignatureFraction}
- \partial@keyindex{partial} @var{duration} @code{;}
-@end example
+@c_ {Partial}
+@subsubsection Partial
+@cindex Partial
@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.
-
+@cindex partial measure
+@cindex measure, partial
+@cindex shorten measures
+@cindex @code{\partial}
@example
+ \partial @var{duration} @code{;}
+@end example
- @code{|}@indexcode{|}
-@cindex bar check
+Short cut for
+@example
+ \property Score.measurePosition = @var{length of duration}
@end example
+@cindex @code{|}
-@cindex shorten measures
-
-@cindex upstep
+See the documentation of @code{measurePosition}.
-`@code{|}' is a barcheck. Whenever a barcheck 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.
-@example
+@c_ {Spanners}
+@node Spanners
+@subsection Spanners
+@cindex Spanners
- \penalty@keyindex{penalty} @var{int} @code{;}
-@end example
+@menu
+* Beam::
+* Slur::
+* Tie::
+* Tuplet::
+* Volta::
+* Crescendo and Decrescendo::
+* Text spanner::
+* Ottava::
+* Span requests::
+@end menu
+@c_ {Beam}
+@node Beam
+@subsubsection Beam
+@cindex Beam
+@c_ {Automatic beams}
+@unnumberedsubsubsec Automatic beams
-Discourage or encourage line breaks. See identifiers
-@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
-section [on identifiers] [FIXME].
+@cindex automatic beam generation
+@cindex autobeam
-@example
+@cindex @code{Voice.noAutoBeaming}
- \clef@keyindex{clef} @var{clefname} @code{;}
-@end example
+By default, LilyPond will generate beams automatically. This feature
+can be disabled by setting the @code{Voice.noAutoBeaming} property to
+true. It can be overridden for specific cases by specifying explicit
+beams.
-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:
+@cindex @code{Voice.autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+A large number of Voice properties are used to decide how to generate
+beams. Their default values appear in @file{scm/auto-beam.scm}. In
+general, beams can begin anywhere, but their ending location is
+significant. Beams can end on a beat, or at durations specified by the
+properties in
+@code{Voice.autoBeamSettings}.
+To end beams every quarter note, for example, you could set the property
+@code{(end * * * *)} to @code{(make-moment 1
+4)}. To end beams at every three eighth notes you would set
+it to @code{(make-moment 1 8)}.
+The same syntax can be used to specify beam
+starting points using
+@code{(begin * * * *)}, eg:
@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
+@example
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 1 4)
+\property Voice.autoBeamSettings \override
+ #'(begin * * * *) = #(make-moment 1 8)
+@end example
@end quotation
-@quotation
-
-@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
+To allow different settings for different time signatures, instead of
+the first two asterisks @code{* *} you can specify a time signature; use
+@code{(end N M * *)} to restrict the definition to
+`@var{N}@code{/}@var{M}' time. For example, to specify beams ending
+only for 6/8 time you would use the property @code{(end 6 8 * *)}.
-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}'.
+To allow different endings for notes of different durations, instead of
+th last two asterisks you can specify a duration; use @code{(end * * N
+M)} to restrict the definition to beams that contain notes of
+`@var{N}@code{/}@var{M}' duration.
-@example
+For example, to specify beam endings for beams that contain 32nd notes,
+you would use @code{(end * * 1 32)}.
- \skip@keyindex{skip} @var{duration} @code{;}
-@end example
-Skips the amount of time specified by @var{duration}. If no other
-music is played, a gap will be left for the skipped time with no
-notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
-this has the same effect as the space rest `@code{s}'.
+@c_ {Manual beams}
+@cindex Automatic beams
+@unnumberedsubsubsec Manual beams
-@cindex beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
-@node Manual beams
-@section Manual beams
+FIXME
+Beaming can be generated automatically; see section @ref{Automatic Beaming}.
A beam is specified by surrounding the beamed notes with brackets
-`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
+`@code{[}' and `@code{]}'.
-@mudela[fragment,verbatim,center]
+@lilypond[fragment,verbatim,center]
[a'8 a'] [a'16 a' a' a']
-@end mudela
-
-Some more elaborate constructions:
-
-@mudela[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].
-[OUTDATED, FIXME]
+@cindex @code{-}@code{-}
-To place tremolo marks
-@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
-@cindex --@@@code{-}@code{-}
+@c_ {Adjusting beams}
+@unnumberedsubsubsec Adjusting beams
+@cindex Adjusting beams
-@indexcode{__}
-@cindex extender
+@c_ {Slur}
-@cindex hyphen
+@node Slur
+@subsubsection Slur
+@cindex Slur
+
+@cindex slur
+
+Slurs connects chords and try to avoid crossing stems. A slur is
+started with @code{(} and stopped with @code{)}. The
+starting @code{(} appears to the right of the first note in
+the slur. The terminal @code{)} appears to the left of the
+first note in the slur. This makes it possible to put a note in
+slurs from both sides:
+
+@lilypond[fragment,verbatim,center]
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
+@end lilypond
-The syntax for an extender mark is `@code{__}'. This syntax can only
-be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
-a hyphen that will be printed between two lyric syllables) is
-`@code{-}@code{-}'.
+@c_ {Adjusting slurs}
+@unnumberedsubsubsec Adjusting slurs
+@c_ {Tie}
+@cindex Adusting slurs
+@node Tie
+@subsubsection Tie
+
+@cindex Tie
@cindex ties
+@cindex @code{~}
A tie connects two adjacent note heads of the same pitch. When used
with chords, it connects all of the note heads whose pitches match.
-Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
+Ties are indicated using the tilde symbol `@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
+[sparseTies]
-[TODO: explain Requests]
+@c_ {Tuplet}
+@node Tuplet
+@subsubsection Tuplet
+@cindex Tuplet
-@cindex articulations
+See @ref{Times}.
-@cindex scripts
+@c_ {Volta}
+@node Volta
+@subsubsection Volta
+@cindex Volta
-@cindex ornaments
+See @ref{Repeat}.
-A variety of symbols can appear above and below notes to indicate
+@c_ {Crescendo and Decrescendo}
+@node Crescendo and Decrescendo
+@subsubsection Crescendo and Decrescendo
+@cindex Crescendo and Decrescendo
+@cindex crescendo
+@cindex @code{\cr}
+@cindex @code{\rc}
+@cindex @code{\decr}
+@cindex @code{\rced}
+@cindex @code{\<}
+@cindex @code{\>}
+@cindex @code{\"!}
+
+
+
+A crescendo mark is started with @code{\cr} and terminated with
+@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
+started with @code{\decr} and terminated with @code{\rced}. There are
+also shorthands for these marks. A crescendo can be started with
+@code{\<} and a decrescendo can be started with @code{\>}. Either one
+can be terminated with @code{\!}. Note that @code{\!} must go before
+the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
+after the last note. Because these marks are bound to notes, if you
+want to get several marks during one note, you must use spacer notes.
+
+@lilypond[fragment,verbatim,center]
+ c'' \< \! c'' d'' \decr e'' \rced
+ < f''1 { s4 \< \! s2 \> \! s4 } >
+@end lilypond
+
+[todo: text cr]
+
+
+@c_ {Text spanner}
+@node Text spanner
+@subsubsection Text spanner
+@cindex Text spanner
+
+Have crescendo set a text spanner instead of hairpin
+
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.crescendoText = "cresc."
+ \property Voice.crescendoSpanner = #'dashed-line
+ a''2\mf\< a a \!a
+ }
+@end lilypond
+
+@c_ {Ottava}
+@node Ottava
+@subsubsection Ottava
+@cindex Ottava
+@unnumberedsubsubsec Ottava
+
+@lilypond[fragment,relative,verbatim]
+ a'''' b c a
+ \property Voice.TextSpanner \set #'type = #'dotted-line
+ \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
+ \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
+ \property Staff.centralCPosition = #-13
+ a\spanrequest \start "text" b c a \spanrequest \stop "text"
+@end lilypond
+
+
+
+@c_ {Text crescendo and decrescendo}
+@unnumberedsubsubsec Text crescendo and decrescendo
+
+TODO
+
+@c_ {Span requests}
+@node Span requests
+@subsubsection Span requests
+@cindex Span requests
+
+@cindex @code{\spanrequest}
+
+@example
+ \spanrequest @var{startstop} @var{type}
+@end example
+@cindex @code{\start}
+@cindex @code{\stop}
+
+Define 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. Supported types are @code{crescendo},
+@code{decrescendo}, @code{beam}, @code{slur}. This is an internal
+command. Users should use the shorthands which are defined in the
+initialization file @file{spanners.ly}.
+
+You can attach a (general) span request to a note using
+
+@lilypond[fragment,verbatim,center]
+ c'4-\spanrequest \start "slur"
+ c'4-\spanrequest \stop "slur"
+@end lilypond
+
+The slur syntax with parentheses is a shorthand for this.
+
+
+@c_ {Ornaments}
+@node Ornaments
+@subsection Ornaments
+@cindex Ornaments
+@menu
+* Articulation::
+* Text scripts::
+* Grace notes::
+* Stem tremolo::
+* Arpeggio::
+* Glissando ::
+* Dynamics::
+* Bar lines::
+* Breath marks::
+* Rehearsal marks::
+@end menu
+
+@c_ {Articulation}
+@node Articulation
+@subsubsection Articulation
+@cindex Articulation
+
+@cindex articulations
+@cindex scripts
+@cindex ornaments
+
+A variety of symbols can appear above and below notes to indicate
different characteristics of the performance. These symbols can be
added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
are defined in @file{script.ly} and @file{script.scm}. Symbols can be
respectively. Here is a chart showing symbols above notes, with the
name of the corresponding symbol appearing underneath.
-@mudela[]
+@lilypond[]
\score {
< \notes {
+ \property Score.LyricSyllable \override #'font-family =
+#'typewriter
+ \property Score.LyricSyllable \override #'font-shape = #'upright
c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
c''-\thumb c''-\segno c''-\coda
}
- \context Lyrics \lyrics {
+ \context Lyrics \lyrics {
accent__ marcato__ staccatissimo__ fermata
stopped__ staccato__ tenuto__ upbow
downbow__ lheel__ rheel__ ltoe
}
}
-@end mudela
+@end lilypond
+
+@c_ {Text scripts}
+@node Text scripts
+@subsubsection Text scripts
+@cindex Text scripts
+
+FIXME: markup
In addition, it is possible to place arbitrary strings of text or
@TeX{} above or below notes by using a string instead of an
-identifier: `@code{c^"text"}'. Fingerings
-@cindex fingering
- can be
-placed by simply using digits. All of these note ornaments appear in
-the printed output but have no effect on the MIDI rendering of the
-music.
+identifier: @code{c^"text"}. Fingerings
+can be placed by simply using digits. All of these note ornaments
+appear in the printed output but have no effect on the MIDI rendering of
+the music.
+
+@c_ {Fingerings}
+@unnumberedsubsubsec Fingerings
+@cindex Fingerings
To save typing, fingering instructions (digits 0 to 9 are
supported) and single characters shorthands exist for a few
common symbols
-@mudela[]
-
+@lilypond[]
\score {
- \notes {
- \property Voice.textStyle = typewriter
+ \notes \context Voice {
+ \property Voice.TextScript \set #'font-family = #'typewriter
+ \property Voice.TextScript \set #'font-shape = #'upright
c''4-._"c-." s4
c''4--_"c-{}-" s4
c''4-+_"c-+" s4
}
}
-@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})'.
-The available dynamic marks are:
-@code{\ppp}@keyindex{ppp},
-@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
-@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
-@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
-@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
-@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
-@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
-@code{\rfz}@keyindex{rfz}.
+@cindex @code{\textscript}
@example
- \textscript@keyindex{textscript} @var{text} @var{style}
+ \textscript @var{text} @var{style}
@end example
Defines a text to be printed over or under a note. @var{style} is a
@end quotation
-This is equivalent to `@code{c4-6 c4-"foo"}'.
-
+This is equivalent to @code{c4-6 c4-"foo"}.
+@cindex @code{\script}
@cindex scripts
@example
- \script@keyindex{script} @var{alias}
+ \script @var{alias}
@end example
+@cindex @code{\script}
-Prints a symbol above or below a note. The argument is a string
-which points into the script-alias table defined in @file{script.scm}.
-The scheme definitions specify whether the symbol follows notes into
-the staff, dependence of symbol placement on staff direction, and a
-priority for placing several symbols over one note. Usually the
-@code{\script}@keyindex{script} keyword is not used directly. Various
+Prints a symbol above or below a note. The argument is a string which
+points into the script-alias table defined in @file{scm/script.scm}, for
+information on how to add scripts, read the comments in that file.
+Usually the @code{\script} keyword is not used directly. Various
helpful identifier definitions appear in @file{script.ly}.
-@cindex slur
-
-Slurs connects chords and try to avoid crossing stems. A slur is
-started with `@code{(}' and stopped with `@code{)}'. The
-starting `@code{(}' appears to the right of the first note in
-the slur. The terminal `@code{)}' appears to the left of the
-first note in the slur. This makes it possible to put a note in
-slurs from both sides:
-
-@mudela[fragment,verbatim,center]
- f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
-@end mudela
-
-
-@cindex crescendo
-
-A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
-with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
-@code{\decr}@keyindex{decr} and terminated with
-@code{\rced}@keyindex{rced}. There are also shorthands for these
-marks. A crescendo can be started with @code{\<}@keyindex{<} and a
-decrescendo can be started with @code{\>}@keyindex{>}. Either one can
-be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
-must go before the last note of the dynamic mark whereas @code{\rc}
-and @code{\rced} go after the last note. Because these marks are
-bound to notes, if you want to get several marks during one note, you
-must use spacer notes.
-
-@mudela[fragment,verbatim,center]
- c'' \< \! c'' d'' \decr e'' \rced
- < f''1 { s4 \< \! s2 \> \! s4 } >
-@end mudela
-
-
-@example
-
- \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
-@end example
-
-Define a spanning request. The @var{startstop} parameter is either -1
-(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
-@var{type} is a string that describes what should be started.
-Supported types are @code{crescendo}, @code{decrescendo},
-@code{beam}, @code{slur}. This is an internal command. Users should
-use the shorthands which are defined in the initialization file
-@file{spanners.ly}.
-
-You can attach a (general) span request to a note using
-
-@mudela[fragment,verbatim,center]
- c'4-\spanrequest \start "slur"
- c'4-\spanrequest \stop "slur"
-@end mudela
-The slur syntax with parentheses is a shorthand for this.
+@c_ {Grace notes}
+@node Grace notes
+@subsubsection Grace notes
+@cindex Grace notes
+See @ref{Grace music}.
+@c_ {Stem tremolo}
+@node Stem tremolo
+@subsubsection Stem tremolo
@cindex tremolo marks
+@cindex @code{tremoloFlags}
-@node stem tremolo
-@section stem tremolo
+[FIXME: should be \repeat]
Tremolo marks can be printed on a single note by adding
`@code{:}[@var{length}]' after the note. The length must be at
least 8. A @var{length} value of 8 gives one line across
the note stem. If the length is omitted, then the last value is
-used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
+used, or the value of the @code{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
+@c_ {Arpeggio}
+@node Arpeggio
+@subsubsection Arpeggio
+@cindex Arpeggio
-@node Compound music expressions
-@section Compound music expressions
+@cindex broken arpeggio
+@cindex @code{\arpeggio}
-@cindex compound music expressions
+You can specify an @rgrob{Arpeggio} sign on a chord by issuing an
+@c FIXME
+@c @code{\arpeggio} request:
+@code{\arpeggio} request:
-Music expressions are compound data structures. You can nest music
-expressions any way you like. This simple example shows how three
-chords can be expressed in two different ways:
-@mudela[fragment,verbatim,center]
- \notes \context Staff {
- \cadenzaOn
- <a c'> <b d' > <c' e'>
- < { a b c' } { c' d' e' } >
- }
-@end mudela
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Voice <c'\arpeggio e g c>
+@end lilypond
+@end quotation
-@cindex context selection
-@c @keyindex{context}
+Typesetting of simultanious chords with arpeggios can be controlled with
+the property @code{PianoStaff.connectArpeggios} @footnote{ FIXME:
+connectArpeggios. Can't find the English terms for two kinds of
+arpeggio (Dutch: gebroken arpeggio vs doorlopend arpeggio).} By
+default, LilyPond prints broken arpeggios; when set to true, one
+extended arpeggio sign is printed.
-@example
- \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
-@end example
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.connectArpeggios = ##t
+ \context Staff \context Voice <c''\arpeggio e g c>
+ \context Staff=other \context Voice <c,\arpeggio e g>
+ >
+@end lilypond
+@end quotation
-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.
+@c_ {Glissando}
+@node Glissando
+@subsubsection Glissando
+@cindex Glissando
+@cindex @code{\glissando}
-@cindex input modes
+A @rgrob{Glissando} line can be requested by issuing a
+@c FIXME
+@c @code{\glissando} request:
+@code{\glissando} request:
-@cindex mode switch
-Mode switching keywords form compound music expressions: @code{\notes}
-@keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
-@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
-information on modes.
+@quotation
+@lilypond[fragment,relative,verbatim]
+ c'' \glissando c'
+@end lilypond
+@end quotation
-More information on context selection can be found in
-section XREF-contextselection [FIXME].
+Printing of the additional text @samp{gliss.} must be done manually.
+@c_ {Follow Thread}
+@subsubsection Follow Thread
+@cindex follow thread
+@cindex staff switching
+@cindex cross staff
-@cindex sequential music
+@c Documented here because it looks like a glissando...
+@cindex @code{followThread}
+A glissando-like line can be printed to connect notes whenever a thread
+switches to another staff. This is enabled if the property
+@code{PianoStaff.followThread} is set to true:
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.followThread = ##t
+ \context Staff \context Voice {
+ c'1
+ \translator Staff=two
+ b2 a
+ }
+ \context Staff=two {\clef bass; \skip 1*2;}
+ >
+@end lilypond
+@end quotation
-@example
- \sequential@keyindex{sequential}
- @code{@{} @var{musicexprlist} @code{@}}
-@end example
+@c_ {Dynamics}
+@node Dynamics
+@subsubsection Dynamics
+@cindex Dynamics
-This means that list should be played or written in sequence, i.e.,
-the second after the first, the third after the second. The duration
-of sequential music is the the sum of the durations of the elements.
-There is a shorthand, which leaves out the keyword:
+@unnumberedsubsec Dynamics
-@example
+@cindex @code{\ppp}
+@cindex @code{\pp}
+@cindex @code{\p}
+@cindex @code{\mp}
+@cindex @code{\mf}
+@cindex @code{\f}
+@cindex @code{\ff}
+@cindex @code{\fff}
+@cindex @code{\ffff}
+@cindex @code{\fp}
+@cindex @code{\sf}
+@cindex @code{\sff}
+@cindex @code{\sp}
+@cindex @code{\spp}
+@cindex @code{\sfz}
+@cindex @code{\rfz}
- @code{@{} @var{musicexprlist} @code{@}}
-@end example
+Dynamic marks are specified by using an identifier after a note:
+@code{c4-\ff} (the dash is optional for dynamics: `@code{c4 \ff})'.
+The available dynamic marks are:
+@code{\ppp},
+@code{\pp}, @code{\p}, @code{\mp},
+@code{\mf}, @code{\f}, @code{\ff},
+@code{\fff}, @code{\fff},
+@code{\fp}, @code{\sf},
+@code{\sff}, @code{\sp},
+@code{\spp}, @code{\sfz}, and
+@code{\rfz}.
+See also @ref{Crescendo and Decrescendo}
-@cindex simultaneous music
+@c_ {Bar lines}
+@node Bar lines
+@subsubsection Bar lines
+@cindex Bar lines
-@indexcode{<}
-@indexcode{>}
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
@example
+ \bar @var{bartype};
+@end example
- \simultaneous@keyindex{simultaneous}
- @code{@{} @var{musicexprlist} @code{@}}
+This is a short-cut for doing
+@example
+ \property Score.whichBar = @var{bartype}
@end example
-It constructs a music expression where all of its arguments start at
-the same moment. The duration is the maximum of the durations of the
-elements. The following shorthand is a common idiom:
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeat}, @ref{Volta}, and the documentation of @code{whichBar} in
+@ref{(lilypond-internals)LilyPond context properties}.
-@example
- @code{<} @var{musicexprlist} @code{>}
-@end example
+[FIXME]
-If you try to use a chord as the first thing in your score, you might
-get multiple staffs instead of a chord.
+@c_ {Breath marks}
+@node Breath marks
+@subsubsection Breath marks
+@cindex Breath marks
-@mudela[verbatim,center]
- \score {
- \notes <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
-@end mudela
+@c_ {Rehearsal marks}
+@node Rehearsal marks
+@subsubsection Rehearsal marks
+@cindex Rehearsal marks
+@cindex mark
+@cindex @code{\mark}
-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:
+@example
+ \mark @var{unsigned};
+@cindex @code{Mark_engraver}
+ \mark @var{string};
+@end example
-@mudela[verbatim,center]
- \score {
- \notes\context Voice <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
-@end mudela
+Prints a mark over or under the staff.
+@c_ {Bar check}
+@node Bar check
+@subsection Bar check
+@cindex Bar check
-@cindex relative pitch specification
+@cindex bar check
+@cindex @code{barCheckNoSynchronize}
+@cindex @code{|}
-@node relative
-@section relative
-It is easy to get confused by octave changing marks and accidentally
-putting a pitch in the wrong octave. A much better way of entering a
-note's octave is `the relative octave' mode.
+Bar checks help you find errors in the input: Whenever one is
+encountered during interpretation, a warning message is issued if it
+doesn't fall at a measure boundary. Depending on the value of
+@code{barCheckNoSynchronize}, the beginning of the measure will be
+relocated, so this can also be used to shorten measures.
-@example
+A bar check is entered using the bar symbol, @code{|}
- \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
-@end example
+This can help you finding errors in the input.
-The octave of notes that appear in @var{musicexpr} are calculated as
-follows: If no octave changing marks are used, the basic interval
-between this and the last note is always taken to be a fourth or
-less.@footnote{The interval is determined without regarding
-accidentals. A @code{fisis} following a @code{ceses} will be put above
-the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
-can then be added to raise or lower the pitch by an extra octave.
-Upon entering relative mode, an absolute starting pitch must be
-specified that will act as the predecessor of the first note of
-@var{musicexpr}.
-Entering scales is straightforward in relative mode.
+@c_ {Lyrics entry}
+@node Lyrics entry
+@section Lyrics entry
+@cindex Lyrics entry
-@mudela[fragment,verbatim,center]
- \relative c' {
- c d e f g a b c c,
- }
-@end mudela
+@menu
+* Lyrics mode::
+* Printing lyrics::
+* Lyric hyphen::
+* Lyric extender::
+* Addlyrics::
+@end menu
-And octave changing marks are used for intervals greater than a fourth.
+@c_ {Lyrics mode}
+@node Lyrics mode
+@subsection Lyrics mode
+@cindex Lyrics mode
+
+@cindex lyric mode
+@cindex @code{\lyrics}
+
+Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
+rules that make it easy to include punctuation and diacritical marks in
+words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
+format or a standard encoding without needing quotes. The precise
+definition of this mode is ludicrous, and this will remain so until the
+authors of LilyPond acquire a deeper understanding of character
+encoding, or someone else steps up to fix this.
+
+A word in Lyrics mode begins with: an alphabetic character, @code{_},
+@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
+through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
+any 8-bit character with ASCII code over 127, or a two-character
+combination of a backslash followed by one of @code{`}, @code{'},
+@code{"}, or @code{^}.
+
+Subsequent characters of a word can be any character that is not a digit
+and not white space. One important consequence of this is that a word
+can end with `@code{@}}', which may be confusing. However, LilyPond will
+issue a warning. Any @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 are printable by
+@TeX{}.
-@mudela[fragment,verbatim,center]
- \relative c'' {
- c g c f, c' a, e'' }
-@end mudela
+@example
+Ah! % a word
+2B_||_!2B % not a word because it starts with a digit
+``Hello'' % not a word because it starts with `
+_ _ _ _ % 4 words, each one a space
+@end example
-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.
+Since combinations of numbers and dots are used for indicating
+durations, you can not enter real numbers in this mode.
-@mudela[fragment,verbatim,center]
- \relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
- }
-@end mudela
+[todo: include short table showing differences]
-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
-be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
-shown here).
+@cindex lyrics expressions
-The relative conversion will not affect @code{\transpose} or
-@code{\relative} sections in its argument. If you want to use
-relative within transposed music, you must place an additional
-@code{\relative} inside the @code{\transpose}.
+Syllables are entered like notes, with pitches replaced by text. For
+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 @ref{Lexical modes} for a description of what is interpreted as
+lyrics.
-It is strongly recommended to use relative pitch mode: less work,
-less error-prone, and more readable.
+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 @ref{lyricprint}.
+@c_ {Printing Lyrics}
+@node Printing lyrics
+@subsection lyricprint
+@cindex lyrics
-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]).
-@example
+@cindex printing!lyrics
- @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
-@end example
-@var{tonic} should be the tonic note of the chord, and @var{duration}
-is the chord duration in the usual notation. There are two kinds of
-modifiers. One type is @emph{chord additions}, which are obtained by
-listing intervals separated by dots. An interval is written by its
-number with an optional `@code{+}' or `@code{-}' to indicate raising or
-lowering by half a step. Chord additions has two effects: It adds
-the specified interval and all lower odd numbered intervals to the
-chord, and it may lower or raise the specified interval. Intervals
-must be separated by a dot (`@code{.}').
+Lyric syllables must be interpreted within a @code{Lyrics} context
-@quotation
+@cindex context!Lyrics
+ for printing them.
-@mudela[fragment,verbatim]
-\transpose c'' {
- \chords {
- c1 c:3- c:7 c:8
- c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
- }
+Here is a full example:
+
+@quotation
+@lilypond[verbatim]
+\score {
+ <
+ \notes \transpose c'' {
+ c d e c | c d e c |
+ e f g2 | e4 f g2 \bar "|.";
+ }
+ \context Lyrics \lyrics {
+ Va-4 der Ja- cob Va- der Ja- cob
+ Slaapt gij nog?2 Slaapt4 gij nog?2
+ }
+ >
}
-@end mudela
+@end lilypond
@end quotation
-The second type of modifier that may appear after the `@code{:}' is a
-named modifier. Named modifiers are listed in the file
-@file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
-`@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
-raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
-`@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
-which replaces the 5th with a 4th.
+You may want a continuous line after the syllables to show melismata.
+To achieve this effect, add a @code{__} lyric as a separate word
+after the lyric to be extended. This will create an extender, a line
+that extends over the entire duration of the lyric. This line will
+run all the way to the start of the next lyric, so you may want to
+shorten it by using a blank lyric (using @code{_}).
@quotation
-@mudela[fragment,verbatim]
-\transpose c'' {
- \chords {
- c1:m c:min7 c:maj c:aug c:dim c:sus
- }
+@lilypond[verbatim]
+\score {
+ <
+ \notes \relative c'' {
+ a4 () b () c () d | c () d () b () a | c () d () b () a
+ }
+ \context Lyrics \lyrics {
+ foo1 __ | bar2. __ _4 | baz1 __
+ }
+ >
}
-@end mudela
+@end lilypond
@end quotation
-
-Chord subtractions are used to eliminate notes from a chord. The
-notes to be subtracted are listed after a `@code{^}' character,
-separated by dots.
-
-@mudela[fragment,verbatim,center]
- \transpose c'' {
- \chords {
- c1^3 c:7^5.3 c:8^7
- }
- }
-@end mudela
+
+If you want to have hyphens centered between syllables (rather than
+attached to the end of the first syllable) you can use the special
+`@code{-}@code{-}' lyric as a separate word between syllables. This
+will result in a hyphen which length varies depending on the space
+between syllables, and which will be centered between the syllables.
+For example:
-Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
-the name of a single note to a chord. This has the effect of
-lowering the specified note by an octave so it becomes the lowest
-note in the chord. If the specified note is not in the chord, a
-warning will be printed.
+@quotation
-@mudela[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/e c/g c:7/e
+@lilypond[verbatim]
+\score {
+ <
+ \notes \transpose c'' {
+ c d e c | c d e c |
+ e f g2 | e4 f g2 \bar "|.";
}
- }
-
-@end mudela
-
-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]
- \transpose c''' {
- \chords {
- c1 c/+c c/+g c:7/+b
+ \context Lyrics \lyrics {
+ Va4 -- der Ja -- cob | Va -- der Ja -- cob |
+ Slaapt gij nog?2 | Slaapt4 gij nog?2
}
- }
+ >
+}
-@end mudela
+@end lilypond
+@end quotation
-Throughout these examples, chords have been shifted around the staff
-using @code{\transpose}.
-You should not combine @code{\relative} with named chords.
+@c_ {Lyric hyphen}
+@node Lyric hyphen
+@subsection Lyric hyphen
+@cindex Lyric hyphen
-@cindex tuplets
+The syntax for a spanning hyphen (i.e., a hyphen that will be printed
+between two lyric syllables) is `@code{-}@code{-}'.
-Tuplets are made out of a music expression by multiplying their
-duration with a fraction.
+@c_ {Lyric extender}
+@node Lyric extender
+@subsection Lyric extender
+@cindex Lyric extender
+@cindex extender
+@cindex lyric extender
+@cindex hyphen
-@example
+The syntax for an extender mark is @code{__}. This syntax can only
+be used within lyrics mode.
- \times@keyindex{times} @var{fraction} @var{musicexpr}
-@end example
-The duration of @var{musicexpr} will be multiplied by the fraction.
-In print, the fraction's denominator will be printed over the notes,
-optionally with a bracket. The most common tuplet is the triplet in
-which 3 notes have the length of 2, so the notes are 2/3 of
-their written length:
-@mudela[fragment,verbatim,center]
- g'4 \times 2/3 {c'4 c' c'} d'4 d'4
-@end mudela
+@c_ {Addlyrics}
+@node Addlyrics
+@subsection Addlyrics
+@cindex Addlyrics
-@cindex grace notes
+[explain automatic phrasing]
+@cindex automatic lyric durations
+@cindex @code{\addlyrics}
+If you have lyrics that are set to a melody, you can import the rhythm
+of that melody into the lyrics using @code{\addlyrics}. The syntax for
+this is
@example
-
- \grace@keyindex{grace} @var{musicexpr}
+ \addlyrics @var{musicexpr1 musicexpr2}
@end example
-A grace note expression has duration 0; the next real note is
-assumed to be the main note.
-
-You cannot have the grace note after the main note, in terms of
-duration, and main notes, but you can typeset the grace notes to the
-right of the main note using the property
-@code{graceAlignPosition}@indexcode{graceAlignPosition}.
+This means that both @var{musicexpr1} and @var{musicexpr2} are
+interpreted, but that every non-command atomic music expression
+(``every syllable'') in @var{musicexpr2} is interpreted using timing
+of @var{musicexpr1}.
+@cindex @code{automaticMelismata}
-When grace music is interpreted, a score-within-a-score is set up:
-@var{musicexpr} has its own time bookkeeping, and you could (for
-example) have a separate time signature within grace notes. While in
-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.
+If the property @code{automaticMelismata} is set in the
+context of @var{musicexpr1}, no lyrics will be put on slurred or tied
+notes.
@quotation
-
-@mudela[fragment,verbatim]
-\relative c'' {
- \grace c8 c4 \grace { [c16 c16] } c4
- \grace { \property Grace.stemStyle = "" c16 } c4
+@lilypond[verbatim,fragment]
+\addlyrics
+\transpose c'' {
+ \property Voice.automaticMelismata = ##t
+ c8 () cis d8. e16 f2
}
-
-@end mudela
+\context Lyrics \lyrics {
+ do4 re mi fa }
+@end lilypond
@end quotation
-At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
-
-@example
-
- @code{\grace @{ \grace c32 c16 @} c4}
-@end example
-
-may result in run-time errors of LilyPond. Since the meaning of such
-a construct is unclear, we don't consider this a loss. Similarly,
-juxtaposing two @code{\grace} sections is syntactically valid, but
-makes no sense and may cause runtime errors.
-
-Ending a staff or score with grace notes may also generate a run-time
-error, since there will be no main note to attach the grace notes to.
+You should use a single rhythm melody, and single rhythm lyrics (a
+constant duration is the obvious choice). If you do not, you will get
+undesired effects when using multiple stanzas:
+@quotation
+@lilypond[verbatim,fragment]
+\addlyrics
+\transpose c'' {
+ c8 () cis d8. e16 f2
+}
+\context Lyrics \lyrics
+< { do4 re mi fa }
+ { do8 re mi fa } >
+@end lilypond
+@end quotation
-@cindex repeats
+It is valid (but probably not very useful) to use notes instead of
+lyrics for @var{musicexpr2}.
-@node Repeats
-@section Repeats
-In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
-keyword. Since repeats look and sound differently when played or
-printed, there are a few different variants of repeats.
-@table @code
- @item unfolded
- Repeated music is fully written (played) out. Useful for MIDI
- output.
+@c_ {Chord entry}
+@node Chord entry
+@section Chord entry
+@cindex Chord entry
- @item volta
- This is the normal notation: Repeats are not written out, but
- alternative endings (voltas) are printed, left to right.
+@menu
+* Chords mode::
+* Entering named chords::
+* Printing named chords::
+@end menu
- @item folded
- Alternative endings are written stacked, which is useful for
- lyrics.
-@end table
+@c_ {Chords mode}
+@node Chords mode
+@subsection Chords mode
+@cindex Chords mode
-The syntax for repeats is
+Chord mode is introduced by the keyword
+@code{\chords}. It is similar to Note mode, but
+words are also looked up in a chord modifier table (containing
+@code{maj}, @code{dim}, etc).
-@example
+Since combinations of numbers and dots are used for indicating
+durations, you can not enter real numbers in this mode. Dashes
+and carets are used to indicate chord additions and subtractions,
+so scripts can not be entered in Chord mode.
- \repeat @var{variant} @var{repeatcount} @var{repeatbody}
-@end example
+@c_ {Entering named chords}
+@node Entering named chords
+@subsection Entering named chords
+@cindex Chords names
-If you have alternative endings, you may add
+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 @ref{Lexical modes}).
@example
- \alternative@keyindex{alternative}
- @code{@{} @var{alternative1}
- @var{alternative2}
- @var{alternative3} @dots{} @code{@}}
+ @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
@end example
-where each @var{alternative} is a Music expression.
-
-Normal notation repeats are used like this:
-
-@quotation
+@var{tonic} should be the tonic note of the chord, and @var{duration}
+is the chord duration in the usual notation. There are two kinds of
+modifiers. One type is @emph{chord additions}, which are obtained by
+listing intervals separated by dots. An interval is written by its
+number with an optional @code{+} or @code{-} to indicate raising or
+lowering by half a step. Chord additions has two effects: It adds
+the specified interval and all lower odd numbered intervals to the
+chord, and it may lower or raise the specified interval. Intervals
+must be separated by a dot (@code{.}).
-@mudela[fragment,verbatim]
- c'1
- \repeat volta 2 { c'4 d' e' f' }
- \repeat volta 2 { f' e' d' c' }
-@end mudela
-@end quotation
+Throughout these examples, chords have been shifted around the staff
+using @code{\transpose}.
-With alternative endings:
@quotation
-@mudela[fragment,verbatim]
- c'1
- \repeat volta 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1 c:3- c:7 c:8
+ c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
+ }
+}
-@end mudela
+@end lilypond
@end quotation
-Folded repeats look like this:@footnote{Folded repeats offer little
-more over simultaneous music. However, it is to be expected that
-more functionality -- especially for the MIDI backend -- will be
-implemented.}
-
-@quotation
-
-@mudela[fragment,verbatim]
- c'1
- \repeat fold 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
+@cindex @code{aug}
+@cindex @code{dim}
+@cindex @code{maj}
+@cindex @code{sus}
-@end mudela
-@end quotation
+The second type of modifier that may appear after the @code{:} is a
+named modifier. Named modifiers are listed in the file
+@file{chord-modifiers.ly}. The available modifiers are @code{m} and
+@code{min} which lower the 3rd half a step, `@code{aug}' which
+raises the 5th, `@code{dim}' which lowers the 5th,
+`@code{maj}' which adds a raised 7th, and `@code{sus}'
+which replaces the 5th with a 4th.
@quotation
-@mudela[fragment,verbatim]
-\context Staff {
- \relative c' {
- \partial 4;
- \repeat volta 2 { e | c2 d2 | e2 f2 | }
- \alternative { { g4 g g } { a | a a a a | b1 } }
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1:m c:min7 c:maj c:aug c:dim c:sus
}
}
-@end mudela
+@end lilypond
@end quotation
+
-If you don't give enough alternatives for all of the repeats, then
-the first alternative is assumed to be repeated often enough to equal
-the specified number of repeats.
-
-@quotation
+Chord subtractions are used to eliminate notes from a chord. The
+notes to be subtracted are listed after a @code{^} character,
+separated by dots.
-@mudela[fragment,verbatim]
-\context Staff {
- \relative c' {
- \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
- \alternative { { g4 g g }
- {\partial 1; e4 e e }
- {\partial 1; a a a a | b1 } }
+@lilypond[fragment,verbatim,center]
+ \transpose c'' {
+ \chords {
+ c1^3 c:7^5.3 c:8^7
+ }
}
-}
+@end lilypond
+@cindex @code{/}
-@end mudela
-@end quotation
+Chord inversions can be specified by appending `@code{/}' and
+the name of a single note to a chord. This has the effect of
+lowering the specified note by an octave so it becomes the lowest
+note in the chord. If the specified note is not in the chord, a
+warning will be printed.
-It is possible to nest @code{\repeat}. This is not entirely
-supported: the notes will come be in the right places, but the repeat
-bars will not.
+@lilypond[fragment,verbatim,center]
+ \transpose c''' {
+ \chords {
+ c1 c/e c/g c:7/e
+ }
+ }
+@end lilypond
+@cindex @code{/+}
+Bass notes can be added by `@code{/+}' 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.
-@cindex transposition of pitches
+@lilypond[fragment,verbatim,center]
+ \transpose c''' {
+ \chords {
+ c1 c/+c c/+g c:7/+b
+ }
+ }
-@node transpose
-@section transpose
+@end lilypond
-A music expression can be transposed with
-@code{\transpose}@keyindex{transpose}. The syntax is
+The most interesting application is printing chords using chord names,
+See @ref{Chord names}.
-@example
+You should not combine @code{\relative} with named chords. [FIXME]
- \transpose @var{pitch} @var{musicexpr}
-@end example
+@c_ {Printing named chords}
+@node Printing named chords
+@subsection Printing named chords
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
+@cindex chord names
+@cindex chords
-@code{\transpose} distinguishes between enharmonic pitches: both
-@code{\transpose cis'} or @code{\transpose des'} will transpose up half
-a tone. The first version will print sharps and the second version
-will print flats.
+@cindex printing!chord names
+@cindex @code{ChordNames}
+@cindex @code{ChordNameVoice}
-@quotation
+For displaying printed chord names, use the @code{ChordNames} and
+@code{ChordNameVoice} contexts. The chords may be entered either using
+the notation described above, or directly using simultaneous music.
-@mudela[fragment,verbatim]
-\context Staff {
- \clef "F";
- { \key e; c d e f }
- \clef "G";
- \transpose des'' { \key e; c d e f }
- \transpose cis'' { \key e; c d e f }
+@quotation
+@lilypond[verbatim]
+scheme = \notes {
+ \chords {a1 b c} <d f g> <e g b>
}
-
-@end mudela
+\score {
+ \notes<
+ \context ChordNamesVoice \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper { linewidth = -1.; }
+}
+@end lilypond
@end quotation
-If you want to use both @code{\transpose} and @code{\relative}, then
-you must use @code{\transpose} first. @code{\relative} will have no
-effect music that appears inside a @code{\transpose}.
+You can make the chord changes stand out more by setting property
+@code{ChordNames.chordChanges} to true. This will only display chord
+names when there's a change in the chords scheme, but always display the
+chord name after a line break:
+@c bug
+@quotation
+@lilypond[verbatim]
+scheme = \chords {
+ c1:m \break c:m c:m c:m d
+}
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper{
+ linewidth = 40 * \staffspace;
+ \translator {
+ \ChordNamesContext
+ chordChanges = ##t
+ }
+ }
+}
+@end lilypond
+@end quotation
-@cindex automatic lyric durations
-If you have lyrics that are set to a melody, you can import the
-rhythm of that melody into the lyrics using @code{\addlyrics}.
-@keyindex{addlyrics} The syntax for this is
-@example
+LilyPond examines chords specified as lists of notes to determine a
+name to give the chord. LilyPond will not try to
+identify chord inversions or added base, which may result in strange
+chord names when chords are entered as a list of pitches:
- \addlyrics @var{musicexpr1 musicexpr2}
-@end example
+@quotation
+@lilypond[verbatim,center]
+scheme = \notes {
+ <c'1 e' g'>
+ <e' g' c''>
+ <e e' g' c''>
+}
-This means that both @var{musicexpr1} and @var{musicexpr2} are
-interpreted, but that every non-command atomic music expression
-(``every syllable'') in @var{musicexpr2} is interpreted using timing
-of @var{musicexpr1}.
+\score {
+ <
+ \context ChordNamesVoice \scheme
+ \context Staff \scheme
+ >
+ \paper { linewidth = -1.; }
+}
+@end lilypond
+@end quotation
-If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
-context of @var{musicexpr1}, no lyrics will be put on slurred or tied
-notes.
+To specify chord inversions, append @code{/<notename>}. To specify an
+added bass note, append @code{/+<notename}:
@quotation
-
-@mudela[verbatim,fragment]
-\addlyrics
-\transpose c'' {
- \property Voice.automaticMelismata = "1"
- c8 () cis d8. e16 f2
+@lilypond[verbatim,center]
+scheme = \chords {
+ d1 d/a d/+gis
}
-\context Lyrics \lyrics {
- do4 re mi fa }
-@end mudela
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper { linewidth = -1.; }
+}
+@end lilypond
@end quotation
-You should use a single rhythm melody, and single rhythm lyrics (a
-constant duration is the obvious choice). If you do not, you will get
-undesired effects when using multiple stanzas:
+The chord names that LilyPond should print are fully customizable. The
+code to print chord names is written in Scheme. It can be found in
+@file{scm/chord-name.scm}. Chord names are based on Banter style
+naming, which is unambiguous and has a logical structure. Typical
+American style chord names are implemented as a variation on Banter
+names, they can be selected by setting property @code{ChordName.style}
+to @code{american}:
@quotation
+@lilypond[verbatim]
+\include "english.ly"
+
+scheme = \chords {
+ c % Major triad
+ cs:m % Minor triad
+ df:m5- % Diminished triad
+ c:5^3 % Root-fifth chord
+ c:4^3 % Suspended fourth triad
+ c:5+ % Augmented triad
+ c:2^3 % "2" chord
+ c:m5-.7- % Diminished seventh
+ c:7+ % Major seventh
+ c:7.4^3 % Dominant seventh suspended fourth
+ c:5+.7 % Augmented dominant seventh
+ c:m5-.7 % "Half" diminished seventh
+ c:5-.7 % Dominant seventh flat fifth
+ c:5-.7+ % Major seventh flat fifth
+ c:m7+ % Minor-major seventh
+ c:m7 % Minor seventh
+ c:7 % Dominant seventh
+ c:6 % Major sixth
+ c:m6 % Minor sixth
+ c:9^7 % Major triad w/added ninth
+ c:6.9^7 % Six/Nine chord
+ c:9 % Dominant ninth
+ c:7+.9 % Major ninth
+ c:m7.9 % Minor ninth
+}
-@mudela[verbatim,fragment]
-\addlyrics
-\transpose c'' {
- c8 () cis d8. e16 f2
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper {
+ \translator {
+ \ChordNamesContext
+ ChordName \override #'word-space = #1
+ ChordName \override #'style = #'american
+ }
+ }
}
-\context Lyrics \lyrics
-< { do4 re mi fa }
- { do8 re mi fa } >
+@end lilypond
+@end quotation
-@end mudela
+Similarly, Jazz style chord names are implemented as a variation on
+American style names:
+@quotation
+@lilypond[verbatim]
+scheme = \chords {
+ % major chords
+ c
+ c:6 % 6 = major triad with added sixth
+ c:maj % triangle = maj
+ c:6.9^7 % 6/9
+ c:9^7 % add9
+
+ % minor chords
+ c:m % m = minor triad
+ c:m.6 % m6 = minor triad with added sixth
+ c:m.7+ % m triangle = minor major seventh chord
+ c:3-.6.9^7 % m6/9
+ c:m.7 % m7
+ c:3-.9 % m9
+ c:3-.9^7 % madd9
+
+ % dominant chords
+ c:7 % 7 = dominant
+ c:7.5+ % +7 = augmented dominant
+ c:7.5- % 7b5 = hard diminished dominant
+ c:9 % 7(9)
+ c:9- % 7(b9)
+ c:9+ % 7(#9)
+ c:13^9.11 % 7(13)
+ c:13-^9.11 % 7(b13)
+ c:13^11 % 7(9,13)
+ c:13.9-^11 % 7(b9,13)
+ c:13.9+^11 % 7(#9,13)
+ c:13-^11 % 7(9,b13)
+ c:13-.9-^11 % 7(b9,b13)
+ c:13-.9+^11 % 7(#9,b13)
+
+ % half diminished chords
+ c:m5-.7 % slashed o = m7b5
+ c:9.3-.5- % o/7(pure 9)
+
+ % diminished chords
+ c:m5-.7- % o = diminished seventh chord
+}
+
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper {
+ \translator {
+ \ChordNamesContext
+ ChordName \override #'word-space = #1
+ ChordName \override #'style = #'jazz
+ }
+ }
+}
+@end lilypond
@end quotation
-It is valid (but probably not very useful) to use notes instead of
-lyrics for @var{musicexpr2}.
+@c_ {Page layout}
+@node Page layout
+@section Page layout
+@cindex Page layout
-@node Ambiguities
-@section Ambiguities
+@menu
+* Paper block::
+* Paper variables::
+* Font Size::
+* Paper size::
+* Line break::
+* Page break::
+@end menu
-@cindex ambiguities
+@c_ {Paper block}
+@node Paper block
+@subsection Paper block
+@cindex Paper block
-The grammar contains a number of ambiguities.@footnote{The authors
-hope to resolve them at a later time.}
+The most important output definition is the @code{\paper} block, for
+music notation. The syntax is
-@itemize @bullet
- @item The assignment
+@example
+ @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
+@end example
- @example
-foo = bar
-@end example
+where each of the items is one of
- can be interpreted as making a string identifier @code{\foo}
- containing @code{"bar"}, or a music identifier @code{\foo}
- containing the syllable `bar'.
+@itemize @bullet
+ @item An assignment. The assignment must be terminated by a
+ semicolon.
- @item The assignment
+ @item A context definition. See section @ref{contextdefs} for
+ more information on context definitions.
- @example
-foo = -6
-@end example
+@ignore
- can be interpreted as making an integer identifier
- containing -6, or a Request identifier containing the
- fingering `6' (with neutral direction).
+ FIXME
- @item If you do a nested repeat like
- @quotation
+ @item
+
+ A margin shape declaration. The syntax is
+@cindex @code{\shape}
+ @example
-@example
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end example
+ \shape @var{indent1}@code{,} @var{width1}@code{,}
+ @var{indent2}@code{,} @var{width2} @dots{} @code{;}
+ @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.
+ Each pair of @var{indent} and @var{width} values is a dimension
+ specifying how far to indent and how wide to make the line.
+ The indentation and width of successive lines are specified by
+ the successive pairs of dimensions. The last pair of
+ dimensions will define the characeristics of all lines beyond
+ those explicitly specified.
+@end ignore
- @item (an as yet unidentified ambiguity :-)
+ @item \stylesheet declaration. Its syntax is
+ @example
+ \stylesheet @var{alist}
+ @end example
+
+ See @file{font.scm} for details of @var{alist}.
@end itemize
+@c_ {Paper variables}
+@node Paper variables
+@subsection Paper variables
+@cindex Paper variables
+The paper block has some variables you may want to use or change:
-@node Notation conversion specifics
-@section Notation conversion specifics
+@table @code
+@cindex @code{indent}
+ @item @code{indent}
+ The indentation of the first line of music.
+@cindex @code{staffspace}
-[todo]
+ @item @code{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.
+
+@cindex @code{linewidth}
+ @item @code{linewidth}
+ Sets the width of the lines. If set to -1.0, a single
+ unjustified line is produced. If you use this variable, you
+ probably want to define it in staff spaces, ie
+ @example
+ linewidth = 30 * \staffspace;
+ @end example
+@cindex @code{textheight}
+
+ @item @code{textheight}
+ Sets the total height of the music on each page. Only used by
+ ly2dvi.
+@cindex @code{interscoreline}
+
+ @item @code{interscoreline}
+ Sets the spacing between the score lines. Defaults to 16 pt.
+@cindex @code{interscorelinefill}
+
+ @item @code{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.
+@cindex @code{stafflinethickness}
+
+ @item @code{stafflinethickness}
+ Determines the thickness of staff lines, and also acts as a scaling
+ parameter for other line thicknesses.
+@end table
-@cindex automatic beam generation
-@node autobeam
-@section autobeam
+@c_ {Font size}
+@node Font Size
+@subsection Font size
+@cindex font size
-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].
+The Feta font provides musical symbols at six different sizes. These
+fonts are 11 point, 13 point, 16 point, 20 point,
+23 point, and 26 point. The point size of a font is the
+height of the five lines in a staff when displayed in the font.
-A large number of Voice properties are used to decide how to generate
-beams. Their default values appear in @file{auto-beam-settings.ly}.
-In general, beams can begin anywhere, but their ending location is
-significant. Beams can end on a beat, or at durations specified by
-the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
-quarter note, for example, you could set
-@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
-at every three eighth notes you would set it to `@code{"3/8"}'. The
-same syntax can be used to specify beam starting points using
-@code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
-
-To allow different settings for different time signatures, these
-property names can start with `@code{time}@var{N}@code{_}@var{M}' to
-restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
-to specify beams ending only for 6/8 time you would use the
-property @code{Voice.time6_8beamAutoEnd}. To allow different endings
-for notes of different durations, the duration can be tacked onto the
-end of the property. To specify beam endings for beams that contain
-32nd notes, you would use @code{Voice.beamAutoEnd_32}.
+Definitions for these sizes are the files @file{paperSZ.ly}, where
+@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
+these files, the identifiers @code{paperEleven}, @code{paperThirteen},
+@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
+@code{paperTwentysix} are defined respectively. The default
+@code{\paper} block is also set.
+The font definitions are generated using a Scheme function. For more
+details, see the file @file{font.scm}.
-@cindex chord names
-@cindex chords
+@c_ {Paper size}
+@node Paper size
+@subsection Paper size
+@cindex Paper size
-@cindex printing!chord names
+@cindex paper size
+@cindex page size
+@cindex @code{papersize}
-For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
-and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
-either using the notation described above, or directly using
-simultaneous music.
+To change the paper size, you must first set the
+@code{papersize} variable at top level. Set it to
+the strings @code{a4}, @code{letter}, or @code{legal}. After this
+specification, you must set the font as described above. If you want
+the default font, then use the 20 point font. The new paper size will
+not take effect if the font is not loaded and selected afterwards.
-@quotation
+@example
+ papersize = "a4"
+ \include "paper16.ly"
-@mudela[fragment,verbatim]
-<
- \context ChordNames {
- \chords{a b c} \notes{<d f g> <e g b>}
- }
- \context Staff \notes {
- a b c' d' e'
- }
->
+ \score @{
+ ...
+ \paper @{ \paperSixteen @}
+ @}
+@end example
-@end mudela
-@end quotation
+The file "paper16.ly" will now include a file named @file{a4.ly}, which
+will set the paper variables @code{hsize} and @code{vsize} (used by
+@code{ly2dvi})
-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]
- <
- \context ChordNameVoice \notes {
- <e'1 g' c''>
- }
- \context Thread \notes {
- <e'1 g' c''>
- }
- >
-@end mudela
-If you want inversions to be recognized, you must set the property
-@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
-@mudela[fragment,verbatim,center]
- <
- \property Score.chordInversion = 1
- \context ChordNameVoice \notes {
- <e'1 g' c''>
- }
- \context Thread \notes {
- <e'1 g' c''>
- }
- >
-@end mudela
-@cindex lyrics
+@c_ {Line break}
+@node Line break
+@subsection Line break
+@cindex Line break
-@cindex printing!lyrics
-@node lyricprint
-@section lyricprint
+@cindex @code{\penalty}
-Lyric syllables must be interpreted within a @code{Lyrics} context
+@example
+ \penalty @var{int} @code{;}
+@end example
-@cindex context!Lyrics
- for printing them.
+Discourage or encourage line breaks. See @ref{Page layout}.
-Here is a full example:
-@quotation
-@mudela[verbatim]
-\score {
- <
- \notes \transpose c'' {
- c d e c | c d e c |
- e f g2 | e4 f g2 \bar "|.";
- }
- \context Lyrics \lyrics {
- Va-4 der Ja- cob Va- der Ja- cob
- Slaapt gij nog?2 Slaapt4 gij nog?2
- }
- >
-}
-@end mudela
-@end quotation
+@cindex line breaks
+@cindex breaking lines
-You may want a continuous line after the syllables to show melismata.
-To achieve this effect, add a `@code{__}' lyric as a separate word
-after the lyric to be extended. This will create an extender, a line
-that extends over the entire duration of the lyric. This line will
-run all the way to the start of the next lyric, so you may want to
-shorten it by using a blank lyric (using `@code{_}').
+Line breaks are normally computed automatically. They are chosen such
+that the resulting spacing has low variation, and looks neither cramped
+nor loose.
-@quotation
+Occasionally you might want to override the automatic breaks; you can do
+this by specifying @code{\break} (see also @ref{Pre-defined
+Identifiers}). This will force a line break at this point. Do remember
+that line breaks can only occur at places where there are barlines. If
+you want to have a line break where there is no barline, you can force a
+barline by entering @code{\bar "";}.
-@mudela[verbatim]
-\score {
- <
- \notes \relative c'' {
- a4 () b () c () d | c () d () b () a | c () d () b () a
- }
- \context Lyrics \lyrics {
- foo1 __ | bar2. __ _4 | baz1 __
- }
- >
-}
-@end mudela
-@end quotation
-
-If you want to have hyphens centered between syllables (rather than
-attached to the end of the first syllable) you can use the special
-`@code{-}@code{-}' lyric as a separate word between syllables. This
-will result in a hyphen which length varies depending on the space
-between syllables, and which will be centered between the syllables.
-For example:
-@quotation
+@c_ {Page break}
+@node Page break
+@subsection Page break
+@cindex Page break
-@mudela[verbatim]
-\score {
- <
- \notes \transpose c'' {
- c d e c | c d e c |
- e f g2 | e4 f g2 \bar "|.";
- }
- \context Lyrics \lyrics {
- Va4 -- der Ja -- cob | Va -- der Ja -- cob |
- Slaapt gij nog?2 | Slaapt4 gij nog?2
- }
- >
-}
-@end mudela
-@end quotation
+Not implemented, but see @ref{Tricks}
+Page breaks are normally computed by @TeX{}, so they are not under direct
+control. However, you can insert a commands into the .tex output to
+instruct @TeX{} where to break pages. For more details, see the
+example file @file{input/test/between-systems.ly}
-@node Notation Contexts
-@section Notation Contexts
+@cindex page breaks
+@cindex breaking pages
-@cindex notation contexts
-Notation contexts are objects that only exist during a run of
-LilyPond. During the interpretation phase of LilyPond, the Music
-expression contained in a @code{\score} block is interpreted in time
-order. This is the order in which humans read, play, and write
-music.
-A context is an object that holds the reading state of the
-expression; it contains information like
-@itemize @bullet
- @item What notes are playing at this point?
- @item What symbols will be printed at this point?
- @item In what style will they printed?
- @item What is the current key signature, time signature, point within
- the measure, etc.?
-@end itemize
-Contexts are grouped hierarchically: A @code{Voice} context is
-contained in a @code{Staff} context (because a staff can contain
-multiple voices at any point), a @code{Staff} context is contained in
-a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
-these can all contain multiple staffs).
+@c_ {Sound}
+@node Sound
+@section Sound
+@cindex Sound
+@menu
+* MIDI block::
+* MIDI instrument names::
+* Tempo::
+@end menu
-Contexts associated with sheet music output are called @emph{notation
-contexts}, those for sound output are called playing contexts.
+@c_ {MIDI block}
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
-Contexts are created either manually or automatically. Initially,
-the top level music expression is interpreted by the top level
-context (the @code{Score} context). When a atomic music expression
-(i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
-set of contexts is created that can process these atomic expressions,
-as in this example:
-@example
+The MIDI block is analogous to the paper block, but it is somewhat
+simpler. The @code{\midi} block can contain:
+@cindex MIDI block
- @example
-\score @{ \notes < c4 > @}
-@end example
+@itemize @bullet
+ @item a @code{\tempo} definition
+ @item context definitions
+@end itemize
-@end example
+Assignments in the @code{\midi} block are not allowed.
-The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
-context. When the note `@code{c4}' itself is interpreted, a set of
-contexts is needed that will accept notes. The default for this is a
-@code{Voice} context, contained in a @code{Staff} context. Creation of
-these contexts results in the staff being printed.
-@cindex context
+@cindex context definition
-You can also create contexts manually, and you probably have to do so
-if you want to typeset complicated multiple part material. If a
-`@code{\context} @var{name} @var{musicexpr}' expression is encountered
-during the interpretation phase, the @var{musicexpr} argument will be
-interpreted with a context of type @var{name}. If you specify a name,
-the specific context with that name is searched.
+Context definitions follow precisely the same syntax as within the
+\paper block. Translation modules for sound are called performers.
+The contexts for MIDI output are defined in @file{ly/performer.ly}.
-If a context of the specified type and name can not be found, a new
-one is created. For example,
-@quotation
+@c_ {MIDI instrument names}
+@node MIDI instrument names
+@subsection MIDI instrument names
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+@cindex @code{Staff.instrument}
-@mudela[verbatim]
-\score {
- \notes \relative c'' {
- c4 <d4 \context Staff = "another" e4> f
- }
-}
+The MIDI instrument name is set by the @code{Staff.midiInstrument}
+property or, if that property is not set, the @code{Staff.instrument}
+property. The instrument name should be chosen from the following list.
+If the selected string does not exactly match, then LilyPond uses the
+default piano.
-@end mudela
-@end quotation
+[FIXME: to appendix ]
-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.
-
-Almost all music expressions inherit their interpretation context
-from their parent. In other words, suppose that the syntax for a
-music expression is
-
-@example
-
- \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
-@end example
-
-When the interpretation of this music expression starts, the context
-for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
-expression.
-
-Lastly, you may wonder, why this:
-
-@quotation
@example
-\score @{
- \notes \relative c'' @{
- c4 d4 e4
- @}
-@}
+"acoustic grand" "contrabass" "lead 7 (fifths)"
+"bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
+"electric grand" "pizzicato strings" "pad 1 (new age)"
+"honky-tonk" "orchestral strings" "pad 2 (warm)"
+"electric piano 1" "timpani" "pad 3 (polysynth)"
+"electric piano 2" "string ensemble 1" "pad 4 (choir)"
+"harpsichord" "string ensemble 2" "pad 5 (bowed)"
+"clav" "synthstrings 1" "pad 6 (metallic)"
+"celesta" "synthstrings 2" "pad 7 (halo)"
+"glockenspiel" "choir aahs" "pad 8 (sweep)"
+"music box" "voice oohs" "fx 1 (rain)"
+"vibraphone" "synth voice" "fx 2 (soundtrack)"
+"marimba" "orchestra hit" "fx 3 (crystal)"
+"xylophone" "trumpet" "fx 4 (atmosphere)"
+"tubular bells" "trombone" "fx 5 (brightness)"
+"dulcimer" "tuba" "fx 6 (goblins)"
+"drawbar organ" "muted trumpet" "fx 7 (echoes)"
+"percussive organ" "french horn" "fx 8 (sci-fi)"
+"rock organ" "brass section" "sitar"
+"church organ" "synthbrass 1" "banjo"
+"reed organ" "synthbrass 2" "shamisen"
+"accordion" "soprano sax" "koto"
+"harmonica" "alto sax" "kalimba"
+"concertina" "tenor sax" "bagpipe"
+"acoustic guitar (nylon)" "baritone sax" "fiddle"
+"acoustic guitar (steel)" "oboe" "shanai"
+"electric guitar (jazz)" "english horn" "tinkle bell"
+"electric guitar (clean)" "bassoon" "agogo"
+"electric guitar (muted)" "clarinet" "steel drums"
+"overdriven guitar" "piccolo" "woodblock"
+"distorted guitar" "flute" "taiko drum"
+"guitar harmonics" "recorder" "melodic tom"
+"acoustic bass" "pan flute" "synth drum"
+"electric bass (finger)" "blown bottle" "reverse cymbal"
+"electric bass (pick)" "skakuhachi" "guitar fret noise"
+"fretless bass" "whistle" "breath noise"
+"slap bass 1" "ocarina" "seashore"
+"slap bass 2" "lead 1 (square)" "bird tweet"
+"synth bass 1" "lead 2 (sawtooth)" "telephone ring"
+"synth bass 2" "lead 3 (calliope)" "helicopter"
+"violin" "lead 4 (chiff)" "applause"
+"viola" "lead 5 (charang)" "gunshot"
+"cello" "lead 6 (voice)"
@end example
-@end quotation
-
-doesn't result in this:
-
-@mudela[]
-
- \score {
- \notes \relative c'' {
- <c4> <d4> <e4>
- }
- }
-
-@end mudela
-
-For the @code{c4}, a default @code{Staff} (with a contained
-@code{Voice}) context is created. After the @code{c4} ends, no
-music refers to this default staff, so it would be ended, with the
-result shown. To prevent this inconvenient behavior, the context to
-which the sequential music refers is adjusted during the
-interpretation. So after the @code{c4} ends, the context of the
-sequential music is also the default @code{Voice} context.
-The @code{d4} gets interpreted in the same context
-as @code{c4}.
-
-
-These are the contexts supplied with the package. They are defined
-in the initialization file @file{ly/engraver.ly}.
-@table @code
- @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
+@c_ {Tempo}
+@node Tempo
+@subsection Tempo
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
-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 preset within the @code{\translator} block
-corresponding to the appropriate context. In this case, the syntax
-is
-
+@cindex @code{\tempo}
@example
-
- @var{propname} @code{=} @var{value}
+ \tempo @var{duration} = @var{perminute} @code{;}
@end example
-This assignment happens before interpretation starts, so a
-@code{\property} expression will override any predefined settings.
+Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
+output with 76 quarter notes per minute.
-The @code{\property} expression will create any property you specify.
-There is no guarantee that a property will be used. So if you spell
-a property name wrong, there will be no error message.
-
-The property settings are used during the interpretation phase. They
-are read by the LilyPond modules where interpretation contexts are
-built of. These modules are called @emph{translators}. Translators for
-notation are called @emph{engravers}, and translators for sound are
-called @emph{performers}.
-The precise result of a property is determined by the implementation
-of the translator that reads them. Therefore, the result of a
-property can vary, since it is implementation and configuration
-dependent.
-In order to fully find out what properties are used, you must
-currently search the source code for calls to @code{get_property}.
-The rest of the section is devoted to an (incomplete) overview of
-available properties.
-@node Properties
-@section Properties
-
-Properties are Scheme values, so they have a type. The type of a
-property is listed in parentheses after the property name.
-
-@macro propertytype{t}
- (\t\)
-@end macro
+@c_ {Music entry}
+@node Music entry
+@section Music entry
+@cindex Music entry
+@menu
+* Pre-defined Identifiers::
+* Point and click::
+@end menu
+@c_ {Music entry}
+@node Pre-defined Identifiers
+@subsection Pre-defined Identifiers
+@cindex pre-defined identifiers
-TODO:
+Various identifiers are defined in the initialization files to
+provide shorthands for some settings. Most of them are in
+@file{ly/declarations.ly} and @file{ly/property.ly}.
@table @code
- @item @code{Generic_property_list}
- Defines names and types for generic properties. These are properties
- than can be plugged into the backend directly. See the init file
- @file{generic-property.scm} for details. For internal use only.
+@cindex @code{\break}
+ @item @code{\break}
+ Force a line break in music by using a large argument for the
+ keyword @code{\penalty}.
- @item @code{XXXVerticalExtent}@indexcode{groupVerticalExtent} @propertytype{Interval: a cons of numbers}
- Hard code the size of the vertical group in context XXX, example
-@example
-\property Staff.StaffVerticalExtent = #(-5.0 . 5.0)
-@end example
- The value is a cons of real numbers, that measure the extent in
- staff spaces.
-@end table
+@cindex @code{\nobreak}
+ @item @code{\nobreak}
+ Prevent a line break in music by using a large negative argument
+ for the keyword @code{\penalty}.
-@subsubheading Lyrics properties
+@cindex @code{\shiftOff}
+ @item @code{\shiftOff}
+ Disable horizontal shifting of note heads that collide.
-@cindex properties!Lyrics
+@cindex @code{\shiftOn}
+ @item @code{\shiftOn}
+ Enable note heads that collide with other note heads to be
+ shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
+set different shift values.
-@table @code
- @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
- Set the font for lyrics. The available font choices are
- @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
- @code{typewriter}, and @code{finger}. The @code{finger} font can
- only display numbers. Note also that you must be careful when
- using @code{\property} in Lyrics mode, because of the way strings
- are parsed. Either put quotes around the arguments to
- @code{\property} or be sure to leave a space on both sides of the
- dot.
-@end table
+@cindex @code{\stemBoth}
+ @item @code{\stemBoth}
+ Allow stems, beams, and slurs to point either upwards or
+ downwards, decided automatically by LilyPond.
-@subsubheading Thread properties
+@cindex @code{\stemDown}
+ @item @code{\stemDown}
+ Force stems, beams, and slurs to point down.
-@cindex properties!Thread
+@cindex @code{\stemUp}
+ @item @code{\stemUp}
+ Force stems, beams and slurs to point up.
-@table @code
- @item @code{noteheadStyle}@indexcode{noteheadStyle} @propertytype{string}
- Selects type of note head. Choices are @code{cross},
- @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
- They are shown in that order below.
-
- @mudela[center,verbatim]
- \score {
- \notes {
- \property Staff.barNonAuto = 1
- \property Voice.noteHeadStyle = cross
- a'
- \property Voice.noteHeadStyle = diamond
- a'
- \property Voice.noteHeadStyle = harmonic
- a'
- \property Voice.noteHeadStyle = transparent
- a'
- \property Voice.noteHeadStyle = ""
- a'
- }
- \paper {
- linewidth = -1.;
- }
- }
-
-@end mudela
@end table
-@subsubheading Grace properties
-@cindex properties!Grace
+@c_ {Point and click}
+@node Point and click
+@subsection Point and click
-
-@table @code
- @item @code{stemStyle}@indexcode{flagStyle} @propertytype{string}
- By default set to @code{"grace"} meaning that all unbeamed
- notes with flags are typeset with a slash through the flag.
- Setting to @code{""} gives standard flags.
-
-@mudela[verbatim]
-c'8 \property Voice.flagStyle = "grace" c'8
-@end mudela
-@end table
+[todo]
+@c_ {Engravers}
+@node Engravers
+@section Engravers
+@cindex engravers
+@menu
+* Context definitions::
+* Notation Contexts::
+@end menu
-@subsubheading Voice properties
+@c_ {Context definitions}
+@node Context definitions
+@subsection Context definitions
-@cindex properties!Voice
+@cindex context definition
+@cindex translator definition
+@cindex engraver hacking
-@table @code
- @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
- Set length for tremolo to be used if no length is explicitly
- specified.
- @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
- Determines the extra space added between articulation marks, such
- as staccato, tenuto, trill, up/down bow or fermata, and the
- closest staff line or note.
+A notation contexts is defined by the following information
- @item @code{articulationScriptVerticalDirection} @propertytype{direction}
- @indexcode{articulationScriptVerticalDirection}
- Determines the location of articulation marks. Set to @code{\up}
- to print marks above the staff; set to @code{\down} to print marks
- below the staff. This property does not override explicit
- directions marked with `@code{^}' or `@code{_}' in the mudela file.
-
- @item @code{noAutoBeaming}@indexcode{beamAuto} @propertytype{boolean}
- If set to 1 then beams are not generated automatically.
+@enumerate 1
+ @item A name.
- @item @code{beamAutoEnd}@indexcode{beamAutoEnd} @propertytype{?}
- Specifies when automatically generated beams can end. See
- section XREF-autobeam [FIXME].
+ @item The LilyPond modules that do the actual conversion of music to
+ notation. Each module is a so-called
+ @emph{engraver}
+@cindex engraver
+.
- @item @code{beamAutoBegin}@indexcode{beamAutoBegin} @propertytype{?}
- Specifies when automatically generated beams can start. See
- section XREF-autobeam [FIXME].
+ @item How these modules should cooperate, i.e. which ``cooperation
+ module'' should be used. This cooperation module is a special
+ type of engraver.
+ @item What other contexts the context can contain,
-[outdated FIXME]
- @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
- Set to @code{\none} for no quantization. Set to @code{\normal} to
- quantize position and slope. Set to @code{\traditional} to avoid
- wedges. These three settings are available via
- @code{\beamposfree}@keyindex{beamposfree},
- @code{\beamposnormal}@keyindex{beamposnormal}, and
- @code{\beampostraditional}@keyindex{beampostraditional}.
+ @item What properties are defined.
+@end enumerate
- @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
- Set to @code{\none} for undamped beams. Set to @code{\normal} for
- damped beams. Set to @code{\infinity} for beams with zero slope.
- The identifiers
- @code{\beamslopeproportional}@keyindex{beamslopeproportional},
- @code{\beamslopedamped}@keyindex{beamslopedamped}, and
- @code{\beamslopezero}@keyindex{beamslopezero} each set the
- corresponding value.
+A context definition has this syntax:
- @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
- Determines location of dynamic marks. Set to @code{\up} to print
- marks above the staff; set to @code{\down} to print marks below
- the staff.
+@example
- @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
- Set the text style for dynamics.
+ \translator @code{@{}
+ @var{translatorinit} @var{translatormodifierlist}
+ @code{@}}
+@end example
- @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
- Can be used to select smaller font sizes for music. The normal
- font size is 0, and the two smaller sizes are -1
- and -2.
+@var{translatorinit} can be an identifier or of the form
-@mudela[verbatim]
-c''16 \property Staff.fontSize = -2 c''16
-@end mudela
+@example
- @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
- Force horizontal shift for collision resolution. It overrides
- automatic collision resolution. The value is the shift amount
- expressed in @code{note_width}, as set in the paper section.
+ \type @var{typename} @code{;}
+@end example
-@item @code{collisionMergeDotted}@indexcode{collisionMergeDotted} @propertytype{boolean}
+@var{typename} is one of
-Merge noteheads in collisions, even if they have a different number of
-dots. This normal notation for polyphonic guitar music.
+@table @code
+@cindex @code{Engraver_group_engraver}
+ @item @code{Engraver_group_engraver}
+ The standard cooperation engraver.
+@cindex @code{Score_engraver}
-@mudelafile[verbatim]{force-hshift.ly}
+ @item @code{Score_engraver}
+ This is cooperation module that should be in the top level 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
-[FIXME: this should be moved]
+@var{translatormodifierlist} is a list of items where each item is
+one of
-Lilypond always arranges note heads on alternate sides of a stem (that
-is, within a single voice) as necessary to prevent collisions (note head
-overlaps). For up stems, the upper note of a colliding pair is placed
-on the right side of the stem, the lower on the left. For down stems,
-the algorithm works in reverse.
+@itemize @bullet
+ @item @code{\consists} @var{engravername} @code{;}
+ Add @var{engravername} to the list of modules in this context.
+ The order of engravers added with @code{\consists} is
+ significant.
-Lily also attempts to prevent collisions of note heads in different
-voices. A situation where chords of two or more voices are played
-simultaneously within one staff.
-
-By default, if only two voices (and both have opposite stem directions)
-are in this 'collision group', the notes both are shifted by @code{0.5
-\quartwidth} if there are unisons or seconds between the voices.
-
-If there are more than two voices in a collision group, shifting is
-inactive by default, since in this case, there are multiple chords with
-the same stem direction. By distinguish between those chords, LilyPond
-can do collision resolution in these cases as well.
-
-Distinguishing between voices with the same stem direction, is done by
-setting the property @code{Voice.horizontalNoteShift}. It must be set
-to a different integer for each voice. Then, all note heads in collision
-groups (not just unisons and seconds) will be offset, one voice relative
-another. The following fragment of sheet music shows how shifting is
-done, with values of @code{horizontalNoteShift} printed over and under
-the notes. In this case the chords are just simple notes.
-
-@c URG : mudela book bug.
-@mudela[singleline,verbatim]
-\score {
- \notes \context Staff <
- \context Voice = VA { \stemup f''4^"0" }
- \context Voice = VB {\stemup
- \property Voice.horizontalNoteShift = 1 d''4^" 1" }
- \context Voice = VC { \stemup \property
-Voice.horizontalNoteShift = 2 b'4^" 2" }
- \context Voice = VD { \stemdown \property
-Voice.horizontalNoteShift = 1 g'4_"1 " }
- \context Voice = VE { \stemdown e'4_"0" }
- >
-}
-@end mudela
-
-If you are not satisfied with the collision resolution of LilyPond, you
-can override the horizontal shift value of the chord of one Voice, by
-setting @code{forceHorizontalShift}. This sets the amount shift,
-measured in black note head widths.
-
-To take complete control of note position shifts in complex passages,
-you have set things up for normal collisions and override all shifts by
-setting @code{forceHorizontalShift} to zero everywhere
-@example
-\property Voice.horizontalNoteShift = <n>
-\property Voice.forceHorizontalShift = "0.0"
-@end example
+ @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.
-Then you can set the force property to a suitable value before each note
-that really needs it (unisons and seconds), and reset it to 0.0 after
-the note.
-
- @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift} @propertytype{integer}
- Enable LilyPond to shift notes horizontally if they collide with
- other notes. This is useful when typesetting many voices on one
- staff. The identifier @code{\shift}@keyindex{shift} is defined to
- enable this. Traditionally, the outer chords (the upmost and
- downmost voices), should have no @code{horizontalNoteShift}.
-
- @item @code{markScriptPadding}@indexcode{markScriptPadding} @propertytype{number}
- Determines the extra space added between the mark and the closest
- staff line or note.
-
- @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
- Determines if marks should be printed above or below the staff.
- Set to @code{\up} to print marks above the staff; set to
- @code{\down} to print marks below the staff.
-
- @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
- Sets the instrument for MIDI output. If this property is not set
- then LilyPond will use the @code{instrument} property. This must
- be set to one of the strings on the list of MIDI instruments that
- appears in section XREF-midilist [FIXME]. If you use a string which
- is not listed, LilyPond will silently substitute piano.
-
- @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
- Change the layout of rests shorter than quarter notes.
- Currently, the standard layout @code{""} and mensural notation
- @code{"mensural"} are available. Mensural rests of duration
- 32 or shorter are not available.
-@mudela[verbatim]
-r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
-\property Staff.restStyle = "mensural"
-r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
-@end mudela
-
- @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
- Put scripts left or right of note heads. Support for this is
- limited. Accidentals will collide with scripts.
-
- @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
- Set to @code{\free} for free choice of slur direction, set to
- @code{\up} to force slurs up, set to @code{\down} to force slurs
- down. The shorthands @code{\slurup}@keyindex{slurup},
- @code{\slurdown}@keyindex{slurdown}, and
- @code{\slurboth}@keyindex{slurboth} are available.
-
- @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
- Set to NIL for normal slurs, 1 for dotted slurs, and a
- larger value for dashed slurs. Identifiers
- @code{\slurnormal}@keyindex{slurnormal} and
- @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
- first two settings.
-
-@mudela[verbatim]
- c4( )d
- \property Voice.slurDash = 3
- c ( )e
-@end mudela
-
-@item @code{stemLength}@indexcode{stemLength}
- Set length of stems. Unit is `@code{interline}/2', so
- @code{stemLength} defaults to 7.
-@mudela[verbatim]
-g''4 \property Voice.stemLength = #14 g4 \property Voice.stemLength = #3 g4 g,,4
-@end mudela
-
- @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
- Specify the number of beams to draw on the left side of the next
- note. Overrides automatic beaming. The value is only used once,
- and then it is erased.
-
- @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
- Specify the number of beams to draw on the right side of the next
- note. Overrides automatic beaming. The value is only used once,
- and then it is erased.
-
- @item @code{tieDash}@indexcode{tieDash} @propertytype{integer}
- Set dashing of ties. See also @code{slurDash}
-
- @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
- Set to @code{\free} for free choice of tie direction, set to
- @code{\up} to force ties up, set to @code{\down} to force ties
- down.
-
- @item @code{transposing}@indexcode{transposing} @propertytype{integer}
- Transpose the MIDI output. Set this property to the number of
- half-steps to transpose by.
-
- @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
- If set to true then text placed above or below the staff is
- assumed to have zero width. @code{fatText} and @code{emptyText}
-are predefined settings.
-
-@mudela[verbatim]
-c4^"foo" \emptyText c4^"foo" c4
-@end mudela
-
- @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
- Set the text style for superscripts and subscripts. See above
- for list of text styles.
-
- @item @code{textScriptPadding}@indexcode{textScriptPadding} @propertytype{number}
- Determines the extra space added between superscripted resp.
- subscripted text and the closest staff line or note.
-
- @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
- Determines the direction of stems, subscripts, beams, slurs, and
- ties. Set to @code{\down} to force them down, @code{\up} to force
- them up, or @code{\free} to let LilyPond decide. This can be used
- to distinguish between voices on the same staff. The
- @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
- and @code{\stemboth}@keyindex{stemboth} identifiers set this
- property.
+ 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{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
- Determines the direction of triplets and other tuplets. Set to
- @code{\down} to force them below the staff, @code{\up} to force
- them above, or @code{\free} to let LilyPond decide.
-
- @item @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
- @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}
-
- These properties the visibility of the tuplet bracket and its
-number respectively. Setting it to false will prevent printing of the
-associated element. Setting the property to 'if-no-beam will make it
-print only if there is no beam associated with this tuplet bracket.
-
-[fixme examples]
-
- @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}
-
- If set to true, tuplet bracket creation is switched off
-entirely. This has the same effect as setting both
-@code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
-@code{#f}, but as this does not even create elements, this setting
-uses less memory and time.
-
-
-@item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
-@propertytype{moment}
-
-Normally a tuplet bracket is as wide as the
-@code{\times} expression that gave rise to it. By setting this
-property, you can make brackets last shorter. Example
-
-@mudela[verbatim,fragment]
-\context Voice \times 2/3 {
- \property Voice.tupletSpannerDuration = #(make-moment 1 4)
- [c8 c c] [c c c]
-}
-@end mudela
-
-@end table
-
-@subsubheading Staff properties
-
-@cindex properties!Staff
-
-@table @code
-
- @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
- If set to true then bar lines will not be printed
- automatically; they must be explicitly created with @code{\bar}
- keywords. Unlike with the @code{\cadenza} keyword, measures are
- still counted. Bar generation will resume according to that
- count if this property is set to zero.
-
- @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
- Set to @code{\up} or @code{\down} to put bar numbers above or below
- the staff.
-
- @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
- Sets extra space between the bar number and the bar it labels.
-
- @item @code{barSize}@indexcode{barSize}
- Specify the height of the bar lines if it should be different
- than the staff height.
-@mudela[verbatim]
-c1 c1 \property Staff.barSize = 20 c1 c1
-@end mudela
-
- @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
- Set to true to produce a bar line after the clef at the start
- of each line (but not at the beginning of the music).
-
- [BROKEN]
-
- @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
- Determines how clefs are typeset. If set to @code{transparent},
- the clefs are not printed at all, if set to
- @code{fullSizeChanges}, clef changes in the middle of a line are
- typeset with a full size clef. By default, clef changes are
- typeset in smaller size.
-
- @item @code{supportedClefTypes}@indexcode{supportedClefTypes} @propertytype{alist}
-
- Clef settings supported. The value is an association list clef
-descriptions indexed by clef name (alto, baritone, etc.). A clef
-description is a list with the glyph name, and the staff position
-where it should go. For internal use.
-
- @item @code{clefPitches}@indexcode{clefPitches} @propertytype{alist}
- Settings for the position of the central C, relative to this clef
- symbol. For internal use.
-
- @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
- Clef setting to use when this context is created. If unset,
-no clef is printed upon creation.
-
- @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
- Set to @code{\left} or @code{\right} to specify location of
- marginal scripts.
-
- @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
- Specify extra space for marginal scripts.
-
- @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
- Causes accidentals to be printed at every note instead of
- remembered for the duration of a measure.
-
- @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
- Do not reset the key at the start of a measure. Accidentals will
- be printed only once and are in effect until overridden, possibly
- many measures later.
-
- @item @code{staffSpace}@indexcode{staffLineLeading} @propertytype{number}
- Specifies the distance (in points) between lines of the staff.
-
- @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
- Specifies the number of staff lines. The default is 5.
-
- @item @code{postBreakPadding}@indexcode{postBreakPadding} @propertytype{number}
- Extra space in points to be added after the clef, time signature
- and key signature on the staff. Deprecated, do not use.
-
- @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
- Set to true to suppress the printing of brackets over alternate
- endings specified by the command @code{\alternative}.
-
+ @item @code{\denies}. The opposite of @code{\accepts}. Added for
+completeness, but is never used in practice.
- @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
- If set to true a bar line is drawn after each note.
-
- @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
- Sets the default type of bar line. See Section XREF-barlines [FIXME]
- for a list of available bar types.
-
- @item @code{instrument}, @code{instr} @propertytype{string}
- @indexcode{instrument}@indexcode{instr}
- If @code{Instrument_name_engraver}
-@cindex Instrument_name_engraver
- is
- added to the Staff translator, then the @code{instrument} property
- is used to label the first line of the staff and the @code{instr}
- property is used to label subsequent lines. If the
- @code{midiInstrument} property is not set, then @code{instrument}
- is used to determine the instrument for MIDI output.
-
- @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
- If set to false, then keys are the same in all octaves. If set
- to true then the key signature for different octaves can be
- different and is specified independently:
-
- @example
- \keysignature bes fis'
- @end example
-
- The default value is @code{#f}. Can be set to @code{#t} with
- @code{\specialkey} or reset with @code{\normalkey}.
-
- @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
- Changes the default two-digit layout for time signatures. The
- following values are recognized:
-
- @table @code
- @item @code{C}@indexcode{C}
- 4/4 and 2/2 are typeset as C and struck C, respectively. All
- other time signatures are written with two digits.
-
- @item @code{old}@indexcode{old}
- 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
- typeset with old-style mensuration marks. All other time
- signatures are written with two digits.
-
- @item @code{1}@indexcode{1}
- All time signatures are typeset with a single
- digit, e.g. 3/2 is written as 3.
-
- @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
- @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
- @code{old6/8alt}@indexcode{old6/8alt}
- Tells LilyPond to use a specific symbol as time signature.
- @end table
-
- The different time signature characters are shown below with its
- names:
-
- @mudela[center,verbatim]
-
- \score {
- \notes\relative c'' {
- \property Voice.textStyle = typewriter
- \property Staff.timeSignatureStyle = "C2/2"
- \time 2/2; a2^"C2/2" a2
- \property Staff.timeSignatureStyle = "C4/4"
- \time 2/2; a2^"C4/4" a2
- \property Staff.timeSignatureStyle = "old2/2"
- \time 2/2; a2^"old2/2" a2
- \property Staff.timeSignatureStyle = "old3/2"
- \time 2/2; a2^"old3/2" a2
- \property Staff.timeSignatureStyle = "old2/4"
- \time 2/2; a2^"old2/4" a2
- \property Staff.timeSignatureStyle = "old4/4"
- \time 2/2; a2^"old4/4" a2
- \property Staff.timeSignatureStyle = "old6/4"
- \time 2/2; a2^"old6/4" a2
- \property Staff.timeSignatureStyle = "old9/4"
- \time 2/2; a2^"old9/4" a2
- \property Staff.timeSignatureStyle = "old4/8"
- \time 2/2; a2^"old4/8" a2
- \property Staff.timeSignatureStyle = "old6/8"
- \time 2/2; a2^"old6/8" a2
- \property Staff.timeSignatureStyle = "old6/8alt"
- \time 2/2; a2^"old6/8alt" a2
- \property Staff.timeSignatureStyle = "old9/8"
- \time 2/2; a2^"old9/8" a2
- }
- \paper {
- linewidth = 4.5 \in;
- }
- }
-
-@end mudela
-
- @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
- Set to an integer to control the size of the brackets printed by
- @code{\alternative}. The integer specifies the number of whole
- notes duration to use for the brackets. It is rounded to the
- nearest measure. This can be used to shrink the length of
- brackets in the situation where one alternative is very large.
- It may have odd effects if the specified duration is longer than
- the music given in an @code{\alternative}.
-@end table
-
-@subsubheading GrandStaff properties
+
+ @item @code{\remove} @var{engravername} @code{;}
+ Remove a previously added (with @code{\consists}) engraver.
+
+ @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.
-@cindex properties!GrandStaff
+ @item @var{propname} @code{=} @var{value} @code{;}
+ A property assignment. It is allowed to use reals for
+ @var{value}.
+@end itemize
-@table @code
- @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign} @propertytype{number}
- Set the maximum vertical distance between staffs.
+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
- @item @code{minVerticalAlign}@indexcode{minVerticalAlign} @propertytype{number}
- Set the minimum vertical distance between staffs.
-@end table
+@quotation
-@subsubheading Score properties
+@example
+\paper @{
+ foo = \translator @{ @dots{} @}
+@}
+\score @{
+ \notes @{
+ @dots{}
+ @}
+ \paper @{
+ \translator @{ \foo @dots{} @}
+ @}
+@}
+@end example
-@cindex properties!Score
+@end quotation
+@cindex paper types, engravers, and pre-defined translators
+Some pre-defined identifiers can simplify modification of
+translators. The pre-defined identifiers are:
@table @code
- @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
- Set to 1 to skip the empty bars that are produced by
- multimeasure notes and rests. These bars will not appear on the
- printed output. Set to zero (the default) to expand multimeasure
- notes and rests into their full length, printing the appropriate
- number of empty bars so that synchronization with other voices is
- preserved.
-
- @quotation
-
-@mudela[fragment,verbatim,center]
-r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
-
-@end mudela
- @end quotation
-
-@item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}
+@cindex @code{StaffContext}
+ @item @code{StaffContext}
+ Default Staff context.
+@cindex @code{RhythmicStaffContext}
- Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
-@example
- \property Score.breakAlignOrder = #'(
- "Span_bar"
- "Breathing_sign"
- "Clef_item"
- "Staff_bar"
- "Key_item"
- "Time_signature"
- )
-@end example
+ @item @code{RhythmicStaffContext}
+ Default RhythmicStaff context.
+@cindex @code{VoiceContext}
+ @item @code{VoiceContext}
+ Default Voice context.
+@cindex @code{ScoreContext}
-@item @code{timing}@indexcode{timing} @propertytype{boolean}
- Keep administration of measure length, position, bar number, etc?
-Switch off for cadenzas.
+ @item @code{ScoreContext}
+ Default Score context.
+@cindex @code{ScoreWithNumbers}
-@item @code{currentBarNumber}@indexcode{currentBarNumber} @propertytype{integer}
- Contains the current barnumber. This property is incremented at
-every barline.
+ @item @code{ScoreWithNumbers}
+ Score context with numbering at the Score level.
+@cindex @code{BarNumberingStaffContext}
-@item @code{measurePosition}@indexcode{measurePosition} @propertytype{Moment}
+ @item @code{BarNumberingStaffContext}
+ Staff context with numbering at the Staff level.
+@cindex @code{HaraKiriStaffContext}
- How much of the current measure (measured in whole notes) have we had?
+ @item @code{HaraKiriStaffContext}
+ Staff context that does not print if it only contains rests.
+ Useful for orchestral scores.@footnote{Harakiri, also called
+ Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
+@cindex @code{OrchestralPartStaffContext}
-@item @code{oneBeat}@indexcode{oneBeat} @propertytype{Moment}
+ @item @code{OrchestralPartStaffContext}
+@cindex @code{OrchestralScoreContext}
- How long does one beat in the current time signature last?
+ @item @code{OrchestralScoreContext}
+@end table
-@item @code{measureLength}@indexcode{measureLength} @propertytype{Moment}
+Using these pre-defined values, you can remove or add items to the
+translator:
- How long does one measure in the current time signature last?
+@quotation
-@end table
+@example
+\paper @{
+ \translator @{
+ \StaffContext
+ \remove Some_engraver;
+ \consists Different_engraver;
+ @}
+@}
+@end example
-@subsubheading ChordNamesVoice properties
+@end quotation
-@cindex properties!ChordNamesVoice
+
-@table @code
- @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
- Determines whether LilyPond should look for chord inversions when
- translating from notes to chord names. Set to 1 to find
- inversions. The default is 0 which does not look for
- inversions.
-@end table
+@c_ {Notation Contexts}
+@node Notation Contexts
+@subsection Notation Contexts
+@cindex notation contexts
-@node Notation output definitions
-@section Notation output definitions
+Notation contexts are objects that only exist during a run of
+LilyPond. During the interpretation phase of LilyPond, the Music
+expression contained in a @code{\score} block is interpreted in time
+order. This is the order in which humans read, play, and write
+music.
-@cindex output
+A context is an object that holds the reading state of the
+expression; it contains information like
-@cindex notation output
+@itemize @bullet
+ @item What notes are playing at this point?
+ @item What symbols will be printed at this point?
+ @item In what style will they printed?
+ @item What is the current key signature, time signature, point within
+ the measure, etc.?
+@end itemize
-@cindex output definition
+Contexts are grouped hierarchically: A @code{Voice} context is
+contained in a @code{Staff} context (because a staff can contain
+multiple voices at any point), a @code{Staff} context is contained in
+a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
+these can all contain multiple staffs).
-@node paper
-@section paper
+Contexts associated with sheet music output are called @emph{notation
+contexts}, those for sound output are called performance contexts.
-The most important output definition is the @code{\paper} block, for
-music notation. The syntax is
+Contexts are created either manually or automatically. Initially, the
+top level music expression is interpreted by the top level context (the
+@code{Score} context). When a atomic music expression (i.e. a note, a
+rest, etc.), a nested set of contexts is created that can process these
+atomic expressions, as in this example:
@example
+\score @{ \notes @{ c4 @} @}
+@end example
- @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
-@end example
+The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
+context. When the note @code{c4} itself is interpreted, a set of
+contexts is needed that will accept notes. The default for this is a
+@code{Voice} context, contained in a @code{Staff} context. Creation of
+these contexts results in the staff being printed.
-where each of the items is one of
+@cindex context
-@itemize @bullet
- @item An assignment. The assignment must be terminated by a
- semicolon. See section XREF-papervars [FIXME] for information on
- paper variables.
+You can also create contexts manually, and you probably have to do so
+if you want to typeset complicated multiple part material. If a
+`@code{\context} @var{name} @var{musicexpr}' expression is encountered
+during the interpretation phase, the @var{musicexpr} argument will be
+interpreted with a context of type @var{name}. If you specify a name,
+the specific context with that name is searched.
- @item A context definition. See section XREF-contextdefs [FIXME] for
- more information on context definitions.
+[type vs id]
- @item
- FIXME now in SCM
+If a context of the specified type and name can not be found, a new
+one is created. For example,
- A margin shape declaration. The syntax is
+@quotation
- @example
+@lilypond[verbatim]
+\score {
+ \notes \relative c'' {
+ c4 <d4 \context Staff = "another" e4> f
+ }
+}
- \shape @var{indent1}@code{,} @var{width1}@code{,}
- @var{indent2}@code{,} @var{width2} @dots{} @code{;}
- @end example
+@end lilypond
+@end quotation
- @keyindex{shape}
+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.
- Each pair of @var{indent} and @var{width} values is a dimension
- specifying how far to indent and how wide to make the line.
- The indentation and width of successive lines are specified by
- the successive pairs of dimensions. The last pair of
- dimensions will define the characeristics of all lines beyond
- those explicitly specified.
+Almost all music expressions inherit their interpretation context
+from their parent. In other words, suppose that the syntax for a
+music expression is
- @item A font declaration. Its syntax is
+@example
- @example
+ \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
+@end example
- @var{fontsize} @code{=} \font@keyindex{font} @var{fontname}
- @end example
+When the interpretation of this music expression starts, the context
+for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
+expression.
- @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).
-@end itemize
+Lastly, you may wonder, why this:
+@quotation
+@example
+\score @{
+ \notes \relative c'' @{
+ c4 d4 e4
+ @}
+@}
+@end example
-@cindex changing font size and paper size
+@end quotation
-The Feta font provides musical symbols at six different sizes. These
-fonts are 11 point, 13 point, 16 point, 20 point,
-23 point, and 26 point. The point size of a font is the
-height of the five lines in a staff when displayed in the font.
+doesn't result in this:
-Definitions for these sizes are the files @file{paperSZ.ly}, where
-@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
-any of these files, the identifiers @code{paper_eleven},
-@code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
-@code{paper_twentythree}, and @code{paper_twentysix} are defined
-respectively. The default @code{\paper} block is also set.
+@lilypond[]
-To change the paper size, you must first set the
-@code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
-@code{a4}, @code{letter}, or @code{legal}. After this specification,
-you must set the font as described above. If you want the default
-font, then use the 20 point font. The new paper size will not
-take effect if the font is not loaded and selected afterwards. Paper
-size selection works by loading a file named after the paper size you
-select.
+ \score {
+ \notes \relative c'' {
+ <c4> <d4> <e4>
+ }
+ }
+@end lilypond
+For the @code{c4}, a default @code{Staff} (with a contained
+@code{Voice}) context is created. After the @code{c4} ends, no
+music refers to this default staff, so it would be ended, with the
+result shown. To prevent this inconvenient behavior, the context to
+which the sequential music refers is adjusted during the
+interpretation. So after the @code{c4} ends, the context of the
+sequential music is also the default @code{Voice} context.
+The @code{d4} gets interpreted in the same context
+as @code{c4}.
-@cindex paper variables
+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.
-@node Paper variables
-@section Paper variables
+Properties can be preset within the @code{\translator} block
+corresponding to the appropriate context. In this case, the syntax
+is
-There is a large number of paper variables that are used to control
-details of the layout. These variables control the defaults for the
-entire score. Usually, they do not have to be changed; they are by
-default set to values that depend on the font size in use. The
-values are used by the graphic objects while formatting the score;
-they are therefore implementation dependent. Most variables are
-accompanied by documentation in the initalization file
-@file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
-height in points.
+@example
+ @var{propname} @code{=} @var{value}
+@end example
-Nevertheless, here are some variables you may want to use or change:
+This assignment happens before interpretation starts, so a
+@code{\property} expression will override any predefined settings.
-@table @code
- @item @code{indent}@indexcode{indent}
- The indentation of the first line of music.
+The property settings are used during the interpretation phase. They
+are read by the LilyPond modules where interpretation contexts are
+built of. These modules are called @emph{translators}. Translators for
+notation are called @emph{engravers}, and translators for sound are
+called @emph{performers}.
- @item @code{interline}@indexcode{interline}
- 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.
-
- @item @code{linewidth}@indexcode{linewidth}
- 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{rulethickness}@indexcode{rulethickness}
- Determines the thickness of staff and bar lines.
-@end table
+@c_ {Lexer innards}
+@node Lexer innards
+@section Lexer innards
+@cindex Lexer innards
+@menu
+* Top level::
+* Identifiers::
+* Assignments::
+* Lexical details::
+* Lexical modes::
+* Ambiguities::
+@end menu
+@c_ {Top level}
+@node Top level
+@subsection Top level
+@cindex Top level
-@node contextdefs
-@section contextdefs
+This section describes what you may enter at top level.
-@cindex context definition
-A notation contexts is defined by the following information
+@unnumberedsubsec Score definition
+@cindex score definition
-@enumerate i
- @item A name.
+The output is generated combining a music expression with an output
+definition. A score block has the following syntax:
- @item The LilyPond modules that do the actual conversion of music to
- notation. Each module is a so-called
- @emph{engraver}
-@cindex engraver
-.
+@example
+ \score @{ @var{musicexpr} @var{outputdefs} @}
+@end example
- @item How these modules should cooperate, i.e. which ``cooperation
- module'' should be used. This cooperation module is a special
- type of engraver.
+@var{outputdefs} are zero or more output definitions. If no output
+definition is supplied, the default @code{\paper} block will be added.
- @item What other contexts the context can contain,
- @item What properties are defined.
-@end enumerate
+@c_ {Score}
+@subsubsection Score
+@cindex Score
-A context definition has this syntax:
+@c_ {Paper}
+@subsubsection Paper
+@cindex Paper
-@example
+@c_ {Midi}
+@subsubsection Midi
+@cindex Midi
- \translator @code{@{}
- @var{translatorinit} @var{translatormodifierlist}
- @code{@}}
-@end example
+@c_ {Header}
+@subsubsection Header
+@cindex Header
+@cindex @code{\header}
-@var{translatorinit} can be an identifier or of the form
+The syntax is
@example
-
- \type @var{typename} @code{;}
+ \header @{ @var{key1} = @var{val1};
+@cindex @code{ly2dvi}
+ @var{key2} = @var{val2}; @dots{} @}
@end example
-@var{typename} is one of
-
-@table @code
- @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
- The standard cooperation engraver.
- @item @code{Score_engraver}@indexcode{Score_engraver}
- This is cooperation module that should be in the top level context.
-
- @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
- This is a special cooperation module (resembling
- @code{Score_engraver}) that is used to created an embedded
- `miniscore'.
-@end table
+A header describes 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.
-@var{translatormodifierlist} is a list of items where each item is
-one of
+It is customary to put the @code{\header} at the top of the file.
-@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
- significant.
-
- @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.
+@subsubsection Default output
- 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 the context to create by
- default.
-
- @item @code{\remove} @var{engravername} @code{;}
- Remove a previously added (with @code{\consists}) engraver.
-
- @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.
+A @code{\midi} or @code{\paper} block at top-level sets the default
- @item @var{propname} @code{=} @var{value} @code{;}
- A property assignment. It is allowed to use reals for
- @var{value}.
+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: see @ref{Music expressions}
+@item Identifier
+@item Translator_def:
+See section @ref{contextdefs} for more information
+@item Duration
+@item Pitch
+@item Score
+@item Music_output_def
+@item Moment (rational number)
@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
+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.
-@quotation
+@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})
+@c @item Audio_element: (todo, smobme)
+@end itemize
-@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
-@end quotation
+@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.
-@cindex paper types, engravers, and pre-defined translators
+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.
-Some pre-defined identifiers can simplify modification of
-translators. The pre-defined identifiers are:
+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 alphanumeric. It is impossible to refer to an identifier
+whose name is the same as the name of a keyword.
-@table @code
- @item @code{StaffContext}@indexcode{StaffContext}
- Default Staff context.
+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.
- @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
- Default RhythmicStaff context.
+@example
+foo = \foo * 2.0
+@end example
- @item @code{VoiceContext}@indexcode{VoiceContext}
- Default Voice context.
+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
+@}
- @item @code{ScoreContext}@indexcode{ScoreContext}
- Default Score context.
+\paper @{
+\paperIdent % correct
+foo = 1.0
+@}
+@end example
- @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
- Score context with numbering at the Score level.
- @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
- Staff context with numbering at the Staff level.
- @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
- Staff context that does not print if it only contains rests.
- Useful for orchestral scores.@footnote{Harakiri, also called
- Seppuku, is the ritual suicide of the Samourai.}
+@c_ {Lexical details}
+@node Lexical details
+@subsection Lexical details
+@cindex Lexical details
+@menu
+@end menu
- @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
+@c_ {Comments}
+@subsubsection Comments
+@cindex Comments
- @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
-@end table
+@cindex @code{%}
-Using these pre-defined values, you can remove or add items to the
-translator:
-@quotation
+A one line comment is introduced by a @code{%} character.
+Block comments are started by @code{%@{} and ended by `@code{%@}}'.
+They cannot be nested.
-@example
-\paper @{
- \translator @{
- \StaffContext
- \remove Some_engraver;
- \consists Different_engraver;
- @}
-@}
-@end example
+@c_ {Direct Scheme}
+@subsubsection Direct Scheme
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
-@end quotation
-
+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
-@node engravers
-@section engravers
+@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).
-The engravers for paper output are:
+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.
-[incomplete, FIXME]
-@table @code
- @item @code{Bar_engraver}@indexcode{Bar_engraver}
- Engraves bar lines. Normally in @code{Staff} and
- @code{RhythmicStaff}.
+@c_ {Keywords}
+@subsubsection Keywords
+@cindex Keywords
- @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.
+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
- @item @code{Beam_req_swallow_translator}
- @indexcode{Beam_req_swallow_translator}
- Swallows beam requests. In @code{LyricVoice}.
+@c_ {Integers}
+@subsubsection Integers
- @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver}
- Engraves chord names. Normally in @code{ChordNameVoice} .
+@cindex integers
+@cindex @code{+}
+@cindex @code{-}
+@cindex @code{*}
+@cindex @code{/}
- @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver}
+Formed from an optional minus sign followed by digits. Arithmetic
+operations cannot be done with integers, and integers cannot be mixed
+with reals.
- @item @code{Clef_engraver}@indexcode{Clef_engraver}
- Engraves the clef symbol. Normally in @code{Staff}.
+@c_ {Reals}
+@subsubsection Reals
+@cindex real numbers
- @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}.
+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.
- @item @code{Local_key_engraver}@indexcode{Local_key_engraver}
+@cindex @code{\mm},
+@cindex @code{\in}
+@cindex @code{\cm}
+@cindex @code{\pt}
+@cindex dimensions
- @item @code{Lyric_engraver}@indexcode{Lyric_engraver}
- Engraves lyrics. Normally in @code{LyricVoice}.
+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
+to a real that is the internal representation of dimensions.
- @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}
+@c_ {Strings}
+@subsubsection Strings
+@cindex string
+@cindex concatenate
- @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.
+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.
- @item @code{Priority_horizontal_align_engraver}
- @indexcode{Priority_horizontal_align_engraver}
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
- @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}.
+@c_ {Main input}
+@subsubsection Main input
+@cindex Main input
- @item @code{Rest_engraver}@indexcode{Rest_engraver}
- Engraves rests. Normally in @code{Voice}.
+@cindex @code{\maininput}
- @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver}
+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.
- @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver}
+@c_ {File inclusion}
+@subsubsection Main input
+@cindex Main input
- @item @code{Script_engraver}@indexcode{Script_engraver}
- Handles note ornaments generated by @code{\script}. Normally in
- @code{Voice}.
+@subsubsection File inclusion
+@cindex @code{\include}
+@example
+ \include @var{filename}
+@end example
- @item @code{Separating_line_group_engraver}
- @indexcode{Separating_line_group_engraver}
+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,
- @item @code{Skip_req_swallow_translator}
- @indexcode{Skip_req_swallow_translator}
+@subsubsection Version information
+@cindex @code{\version}
+@example
+ \version @var{string} ;
+@end example
- @item @code{Slur_engraver}@indexcode{Slur_engraver}
- Engraves slurs. Normally in @code{Voice}.
+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}.
- @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}.
+@cindex convert-ly
- @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver}
- @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver}
- @item @code{Instrument_name_engraver}@indexcode{Instrument_name_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}
+@c_ {Pitch names}
+@subsubsection Pitch names
+@cindex Lexical modes
+@cindex pitch names
- @item @code{Stem_engraver}@indexcode{Stem_engraver}
- Engraves stems. Normally in @code{Voice}.
+@cindex note names
+@cindex chord modifier names
- @item @code{Ties_engraver}@indexcode{Ties_engraver}
- Engraves ties. Normally in @code{Voice}.
+Note names and chord modifiers can be customised for nationalities.
+languages and conventions. The syntax is as follows.
+@cindex @code{\pitchnames}
+@cindex @code{\chordmodifiers}
- @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver}
- Engraves the time signature. Normally in @code{Staff} and
- @code{RhythmicStaff}.
+@example
+ \pitchnames @var{scheme-alist}
+ \chordmodifiers @var{scheme-alist}
+@end example
- @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}.
+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
+section @ref{Other languages}.
+A @code{\paper} block at top level sets the default paper block. A
+@code{\midi} block at top level works similarly.
- @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver}
- Engraves tuplet brackets? In @code{Staff}.
+@c_ {Assignments}
+@subsubsection Assignments
+@cindex assignments
+@cindex @code{#}
- @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver}
-@end table
+Identifier assignments may appear at top level. @ref{Assignments}
-@node Sound output
-@section Sound output
+@c_ {Direct scheme}
+@subsubsection Direct scheme
+@cindex Direct scheme
+Scheme statements maybe issued to produce interesting side-effects.
-The MIDI block is analogous to the paper block, but it is simpler.
-The @code{\midi} block can contain:
-@cindex MIDI block
+@c_ {Lexical modes}
+@node Lexical modes
+@subsection Lexical modes
+@cindex Lexical modes
-@itemize @bullet
- @item a @code{\tempo} definition
- @item context definitions
-@end itemize
+@cindex Lexical modes
+@cindex modes
-Assignments in the @code{\midi} block are not allowed.
+To simplify entering notes, lyrics, and chords, 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
+a keyword or as an identifier. The behavior of the modes differs in
+two ways: Different modes treat unquoted words differently, and
+different modes have different rules for deciding what is a word.
+@table @asis
+@item Normal mode.
+@cindex normal mode
+
+At the start of parsing, 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.
+@item Note mode
+See @ref{Note entry}.
-@cindex context definition
+@item Lyrics mode
+See @ref{Lyrics entry}.
-Context definitions follow precisely the same syntax as within the
-\paper block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/performer.ly}.
+@item Chord mode
+See @ref{Chord entry}.
+@end table
+@cindex input modes
+@cindex mode switch
-@cindex MIDI instrument names
+@cindex @code{\notes}
+@cindex @code{\chords}
+@cindex @code{\lyrics}
-@node midilist
-@section midilist
+Mode switching keywords form compound music expressions: @code{\notes}
+@var{musicexpr}, @code{\chords} @var{musicexpr},
+and @code{\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 @ref{Lexical modes} for more information on modes.
-The MIDI instrument name is set by the
-@code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
-if that property is not set, the
-@code{Staff.instrument}@indexcode{Staff.instrument} property. The
-instrument name should be chosen from the following list. If the
-selected string does not exactly match, then LilyPond uses the default
-piano.
+@c_ {Ambiguities}
+@node Ambiguities
+@subsection Ambiguities
+@cindex ambiguities
+@cindex grammar
-@c @quotation
-@example
-"acoustic grand" "contrabass" "lead 7 (fifths)"
-"bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
-"electric grand" "pizzicato strings" "pad 1 (new age)"
-"honky-tonk" "orchestral strings" "pad 2 (warm)"
-"electric piano 1" "timpani" "pad 3 (polysynth)"
-"electric piano 2" "string ensemble 1" "pad 4 (choir)"
-"harpsichord" "string ensemble 2" "pad 5 (bowed)"
-"clav" "synthstrings 1" "pad 6 (metallic)"
-"celesta" "synthstrings 2" "pad 7 (halo)"
-"glockenspiel" "choir aahs" "pad 8 (sweep)"
-"music box" "voice oohs" "fx 1 (rain)"
-"vibraphone" "synth voice" "fx 2 (soundtrack)"
-"marimba" "orchestra hit" "fx 3 (crystal)"
-"xylophone" "trumpet" "fx 4 (atmosphere)"
-"tubular bells" "trombone" "fx 5 (brightness)"
-"dulcimer" "tuba" "fx 6 (goblins)"
-"drawbar organ" "muted trumpet" "fx 7 (echoes)"
-"percussive organ" "french horn" "fx 8 (sci-fi)"
-"rock organ" "brass section" "sitar"
-"church organ" "synthbrass 1" "banjo"
-"reed organ" "synthbrass 2" "shamisen"
-"accordion" "soprano sax" "koto"
-"harmonica" "alto sax" "kalimba"
-"concertina" "tenor sax" "bagpipe"
-"acoustic guitar (nylon)" "baritone sax" "fiddle"
-"acoustic guitar (steel)" "oboe" "shanai"
-"electric guitar (jazz)" "english horn" "tinkle bell"
-"electric guitar (clean)" "bassoon" "agogo"
-"electric guitar (muted)" "clarinet" "steel drums"
-"overdriven guitar" "piccolo" "woodblock"
-"distorted guitar" "flute" "taiko drum"
-"guitar harmonics" "recorder" "melodic tom"
-"acoustic bass" "pan flute" "synth drum"
-"electric bass (finger)" "blown bottle" "reverse cymbal"
-"electric bass (pick)" "skakuhachi" "guitar fret noise"
-"fretless bass" "whistle" "breath noise"
-"slap bass 1" "ocarina" "seashore"
-"slap bass 2" "lead 1 (square)" "bird tweet"
-"synth bass 1" "lead 2 (sawtooth)" "telephone ring"
-"synth bass 2" "lead 3 (calliope)" "helicopter"
-"violin" "lead 4 (chiff)" "applause"
-"viola" "lead 5 (charang)" "gunshot"
-"cello" "lead 6 (voice)"
-@end example
+The grammar contains a number of ambiguities. We hope to resolve them at
+some time.
-@c @end quotation
+@itemize @bullet
+ @item The assignment
+ @example
+foo = bar
+@end example
-@cindex MIDI types and performers
+ can be interpreted as making a string identifier @code{\foo}
+ containing @code{"bar"}, or a music identifier @code{\foo}
+ containing the syllable `bar'.
-The types available for MIDI translators are:
+ @item The assignment
-@table @code
- @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
+ @example
+foo = -6
+@end example
-The performers for MIDI translators are:
+ can be interpreted as making an integer identifier
+ containing -6, or a Request identifier containing the
+ fingering `6' (with neutral direction).
-@table @code
- @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
+ @item If you do a nested repeat like
+ @quotation
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
-@node Pre-defined Identifiers
+ @end quotation
-@section Pre-defined Identifiers
+ then it is ambiguous to which @code{\repeat} the
+ @code{\alternative} belongs. This is the classic if-then-else
+ dilemma. It may be solved by using braces.
-@cindex pre-defined identifiers
+ @item (an as yet unidentified ambiguity :-)
+@end itemize
-Various identifiers are defined in the initialization files to
-provide shorthands for some settings. Most of them are in
-@file{ly/declarations.ly}.
-@table @code
- @item @code{\break}@keyindex{break}
- 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.
+@c_ {Unsorted}
+@node Unsorted
+@section Unsorted
- @item @code{\free}@keyindex{free}
- Used for setting direction setting properties. Is equal
- to 0.
+[mucho todo]
- @item @code{\left}@keyindex{left}
- Used for setting text alignment property. Is equal to -1.
+Translation?
- @item @code{\nobreak}@keyindex{nobreak}
- Prevent a line break in music by using a large negative argument
- for the keyword @code{\penalty}.
+@cindex properties
+@unnumberedsubsec Translation property
- @item @code{\none}@keyindex{none}
- Used for setting @code{Score.beamslopedamping} and
- @code{Score.beamquantisation} properties. Is equal to 0.
+@cindex @code{\property}
+@example
+ \property @var{contextname}.@var{propname} = @var{value}
+@end example
- @item @code{\normal}@keyindex{normal}
- Used for setting @code{Score.beamslopedamping} and
- @code{Score.beamquantisation} properties. Is equal to 1.
+Sets the @var{propname} property of the context @var{contextname} to
+the specified @var{value}. All three arguments are strings.
+Depending on the context, it may be necessary to quote the strings or
+to leave space on both sides of the dot.
- @item @code{\normalkey}@keyindex{normalkey}
- Select normal key signatures where each octave has the same key
- signature. This sets the @code{Staff.keyoctaviation} property.
+@cindex translator switches
+@unnumberedsubsec Translator switches
- @item @code{\right}@keyindex{right}
- Used for setting text alignment property. Is set to 1.
+@cindex @code{\translator}
+@example
+ \translator @var{contexttype} = @var{name}
+@end example
- @item @code{\shiftoff}@keyindex{shiftoff}
- Disable horizontal shifting of note heads that collide. Sets the
- @code{Voice.horizontalNoteShift} property.
+A music expression indicating that the context which is a direct
+child of the a context of type @var{contexttype} should be shifted to
+a context of type @var{contexttype} and the specified name.
- @item @code{\shifton}@keyindex{shifton}
- Enable note heads that collide with other note heads to be
- shifted horiztonally. Sets the @code{Voice.horizontalNoteShift}
- property.
+Usually this is used to switch staffs in Piano music, e.g.
- @item @code{\slurboth}@keyindex{slurboth}
- Allow slurs to be above or below notes. This sets the
- @code{Voice.slurVerticalDirection} property.
+@example
+ \translator Staff = top @var{Music}
+@end example
- @item @code{\slurdown}@keyindex{slurdown}
- Force slurs to be below notes. This sets the
- @code{Voice.slurVerticalDirection} property.
- @item @code{\slurup}@keyindex{slurup}
- Force slurs to be above notes. This sets the
- @code{Voice.slurVerticalDirection} property.
+@cindex output properties
+@unnumberedsubsec Output properties
- @item @code{\specialkey}@keyindex{specialkey}
- Allow key signatures do differ in different octaves. This sets
- the @code{Staff.keyoctaviation} property.
+These allow you to tweak what is happening in the back-end
+directly. If you want to control every detail of the output
+formatting, this is the feature to use. The downside to this is that
+you need to know exactly how the backend works. Example:
- @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.
- @item @code{\stemdown}@keyindex{stemdown}
- Force stems, beams, and slurs to point down. This sets the
- @code{Voice.verticalDirection} property.
+@lilypond[fragment,verbatim]
+\relative c'' { c4
+ \context Staff \outputproperty
+ #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(5.0 . 7.5)
+<c8 e g> }
+@end lilypond
- @item @code{\stemup}@keyindex{stemup}
- Force stems, beams and slurs to point up. This sets the
- @code{Voice.verticalDirection} property.
+This selects all note heads occurring at current staff level, and sets
+the @code{extra-offset} of those heads to @code{(5,7.5)}, shifting them
+up and right.
- @item @code{\traditional}@keyindex{traditional}
- Used for setting the @code{Score.beamquantisation} property. Is
- equal to 2.
+Use of this feature is entirely on your own risk: if you use this, the
+result will depend very heavily on the implementation of the backend,
+which we change regularly and unscrupulously.
+
+
+@c_{Local emacs vars}
+@c Local variables:
+@c mode: texinfo
+@c minor-mode: font-lock
+@c minor-mode: outline
+@c xoutline-layout: (0 : -1 -1 0)
+@c outline-layout: (-1 : 0)
+@c outline-primary-bullet: "{"
+@c outline-stylish-prefixes: nil
+@c outline-override-protect: t
+@c End:
- @item @code{\up}@keyindex{up}
- Used for setting various direction properties. Is equal
- to 1.
-@end table