-@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 ugh: because of @include, we need to fill in these nodes
+@c Note:
+@c
+@c A menu is needed before every deeper *section nesting of @nodes
+@c Run M-x texinfo-all-menus-update
+@c to automagically fill in these menus
+@c before saving changes
-@node Reference Manual, , , top
+
+@macro refbugs
+@unnumberedsubsec Bugs
+
+@end macro
+
+
+@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
-@c May be fragile. Better make single link to generated doco?
-* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
-* Engravers:(lilypond-internals)LilyPond engravers.
-* Backend:(lilypond-internals)LilyPond backend.
-@end menu
+This document describes GNU LilyPond and its input format. The last
+revision of this document was for LilyPond 1.3.141.
+@menu
+* Overview::
+* Note entry::
+* Staff notation::
+* Polyphony::
+* Beaming::
+* Expressive marks::
+* Ornaments::
+* Repeats::
+* Rhythmic music::
+* Piano music::
+* Lyrics::
+* Chords::
+* Writing parts::
+* Custodes::
+* Tuning output::
+* Page layout::
+* Sound::
+* Music entry::
+* Interpretation context::
+* Syntactic details::
+* Lexical 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.
-LilyPond input can be classified into three types:
-@itemize @bullet
- @item musical expressions: a musical expression is some combination of
-rest, notes, lyrics
- @item output definitions: recipes for translating those musical
-expressions into performances (MIDI) or graphics (eg. PostScript).
+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.
+Symbols and their placements are @emph{generated} from a high-level
+musical description. In other words, LilyPond would be best described
+by `music compiler' or `music to notation compiler'.
- @item declarations: by declaring and naming musical expressions, you
-can enter and edit them in manageable chunks.
-@end itemize
+LilyPond is linked to GUILE, GNU's Scheme library for extension. The
+Scheme library provides the glue that holds together the low-level
+routines and separate modules general, which are C++.
-@node Top level
-@section Top level
+When lilypond is run to typeset sheet music, the following happens:
+@itemize @bullet
+@item GUILE Initialization: various scheme files are read
+@item parsing: first standard @code{ly} initialization files are read, and
+then the user @file{ly} file is read.
+@item interpretation: the music in the file is processed ``in playing
+order'', i.e. the order that you use to read sheet music, or the
+order in which notes are played.
+
+@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
-This section describes what you may enter at top level.
+During these stages different types of data play the the main role:
+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.
-@cindex score definition
+@c . {Note entry}
+@node Note entry
+@section Note entry
+@cindex Note entry
-The output is generated combining a music expression with an output
-definition. A score block has the following syntax:
+The most basic forms of music are notes. We discuss how you enter them
+here. Notes on their own don't form valid input, but for the sake of
+brevity we omit obligotary lint such as @code{\score} blocks and
+@code{\paper} declarations.
-@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.
+@menu
+* Pitches::
+* Defining pitch names::
+* Durations::
+* Notes::
+* Easy Notation note heads ::
+* Tie::
+* Tuplets::
+* Rests::
+* Skip::
+* Note mode::
+@end menu
-@cindex header
+@c . {Pitches}
+@node Pitches
+@subsection Pitches
-@keyindex{header}
+@cindex Pitch names
+@cindex Note specification
+@cindex pitches
+@cindex entering notes
-The syntax is
+The verbose syntax for pitch specification is
+@cindex @code{\pitch}
@example
- \header @{ @var{key1} = @var{val1};
- @var{key2} = @var{val2}; @dots{} @}
+ \pitch @var{scmpitch}
@end example
-A header describes the file's contents. It can also appear in a
-@code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this
-information for generating titles. Key values that are used by
-@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
-metre, arranger, piece and tagline.
-
-It is customary to put the @code{\header} at the top of the file.
+@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
-@node Pitch names
-@section Pitch names
+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{a} through @code{g} (where the octave is formed by notes ranging
+from @code{c}, to @code{b}). The pitch @code{c} is an octave below
+middle C and the letters span the octave above that C.
-@cindex pitch names
-@cindex note names
-@cindex chord modifier names
+@cindex note names, Dutch
-Note names and chord modifiers can be customised for nationalities.
-languages and conventions. The syntax is as follows.
-@example
- \pitchnames @keyindex{pitchnames} @var{scheme-alist}
- \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
-@end example
+In 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 are accepted.
-See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
-specific examples how to do this. tables can be tailored specified
-using. Some national note names have been provided, see
-@ref{Other languages}.
-A @code{\paper} block at top level sets the default paper block. A
-@code{\midi} block at top level works similarly.
+LilyPond 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:
-Identifier assignments may appear at top level. Semicolons are
-forbidden after top level assignments.
+@example
+ Note Names sharp flat
+nederlands.ly c d e f g a bes b -is -es
+english.ly c d e f g a bf b -s/-sharp -f/-flat
+deutsch.ly c d e f g a b h -is -es
+norsk.ly c d e f g a b h -iss/-is -ess/-es
+svenska.ly c d e f g a b h -iss -ess
+italiano.ly do re mi fa sol la sib si -d -b
+catalan.ly do re mi fa sol la sib si -d/-s -b
+@end example
-@cindex assignments
+@cindex @code{'}
+@cindex @code{,}
-@node Lexical conventions
-@section Lexical conventions
-@cindex lexical conventions
+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.
+@lilypond[fragment,verbatim,center]
+ c' c'' es' g' as' gisis' ais'
+@end lilypond
+@c . {Defining pitch names}
+@node Defining pitch names
+@subsection Defining pitch names
-@unnumberedsubsec Comments
+@cindex defining pitch names
+@cindex pitch names, defining
-@cindex comment
+Note names and chord modifiers can be customised for nationalities. The
+syntax is as follows.
-@indexcode{%}
+@cindex @code{\pitchnames}
+@cindex @code{\chordmodifiers}
+@example
+ \pitchnames @var{scheme-alist}
+ \chordmodifiers @var{scheme-alist}
+@end example
-A one line comment is introduced by a `@code{%}' character.
-Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
-They cannot be nested.
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+specific examples how to do this.
-@unnumberedsubsec Scheme
-@indexcode{#}
-LilyPond contains a Scheme interpreter (the GUILE library) for
-internal use. The interpreter is accessed by the pound sign:
+@c . {Durations}
+@node Durations
+@subsection Durations
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-Whereever the syntax allows Scheme expressions, you may enter one as
+@cindex duration
+@cindex @code{\duration}
+The syntax for a verbose duration specification is
@example
- #@var{scheme}
+ \duration @var{scmduration}
@end example
+Here, @var{scmduration} is a Scheme object of type Duration. See
+@ref{Duration} for more information.
-Evaluates the specified Scheme code. If this is used at toplevel, then
-the result is discarded. Example:
-@example
- \property Staff.TestObject \override #'symbol = #(+ 1 2)
-@end example
-(in this case, @code{\override} expects two Scheme expressions.
+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.
-[refer appendix/ online intro on Scheme]
+@quotation
-@unnumberedsubsec Keywords
+@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
-@cindex keyword
-Keywords start with a backslash, followed by a number of lower case
-alphabetic characters. These are all the keywords.
+@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
-@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
-@end example
+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}.
-@unnumberedsubsec Integers
+If the duration is omitted then it is set to the previous duration
+entered. At the start of parsing a quarter note is assumed. The
+duration can be followed by a dot (`@code{.}') to obtain dotted note
+lengths.
+@cindex @code{.}
-@cindex integer
+@lilypond[fragment,verbatim,center]
+ a'4. b'4.. c'8.
+@end lilypond
+@cindex @code{r}
+@cindex @code{s}
-Formed from an optional minus sign followed by digits. Arithmetic
-operations cannot be done with integers, and integers cannot be mixed
-with reals.
+You can alter the length of duration by appending
+`@code{*}@var{fraction}'. This will not affect the appearance of the
+notes or rests produced.
-@unnumberedsubsec Reals
+@c . {Notes}
+@node Notes
+@subsection Notes
-@cindex real
-
+A note specification has the form
-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.
+@example
+ @var{pitch}[@var{octavespec}][!][?][@var{duration}]
+@end example
-A real constant can be followed by one of the dimension
-keywords:
-@cindex dimensions
- @code{\mm}@keyindex{mm},
-@code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
-@code{\cm}@keyindex{cm}, for millimeters, points, inches and
-centimeters, respectively. This converts the number to a real that
-is the internal representation of dimensions.
+LilyPond will determine what accidentals to typeset depending on the key
+and context. The alteration refers to what note is heard, not to whether
+an accidental is 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
+i.e., an accidental within parentheses can be obtained by adding the
+question mark `@code{?}' after the pitch.
+@lilypond[fragment,verbatim,center]
+ cis' d' e' cis' c'? d' e' c'!
+@end lilypond
-@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.
-The tokenizer accepts the following commands. They have no grammatical
-function, hence they can appear anywhere in the input.
+@node Easy Notation note heads
+@subsection Easy Notation note heads
-@example
- \maininput@keyindex{maininput}
-@end example
+@cindex easy notation
+@cindex Hal Leonard
-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.
+A entirely different type of note head is the "easyplay" note head: a
+note head that includes a note name. It is used in some publications by
+Hal-Leonard Inc. music publishers.
-@unnumberedsubsec file inclusion
+@lilypond[singleline,verbatim]
+\include "paper26.ly"
+\score {
+ \notes { c'2 e'4 f' | g'1 }
+ \paper { \translator { \EasyNotation } }
+}
+@end lilypond
-@example
- \include@keyindex{include} @var{file}
-@end example
+Note that @code{EasyNotation} overrides a @code{Score} context. You
+probably will want to print it with magnification to make it better
+readable.
-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,
+@cindex Xdvi
+@cindex ghostscript
-@unnumberedsubsec Version information
+If you view the result with Xdvi, then staff lines will show through the
+letters. Printing the postscript file obtained either by using dvips or
+the @code{-f ps} option of lilypond will produce the desired result.
-@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
+@node Tie
+@subsection Tie
-@node Other languages
-@section Other languages
-@cindex Note names, international
+@cindex Tie
+@cindex ties
+@cindex @code{~}
-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:
+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
- 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
+@lilypond[fragment,verbatim,center]
+ e' ~ e' <c' e' g'> ~ <c' e' g'>
+@end lilypond
-Pitch names can be redefined using the @code{\pitchnames} command, see
-@ref{Pitch names}.
+If you dislike the amount of ties created for a chord, you set
+@code{Voice.sparseTies} to true, resulting in a smaller number of
+ties:
+@lilypond[fragment,verbatim,center]
+ \property Voice.sparseTies = ##t
+ <c' e' g'> ~ <c' e' g'>
+@end lilypond
-@node Lexical modes
-@section Lexical modes
-@cindex Lexical modes
-@cindex modes
+In its meaning a tie is just a way of extending a note duration, similar
+to the augmentation dot: the following example are three ways of notating
+exactly the same concept.
+@lilypond[fragment, singleline]
+c'2 c'4 ~ c'4
+@end lilypond
+@refbugs
-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.
+At present, the tie is implemented as a separate thing, temporally
+located in between the notes. There is also no way to convert
+between tied notes, dotted notes and plain notes.
-@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{}.
+Tieing only a subset of the note heads of a chord is not supported in a
+simple way. It can be achieved by moving the tie-engraver into Thread
+context and turning off ties per Thread.
-@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
- Since combinations of numbers and dots are used for indicating
- durations, you can not enter real numbers in this mode.
-@end table
+@node Tuplets
+@subsection Tuplets
-[todo: include short table showign differences]
+@cindex tuplets
+@cindex triplets
+@cindex @code{\times}
-@node Types
-@section Types
+Tuplets are made out of a music expression by multiplying their duration
+with a fraction.
-@cindex Identifiers
+@cindex @code{\times}
+@example
+ \times @var{fraction} @var{musicexpr}
+@end example
-[say something about types]
+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:
-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,
+@lilypond[fragment,verbatim,center]
+ g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@end lilypond
-@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)
-@end itemize
+The property @code{tupletSpannerDuration} specifies how long brackets
+should last. With this, you can make lots of tuplets while typing
+@code{\times} only once. This saves typing work when you must make lots
+of tuplets.
-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.
+@lilypond[fragment, relative, singleline, verbatim]
+\property Voice.tupletSpannerDuration = #(make-moment 1 4)
+\times 2/3 { c''8 c c c c c }
+@end lilypond
-@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)
-@end itemize
+@c . {Rests}
+@node Rests
+@subsection Rests
+@cindex Rests
-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}.
+Rests are entered like notes, with note name `@code{r}'.
-@var{value} is any valid Scheme value or any of the input-types listed
-above.
-An identifier can be created with any string for its name, but you will
-only be able to refer to identifiers whose names begin with a letter,
-being entirely alphanumeric. It is impossible to refer to an identifier
-whose name is the same as the name of a keyword.
+@c . {Skip}
+@node Skip
+@subsection Skip
+@cindex Skip
-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
+ \skip @var{duration} @code{;}
+ s@var{duration}
@end example
+@cindex @code{\skip}
-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
-@}
+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. The shorthand is only available in Note and Chord mode.
-\paper @{
- \paperIdent % correct
- foo = 1.0
-@}
-@end example
-@node Music expressions
-@section Music expressions
+@node Note mode
+@subsection Note mode
-@cindex music expressions
-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:
-@example
-\sequential @{ c4 d4 @}
-@end example
+@cindex note mode
+@cindex @code{\notes}
-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).
+Note mode is the lexical mode generally used for inputting notes. The
+syntax is
+@example
+\notes @var{expr}
+@end example
-Atomic music expression are discussed in
-subsection @ref{Atomic music expressions}. Compound music expressions are
-discussed in subsection @ref{Compound music expressions}.
+This instructs the tokenizer to interpret @var{expr} in note mode. If a
+a sequence of alfabetical characters, like @code{foobar}, LilyPond first
+checks if @code{foobar} is a pitch name. If it is not a pitch name,
+then it is treated as a string.
+Numbers and dots indicate durations, so you can enter floating point
+numbers in this mode.
-@node Atomic music expressions
-@section Atomic music expressions
+@node Staff notation
+@section Staff notation
+@cindex Staff notation
+@menu
+* Key signature::
+* Clef::
+* Time signature::
+* Unmetered music::
+* Bar lines::
+@end menu
+@c . {Key}
+@node Key signature
+@subsection Key signature
+@cindex Key
-@cindex pitch
+@cindex @code{\key}
-@cindex duration
-
+Changing the key signature is done with the @code{\key} command.
+@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}
+
+Here, @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.
-The syntax for pitch specification is
+This command sets context property @code{Staff.keySignature}.
+@cindex @code{keySignature}
+@c . {Clef}
+@node Clef
+@subsection Clef
+@cindex @code{\clef}
@example
- \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
+ \clef @var{clefname} @code{;}
@end example
-@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.
-
-In Note and Chord mode, pitches may be designated by names. See
-section
- @c @ref{Other languages} FIXME
- for pitch names in different languages.
-
-The syntax for duration specification is
+Shortcut for
@example
- \duration@keyindex{duration}
- @{ @var{length} @var{dotcount} @}
+ \property Staff.clefGlyph = @var{glyph associated with clefname}
+ \property Staff.clefPosition = @var{clef Y-position for clefname}
+ \property Staff.clefOctavation = @var{extra pitch of clefname}
@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}.
+Supported clef-names include
-In Note, Chord, and Lyrics mode, durations may be designated by
-numbers and dots.
+@itemize @bullet
+@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
+Supported associated glyphs (for @code{Staff.clefGlyph}) are:
-@node Note specification
-@section Note specification
-@cindex Note specification
+@itemize @bullet
+@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
-@cindex pitches
+@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.''
-@cindex entering notes
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel clefs
-A note specification has the form
+@c . {Time signature}
+@node Time signature
+@subsection Time signature
+@cindex Time signature
+@cindex meter
+@cindex @code{\time}
+
+The time signature is changed by the @code{\time} command. Syntax:
@example
- @var{pitch}[@var{octavespec}][!][?][@var{duration}]
+ \time @var{numerator}@code{/}@var{denominator} @code{;}
+@end example
+Internally, this is a shortcut for doing
+@example
+ \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
@end example
-The pitch of the note is specified by the note's name.
+[TODO: discuss options for layout]
+@c . {Partial}
+@subsection Partial
+@cindex Partial
+@cindex anacrusis
+@cindex upstep
+@cindex partial measure
+@cindex measure, partial
+@cindex shorten measures
+@cindex @code{\partial}
-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.
+Partial measures are entered using the @code{\partial} command:
+@example
+ \partial @var{duration} @code{;}
+@end example
-LilyPond has predefined sets of notenames for various languages. See
-@ref{Other languages}.
+Internally, this is a shortcut for
-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.
+@example
+ \property Score.measurePosition = -@var{length of duration}
+@end example
+@cindex @code{|}
-@lilypond[fragment,verbatim,center]
- c' d' e' f' g' a' b' c''
-@end lilypond
-@lilypond[fragment,verbatim,center]
- cis' dis' eis' fis' gis' ais' bis'
-@end lilypond
+@node Unmetered music
+@subsection Unmetered music
-@lilypond[fragment,verbatim,center]
- ces' des' es' fes' ges' as' bes'
-@end lilypond
+Bar lines and bar numbers are calculated automatically. For unmetered
+music (e.g. cadenzas), this is not desirable. The property
+@code{Score.timing} can be used to switch off this automatic timing
-@lilypond[fragment,verbatim,center]
- cisis' eisis' gisis' aisis' beses'
+@lilypond[fragment,relative,singleline,verbatim]
+c'2.
+\property Score.timing = ##f
+c4 c4 c4
+\property Score.timing = ##t
+c4 c4 c4
@end lilypond
-@lilypond[fragment,verbatim,center]
- ceses' eses' geses' ases' beses'
-@end lilypond
-
-Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
-will determine what accidentals to typeset depending on the key and
-context. A reminder accidental
-@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.
-
-@lilypond[fragment,verbatim,center]
- cis' d' e' cis' c'? d' e' c'!
-@end lilypond
-
-
-@cindex duration
-
-Durations are entered as their reciprocal values. For notes longer
-than a whole note, use identifiers.
-
-@quotation
-
-@example
-c'\longa c'\breve
-c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
-@end example
-
-@end quotation
-
-@quotation
-
-@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";
- } %}
- }
-}
-@end lilypond
-@end quotation
-
-@quotation
-
-@example
-r\longa r\breve
-r1 r2 r4 r8 r16 r32 r64 r64
-@end example
-
-@end quotation
-
-@quotation
-
-@lilypond[]
-\score {
- \notes \relative c'' {
- r\longa r\breve
- r1 r2 r4 r8 r16 r32 r64 r64
- }
- \paper {
- loose_column_distance = 2.5 * \staffspace;
- linewidth = -1.0;
- \translator {
- \StaffContext
- \remove "Clef_engraver";
- \remove "Staff_symbol_engraver";
- \remove "Bar_engraver";
- }
- }
-}
-@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.
-
-
-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.
-
+The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used to
+achieve the same effect.
-@cindex lyrics expressions
-
-Syllables are entered like notes, with pitches replaced by text. For
-example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
-with quarter note duration. Note that the hyphen has no special
-meaning for lyrics, and does not introduce special symbols. See
-section @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 . {Bar lines}
+@node Bar lines
+@subsection Bar lines
+@cindex Bar lines
-
-@cindex properties
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
@example
- \property@keyindex{property}
- @var{contextname}.@var{propname} = @var{value}
+ \bar @var{bartype};
@end example
-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.
-
-
-
-@cindex translator switches
-
+This is a shortcut for doing
@example
- \translator@keyindex{translator}
- @var{contexttype} = @var{name}
+ \property Score.whichBar = @var{bartype}
@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.
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeats}, and the documentation of @code{whichBar} in the generated
+documentation.
-Usually this is used to switch staffs in Piano music, e.g.
-@example
- \translator Staff = top @var{Music}
-@end example
+@cindex Bar_line_engraver
+@cindex whichBar
+@cindex repeatCommands
+@cindex defaultBarType
+Bar lines are created by the @code{Bar_line_engraver}. That engraver examines
+@code{whichBar} at every moment. Whenever it is set to a string, it will
+create a bar with that type. @code{whichBar} is usually set
+automatically: at the start of a measure it is set to
+@code{defaultBarType}. The contents of @code{repeatCommands} is used to
+override default measure bars.
-@cindex output properties
+@code{whichBar} can also be set directly, using @code{\property} or
+@code{\bar ; }. These settings take precedence over automatic @code{whichBar}
+settings.
-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 . {Polyphony}
+@node Polyphony
+@section Polyphony
+@cindex Polyphony
+[TODO: collisions, rest-collisinos, voiceX identifiers, how to
+which contexts to instantiate. some small examples? ]
-@lilypond[fragment,verbatim]
-\relative c'' { c4
- \context Staff \outputproperty
- #(make-type-checker 'Note_head)
- #'extra-offset = #'(5.0 . 7.5)
-<c8 e g> }
-@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.
+@table @code
+@cindex @code{\shiftOff}
+ @item @code{\shiftOff}
+ Disable horizontal shifting of note heads that collide.
-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 @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.
+@cindex @code{\stemBoth}
+ @item @code{\stemBoth}
+ Allow stems and beams to point either upwards or
+ downwards, decided automatically by LilyPond.
-@cindex commands
+@cindex @code{\stemDown}
+ @item @code{\stemDown}
+ Force stems and beams to point down.
-Commands are music expressions that have no duration.
+@cindex @code{\stemUp}
+ @item @code{\stemUp}
+ Force stems and beams to point up.
+@end table
+@cindex @code{\slurBoth}
+@cindex @code{\slurDown}
+@cindex @code{\slurUp}
+Similarly, for slurs use
+@code{\slurBoth},
+@code{\slurDown},
+@code{\slurUp}.
+
+@cindex @code{\tieBoth}
+@cindex @code{\tieDown}
+@cindex @code{\tieUp}
+For ties use
+@code{\tieBoth},
+@code{\tieDown},
+@code{\tieUp}.
+
+@cindex @code{\dynacmicBoth}
+@cindex @code{\dynamicDown}
+@cindex @code{\dynamicUp}
+For dynamics use
+@code{\dynamicBoth},
+@code{\dynamicDown},
+@code{\dynamicUp}.
+
+@c text scripts? articulation scripts? fingering?
+
+@cindex @code{\voiceOne}
+@cindex @code{\voiceTwo}
+@cindex @code{\voiceThree}
+@cindex @code{\voiceFour}
+@cindex @code{\oneVoice}
+@cindex @code{\shiftOn}
+@cindex @code{\shiftOff}
+
+If two voices sharing one staff have the same stem directions, their
+note heads may collide. You can shift the note heads of one voice by
+setting @code{\shiftOn}. This can be undone by setting
+@code{\shiftOff}.
+
+For simple polyphonic music, shorthands are available that combine
+directions and shift settings: @code{\voiceOne}, @code{\voiceTwo},
+@code{\voiceThree}, @code{\voiceFour} and @code{\oneVoice}.
+
+
+@node Beaming
+@section Beaming
+
+Beams are used to group short notes into chunks that are aligned with
+the metrum. LilyPond guesses where beams should be inserted, but if
+you're not satisfied with the automatic beaming, you can either instruct
+lilypond which patterns to beam automatically. In specific cases, you
+can also specify explicitly what to beam and what not.
+
+
+@c . {Automatic beams}
+@subsection Automatic beams
+
+@cindex @code{Voice.autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
-@example
- @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
-@end example
+A large number of Voice properties are used to decide how to generate
+beams. Their default values appear in @file{scm/auto-beam.scm}.
-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.
+By default, automatic beams can start on any note@footnote{In exotic
+time signatures such as 1/8 and 1/16 this is not true} but can only end
+in a few positions within the measure: they can end on a beat, or at
+durations specified by the properties in
+@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
+are defined in @file{scm/auto-beam.scm}.
-
+The syntax for changing the value @code{autoBeamSettings} is set using
+@code{\override} and unset using @code{\revert}:
@example
- \mark@keyindex{mark} @var{unsigned};
- \mark @var{string};
+\property Voice.autoBeamSettings \override #'(@var{BE} @var{N} @var{M} @var{P} @var{Q}) = @var{dur}
+\property Voice.autoBeamSettings \revert #'(@var{BE} @var{N} @var{M} @var{P} @var{Q})
@end example
-
-Prints a mark over or under the staff. You must add
-@code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
-this to work.
-
-@node barlines
-@section barlines
-
+Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
+whether the rule applies to begin or end-points. The quantity
+@var{N}/@var{M} refers to a time signature (@code{* *} may be entered to
+designate all time signatures), @var{P}/@var{Q} refers to the length of
+the beamed notes (@code{* *} designate notes of any length).
+
+If you want automatic beams to end on every quarter note, you can
+use the following:
@example
- \bar@keyindex{bar} @var{bartype};
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 1 4)
@end example
+The duration a quarter note is 1/4 of a whole note. It is entered as
+@code{(make-moment 1 4)}.
-This is a short-cut for doing
+The same syntax can be used to specify beam starting points. In this
+example, you automatic beams can only end on a dotted quarter note.
@example
- \property Score.whichBar = @var{bartype}
+\property Voice.autoBeamSettings \override
+ #'(begin * * * *) = #(make-moment 3 8)
+@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8 has passed within the measure).
+
+You can also restrict rules to specific time signatures. A rule that
+should only be applied in @var{N}/@var{M} time signature is formed by
+replacing the first asterisks by @var{N} and @var{M}. For example, a
+rule for 6/8 time exclusively looks like
+@example
+\property Voice.autoBeamSettings \override
+ #'(begin 6 8 * *) = ...
@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}.
+If you want a rule to apply to certain types of beams, you can use the
+second pair of asterisks. Beams are classified according to the shortest
+note they contain. For a beam ending rule that only applies to beams
+with 32nd notes (and no shorter notes), you would use @code{(end * * 1
+32)}.
+[say something about irregular meters. eg 5/8 = 2+3/8, 3+2/8]
-@example
- \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
-@end example
+Automatic beams can not be put on the last note in a score.
-A short-cut for doing
-@example
- \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
-@end example
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{Voice.noAutoBeaming}
-See the documentation of @code{timeSignatureFraction}
+Automatic beaming is on by default, but it can switched off by setting
+@code{Voice.noAutoBeaming} to true. You you may find this necessary for
+a melody that goes with lyrics.
-@example
+@refbugs
- \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
-@end example
+It is not possible to specify beaming for beams with mixed durations,
+that differs from the beaming of all separate durations, ie, you'll
+have to specify manual beams to get:
+@lilypond[fragment,singleline,relative]
+ \property Voice.autoBeamSettings
+ \override #'(end * * * *) = #(make-moment 3 8)
+ \time 12/8; c'8 c c c16 c c c c c [c c c c] c8 c c4
+@end lilypond
-Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
-requests output with 76 quarter notes per minute.
-@example
- \partial@keyindex{partial} @var{duration} @code{;}
-@end example
+@c . {Manual beams}
+@cindex Automatic beams
+@subsection Manual beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
-Short cut for
+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{]}:
-@example
- \property Score.measurePosition = @var{length of duration}
-@end example
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ r4 [r8 g'' a r8] r8 [g | a] r8
+ }
+@end lilypond
+Whenever an manual beam is busy, the auto beam will not produce
+anything.
-See the documentation of @code{measurePosition}.
+@cindex @code{stemLeftBeamCount}
-@cindex anacrusis
+If you have specific wishes for the number of beams, you can fully
+control the number of beams through the properties
+@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
-@cindex upstep
+@lilypond[fragment,relative,verbatim]
+ \context Staff {
+ [f'8 r16 f g a]
+ [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
+ }
+@end lilypond
+@cindex @code{stemRightBeamCount}
-@example
+The beam symbol can be tweaked through @code{Voice.Beam}'s
+grob-properties @code{height} and @code{staff-position},
+in staff-spaces.
- @code{|}@indexcode{|}
-@cindex bar check
+Set @code{height} to zero, to get horizontal beams:
-@end example
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'direction = #1
+ \property Voice.Beam \set #'height = #0
+ [a''8 e' d c]
+@end lilypond
-@cindex shorten measures
+Here's how you'd specify a weird looking beam that instead of being
+horizontal, falls two staff spaces:
-@cindex upstep
+@lilypond[fragment,relative,verbatim]
+ \property Voice.Beam \set #'staff-position = #2
+ \property Voice.Beam \set #'height = #-2
+ [c'8 c]
+@end lilypond
+@cindex @code{default-neutral-direction}
-`@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.
+@node Expressive marks
+@section Expressive marks
+@c . {Slur}
+@menu
+* Slur ::
+* Phrasing slur::
+* Breath marks::
+* Tempo::
+* Text spanner::
+@end menu
-@example
- \penalty@keyindex{penalty} @var{int} @code{;}
-@end example
+@node Slur
+@subsection Slur
+@cindex slur
-Discourage or encourage line breaks. See identifiers
-@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
-section [on identifiers] [FIXME].
+A slur indicates that notes are to be played bound or @emph{legato}. In
+lilypond, they are entered using parentheses:
+@lilypond[fragment,verbatim,center]
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
+@end lilypond
-@example
- \clef@keyindex{clef} @var{clefname} @code{;}
-@end example
-Short-cut for
+Slurs avoid crossing stems, and are attached to note heads whenever
+possible. In some instances involving beams slurs may be attached to a
+stem end. If you want to override this layout you can do this through
+@code{Voice.Slur}'s grob-property @code{attachment}:
-@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
+Maybe reinclude other slur features and move back to tricks? Esp. the
+second example, how to fix, can be very helpful.
-Supported clef-names include
+@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
-[todo]
+If a slur would strike through a stem or beam, the slur will be moved
+away upward or downward. If this happens, attaching the slur to the
+stems might look better:
-@example
+@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
- \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}'.
+Similarly, the curvature of a slur is adjusted to stay clear of note
+heads and stems. When that would increase the curvature too much, the
+slur is reverted to its default shape. The threshold for this decision
+is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely
+related to the enclosed area between the slur and the notes. Usually,
+the default setting works well, but in some cases you may prefer a
+curved slur when LilyPond decides for a vertically moved one. You can
+express this by increasing the @code{beautiful} value:
+
+@lilypond[verbatim,singleline,relative]
+ \property Voice.Beam \override #'direction = #-1
+ \property Voice.Slur \override #'direction = #1
+ c'16( a' f' a a f a, )c,
+ c( a' f' a a f d, )c
+ \property Voice.Slur \override #'beautiful = #5.0
+ c( a' f' a a f d, )c
+@end lilypond
+@refbugs
-@node Manual beams
-@section Manual beams
-@cindex beams
+The definition for @code{beautiful} is vague, the default setting is
+experimental computer science.
-A beam is specified by surrounding the beamed notes with brackets
-`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
+@cindex Adusting slurs
-@lilypond[fragment,verbatim,center]
- [a'8 a'] [a'16 a' a' a']
-@end lilypond
+@node Phrasing slur
+@subsection Phrasing slur
-Some more elaborate constructions:
+@cindex phrasing slur
+@cindex phrasing mark
-@lilypond[fragment,verbatim,center]
- [a'16 <a' c''> c'' <a' c''>]
- \times 2/3 { [e'8 f' g'] }
+A phrasing slur (or phrasing mark) connects chords and is used to
+indicate a musical sentence. It is entered using @code{\(} and
+@code{\)}.
+
+@lilypond[fragment,verbatim,center,relative]
+ \time 6/4; c''\((d)e f(e)\)d
@end lilypond
-Beaming can be generated automatically; see section @ref{Automatic Beaming}.
+Typographically, the phrasing slur behaves almost exactly like a normal
+slur. The grob associated with it is @code{Voice.PhrasingSlur}.
+@node Breath marks
+@subsection Breath marks
-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.
+Breath marks are entered using @code{\breathe}:
-@lilypond[fragment,verbatim,center]
- \repeat "tremolo" 8 { c16 d16 }
- \repeat "tremolo" 4 { c16 d16 }
+@lilypond[fragment,relative]
+c'4 \breathe d4
@end lilypond
-@lilypond[fragment,verbatim,center]
- c'4:32
-@end lilypond
+Currently, only tick marks are supported, comma style breath marks are
+not. The grob for this object is called @code{Voice.BreathingSign}.
-@cindex --@@@code{-}@code{-}
+@refbugs
-@indexcode{__}
+ Currently, only tick marks are supported, comma style breath marks are
+not.
-@cindex extender
-@cindex hyphen
+@c . {Tempo}
+@node Tempo
+@subsection Tempo
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
-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{-}'.
+@cindex @code{\tempo}
+@example
+ \tempo @var{duration} = @var{perminute} @code{;}
+@end example
+Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
+output with 76 quarter notes per minute.
+
+@refbugs
+
+The tempo setting is not printed, but is currently only used in the MIDI
+output.
+
-@cindex ties
-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.
+@node Text spanner
+@subsection Text spanner
+@cindex Text spanner
-@lilypond[fragment,verbatim,center]
- e' ~ e' <c' e' g'> ~ <c' e' g'>
+Some textual indications, e.g. rallentando, accelerando, often extend
+over a many measures. This is indicated by following the text with a
+dotted line. You can create such texts in LilyPond using
+text spanners. The syntax is as follows:
+@example
+\spanrequest \start "text"
+\spanrequest \stop "text"
+@end example
+LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The
+string to be printed, as well as the style is set through grob
+properties.
+
+An application---or rather, a hack---is to fake octavation indications.
+@lilypond[fragment,relative,verbatim]
+ \relative c' { 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
-@cindex articulations
-@cindex scripts
+@c . {Ornaments}
+@node Ornaments
+@section Ornaments
+@cindex Ornaments
+@menu
+* Articulation::
+* Text scripts::
+* Grace notes::
+* Glissando ::
+* Dynamics::
+@end menu
+@c . {Articulation}
+@node Articulation
+@subsection Articulation
+@cindex Articulation
+
+@cindex articulations
+@cindex scripts
@cindex ornaments
A variety of symbols can appear above and below notes to indicate
name of the corresponding symbol appearing underneath.
@lilypond[]
-
\score {
< \notes {
+ \property Score.LyricSyllable \override #'font-family =
+#'typewriter
+ \property Score.LyricSyllable \override #'font-shape = #'upright
c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
c''-\thumb c''-\segno c''-\coda
}
- \context Lyrics \lyrics {
+ \context Lyrics \lyrics {
accent__ marcato__ staccatissimo__ fermata
stopped__ staccato__ tenuto__ upbow
downbow__ lheel__ rheel__ ltoe
indent = 0.0;
}
}
-
@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
-
-@lilypond[]
-
+To save typing work, some shorthands are available:
+@lilypond[singleline]
\score {
- \notes {
- \property Voice.TextScript \set #'font-style = #'typewriter
+ \notes \context Voice {
+ \property Voice.TextScript \set #'font-family = #'typewriter
+ \property Voice.TextScript \set #'font-shape = #'upright
c''4-._"c-." s4
c''4--_"c-{}-" s4
c''4-+_"c-+" s4
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;
}
}
-
@end lilypond
-Dynamic marks are specified by using an identifier after a note:
-`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
-The available dynamic marks are:
-@code{\ppp}@keyindex{ppp},
-@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
-@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
-@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
-@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
-@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
-@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
-@code{\rfz}@keyindex{rfz}.
-
-
-@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:
-
-@quotation
-
-@example
-c4-\textscript "6" "finger"
-c4-\textscript "foo" "normal"
-@end example
+@cindex fingering
-@end quotation
+Fingering instructions can also be entered in this shorthand.
+@lilypond[verbatim, singleline, fragment]
+ c'4-1 c'4-2 c'4-3 c'4-4
+@end lilypond
-This is equivalent to `@code{c4-6 c4-"foo"}'.
+@cindex @code{\script}
@cindex scripts
+@cindex superscript
+@cindex subscript
@example
-
- \script@keyindex{script} @var{alias}
+ \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
+Defines a script printing request. 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}.
+For information on how to add scripts, consult @file{scm/script.scm}.
-@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:
+@refbugs
-@lilypond[fragment,verbatim,center]
- f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
-@end lilypond
+All of these note ornaments appear in the printed output but have no
+effect on the MIDI rendering of the music.
+Unfortunately, there is no support adding fingering instructions or
+ornaments to individual note heads. Some hacks exist, though. See
+@file{input/test/script-horizontal.ly}.
-@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.
+@c . {Text scripts}
+@node Text scripts
+@subsection Text scripts
+@cindex Text scripts
-@lilypond[fragment,verbatim,center]
- c'' \< \! c'' d'' \decr e'' \rced
- < f''1 { s4 \< \! s2 \> \! s4 } >
+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:
+@code{c^"text"}. The text is typeset in italic by default.
+
+The amount of space taken by these indications by default does not
+influence, spacing, but setting @code{Voice.textNonEmpty} to true will
+take the widths into account. The identifier @code{\fattext} is defined
+in the standard includes.
+@lilypond[fragment,singleline,verbatim]
+\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
@end lilypond
+Text scripts are created in form of @code{Voice.TextScript} grobs.
-@example
+For purposes of defining identifiers, a more verbose form also exists:
- \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
+@example
+ \textscript @var{text}
@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"
-@end lilypond
+Defines a text to be printed over or under a note. @var{text} is a
+string or a markup text.
+@quotation
-The slur syntax with parentheses is a shorthand for this.
+@example
+foo = \textscript #'(finger "6")
+ [..]
+c4-\foo
+@end example
+@end quotation
-@node stem tremolo
-@section stem tremolo
-@cindex tremolo marks
+This is equivalent to @code{c4-6 c4-"foo"}.
-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.
-@lilypond[verbatim,fragment,center]
- c'2:8 c':32
-@end lilypond
+@c . {Grace notes}
+@node Grace notes
+@subsection Grace notes
-@node Compound music expressions
-@section Compound music expressions
-@cindex compound music expressions
-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
-@cindex context selection
-@c @keyindex{context}
+@cindex Grace music
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
+@cindex @code{graceAlignPosition}
+Grace notes are ornaments that are written out, but do not take up any
+logical time in a measure. LilyPond has limited support for grace notes.
+The syntax is as follows.
@example
- \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+ \grace @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.
-
-@cindex input modes
-
-@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
+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{Stem}.@code{flag-style} property.
+@lilypond[fragment,verbatim]
+\relative c'' {
+ \grace c8 c4 \grace { [c16 c16] } c4
+ \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4
+}
+@end lilypond
+At present, nesting @code{\grace} notes is not supported. The following
+may cause run-time errors:
@example
-
- \sequential@keyindex{sequential}
- @code{@{} @var{musicexprlist} @code{@}}
+ @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.
-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:
-
-@example
- @code{@{} @var{musicexprlist} @code{@}}
-@end example
+A grace note expression has duration 0; the next real note is assumed to
+be the main note. If you want the note to appear after the main note,
+set @code{Voice.graceAlignPosition} to @code{1}.
+@refbugs
+The present implementation of grace notes is not robust and generally
+kludgy. We expect it to change after LilyPond 1.4. Syntax changes might
+also be implemented.
-@cindex simultaneous music
-@indexcode{<}
-@indexcode{>}
-@example
+@menu
+* Glissando ::
+* Dynamics::
+@end menu
- \simultaneous@keyindex{simultaneous}
- @code{@{} @var{musicexprlist} @code{@}}
-@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:
-@example
+@c . {Glissando}
+@node Glissando
+@subsection Glissando
+@cindex Glissando
- @code{<} @var{musicexprlist} @code{>}
-@end example
+@cindex @code{\glissando}
-If you try to use a chord as the first thing in your score, you might
-get multiple staffs instead of a chord.
+A glissando line can be requested by attaching a @code{\glissando} to a
+note:
-@lilypond[verbatim,center]
- \score {
- \notes <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
+@lilypond[fragment,relative,verbatim]
+ c'' \glissando c'
@end lilypond
-This happens because the chord is interpreted by a score context.
-Each time a note is encountered a default Voice context (along with a
-Staff context) is created. The solution is to explicitly instantiate
-a Voice context:
-
-@lilypond[verbatim,center]
- \score {
- \notes\context Voice <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
-@end lilypond
+@refbugs
+Printing of an additional text (such as @emph{gliss.}) must be done
+manually.
-@node relative
-@section relative
-@cindex relative pitch specification
+@c . {Dynamics}
+@node Dynamics
+@subsection Dynamics
+@cindex Dynamics
-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.
-@example
- \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
-@end 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}
-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.
+Absolute 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}.
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c d e f g a b c c,
- }
+@lilypond[verbatim,singleline,fragment,relative]
+ c''\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
+ c2\sf c\rfz
@end lilypond
-And octave changing marks are used for intervals greater than a fourth.
+@cindex Crescendo and Decrescendo
+@cindex crescendo
+@cindex @code{\cr}
+@cindex @code{\rc}
+@cindex @code{\decr}
+@cindex @code{\rced}
+@cindex @code{\<}
+@cindex @code{\>}
+@cindex @code{\"!}
+
+
+A crescendo mark is started with @code{\cr} and terminated with
+@code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
+started with @code{\decr} and terminated with @code{\rced}. There are
+also shorthands for these marks. A crescendo can be started with
+@code{\<} and a decrescendo can be started with @code{\>}. Either one
+can be terminated with @code{\!}. Note that @code{\!} must go before
+the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
+after the last note. Because these marks are bound to notes, if you
+want to get several marks during one note, you must use spacer notes.
@lilypond[fragment,verbatim,center]
- \relative c'' {
- c g c f, c' a, e'' }
+ c'' \< \! c'' d'' \decr e'' \rced
+ < f''1 { s4 s4 \< \! s4 \> \! s4 } >
@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.
+You can also use a text saying @emph{cresc.} instead of hairpins. Here
+is an example how to do it:
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.crescendoText = "cresc."
+ \property Voice.crescendoSpanner = #'dashed-line
+ a''2\mf\< a a \!a
}
-@end lilypond
+@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}.
+@refbugs
+
+When using spacer notes to subdivide note dynamics and @code{linewidth =
+-1}, starting a hairpin on the first spacer note (the one coinciding
+with the real note) exposes an embarassing bug.
+
+
+
+@c . {Repeats}
+@node Repeats
+@section Repeats
+
+
+@cindex repeats
+@cindex @code{\repeat}
+
+To specify repeats, use the @code{\repeat} keyword. Since repeats
+should work differently when played or printed, there are a few
+different variants of repeats.
+
+@table @asis
+@item unfolded
+Repeated music is fully written (played) out. Useful for MIDI
+output.
+
+@item volta
+This is the normal notation: Repeats are not written out, but
+alternative endings (voltas) are printed, left to right.
+
+@item folded
+Alternative endings are written stacked. Which is unfortunately not
+practical for anything right now.
+
+@item tremolo
+Make tremolo beams.
+
+@item percent
+Make measure repeats. These look like percent signs.
-It is strongly recommended to use relative pitch mode: less work,
-less error-prone, and more readable.
+@end table
+@menu
+* Repeat syntax::
+* Manual repeat commands::
+* Tremolo repeats::
+* Tremolo subdivision::
+* Measure repeats::
+@end menu
+@node Repeat syntax
+@subsection Repeat syntax
-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 syntax for repeats is
@example
+ \repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
- @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
+If you have alternative endings, you may add
+@cindex @code{\alternative}
+@example
+ \alternative @code{@{} @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @code{@}}
@end example
+where each @var{alternative} is a music expression.
-@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{.}').
+Normal notation repeats are used like this:
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 { c'4 d' e' f' }
+ \repeat volta 2 { f' e' d' c' }
+@end lilypond
-@quotation
+With alternative endings:
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
+@end lilypond
+
+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.}
@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
- }
-}
+ c'1
+ \repeat fold 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
@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
+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]
-\transpose c'' {
- \chords {
- c1:m c:min7 c:maj c:aug c:dim c:sus
+\context Staff {
+ \relative c' {
+ \partial 4;
+ \repeat volta 3 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b2. } }
}
}
-
@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.
-@lilypond[fragment,verbatim,center]
- \transpose c'' {
- \chords {
- c1^3 c:7^5.3 c:8^7
- }
- }
-@end lilypond
+@refbugs
-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.
+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, e.g. using a bar-check (See @ref{Bar check}),
+@code{Score.measurePosition} or @code{\partial}. We hope to fix this
+after 1.4.
-@lilypond[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/e c/g c:7/e
- }
- }
+It is possible to nest @code{\repeat}, although it probably is only
+meaningful for unfolded repeats.
-@end lilypond
+@node Manual repeat commands
+@subsection Manual repeat commands
-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.
+@cindex @code{repeatCommands}
-@lilypond[fragment,verbatim,center]
- \transpose c''' {
- \chords {
- c1 c/+c c/+g c:7/+b
- }
- }
+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
-@end lilypond
+@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
-Throughout these examples, chords have been shifted around the staff
-using @code{\transpose}.
+@lilypond[verbatim, fragment]
+ c''4
+ \property Score.repeatCommands = #'((volta "93") end-repeat)
+ c4 c4
+ \property Score.repeatCommands = #'((volta #f))
+ c4 c4
+@end lilypond
-You should not combine @code{\relative} with named chords.
+@node Tremolo repeats
+@subsection Tremolo repeats
+@cindex tremolo beams
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
+@lilypond[verbatim,center,singleline]
+\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
+ }
+}
+@end lilypond
-@cindex tuplets
+@refbugs
-Tuplets are made out of a music expression by multiplying their
-duration with a fraction.
-@example
+At present, the spacing between tremolo beams is not regular, since the
+spacing engine does not notice that not all notes are printed.
- \times@keyindex{times} @var{fraction} @var{musicexpr}
-@end example
+@node Tremolo subdivision
+@subsection Tremolo subdivision
+@cindex tremolo marks
+@cindex @code{tremoloFlags}
-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:
+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 then the last value (stored in
+@code{Voice.tremoloFlags}) is used.
-@lilypond[fragment,verbatim,center]
- g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@lilypond[verbatim,fragment,center]
+ c'2:8 c':32
@end lilypond
+Using this mechanism pays off when you entering many tremolos, since the
+default argument saves a lot of typing.
+@refbugs
-@cindex grace notes
-
-@example
-
- \grace@keyindex{grace} @var{musicexpr}
-@end example
+Tremolos in this style do not carry over into the MIDI output.
-A grace note expression has duration 0; the next real note is
-assumed to be the main note.
-You cannot have the grace note after the main note, in terms of
-duration, and main notes, but you can typeset the grace notes to the
-right of the main note using the property
-@code{graceAlignPosition}@indexcode{graceAlignPosition}.
+@node Measure repeats
+@subsection Measure repeats
-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.
+@cindex percent repeats
+@cindex measure repeats
-@quotation
+In the @code{percent} style, a note pattern can be repeated. It is
+printed once, and then the pattern is replaced with a special sign.
-@lilypond[fragment,verbatim]
-\relative c'' {
- \grace c8 c4 \grace { [c16 c16] } c4
- \grace { \property Grace.flagStyle = "" c16 } c4
+@lilypond[verbatim,singleline]
+ \context Voice { \repeat "percent" 4 { c'4 }
+ \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
}
-
@end lilypond
-@end quotation
-At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
+@refbugs
-@example
+You can not nest percent repeats, filling in the first measure with
+slashes, and repeating that measure with percents.
- @code{\grace @{ \grace c32 c16 @} c4}
-@end example
+@node Rhythmic music
+@section Rhythmic music
-may result in run-time errors of LilyPond. Since the meaning of such
-a construct is unclear, we don't consider this a loss. Similarly,
-juxtaposing two @code{\grace} sections is syntactically valid, but
-makes no sense and may cause runtime errors.
-Ending a staff or score with grace notes may also generate a run-time
-error, since there will be no main note to attach the grace notes to.
+@menu
+* Rhythmic staffs::
+@end menu
+@node Rhythmic staffs
+@subsection Rhythmic staffs
+Some times you might want to show only the rhythm of a melody. This can
+be done with the rhythmic staff. All pitches of notes on such a staff
+are squashed, and the staff itself looks has a single staff line:
-@node Repeats
-@section Repeats
-@cindex repeats
+@lilypond[fragment,relative ]
+ \context RhythmicStaff {
+ \time 4/4;
+ c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
+ }
+@end lilypond
-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.
+@c . {Piano music}
+@node Piano music
+@section Piano music
-@table @samp
- @item unfolded
- Repeated music is fully written (played) out. Useful for MIDI
- output.
+Piano music is an odd type of notation: two staffs are largely
+independent, but sometimes voices can cross between the two staffs. The
+@code{PianoStaff} is especially built to handle this cross-staffing
+behavior. In this section we discuss the @code{PianoStaff} and some
+other pianistic peculiarities.
- @item volta
- This is the normal notation: Repeats are not written out, but
- alternative endings (voltas) are printed, left to right.
+@menu
+* Automatic staff changes::
+* Manual staff switches::
+* Pedals::
+* Arpeggio::
+* VoiceFollower::
+@end menu
- @item folded
- Alternative endings are written stacked, which is useful for
- lyrics.
-@end table
-The syntax for repeats is
+@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
-
- \repeat @var{variant} @var{repeatcount} @var{repeatbody}
+ \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
-If you have alternative endings, you may add
+Note how spacer rests are used to prevent the bottom staff from
+terminating too soon.
+
+
+@node Manual staff switches
+@subsection Manual staff switches
+
+@cindex manual staff switches
+@cindex staff switch, manual
+Voices can be switched between staffs manually, using the following command:
@example
+ \translator Staff = @var{which} @var{music}
+@end example
+The string @var{which} is the name of the staff. Typically it is
+@code{"up"} or @code{"down"}.
- \alternative@keyindex{alternative}
- @code{@{} @var{alternative1}
- @var{alternative2}
- @var{alternative3} @dots{} @code{@}}
+Formally, this construct is 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.
+
+@cindex @code{\translator}
+@example
+ \translator @var{contexttype} = @var{name}
@end example
-where each @var{alternative} is a Music expression.
-Normal notation repeats are used like this:
+@c . {Pedals}
+@node Pedals
+@subsection Pedals
+@cindex Pedals
-@quotation
+Piano pedal instruction can be expressed using
+@code{\sustainDown}, @code{\sustainUp}, @code{\unaChorda},
+@code{\treChorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 { c'4 d' e' f' }
- \repeat volta 2 { f' e' d' c' }
+These identifiers are shorthands for spanner commands of the types
+@code{Sustain}, @code{UnaChorda} and @code{Sostenuto}:
+@lilypond[fragment,verbatim]
+c''4 \spanrequest \start "Sustain" c''4 c''4 \spanrequest \stop "Sustain"
@end lilypond
-@end quotation
-With alternative endings:
+The symbols that are printed can be modified by setting
+@code{pedal@var{X}Strings}, where @var{X} is one of the pedal
+types. Refer to the generated documentation for more information.
-@quotation
+@refbugs
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
-@end lilypond
-@end quotation
+Currently, brackets are not supported, only text markings (ie. *Ped
+style).
-Folded repeats look like this:@footnote{Folded repeats offer little
-more over simultaneous music. However, it is to be expected that
-more functionality -- especially for the MIDI backend -- will be
-implemented.}
-@quotation
+@c . {Arpeggio}
+@node Arpeggio
+@subsection Arpeggio
+@cindex Arpeggio
-@lilypond[fragment,verbatim]
- c'1
- \repeat fold 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
+@cindex broken arpeggio
+@cindex @code{\arpeggio}
-@end lilypond
-@end quotation
+You can specify an arpeggio sign on a chord by attaching an
+@code{\arpeggio} to a note of the chord.
-@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 } }
- }
-}
+@lilypond[fragment,relative,verbatim]
+ \context Voice <c'\arpeggio e g c>
+@end lilypond
+
+When an arpeggio crosses staffs in piano music, you attach an arpeggio
+to the chords in both staffs, and set
+@code{PianoStaff.connectArpeggios}.
+@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
-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.
+This command creates @code{Arpeggio} grobs.
-@quotation
+@refbugs
-@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 } }
- }
-}
+ It is not possible to mix
+connected arpeggios and unconnected arpeggios at the same time.
+
+
+@c . {VoiceFollower}
+@node VoiceFollower
+@subsection VoiceFollower
+@cindex follow voice
+@cindex staff switching
+@cindex cross staff
+
+@cindex @code{followVoice}
+
+Whenever a voice switches to another staff a line connecting the notes
+can be printed automatically. This is enabled if the property
+@code{PianoStaff.followVoice} is set to true:
+
+@lilypond[fragment,relative,verbatim]
+ \context PianoStaff <
+ \property PianoStaff.followVoice = ##t
+ \context Staff \context Voice {
+ c'1
+ \translator Staff=two
+ b2 a
+ }
+ \context Staff=two {\clef bass; \skip 1*2;}
+ >
@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.
+@c . {Lyrics}
+@node Lyrics
+@section Lyrics
+@menu
+* Lyrics mode::
+* Printing lyrics::
+* Automatic syllable durations::
+* More stanzas::
+@end menu
-@node transpose
-@section transpose
-@cindex transposition of pitches
+@c . {Lyrics mode}
+@node Lyrics mode
+@subsection Lyrics mode
+@cindex Lyrics mode
-A music expression can be transposed with
-@code{\transpose}@keyindex{transpose}. The syntax is
+To print lyrics in LilyPond, you must first make a music expression from
+the lyric text. When they're in a music expression, that music
+expression can be printed by selecting an appropriate context. We shall
+discuss lyric printing in this order.
-@example
- \transpose @var{pitch} @var{musicexpr}
-@end example
+@cindex lyric mode
+@cindex @code{\lyrics}
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
+You can enter lyrics in a special input mode of LilyPond. This mode is
+called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
+The purpose of this mode is that you can enter lyrics as plain text,
+punctuation and accents without any hassle.
-@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.
+The precise definition of this mode is in @ref{Lyrics mode
+definition}. The definition itself 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.
-@quotation
+Syllables are entered like notes, with pitches replaced by text. For
+example, @code{Twin- kle twin- kle} enters four syllables. Note that
+the hyphen has no special meaning for lyrics, and does not introduce
+special symbols.
-@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 }
-}
+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.
+@c . {Printing lyrics}
+@node Printing lyrics
+@subsection Printing lyrics
+@cindex lyrics
+
+Normally, you will want to have notes and syllables matched
+automatically. This is accomplished using @code{\addlyrics}, which is
+documented in @ref{Automatic syllable durations}. Setting
+@code{automaticMelismata} in the melody staff, will cause slurs to be
+interpreted as melismata. Lyric syllables must be interpreted within a
+@code{Lyrics} context in order to printing them.
+
+@lilypond[verbatim,singleline]
+\addlyrics \notes \relative c' {
+ \time 7/4;
+ \property Staff.automaticMelismata = ##t
+ d'2 c4 b2 a2
+ b2 c4 b4 () a4 g2 }
+ \context Lyrics \lyrics {
+ Join us now and
+ share the so -- ftware; }
@end lilypond
-@end quotation
-If you want to use both @code{\transpose} and @code{\relative}, then
-you must use @code{\transpose} first. @code{\relative} will have no
-effect music that appears inside a @code{\transpose}.
+@cindex extender
+@cindex lyric extender
+@cindex melisma
+As you can see, extender lines are entered as @code{__}. 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{_}).
+@cindex hyphen
-@cindex automatic lyric durations
+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.
-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
+@cindex Lyric hyphen
-@example
+@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}. 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
-You should use a single rhythm melody, and single rhythm lyrics (a
-constant duration is the obvious choice). If you do not, you will get
-undesired effects when using multiple stanzas:
+If you want the lyric lines to be above the melody staff, or in some
+other, more complex configuration, then build that configuration first
+using simultaneous music, and use @code{\addlyrics} after that.
+
+@lilypond[verbatim, singleline]
+\notes <
+ \context Lyrics = LA { s1 }
+ \context Staff = SA { s1 }
+ \addlyrics
+ \context Staff = SA \relative c' { c4 e g g }
+ \context Lyrics = LA \lyrics { geen ge -- don -- der } >
+@end lilypond
-@quotation
+For @code{\addlyrics} you should use a single rhythm melody, and single
+rhythm lyrics (a constant duration is the obvious choice). If you do
+not, you can get undesired effects when using multiple stanzas:
@lilypond[verbatim,fragment]
\addlyrics
\context Lyrics \lyrics
< { do4 re mi fa }
{ do8 re mi fa } >
-
@end lilypond
-@end quotation
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
+LilyPond has support for both entering and printing chords. Chords are
+a harmonic device that is characterized by a set of pitches. It is
+something different from simultaneous music, although you can express a
+chord using simultaneous music. In fact, chords are internally stored as
+simultaneous music expressions. This means you can enter chords by name,
+and print them as note head, or enter as notes and print as chord names:
- 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
+@lilypond[verbatim,singleline]
+twoWays = \notes \transpose c'' {
+ \chords {
+ c1 f:sus4 bes/f
+ }
+ <c e g>
+ <f bes c'>
+ <f bes d'>
+ }
- @quotation
+\score {
+ < \context ChordNames \twoWays
+ \context Staff \twoWays > }
+@end lilypond
-@example
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end example
+Note that this example also shows that the LilyPond chord does not
+attempt to be intelligent, if you enter @code{f bes d}, it does no
+attempt to find out whether it this is an inversion.
- @end quotation
+@menu
+* Chords mode::
+* Printing named chords::
+@end menu
- 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.
+@c . {Chords mode}
+@node Chords mode
+@subsection Chords mode
+@cindex Chords mode
- @item (an as yet unidentified ambiguity :-)
-@end itemize
+Chord mode is a mode where you can input sets of pitches using common
+names. It 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).
+
+Dashes and carets are used to indicate chord additions and subtractions,
+so articulation scripts can not be entered in Chord mode.
+
+The syntax for named chords is as follows:
+@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{.}).
+
+Throughout these examples, chords have been shifted around the staff
+using @code{\transpose}.
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1 c:3- c:7 c:8
+ c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
+ }
+}
+@end lilypond
-@node Notation conversion specifics
-@section Notation conversion specifics
+@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.
-@node Automatic Beaming
-@section Automatic Beaming
-@cindex automatic beam generation
-@cindex autobeam
+@lilypond[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1:m c:min7 c:maj c:aug c:dim c:sus
+ }
+}
+@end lilypond
+
-@c beamAuto vs autoBeam ?
+Chord subtractions are used to eliminate notes from a chord. The
+notes to be subtracted are listed after a @code{^} character,
+separated by dots.
-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.
+@lilypond[fragment,verbatim,center]
+ \transpose c'' {
+ \chords {
+ c1^3 c:7^5.3 c:8^7
+ }
+ }
+@end lilypond
+@cindex @code{/}
+Chord inversions can be specified by appending `@code{/}' and the name
+of a single note to a chord. In a chord inversion, the inverted note is
+transposed down until it is the lowest note in the chord. If the
+specified note is not in the chord, a warning will be printed.
-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
-@end quotation
+@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
-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.
-For example, to specify beam endings for beams that contain 32nd notes,
-you would use @code{(end * * 1 32)}.
+@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 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} context.
+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>
}
\score {
\notes<
- \context ChordNamesVoice \scheme
+ \context ChordNames \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:
+You can make the chord changes stand out by setting property
+@code{ChordNames.chordChanges} to true. This will only display chord
+names when there's a change in the chords scheme and at the start of the
+line.
-@c bug
-@quotation
@lilypond[verbatim]
scheme = \chords {
-% \property ChordNames.chordChanges = ##t
c1:m \break c:m c:m c:m d
}
\score {
\notes <
- \context ChordNamesVoice \scheme
+ \context ChordNames {
+ \property ChordNames.chordChanges = ##t
+ \scheme }
\context Staff \transpose c'' \scheme
- >
- \paper{
- linewidth = 40 * \staffspace;
- }
-}
+ > }
@end lilypond
-@end quotation
-
+LilyPond examines chords specified as lists of notes to determine a name
+to give the chord. LilyPond will not try to identify chord inversions or
+added base, which may result in strange chord names when chords are
+entered as a list of pitches:
-LilyPond examines chords specified as lists of notes to determine a
-name to give the chord. LilyPond will not try to
-identify chord inversions or added base, which may result in strange
-chord names when chords are entered as a list of pitches:
+[base vs. bass ?]
-@quotation
-@lilypond[verbatim,center]
+@lilypond[verbatim,center,singleline]
scheme = \notes {
<c'1 e' g'>
<e' g' c''>
\score {
<
- \context ChordNamesVoice \scheme
+ \context ChordNames \scheme
\context Staff \scheme
>
- \paper { linewidth = -1.; }
}
@end lilypond
-@end quotation
-To specify chord inversions, append @code{/<notename>}. To specify an
-added bass note, append @code{/+<notename}:
-@quotation
-@lilypond[verbatim,center]
-scheme = \chords {
- d1 d/a d/+gis
-}
+By default LilyPond uses chord name system proposed by Harald Banter
+(See @ref{Literature}). The system is is unambiguous and has a logical
+structure. Typical American style chord names may be selected by
+setting the @code{style} property of the @code{ChordNames.ChordName}
+grob to @code{'american}. Similarly @code{'jazz} selects Jazz
+chordnames.
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper { linewidth = -1.; }
-}
-@end lilypond
-@end quotation
+Routines that determine the names to be printed are written in Scheme,
+and may be customized by the user. The code can be found in
+@file{scm/chord-name.scm}.
-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}:
+[3 short examples showing differences between american, banter and jazz]
-@quotation
-@lilypond[verbatim]
-\include "english.ly"
+@node Writing parts
+@section Writing parts
-scheme = \chords {
- c % Major triad
- cs:m % Minor triad
- df:m5- % Diminished triad
- c:5^3 % Root-fifth chord
- c:4^3 % Suspended fourth triad
- c:5+ % Augmented triad
- c:2^3 % "2" chord
- c:m5-.7- % Diminished seventh
- c:7+ % Major seventh
- c:7.4^3 % Dominant seventh suspended fourth
- c:5+.7 % Augmented dominant seventh
- c:m5-.7 % "Half" diminished seventh
- c:5-.7 % Dominant seventh flat fifth
- c:5-.7+ % Major seventh flat fifth
- c:m7+ % Minor-major seventh
- c:m7 % Minor seventh
- c:7 % Dominant seventh
- c:6 % Major sixth
- c:m6 % Minor sixth
- c:9^7 % Major triad w/added ninth
- c:6.9^7 % Six/Nine chord
- c:9 % Dominant ninth
- c:7+.9 % Major ninth
- c:m7.9 % Minor ninth
-}
+Orchestral music involves some special notation, both in the full score,
+as in the individual parts. This section explains how to tackle common
+problems in orchestral music.
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper {
- \translator {
- \ChordNamesContext
- ChordName \override #'word-space = #1
- ChordName \override #'style = #'american
- }
- }
+
+@c . {Transpose}
+@menu
+* Rehearsal marks::
+* Bar numbers::
+* Instrument names::
+* Transpose::
+* Sound output for transposing instruments::
+* Multi measure rests::
+* Automatic part combining::
+* Hara-kiri staffs::
+@end menu
+
+@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
+
+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.
+
+@lilypond[fragment,verbatim]
+\relative c'' {
+ c1 \mark "A2";
+ c1 \mark ;
+ c1 \mark ;
+ c1 \mark "12";
+ c1 \mark #'(music "scripts-segno") ;
+ c1
}
@end lilypond
-@end quotation
-Similarly, Jazz style chord names are implemented as a variation on
-American style names:
-@quotation
-@lilypond[verbatim]
-scheme = \chords {
- % major chords
- c
- c:6 % 6 = major triad with added sixth
- c:maj % triangle = maj
- c:6.9^7 % 6/9
- c:9^7 % add9
-
- % minor chords
- c:m % m = minor triad
- c:m.6 % m6 = minor triad with added sixth
- c:m.7+ % m triangle = minor major seventh chord
- c:3-.6.9^7 % m6/9
- c:m.7 % m7
- c:3-.9 % m9
- c:3-.9^7 % madd9
-
- % dominant chords
- c:7 % 7 = dominant
- c:7.5+ % +7 = augmented dominant
- c:7.5- % 7b5 = hard diminished dominant
- c:9 % 7(9)
- c:9- % 7(b9)
- c:9+ % 7(#9)
- c:13^9.11 % 7(13)
- c:13-^9.11 % 7(b13)
- c:13^11 % 7(9,13)
- c:13.9-^11 % 7(b9,13)
- c:13.9+^11 % 7(#9,13)
- c:13-^11 % 7(9,b13)
- c:13-.9-^11 % 7(b9,b13)
- c:13-.9+^11 % 7(#9,b13)
-
- % half diminished chords
- c:m5-.7 % slashed o = m7b5
- c:9.3-.5- % o/7(pure 9)
-
- % diminished chords
- c:m5-.7- % o = diminished seventh chord
-}
+@node Bar numbers
+@subsection Bar numbers
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper {
- \translator {
- \ChordNamesContext
- ChordName \override #'word-space = #1
- ChordName \override #'style = #'jazz
- }
- }
-}
-@end lilypond
-@end quotation
+Bar numbers are printed at the start of the line by default. This is
+done by the @code{Bar_number_engraver} in the Score context.
+@refbugs
-@node lyricprint
-@section lyricprint
-@cindex lyrics
+It is currently not possible to make boxed bar numbers, or print them at
+regular intervals.
-@cindex printing!lyrics
+@node Instrument names
+@subsection Instrument names
-Lyric syllables must be interpreted within a @code{Lyrics} context
+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.
-@cindex context!Lyrics
- for printing them.
+@lilypond[verbatim,singleline]
+\score { \notes {
+ \property Staff.instrument = "ploink " { c''4 } }
+ \paper {
+ \translator { \StaffContext
+ \consists "Instrument_name_engraver"; } } }
+@end lilypond
-Here is a full example:
+This requires that you add the @code{Instrument_name_engraver} to the
+staff context.
-@quotation
-@lilypond[verbatim]
-\score {
- <
- \notes \transpose c'' {
- c d e c | c d e c |
- e f g2 | e4 f g2 \bar "|.";
- }
- \context Lyrics \lyrics {
- Va-4 der Ja- cob Va- der Ja- cob
- Slaapt gij nog?2 Slaapt4 gij nog?2
- }
- >
-}
-@end lilypond
-@end quotation
+@node Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
-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{_}').
+A music expression can be transposed with @code{\transpose}. The syntax
+is
+@example
+ \transpose @var{pitch} @var{musicexpr}
+@end example
-@quotation
+This means that middle C in @var{musicexpr} is transposed to
+@var{pitch}.
-@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 __
- }
- >
-}
+@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.
+@lilypond[fragment,verbatim]
+\context Staff {
+ \clef "F";
+ { \key e \major; c d e f }
+ \clef "G";
+ \transpose des'' { \key e \major; c d e f }
+ \transpose cis'' { \key e \major; c d e f }
+}
@end lilypond
-@end quotation
-
-If you want to 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:
+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
-@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
- }
- >
-}
+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 the
+@code{transposing} property. It does not affect printed output.
-@end lilypond
-@end quotation
+@cindex @code{transposing}
+@example
+ \property Staff.instrument = #"Cl. in B-flat"
+ \property Staff.transposing = #-2
+@end example
-@node Notation Contexts
-@section Notation Contexts
+@c . {Multi measure rests}
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex Multi measure rests
-@cindex notation contexts
+@cindex @code{R}
-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.
+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.
-A context is an object that holds the reading state of the
-expression; it contains information like
+@lilypond[fragment,verbatim]
+ \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
+@end lilypond
-@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
+Currently, there is no way to condense multiple rests into a single
+multimeasure rest.
-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 condensing rests
-Contexts associated with sheet music output are called @emph{notation
-contexts}, those for sound output are called playing contexts.
+@node Automatic part combining
+@subsection Automatic part combining
+@cindex automatic part combining
+@cindex part combiner
+
+Automatic part combining is used to merge two parts of music onto on
+staff in an intelligent way. It is aimed primarily at typesetting Hymns
+and orchestral scores. When the two parts are identical for a period of
+time, only one is shown. In places where the two parts differ, stem
+directions are set automatically. Also, soli and @emph{a due} parts can be
+identified and marke.
-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:
+The syntax for part combining is
@example
+ \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
+@end example
- @example
-\score @{ \notes < c4 > @}
-@end example
+where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
+combined into one context @var{context}. The names of the music
+expressions must start with the prefixes @code{one} and @code{two}.
-@end example
+[Name of music expressions? is that context name? ]
+
+The most useful function of the part combiner to combining threads into
+one voice, as common for wind parts in orchestral scores:
+
+@lilypond[verbatim,singleline,fragment]
+ \context Staff <
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ g a b r
+ }
+ \context Thread=two \relative c'' {
+ g r2 f4
+ }
+ >
+@end lilypond
+
+Notice that the first @code{g} appears only once, although it was
+specified twice (once in each Thread). Also note that stem, slur and tie
+directions are set automatically, depending whether there is a solo or
+unisono. The Thread called @code{one} always gets up stems, and "solo",
+while @code{two} always gets down stems and "Solo II".
+
+If you just want the splitting of Threads and setting of directions, and
+not the textual markings, you may set the property @var{soloADue} to
+false. This mode can be used to set hymns:
+
+@lilypond[verbatim,singleline,fragment]
+ \context Staff <
+ \property Staff.soloADue = ##f
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ b4 a c g
+ }
+ \context Thread=two \relative c'' {
+ d,2 a4 g'
+ }
+ >
+@end lilypond
-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.
+There are a number of other properties that you can use to tweak
+the behavior of part combining, refer to the automatically generated
+documentation. Look for @code{Thread_devnull_engraver}
+@code{Voice_devnull_engraver} and @code{A2_engraver}.
+@refbugs
+
+In @code{soloADue} mode, when the two voices play the same notes on and
+off, the part combiner may typeset @code{a2} more than once in a
+measure.
+
+@lilypond[fragment,singleline]
+ \context Staff <
+ \context Voice=one \partcombine Voice
+ \context Thread=one \relative c'' {
+ c b c b c a c a
+ }
+ \context Thread=two \relative c'' {
+ b b b b f a f a
+ }
+ >
+@end lilypond
-@cindex context
+@cindex @code{Thread_devnull_engraver}
+@cindex @code{Voice_engraver}
+@cindex @code{A2_engraver}
-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.
+@node Hara-kiri staffs
+@subsection Hara-kiri staffs
-If a context of the specified type and name can not be found, a new
-one is created. For example,
+In orchestral scores, staffs that only have rests are usually removed.
+This saves some space. LilyPond also supports this through the
+hara-kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide
+of the Japanese Samourai warriors.} staff. This staff commits suicide
+when it finds itself to be empty after the line-breaking process---note
+that it will not disappear when it contains normal rests, you must use
+multi measure rests.
-@quotation
+The hara kiri staff is specialized version of the Staff context. It is
+available as the context identifier @code{\HaraKiriStaffContext}.
+Observe how the second staff in this example disappears in the second
+line.
@lilypond[verbatim]
-\score {
- \notes \relative c'' {
- c4 <d4 \context Staff = "another" e4> f
+\score {
+ \notes \relative c' <
+ \context Staff = SA { e4 f g a \break c1 }
+ \context Staff = SB { c4 d e f \break R1 }
+ >
+ \paper {
+ linewidth = 6.\cm ;
+ \translator { \HaraKiriStaffContext }
}
}
+@end lilypond
+
+
+
+@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.
+
+@lilypond[verbatim]
+\score {
+ \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
-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.
+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 @emph{editio vaticana} dating back to the beginning of
+the 20th century.
-Almost all music expressions inherit their interpretation context
-from their parent. In other words, suppose that the syntax for a
-music expression is
+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}.
@example
+\paper @{
+ \translator @{
+ \StaffContext
+ \consists Custos_engraver;
+ Custos \override #'style = #'mensural;
+ @}
+@}
+@end example
- \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
+The property can also be set locally, for example in a @code{\notes}
+block:
+
+@example
+\notes @{
+ \property Staff.Custos \override #'style = #'vaticana
+ c'1 d' e' d' \break c' d' e' d'
+@}
@end example
-When the interpretation of this music expression starts, the context
-for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
-expression.
+@c . {Tuning output}
+@node Tuning output
+@section Tuning output
-Lastly, you may wonder, why this:
+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. In this section we discuss
+ways to do just that.
-@quotation
+Notation output is specified in so called grobs (graphic objects). Each
+grob carries with it a set of properties (grob properties) specific to
+that object. For example, a stem grob has properties that specify its
+direction, length and thickness.
-@example
-\score @{
- \notes \relative c'' @{
- c4 d4 e4
- @}
-@}
-@end example
-@end quotation
+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 temporarily
+change the definition of a certain type of grob, thus affecting a whole
+set of objects. Second, you can select one specific object, and set a
+grob property.
-doesn't result in this:
+@menu
+* Tuning groups of grobs ::
+* Tuning per grob ::
+* What to tune?::
+* Font selection::
+* Text markup::
+@end menu
-@lilypond[]
+@node Tuning groups of grobs
+@subsection Tuning groups of grobs
- \score {
- \notes \relative c'' {
- <c4> <d4> <e4>
- }
- }
+@cindex grob description
+
+A grob definition is a Scheme 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 \override #'meta = #'((interfaces . ())) c'4
@end lilypond
-For the @code{c4}, a default @code{Staff} (with a contained
-@code{Voice}) context is created. After the @code{c4} ends, no
-music refers to this default staff, so it would be ended, with the
-result shown. To prevent this inconvenient behavior, the context to
-which the sequential music refers is adjusted during the
-interpretation. So after the @code{c4} ends, the context of the
-sequential music is also the default @code{Voice} context.
-The @code{d4} gets interpreted in the same context
-as @code{c4}.
+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.
-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.
+@cindex \override
+@cindex \revert
+@cindex \set
-Properties can be preset within the @code{\translator} block
-corresponding to the appropriate context. In this case, the syntax
-is
+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.
-@example
- @var{propname} @code{=} @var{value}
-@end example
+@lilypond[verbatim]
+c'4 \property Voice.Stem \override #'thickness = #4.0
+c'4 \property Voice.Stem \revert #'thickness
+c'4
+@end lilypond
-This assignment happens before interpretation starts, so a
-@code{\property} expression will override any predefined settings.
+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 for overriding automatic
+beaming 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}.
+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.
-@mbinclude properties.itely
+If balancing them is too much work, use the @code{\set} shorthand. It
+performs a revert followed by an override:
+@example
+\property Voice.Stem \set #'thickness = #2.0
+@end example
-@node Page layout
-@section Page layout
+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.
-@subsection Paper block
+If you want to be
+Correct nesting of @code{\override}, @code{\set}, @code{\revert} is as
+follows
-The most important output definition is the @code{\paper} block, for
-music notation. The syntax is
+@example
+\override \set \set \set \set
+\revert
+@end example
+This is always correct, but if you know the default value, you can also use
@example
- @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
+\set \set \set \set
+\set @var{to default value}
@end example
-where each of the items is one of
+If there is no default (i.e. by default, the grob property is unset),
+then you can use
+@example
+\set \set \set \set \set
+\revert
+@end example
-@itemize @bullet
- @item An assignment. The assignment must be terminated by a
- semicolon.
- @item A context definition. See section @ref{contextdefs} for
- more information on context definitions.
+@refbugs
-@ignore
+LilyPond will hang or crash if @var{value} contains cyclic references.
+The backend is not very strict in type-checking grob properties. If you
+@code{\revert} properties that are expected to be set by default,
+LilyPond may crash.
- FIXME
- @item
-
- A margin shape declaration. The syntax is
+@node Tuning per grob
+@subsection Tuning per grob
- @example
+@cindex \outputproperty
- \shape @var{indent1}@code{,} @var{width1}@code{,}
- @var{indent2}@code{,} @var{width2} @dots{} @code{;}
- @end example
+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 function taking a grob 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}.
- @keyindex{shape}
+You will need to combine this statement with @code{\context} to select
+the appropriate context to apply this to.
- 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
+If possible, avoid this feature: the semantics are not very clean, and
+the syntax and semantics are up for rewrite.
- @item \stylesheet declaration. Its syntax is
- @example
- \stylesheet @var{alist}
- @end example
+Here are some random examples:
- See @file{font.scm} for details of @var{alist}.
-@end itemize
+@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
-@subsection Paper variables
+@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-grob-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
-The paper block has some variables you may want to use or change:
-@table @samp
- @item @code{indent}@indexcode{indent}
- The indentation of the first line of music.
- @item @code{staffspace}@indexcode{staffspace}
- The distance between two staff lines, calculated from the center
- of the lines. You should use either this or @code{rulethickness}
- as a unit for distances you modify.
-
- @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}
- Sets the total height of the music on each page. Only used by
- ly2dvi.
+@node What to tune?
+@subsection What to tune?
- @item @code{interscoreline}@indexcode{interscoreline}
- Sets the spacing between the score lines. Defaults to 16 pt.
+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.).
- @item @code{interscorelinefill}@indexcode{interscorelinefill}
- If set to a positive number, the distance between the score
- lines will stretch in order to fill the full page. In that
- case @code{interscoreline} specifies the minimum spacing.
- Defaults to 0.
+Grob properties are tied directly to the implementation of LilyPond, and
+they are thus a moving target. Documentation of such variables are part
+of the generated documentation: this documentation is generated from the
+sourcecode of lily for each version, so it is usually mch more up to
+date than this manual. It should be available from the same place where
+you got this manual.
- @item @code{stafflinethickness}@indexcode{stafflinethickness}
- Determines the thickness of staff lines, and also acts as a scaling
- parameter for other line thicknesses.
-@end table
+To decide how to tune a grob, you need to find the following information
+@itemize @bullet
+@item
+which grob to modify
+@item
+which property to modify
+@item
+which context the grob comes from.
+@end itemize
+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.
-@subsection Line breaks
+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.
-@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.
+@node Font selection
+@subsection Font selection
-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 "";}.
+Most graphics in LilyPond are composed of characters of fonts. You can
+alter the characteristics of the font by setting certain grob
+properties. The mechanism that is used for this resembles LaTeX's New
+Font Selection Scheme. Within this scheme, a font is entirely
+characterized by its font name.
-@subsection Page breaks
+For each grob that uses fonts (in other words, each grob that supports
+@code{font-interface}) a font-name must be selected before it can be
+printed. The font name is selected by looking at a number of grob
+properties:
-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}
+@table @code
+@item font-family
+ The general class of the typeface. Supported are roman (Computer
+Modern), braces (for piano staff braces), music (the standard music
+font), dynamic (font for dynamic signs) and typewriter
+@item font-shape
+ A symbol indicating the shape of the font, a finer gradation than
+ font-family. Choices are italic and upright
+@item font-series
+ Symbol indicating the serie of the font. Series form a finer gradation
+ than font-shape. Choices are medium and bold.
-@cindex page breaks
-@cindex breaking pages
+@item font-relative-size
+ A number indicating the size relative the standard size. For example,
+ with 20pt staff height, relative size -1 corresponds to 16pt staff
+ height, and relative size +1 corresponds to 23 pt staff height.
+@item font-design-size
+A number indicating the design size of the font.
-@subsection Font size
+This is a feature of the Computer Modern Font: each point size has a
+slightly different design. Smaller design sizes are relatively wider,
+which enhances readability. Scalable type faces such TrueType and Adobe
+Type1 usually come as ``one design fits all sizes''.
-@cindex font size
-@cindex paper size
+@item font-name
+ The name of the font, without the design size, eg. @code{cmr},
+@code{cmti}, etc. Setting this overrides font-family, font-shape and
+font-series.
-The Feta font provides musical symbols at six different sizes. These
-fonts are 11 point, 13 point, 16 point, 20 point,
-23 point, and 26 point. The point size of a font is the
-height of the five lines in a staff when displayed in the font.
+@end table
-Definitions for these sizes are the files @file{paperSZ.ly}, where
-@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
-these files, the identifiers @code{paperEleven}, @code{paperThirteen},
-@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
-@code{paperTwentysix} are defined respectively. The default
-@code{\paper} block is also set.
+The font is selected by taking the first font that satisfies all
+qualifiers specified. You can override any of these fields through
+@code{\override} and @code{\revert}. The special value @code{*} matches
+any value for that qualifier.
-The font definitions are generated using a Scheme function. For more
-details, see the file @file{font.scm}.
+@example
+ \property Lyrics.LyricText \override #'font-series = #'bold
+ \property Lyrics.LyricText \override #'font-shape = #'*
+@end example
-@subsection paper size
+@cindex @code{font-style}
-@cindex paper size
-@cindex page size
+There are also pre-cooked font selection qualifiers. These are selected
+through the grob property @code{font-style}. For example, the style
+@code{finger} selects family @code{number} and relative size @code{-3}.
+Styles available include: volta, finger, tuplet, timesig, mmrest,
+script, large, Large and dynamic.
-To change the paper size, you must first set the
-@code{papersize}@indexcode{papersize} variable at top level. Set it to
-the strings @code{a4}, @code{letter}, or @code{legal}. After this
-specification, you must set the font as described above. If you want
-the default font, then use the 20 point font. The new paper size will
-not take effect if the font is not loaded and selected afterwards.
+The style sheets and tables for selecting fonts are located in
+@file{scm/font.scm}. Refer to this file for more information.
-@example
- papersize = "a4"
- \include "paper16.ly"
+@refbugs
- \score @{
- ...
- \paper @{ \paperSixteen @}
- @}
-@end example
+Relative size is not linked to any real size. There is no mechanism to
+select magnifications of fonts, meaning that you can not scale fonts
+continuoussly. There is no style sheet provided for other fonts besides
+the @TeX{} family.
-The file "paper16.ly" will now include a file named @file{a4.ly}, which
-will set the paper variables @code{hsize} and @code{vsize} (used by
-@code{ly2dvi})
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
-@node contextdefs
-@section contextdefs
-@cindex context definition
-@cindex translator definition
-@cindex engraver hacking
+@node Text markup
+@subsection Text markup
+@cindex text markup
+@cindex markup text
+LilyPond has an internal mechanism to typeset texts. You can
+form text markup expressions by composing scheme expressions
+in the following way.
+
+@lilypond[verbatim, singleline]
+ \relative c' {
+ \fatText
+ a^#"upright"
+ b_#'(bold "bold")
+ c^#'(italic "italic")
+ d_#'((bold italic) "ff")
+ e^#'(dynamic "ff")
+ f_#'(lines "one" (bold "two"))
+ g^#'(music "noteheads-2" "flags-u3")
+ }
+@end lilypond
-A notation contexts is defined by the following information
+Normally, the Scheme markup text is stored in the @code{text} property
+of a grob. Formally, it is defined as follows:
-@enumerate i
- @item A name.
+@example
+text: string | (head? text+)
+head: markup | (markup+)
+markup-item: property | abbrev
+property: (@var{key} . @var{value})
+abbrev: @code{rows lines roman music bold italic named super sub text}
+ @code{finger volta timesig mmrest mark script large Large dynamic}
+@end example
- @item The LilyPond modules that do the actual conversion of music to
- notation. Each module is a so-called
- @emph{engraver}
-@cindex engraver
-.
+The markup is broken down and converted into a list of grob properties,
+which are prepended to the 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
+@item finger
+ select fingering number fontstyle
+@item volta
+ select volta number fontstyle
+@item timesig
+ select time signature number fontstyle
+@item mmrest
+ select multi measure rest number fontstyle
+@item mark
+ select mark number fontstyle
+@item script
+ select scriptsize roman fontstyle
+@item large
+ select large roman fontstyle
+@item Large
+ select Large roman fontstyle
+@item dynamic
+ select dynamics fontstyle
+@end table
- @item How these modules should cooperate, i.e. which ``cooperation
- module'' should be used. This cooperation module is a special
- type of engraver.
+It is possible to use @TeX{} commands in the strings, 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.
- @item What other contexts the context can contain,
+@c . {Page layout}
+@node Page layout
+@section Page layout
+@cindex Page layout
- @item What properties are defined.
-@end enumerate
+@menu
+* Paper block::
+* Paper variables::
+* Font Size::
+* Paper size::
+* Line break::
+* Page break::
+@end menu
-A context definition has this syntax:
+@c . {Paper block}
+@node Paper block
+@subsection Paper block
+@cindex Paper block
-@example
+The most important output definition is the @code{\paper} block, for
+music notation. The syntax is
- \translator @code{@{}
- @var{translatorinit} @var{translatormodifierlist}
- @code{@}}
+@example
+ @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
@end example
-@var{translatorinit} can be an identifier or of the form
+where each of the items is one of
+
+@itemize @bullet
+ @item An assignment. The assignment must be terminated by a
+ semicolon.
+
+ @item A context definition. See @ref{Notation Contexts} for
+ more information on context definitions.
+
+ @item \stylesheet declaration. Its syntax is
+ @example
+ \stylesheet @var{alist}
+ @end example
+
+ See @file{scm/font.scm} for details of @var{alist}.
+ @item an \elementdescriptions declaration.
+ @example
+ \elementdescriptions @var{alist}
+ @end example
+ See @file{scm/grob-description.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 @code
+@cindex @code{indent}
+ @item @code{indent}
+ The indentation of the first line of music.
+@cindex @code{staffspace}
+
+ @item @code{staffspace}
+ The distance between two staff lines, calculated from the center
+ of the lines. If you want scale independent output, then you should
+use either this or @code{stafflinethickness}
+ as a unit for distances you modify.
+
+@cindex @code{linewidth}
+ @item @code{linewidth}
+ Sets the width of the lines.
+
+If set to a negative value, a single unjustified line is produced.
+@c rename to singleLinePaper ?
+The shorthand @code{\singleLine} defines a default paper block that
+produces a single line.
+
+@cindex @code{textheight}
+
+ @item @code{textheight}
+ Sets the total height of the music on each page. Only used by
+@code{ly2dvi}.
+
+@cindex @code{interscoreline}
+
+ @item @code{interscoreline}
+ Sets the spacing between systems.
+Not set by default.
+@cindex @code{interscorelinefill}
+
+
+
+ @item @code{interscorelinefill}
+ If set to a positive number, the distance between the score
+ lines will stretch in order to fill the full page. In that
+ case @code{interscoreline} specifies the minimum spacing.
+
+ Not set by default.
+
+
+@cindex @code{stafflinethickness}
+
+ @item @code{stafflinethickness}
+ Determines the thickness of staff lines, and also acts as a scaling
+ parameter for other line thicknesses.
+@end table
+
+
+
+@c . {Font size}
+@node Font Size
+@subsection Font size
+@cindex font size
+
+The Feta font provides musical symbols at six different sizes. These
+fonts are 11 point, 13 point, 16 point, 20 point,
+23 point, and 26 point. The point size of a font is the
+height of the five lines in a staff when displayed in the font.
+
+Definitions for these sizes are the files @file{paperSZ.ly}, where
+@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
+these files, the identifiers @code{paperEleven}, @code{paperThirteen},
+@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
+@code{paperTwentysix} are defined respectively. The default
+@code{\paper} block is also set.
+
+The font definitions are generated using a Scheme function. For more
+details, see the file @file{font.scm}.
+
+
+
+@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} variable at top level. Set it to
+the strings @code{a4}, @code{letter}, or @code{legal}. After this
+specification, you must set the font as described above. If you want
+the default font, then use the 20 point font. The new paper size will
+not take effect if the font is not loaded and selected afterwards.
@example
+ papersize = "a4"
+ \include "paper16.ly"
- \type @var{typename} @code{;}
+ \score @{
+ ...
+ \paper @{ \paperSixteen @}
+ @}
@end example
-@var{typename} is one of
+The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
+will set the paper variables @code{hsize} and @code{vsize} (used by
+@code{ly2dvi})
-@table @samp
- @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
- The standard cooperation engraver.
- @item @code{Score_engraver}@indexcode{Score_engraver}
- This is cooperation module that should be in the top level context.
- @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
- This is a special cooperation module (resembling
- @code{Score_engraver}) that is used to created an embedded
- `miniscore'.
-@end table
-@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.
+@c . {Line break}
+@node Line break
+@subsection Line break
- @item @var{propname} @code{=} @var{value} @code{;}
- A property assignment. It is allowed to use reals for
- @var{value}.
-@end itemize
+@cindex line breaks
+@cindex breaking lines
-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
+Line breaks are normally computed automatically. They are chosen such
+that the resulting spacing has low variation, and looks neither cramped
+nor loose.
-@quotation
+Occasionally you might want to override the automatic breaks; you can do
+this by specifying @code{\break}. 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 an invisible barline by entering @code{\bar "";}.
-@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
+Similarly, @code{\noBreak} forbids a line break at a certain point.
-@end quotation
+@cindex @code{\penalty}
+The @code{\break} and @code{\noBreak} commands are defined in terms of
+the penalty command:
+@example
+ \penalty @var{int} @code{;}
+@end example
-@cindex paper types, engravers, and pre-defined translators
+This encourages or discourages LilyPond to make a line break at this
+point.
+
+@refbugs
-Some pre-defined identifiers can simplify modification of
-translators. The pre-defined identifiers are:
+The scaling of the @code{\penalty} argument is not well-defined. The
+command is rather kludgy, and slated for rewriting.
-@table @samp
- @item @code{StaffContext}@indexcode{StaffContext}
- Default Staff context.
+@c . {Page break}
+@node Page break
+@subsection Page break
- @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
- Default RhythmicStaff context.
+@cindex page breaks
+@cindex breaking pages
- @item @code{VoiceContext}@indexcode{VoiceContext}
- Default Voice context.
- @item @code{ScoreContext}@indexcode{ScoreContext}
- Default Score context.
+Page breaks are normally computed by @TeX{}, so they are not under
+direct control of LilyPond. 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{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 can produce MIDI output. The performance lacks lots of
+interesting effects, such as swing, articulation, slurring, tieing,
+etc., but it is good enough for proof-hearing the music you enter.
-@quotation
+Dynamics and tempo changes are interpreted.
-@example
-\paper @{
- \translator @{
- \StaffContext
- \remove Some_engraver;
- \consists Different_engraver;
- @}
-@}
-@end example
+[TODO: mention volume control/Instrument Equaliser]
-@end quotation
-
-@node Sound output
-@section Sound output
+@refbugs
+
+It is currently not possible to use the percussion channel (generally
+channel 10 of a MIDI file).
+
+@menu
+* MIDI block::
+* MIDI instrument names::
+@end menu
+
+@c . {MIDI block}
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
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}.
+@node MIDI instrument names
+@subsection MIDI instrument names
-@cindex MIDI instrument names
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+@cindex @code{Staff.instrument}
-@node midilist
-@section midilist
+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 list in
+@ref{MIDI instruments}.
-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.
+@refbugs
-@c @quotation
+If the selected string does not exactly match, then LilyPond uses the
+default piano. It is not possible to select an instrument by number.
-@example
-"acoustic grand" "contrabass" "lead 7 (fifths)"
-"bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
-"electric grand" "pizzicato strings" "pad 1 (new age)"
-"honky-tonk" "orchestral strings" "pad 2 (warm)"
-"electric piano 1" "timpani" "pad 3 (polysynth)"
-"electric piano 2" "string ensemble 1" "pad 4 (choir)"
-"harpsichord" "string ensemble 2" "pad 5 (bowed)"
-"clav" "synthstrings 1" "pad 6 (metallic)"
-"celesta" "synthstrings 2" "pad 7 (halo)"
-"glockenspiel" "choir aahs" "pad 8 (sweep)"
-"music box" "voice oohs" "fx 1 (rain)"
-"vibraphone" "synth voice" "fx 2 (soundtrack)"
-"marimba" "orchestra hit" "fx 3 (crystal)"
-"xylophone" "trumpet" "fx 4 (atmosphere)"
-"tubular bells" "trombone" "fx 5 (brightness)"
-"dulcimer" "tuba" "fx 6 (goblins)"
-"drawbar organ" "muted trumpet" "fx 7 (echoes)"
-"percussive organ" "french horn" "fx 8 (sci-fi)"
-"rock organ" "brass section" "sitar"
-"church organ" "synthbrass 1" "banjo"
-"reed organ" "synthbrass 2" "shamisen"
-"accordion" "soprano sax" "koto"
-"harmonica" "alto sax" "kalimba"
-"concertina" "tenor sax" "bagpipe"
-"acoustic guitar (nylon)" "baritone sax" "fiddle"
-"acoustic guitar (steel)" "oboe" "shanai"
-"electric guitar (jazz)" "english horn" "tinkle bell"
-"electric guitar (clean)" "bassoon" "agogo"
-"electric guitar (muted)" "clarinet" "steel drums"
-"overdriven guitar" "piccolo" "woodblock"
-"distorted guitar" "flute" "taiko drum"
-"guitar harmonics" "recorder" "melodic tom"
-"acoustic bass" "pan flute" "synth drum"
-"electric bass (finger)" "blown bottle" "reverse cymbal"
-"electric bass (pick)" "skakuhachi" "guitar fret noise"
-"fretless bass" "whistle" "breath noise"
-"slap bass 1" "ocarina" "seashore"
-"slap bass 2" "lead 1 (square)" "bird tweet"
-"synth bass 1" "lead 2 (sawtooth)" "telephone ring"
-"synth bass 2" "lead 3 (calliope)" "helicopter"
-"violin" "lead 4 (chiff)" "applause"
-"viola" "lead 5 (charang)" "gunshot"
-"cello" "lead 6 (voice)"
-@end example
-@c @end quotation
-@node Pre-defined Identifiers
-@section Pre-defined Identifiers
-@cindex pre-defined identifiers
-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}.
+@c . {Music entry}
+@node Music entry
+@section Music entry
+@cindex Music entry
+@menu
+* Relative::
+* Bar check::
+* Point and click::
+@end menu
-@table @samp
- @item @code{\break}@keyindex{break}
- Force a line break in music by using a large argument for the
- keyword @code{\penalty}.
+One of the applications of LilyPond is to enter music from existing
+written or printed material. When you're doing this kind of copying
+work, you can easily make mistakes. This section deals with tricks and
+features that help you enter music, and find and correct mistakes.
- @item @code{\nobreak}@keyindex{nobreak}
- Prevent a line break in music by using a large negative argument
- for the keyword @code{\penalty}.
+@c . {Relative}
+@node Relative
+@subsection Relative
+@cindex Relative
+@cindex relative octave specification
- @item @code{\shiftOff}@keyindex{shiftOff}
- Disable horizontal shifting of note heads that collide.
+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.
- @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.
+@cindex @code{\relative}
+@example
+ \relative @var{startpitch} @var{musicexpr}
+@end example
- @item @code{\stemBoth}@keyindex{stemBoth}
- Allow stems, beams, and slurs to point either upwards or
- downwards, decided automatically by LilyPond.
+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 music that changes octave frequently is easy in relative mode.
+@lilypond[fragment,singleline,verbatim,center]
+ \relative c'' {
+ b c d c b c bes a
+ }
+@end lilypond
- @item @code{\stemDown}@keyindex{stemDown}
- Force stems, beams, and slurs to point down.
+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
- @item @code{\stemUp}@keyindex{stemUp}
- Force stems, beams and slurs to point up.
+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.
-@end table
+@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},
+@code{\chords} 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 . {Bar check}
+@node Bar check
+@subsection Bar check
+@cindex Bar check
+
+@cindex bar check
+@cindex @code{barCheckNoSynchronize}
+@cindex @code{|}
+
+
+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.
+
+A bar check is entered using the bar symbol, @code{|}
+
+
+
+@c . {Point and click}
+@node Point and click
+@subsection Point and click
+
+Point and click lets you find notes in the input by clicking on them in
+the Xdvi window. This makes it very easy to find input that causes some
+error in the sheet music.
+
+To use it, you need the following software
+
+@itemize
+@item
+@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
+Xdvi} version 22.36 or newer.
+
+ Note that most @TeX{} distributions ship with xdvik, which is a
+ different and less well maintained program. To find out which xdvi you
+ are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
+@item emacs
+@end itemize
+
+
+Add one these lines to the top of your .ly file. The first one is for
+line location only. The second one is more convenient, but requires
+patching @code{emacsclient}.
+
+@example
+#(set! point-and-click line-location)
+#(set! point-and-click line-column-location)
+@end example
+
+In the emacs startup file (usually @file{~/.emacs}), add the following
+@example
+(server-start)
+@end example
+
+If you want emacs to jump to the exact spot (and not just the line) on a
+click, you must enable column positioning. To do so, you need to patch
+emacsclient. Apply @file{emacsclient.patch} (included with the source
+package) to @file{emacsclient.c} and @file{server.el} from the emacs
+source code. Recompile and stick the recompiled emacsclient into a bin
+directory, and put @file{server.el} into a elisp directory
+(eg. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
+init file, before invoking server-start.
+
+@example
+ (setq load-path (cons "~/usr/share/emacs" load-path))
+@end example
+
+
+Xdvi must be configured to use the emacs editor. Before starting, set
+the environment variable @code{XEDITOR} to
+@example
+emacsclient --no-wait +%c:%l %f
+@end example
+Xdvi also must be configured to find the fonts. Refer to the
+xdvi documentation for more information.
+
+When viewing, control-mousebutton 1 will take you to the originating
+line and column. Control-mousebutton 2 will show all clickable boxes.
+
+@refbugs
+
+When you convert the TeX file to PostScript using dvips, dvips
+will complain about not finding @code{src:X:Y} files. Those complaints are
+harmless, and can be ignored.
+
+
+@node Interpretation context
+@section Interpretation context
+
+@menu
+* Notation Contexts::
+* Creating contexts::
+* Default contexts::
+* Context properties::
+* Changing context definitions::
+* Defining new contexts::
+@end menu
+
+
+@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 it prints
+"interpreting music"), the music expresiion in a @code{\score} block is
+interpreted in time order. This is the same order that humans hear and
+play music.
+
+During this interpretation, 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.
+
+@lilypond[verbatim,singleline]
+\score {
+ \notes \relative c'' {
+ c4 <d4 \context Staff = "another" e4> f
+ }
+}
+
+@end lilypond
+
+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:
+
+First, 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
+
+Second, sequential music follows the contexts of its
+``children''. Consider the following 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.
+
+Properties can be unset using the following expression:
+@example
+ \property @var{contextname}.@var{propname} \unset
+@end example
+
+This removes the definition of @var{propname} in @var{contextname}. If
+@var{propname} was not defined in @var{contextname} (but was inherited
+from a higher context), then this has no effect.
+
+
+@refbugs
+
+@code{\property \unset} is not the inverse of @code{\property \set}
+
+
+
+
+@c . {Context definitions}
+@node Changing context definitions
+@subsection Changing context definitions
+
+@cindex context definition
+@cindex translator definition
+
+The most common way to define a context is by extending an existing
+context. You can change an existing context from the paper block, by
+first initializing a translator with an existing context identifier:
+@example
+\paper @{
+ \translator @{
+ @var{context-identifier}
+ @} @}
+@end example
+Then you can add engravers, remove engravers.
+The syntax for these operations are respectively
+@example
+ \remove @var{engravername}
+ \consists @var{engravername}
+@end example
+
+
+Here @var{engravername} is a string, the name of an engraver in the
+system.
+@example
+ @var{propname} = @var{value}
+@end example
+
+
+@lilypond[verbatim,singleline]
+\score { \notes {
+ c'4 c'4 }
+ \paper {
+ \translator { \StaffContext
+ \remove Clef_engraver;
+ } } }
+@end lilypond
+
+@cindex engraver
+
+You can also set properties in a translator definition. The syntax is as
+follows:
+
+@var{propname} is a string and @var{value} is a Scheme
+expression.
+@example
+ @var{propname} = @var{value}
+ @var{propname} \set @var{symbol} = @var{value}
+ @var{propname} \override @var{symbol} = @var{value}
+ @var{propname} \revert @var{symbol}
+
+@end example
+
+These type of property assignments happen before interpretation starts,
+so a @code{\property} expression will override any predefined settings.
+
+
+ To simplify editing translators, all standard contexts have standard
+identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
+@code{VoiceContext}.
+
+@node Defining new contexts
+@subsection Defining new contexts
+
+If you want to build a context from scratch, you must also supply the
+following extra information:
+@itemize @bullet
+ @item A name, specified by @code{\name @var{contextname};}.
+
+ @item A cooperation module. This is specified by @code{\type
+@var{typename};}.
+@end itemize
+
+This is an example:
+@example
+\translator @code{
+ \type "Engraver_group_engraver";
+ \name "SimpleStaff";
+ \alias "Staff";
+ \consists "Staff_symbol_engraver";
+ \consists "Note_head_engraver";
+ \consistsend "Axis_group_engraver";
+}@
+@end example
+
+Basic building blocks of translation are called engravers; they are
+special C++ classes.
+
+The argument of @code{\type} is the name for a special engraver that
+handles cooperation between simple engravers such as
+@code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
+for this engraver are the following:
+@table @code
+@cindex @code{Engraver_group_engraver}
+ @item @code{Engraver_group_engraver}
+ The standard cooperation engraver.
+
+@cindex @code{Score_engraver}
+
+ @item @code{Score_engraver}
+ This is cooperation module that should be in the top level context,
+and only the toplevel context.
+
+@cindex @code{Grace_engraver_group}
+
+ @item @code{Grace_engraver_group}
+ This is a special cooperation module (resembling
+ @code{Score_engraver}) that is used to created an embedded
+ `miniscore'.
+@end table
+
+Other modifiers are
+
+@itemize @bullet
+ @item @code{\alias} @var{alternate-name} @code{;}
+ This specifies a different name. In the above example,
+@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
+
+ @item @code{\consistsend} @var{engravername} @code{;}
+ Analogous to @code{\consists}, but makes sure that
+ @var{engravername} is always added to the end of the list of
+ engravers.
+
+ Some engraver types need to be at the end of the list; this
+ insures they are put there, and stay there, if a user adds or
+ removes engravers. This command is usually not needed for
+ end-users.
+
+ @item @code{\accepts} @var{contextname} @code{;}
+ Add @var{contextname} to the list of context this context can
+ contain. The first listed context is the context to create by
+ default.
+
+ @item @code{\denies}. The opposite of @code{\accepts}. Added for
+completeness, but is never used in practice.
+
+
+ @item @code{\name} @var{contextname} @code{;}
+ This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
+ the name is not specified, the translator won't do anything.
+@end itemize
+
+In the @code{\paper} block, it is also possible to define translator
+identifiers. Like other block identifiers, the identifier can only
+be used as the very first item of a translator. In order to define
+such an identifier outside of @code{\score}, you must do
+
+@quotation
+@example
+\paper @{
+ foo = \translator @{ @dots{} @}
+@}
+\score @{
+ \notes @{
+ @dots{}
+ @}
+ \paper @{
+ \translator @{ \foo @dots{} @}
+ @}
+@}
+@end example
+
+@end quotation
+
+
+@cindex paper types, engravers, and pre-defined translators
+
+
+
+
+
+
+@c . {Syntactic details}
+@node Syntactic details
+@section Syntactic details
+@cindex Syntactic details
+
+This section describes details that were too boring to be put elsewhere.
+
+@menu
+* Top level::
+* Identifiers::
+* Music expressions::
+* Manipulating music expressions::
+* Assignments::
+* Lexical modes::
+* Ambiguities::
+@end menu
+
+@c . {Top level}
+@node Top level
+@subsection Top level
+@cindex Top level
+
+This section describes what you may enter at top level.
+
+
+@c . {Score}
+@subsubsection Score
+@cindex Score
+
+@cindex score definition
+
+The output is generated combining a music expression with an output
+definition. A score block has the following syntax:
+
+@example
+ \score @{ @var{musicexpr} @var{outputdefs} @}
+@end example
+
+@var{outputdefs} are zero or more output definitions. If none is
+supplied, the default @code{\paper} block will be added.
+
+
+
+@c . {Default output}
+@subsubsection Default output
+
+Default values for the @code{\paper} and @code{\midi} block are set by
+entering such a block at top-level.
+
+@c . {Header}
+@subsubsection Header
+@cindex Header
+@cindex @code{\header}
+
+
+A header describes bibilographic information of the file's contents. It
+can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
+use this information for generating titles. Key values that are used by
+@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
+metre, arranger, piece and tagline.
+
+@cindex @code{ly2dvi}
+
+The syntax is
+@example
+ \header @{ @var{key1} = @var{val1};
+ @var{key2} = @var{val2}; @dots{} @}
+@end example
+
+It is customary to put the @code{\header} at the top of the file.
+
+@subsubsection Default output
+
+A @code{\midi} or @code{\paper} block at top-level sets the default
+
+paper block for all scores that lack an explicit paper block.
+
+@c . {Identifiers}
+@node Identifiers
+@subsection Identifiers
+@cindex Identifiers
+
+All of the information in a LilyPond input file, is represented as a
+Scheme value. In addition to normal Scheme data types (such as pair,
+number, boolean, etc.), LilyPond has a number of specialized data types,
+
+@itemize @bullet
+@item Input
+@item c++-function
+@item Music
+@item Identifier
+@item Translator_def
+@item Duration
+@item Pitch
+@item Score
+@item Music_output_def
+@item Moment (rational number)
+@end itemize
+
+LilyPond also includes some transient object types. Objects of these
+types are built during a LilyPond run, and do not `exist' per se within
+your input file. These objects are created as a result of your input
+file, so you can include commands in the input to manipulate them,
+during a lilypond run.
+
+@itemize @bullet
+@item Grob: short for Graphical object. See @ref{Grobs}.
+@item Molecule: device-independent page output object,
+including dimensions. Produced by some Grob functions
+See @ref{Molecules}
+@item Translator: object that produces audio objects or Grobs. This is
+not yet user accessible.
+@item Font_metric: object representing a font. (See @ref{Font metrics})
+
+@end itemize
+
+
+@node Music expressions
+@subsection Music expressions
+
+@cindex music expressions
+
+Music in LilyPond is entered as a music expression. Notes, rests, lyric
+syllables are music expressions, and you can combine music expressions
+to form new ones, for example by enclosing a list of expressions in
+@code{\sequential @{ @}} or @code{< >}. In the following example, a
+compound expression is formed out of the quarter note @code{c} and a
+quarter note @code{d}:
+
+@example
+\sequential @{ c4 d4 @}
+@end example
+
+@cindex Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
+@cindex @code{<}
+@cindex @code{>}
+@cindex Simultaneous music
+@cindex @code{\simultaneous}
+
+The two basic compound music expressions are simultaneous and
+sequential music.
+
+@example
+ \sequential @code{@{} @var{musicexprlist} @code{@}}
+ \simultaneous @code{@{} @var{musicexprlist} @code{@}}
+@end example
+For both, there is a shorthand:
+@example
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
+for sequential and
+@example
+ @code{<} @var{musicexprlist} @code{>}
+@end example
+for simultaneous music.
+In principle, the way in which you nest sequential and simultaneous to
+produce music is not relevant. In the following example, three chords
+are expressed in two different ways:
+
+@lilypond[fragment,verbatim,center]
+ \notes \context Voice {
+ <a c'> <b d' > <c' e'>
+ < { a b c' } { c' d' e' } >
+ }
+@end lilypond
+
+
+Other compound music expressions include
+@example
+ \repeat @var{expr}
+ \transpose @var{pitch} @var{expr}
+ \apply @var{func} @var{expr}
+ \context @var{type} = @var{id} @var{expr}
+ \times @var{fraction} @var{expr}
+@end example
+
+
+@c . {Manipulating music expressions}
+@node Manipulating music expressions
+@subsection Manipulating music expressions
+
+The @code{\apply} mechanism gives you access to the internal
+representation of music. You can write Scheme-functions that operate
+directly on it. The syntax is
+@example
+ \apply #@var{func} @var{music}
+@end example
+This means that @var{func} is applied to @var{music}. The function
+@var{func} should return a music expression.
+
+This example replaces the text string of a script. It also shows a dump
+of the music it processes, which is useful if you want to know more
+about how music is stored.
+@lilypond[verbatim]
+#(define (testfunc x)
+ (if (equal? (ly-get-mus-property x 'text) "foo")
+ (ly-set-mus-property x 'text "bar"))
+ ;; recurse
+ (ly-set-mus-property x 'elements
+ (map testfunc (ly-get-mus-property x 'elements)))
+ (display x)
+ x
+)
+\score { \notes
+ \apply #testfunc { c4_"foo" }
+}
+@end lilypond
+
+For more information on what is possible, see the @ref{Tricks} and the
+automatically generated documentation.
+
+
+Directly accessing internal representations is dangerous: the
+implementation is subject to changes, so you should avoid this feature
+if possible.
+
+
+
+@c . {Span requests}
+@menu
+* Span requests::
+@end menu
+
+@node Span requests
+@subsubsection Span requests
+@cindex Span requests
+
+Notational constructs that start and end on different notes can be
+entered using span requests. The syntax is as follows:
+
+
+@example
+ \spanrequest @var{startstop} @var{type}
+@end example
+
+
+@cindex @code{\start}
+@cindex @code{\stop}
+
+This defines a spanning request. The @var{startstop} parameter is either
+-1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
+describes what should be started. Much of the syntactic sugar is a
+shorthand for @code{\spanrequest}, for example,
+
+@lilypond[fragment,verbatim,center]
+ c'4-\spanrequest \start "slur"
+ c'4-\spanrequest \stop "slur"
+@end lilypond
+
+Among the supported types are @code{crescendo}, @code{decrescendo},
+@code{beam}, @code{slur}. This is an internal command. Users are
+encouraged to use the shorthands which are defined in the initialization
+file @file{spanners.ly}.
+
+
+@c . {Assignments}
+@node Assignments
+@subsection Assignments
+@cindex Assignments
+
+Identifiers allow objects to be assigned to names during the parse
+stage. To assign an identifier, you use @var{name}@code{=}@var{value}
+and to refer to an identifier, you preceed its name with a backslash:
+`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
+the input-types listed above. Identifier assignments can appear at top
+level in the LilyPond file, but also in @code{\paper} blocks.
+
+Semicolons are forbidden after top level assignments, but mandatory in
+other places. The rules about semicolons and assignments are very
+confusing, but when LilyPond input evolves more towards Scheme, we hope
+that this problem will grow smaller.
+
+An identifier can be created with any string for its name, but you will
+only be able to refer to identifiers whose names begin with a letter,
+being entirely alphabetical. It is impossible to refer to an identifier
+whose name is the same as the name of a keyword.
+
+The right hand side of an identifier assignment is parsed completely
+before the assignment is done, so it is allowed to redefine an
+identifier in terms of its old value, e.g.
+
+@example
+foo = \foo * 2.0
+@end example
+
+When an identifier is referenced, the information it points to is
+copied. For this reason, an identifier reference must always be the
+first item in a block.
+@example
+\paper @{
+ foo = 1.0
+ \paperIdent % wrong and invalid
+@}
+
+\paper @{
+ \paperIdent % correct
+ foo = 1.0 @}
+@end example
+
+
+@c . {Lexical modes}
+@node Lexical modes
+@subsection Lexical modes
+@cindex Lexical modes
+@cindex input mode
+@cindex mode, input
+@cindex @code{\notes}
+@cindex @code{\chords}
+@cindex @code{\lyrics}
+
+To simplify entering notes, lyrics, and chords, LilyPond has three
+special input modes on top of the default mode: note, lyrics and chords
+mode. These input modes change the way that normal, unquoted words are
+interpreted: for example, the word @code{cis} may be interpreted as a
+C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
+respectively.
+
+A mode switch is entered as a compound music expressions
+@example
+@code{\notes} @var{musicexpr}
+@code{\chords} @var{musicexpr}
+@code{\lyrics} @var{musicexpr}.
+@end example
+
+In each of these cases, these expressions do not add anything to the
+meaning of their arguments. They are just a way to indicate that the
+arguments should be parsed in indicated mode. The modes are treated in
+more detail in the @ref{Note entry}, @ref{Lyrics} and
+@ref{Chords}.
+
+You may nest different input modes.
+
+@c . {Ambiguities}
+@node Ambiguities
+@subsection Ambiguities
+@cindex ambiguities
+@cindex grammar
+
+
+The grammar contains a number of ambiguities. We hope to resolve them at
+some time.
+
+@itemize @bullet
+ @item The assignment
+
+ @example
+foo = bar
+@end example
+
+ can be interpreted as making a string identifier @code{\foo}
+ containing @code{"bar"}, or a music identifier @code{\foo}
+ containing the syllable `bar'.
+
+ @item The assignment
+
+ @example
+foo = -6
+@end example
+
+ can be interpreted as making an integer identifier
+ containing -6, or a Request identifier containing the
+ fingering `6' (with neutral direction).
+
+ @item If you do a nested repeat like
+
+ @quotation
+
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
+
+ @end quotation
+
+ then it is ambiguous to which @code{\repeat} the
+ @code{\alternative} belongs. This is the classic if-then-else
+ dilemma. It may be solved by using braces.
+
+ @item (an as yet unidentified ambiguity :-)
+@end itemize
+
+
+@c . {Lexical details}
+@node Lexical details
+@section Lexical details
+
+Even more boring details, now on lexical side of the input parser.
+
+@menu
+* Comments::
+* Direct Scheme::
+* Keywords::
+* Integers::
+* Reals::
+* Strings::
+* Main input::
+* File inclusion::
+* Version information::
+@end menu
+
+
+@node Comments
+@subsection Comments
+
+@cindex comments
+@cindex block comment
+@cindex line comment
+
+@cindex @code{%}
+
+A one line comment is introduced by a @code{%} character.
+Block comments are started by @code{%@{} and ended by @code{%@}}.
+They cannot be nested.
+
+@node Direct Scheme
+@subsection Direct Scheme
+
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+
+
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. In some places Scheme expressions also form valid syntax:
+whereever it is allowed,
+@example
+ #@var{scheme}
+@end example
+evaluates the specified Scheme code. If this is used at toplevel, then
+the result is discarded. Example:
+@example
+ \property Staff.TestObject \override #'foobar = #(+ 1 2)
+@end example
+
+@code{\override} expects two Scheme expressions, so there are two Scheme
+expressions. The first one is a symbol (@code{foobar}), the second one
+an integer (namely, 3).
+
+Scheme is a full-blown programming language, and a full discussion is
+outside the scope of this document. Interested readers are referred to
+the website @uref{http://www.schemers.org/} for more information on
+Scheme.
+
+
+@node Keywords
+@subsection Keywords
+@cindex Keywords
+
+
+Keywords start with a backslash, followed by a number of lower case
+alphabetic characters. These are all the keywords.
+
+@example
+apply arpeggio autochange spanrequest commandspanrequest
+simultaneous sequential accepts alternative bar breathe
+char chordmodifiers chords clef cm consists consistsend
+context denies duration dynamicscript elementdescriptions
+font grace header in lyrics key mark pitch
+time times midi mm name pitchnames notes outputproperty
+override set revert partial paper penalty property pt
+relative remove repeat addlyrics partcombine score
+script stylesheet skip textscript tempo translator
+transpose type
+@end example
+
+@node Integers
+@subsection Integers
+
+@cindex integers
+@cindex @code{+}
+@cindex @code{-}
+@cindex @code{*}
+@cindex @code{/}
+
+Formed from an optional minus sign followed by digits. Arithmetic
+operations cannot be done with integers, and integers cannot be mixed
+with reals.
+
+@node Reals
+@subsection Reals
+@cindex real numbers
+
+
+
+
+
+Formed from an optional minus sign and a sequence of digits followed
+by a @emph{required} decimal point and an optional exponent such as
+@code{-1.2e3}. Reals can be built up using the usual operations:
+`@code{+}', `@code{-}', `@code{*}', and
+`@code{/}', with parentheses for grouping.
+
+@cindex @code{\mm},
+@cindex @code{\in}
+@cindex @code{\cm}
+@cindex @code{\pt}
+@cindex dimensions
+
+A real constant can be followed by one of the dimension keywords:
+@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
+points, inches and centimeters, respectively. This converts the number
+a number that is the internal representation of that dimension.
+
+
+@node Strings
+@subsection Strings
+@cindex string
+@cindex concatenate
+
+Begins and ends with the @code{"} character. To include a @code{"}
+character in a string write @code{\"}. Various other backslash
+sequences have special interpretations as in the C language. A string
+that contains no spaces can be written without the quotes. See
+@ref{Lexical modes} for details on unquoted strings; their
+interpretation varies depending on the situation. Strings can be
+concatenated with the @code{+} operator.
+
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
+
+
+@node Main input
+@subsection Main input
+@cindex Main input
+
+@cindex @code{\maininput}
+
+The @code{\maininput} command is used in init files to signal that the
+user file must be read. This command cannot be used in a user file.
+
+@node File inclusion
+@subsection File inclusion
+@cindex @code{\include}
+@example
+ \include @var{filename}
+@end example
+
+Include @var{filename}. The argument @var{filename} may be a quoted string (an
+unquoted string will not work here!) or a string identifier. The full
+filename including the @file{.ly} extension must be given,
+
+
+@node Version information
+@subsection Version information
+@cindex @code{\version}
+@example
+ \version @var{string} ;
+@end example
+
+Specify the version of LilyPond that a file was written for. The
+argument is a version string in quotes, for example @code{"1.2.0"}.
+This is used to detect invalid input, and to aid
+@code{convert-ly} a tool that automatically upgrades input files. See
+See @ref{convert-ly} for more information on @code{convert-ly}.
+
+@cindex convert-ly
+
+
+
+
+
+
+@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: