-@c -*-texinfo-*-
-@c TODO:
-@c - Reinsert subsection commands that were lost in the
-@c ancient conversion from YODL! /MB
-@c - Restructure! Separate internal commands from user level commands. /MB
-@c - Add some words about Guile. /MB
-@c - Fix indexing (keyindex) so it doesn't add line breaks /MB
+
+@c Note:
@c
-@c FIXME: Index has two alphabetically sorted lists @code vs plain?
-@c
-@c If we'd include the auto-generated documentation, we 'd get a lot of
-@c very useful index entries.
-@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
+
+
+@ignore
+ TODO:
+
+ fix all FIXMEs
+
+ Rhythm staff (clef, x-notehead)
+
+@end ignore
+@c .{Reference Manual}
+
@node Reference Manual
@chapter Reference Manual
-@menu
-* Overview:: Overview
-* Top level:: Top level
-* Pitch names:: Pitch names
-* Lexical conventions:: Lexical conventions
-* Other languages:: Note names in various languages
-* Lexical modes:: modes
-* Types:: Types
-* Music expressions:: Music expressions
-* Atomic music expressions:: Atomic music expressions
-* Note specification:: notedesc
-* barlines:: barlines
-* Manual beams:: Manual beam
-* stem tremolo:: tremolo
-* Compound music expressions:: Compound music expressions
-* relative:: relative
-* Repeats:: Repeats
-* transpose:: transpose
-* Ambiguities:: Ambiguities
-* Notation conversion specifics:: Notation conversion specifics
-* Automatic Beaming:: Automatic Beaming
-* Chord Names:: Chord Names
-* lyricprint:: lyricprint
-* Notation Contexts:: Notation Contexts
-* Properties:: Changing formatting
-* Page layout:: Layout
-* contextdefs:: contextdefs
-* Sound output:: Sound output
-* midilist:: midilist
-* Pre-defined Identifiers:: Pre-defined Identifiers
-* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
-* Engravers:(lilypond-internals)LilyPond engravers.
-* Backend:(lilypond-internals)LilyPond backend.
-@end menu
+This document describes GNU LilyPond and its input format. This document
+has been revised for LilyPond 1.3.131
+
+@menu
+* Overview::
+* Note entry::
+* Music notation::
+* Polyphony::
+* Spanners::
+* Repeats::
+* Piano music::
+* Lyrics::
+* Chords::
+* Writing parts::
+* Custodes::
+* Tuning output::
+* Page layout::
+* Sound::
+* Music entry::
+* Engravers::
+* Syntactic details::
+@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 This format represents a
-piece of music in an elegant way, but contains enough information for
-both automatic typesetting and automatic performances.
+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'.
+
+Internally, LilyPond is written in a mixture of Scheme and C++. Most of
+the algorithms and low-level routines are written in C++, but these low
+level components are glued together using Scheme data
+structures. LilyPond is linked to GUILE, GNU's Scheme library for
+extension.
+
+When lilypond is run to typeset sheet music, the following happens:
+@itemize @bullet
+@item GUILE Initialization: various scheme files are read
+@item parsing: first standard .ly initialization files are read, and
+then the user @file{.ly} file is read.
+@item interpretation: the music in the file is processed "in playing
+order", i.e. in the same order as your eyes scan sheet music, and in the
+same order that you hear the notes play.
+
+@item typesetting:
+in this step, the results of the interpretation, a typesetting
+specification, is solved.
+
+@item the visible results ("virtual ink") is written to the output file.
+@end itemize
-LilyPond input can be classified into three types:
+These stages, involve data of a specific type: during parsing,
+@strong{Music} objects are created. During the interpretation,
+@strong{context} is constructed, and with this context af network of
+@strong{graphical objects} (``grobs'') is created. The grobs contain
+unknown variables, and the network forms a set of equations. After
+solving the equations and filling in these variables, the printed output
+(in the form of @strong{molecules}) is written to an output file.
+
+These threemanship of tasks (parsing, translating, typesetting) and
+data-structures (music, context, graphical objects) permeates the entire
+design of the program. This manual is ordered in terms of user
+tasks. With each concept will be explained to which of the three parts
+it belongs.
+
+LilyPond input can be classified into three types:
@itemize @bullet
@item musical expressions: a musical expression is some combination of
rest, notes, lyrics
can enter and edit them in manageable chunks.
@end itemize
-@node Top level
-@section Top level
-
-This section describes what you may enter at top level.
-
-
-
-@cindex score definition
-The output is generated combining a music expression with an output
-definition. A score block has the following syntax:
-@example
- \score @{ @var{musicexpr} @var{outputdefs} @}
-@end example
-@var{outputdefs} are zero or more output definitions. If no output
-definition is supplied, the default @code{\paper} block will be added.
+@c . {Note entry}
+@node Note entry
+@section Note entry
+@cindex Note entry
-@cindex header
+@menu
+* Notes mode::
+* Pitches::
+* Defining pitch names::
+* Durations::
+* Notes::
+* Rests::
+* Skip::
+@end menu
-@keyindex{header}
+@c . {Notes mode}
+@node Notes mode
+@subsection Notes mode
-The syntax is
+@cindex note mode
-@example
- \header @{ @var{key1} = @var{val1};
- @var{key2} = @var{val2}; @dots{} @}
-@end example
+@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.
-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.
+Since combinations of numbers and dots are used for indicating
+durations, it is not possible to enter real numbers in this mode.
-It is customary to put the @code{\header} at the top of the file.
+@cindex Notes mode
-@node Pitch names
-@section Pitch names
+@c . {Pitches}
+@node Pitches
+@subsection Pitches
+@cindex Pitch names
+@cindex Note specification
+@cindex pitches
+@cindex entering notes
-@cindex pitch names
-@cindex note names
-@cindex chord modifier names
+The verbose syntax for pitch specification is
-Note names and chord modifiers can be customised for nationalities.
-languages and conventions. The syntax is as follows.
+@cindex @code{\pitch}
@example
- \pitchnames@keyindex{pitchnames} @var{scheme-alist}
- \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
+ \pitch @var{scmpitch}
@end example
-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.
+@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
-Identifier assignments may appear at top level. Semicolons are
-forbidden after top level assignments.
+In Note and Chord mode, pitches may be designated by names. The default
+names are the Dutch note names. The notes are specified by the letters
+@code{c} through @code{b}, where @code{c} is an octave below middle C
+and the letters span the octave above that C. In 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.
-@cindex assignments
+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
-@node Lexical conventions
-@section Lexical conventions
+@cindex @code{'}
+@cindex @code{,}
-@cindex lexical conventions
-@unnumberedsubsec Comments
-@cindex comment
+The optional octave specification takes the form of a series of
+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.
-@indexcode{%}
+@lilypond[fragment,verbatim,center]
+ c' d' e' f' g' a' b' c''
+@end lilypond
-A one line comment is introduced by a `@code{%}' character.
-Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
-They cannot be nested.
+@lilypond[fragment,verbatim,center]
+ cis' dis' eis' fis' gis' ais' bis'
+@end lilypond
-@unnumberedsubsec Scheme
+@lilypond[fragment,verbatim,center]
+ ces' des' es' fes' ges' as' bes'
+@end lilypond
-@indexcode{#}
+@lilypond[fragment,verbatim,center]
+ cisis' eisis' gisis' aisis' beses'
+@end lilypond
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. The interpreter is accessed by the pound sign:
+@lilypond[fragment,verbatim,center]
+ ceses' eses' geses' ases' beses'
+@end lilypond
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-Whereever the syntax allows Scheme expressions, you may enter one as
+@c . {Defining pitch names}
+@node Defining pitch names
+@subsection Defining pitch names
-@example
- #@var{scheme}
-@end example
+@cindex defining pitch names
+@cindex pitch names, defining
-Evaluates the specified Scheme code. If this is used at toplevel, then
-the result is discarded. Example:
+Note names and chord modifiers can be customised for nationalities. The
+syntax is as follows.
+
+@cindex @code{\pitchnames}
+@cindex @code{\chordmodifiers}
@example
- \property Staff.TestObject \override #'symbol = #(+ 1 2)
+ \pitchnames @var{scheme-alist}
+ \chordmodifiers @var{scheme-alist}
@end example
-(in this case, @code{\override} expects two Scheme expressions.
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+specific examples how to do this. Some national note names have been
+provided, among others: Norwegian, Swedish, German, Italian, Catalan,
+French, Dutch and English.
-[refer appendix/ online intro on Scheme]
-@unnumberedsubsec Keywords
+@c . {Durations}
+@node Durations
+@subsection Durations
-@cindex keyword
-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 an verbose duration specification is
@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 musicalpitch
-time times midi mm name pitchnames notes outputproperty
-override set revert partial paper penalty property pt
-relative remove repeat addlyrics partcombine score
-script stylesheet skip textscript tempo translator
-transpose type
+ \duration @var{scmduration}
@end example
-@unnumberedsubsec Integers
+In Note, Chord, and Lyrics mode, durations may be designated by numbers
+and dots: durations are entered as their reciprocal values. For notes
+longer than a whole note, use identifiers.
-@cindex integer
+@quotation
-Formed from an optional minus sign followed by digits. Arithmetic
-operations cannot be done with integers, and integers cannot be mixed
-with reals.
+@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
-@unnumberedsubsec Reals
-@cindex real
-
+@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 {
+ \translator {
+ \StaffContext
+ \remove "Clef_engraver";
+ \remove "Staff_symbol_engraver";
+ \remove "Time_signature_engraver";
+ \consists "Pitch_squash_engraver";
+ }
+ }
+}
+@end lilypond
+@end quotation
-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.
+As you can see, the longa is not printed. To get a longa note head, you
+have to use a mensural note heads. This is done accomplished by setting
+the @code{style} property of the NoteHead grob to @code{mensural}.
-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.
+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 @code{.}
+
+@lilypond[fragment,verbatim,center]
+ a'4. b'4. c'2..
+@end lilypond
+@cindex @code{r}
+@cindex @code{s}
+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.
-@unnumberedsubsec
-@cindex string
-
-Begins and ends with the `@code{"}' character. To include a `@code{"}'
-character in a string write `@code{\"}'. Various other backslash
-sequences have special interpretations as in the C language. A string
-that contains no spaces can be written without the quotes. See
-@ref{Lexical modes} for details on unquoted strings; their interpretation varies
-depending on the situation. Strings can be concatenated with the
-`@code{+}' operator.
+@c . {Notes}
+@node Notes
+@subsection Notes
-The tokenizer accepts the following commands. They have no grammatical
-function, hence they can appear anywhere in the input.
+A note specification has the form
@example
- \maininput@keyindex{maininput}
+ @var{pitch}[@var{octavespec}][!][?][@var{duration}]
@end example
-This command is used in init files to signal that the user file must
-be read. This command cannot be used in a user file.
-
-@unnumberedsubsec file inclusion
-@example
- \include@keyindex{include} @var{file}
-@end example
+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
+@cindex @code{?}
+can be forced by adding an exclamation mark @code{!} after the pitch.
+A cautionary accidental,
+@cindex cautionary accidental
-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,
+i.e., an accidental within parentheses can be obtained by adding the
+question mark `@code{?}' after the pitch.
-@unnumberedsubsec Version information
+@lilypond[fragment,verbatim,center]
+ cis' d' e' cis' c'? d' e' c'!
+@end lilypond
-@example
- \version@keyindex{version} @var{string} ;
-@end example
-Specify the version of LilyPond that a file was written for. The
-argument is a version string in quotes, for example @code{"1.2.0"}.
-This is used to detect invalid input, and to aid
-@code{convert-ly}, a tool that automatically upgrades input files.
-@cindex convert-ly
+@c . {Rests}
+@node Rests
+@subsection Rests
+@cindex Rests
-@node Other languages
-@section Other languages
-@cindex Note names, international
+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.
-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:
-@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
+@c . {Skip}
+@node Skip
+@subsection Skip
+@cindex Skip
-Pitch names can be redefined using the @code{\pitchnames} command, see
-@ref{Pitch names}.
-@node Lexical modes
-@section Lexical modes
-@cindex Lexical modes
-@cindex modes
+@example
+ \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.
-To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
-special input modes on top of the default mode. In each mode, words
-are identified on the input. If @code{"word"} is encountered, it is
-treated as a string. If @code{\word} is encountered, it is treated as
-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 @samp
- @item Normal mode.
-@cindex mode!normal
-
- At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal
- mode, a word is an alphabetic character followed by alphanumeric
- characters. If @code{word} is encountered on the input it is
- treated as a string.
-
- @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{_}' 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{}.
-@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
+@c . {Music notation}
+@node Music notation
+@section Music notation
+@cindex Music notation
+@menu
+* Key::
+* Breath marks::
+* Time signature::
+@end menu
- Since combinations of numbers and dots are used for indicating
- durations, you can not enter real numbers in this mode.
-@end table
+@c . {Key}
+@node Key
+@subsection Key
+@cindex Key
-[todo: include short table showign differences]
+@cindex @code{\key}
-@node Types
-@section Types
+@example
+ @code{\key} @var{pitch} @var{type} @code{;}
+@end example
+@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.
+
+This command sets @code{Staff.keySignature}.
+
+
+
+@cindex @code{keySignature}
+
+@c . {Clef changes}
+@subsubsection Clef changes
+@cindex @code{\clef}
+@example
+ \clef @var{clefname} @code{;}
+@end example
-@cindex Identifiers
+Short-cut for
-[say something about types]
+@example
+ \property Staff.clefGlyph = @var{symbol associated with clefname}
+ \property Staff.clefPosition = @var{clef Y-position for clefname}
+ \property Staff.clefOctavation = @var{extra pitch of clefname}
+@end example
-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,
+Supported clef-names include
@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 (TODO: this is not really a Scheme object
-yet. Nevertheless, you can use identifiers to make references to them )
- @item Moment (rational number)
+@item treble, violin, G, G2: G clef on 2nd line
+@item french: G clef on 1st line
+@item soprano: C clef on 1st line
+@item mezzosoprano: C clef on 2nd line
+@item alto: C clef on 3rd line
+@item tenor: C clef on 4th line
+@item baritone: C clef on 5th line
+@item varbaritone: F clef on 3rd line
+@item bass, F: F clef on 4th line
+@item subbass: F clef on 5th line
+@item percussion: percussion clef
@end itemize
-LilyPond also includes some transient object types. Objects of these
-types are built during a LilyPond run, and do not `exist' per se within
-your input file. These objects are created as a result of your input
-file, so you can include commands in the input to manipulate them,
-during a lilypond run.
+Supported associated symbols (for Staff.clefGlyph) are:
@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.
- @item Font_metric: object representing a font. (Not yet user
-accessible.)
-
-@c @item Audio_element: (todo, smobme)
+@item clefs-C: modern style C clef
+@item clefs-F: modern style F clef
+@item clefs-G: modern style G clef
+@item clefs-vaticana_do: Editio Vaticana style do clef
+@item clefs-vaticana_fa: Editio Vaticana style fa clef
+@item clefs-medicaea_do: Editio Medicaea style do clef
+@item clefs-medicaea_fa: Editio Medicaea style fa clef
+@item clefs-mensural1_c: modern style mensural C clef
+@item clefs-mensural2_c: historic style small mensural C clef
+@item clefs-mensural3_c: historic style big mensural C clef
+@item clefs-mensural1_f: historic style traditional mensural F clef
+@item clefs-mensural2_f: historic style new mensural F clef
+@item clefs-mensural_g: historic style mensural G clef
+@item clefs-hufnagel_do: historic style hufnagel do clef
+@item clefs-hufnagel_fa: historic style hufnagel fa clef
+@item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef
+@item clefs-percussion: modern style percussion clef
@end itemize
-Identifiers allow objects to be assigned to names during the parse
-stage. To assign an identifier, you use `@var{name}=@var{value}' and to
-refer to an identifier, you preceed its name with a backslash:
-`@code{\}@var{name}'. Identifier assignments must appear at top level
-in the @emph{Lilypond} file. Semicolons are forbidden after assignments
-appearing at top level but they are obligatory after assignments
-appearing in the @code{\paper} block, see Section @ref{Page layout}.
+@emph{Modern style} means "as is typeset in current editions".
+@emph{Historic style} means "as was typeset or written in contemporary
+historic editions". @emph{Editio XXX style} means "as is/was printed in
+Editio XXX".
-@var{value} is any valid Scheme value or any of the input-types listed
-above.
+@node Breath marks
+@subsection Breath marks
-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.
+Breath marks are entered using @code{\breathe}:
+
+@lilypond[fragment,relative]
+c'4 \breathe d4
+@end lilypond
-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.
+
+
+@c . {Time signature}
+@node Time signature
+@subsection Time signature
+@cindex Time signature
+@cindex meter
+@cindex @code{\time}
@example
- foo = \foo * 2.0
+ \time @var{numerator}@code{/}@var{denominator} @code{;}
@end example
-When an identifier is referenced, the information it points to is
-copied. For this reason, an identifier reference must always be the
- first item in a block.
+A short-cut for doing
@example
-\paper @{
- foo = 1.0
- \paperIdent % wrong and invalid
-@}
-
-\paper @{
- \paperIdent % correct
- foo = 1.0
-@}
+ \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
@end example
+See the documentation of @code{timeSignatureFraction}
-@node Music expressions
-@section Music expressions
-@cindex music expressions
+@c . {Partial}
+@subsubsection Partial
+@cindex Partial
+@cindex anacrusis
+@cindex upstep
+@cindex partial measure
+@cindex measure, partial
+@cindex shorten measures
+@cindex @code{\partial}
+@example
+ \partial @var{duration} @code{;}
+@end example
-Music in @emph{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:
+Short cut for
-@example
-\sequential @{ c4 d4 @}
-@end example
+@example
+ \property Score.measurePosition = @var{length of duration}
+@end example
+@cindex @code{|}
-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).
+See the documentation of @code{measurePosition}.
-Atomic music expression are discussed in
-subsection @ref{Atomic music expressions}. Compound music expressions are
-discussed in subsection @ref{Compound music expressions}.
-@node Atomic music expressions
-@section Atomic music expressions
+@c . {Polyphony}
+@node Polyphony
+@section Polyphony
+@cindex Polyphony
+[todo : collisiosn, rest-collisinos, voiceX identifiers, how to
+which contexts to instantiate.]
-@cindex pitch
+@table @code
+@cindex @code{\shiftOff}
+ @item @code{\shiftOff}
+ Disable horizontal shifting of note heads that collide.
-@cindex duration
-
+@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.
-The syntax for pitch specification is
+@cindex @code{\stemBoth}
+ @item @code{\stemBoth}
+ Allow stems, beams, and slurs to point either upwards or
+ downwards, decided automatically by LilyPond.
+@cindex @code{\stemDown}
+ @item @code{\stemDown}
+ Force stems, beams, and slurs to point down.
-@example
- \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
-@end example
+@cindex @code{\stemUp}
+ @item @code{\stemUp}
+ Force stems, beams and slurs to point up.
+@end table
-@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.
+@c . {Spanners}
+@node Spanners
+@section Spanners
+@cindex Spanners
-In Note and Chord mode, pitches may be designated by names. See
-section @ref{Other languages} for pitch names in different languages.
+@menu
+* Beam::
+* Slur ::
+* Phrasing slur::
+* Ornaments::
+* Grace notes::
+* Bar check::
+@end menu
-The syntax for duration specification is
-@example
- \duration@keyindex{duration}
- @{ @var{length} @var{dotcount} @}
-@end example
-@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}.
+@c . {Beam}
+@node Beam
+@subsection Beams
-In Note, Chord, and Lyrics mode, durations may be designated by
-numbers and dots.
+@cindex beams
+@c . {Automatic beams}
+@subsubsection Automatic beams
-@node Note specification
-@section Note specification
-@cindex Note specification
-@cindex pitches
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{Voice.noAutoBeaming}
-@cindex entering notes
+LilyPond will group flagged notes and generate beams autmatically, where
+appropriate.
+
+This feature can be disabled by setting the @code{Voice.noAutoBeaming}
+property to true, which you may find necessary for the melody that goes
+with lyrics, eg. Automatic beaming can easily be overridden for
+specific cases by specifying explicit beams. This is discussed in the
+next subsubsection.
-A note specification has the form
+
+@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
@example
- @var{pitch}[@var{octavespec}][!][?][@var{duration}]
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 1 4)
+\property Voice.autoBeamSettings \override
+ #'(begin * * * *) = #(make-moment 1 8)
@end example
+@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 * *)}.
+
+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.
-The pitch of the note is specified by the note's name.
+For example, to specify beam endings for beams that contain 32nd notes,
+you would use @code{(end * * 1 32)}.
-The default names are the Dutch note names. The notes are specified
-by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
-octave below middle C and the letters span the octave above that C.
-In Dutch,
-@cindex notenames!Dutch
-a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
-flat is formed by adding `@code{-es}'. Double sharps and double flats
-are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
-and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
-but both forms will be accepted.
-LilyPond has predefined sets of notenames for various languages. See
-section @ref{Other languages}.
+@c . {Manual beams}
+@cindex Automatic beams
+@subsubsection Manual beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
-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
-octave; each @code{,} lowers the pitch by an octave.
+In some cases it may be necessary to override LilyPond's automatic
+beaming algorithm. For example, the auto beamer will not beam over
+rests or bar lines, so if you want that, specify the begin and end point
+manually using @code{[} and @code{]}:
-@lilypond[fragment,verbatim,center]
- c' d' e' f' g' a' b' c''
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ r4 [r8 g'' a r8] r8 [g | a] r8
+ }
@end lilypond
-@lilypond[fragment,verbatim,center]
- cis' dis' eis' fis' gis' ais' bis'
-@end lilypond
-@lilypond[fragment,verbatim,center]
- ces' des' es' fes' ges' as' bes'
-@end lilypond
+@cindex @code{stemLeftBeamCount}
-@lilypond[fragment,verbatim,center]
- cisis' eisis' gisis' aisis' beses'
-@end lilypond
+If you have specific wishes for the number of beams, you can fully
+control the number of beams through the properties
+y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
-@lilypond[fragment,verbatim,center]
- ceses' eses' geses' ases' beses'
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ [f'8 r16 f g a]
+ [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
+ }
@end lilypond
+@end quotation
+@cindex @code{stemRightBeamCount}
+
+
+@c . {Adjusting beams}
+@unnumberedsubsubsec Adjusting beams
+@cindex Adjusting beams
+
+FIXME
-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
-@cindex reminder accidental
-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.
+
+
+
+@c . {Slur}
+@node Slur
+@subsection Slur
+@cindex slur
+
+@menu
+* Slur attachments::
+@end menu
+
+A slur connects chords and is used to indicate legato. Slurs 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 last note
+in the slur. This makes it possible to put a note in slurs from both
+sides:
@lilypond[fragment,verbatim,center]
- cis' d' e' cis' c'? d' e' c'!
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
@end lilypond
+@c . {Adjusting slurs}
+@unnumberedsubsubsec Adjusting slurs
-@cindex duration
-Durations are entered as their reciprocal values. For notes longer
-than a whole note, use identifiers.
+@node Slur attachments
+@subsubsection Slur attachments
-@quotation
+The ending of a slur should whenever possible be attached to a note
+head. Only in some instances where beams are involved, LilyPond may
+attach a slur to a stem end. In some cases, you may want to override
+LilyPond's decision, e.g., to attach the slur to the stem end. This can
+be done through @code{Voice.Slur}'s grob-property @code{attachment}:
-@example
-c'\longa c'\breve
-c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
-@end example
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Slur \set #'direction = #1
+ \property Voice.Stem \set #'length = #5.5
+ g''8(g)g4
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+ g8(g)g4
+@end lilypond
@end quotation
-@quotation
+Similarly, slurs can be attached to note heads even when beams are
+involved:
-@lilypond[]
-\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";
- } %}
- }
-}
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Slur \set #'direction = #1
+ \property Voice.Slur \set #'attachment = #'(head . head)
+ g''16()g()g()g()d'()d()d()d
@end lilypond
@end quotation
+If a slur would strike through a stem or beam, LilyPond will move the
+slur away vertically (upward or downward). In some cases, this may
+cause ugly slurs that you may want to correct:
+
@quotation
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Stem \set #'direction = #1
+ \property Voice.Slur \set #'direction = #1
+ d'32( d'4 )d8..
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+ d,32( d'4 )d8..
+@end lilypond
+@end quotation
-@example
-r\longa r\breve
-r1 r2 r4 r8 r16 r32 r64 r64
-@end example
+LilyPond will increase the curvature of a slur trying to stay free of
+note heads and stems. However, if the curvature would increase too much,
+the slur will be reverted to its default shape. This decision is based
+on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
+cases, you may find ugly slurs beautiful, and tell LilyPond so by
+increasing the @code{beautiful} value:
-@end quotation
+[hoe gedefd?? wat betekent beautiful = X?]
@quotation
-
-@lilypond[]
+@lilypond[verbatim]
\score {
- \notes \relative c'' {
- r\longa r\breve
- r1 r2 r4 r8 r16 r32 r64 r64
- }
+ \notes \context PianoStaff <
+ \time 6/4;
+ \context Staff=up { s1 * 6/4 }
+ \context Staff=down <
+ \clef bass;
+ \autochange Staff \context Voice
+ \notes \relative c {
+ d,8( a' d f a d f d a f d )a
+ }
+ >
+ >
\paper {
- loose_column_distance = 2.5 * \staffspace;
- linewidth = -1.0;
+ linewidth = -1.;
+ \translator {
+ \VoiceContext
+ Slur \override #'beautiful = #5.0
+ Slur \override #'direction = #1
+ Stem \override #'direction = #-1
+ autoBeamSettings \override #'(end * * * *)
+ = #(make-moment 1 2)
+ }
\translator {
- \StaffContext
- \remove "Clef_engraver";
- \remove "Staff_symbol_engraver";
- \remove "Bar_engraver";
+ \PianoStaffContext
+ VerticalAlignment \override #'threshold = #'(5 . 5)
}
}
}
@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.
-
-@lilypond[fragment,verbatim,center]
- a'4. b'4.
-@end lilypond
-
-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.
+@cindex Adusting slurs
-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.
-You can control the expansion by setting the property
-@code{Score.skipBars}. If this is set to true, Lily will not expand
-empty measures, and the multimeasure rests automatically adds the
-appropriate number.
-
-Note that there is currently no way to condense multiple rests into a
-single multimeasure rest.
+@c . {Phrasing slur}
+@node Phrasing slur
+@subsection Phrasing slur
+@cindex phrasing slur
+@cindex phrasing mark
+A phrasing slur (or phrasing mark) connects chords and is used to
+indicate a musical sentence. Phrasing slurs avoid crossing stems. A
+phrasing slur is started with @code{\(} and stopped with @code{\)}. The
+starting @code{\(} appears to the right of the first note in the
+phrasing slur. The terminal @code{\)} appears to the left of the last
+note in the phrasing slur.
+@lilypond[fragment,verbatim,center,relative]
+ \time 6/4; c''\((d)e f(e)\)d
+@end lilypond
-@cindex lyrics expressions
+[TODO: put together with breath mark.]
-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.
-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 . {Tie}
+@menu
+* Tie::
+* Tuplets::
+* Text spanner::
+* Ottava::
+* Span requests::
+@end menu
+@node Tie
+@subsubsection Tie
+@cindex Tie
+@cindex ties
+@cindex @code{~}
-@cindex properties
+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{~}'.
+If you try to tie together chords which have no common pitches, a
+warning message will appear and no ties will be created.
-@example
- \property@keyindex{property}
- @var{contextname}.@var{propname} = @var{value}
-@end example
+@lilypond[fragment,verbatim,center]
+ e' ~ e' <c' e' g'> ~ <c' e' g'>
+@end lilypond
-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.
+[sparseTies]
+@c . {Tuplets}
+@node Tuplets
+@subsubsection Tuplets
+@cindex Tuplets
+@cindex Times
-@cindex translator switches
+Tuplets are made out of a music expression by multiplying their duration
+with a fraction.
+@cindex @code{\times}
@example
- \translator@keyindex{translator}
- @var{contexttype} = @var{name}
+ \times @var{fraction} @var{musicexpr}
@end example
-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.
+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:
-Usually this is used to switch staffs in Piano music, e.g.
+@lilypond[fragment,verbatim,center]
+ g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@end lilypond
-@example
- \translator Staff = top @var{Music}
-@end example
+[todo: document tupletSpannerDuration]
-@cindex output properties
+@c . {Text spanner}
+@node Text spanner
+@subsubsection Text spanner
+@cindex Text spanner
-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:
+@c . {Ottava}
+@node Ottava
+@subsubsection Ottava
+@cindex Ottava
+@unnumberedsubsubsec Ottava
+[move to trick. Not a supported feature.]
-@lilypond[fragment,verbatim]
-\relative c'' { c4
- \context Staff \outputproperty
- #(make-type-checker 'Note_head)
- #'extra-offset = #'(5.0 . 7.5)
-<c8 e g> }
+@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
-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 implementation of the backend,
-which we change regularly and unscrupulously.
-@cindex commands
-
-Commands are music expressions that have no duration.
+@c . {Span requests}
+@node Span requests
+@subsubsection Span requests
+@cindex Span requests
+@cindex @code{\spanrequest}
@example
- @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
+ \spanrequest @var{startstop} @var{type}
@end example
+@cindex @code{\start}
+@cindex @code{\stop}
-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.
+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. Among the 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}.
-
-@example
- \mark@keyindex{mark} @var{unsigned};
- \mark @var{string};
-@end example
+You can attach a (general) span request to a note using the following
+syntax.
-Prints a mark over or under the staff. You must add
-@code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
-this to work.
+@lilypond[fragment,verbatim,center]
+ c'4-\spanrequest \start "slur"
+ c'4-\spanrequest \stop "slur"
+@end lilypond
-@node barlines
-@section barlines
+The slur syntax with parentheses is a shorthand for this.
-@example
- \bar@keyindex{bar} @var{bartype};
-@end example
+@c . {Ornaments}
+@node Ornaments
+@subsection Ornaments
+@cindex Ornaments
+@menu
+* Articulation::
+* Text scripts::
+@end menu
-This is a short-cut for doing
-@example
- \property Score.whichBar = @var{bartype}
-@end example
+@c . {Articulation}
+@node Articulation
+@subsubsection Articulation
+@cindex Articulation
-You are encouraged to use @code{\repeat} for repetitions. See
-@ref{Repeats}, and the documentation of @code{whichBar} in
-@ref{(lilypond-internals)LilyPond context properties}.
+@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
+forced to appear above or below the note by writing
+`@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
+respectively. Here is a chart showing symbols above notes, with the
+name of the corresponding symbol appearing underneath.
-@example
- \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
-@end example
+@lilypond[]
-A short-cut for doing
-@example
- \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
-@end example
+ \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''-\rtoe c''-\turn c''-\open c''-\flageolet
+ c''-\reverseturn c''-\trill c''-\prall c''-\mordent
+ c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
+ c''-\thumb c''-\segno c''-\coda
+ }
+ \context Lyrics \lyrics {
+ accent__ marcato__ staccatissimo__ fermata
+ stopped__ staccato__ tenuto__ upbow
+ downbow__ lheel__ rheel__ ltoe
+ rtoe__ turn__ open__ flageolet
+ reverseturn__ trill__ prall__ mordent
+ prallprall__ prallmordent__ uprall__ downprall
+ thumb__ segno__ coda
+ }
+ >
+ \paper {
+ linewidth = 5.875\in;
+ indent = 0.0;
+ }
+ }
-See the documentation of @code{timeSignatureFraction}
+@end lilypond
-@example
+@c . {Text scripts}
+@node Text scripts
+@subsubsection Text scripts
+@cindex Text scripts
+
+In addition, it is possible to place arbitrary strings of text or markup
+text (see @ref{Text markup}) above or below notes by using a string
+instead of an identifier: @code{c^"text"}. It is possible to use @TeX{}
+commands, but this should be avoided because this makes it impossible
+for LilyPond to compute the exact length of the string, which may lead
+to collisions. Also, @TeX{} commands won't work with direct postscript
+output. 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
- \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
-@end example
+To save typing, fingering instructions (digits 0 to 9 are
+supported) and single characters shorthands exist for a few
+common symbols
+
+@lilypond[]
+ \score {
+ \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
+ c''4-|_"c-|" s4
+ c''4->_"c->" s4
+ c''4-^_"c-\\^{ }" s4
+ c''4-1_"c-1" s4
+ c''4-2_"c-2" s4
+ c''4-3_"c-3" s4
+ c''4-4_"c-4" s4
+ }
+ \paper {
+ linewidth = 5.875 \in;
+ indent = 0.0;
+ }
+ }
-Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
-requests output with 76 quarter notes per minute.
+@end lilypond
-@example
- \partial@keyindex{partial} @var{duration} @code{;}
-@end example
-Short cut for
+@cindex @code{\textscript}
@example
- \property Score.measurePosition = @var{length of duration}
+
+ \textscript @var{text} @var{style}
@end example
-See the documentation of @code{measurePosition}.
+Defines a text to be printed over or under a note. @var{style} is a
+string that may be one of @code{roman}, @code{italic}, @code{typewriter},
+@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
-@cindex anacrusis
-
-@cindex upstep
-
-@example
-
- @code{|}@indexcode{|}
-@cindex bar check
+You can attach a general textscript request using this syntax:
-@end example
+@quotation
-@cindex shorten measures
+@example
+c4-\textscript "6" "finger"
+c4-\textscript "foo" "normal"
+@end example
-@cindex upstep
+@end quotation
-`@code{|}' is a bar check. Whenever a bar check is encountered during
-interpretation, a warning message is issued if it doesn't fall at a
-measure boundary. This can help you finding errors in the input.
-Depending on the value of @code{barCheckNoSynchronize}
-@indexcode{barCheckNoSynchronize} The beginning of the measure will be
-relocated, so this can also be used to shorten measures.
+This is equivalent to @code{c4-6 c4-"foo"}.
+@cindex @code{\script}
+@cindex scripts
+@cindex superscript
+@cindex subscript
@example
- \penalty@keyindex{penalty} @var{int} @code{;}
+ \script @var{alias}
@end example
-Discourage or encourage line breaks. See identifiers
-@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
-section [on identifiers] [FIXME].
-
-@example
- \clef@keyindex{clef} @var{clefname} @code{;}
-@end example
+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}.
+Usually the @code{\script} keyword is not used directly. Various
+helpful identifier definitions appear in @file{script.ly}.
-Short-cut for
+For information on how to add scripts, consult @file{scm/script.scm}.
-@example
- \property Clef.clefGlyph = @var{symbol associated with clefname}
- \property Clef.clefPosition = @var{clef Y-position for clefname}
- \property Clef.clefOctavation = @var{extra pitch of clefname}
-@end example
-Supported clef-names include
-[todo]
-@example
+@c . {Grace notes}
+@node Grace notes
+@subsection Grace notes
- \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}'.
-@node Manual beams
-@section Manual beams
-@cindex beams
-A beam is specified by surrounding the beamed notes with brackets
-`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
-@lilypond[fragment,verbatim,center]
- [a'8 a'] [a'16 a' a' a']
-@end lilypond
-Some more elaborate constructions:
+@cindex Grace music
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
+@cindex @code{graceAlignPosition}
-@lilypond[fragment,verbatim,center]
- [a'16 <a' c''> c'' <a' c''>]
- \times 2/3 { [e'8 f' g'] }
-@end lilypond
+@example
+ \grace @var{musicexpr}
+@end example
-Beaming can be generated automatically; see section @ref{Automatic Beaming}.
+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}
-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.
+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.
-@lilypond[fragment,verbatim,center]
- \repeat "tremolo" 8 { c16 d16 }
- \repeat "tremolo" 4 { c16 d16 }
-@end lilypond
+@quotation
+@lilypond[fragment,verbatim]
+\relative c'' {
+ \grace c8 c4 \grace { [c16 c16] } c4
+ \grace { \property Grace.flagStyle = "" c16 } c4
+}
-@lilypond[fragment,verbatim,center]
- c'4:32
@end lilypond
+@end quotation
-@cindex --@@@code{-}@code{-}
-
-@indexcode{__}
-
-@cindex extender
-
-@cindex hyphen
-
-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{-}'.
+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.
+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.
-@cindex ties
+The present implementation is not robust and generally kludgy. We expect
+it to change after LilyPond 1.4. Syntax changes might also be
+implemented.
-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{~}'.
-If you try to tie together chords which have no common pitches, a
-warning message will appear and no ties will be created.
-@lilypond[fragment,verbatim,center]
- e' ~ e' <c' e' g'> ~ <c' e' g'>
-@end lilypond
-@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
-forced to appear above or below the note by writing
-`@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
-respectively. Here is a chart showing symbols above notes, with the
-name of the corresponding symbol appearing underneath.
-@lilypond[]
- \score {
- < \notes {
- 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''-\rtoe c''-\turn c''-\open c''-\flageolet
- c''-\reverseturn c''-\trill c''-\prall c''-\mordent
- c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
- c''-\thumb c''-\segno c''-\coda
- }
- \context Lyrics \lyrics {
- accent__ marcato__ staccatissimo__ fermata
- stopped__ staccato__ tenuto__ upbow
- downbow__ lheel__ rheel__ ltoe
- rtoe__ turn__ open__ flageolet
- reverseturn__ trill__ prall__ mordent
- prallprall__ prallmordent__ uprall__ downprall
- thumb__ segno__ coda
- }
- >
- \paper {
- linewidth = 5.875\in;
- indent = 0.0;
- }
- }
+@menu
+* Glissando ::
+* Dynamics::
+* Crescendo and Decrescendo::
+* Bar lines::
+@end menu
-@end lilypond
-In addition, it is possible to place arbitrary strings of text or
-@TeX{} above or below notes by using a string instead of an
-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.
-To save typing, fingering instructions (digits 0 to 9 are
-supported) and single characters shorthands exist for a few
-common symbols
+@c . {Glissando}
+@node Glissando
+@subsubsection Glissando
+@cindex Glissando
-@lilypond[]
+@cindex @code{\glissando}
- \score {
- \notes {
- \property Voice.TextScript \set #'font-style = #'typewriter
- c''4-._"c-." s4
- c''4--_"c-{}-" s4
- c''4-+_"c-+" s4
- c''4-|_"c-|" s4
- c''4->_"c->" s4
- c''4-^_"c-\\^{ }" s4
- c''4-1_"c-1" s4
- c''4-2_"c-2" s4
- c''4-3_"c-3" s4
- c''4-4_"c-4" s4
- }
- \paper {
- linewidth = 5.875 \in;
- indent = 0.0;
- }
- }
+A glissando line can be requested by attaching a @code{\glissando} to a
+note:
+@quotation
+@lilypond[fragment,relative,verbatim]
+ c'' \glissando c'
@end lilypond
+@end quotation
-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}.
-
-
-@example
-
- \textscript@keyindex{textscript} @var{text} @var{style}
-@end example
-
-Defines a text to be printed over or under a note. @var{style} is a
-string that may be one of @code{roman}, @code{italic}, @code{typewriter},
-@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
-
-You can attach a general textscript request using this syntax:
+Printing of an additional text (such as @emph{gliss.}) must be done
+manually.
-@quotation
-@example
-c4-\textscript "6" "finger"
-c4-\textscript "foo" "normal"
-@end example
-@end quotation
+@c . {Dynamics}
+@node Dynamics
+@subsubsection Dynamics
+@cindex Dynamics
-This is equivalent to `@code{c4-6 c4-"foo"}'.
-@cindex scripts
-@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}
- \script@keyindex{script} @var{alias}
-@end example
-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
-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:
-@lilypond[fragment,verbatim,center]
- f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
-@end lilypond
+Dynamic marks are specified by using an identifier after a note:
+@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}.
+@c . {Crescendo and Decrescendo}
+@node Crescendo and Decrescendo
+@subsubsection Crescendo and Decrescendo
+@cindex Crescendo and Decrescendo
@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.
+@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
+You can also use a text saying @emph{cresc.} instead of hairpins. Here
+is an example how to do it:
-@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
-
-@lilypond[fragment,verbatim,center]
- c'4-\spanrequest \start "slur"
- c'4-\spanrequest \stop "slur"
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.crescendoText = "cresc."
+ \property Voice.crescendoSpanner = #'dashed-line
+ a''2\mf\< a a \!a
+ }
@end lilypond
-The slur syntax with parentheses is a shorthand for this.
-@node stem tremolo
-@section stem tremolo
-@cindex tremolo marks
+@c . {Bar lines}
+@node Bar lines
+@subsubsection Bar lines
+@cindex Bar lines
-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
-no last value.
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
-@lilypond[verbatim,fragment,center]
- c'2:8 c':32
-@end lilypond
+@example
+ \bar @var{bartype};
+@end example
+This is a short-cut for doing
+@example
+ \property Score.whichBar = @var{bartype}
+@end example
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeats}, and the documentation of @code{whichBar} in
+@ref{(lilypond-internals)LilyPond context properties}.
-@node Compound music expressions
-@section Compound music expressions
-@cindex compound music expressions
+[FIXME]
-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 {
- \cadenzaOn
- <a c'> <b d' > <c' e'>
- < { a b c' } { c' d' e' } >
- }
-@end lilypond
+@c . {Bar check}
+@node Bar check
+@subsection Bar check
+@cindex Bar check
-@cindex context selection
-@c @keyindex{context}
+@cindex bar check
+@cindex @code{barCheckNoSynchronize}
+@cindex @code{|}
-@example
- \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
-@end example
-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.
+Whenever a bar check is encountered during interpretation, a warning
+message is issued if it doesn't fall at a measure boundary. This can
+help you find errors in the input. Depending on the value of
+@code{barCheckNoSynchronize}, the beginning of the measure will be
+relocated, so this can also be used to shorten measures.
-@cindex input modes
+A bar check is entered using the bar symbol, @code{|}
-@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 @ref{Lexical modes} for more
-information on modes.
-@cindex sequential music
+@c . {Repeats}
+@node Repeats
+@section Repeats
-@example
- \sequential@keyindex{sequential}
- @code{@{} @var{musicexprlist} @code{@}}
-@end example
+@cindex repeats
+@cindex @code{\repeat}
-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:
+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.
-@example
+@table @asis
+@item unfolded
+Repeated music is fully written (played) out. Useful for MIDI
+output.
- @code{@{} @var{musicexprlist} @code{@}}
-@end example
+@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.
+@item tremolo
+Make tremolo beams.
+@end table
+@menu
+* Repeat syntax::
+* Manual repeat commands::
+* Tremolo repeats::
+* Tremolo subdivision::
+@end menu
-@cindex simultaneous music
+@node Repeat syntax
+@subsection Repeat syntax
-@indexcode{<}
-@indexcode{>}
+The syntax for repeats is
@example
-
- \simultaneous@keyindex{simultaneous}
- @code{@{} @var{musicexprlist} @code{@}}
+ \repeat @var{variant} @var{repeatcount} @var{repeatbody}
@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:
+If you have alternative endings, you may add
+@cindex @code{\alternative}
@example
-
- @code{<} @var{musicexprlist} @code{>}
+ \alternative @code{@{} @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @code{@}}
@end example
-If you try to use a chord as the first thing in your score, you might
-get multiple staffs instead of a chord.
+where each @var{alternative} is a Music expression.
-@lilypond[verbatim,center]
- \score {
- \notes <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
-@end lilypond
+Normal notation repeats are used like this:
-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:
+@quotation
-@lilypond[verbatim,center]
- \score {
- \notes\context Voice <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 { c'4 d' e' f' }
+ \repeat volta 2 { f' e' d' c' }
@end lilypond
+@end quotation
+With alternative endings:
+@quotation
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
+@end lilypond
+@end quotation
-@node relative
-@section relative
-@cindex relative pitch specification
+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 at some point in the future.}
-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.
+@quotation
-@example
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat fold 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
- \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
-@end example
+@end lilypond
+@end quotation
-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.
+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.
-@lilypond[fragment,verbatim,center]
+@quotation
+@lilypond[fragment,verbatim]
+\context Staff {
\relative c' {
- c d e f g a b c c,
+ \partial 4;
+ \repeat volta 3 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b2. } }
}
-@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
+@end quotation
-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.
-
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
- }
-@end lilypond
-
-The pitch after the @code{\relative} contains a notename. To parse
-the pitch as a notename, you have to be in note mode, so there must
-be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
-shown here).
-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}.
+As you can see, LilyPond doesn't remember the timing information, nor
+are slurs or ties repeated, so you have to reset timing information
+after a repeat, eg using bar-checks, @code{Score.measurePosition} or
+@code{\partial}. We hope to fix this after 1.4.
-It is strongly recommended to use relative pitch mode: less work,
-less error-prone, and more readable.
+It is possible to nest @code{\repeat}, although it probably is only
+meaningful for unfolded repeats.
+@node Manual repeat commands
+@subsection Manual repeat commands
+@cindex @code{repeatCommands}
-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}).
+The property @code{repeatCommands} can be used to control the layout of
+repeats. Its value is a Scheme list of repeat commands, where each repeat
+command can be
-@example
+@table @code
+@item 'start-repeat
+ Print a |: bar line
+@item 'stop-repeat
+ Print a :| bar line
+@item (volta . @var{text})
+ Print a volta bracket saying @var{text}.
+@item (volta . #f)
+ Stop a running volta bracket
+@end table
- @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
-@end example
+@lilypond[verbatim, fragment]
+ c''4
+ \property Score.repeatCommands = #'((volta "93") end-repeat)
+ c4 c4
+ \property Score.repeatCommands = #'((volta #f))
+ c4 c4
+@end lilypond
-@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{.}').
-@quotation
+@node Tremolo repeats
+@subsection Tremolo repeats
+@cindex tremolo beams
-@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
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
+@lilypond[verbatim,center]
+\score {
+ \context Voice \notes\relative c' {
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+ \repeat "tremolo" 2 { c16 d16 }
+ \repeat "tremolo" 4 c16
}
+ \paper {
+ linewidth = 40*\staffspace;
+ }
}
-
@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.
-
-@quotation
+@node Tremolo subdivision
+@subsection Tremolo subdivision
+@cindex tremolo marks
+@cindex @code{tremoloFlags}
-@lilypond[fragment,verbatim]
-\transpose c'' {
- \chords {
- c1:m c:min7 c:maj c:aug c:dim c:sus
- }
-}
+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} property if there was no last value.
+@lilypond[verbatim,fragment,center]
+ c'2:8 c':32
@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.
+Tremolos in this style do not carry over into the MIDI output.
-@lilypond[fragment,verbatim,center]
- \transpose c'' {
- \chords {
- c1^3 c:7^5.3 c:8^7
- }
- }
-@end lilypond
+Using this mechanism pays off when you entering many tremolos, since the
+default argument saves a lot of typing.
-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.
-@lilypond[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/e c/g c:7/e
- }
- }
-@end lilypond
-Bass notes can be added by `@code{/+}@indexcode{/+}' and
-the name of a single note to a chord. This has the effect of
-adding the specified note to the chord, lowered by an octave,
-so it becomes the lowest note in the chord.
-@lilypond[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/+c c/+g c:7/+b
- }
- }
+@c . {Piano music}
+@node Piano music
+@section Piano music
+@menu
+* Automatic staff changes::
+* Manual staff switches::
+* Pedals::
+* Arpeggio::
+* Follow Thread::
+@end menu
-@end lilypond
-Throughout these examples, chords have been shifted around the staff
-using @code{\transpose}.
+@c . {Automatic staff changes}
+@node Automatic staff changes
+@subsection Automatic staff changes
+@cindex Automatic staff changes
+
+Voices can be switched from top to bottom staff automatically. The
+syntax for this is
+@example
+ \autochange @var{contexttype} @var{musicexp}
+@end example
+This will switch notation context of @var{musicexp} between a
+@var{contexttype} named @code{up} and @code{down}. Typically, you use
+@code{Staff} for @var{contexttype}. The autochanger switches on basis
+of pitch (central C is the turning point), and it looks ahead skipping
+over rests to switch rests in advance.
+
+@lilypond[verbatim,singleline]
+\score { \notes \context PianoStaff <
+ \context Staff = "up" {
+ \autochange Staff \context Voice = VA < \relative c' { g4 a b c d r4 a g } >
+ }
+ \context Staff = "down" {
+ \clef bass;
+ s1*2
+ } > }
+@end lilypond
-You should not combine @code{\relative} with named chords.
-@cindex tuplets
+@node Manual staff switches
+@subsection Manual staff switches
-Tuplets are made out of a music expression by multiplying their
-duration with a fraction.
+@cindex manual staff switches
+@cindex staff switch, manual
+@cindex @code{\translator}
@example
+ \translator @var{contexttype} = @var{name}
+@end example
+
+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.
+
+Usually this is used to switch staffs in Piano music, e.g.
- \times@keyindex{times} @var{fraction} @var{musicexpr}
+@example
+ \translator Staff = top @var{Music}
@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:
-@lilypond[fragment,verbatim,center]
- g'4 \times 2/3 {c'4 c' c'} d'4 d'4
-@end lilypond
+@c . {Pedals}
+@node Pedals
+@subsection Pedals
+@cindex Pedals
+Piano pedals can be entered using the following span requests of the
+types @code{Sustain}, @code{UnaChorda} and @code{Sostenuto}:
+@lilypond[fragment,verbatim]
+c''4 \spanrequest \start "Sustain" c4 c4 \spanrequest \stop "Sustain"
+@end lilypond
+For these verbose expressions, standard shorthands have been defined:
+@table @code
+@item sustainDown
+@item sustainUp
+@item unaChorda
+@item treChorde
+@item sostenutoDown
+@item sostenutoUp
+@end table
-@cindex grace notes
+The symbols that are printed can be modified by setting pedalXStrings,
+where one of the pedal types. Refer to the generaetd documentation for
+more information.
-@example
+Currently, brackets are not supported, only text markings (ie. Ped*
+style).
- \grace@keyindex{grace} @var{musicexpr}
-@end example
-A grace note expression has duration 0; the next real note is
-assumed to be the main note.
+@c . {Arpeggio}
+@node Arpeggio
+@subsection Arpeggio
+@cindex Arpeggio
+@cindex broken arpeggio
+@cindex @code{\arpeggio}
-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}.
+You can specify an arpeggio sign on a chord by attaching an
+@code{\arpeggio} to a note of the chord.
-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}@indexcode{flagStyle} property.
@quotation
+@lilypond[fragment,relative,verbatim]
+ \context Voice <c'\arpeggio e g c>
+@end lilypond
+@end quotation
-@lilypond[fragment,verbatim]
-\relative c'' {
- \grace c8 c4 \grace { [c16 c16] } c4
- \grace { \property Grace.flagStyle = "" c16 } c4
-}
+When an arpeggio crosses staffs in piano music, you attach an arpeggio
+to the chords in both staffs, and set
+@code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
+in both staffs.
+@quotation
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.connectArpeggios = ##t
+ \context Voice = one { <c''\arpeggio e g c> }
+ \context Voice = other { \clef bass; <c,,\arpeggio e g>}
+ >
@end lilypond
@end quotation
-At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
-@example
- @code{\grace @{ \grace c32 c16 @} c4}
-@end example
+@c . {Follow Thread}
+@node Follow Thread
+@subsection Follow Thread
+@cindex follow thread
+@cindex staff switching
+@cindex cross staff
-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.
+[todo: different name, eg. voice line ? ]
-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.
+@cindex @code{followThread}
+Whenever a voice switches to another staff a line connecting the notes
+can be printed automatically. 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
-@node Repeats
-@section Repeats
-@cindex repeats
+@c . {Lyrics}
+@node Lyrics
+@section Lyrics
-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 @samp
- @item unfolded
- Repeated music is fully written (played) out. Useful for MIDI
- output.
+@menu
+* Lyrics mode::
+* Printing lyrics::
+* Automatic syllable durations::
+* More stanzas::
+@end menu
- @item volta
- This is the normal notation: Repeats are not written out, but
- alternative endings (voltas) are printed, left to right.
+@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{}.
- @item folded
- Alternative endings are written stacked, which is useful for
- lyrics.
-@end table
+@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
-The syntax for repeats is
+Since combinations of numbers and dots are used for indicating
+durations, you can not enter real numbers in this mode.
-@example
+@cindex lyrics expressions
- \repeat @var{variant} @var{repeatcount} @var{repeatbody}
-@end example
+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.
-If you have alternative endings, you may add
+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 the next section.
-@example
- \alternative@keyindex{alternative}
- @code{@{} @var{alternative1}
- @var{alternative2}
- @var{alternative3} @dots{} @code{@}}
-@end example
+@c . {Printing lyrics}
+@node Printing lyrics
+@subsection Printing lyrics
+@cindex lyrics
-where each @var{alternative} is a Music expression.
-Normal notation repeats are used like this:
+Lyric syllables must be interpreted within a @code{Lyrics} context for
+printing them. Here is a full example:
@quotation
-
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 { c'4 d' e' f' }
- \repeat volta 2 { f' e' d' c' }
+@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 lilypond
@end quotation
-With alternative endings:
-@quotation
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
-@end lilypond
-@end quotation
+@cindex extender
+@cindex lyric extender
-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.}
+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
-@lilypond[fragment,verbatim]
- c'1
- \repeat fold 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
-
-@end lilypond
-@end quotation
-
-@quotation
-
-@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 } }
- }
-}
-
-@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
-
-@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 } }
- }
+@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 lilypond
@end quotation
-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 transpose
-@section transpose
-@cindex transposition of pitches
-
-A music expression can be transposed with
-@code{\transpose}@keyindex{transpose}. The syntax is
-
-@example
-
- \transpose @var{pitch} @var{musicexpr}
-@end example
-
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
+@cindex Lyric hyphen
-@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.
+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
-@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 }
+@lilypond[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 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}.
+@c . {Automatic syllable durations}
+@node Automatic syllable durations
+@subsection Automatic syllable durations
+@cindex Automatic syllable durations
@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}.
-@keyindex{addlyrics} The syntax for this is
-
+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
-
\addlyrics @var{musicexpr1 musicexpr2}
@end example
interpreted, but that every non-command atomic music expression
(``every syllable'') in @var{musicexpr2} is interpreted using timing
of @var{musicexpr1}.
+@cindex @code{automaticMelismata}
-If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
+If the property @code{automaticMelismata} is set in the
context of @var{musicexpr1}, no lyrics will be put on slurred or tied
notes.
@quotation
-
@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
}
\context Lyrics \lyrics {
do4 re mi fa }
-
@end lilypond
@end quotation
undesired effects when using multiple stanzas:
@quotation
-
@lilypond[verbatim,fragment]
\addlyrics
\transpose c'' {
It is valid (but probably not very useful) to use notes instead of
lyrics for @var{musicexpr2}.
+@node More stanzas
+@subsection More stanzas
+@cindex phrasing
+If you have multiple stanzas printed underneath each other, the separate
+syllables should be aligned around punctuation. LilyPond can do this if
+you explain it which lyric lines belong to which melody.
-@node Ambiguities
-@section Ambiguities
+To this end, give the Voice context an identity, and set the LyricsVoice
+to name starting with that identity. In the following example, the Voice
+identity is @code{duet}, and the identities of the LyricsVoices are
+@code{duet-1} and @code{duet-2}.
-@cindex ambiguities
-The grammar contains a number of ambiguities.@footnote{The authors
-hope to resolve them at a later time.}
+@lilypond[singleline,verbatim]
+\score {
+\addlyrics
+ \notes \relative c'' \context Voice = duet { \time 3/4; g2 e4 a2 f4 g2. }
+ \lyrics \context Lyrics <
+ \context LyricsVoice = "duet-1" {
+ \property LyricsVoice . stanza = "Bert"
+ Hi, my name is bert. }
+ \context LyricsVoice = "duet-2" {
+ \property LyricsVoice . stanza = "Ernie"
+ Ooooo, ch\'e -- ri, je t'aime. }
+ >
+}
+@end lilypond
-@itemize @bullet
- @item The assignment
+You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
+first system) and @code{LyricsVoice.stz} for the following systems.
- @example
-foo = bar
-@end example
+@cindex stanza numbering
- can be interpreted as making a string identifier @code{\foo}
- containing @code{"bar"}, or a music identifier @code{\foo}
- containing the syllable `bar'.
- @item The assignment
+@c . {Chords}
+@node Chords
+@section Chords
+@cindex Chords
- @example
-foo = -6
-@end example
+[chords vs. simultaneous music]
- can be interpreted as making an integer identifier
- containing -6, or a Request identifier containing the
- fingering `6' (with neutral direction).
+@menu
+* Chords mode::
+* Entering named chords::
+* Printing named chords::
+@end menu
- @item If you do a nested repeat like
+@c . {Chords mode}
+@node Chords mode
+@subsection Chords mode
+@cindex Chords mode
- @quotation
+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
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end 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.
- @end quotation
+@c . {Entering named chords}
+@node Entering named chords
+@subsection Entering named chords
+@cindex Chords names
- 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.
+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}).
- @item (an as yet unidentified ambiguity :-)
-@end itemize
+@example
+ @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{.}).
-@node Notation conversion specifics
-@section Notation conversion specifics
+Throughout these examples, chords have been shifted around the staff
+using @code{\transpose}.
-@node Automatic Beaming
-@section Automatic Beaming
-@cindex automatic beam generation
-@cindex autobeam
-@c beamAuto vs autoBeam ?
+@quotation
+
+@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
+ }
+}
-By default, LilyPond will generate beams automatically. This feature
-can be disabled by setting the
-@code{Voice.beamAuto}@indexcode{Voice.beamAuto} property to false.
-It can be overridden for specific cases by specifying explicit beams.
+@end lilypond
+@end quotation
+@cindex @code{aug}
+@cindex @code{dim}
+@cindex @code{maj}
+@cindex @code{sus}
+
+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.
-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}@indexcode{Voice.autoBeamSettings}.
-To end beams every quarter note, for example, you could set the property
-@code{(end * * * *)} @indexcode{(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 * * * *)}@indexcode{(begin * * * *)}, eg:
@quotation
-@example
-\property Voice.autoBeamSettings \override
- #'(end * * * *) = #(make-moment 1 4)
-\property Voice.autoBeamSettings \override
- #'(begin * * * *) = #(make-moment 1 8)
-@end example
+
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1:m c:min7 c:maj c:aug c:dim c:sus
+ }
+}
+
+@end lilypond
@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 * *)}.
+Chord subtractions are used to eliminate notes from a chord. The
+notes to be subtracted are listed after a @code{^} character,
+separated by dots.
-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.
+@lilypond[fragment,verbatim,center]
+ \transpose c'' {
+ \chords {
+ c1^3 c:7^5.3 c:8^7
+ }
+ }
+@end lilypond
+@cindex @code{/}
-For example, to specify beam endings for beams that contain 32nd notes,
-you would use @code{(end * * 1 32)}.
+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.
+
+@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.
+
+@lilypond[fragment,verbatim,center]
+ \transpose c''' {
+ \chords {
+ c1 c/+c c/+g c:7/+b
+ }
+ }
+
+@end lilypond
+
+The most interesting application is printing chord names, which is
+explained in the next subsection.
+
+You should not combine @code{\relative} with named chords. [FIXME]
+
+@c . {Printing named chords}
+@node Printing named chords
+@subsection Printing named chords
-@node Chord Names
-@section Chord Names
+
+
+
+@cindex printing chord names
@cindex chord names
@cindex chords
+@cindex @code{ChordNames}
+@cindex @code{ChordNameVoice}
-@cindex printing!chord names
-
-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.
+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.
@quotation
-@lilypond[verbatim]
+@lilypond[verbatim,singleline]
scheme = \notes {
\chords {a1 b c} <d f g> <e g b>
}
\context ChordNamesVoice \scheme
\context Staff \transpose c'' \scheme
>
- \paper { linewidth = -1.; }
}
@end lilypond
@end quotation
-
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:
+@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
chord names when chords are entered as a list of pitches:
@quotation
-@lilypond[verbatim,center]
+@lilypond[verbatim,center,singleline]
scheme = \notes {
<c'1 e' g'>
<e' g' c''>
\context ChordNamesVoice \scheme
\context Staff \scheme
>
- \paper { linewidth = -1.; }
}
@end lilypond
@end quotation
added bass note, append @code{/+<notename}:
@quotation
-@lilypond[verbatim,center]
+@lilypond[verbatim,center,singleline]
scheme = \chords {
d1 d/a d/+gis
}
\context ChordNames \scheme
\context Staff \transpose c'' \scheme
>
- \paper { linewidth = -1.; }
}
@end lilypond
@end quotation
-The chord names that LilyPond should print are fully customisable. The
-default code 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 poperty
-@code{ChordName.style} to @code{american}:
+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]
@end lilypond
@end quotation
+@node Writing parts
+@section Writing parts
-@node lyricprint
-@section lyricprint
-@cindex lyrics
+@c . {Transpose}
+@menu
+* Rehearsal marks::
+* Instrument names::
+* Transpose::
+* Sound output for transposing instruments::
+* Multi measure rests::
+* Automatic part combining::
+@end menu
-@cindex printing!lyrics
+@c . {Rehearsal marks}
+@node Rehearsal marks
+@subsection Rehearsal marks
+@cindex Rehearsal marks
+@cindex mark
+@cindex @code{\mark}
+@cindex @code{Mark_engraver}
+@example
+ \mark @var{unsigned};
+ \mark @var{string};
+ \mark ;
+@end example
-Lyric syllables must be interpreted within a @code{Lyrics} context
+With this command, you can print a rehearsal mark above the system. You
+can provide a number, a string or a markup text as argument. If there is
+no argument, the property @code{rehearsalMark} is used and automatically
+incremented.
-@cindex context!Lyrics
- for printing them.
+@lilypond[fragment,verbatim]
+\relative c'' {
+ c1 \mark "A2";
+ c1 \mark ;
+ c1 \mark ;
+ c1 \mark "12";
+ c1 \mark #'(music "scripts-segno") ;
+ c1
+}
+@end lilypond
-Here is a full example:
+@node Instrument names
+@subsection Instrument names
-@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
- }
- >
+You can specify an instrument name for a staff by setting
+@code{Staff.instrument} and @code{Staff.instr}. This will print a string
+before the start of the staff. For the first start, @code{instrument} is
+used, for the next ones @code{instr} is used.
+
+@lilypond[verbatim,singleline]
+\score { \notes {
+ \property Staff.instrument = "instr " { c''4 } }
+ \paper {
+ \translator { \StaffContext
+ \consists "Instrument_name_engraver"; } } }
+@end lilypond
+
+This requires that you add the @code{Instrument_name_engraver} to the
+staff context.
+
+
+@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
+ \transpose @var{pitch} @var{musicexpr}
+@end example
+
+This means that middle C in @var{musicexpr} is transposed to
+@var{pitch}.
+
+@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.
+
+@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
-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{_}').
+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}.
-@quotation
+@node Sound output for transposing instruments
+@subsection Sound output transposing instruments
+
+When you want to play a score containing transposed and untransposed
+instruments, you have to instruct LilyPond the pitch offset (in
+semitones) for the transposed instruments. This is done using
+@code{transposing}.
+
+@cindex @code{transposing}
+
+@example
+ \property Staff.instrument = #"Cl. in B-flat"
+ \property Staff.transposing = #-2
+@end example
+
+
+@c . {Multi measure rests}
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex Multi measure rests
+
+@cindex @code{R}
+
+Multi measure rests 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 appropriate number is added
+automatically.
+@lilypond[fragment,verbatim]
+ \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
+@end lilypond
+
+Currently, there is no way to condense multiple rests into a single
+multimeasure rest.
+
+@cindex condensing rests
+
+@node Automatic part combining
+@subsection Automatic part combining
+
+[TODO]
+
+
+@c . {Custodes}
+@node Custodes
+@section Custodes
+@cindex Custos
+@cindex Custodes
+
+A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a
+staff context symbol that appears at the end of a staff line. It
+anticipates the pitch of the first note(s) of the following line and
+thus helps the player or singer to manage line breaks during
+performance, thus enhancing readability of a score.
+
+@quotation
@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 __
+ \notes { c'1 d' e' d' \break c' d' e' d' }
+ \paper {
+ \translator {
+ \StaffContext
+ \consists Custos_engraver;
+ Custos \override #'style = #'mensural;
}
- >
+ }
}
-
@end lilypond
@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:
+Custodes were frequently used in music notation until the 16th century.
+There were different appearences for different notation styles.
+Nowadays, they have survived only in special forms of musical notation
+such as via the editio vaticana dating back to the beginning of the 20th
+century.
+
+For typesetting custodes, just put a @code{Custos_engraver} into the
+@code{StaffContext} when declaring the @code{\paper} block. In this
+block, you can also globally control the appearance of the custos symbol
+by setting the custos @code{style} property. Currently supported styles
+are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
+@code{mensural}.
@quotation
+\paper @{
+ \translator @{
+ \StaffContext
+ \consists Custos_engraver;
+ Custos \override #'style = #'mensural;
+ @}
+@}
+@end 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 {
- Va4 -- der Ja -- cob | Va -- der Ja -- cob |
- Slaapt gij nog?2 | Slaapt4 gij nog?2
- }
- >
-}
+The property can also be set locally, for example in a @code{\notes}
+block:
-@end lilypond
+@quotation
+\notes @{
+ \property Staff.Custos \override #'style = #'vaticana
+ c'1 d' e' d' \break c' d' e' d'
+@}
@end quotation
+@c . {Tuning output}
+@node Tuning output
+@section Tuning output
+LilyPond tries to take as much formatting as possible out of your
+hands. Nevertheless, there are situations where it needs some help, or
+where you want to override its decisions.
-@node Notation Contexts
-@section Notation Contexts
+Here we discuss how you can do that.
-@cindex notation contexts
+Notational output is specified in so called grobs (graphic
+objects). Each grob carries with it a set of properties (grob
+properties) specific to that grob. For example, a stem grob has grob
+properties that specify its direction, length and thickness.
-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.
+The most common way of tuning the output is to alter the values of these
+properties. There are two ways of doing that: first, you can
+specifically select a set of grobs at one point, and set properties as
+you wish, or secondly, you can (temporarily) modify the definition of a
+grob, thereby affecting an entire group of grobs.
-A context is an object that holds the reading state of the
-expression; it contains information like
+@menu
+* Tuning groups of grobs ::
+* Tuning per grob ::
+* What to tune?::
+* Text markup::
+@end menu
-@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
+@node Tuning groups of grobs
+@subsection Tuning groups of grobs
-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).
+@cindex grob description
-Contexts associated with sheet music output are called @emph{notation
-contexts}, those for sound output are called playing contexts.
+A grob definition is an association list, that is stored in a context
+property. By assigning to that property (using plain @code{\property}),
+you can change the resulting grobs.
+@lilypond[verbatim, fragment]
+c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
+@end lilypond
+The @code{\property} statement effectively empties the definition of the
+Stem object. One of the effects is that property specifying how it
+should be printed is erased, with the effect of rendering it invisible.
-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:
+@cindex \override
+@cindex \revert
+@cindex \set
-@example
- @example
-\score @{ \notes < c4 > @}
-@end example
+This mechanism is fairly crude, since you can only set, but not modify,
+the definition of a grob. For this reason, there is a more advanced
+mechanism: you can add a property on top of an existing definition, or
+remove a property: @code{\override} adds a settings, @code{\revert}
+removes that setting.
+@lilypond[verbatim]
+c'4 \property Voice.Stem \override #'thickness = #4.0
+c'4 \property Voice.Stem \revert #'thickness
+c'4
+@end lilypond
+
+For the digirati, the grob description is an Scheme association
+list. Since it is singly linked, we can treat it as a stack, and
+@code{\override} and @code{\revert} are just push and pop
+operations. This pushing and popping is also used in the
+@code{autoBeamSettings} property.
+If you revert a setting which was not set in the first place, then it
+has no effect. However, if the setting was set as a system default, it
+may remove the default value, and this may give surprising results,
+including crashes. In other words, if you use @code{\override} and
+@code{\revert}, be sure to balance the overrides and reverts.
+
+If balancing them is too much work, use the following shorthand:
+@code{\set} performs a revert followed by an override:
+@example
+\property Voice.Stem \set #'thickness = #2.0
@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.
+Formally the syntax for these constructions is
+@example
+\property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
+\property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
+\property @var{context}.@var{grobname} \revert @var{symbol}
+@end example
+Here @var{symbol} is a Scheme expression of symbol type, @var{context}
+and @var{grobname} are strings and @var{value} is a Scheme expression.
+LilyPond will hang or crash if @var{value} contains cyclic references.
-@cindex context
-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.
-If a context of the specified type and name can not be found, a new
-one is created. For example,
+@node Tuning per grob
+@subsection Tuning per grob
-@quotation
+@cindex \outputproperty
-@lilypond[verbatim]
-\score {
- \notes \relative c'' {
- c4 <d4 \context Staff = "another" e4> f
+A second way of tuning grobs is the more arcane @code{\outputproperty}
+feature.
+Syntax is as follows
+@example
+\outputproperty @var{predicate} @var{symbol} = @var{value}
+@end example
+Here @code{predicate} is a Scheme functoin taking a grob a argument
+argument, and returning a boolean. This statement is processed by the
+@code{Output_property_engraver}. It instructs the engraver to feed all
+grobs that it sees to @var{predicate}. Whenever the predicate returns
+true, the grob property @var{symbol} will be set to @var{value}.
+
+You will need to combine this statement with @code{\context} to select
+the appropriate context to apply this to.
+
+If possible, avoid this feature: the semantics are not very clean, and
+the syntax and semantics are up for rewrite.
+
+Here are some random examples:
+
+@lilypond[fragment,verbatim,singleline]
+\relative c'' { c4
+ \context Staff \outputproperty
+ #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(0.5 . 0.75)
+ <c8 e g> }
+@end lilypond
+
+@cindex @code{extra-offset}
+
+This selects all note heads occurring at current staff level, and sets
+the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting
+them up and right.
+
+Move the text "m.d.", but not the fingering instruction "2".
+@lilypond[verbatim,singleline]
+#(define (make-text-checker text)
+ (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
+
+\score {
+ \notes\relative c''' {
+ \property Voice.Stem \set #'direction = #1
+ \outputproperty #(make-text-checker "m.d.")
+ #'extra-offset = #'(-3.5 . -4.5)
+ a^2^"m.d."
}
}
-
@end lilypond
-@end quotation
-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
+@node What to tune?
+@subsection What to tune?
-When the interpretation of this music expression starts, the context
-for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
-expression.
+This all tells you how to tune grobs, but what variables are there? The
+question is not answered in this manual (although you may encounter
+some examples.).
-Lastly, you may wonder, why this:
+Grob properties are tied directly to the implementation of LilyPond, and
+they are thus a moving target. Refer to the automatically generated
+documentation of the internals (available from the website).
-@quotation
+You need the following information
-@example
-\score @{
- \notes \relative c'' @{
- c4 d4 e4
- @}
-@}
-@end example
+@itemize @bullet
+@item
+which grob to modify
+@item
+which property to modify
+@item
+which context the grob comes from.
+@end itemize
-@end quotation
+Included with the automatically generated documentation is a master list
+of grobs. Each one can be clicked, taking you to a overview of the
+available properties.
-doesn't result in this:
+There is also a master list of contexts. Clicking each takes you to an
+overview of the context, listing which grob types are created there.
-@lilypond[]
- \score {
- \notes \relative c'' {
- <c4> <d4> <e4>
- }
- }
-@end lilypond
+@node Text markup
+@subsection Text markup
+@cindex text markup
+@cindex markup text
-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}.
+LilyPond has an internal mechanism to typeset texts. You can
+form text markup expressions by composing scheme expressions
+in the following way.
-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.
+@lilypond[verbatim]
+\score { \notes \relative c' {
+ b-#"text"
+ c-#'(bold "text")
+ d-#'(lines "one" (bold "text"))
+ e-#'(music (named "noteheads-2" "flags-u3"))
+}
+\paper { linewidth = 10.\cm; } }
+@end lilypond
-Properties can be preset within the @code{\translator} block
-corresponding to the appropriate context. In this case, the syntax
-is
+Normally, the Scheme markup text is stored in the @code{text} property
+of a grob. Formally, it is defined as follows:
@example
- @var{propname} @code{=} @var{value}
+text: string | (head? text+)
+head: markup | (markup+)
+markup-item: property | abbrev | @var{fontstyle}
+property: (@var{key} . @var{value})
+abbrev: @code{rows lines roman music bold italic named super sub text}
@end example
-This assignment happens before interpretation starts, so a
-@code{\property} expression will override any predefined settings.
-
-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 markup is broken down and converted into a list of grob properties,
+which are prepended to the grop's property list. The
+@var{key}-@var{value} pair is a grob property.
+
+The following abbreviations are currently
+defined:
+
+@table @code
+@item rows
+horizontal mode: set all text on one line (default)
+@item lines
+ vertical mode: set every text on new line
+@item roman
+ select roman font
+@item music
+ select feta font
+@item bold
+ select bold series
+@item italic
+ select italic shape
+@item named
+ lookup by character name
+@item text
+ plain text lookup (by character value)
+@item super
+ superscript
+@item sub
+ subscript
+@end table
+@var{fontstyle} may be any of @code{finger volta timesig mmrest mark
+script large Large dynamic}
-@mbinclude properties.itely
+@c . {Page layout}
@node Page layout
@section Page layout
+@cindex Page layout
+
+@menu
+* Paper block::
+* Paper variables::
+* Font Size::
+* Paper size::
+* Line break::
+* Page break::
+@end menu
+@c . {Paper block}
+@node Paper block
@subsection Paper block
+@cindex Paper block
The most important output definition is the @code{\paper} block, for
music notation. The syntax is
@item An assignment. The assignment must be terminated by a
semicolon.
- @item A context definition. See section @ref{contextdefs} for
+ @item A context definition. See Section @ref{Notation contexts} for
more information on context definitions.
-@ignore
-
- FIXME
-
-
- @item
-
- A margin shape declaration. The syntax is
-
- @example
-
- \shape @var{indent1}@code{,} @var{width1}@code{,}
- @var{indent2}@code{,} @var{width2} @dots{} @code{;}
- @end example
-
- @keyindex{shape}
-
- 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 \stylesheet declaration. Its syntax is
@example
- \stylesheet @var{alist}
+ \stylesheet @var{alist}
@end example
- See @file{font.scm} for details of @var{alist}.
+ 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:
-@table @samp
- @item @code{indent}@indexcode{indent}
+@table @code
+@cindex @code{indent}
+ @item @code{indent}
The indentation of the first line of music.
+@cindex @code{staffspace}
- @item @code{staffspace}@indexcode{staffspace}
+ @item @code{staffspace}
The distance between two staff lines, calculated from the center
- of the lines. You should use either this or @code{rulethickness}
+ of the lines. You should use either this or @code{stafflinethickness}
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. If you use this variable, you
- probably want to define it in staff spaces, ie
- @example
- linewidth = 30 * \staffspace;
- @end example
-
- @item @code{textheight}@indexcode{textheight}
+@cindex @code{linewidth}
+ @item @code{linewidth}
+ Sets the width of the lines.
+
+If set to a negative value, a single
+ unjustified line is produced.
+
+@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}@indexcode{interscoreline}
+ @item @code{interscoreline}
Sets the spacing between the score lines. Defaults to 16 pt.
+@cindex @code{interscorelinefill}
- @item @code{interscorelinefill}@indexcode{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}@indexcode{stafflinethickness}
+ @item @code{stafflinethickness}
Determines the thickness of staff lines, and also acts as a scaling
parameter for other line thicknesses.
@end table
-@subsection Line breaks
-
-@cindex line breaks
-@cindex breaking lines
-
-Line breaks are normally computed automatically. They are chosen such
-that the resulting spacing has low variation, and looks neither cramped
-nor loose.
-
-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 "";}.
-
-@subsection Page breaks
-
-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}
-
-
-@cindex page breaks
-@cindex breaking pages
-
+@c . {Font size}
+@node Font Size
@subsection Font size
-
@cindex font size
-@cindex paper size
The Feta font provides musical symbols at six different sizes. These
fonts are 11 point, 13 point, 16 point, 20 point,
The font definitions are generated using a Scheme function. For more
details, see the file @file{font.scm}.
-@subsection paper size
+
+
+@c . {Paper size}
+@node Paper size
+@subsection Paper size
+@cindex Paper size
@cindex paper size
@cindex page size
+@cindex @code{papersize}
To change the paper size, you must first set the
-@code{papersize}@indexcode{papersize} variable at top level. Set it to
+@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
will set the paper variables @code{hsize} and @code{vsize} (used by
@code{ly2dvi})
-@node contextdefs
-@section contextdefs
-
-@cindex context definition
-@cindex translator definition
-@cindex engraver hacking
-A notation contexts is defined by the following information
-@enumerate i
- @item A name.
- @item The LilyPond modules that do the actual conversion of music to
- notation. Each module is a so-called
- @emph{engraver}
-@cindex engraver
-.
- @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,
+@c . {Line break}
+@node Line break
+@subsection Line break
- @item What properties are defined.
-@end enumerate
+@cindex line breaks
+@cindex breaking lines
-A context definition has this syntax:
+Line breaks are normally computed automatically. They are chosen such
+that the resulting spacing has low variation, and looks neither cramped
+nor loose.
-@example
+Occasionally you might want to override the automatic breaks; you can do
+this by specifying @code{\break}. 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 "";}.
- \translator @code{@{}
- @var{translatorinit} @var{translatormodifierlist}
- @code{@}}
-@end example
+Similarly, @code{\noBreak} forbids a line break at a certain point.
-@var{translatorinit} can be an identifier or of the form
+@cindex @code{\penalty}
+The @code{\break} and @code{\noBreak} commands are defined in terms of
+the penalty command:
@example
-
- \type @var{typename} @code{;}
+ \penalty @var{int} @code{;}
@end example
-@var{typename} is one of
+This imposes encourages or discourages LilyPond to make a line break
+at this point.
-@table @samp
- @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
- The standard cooperation engraver.
+@strong{Warning} do not use @code{\penalty} directly. It is rather
+kludgy, and slated for rewriting.
- @item @code{Score_engraver}@indexcode{Score_engraver}
- This is cooperation module that should be in the top level context.
+@c . {Page break}
+@node Page break
+@subsection Page break
- @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
+@cindex page breaks
+@cindex breaking pages
-@var{translatormodifierlist} is a list of items where each item is
-one of
-@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.
-
- @item @code{\consistsend} @var{engravername} @code{;}
- Analogous to @code{\consists}, but makes sure that
- @var{engravername} is always added to the end of the list of
- engravers.
-
- Some engraver types need to be at the end of the list; this
- insures they are put there, and stay there, if a user adds or
- removes engravers. This command is usually not needed for
- end-users.
-
- @item @code{\accepts} @var{contextname} @code{;}
- Add @var{contextname} to the list of context this context can
- contain. The first listed context is the context to create by
- default.
-
- @item @code{\denies}. The opposite of @code{\accepts}. Added for
-completeness, but is never used in practice.
-
-
- @item @code{\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.
-
- @item @var{propname} @code{=} @var{value} @code{;}
- A property assignment. It is allowed to use reals for
- @var{value}.
-@end itemize
-
-In the @code{\paper} block, it is also possible to define translator
-identifiers. Like other block identifiers, the identifier can only
-be used as the very first item of a translator. In order to define
-such an identifier outside of @code{\score}, you must do
-
-@quotation
-
-@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
-
-@end quotation
-
-
-@cindex paper types, engravers, and pre-defined translators
-
-Some pre-defined identifiers can simplify modification of
-translators. The pre-defined identifiers are:
-
-@table @samp
- @item @code{StaffContext}@indexcode{StaffContext}
- Default Staff context.
-
- @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
- Default RhythmicStaff context.
+Page breaks are normally computed by @TeX{}, so they are not under direct
+control. However, you can insert a commands into the @file{.tex} output to
+instruct @TeX{} where to break pages. For more details, see the
+example file @file{input/test/between-systems.ly}
- @item @code{VoiceContext}@indexcode{VoiceContext}
- Default Voice context.
+[or -> Tricks? ]
- @item @code{ScoreContext}@indexcode{ScoreContext}
- Default Score context.
- @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.}
- @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
- @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
-@end table
+@c . {Sound}
+@node Sound
+@section Sound
+@cindex Sound
-Using these pre-defined values, you can remove or add items to the
-translator:
+LilyPond allows MIDI output, with the purpose of proof-hearing the music
+you enter. The performance lacks lots of interesting effects, such as
+swing, articulation, slurring, tieing, etc.
-@quotation
+Also note that it is not possible to use the percussion channel
+(generally channel 10 of a MIDI file).
-@example
-\paper @{
- \translator @{
- \StaffContext
- \remove Some_engraver;
- \consists Different_engraver;
- @}
-@}
-@end example
+@menu
+* MIDI block::
+* MIDI instrument names::
+* Tempo::
+@end menu
-@end quotation
+@c . {MIDI block}
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
-
-@node Sound output
-@section Sound output
The MIDI block is analogous to the paper block, but it is somewhat
simpler. The @code{\midi} block can contain:
The contexts for MIDI output are defined in @file{ly/performer.ly}.
+@c . {MIDI instrument names}
+@node MIDI instrument names
+@subsection MIDI instrument names
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+@cindex @code{Staff.instrument}
-@cindex MIDI instrument names
+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.
-@node midilist
-@section midilist
+[FIXME: to appendix ]
-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 @quotation
@example
"acoustic grand" "contrabass" "lead 7 (fifths)"
"cello" "lead 6 (voice)"
@end example
-@c @end quotation
-@node Pre-defined Identifiers
-@section Pre-defined Identifiers
-@cindex pre-defined identifiers
+@c . {Tempo}
+@node Tempo
+@subsection Tempo
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
+@cindex @code{\tempo}
+@example
+ \tempo @var{duration} = @var{perminute} @code{;}
+@end example
-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}.
+Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
+output with 76 quarter notes per minute.
-@table @samp
- @item @code{\break}@keyindex{break}
- Force a line break in music by using a large argument for the
- keyword @code{\penalty}.
- @item @code{\nobreak}@keyindex{nobreak}
- Prevent a line break in music by using a large negative argument
- for the keyword @code{\penalty}.
- @item @code{\shiftOff}@keyindex{shiftOff}
- Disable horizontal shifting of note heads that collide.
- @item @code{\shiftOn}@keyindex{shiftOn}
- Enable note heads that collide with other note heads to be
- shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
-set different shift values.
- @item @code{\stemBoth}@keyindex{stemBoth}
- Allow stems, beams, and slurs to point either upwards or
- downwards, decided automatically by LilyPond.
+@c . {Music entry}
+@node Music entry
+@section Music entry
+@cindex Music entry
+@menu
+* Relative::
+* Point and click::
+@end menu
+
+
+
+@c . {Relative}
+@node Relative
+@subsection Relative
+@cindex Relative
+@cindex relative octave specification
+
+Octaves are specified by adding @code{'} and @code{,} to pitch names.
+When you copy existing music, it is easy to accidentally put a pitch in
+the wrong octave and hard to find such an error. To prevent these
+errors, LilyPond features octave entry.
+
+@cindex @code{\relative}
+@example
+ \relative @var{startpitch} @var{musicexpr}
+@end example
+
+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.
+ 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}.
+
+This distance is determined without regarding accidentals: a
+@code{fisis} following a @code{ceses} will be put above the
+@code{ceses}.
+
+Entering scales is straightforward in relative mode.
+
+@lilypond[fragment,verbatim,center]
+ \relative c'' {
+ g a b c d e f g g, g
+ }
+@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
+
+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.
+
+@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 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}.
+
+
+@c . {Point and click}
+@node Point and click
+@subsection Point and click
+
+[todo]
+
+@c . {Engravers}
+@node Engravers
+@section Engravers
+@cindex engravers
+@menu
+* Notation Contexts::
+* Creating contexts::
+* Default contexts::
+* Context properties::
+* Changing context definitions::
+* Defining new contexts::
+@end menu
+
+@c . {Music expressions}
+
+
+
+@c . {Notation Contexts}
+@node Notation Contexts
+@subsection Notation Contexts
+
+@cindex notation contexts
+
+Notation contexts are objects that only exist during a run of LilyPond.
+During the interpretation phase of LilyPond (when lily prints
+"interpreting music"), music a @code{\score} block is interpreted in
+time order, i.e. in much the same order that humans read, play, and
+write music.
+
+During this reading, the notation context is holds the state
+for the current point within the music. It contains information like
+
+@itemize @bullet
+ @item What notes are playing at this point?
+ @item What symbols will be printed at this point?
+ @item What is the current key signature, time signature, point within
+ the measure, etc.?
+@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).
+
+
+Contexts associated with sheet music output are called @emph{notation
+contexts}, those for sound output are called performance contexts.
+
+
+@node Creating contexts
+@subsection Creating contexts
+
+@cindex @code{\context}
+@cindex context selection
+
+Contexts for a music expression can be selected manually, using the
+following music expression.
+
+@example
+ \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+@end example
+
+This instructs lilypond to interpret @var{musicexpr} within the context
+ of type @var{contexttype} and with name @var{contextname}. If this
+context does not exist, it will be created.
+
+@quotation
+
+@lilypond[verbatim,singleline]
+\score {
+ \notes \relative c'' {
+ c4 <d4 \context Staff = "another" e4> f
+ }
+}
+
+@end lilypond
+@end quotation
+
+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.
+
+
+
+@node Default contexts
+@subsection Default contexts
+
+Most music expressions don't need @code{\context}: they inherit the
+notation context from their parent. Each note is a music expression, and
+as you can see in the following example, only the sequential music
+enclosing the three notes has an explicit context.
+
+@lilypond[verbatim,singleline]
+\score { \notes \context Voice = goUp { c'4 d' e' } }
+@end lilypond
+
+There are some quirks that you must keep in mind when dealing with
+defaults:
+
+Every top-level music is interpreted by the Score context, in other
+words, you may think of @code{\score} working like
+@example
+ \score @{
+ \context Score @var{music}
+ @}
+@end example
+
+Sequential music follows the contexts of its "children". Take this example
+@lilypond[verbatim, singleline]
+\score { \context Score \notes { c'4 ( d' )e' } }
+@end lilypond
+
+The sequential music is interpreted by the Score context initially
+(notice that the @code{\context} specification is redundant), but when a
+note is encountered, contexts are setup to accept that note. In this
+case, a Thread, Voice and Staff are created. The rest of the sequential
+music is also interpreted with the same Thread, Voice and Staff context,
+putting the notes on the same staff, in the same voice.
+
+This is a convenient mechanism, but do not expect opening chords to work
+without @code{\context}. For every note, a separate staff is
+instantiated.
+
+@lilypond[verbatim, singleline]
+\score { \notes <c'4 es'> }
+@end lilypond
+
+Of course, if the chord is preceded by a normal note in sequential
+music, the chord will be interpreted by the Thread of the preceding
+note:
+@lilypond[verbatim,singleline]
+\score { \notes { c'4 <c'4 es'> } }
+@end lilypond
+
+
+
+@node Context properties
+@subsection Context properties
+
+Notation contexts can be modified from within the @file{.ly} file. The
+following music expression does that job:
+
+@cindex @code{\property}
+@example
+ \property @var{contextname}.@var{propname} = @var{value}
+@end example
+
+Sets the @var{propname} property of the context @var{contextname} to the
+specified Scheme expression @var{value}. All @var{propname} and
+@var{contextname} are strings, which are typically unquoted.
+
+Properties that are set in one context are inherited by all of the
+contained contexts. This means that a property valid for the
+@code{Voice} context can be set in the @code{Score} context (for
+example) and thus take effect in all @code{Voice} contexts.
+
+
+
+
+@c . {Context definitions}
+@node Changing context definitions
+@subsection Changing context definitions
+
+@cindex context definition
+@cindex translator definition
+
+The most common way to define a context is by extending an existing
+context. You can change an existing context from the paper block, by
+first initializing a translator with an existing context identifier:
+@example
+\paper @{
+ \translator @{
+ @var{context-identifier}
+ @} @}
+@end example
+Then you can add engravers, remove engravers and set context
+properties. The syntax for these operations are respectively
+@example
+ \remove @var{engravername}
+ \consists @var{engravername}
+ @var{propname} = @var{value}
+@end example
+
+Here @var{engravername} is a string, the name of an engraver in the
+system. @var{propname} is a string and @var{value} is a Scheme
+expression.
+
+@lilypond[verbatim,singleline]
+\score { \notes {
+ c'4 c'4 }
+ \paper {
+ \translator { \StaffContext
+ \consists Instrument_name_engraver;
+ instrument = #"foo"
+ \remove Clef_engraver;
+ } } }
+@end lilypond
+
+@cindex engraver
+
+These type of property assignments happen before interpretation starts,
+so a @code{\property} expression will override any predefined settings.
+
+Engravers are the actual C++ modules that do the work in the
+interpretation phase.
+
+
+There are some pre-defined identifiers to simplify editing translators,
+they are defined in @file{ly/engraver.ly}. These pre-defined
+identifiers are:
+
+@table @code
+@cindex @code{StaffContext}
+ @item @code{StaffContext}
+ Default Staff context.
+@cindex @code{RhythmicStaffContext}
+
+ @item @code{RhythmicStaffContext}
+ Default RhythmicStaff context.
+@cindex @code{VoiceContext}
+
+ @item @code{VoiceContext}
+ Default Voice context.
+@cindex @code{ScoreContext}
+
+ @item @code{ScoreContext}
+ Default Score context.
+
+@cindex @code{HaraKiriStaffContext}
+
+ @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.}
+@end table
+
+@node Defining new contexts
+@subsection Defining new contexts
+
+If you want to build a context from scratch, you must also supply the
+following extra information:
+@itemize @bullet
+ @item A name, specified by @code{\name @var{contextname};}.
+
+ @item A cooperation engraver. This is specified by @code{\type
+@var{typename};}.
+@end itemize
+
+
+A context definition has this syntax:
+
+@example
+
+ \translator @code{@{}
+ @var{translatorinit} @var{translatormodifierlist}
+ @code{@}}
+@end example
+
+@var{translatorinit} can be an identifier or
+@example
+
+@end example
+where @var{typename} is one of
+
+The cooperation engraver groups other engravers, and specifies how they
+should cooperate. Choices are:
+
+@table @code
+@cindex @code{Engraver_group_engraver}
+ @item @code{Engraver_group_engraver}
+ The standard cooperation engraver.
+
+@cindex @code{Score_engraver}
+
+ @item @code{Score_engraver}
+ This is cooperation module that should be in the top level context,
+and only the toplevel context.
+
+@cindex @code{Grace_engraver_group}
+
+ @item @code{Grace_engraver_group}
+ This is a special cooperation module (resembling
+ @code{Score_engraver}) that is used to created an embedded
+ `miniscore'.
+@end table
+
+@var{translatormodifierlist} is a list of items where each item is
+one of
+
+@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.
+
+ @item @code{\consistsend} @var{engravername} @code{;}
+ Analogous to @code{\consists}, but makes sure that
+ @var{engravername} is always added to the end of the list of
+ engravers.
+
+ Some engraver types need to be at the end of the list; this
+ insures they are put there, and stay there, if a user adds or
+ removes engravers. This command is usually not needed for
+ end-users.
+
+ @item @code{\accepts} @var{contextname} @code{;}
+ Add @var{contextname} to the list of context this context can
+ contain. The first listed context is the context to create by
+ default.
+
+ @item @code{\denies}. The opposite of @code{\accepts}. Added for
+completeness, but is never used in practice.
+
+
+ @item @code{\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.
+
+ @item @var{propname} @code{=} @var{value} @code{;}
+ A property assignment.
+@end itemize
+
+In the @code{\paper} block, it is also possible to define translator
+identifiers. Like other block identifiers, the identifier can only
+be used as the very first item of a translator. In order to define
+such an identifier outside of @code{\score}, you must do
+
+@quotation
+
+@example
+\paper @{
+ foo = \translator @{ @dots{} @}
+@}
+\score @{
+ \notes @{
+ @dots{}
+ @}
+ \paper @{
+ \translator @{ \foo @dots{} @}
+ @}
+@}
+@end example
+
+@end quotation
+
+
+@cindex paper types, engravers, and pre-defined translators
+
+
+
+
+ Properties can be preset within the @code{\translator} block
+corresponding to the appropriate context. In this case, the syntax
+is
+
+@example
+ @var{propname} @code{=} @var{value}
+@end example
+
+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}.
+
+
+
+
+@c . {Syntactic details}
+@node Syntactic details
+@section Syntactic details
+@cindex Syntactic details
+@menu
+* Top level::
+* Identifiers::
+* Music expressions::
+* Manipulating music expressions::
+* Assignments::
+* Lexical details::
+* Lexical modes::
+* Ambiguities::
+@end menu
+
+@c . {Top level}
+@node Top level
+@subsection Top level
+@cindex Top level
+
+This section describes what you may enter at top level.
+
+
+@c . {Score}
+@subsubsection Score
+@cindex Score
+
+@cindex score definition
+
+The output is generated combining a music expression with an output
+definition. A score block has the following syntax:
+
+@example
+ \score @{ @var{musicexpr} @var{outputdefs} @}
+@end example
+
+@var{outputdefs} are zero or more output definitions. If no output
+definition is supplied, the default @code{\paper} block will be added.
+
+
+
+@c . {Default output}
+@subsubsection Default output
+
+Default values for the @code{\paper} and @code{\midi} block are set by
+entering such a block at top-level.
+
+@c . {Header}
+@subsubsection Header
+@cindex Header
+@cindex @code{\header}
+
+The syntax is
+
+@example
+ \header @{ @var{key1} = @var{val1};
+@cindex @code{ly2dvi}
+ @var{key2} = @var{val2}; @dots{} @}
+@end example
+
+
+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.
+
+It is customary to put the @code{\header} at the top of the file.
+
+@subsubsection Default output
+
+A @code{\midi} or @code{\paper} block at top-level sets the default
+
+paper block for all scores that lack an explicit paper block.
+
+@c . {Identifiers}
+@node Identifiers
+@subsection Identifiers
+@cindex Identifiers
+
+All of the information in a LilyPond input file, is represented as a
+Scheme value. In addition to normal Scheme data types (such as pair,
+number, boolean, etc.), LilyPond has a number of specialized data types,
+
+@itemize @bullet
+@item Input
+@item c++-function
+@item Music
+@item Identifier
+@item Translator_def
+@item Duration
+@item Pitch
+@item Score
+@item Music_output_def
+@item Moment (rational number)
+@end itemize
+
+LilyPond also includes some transient object types. Objects of these
+types are built during a LilyPond run, and do not `exist' per se within
+your input file. These objects are created as a result of your input
+file, so you can include commands in the input to manipulate them,
+during a lilypond run.
+
+@itemize @bullet
+@item Grob: short for Graphical object. See @ref{Grobs}.
+@item Molecule: device-independent page output object,
+including dimensions. Produced by some Grob functions
+See @ref{Molecules}
+@item Translator: object that produces audio objects or Grobs. This is
+not yet user accessible.
+@item Font_metric: object representing a font. (See @ref{Font metrics})
+
+@end itemize
+
+
+@node Music expressions
+@subsection Music expressions
+
+@cindex music expressions
+
+Music in LilyPond is entered as a music expression. Notes, rests, lyric
+syllables are music expressions, and you can combine music expressions
+to form new ones, for example by enclosing a list of expressions in
+@code{\sequential @{ @}} or @code{< >}. In this example, a compound
+expression is formed out of the quarter note @code{c} and a quarter note
+@code{d}:
+
+@example
+\sequential @{ c4 d4 @}
+@end example
+
+@cindex Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
+@cindex @code{<}
+@cindex @code{>}
+@cindex Simultaneous music
+@cindex @code{\simultaneous}
+
+The two basic compound music expressions are simultaneous and
+sequential music.
+
+@example
+ \sequential @code{@{} @var{musicexprlist} @code{@}}
+ \simultaneous @code{@{} @var{musicexprlist} @code{@}}
+@end example
+For both, there is a shorthand:
+@example
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
+for sequential and
+@example
+ @code{<} @var{musicexprlist} @code{>}
+@end example
+for simultaneous music.
+Other compound music expressions include
+@example
+ \repeat @var{expr}
+ \transpose @var{pitch} @var{expr}
+ \apply @var{func} @var{expr}
+ \context @var{type} = @var{id} @var{expr}
+ \times @var{fraction} @var{expr}
+@end example
+
+In principle, the way in which you nest sequential and simultaneous to
+produce music is not relevant. In the following example, three chords
+are expressed in two different ways:
+
+@lilypond[fragment,verbatim,center]
+ \notes \context Voice {
+ <a c'> <b d' > <c' e'>
+ < { a b c' } { c' d' e' } >
+ }
+@end lilypond
+
+However, in some cases, LilyPond will also try to choose contexts, and
+use the structure of the music expression to do so. This can have
+undesired effects: for example, LilyPond will create a separate staff
+for each note if you start a @code{\score} with a chord:
+@lilypond[verbatim,center,singleline]
+ \score {
+ \notes <c''4 e''>
+ }
+@end lilypond
+ The solution is to explicitly instantiate the context you desire.
+In this case this is typically a Voice context
+@lilypond[verbatim,center,singleline]
+ \score {
+ \notes\context Voice <c''4 e''>
+ }
+@end lilypond
+If you use @code{\context Staff} you will get separate stems for each
+note head, leading to collisions, so don't use that.
+
+
+
+@c . {Manipulating music expressions}
+@node Manipulating music expressions
+@subsection Manipulating music expressions
+
+The @code{\apply} mechanism gives you access to the internal
+representation of music. You can write Scheme-functions that operate
+directly on it. The syntax is
+@example
+ \apply #@var{func} @var{music}
+@end example
+This means that @var{func} is applied to @var{music}. The function
+@var{func} should return a music expression.
+
+This example replaces the text string of a script. It also shows a dump
+of the music it processes, which is useful if you want to know more
+about how music is stored.
+@lilypond[verbatim]
+#(define (testfunc x)
+ (if (equal? (ly-get-mus-property x 'text) "foo")
+ (ly-set-mus-property x 'text "bar"))
+ ;; recurse
+ (ly-set-mus-property x 'elements
+ (map testfunc (ly-get-mus-property x 'elements)))
+ (display x)
+ x
+)
+\score { \notes
+ \apply #testfunc { c4_"foo" }
+}
+@end lilypond
+
+For more information on what is possible, see the @ref{Tricks} and the
+automatically generated documentation.
+
+As always: directly accessing internal representations is dangerous: the
+implementation is subject to changes, so you should not use this if
+possible.
+
+
+@c . {Assignments}
+@node Assignments
+@subsection Assignments
+@cindex Assignments
+
+Identifiers allow objects to be assigned to names during the parse
+stage. To assign an identifier, you use @var{name}@code{=}@var{value}
+and to refer to an identifier, you preceed its name with a backslash:
+`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
+the input-types listed above. Identifier assignments can appear at top
+level in the LilyPond file, but also in @code{\paper} blocks.
+
+Semicolons are forbidden after top level assignments, but mandatory in
+other places. The rules about semicolons and assignments are very
+confusing, but when LilyPond input evolves more towards Scheme, we hope
+that this problem will grow smaller.
+
+An identifier can be created with any string for its name, but you will
+only be able to refer to identifiers whose names begin with a letter,
+being entirely alphabetical. It is impossible to refer to an identifier
+whose name is the same as the name of a keyword.
+
+The right hand side of an identifier assignment is parsed completely
+before the assignment is done, so it is allowed to redefine an
+identifier in terms of its old value, e.g.
+
+@example
+foo = \foo * 2.0
+@end example
+
+When an identifier is referenced, the information it points to is
+copied. For this reason, an identifier reference must always be the
+first item in a block.
+@example
+\paper @{
+ foo = 1.0
+ \paperIdent % wrong and invalid
+@}
+
+\paper @{
+ \paperIdent % correct
+ foo = 1.0 @}
+@end example
+
+@c . {Lexical details}
+@node Lexical details
+@subsection Lexical details
+@cindex Lexical details
+@menu
+@end menu
+
+@c . {Comments}
+@subsubsection Comments
+@cindex Comments
+
+@cindex @code{%}
+
+
+A one line comment is introduced by a @code{%} character.
+Block comments are started by @code{%@{} and ended by @code{%@}}.
+They cannot be nested.
+
+@c . {Direct Scheme}
+@subsubsection Direct Scheme
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+
+
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. In some places Scheme expressions also form valid syntax:
+whereever it is allowed,
+@example
+ #@var{scheme}
+@end example
+evaluates the specified Scheme code. If this is used at toplevel, then
+the result is discarded. Example:
+@example
+ \property Staff.TestObject \override #'foobar = #(+ 1 2)
+@end example
+
+@code{\override} expects two Scheme expressions, so there are two Scheme
+expressions. The first one is a symbol (@code{foobar}), the second one
+an integer (namely, 3).
+
+Scheme is a full-blown programming language, and a full discussion is
+outside the scope of this document. Interested readers are referred to
+the website @uref{http://www.schemers.org/} for more information on
+Scheme.
+
+
+@c . {Keywords}
+@subsubsection Keywords
+@cindex Keywords
+
+
+Keywords start with a backslash, followed by a number of lower case
+alphabetic characters. These are all the keywords.
+
+@example
+apply arpeggio autochange spanrequest commandspanrequest
+simultaneous sequential accepts alternative bar breathe
+char chordmodifiers chords clef cm consists consistsend
+context denies duration dynamicscript elementdescriptions
+font grace header in lyrics key mark pitch
+time times midi mm name pitchnames notes outputproperty
+override set revert partial paper penalty property pt
+relative remove repeat addlyrics partcombine score
+script stylesheet skip textscript tempo translator
+transpose type
+@end example
+
+@c . {Integers}
+@subsubsection Integers
+
+@cindex integers
+@cindex @code{+}
+@cindex @code{-}
+@cindex @code{*}
+@cindex @code{/}
+
+Formed from an optional minus sign followed by digits. Arithmetic
+operations cannot be done with integers, and integers cannot be mixed
+with reals.
+
+@c . {Reals}
+@subsubsection Reals
+@cindex real numbers
+
+
+
+
+
+Formed from an optional minus sign and a sequence of digits followed
+by a @emph{required} decimal point and an optional exponent such as
+@code{-1.2e3}. Reals can be built up using the usual operations:
+`@code{+}', `@code{-}', `@code{*}', and
+`@code{/}', with parentheses for grouping.
+
+@cindex @code{\mm},
+@cindex @code{\in}
+@cindex @code{\cm}
+@cindex @code{\pt}
+@cindex dimensions
+
+A real constant can be followed by one of the dimension keywords:
+@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
+points, inches and centimeters, respectively. This converts the number
+to a real that is the internal representation of dimensions.
+
+
+@c . {Strings}
+@subsubsection Strings
+@cindex string
+@cindex concatenate
+
+Begins and ends with the @code{"} character. To include a @code{"}
+character in a string write @code{\"}. Various other backslash
+sequences have special interpretations as in the C language. A string
+that contains no spaces can be written without the quotes. See
+@ref{Lexical modes} for details on unquoted strings; their
+interpretation varies depending on the situation. Strings can be
+concatenated with the @code{+} operator.
+
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
+
+
+@c . {Main input}
+@subsubsection Main input
+@cindex Main input
+
+@cindex @code{\maininput}
+
+The @code{\maininput} command is used in init files to signal that the
+user file must be read. This command cannot be used in a user file.
+
+@c . {File inclusion}
+@subsubsection Main input
+@cindex Main input
+
+@subsubsection File inclusion
+@cindex @code{\include}
+@example
+ \include @var{filename}
+@end example
+
+Include @var{filename}. The argument @var{filename} may be a quoted string (an
+unquoted string will not work here!) or a string identifier. The full
+filename including the @file{.ly} extension must be given,
+
+@subsubsection Version information
+@cindex @code{\version}
+@example
+ \version @var{string} ;
+@end example
+
+Specify the version of LilyPond that a file was written for. The
+argument is a version string in quotes, for example @code{"1.2.0"}.
+This is used to detect invalid input, and to aid
+@code{convert-ly} a tool that automatically upgrades input files. See
+See @ref{convert-ly} for more information on @code{convert-ly}.
+
+@cindex convert-ly
+
+
+@c . {Pitch names}
+@subsubsection Defining pitch names
+@cindex Lexical modes
+@cindex definining pitch names
+@cindex pitch names, definining
+@cindex note names
+@cindex chord modifier names
+
+A @code{\paper} block at top level sets the default paper block. A
+@code{\midi} block at top level works similarly.
+
+@c . {Assignments}
+@subsubsection Assignments
+@cindex assignments
+@cindex @code{#}
+
+Identifier assignments may appear at top level. @ref{Assignments}
+
+
+
+@c . {Direct scheme}
+@subsubsection Direct scheme
+@cindex Direct scheme
+
+Scheme statements maybe issued to produce interesting side-effects.
+
+
+@c . {Lexical modes}
+@node Lexical modes
+@subsection Lexical modes
+@cindex Lexical modes
+@cindex input mode
+@cindex mode, input
+@cindex @code{\notes}
+@cindex @code{\chords}
+@cindex @code{\lyrics}
+
+To simplify entering notes, lyrics, and chords, LilyPond has three
+special input modes on top of the default mode: note, lyrics and chords
+mode. These input modes change the way that normal, unquoted words are
+interpreted: for example, the word @code{cis} may be interpreted as a
+C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
+respectively.
+
+A mode switch is entered as a compound music expressions
+@example
+@code{\notes} @var{musicexpr}
+@code{\chords} @var{musicexpr}
+@code{\lyrics} @var{musicexpr}.
+@end example
+
+In each of these cases, these expressions do not add anything to the
+meaning of their arguments. They are just a way to indicate that the
+arguments should be parsed in indicated mode. The modes are treated in
+more detail in the sections @ref{Note entry}, @ref{Lyrics} and
+@ref{Chords}.
+
+You may nest different input modes.
+
+@c . {Ambiguities}
+@node Ambiguities
+@subsection Ambiguities
+@cindex ambiguities
+@cindex grammar
+
+
+The grammar contains a number of ambiguities. We hope to resolve them at
+some time.
+
+@itemize @bullet
+ @item The assignment
+
+ @example
+foo = bar
+@end example
+
+ can be interpreted as making a string identifier @code{\foo}
+ containing @code{"bar"}, or a music identifier @code{\foo}
+ containing the syllable `bar'.
+
+ @item The assignment
+
+ @example
+foo = -6
+@end example
+
+ can be interpreted as making an integer identifier
+ containing -6, or a Request identifier containing the
+ fingering `6' (with neutral direction).
+
+ @item If you do a nested repeat like
+
+ @quotation
+
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
+
+ @end quotation
+
+ then it is ambiguous to which @code{\repeat} the
+ @code{\alternative} belongs. This is the classic if-then-else
+ dilemma. It may be solved by using braces.
+
+ @item (an as yet unidentified ambiguity :-)
+@end itemize
+
- @item @code{\stemDown}@keyindex{stemDown}
- Force stems, beams, and slurs to point down.
- @item @code{\stemUp}@keyindex{stemUp}
- Force stems, beams and slurs to point up.
-@end table
+@c .{Local emacs vars}
+@c Local variables:
+@c mode: texinfo
+@c minor-mode: font-lock
+@c minor-mode: outline
+@c outline-layout: (-1 : 0)
+@c outline-use-mode-specific-leader: "@c \."
+@c outline-primary-bullet: "{"
+@c outline-stylish-prefixes: nil
+@c outline-override-protect: t
+@c End: