-@c -*-texinfo-*-
-
+@c Note:
+@c
+@c A menu is needed before every deeper *section nesting of @nodes
+@c Run M-x texinfo-all-menus-update
+@c to automagically fill in these menus
+@c before saving changes
+
+@c_{Reference Manual}
@node Reference Manual
@chapter Reference Manual
-
@menu
-* Overview:: Overview
-* Top level:: Top level
-* Pitch names:: Pitch names
-* Lexical conventions:: Lexical conventions
-* Other languages:: Note names in various languages
-* Lexical modes:: modes
-* Types:: Types
-* Assignments:: Assignments
-* 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
-* Point and click:: Quik edit using Point and Click
-* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
-* Engravers:(lilypond-internals)LilyPond engravers.
-* Backend:(lilypond-internals)LilyPond backend.
+* Overview::
+* Music constructs::
+* Modifying music::
+* Note entry::
+* Note specification::
+* Music notation::
+* Lyrics entry::
+* Chord entry::
+* Page layout::
+* Sound::
+* Music entry::
+* Engravers::
+* Lexer innards::
+* Unsorted::
@end menu
-
-
+@c_ {Overview}
@node Overview
@section Overview
-
-[todo: pedals]
-
This document
describes the the GNU LilyPond input format This format represents a
piece of music in an elegant way, but contains enough information for
description. In other words, LilyPond would be best
described by `music compiler' or `music to notation compiler'.
-
-
LilyPond input can be classified into three types:
@itemize @bullet
@item musical expressions: a musical expression is some combination of
can enter and edit them in manageable chunks.
@end itemize
-@node Top level
-@section Top level
-This section describes what you may enter at top level.
+@c_ {Music constructs}
+@node Music constructs
+@section Music constructs
+@cindex Music constructs
+@menu
+* Music expressions::
+* Sequential music::
+* Simultanious music::
+* Compound music expressions::
+* Grace music::
+* Explicit atomic music::
+@end menu
+@c_ {Music expressions}
+@node Music expressions
+@subsection Music expressions
-@unnumberedsubsec Score definition
-@cindex score definition
+@cindex music expressions
-The output is generated combining a music expression with an output
-definition. A score block has the following syntax:
+Music in LilyPond is entered as a music expression. Notes, rests,
+lyric syllables are music expressions (the atomic
+expressions),
+@cindex atomic music expressions
+and you can combine music expressions to form new ones. This example
+forms a compound expressions out of the quarter @code{c} note and a
+@code{d} note:
+
+@example
+\sequential @{ c4 d4 @}
+@end example
+
+The meaning of this compound expression is to play the @code{c}
+first, and then the @code{d} (as opposed to playing them
+simultaneously, for instance).
+
+Atomic music expression are discussed in
+subsection @ref{Atomic music expressions}. Compound music expressions are
+discussed in subsection @ref{Compound music expressions}.
+
+
+@c_ {Sequential music}
+@node Sequential music
+@subsection Sequential music
+@cindex Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
@example
- \score @{ @var{musicexpr} @var{outputdefs} @}
+ \sequential @code{@{} @var{musicexprlist} @code{@}}
@end example
-@var{outputdefs} are zero or more output definitions. If no output
-definition is supplied, the default @code{\paper} block will be added.
+This means that list should be played or written in sequence, i.e.,
+the second after the first, the third after the second. The duration
+of sequential music is the the sum of the durations of the elements.
+There is a shorthand, which leaves out the keyword:
-@unnumberedsubsec Header definition
-@cindex headers
+@example
+@cindex @code{<}
+@cindex @code{>}
-@cindex @code{\header}
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
-The syntax is
+@c_ {Simultanious music}
+@node Simultanious music
+@subsection Simultanious music
+@cindex Simultanious music
+@cindex @code{\simultaneous}
@example
- \header @{ @var{key1} = @var{val1};
-@cindex @code{ly2dvi}
- @var{key2} = @var{val2}; @dots{} @}
+ \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:
-A header describes the file's contents. It can also appear in a
-@code{\score} block. Tools like @code{ly2dvi} can use this
-information for generating titles. Key values that are used by
-@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
-metre, arranger, piece and tagline.
-
-It is customary to put the @code{\header} at the top of the file.
+@example
+ @code{<} @var{musicexprlist} @code{>}
+@end example
-@unnumberedsubsec Default output
+If you try to use a chord as the first thing in your score, you might
+get multiple staffs instead of a chord.
-A @code{\midi} or @code{\paper} block at top-level sets the default
-paper block for all scores that lack an explicit paper block.
+@lilypond[verbatim,center]
+ \score {
+ \notes <c''4 e''>
+ \paper {
+ linewidth = -1.;
+ }
+ }
+@end lilypond
-@unnumberedsubsec Scheme statements
+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:
-Scheme statements maybe issued to produce interesting side-effects.
+@lilypond[verbatim,center]
+ \score {
+ \notes\context Voice <c''4 e''>
+ \paper {
+ linewidth = -1.;
+ }
+ }
+@end lilypond
+@c_ {Compound music expressions}
+@node Compound music expressions
+@subsection Compound music expressions
-@node Pitch names
-@section Pitch names
+@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:
-@unnumberedsubsec Pitch name definition
-@cindex pitch names
+@lilypond[fragment,verbatim,center]
+ \notes \context Staff {
+ <a c'> <b d' > <c' e'>
+ < { a b c' } { c' d' e' } >
+ }
-@cindex note names
-@cindex chord modifier names
+@end lilypond
-Note names and chord modifiers can be customised for nationalities.
-languages and conventions. The syntax is as follows.
-@cindex @code{\pitchnames}
-@cindex @code{\chordmodifiers}
+@cindex @code{\context}
+@cindex context selection
@example
- \pitchnames @var{scheme-alist}
- \chordmodifiers @var{scheme-alist}
+ \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
@end example
-See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
-specific examples how to do this. tables can be tailored specified
-using. Some national note names have been provided, see
-section @ref{Other languages}.
-A @code{\paper} block at top level sets the default paper block. A
-@code{\midi} block at top level works similarly.
+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.
-@unnumberedsubsec Assignments
-@cindex assignments
-@cindex @code{#}
-Identifier assignments may appear at top level. @ref{Assignments}
+@c_ {Grace music} <-> Grace notes
+@node Grace music
+@subsection Grace music
+@cindex Grace music
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
+@cindex @code{graceAlignPosition}
+@example
+ \grace @var{musicexpr}
+@end example
-@node Lexical conventions
-@section Lexical conventions
+A grace note expression has duration 0; the next real note is
+assumed to be the main note.
-@cindex lexical conventions
+You cannot have the grace note after the main note, in terms of
+duration, and main notes, but you can typeset the grace notes to the
+right of the main note using the property
+@code{graceAlignPosition}.
+@cindex @code{flagStyle}
+When grace music is interpreted, a score-within-a-score is set up:
+@var{musicexpr} has its own time bookkeeping, and you could (for
+example) have a separate time signature within grace notes. While in
+this score-within-a-score, you can create notes, beams, slurs, etc.
+Unbeamed eighth notes and shorter by default have a slash through the
+stem. This behavior can be controlled with the
+@code{flagStyle} property.
-@unnumberedsubsec Comments
+@quotation
+@lilypond[fragment,verbatim]
+\relative c'' {
+ \grace c8 c4 \grace { [c16 c16] } c4
+ \grace { \property Grace.flagStyle = "" c16 } c4
+}
-@cindex comment
-@cindex @code{%}
+@end lilypond
+@end quotation
+@cindex @code{\grace}
+At present, nesting @code{\grace} notes is not supported. The following
+may cause run-time errors:
+@example
+ @code{\grace @{ \grace c32 c16 @} c4}
+@end example
+Since the meaning of such a construct is unclear, we don't consider
+this a loss. Similarly, juxtaposing two @code{\grace} sections is
+syntactically valid, but makes no sense and may cause runtime errors.
-A one line comment is introduced by a @code{%} character.
-Block comments are started by @code{%@{} and ended by `@code{%@}}'.
-They cannot be nested.
+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.
-@unnumberedsubsec Scheme
+The present implementation is not robust and generally kludgy. We expect
+it to change after LilyPond 1.4
+@c_ {Explicit atomic music}
+@node Explicit atomic music
+@subsection Explicit atomic music
+@cindex Explicit atomic music
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
+@cindex pitch
+The syntax for pitch specification is
-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:
+@cindex @code{\pitch}
@example
- \property Staff.TestObject \override #'foobar = #(+ 1 2)
+ \pitch @var{scmpitch}
@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.
-
-@unnumberedsubsec Keywords
-@cindex keyword
+@var{scmpitch} is a pitch scheme object, see @ref{Pitch}.
+In Note and Chord mode, pitches may be designated by names. See
+section @ref{Other languages} for pitch names in different languages.
-Keywords start with a backslash, followed by a number of lower case
-alphabetic characters. These are all the keywords.
+@cindex duration
+@cindex @code{\duration}
+The syntax for duration specification is
@example
-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
+ \duration @var{scmduration}
@end example
-@unnumberedsubsec Integers
+In Note, Chord, and Lyrics mode, durations may be designated by
+numbers and dots.
-@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.
-@unnumberedsubsec Reals
-@cindex real numbers
+@c_ {Modifying music}
+@node Modifying music
+@section Modifying music
+@cindex Modifying music
+@menu
+* Relative::
+* Transpose::
+* Repeat::
+* Times ::
+* Apply::
+* Transform::
+@end menu
+@c_ {Relative}
+@node Relative
+@subsection Relative
+@cindex Relative
+@cindex relative octave specification
+It is easy to get confused by octave changing marks and accidentally
+putting a pitch in the wrong octave. A much better way of entering a
+note's octave is `the relative octave' mode.
+@cindex @code{\relative}
+@example
+ \relative @var{startpitch} @var{musicexpr}
+@end example
+The octave of notes that appear in @var{musicexpr} are calculated as
+follows: If no octave changing marks are used, the basic interval
+between this and the last note is always taken to be a fourth or
+less.@footnote{The interval is determined without regarding
+accidentals. A @code{fisis} following a @code{ceses} will be put above
+the @code{ceses}.} The octave changing marks @code{'} and @code{,}
+can then be added to raise or lower the pitch by an extra octave.
+Upon entering relative mode, an absolute starting pitch must be
+specified that will act as the predecessor of the first note of
+@var{musicexpr}.
-Formed from an optional minus sign and a sequence of digits followed
-by a @emph{required} decimal point and an optional exponent such as
-@code{-1.2e3}. Reals can be built up using the usual operations:
-`@code{+}', `@code{-}', `@code{*}', and
-`@code{/}', with parentheses for grouping.
+Entering scales is straightforward in relative mode.
-@cindex @code{\mm},
-@cindex @code{\in}
-@cindex @code{\cm}
-@cindex @code{\pt}
-@cindex dimensions
+@lilypond[fragment,verbatim,center]
+ \relative c' {
+ c d e f g a b c c,
+ }
+@end lilypond
-A real constant can be followed by one of the dimension keywords:
-@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
-points, inches and centimeters, respectively. This converts the number
-to a real that is the internal representation of dimensions.
+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
-@unnumberedsubsec Strings
-@cindex string
-@cindex concatenate
+If the preceding item is a chord, the first note of the chord is used
+to determine the first note of the next chord. But other notes
+within the second chord are determined by looking at the immediately
+preceding note.
-Begins and ends with the @code{"} character. To include a @code{"}
-character in a string write @code{\"}. Various other backslash
-sequences have special interpretations as in the C language. A string
-that contains no spaces can be written without the quotes. See
-@ref{Lexical modes} for details on unquoted strings; their interpretation varies
-depending on the situation. Strings can be concatenated with the
-@code{+} operator.
+@lilypond[fragment,verbatim,center]
+ \relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+ }
+@end lilypond
+@cindex @code{\notes}
-The tokenizer accepts the following commands. They have no grammatical
-function, hence they can appear anywhere in the input.
+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).
-@unnumberedsubsec Main input
+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}.
-@cindex @code{\maininput}
+It is strongly recommended to use relative pitch mode: less work,
+less error-prone, and more readable.
-The @code{\maininput} command is used in init files to signal that the
-user file must be read. This command cannot be used in a user file.
+@c_ {Transpose}
+@node Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
-@unnumberedsubsec File inclusion
-@cindex @code{\include}
+A music expression can be transposed with @code{\transpose}. The syntax
+is
@example
- \include @var{filename}
+ \transpose @var{pitch} @var{musicexpr}
@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,
-
-@unnumberedsubsec Version information
-@cindex @code{\version}
-@example
- \version @var{string} ;
-@end example
+This means that middle C in @var{musicexpr} is transposed to
+@var{pitch}.
-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}.
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose cis'} or @code{\transpose des'} will transpose up half
+a tone. The first version will print sharps and the second version
+will print flats.
-@cindex convert-ly
+@quotation
+@lilypond[fragment,verbatim]
+\context Staff {
+ \clef "F";
+ { \key e \major; c d e f }
+ \clef "G";
+ \transpose des'' { \key e \major; c d e f }
+ \transpose cis'' { \key e \major; c d e f }
+}
+@end lilypond
+@end quotation
-@node Lexical modes
-@section Lexical modes
-@cindex Lexical modes
-@cindex modes
+If you want to use both @code{\transpose} and @code{\relative}, then
+you must use @code{\transpose} first. @code{\relative} will have no
+effect music that appears inside a @code{\transpose}.
+@c_ {Repeat}
+@node Repeat
+@subsection Repeat
+@cindex Repeat
+@cindex repeats
-To simplify entering notes, lyrics, and chords, LilyPond has three
-special input modes on top of the default mode. In each mode, words
-are identified on the input. If @code{"word"} is encountered, it is
-treated as a string. If @code{\word} is encountered, it is treated as
-a keyword or as an identifier. The behavior of the modes differs in
-two ways: Different modes treat unquoted words differently, and
-different modes have different rules for deciding what is a word.
+@ref{Volta}
+[TODO: document #'repeatCommands.]
-@table @asis
-@item Normal mode.
-@cindex normal mode
-
-At the start of parsing, LilyPond is in Normal mode. In Normal
-mode, a word is an alphabetic character followed by alphanumeric
-characters. If @code{word} is encountered on the input it is
-treated as a string.
+@cindex @code{\repeat}
-@item Note mode.
-@cindex note mode
+In order to specify repeats, use the @code{\repeat}
+keyword. Since repeats look and sound differently when played or
+printed, there are a few different variants of repeats.
-@cindex @code{\notes}
-Note mode is introduced by the keyword
-@code{\notes}. In Note mode, words can only
-contain alphabetic characters. If @code{word} is encountered,
-LilyPond first checks for a notename of @code{word}. If no
-notename is found, then @code{word} is treated as a string.
+@table @asis
+@item unfolded
+Repeated music is fully written (played) out. Useful for MIDI
+output.
-Since combinations of numbers and dots are used for indicating
-durations, it is not possible to enter real numbers in this mode.
+@item volta
+This is the normal notation: Repeats are not written out, but
+alternative endings (voltas) are printed, left to right.
-@item Chord mode.
-@cindex chord mode
+@item folded
+Alternative endings are written stacked. Which is unfortunately not
+practical for anything right now.
-Chord mode is introduced by the keyword
-@code{\chords}. It is similar to Note mode, but
-words are also looked up in a chord modifier table (containing
-@code{maj}, @code{dim}, etc).
+@item tremolo
+Make tremolo beams.
+@end table
-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.
+The syntax for repeats is
-@item Lyrics mode.
-@cindex lyric mode
-@cindex @code{\lyrics}
+@example
+ \repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
-Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
-rules that make it easy to include punctuation and diacritical marks in
-words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
-format or a standard encoding without needing quotes. The precise
-definition of this mode is ludicrous, and this will remain so until the
-authors of LilyPond acquire a deeper understanding of character
-encoding, or someone else steps up to fix this.
+If you have alternative endings, you may add
-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{^}.
+@cindex @code{\alternative}
+@example
+ \alternative @code{@{} @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @code{@}}
+@end example
-Subsequent characters of a word can be any character that is not a digit
-and not white space. One important consequence of this is that a word
-can end with `@code{@}}', which may be confusing. However, LilyPond will
-issue a warning. Any @code{_} character which appears in an unquoted
-word is converted to a space. This provides a mechanism for introducing
-spaces into words without using quotes. Quoted words can also be used
-in Lyrics mode to specify words that cannot be written with the above
-rules. Here are some examples. Not all of these words are printable by
-@TeX{}.
+where each @var{alternative} is a Music expression.
-@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
+Normal notation repeats are used like this:
-Since combinations of numbers and dots are used for indicating
-durations, you can not enter real numbers in this mode.
-@end table
+@quotation
-[todo: include short table showing differences]
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 { c'4 d' e' f' }
+ \repeat volta 2 { f' e' d' c' }
-@node Types
-@section Types
+@end lilypond
+@end quotation
-@cindex Identifiers
+With alternative endings:
-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,
+@quotation
-@itemize @bullet
-@item Input
-@item c++-function
-@item Music: see @ref{Music expressions}
-@item Identifier
-@item Translator_def:
-See section @ref{contextdefs} for more information
-@item Duration
-@item Pitch
-@item Score
-@item Music_output_def
-@item Moment (rational number)
-@end itemize
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
-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.
+@end lilypond
+@end quotation
-@itemize @bullet
-@item Grob: short for Graphical object. See @ref{Grobs}.
-@item Molecule: device-independent page output object,
-including dimensions. Produced by some Grob functions
-See @ref{Molecules}
-@item Translator: object that produces audio objects or Grobs. This is
-not yet user accessible.
-@item Font_metric: object representing a font. (See @ref{Font metrics})
-@c @item Audio_element: (todo, smobme)
-@end itemize
+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.}
-@node Assignments
-@unnumberedsubsec Assignments
+@quotation
-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.
+@lilypond[fragment,verbatim]
+ c'1
+ \repeat fold 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
-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.
+@end lilypond
+@end quotation
-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.
+@quotation
-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.
+@lilypond[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \partial 4;
+ \repeat volta 2 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b1 } }
+ }
+}
-@example
-foo = \foo * 2.0
-@end example
+@end lilypond
+@end quotation
-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
-@}
+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.
-\paper @{
-\paperIdent % correct
-foo = 1.0
-@}
-@end example
+@quotation
+@lilypond[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g }
+ {\partial 1; e4 e e }
+ {\partial 1; a a a a | b1 } }
+ }
+}
+@end lilypond
+@end quotation
+
+As you can see, LilyPond doesn't remember the timing information, nor
+are slurs or ties repeated. We hope to fix this after 1.4.
+It is possible to nest @code{\repeat}. This is not entirely
+supported: the notes will come be in the right places, but the repeat
+bars will not.
-@node Music expressions
-@section Music expressions
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style.
+@cindex tremolo beams
+To create tremolo beams on a single note, simply attach
+`@code{:}@var{length}' to the note itself.
-@cindex music expressions
+@lilypond[verbatim,center]
+\score {
+ \context Voice \notes\relative c' {
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+ \repeat "tremolo" 2 { c16 d16 }
+ }
+ \paper {
+ linewidth = 40*\staffspace;
+ }
+}
+@end lilypond
+@cindex @code{__}
-Music in LilyPond is entered as a music expression. Notes, rests,
-lyric syllables are music expressions (the atomic
-expressions),
-@cindex atomic music expressions
-and you can combine music expressions to form new ones. This example
-forms a compound expressions out of the quarter @code{c} note and a
-@code{d} note:
+@lilypond[fragment,verbatim,center]
-@example
-\sequential @{ c4 d4 @}
-@end example
+ c'4:32
+@end lilypond
-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).
+@c_ {Times}
+@node Times
+@subsection Times
+@cindex Times
+@ref{Tuplets}
+Tuplets are made out of a music expression by multiplying their
+duration with a fraction.
-Atomic music expression are discussed in
-subsection @ref{Atomic music expressions}. Compound music expressions are
-discussed in subsection @ref{Compound music expressions}.
+@cindex @code{\times}
+@example
+ \times @var{fraction} @var{musicexpr}
+@end example
+
+The duration of @var{musicexpr} will be multiplied by the fraction.
+In print, the fraction's denominator will be printed over the notes,
+optionally with a bracket. The most common tuplet is the triplet in
+which 3 notes have the length of 2, so the notes are 2/3 of
+their written length:
+@lilypond[fragment,verbatim,center]
+ g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@end lilypond
-@node Atomic music expressions
-@section Atomic music expressions
+@c_ {Apply}
+@node Apply
+@subsection Apply
+@cindex Apply
+Apply allows a Scheme-function to operate directly on the internal
+representation of music.
+@example
+ \apply #@var{func} @var{music}
+@end example
+The function takes two arguments, being a function and an musical
+argument for that function. The function should return a music
+expression.
+This example replaces the text string of a script. It also shows a dump
+of the music it processes.
+@lilypond[verbatim]
+#(define (testfunc x)
+ (if (eq? (ly-get-mus-property x 'text) "foo")
+ (ly-set-mus-property x 'text "bar"))
+ ;; recurse
+ (ly-set-mus-property x 'elements
+ (map testfunc (ly-get-mus-property x 'elements)))
+ (display x)
+ x
+)
+\score { \notes
+ \apply #testfunc { c4_"foo" }
+}
+@end lilypond
+For more information on what is possible, see the @ref{Tricks} and the
+automatically generated documentation.
+@c_ {Transform}
+@node Transform
+@subsection Transform
+@cindex Transform
-@cindex pitch
-The syntax for pitch specification is
+@c_ {Note entry}
+@node Note entry
+@section Note entry
+@cindex Note entry
-@cindex @code{\pitch}
-@example
- \pitch @var{scmpitch}
-@end example
+@menu
+* Notes mode::
+* Pitch names::
+@end menu
-@var{scmpitch} is a pitch scheme object, see @ref{Pitch}.
+@c_ {Notes mode}
+@node Notes mode
+@subsection Notes mode
-In Note and Chord mode, pitches may be designated by names. See
-section @ref{Other languages} for pitch names in different languages.
+@cindex note mode
-@cindex duration
-@cindex @code{\duration}
+@cindex @code{\notes}
+Note mode is introduced by the keyword
+@code{\notes}. In Note mode, words can only
+contain alphabetic characters. If @code{word} is encountered,
+LilyPond first checks for a notename of @code{word}. If no
+notename is found, then @code{word} is treated as a string.
-The syntax for duration specification is
-@example
- \duration @var{scmduration}
-@end example
+Since combinations of numbers and dots are used for indicating
+durations, it is not possible to enter real numbers in this mode.
-In Note, Chord, and Lyrics mode, durations may be designated by
-numbers and dots.
+@cindex Notes mode
+@c_ {Pitch names}
+@node Pitch names
+@subsection Pitch names
+@cindex Pitch names
@node Note specification
@section Note specification
@cindex Note specification
@cindex pitches
-
@cindex entering notes
A note specification has the form
@end lilypond
-@cindex duration
+@c_ {Rests}
+@menu
+* Rests::
+* Durations::
+* Multi measure rests::
+* Skip::
+@end menu
+
+@node Rests
+@subsection Rests
+@cindex Rests
+
+Rests are entered like notes, with note name `@code{r}'.
+There is also a note name
+`@code{s}', which produces a space of the specified
+duration.
+
+
+@c_ {Durations}
+@node Durations
+@subsection Durations
+@cindex Durations
Durations are entered as their reciprocal values. For notes longer
than a whole note, use identifiers.
a quarter note is assumed. The duration can be followed by a dot
(`@code{.}') to obtain dotted note lengths.
-Rests are entered like notes, with note name `@code{r}'.
-There is also a note name
-`@code{s}', which produces a space of the specified
-duration.
@lilypond[fragment,verbatim,center]
You can alter the length of duration by writing `@code{*}@var{fraction}'
after it. This will not affect the appearance of note heads or rests.
-@unnumberedsubsec Multi measure rests
+@c_ {Multi measure rests}
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex Multi measure rests
@cindex @code{R}
Note that there is currently no way to condense multiple rests into a
single multimeasure rest.
+@c_ {Skip}
+@node Skip
+@subsection Skip
+@cindex Skip
-@unnumberedsubsec Lyrics
-@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}.
+@example
+ \skip @var{duration} @code{;}
+@end example
+@cindex @code{\skip}
-[explain automatic phrasing]
+Skips the amount of time specified by @var{duration}. If no other
+music is played, a gap will be left for the skipped time with no
+notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
+this has the same effect as the spacer rest.
-@cindex properties
-@unnumberedsubsec Translation property
-@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 @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
-@unnumberedsubsec Translator switches
-@cindex @code{\translator}
-@example
- \translator @var{contexttype} = @var{name}
-@end example
+@c_ {Music notation}
+@node Music notation
+@section Music notation
+@cindex Music notation
+@menu
+* Key::
+* Clef::
+* Time signature::
+* Spanners::
+* Ornaments::
+* Bar check::
+@end menu
-A music expression indicating that the context which is a direct
-child of the a context of type @var{contexttype} should be shifted to
-a context of type @var{contexttype} and the specified name.
+@c_ {Key}
+@node Key
+@subsection Key
+@cindex Key
-Usually this is used to switch staffs in Piano music, e.g.
+@cindex @code{\key}
@example
- \translator Staff = top @var{Music}
+ @code{\key} @var{pitch} @var{type} @code{;}
@end example
-
-
-@cindex output properties
-@unnumberedsubsec Output properties
-
-These allow you to tweak what is happening in the back-end
-directly. If you want to control every detail of the output
-formatting, this is the feature to use. The downside to this is that
-you need to know exactly how the backend works. Example:
-
-
-@lilypond[fragment,verbatim]
-\relative c'' { c4
- \context Staff \outputproperty
- #(make-type-checker 'note-head-interface)
- #'extra-offset = #'(5.0 . 7.5)
-<c8 e g> }
-@end lilypond
-
-This selects all note heads occurring at current staff level, and sets
-the @code{extra-offset} of those heads to @code{(5,7.5)}, shifting them
-up and right.
-
-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.
-
-@unnumberedsubsec Key signature
-@cindex @code{\key}
-
-@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}
+@cindex @code{\minor}
+@cindex @code{\major}
+@cindex @code{\minor}
+@cindex @code{\ionian}
+@cindex @code{\locrian}
+@cindex @code{\aeolian}
+@cindex @code{\mixolydian}
+@cindex @code{\lydian}
+@cindex @code{\phrygian}
+@cindex @code{\dorian}
Change the key signature. @var{type} should be @code{\major} or
@code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
@code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
@code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
-@unnumberedsubsec Rehearsal marks
-@cindex rehearsal marks
-@cindex mark
-@cindex @code{\mark}
-@example
- \mark @var{unsigned};
-@cindex @code{Mark_engraver}
- \mark @var{string};
-@end example
-
-Prints a mark over or under the staff.
-@unnumberedsubsec barlines
+@c_ {Clef}
+@node Clef
+@subsection Clef
+@cindex Clef
-@cindex @code{\bar}
-@cindex measure lines
-@cindex repeat bars
+@c_ {Clef changes}
+@subsubsection Clef changes
+@cindex @code{\clef}
@example
- \bar @var{bartype};
+ \clef @var{clefname} @code{;}
@end example
-This is a short-cut for doing
+Short-cut for
+
@example
- \property Score.whichBar = @var{bartype}
+ \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
-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}.
+Supported clef-names include
+
+[todo]
-[FIXME]
-@unnumberedsubsec Time signature
+@c_ {Time signature}
+@node Time signature
+@subsection Time signature
+@cindex Time signature
@cindex meter
-@cindex time signature
@cindex @code{\time}
+
@example
\time @var{numerator}@code{/}@var{denominator} @code{;}
@end example
See the documentation of @code{timeSignatureFraction}
-@unnumberedsubsec Tempo
-@cindex beats per minute
-@cindex metronome marking
-@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.
-@unnumberedsubsec Partial measures
+@c_ {Partial}
+@subsubsection Partial
+@cindex Partial
@cindex anacrusis
@cindex upstep
@cindex partial measure
See the documentation of @code{measurePosition}.
-@unnumberedsubsec Bar check
-
-@cindex bar check
-@cindex @code{barCheckNoSynchronize}
-@cindex @code{|}
-
-
-Bar checks help you find errors in the input: Whenever one is
-encountered during interpretation, a warning message is issued if it
-doesn't fall at a measure boundary. Depending on the value of
-@code{barCheckNoSynchronize}, the beginning of the measure will be
-relocated, so this can also be used to shorten measures.
-A bar check is entered using the bar symbol, @code{|}
-This can help you finding errors in the input.
+@c_ {Spanners}
+@node Spanners
+@subsection Spanners
+@cindex Spanners
-@unnumberedsubsec Line break penalty.
-@cindex @code{\penalty}
+@menu
+* Beam::
+* Slur::
+* Tie::
+* Tuplet::
+* Volta::
+* Crescendo and Decrescendo::
+* Text spanner::
+* Ottava::
+* Span requests::
+@end menu
+@c_ {Beam}
+@node Beam
+@subsubsection Beam
+@cindex Beam
+@c_ {Automatic beams}
+@unnumberedsubsubsec Automatic beams
-@example
- \penalty @var{int} @code{;}
-@end example
+@cindex automatic beam generation
+@cindex autobeam
-Discourage or encourage line breaks. See @ref{Page layout}.
+@cindex @code{Voice.noAutoBeaming}
-@unnumberedsubsec Clef change
-@cindex @code{\clef}
-@example
- \clef @var{clefname} @code{;}
-@end example
+By default, LilyPond will generate beams automatically. This feature
+can be disabled by setting the @code{Voice.noAutoBeaming} property to
+true. It can be overridden for specific cases by specifying explicit
+beams.
-Short-cut for
+@cindex @code{Voice.autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+A large number of Voice properties are used to decide how to generate
+beams. Their default values appear in @file{scm/auto-beam.scm}. In
+general, beams can begin anywhere, but their ending location is
+significant. Beams can end on a beat, or at durations specified by the
+properties in
+@code{Voice.autoBeamSettings}.
+To end beams every quarter note, for example, you could set the property
+@code{(end * * * *)} to @code{(make-moment 1
+4)}. To end beams at every three eighth notes you would set
+it to @code{(make-moment 1 8)}.
+The same syntax can be used to specify beam
+starting points using
+@code{(begin * * * *)}, eg:
+@quotation
@example
- \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}
+\property Voice.autoBeamSettings \override
+ #'(end * * * *) = #(make-moment 1 4)
+\property Voice.autoBeamSettings \override
+ #'(begin * * * *) = #(make-moment 1 8)
@end example
+@end quotation
-Supported clef-names include
+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 * *)}.
-[todo]
+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.
-@unnumberedsubsec Skip
-@example
- \skip @var{duration} @code{;}
-@end example
-@cindex @code{\skip}
+For example, to specify beam endings for beams that contain 32nd notes,
+you would use @code{(end * * 1 32)}.
-Skips the amount of time specified by @var{duration}. If no other
-music is played, a gap will be left for the skipped time with no
-notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
-this has the same effect as the spacer rest.
-@node Manual beams
-@unnumberedsubsec Manual beams
+@c_ {Manual beams}
+@cindex Automatic beams
+@unnumberedsubsubsec Manual beams
@cindex beams, manual
@cindex @code{]}
@cindex @code{[}
+FIXME
+Beaming can be generated automatically; see section @ref{Automatic Beaming}.
+
A beam is specified by surrounding the beamed notes with brackets
`@code{[}' and `@code{]}'.
\times 2/3 { [e'8 f' g'] }
@end lilypond
-Beaming can be generated automatically; see section @ref{Automatic Beaming}.
@cindex @code{-}@code{-}
-@unnumberedsubsec Lyric extender
-@cindex extender
-@cindex lyric extender
-@cindex hyphen
-The syntax for an extender mark is @code{__}. This syntax can only
-be used within lyrics mode.
+@c_ {Adjusting beams}
+@unnumberedsubsubsec Adjusting beams
+@cindex Adjusting beams
-@unnumberedsubsec Lyric hyphens
-The syntax for a spanning hyphen (i.e., a hyphen that will be printed
-between two lyric syllables) is `@code{-}@code{-}'.
+@c_ {Slur}
+
+@node Slur
+@subsubsection Slur
+@cindex Slur
+
+@cindex slur
+
+Slurs connects chords and try to avoid crossing stems. A slur is
+started with @code{(} and stopped with @code{)}. The
+starting @code{(} appears to the right of the first note in
+the slur. The terminal @code{)} appears to the left of the
+first note in the slur. This makes it possible to put a note in
+slurs from both sides:
+
+@lilypond[fragment,verbatim,center]
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
+@end lilypond
-@unnumberedsubsec Ties
+
+@c_ {Adjusting slurs}
+@unnumberedsubsubsec Adjusting slurs
+@c_ {Tie}
+@cindex Adusting slurs
+@node Tie
+@subsubsection Tie
+
+@cindex Tie
@cindex ties
@cindex @code{~}
[sparseTies]
-@unnumberedsubsec Articulation
+
+@c_ {Tuplet}
+@node Tuplet
+@subsubsection Tuplet
+@cindex Tuplet
+
+See @ref{Times}.
+
+@c_ {Volta}
+@node Volta
+@subsubsection Volta
+@cindex Volta
+
+See @ref{Repeat}.
+
+@c_ {Crescendo and Decrescendo}
+@node Crescendo and Decrescendo
+@subsubsection Crescendo and Decrescendo
+@cindex Crescendo and Decrescendo
+@cindex crescendo
+@cindex @code{\cr}
+@cindex @code{\rc}
+@cindex @code{\decr}
+@cindex @code{\rced}
+@cindex @code{\<}
+@cindex @code{\>}
+@cindex @code{\"!}
+
+
+
+A crescendo mark is started with @code{\cr} and terminated with
+@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
+started with @code{\decr} and terminated with @code{\rced}. There are
+also shorthands for these marks. A crescendo can be started with
+@code{\<} and a decrescendo can be started with @code{\>}. Either one
+can be terminated with @code{\!}. Note that @code{\!} must go before
+the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
+after the last note. Because these marks are bound to notes, if you
+want to get several marks during one note, you must use spacer notes.
+
+@lilypond[fragment,verbatim,center]
+ c'' \< \! c'' d'' \decr e'' \rced
+ < f''1 { s4 \< \! s2 \> \! s4 } >
+@end lilypond
+
+[todo: text cr]
+
+
+@c_ {Text spanner}
+@node Text spanner
+@subsubsection Text spanner
+@cindex Text spanner
+
+Have crescendo set a text spanner instead of hairpin
+
+@lilypond[fragment,relative,verbatim]
+ \context Voice {
+ \property Voice.crescendoText = "cresc."
+ \property Voice.crescendoSpanner = #'dashed-line
+ a''2\mf\< a a \!a
+ }
+@end lilypond
+
+@c_ {Ottava}
+@node Ottava
+@subsubsection Ottava
+@cindex Ottava
+@unnumberedsubsubsec Ottava
+
+@lilypond[fragment,relative,verbatim]
+ a'''' b c a
+ \property Voice.TextSpanner \set #'type = #'dotted-line
+ \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
+ \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
+ \property Staff.centralCPosition = #-13
+ a\spanrequest \start "text" b c a \spanrequest \stop "text"
+@end lilypond
+
+
+
+@c_ {Text crescendo and decrescendo}
+@unnumberedsubsubsec Text crescendo and decrescendo
+
+TODO
+
+@c_ {Span requests}
+@node Span requests
+@subsubsection Span requests
+@cindex Span requests
+
+@cindex @code{\spanrequest}
+
+@example
+ \spanrequest @var{startstop} @var{type}
+@end example
+@cindex @code{\start}
+@cindex @code{\stop}
+
+Define a spanning request. The @var{startstop} parameter is either -1
+(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
+describes what should be started. Supported types are @code{crescendo},
+@code{decrescendo}, @code{beam}, @code{slur}. This is an internal
+command. Users should use the shorthands which are defined in the
+initialization file @file{spanners.ly}.
+
+You can attach a (general) span request to a note using
+
+@lilypond[fragment,verbatim,center]
+ c'4-\spanrequest \start "slur"
+ c'4-\spanrequest \stop "slur"
+@end lilypond
+
+The slur syntax with parentheses is a shorthand for this.
+
+
+@c_ {Ornaments}
+@node Ornaments
+@subsection Ornaments
+@cindex Ornaments
+@menu
+* Articulation::
+* Text scripts::
+* Grace notes::
+* Stem tremolo::
+* Arpeggio::
+* Glissando ::
+* Dynamics::
+* Bar lines::
+* Breath marks::
+* Rehearsal marks::
+@end menu
+
+@c_ {Articulation}
+@node Articulation
+@subsubsection Articulation
+@cindex Articulation
+
@cindex articulations
@cindex scripts
@cindex ornaments
@end lilypond
-@unnumberedsubsec Text scripts
+@c_ {Text scripts}
+@node Text scripts
+@subsubsection Text scripts
+@cindex Text scripts
+
+FIXME: markup
In addition, it is possible to place arbitrary strings of text or
@TeX{} above or below notes by using a string instead of an
appear in the printed output but have no effect on the MIDI rendering of
the music.
-@cindex fingering
+@c_ {Fingerings}
+@unnumberedsubsubsec Fingerings
+@cindex Fingerings
To save typing, fingering instructions (digits 0 to 9 are
supported) and single characters shorthands exist for a few
-@unnumberedsubsec Dynamics
-
-@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}
-@cindex crescendo
-@cindex @code{\cr}
-@cindex @code{\rc}
-@cindex @code{\decr}
-@cindex @code{\rced}
-@cindex @code{\<}
-@cindex @code{\>}
-@cindex @code{\"!}
-
-Dynamic marks are specified by using an identifier after a note:
-@code{c4-\ff} (the dash is optional for dynamics: `@code{c4 \ff})'.
-The available dynamic marks are:
-@code{\ppp},
-@code{\pp}, @code{\p}, @code{\mp},
-@code{\mf}, @code{\f}, @code{\ff},
-@code{\fff}, @code{\fff},
-@code{\fp}, @code{\sf},
-@code{\sff}, @code{\sp},
-@code{\spp}, @code{\sfz}, and
-@code{\rfz}.
-
-
-A crescendo mark is started with @code{\cr} and terminated with
-@code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
-started with @code{\decr} and terminated with @code{\rced}. There are
-also shorthands for these marks. A crescendo can be started with
-@code{\<} and a decrescendo can be started with @code{\>}. Either one
-can be terminated with @code{\!}. Note that @code{\!} must go before
-the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
-after the last note. Because these marks are bound to notes, if you
-want to get several marks during one note, you must use spacer notes.
-
-@lilypond[fragment,verbatim,center]
- c'' \< \! c'' d'' \decr e'' \rced
- < f''1 { s4 \< \! s2 \> \! s4 } >
-@end lilypond
-
-[todo: text cr]
-
-@unnumberedsubsec Slurs
-@cindex slur
-
-Slurs connects chords and try to avoid crossing stems. A slur is
-started with @code{(} and stopped with @code{)}. The
-starting @code{(} appears to the right of the first note in
-the slur. The terminal @code{)} appears to the left of the
-first note in the slur. This makes it possible to put a note in
-slurs from both sides:
-
-@lilypond[fragment,verbatim,center]
- f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
-@end lilypond
-
-
-@unnumberedsubsec Spanners
-@cindex @code{\spanrequest}
-
-@example
- \spanrequest @var{startstop} @var{type}
-@end example
-@cindex @code{\start}
-@cindex @code{\stop}
-
-Define a spanning request. The @var{startstop} parameter is either -1
-(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
-describes what should be started. Supported types are @code{crescendo},
-@code{decrescendo}, @code{beam}, @code{slur}. This is an internal
-command. Users should use the shorthands which are defined in the
-initialization file @file{spanners.ly}.
-
-You can attach a (general) span request to a note using
-@lilypond[fragment,verbatim,center]
- c'4-\spanrequest \start "slur"
- c'4-\spanrequest \stop "slur"
-@end lilypond
+@c_ {Grace notes}
+@node Grace notes
+@subsubsection Grace notes
+@cindex Grace notes
-The slur syntax with parentheses is a shorthand for this.
+See @ref{Grace music}.
+@c_ {Stem tremolo}
@node Stem tremolo
-@section Stem tremolo
+@subsubsection Stem tremolo
@cindex tremolo marks
@cindex @code{tremoloFlags}
c'2:8 c':32
@end lilypond
-@section Arpeggio
-@cindex argepeggio
+
+@c_ {Arpeggio}
+@node Arpeggio
+@subsubsection Arpeggio
+@cindex Arpeggio
@cindex broken arpeggio
@cindex @code{\arpeggio}
@end lilypond
@end quotation
-@section Glissando
-@cindex glissando
+
+@c_ {Glissando}
+@node Glissando
+@subsubsection Glissando
+@cindex Glissando
+
@cindex @code{\glissando}
A @rgrob{Glissando} line can be requested by issuing a
Printing of the additional text @samp{gliss.} must be done manually.
-@subsection Follow Thread
+@c_ {Follow Thread}
+@subsubsection Follow Thread
@cindex follow thread
@cindex staff switching
@cindex cross staff
@end lilypond
@end quotation
-@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 {
- <a c'> <b d' > <c' e'>
- < { a b c' } { c' d' e' } >
- }
-@end lilypond
-
-@cindex @code{\context}
-@cindex context selection
-@example
- \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
-@end example
+@c_ {Dynamics}
+@node Dynamics
+@subsubsection Dynamics
+@cindex Dynamics
-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.
+@unnumberedsubsec Dynamics
-@cindex input modes
+@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}
-@cindex mode switch
+Dynamic marks are specified by using an identifier after a note:
+@code{c4-\ff} (the dash is optional for dynamics: `@code{c4 \ff})'.
+The available dynamic marks are:
+@code{\ppp},
+@code{\pp}, @code{\p}, @code{\mp},
+@code{\mf}, @code{\f}, @code{\ff},
+@code{\fff}, @code{\fff},
+@code{\fp}, @code{\sf},
+@code{\sff}, @code{\sp},
+@code{\spp}, @code{\sfz}, and
+@code{\rfz}.
-@cindex @code{\notes}
-@cindex @code{\chords}
-@cindex @code{\lyrics}
+See also @ref{Crescendo and Decrescendo}
-Mode switching keywords form compound music expressions: @code{\notes}
-@var{musicexpr}, @code{\chords} @var{musicexpr},
-and @code{\lyrics} @var{musicexpr}. These
-expressions do not add anything to the meaning of their arguments. They
-are just a way to indicate that the arguments should be parsed in
-indicated mode. See @ref{Lexical modes} for more information on modes.
-[to lexer modes?]
+@c_ {Bar lines}
+@node Bar lines
+@subsubsection Bar lines
+@cindex Bar lines
-@unnumberedsubsec Sequential music
-@cindex @code{\sequential}
-@cindex sequential music
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
@example
- \sequential @code{@{} @var{musicexprlist} @code{@}}
+ \bar @var{bartype};
@end example
-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:
-
+This is a short-cut for doing
@example
-@cindex @code{<}
-@cindex @code{>}
-
- @code{@{} @var{musicexprlist} @code{@}}
+ \property Score.whichBar = @var{bartype}
@end example
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeat}, @ref{Volta}, and the documentation of @code{whichBar} in
+@ref{(lilypond-internals)LilyPond context properties}.
-@unnumberedsubsec Simultaneous music
-@cindex simultaneous music
-@cindex @code{\simultaneous}
+[FIXME]
-@example
- \simultaneous @code{@{} @var{musicexprlist} @code{@}}
-@end example
+@c_ {Breath marks}
+@node Breath marks
+@subsubsection Breath marks
+@cindex Breath marks
-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:
+@c_ {Rehearsal marks}
+@node Rehearsal marks
+@subsubsection Rehearsal marks
+@cindex Rehearsal marks
+@cindex mark
+@cindex @code{\mark}
@example
- @code{<} @var{musicexprlist} @code{>}
+ \mark @var{unsigned};
+@cindex @code{Mark_engraver}
+ \mark @var{string};
@end example
-If you try to use a chord as the first thing in your score, you might
-get multiple staffs instead of a chord.
-
-@lilypond[verbatim,center]
- \score {
- \notes <c''4 e''>
- \paper {
- linewidth = -1.;
- }
- }
-@end lilypond
+Prints a mark over or under the staff.
-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
+@c_ {Bar check}
+@node Bar check
+@subsection Bar check
+@cindex Bar check
+@cindex bar check
+@cindex @code{barCheckNoSynchronize}
+@cindex @code{|}
+Bar checks help you find errors in the input: Whenever one is
+encountered during interpretation, a warning message is issued if it
+doesn't fall at a measure boundary. Depending on the value of
+@code{barCheckNoSynchronize}, the beginning of the measure will be
+relocated, so this can also be used to shorten measures.
-@node Relative octaves
-@section Relative octaves
-@cindex relative octave specification
+A bar check is entered using the bar symbol, @code{|}
-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.
+This can help you finding errors in the input.
-@cindex @code{\relative}
-@example
- \relative @var{startpitch} @var{musicexpr}
-@end example
-The octave of notes that appear in @var{musicexpr} are calculated as
-follows: If no octave changing marks are used, the basic interval
-between this and the last note is always taken to be a fourth or
-less.@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}.
+@c_ {Lyrics entry}
+@node Lyrics entry
+@section Lyrics entry
+@cindex Lyrics entry
-Entering scales is straightforward in relative mode.
+@menu
+* Lyrics mode::
+* Printing lyrics::
+* Lyric hyphen::
+* Lyric extender::
+* Addlyrics::
+@end menu
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c d e f g a b c c,
- }
-@end lilypond
+@c_ {Lyrics mode}
+@node Lyrics mode
+@subsection Lyrics mode
+@cindex Lyrics mode
-And octave changing marks are used for intervals greater than a fourth.
+@cindex lyric mode
+@cindex @code{\lyrics}
+
+Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
+rules that make it easy to include punctuation and diacritical marks in
+words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
+format or a standard encoding without needing quotes. The precise
+definition of this mode is ludicrous, and this will remain so until the
+authors of LilyPond acquire a deeper understanding of character
+encoding, or someone else steps up to fix this.
+
+A word in Lyrics mode begins with: an alphabetic character, @code{_},
+@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
+through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
+any 8-bit character with ASCII code over 127, or a two-character
+combination of a backslash followed by one of @code{`}, @code{'},
+@code{"}, or @code{^}.
+
+Subsequent characters of a word can be any character that is not a digit
+and not white space. One important consequence of this is that a word
+can end with `@code{@}}', which may be confusing. However, LilyPond will
+issue a warning. Any @code{_} character which appears in an unquoted
+word is converted to a space. This provides a mechanism for introducing
+spaces into words without using quotes. Quoted words can also be used
+in Lyrics mode to specify words that cannot be written with the above
+rules. Here are some examples. Not all of these words are printable by
+@TeX{}.
+
+@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.
+
+[todo: include short table showing differences]
+
+@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_ {Printing Lyrics}
+@node Printing lyrics
+@subsection lyricprint
+@cindex lyrics
+
+
+@cindex printing!lyrics
+
+
+Lyric syllables must be interpreted within a @code{Lyrics} context
+
+@cindex context!Lyrics
+ for printing them.
+
+Here is a full example:
+
+@quotation
+@lilypond[verbatim]
+\score {
+ <
+ \notes \transpose c'' {
+ c d e c | c d e c |
+ e f g2 | e4 f g2 \bar "|.";
+ }
+ \context Lyrics \lyrics {
+ Va-4 der Ja- cob Va- der Ja- cob
+ Slaapt gij nog?2 Slaapt4 gij nog?2
+ }
+ >
+}
-@lilypond[fragment,verbatim,center]
- \relative c'' {
- c g c f, c' a, e'' }
@end lilypond
+@end quotation
-If the preceding item is a chord, the first note of the chord is used
-to determine the first note of the next chord. But other notes
-within the second chord are determined by looking at the immediately
-preceding note.
+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{_}).
-@lilypond[fragment,verbatim,center]
- \relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
- }
-@end lilypond
-@cindex @code{\notes}
+@quotation
-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).
+@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 __
+ }
+ >
+}
-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}.
+@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:
+
+@quotation
+
+@lilypond[verbatim]
+\score {
+ <
+ \notes \transpose c'' {
+ c d e c | c d e c |
+ e f g2 | e4 f g2 \bar "|.";
+ }
+ \context Lyrics \lyrics {
+ Va4 -- der Ja -- cob | Va -- der Ja -- cob |
+ Slaapt gij nog?2 | Slaapt4 gij nog?2
+ }
+ >
+}
+
+@end lilypond
+@end quotation
+
+
+
+
+@c_ {Lyric hyphen}
+@node Lyric hyphen
+@subsection Lyric hyphen
+@cindex Lyric hyphen
+
+The syntax for a spanning hyphen (i.e., a hyphen that will be printed
+between two lyric syllables) is `@code{-}@code{-}'.
+
+@c_ {Lyric extender}
+@node Lyric extender
+@subsection Lyric extender
+@cindex Lyric extender
+@cindex extender
+@cindex lyric extender
+@cindex hyphen
+
+The syntax for an extender mark is @code{__}. This syntax can only
+be used within lyrics mode.
+
+
+
+
+@c_ {Addlyrics}
+@node Addlyrics
+@subsection Addlyrics
+@cindex Addlyrics
+
+
+[explain automatic phrasing]
+@cindex automatic lyric durations
+@cindex @code{\addlyrics}
+
+If you have lyrics that are set to a melody, you can import the rhythm
+of that melody into the lyrics using @code{\addlyrics}. The syntax for
+this is
+@example
+ \addlyrics @var{musicexpr1 musicexpr2}
+@end example
+
+This means that both @var{musicexpr1} and @var{musicexpr2} are
+interpreted, but that every non-command atomic music expression
+(``every syllable'') in @var{musicexpr2} is interpreted using timing
+of @var{musicexpr1}.
+@cindex @code{automaticMelismata}
+
+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'' {
+ \property Voice.automaticMelismata = ##t
+ c8 () cis d8. e16 f2
+}
+\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:
+
+@quotation
+@lilypond[verbatim,fragment]
+\addlyrics
+\transpose c'' {
+ c8 () cis d8. e16 f2
+}
+\context Lyrics \lyrics
+< { do4 re mi fa }
+ { do8 re mi fa } >
+
+@end lilypond
+@end quotation
+
+It is valid (but probably not very useful) to use notes instead of
+lyrics for @var{musicexpr2}.
-It is strongly recommended to use relative pitch mode: less work,
-less error-prone, and more readable.
+
+@c_ {Chord entry}
+@node Chord entry
+@section Chord entry
+@cindex Chord entry
+
+@menu
+* Chords mode::
+* Entering named chords::
+* Printing named chords::
+@end menu
+
+@c_ {Chords mode}
+@node Chords mode
+@subsection Chords mode
+@cindex Chords mode
+
+Chord mode is introduced by the keyword
+@code{\chords}. It is similar to Note mode, but
+words are also looked up in a chord modifier table (containing
+@code{maj}, @code{dim}, etc).
+
+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.
+
+@c_ {Entering named chords}
@node Entering named chords
-@unnumberedsubsec named chords
+@subsection Entering named chords
+@cindex Chords names
Chord names are a way to generate simultaneous music expressions that
correspond with traditional chord names. It can only be used in
You should not combine @code{\relative} with named chords. [FIXME]
+@c_ {Printing named chords}
+@node Printing named chords
+@subsection Printing named chords
-@unnumberedsubsec Tuplets
-@cindex tuplets
+@cindex chord names
+@cindex chords
-Tuplets are made out of a music expression by multiplying their
-duration with a fraction.
+@cindex printing!chord names
+@cindex @code{ChordNames}
+@cindex @code{ChordNameVoice}
-@cindex @code{\times}
-@example
- \times @var{fraction} @var{musicexpr}
-@end example
+For displaying printed chord names, use the @code{ChordNames} and
+@code{ChordNameVoice} contexts. The chords may be entered either using
+the notation described above, or directly using simultaneous music.
-The duration of @var{musicexpr} will be multiplied by the fraction.
-In print, the fraction's denominator will be printed over the notes,
-optionally with a bracket. The most common tuplet is the triplet in
-which 3 notes have the length of 2, so the notes are 2/3 of
-their written length:
-
-@lilypond[fragment,verbatim,center]
- g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@quotation
+@lilypond[verbatim]
+scheme = \notes {
+ \chords {a1 b c} <d f g> <e g b>
+}
+\score {
+ \notes<
+ \context ChordNamesVoice \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper { linewidth = -1.; }
+}
@end lilypond
-@cindex @code{\grace}
-
-
-@unnumberedsubsec Grace notes
-
-@cindex ornaments
-@cindex grace notes
-@cindex @code{graceAlignPosition}
-
-@example
- \grace @var{musicexpr}
-@end example
-
-A grace note expression has duration 0; the next real note is
-assumed to be the main note.
-
-You cannot have the grace note after the main note, in terms of
-duration, and main notes, but you can typeset the grace notes to the
-right of the main note using the property
-@code{graceAlignPosition}.
-@cindex @code{flagStyle}
+@end quotation
-When grace music is interpreted, a score-within-a-score is set up:
-@var{musicexpr} has its own time bookkeeping, and you could (for
-example) have a separate time signature within grace notes. While in
-this score-within-a-score, you can create notes, beams, slurs, etc.
-Unbeamed eighth notes and shorter by default have a slash through the
-stem. This behavior can be controlled with the
-@code{flagStyle} property.
+You can make the chord changes stand out more by setting property
+@code{ChordNames.chordChanges} to true. This will only display chord
+names when there's a change in the chords scheme, but always display the
+chord name after a line break:
+@c bug
@quotation
-@lilypond[fragment,verbatim]
-\relative c'' {
- \grace c8 c4 \grace { [c16 c16] } c4
- \grace { \property Grace.flagStyle = "" c16 } c4
+@lilypond[verbatim]
+scheme = \chords {
+ c1:m \break c:m c:m c:m d
}
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper{
+ linewidth = 40 * \staffspace;
+ \translator {
+ \ChordNamesContext
+ chordChanges = ##t
+ }
+ }
+}
@end lilypond
@end quotation
-@cindex @code{\grace}
-
-At present, nesting @code{\grace} notes is not supported. The following
-may cause run-time errors:
-@example
- @code{\grace @{ \grace c32 c16 @} c4}
-@end example
-Since the meaning of such a construct is unclear, we don't consider
-this a loss. Similarly, juxtaposing two @code{\grace} sections is
-syntactically valid, but makes no sense and may cause runtime errors.
-
-Ending a staff or score with grace notes may also generate a run-time
-error, since there will be no main note to attach the grace notes to.
-
-The present implementation is not robust and generally kludgy. We expect
-it to change after LilyPond 1.4
-
-
-@node Repeats
-@section Repeats
-@cindex repeats
-
-@cindex @code{\repeat}
-
-In order to specify repeats, use the @code{\repeat}
-keyword. Since repeats look and sound differently when played or
-printed, there are a few different variants of repeats.
-
-@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.
-@end table
-
-The syntax for repeats is
-
-@example
- \repeat @var{variant} @var{repeatcount} @var{repeatbody}
-@end example
-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.
-Normal notation repeats are used like this:
+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:
@quotation
+@lilypond[verbatim,center]
+scheme = \notes {
+ <c'1 e' g'>
+ <e' g' c''>
+ <e e' g' c''>
+}
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 { c'4 d' e' f' }
- \repeat volta 2 { f' e' d' c' }
-
+\score {
+ <
+ \context ChordNamesVoice \scheme
+ \context Staff \scheme
+ >
+ \paper { linewidth = -1.; }
+}
@end lilypond
@end quotation
-With alternative endings:
+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
+}
-@lilypond[fragment,verbatim]
- c'1
- \repeat volta 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
-
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper { linewidth = -1.; }
+}
@end lilypond
@end quotation
-Folded repeats look like this:@footnote{Folded repeats offer little
-more over simultaneous music. However, it is to be expected that
-more functionality -- especially for the MIDI backend -- will be
-implemented.}
-
-@quotation
-
-@lilypond[fragment,verbatim]
- c'1
- \repeat fold 2 {c'4 d' e' f'}
- \alternative { {d'2 d'} {f' f} }
-
-@end lilypond
-@end quotation
+The chord names that LilyPond should print are fully customizable. The
+code to print chord names is written in Scheme. It can be found in
+@file{scm/chord-name.scm}. Chord names are based on Banter style
+naming, which is unambiguous and has a logical structure. Typical
+American style chord names are implemented as a variation on Banter
+names, they can be selected by setting property @code{ChordName.style}
+to @code{american}:
@quotation
+@lilypond[verbatim]
+\include "english.ly"
-@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 } }
- }
+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
}
-@end lilypond
-@end quotation
-
-If you don't give enough alternatives for all of the repeats, then
-the first alternative is assumed to be repeated often enough to equal
-the specified number of repeats.
-
-@quotation
-@lilypond[fragment,verbatim]
-\context Staff {
- \relative c' {
- \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
- \alternative { { g4 g g }
- {\partial 1; e4 e e }
- {\partial 1; a a a a | b1 } }
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
+ \paper {
+ \translator {
+ \ChordNamesContext
+ ChordName \override #'word-space = #1
+ ChordName \override #'style = #'american
+ }
}
}
@end lilypond
@end quotation
-As you can see, LilyPond doesn't remember the timing information, nor
-are slurs or ties repeated. We hope to fix this after 1.4.
-
-It is possible to nest @code{\repeat}. This is not entirely
-supported: the notes will come be in the right places, but the repeat
-bars will not.
+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
-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.
+ % 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
-@lilypond[verbatim,center]
-\score {
- \context Voice \notes\relative c' {
- \repeat "tremolo" 8 { c16 d16 }
- \repeat "tremolo" 4 { c16 d16 }
- \repeat "tremolo" 2 { c16 d16 }
- }
+ % dominant chords
+ c:7 % 7 = dominant
+ c:7.5+ % +7 = augmented dominant
+ c:7.5- % 7b5 = hard diminished dominant
+ c:9 % 7(9)
+ c:9- % 7(b9)
+ c:9+ % 7(#9)
+ c:13^9.11 % 7(13)
+ c:13-^9.11 % 7(b13)
+ c:13^11 % 7(9,13)
+ c:13.9-^11 % 7(b9,13)
+ c:13.9+^11 % 7(#9,13)
+ c:13-^11 % 7(9,b13)
+ c:13-.9-^11 % 7(b9,b13)
+ c:13-.9+^11 % 7(#9,b13)
+
+ % half diminished chords
+ c:m5-.7 % slashed o = m7b5
+ c:9.3-.5- % o/7(pure 9)
+
+ % diminished chords
+ c:m5-.7- % o = diminished seventh chord
+}
+
+\score {
+ \notes <
+ \context ChordNames \scheme
+ \context Staff \transpose c'' \scheme
+ >
\paper {
- linewidth = 40*\staffspace;
- }
+ \translator {
+ \ChordNamesContext
+ ChordName \override #'word-space = #1
+ ChordName \override #'style = #'jazz
+ }
+ }
}
@end lilypond
-@cindex @code{__}
+@end quotation
-@lilypond[fragment,verbatim,center]
- c'4:32
-@end lilypond
+@c_ {Page layout}
+@node Page layout
+@section Page layout
+@cindex Page layout
+@menu
+* Paper block::
+* Paper variables::
+* Font Size::
+* Paper size::
+* Line break::
+* Page break::
+@end menu
+@c_ {Paper block}
+@node Paper block
+@subsection Paper block
+@cindex Paper block
-@node transpose
-@section Transposition
-@cindex transposition of pitches
-@cindex @code{\transpose}
+The most important output definition is the @code{\paper} block, for
+music notation. The syntax is
-A music expression can be transposed with @code{\transpose}. The syntax
-is
@example
- \transpose @var{pitch} @var{musicexpr}
+ @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
@end example
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
-
-@code{\transpose} distinguishes between enharmonic pitches: both
-@code{\transpose cis'} or @code{\transpose des'} will transpose up half
-a tone. The first version will print sharps and the second version
-will print flats.
+where each of the items is one of
-@quotation
-@lilypond[fragment,verbatim]
-\context Staff {
- \clef "F";
- { \key e \major; c d e f }
- \clef "G";
- \transpose des'' { \key e \major; c d e f }
- \transpose cis'' { \key e \major; c d e f }
-}
+@itemize @bullet
+ @item An assignment. The assignment must be terminated by a
+ semicolon.
-@end lilypond
-@end quotation
+ @item A context definition. See section @ref{contextdefs} for
+ more information on context definitions.
-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}.
+@ignore
-@unnumberedsubsec Adding melodies to lyrics
-@cindex automatic lyric durations
-@cindex @code{\addlyrics}
+ FIXME
-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
-This means that both @var{musicexpr1} and @var{musicexpr2} are
-interpreted, but that every non-command atomic music expression
-(``every syllable'') in @var{musicexpr2} is interpreted using timing
-of @var{musicexpr1}.
-@cindex @code{automaticMelismata}
+ @item
+
+ A margin shape declaration. The syntax is
+@cindex @code{\shape}
+ @example
-If the property @code{automaticMelismata} is set in the
-context of @var{musicexpr1}, no lyrics will be put on slurred or tied
-notes.
+ \shape @var{indent1}@code{,} @var{width1}@code{,}
+ @var{indent2}@code{,} @var{width2} @dots{} @code{;}
+ @end example
-@quotation
-@lilypond[verbatim,fragment]
-\addlyrics
-\transpose c'' {
- \property Voice.automaticMelismata = ##t
- c8 () cis d8. e16 f2
-}
-\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:
+ 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
-@quotation
-@lilypond[verbatim,fragment]
-\addlyrics
-\transpose c'' {
- c8 () cis d8. e16 f2
-}
-\context Lyrics \lyrics
-< { do4 re mi fa }
- { do8 re mi fa } >
+ @item \stylesheet declaration. Its syntax is
+ @example
+ \stylesheet @var{alist}
+ @end example
-@end lilypond
-@end quotation
+ See @file{font.scm} for details of @var{alist}.
+@end itemize
-It is valid (but probably not very useful) to use notes instead of
-lyrics for @var{musicexpr2}.
+@c_ {Paper variables}
+@node Paper variables
+@subsection Paper variables
+@cindex Paper variables
-@node Transforming music
-@unnumberedsubsec Apply
-@unnumberedsubsec Transforming music
+The paper block has some variables you may want to use or change:
-Apply allows a Scheme-function to operate directly on the internal
-representation of music.
-@example
- \apply #@var{func} @var{music}
-@end example
-The function takes two arguments, being a function and an musical
-argument for that function. The function should return a music
-expression.
+@table @code
+@cindex @code{indent}
+ @item @code{indent}
+ The indentation of the first line of music.
+@cindex @code{staffspace}
-This example replaces the text string of a script. It also shows a dump
-of the music it processes.
-@lilypond[verbatim]
-#(define (testfunc x)
- (if (eq? (ly-get-mus-property x 'text) "foo")
- (ly-set-mus-property x 'text "bar"))
- ;; recurse
- (ly-set-mus-property x 'elements
- (map testfunc (ly-get-mus-property x 'elements)))
- (display x)
- x
-)
-\score { \notes
- \apply #testfunc { c4_"foo" }
-}
-@end lilypond
+ @item @code{staffspace}
+ The distance between two staff lines, calculated from the center
+ of the lines. You should use either this or @code{rulethickness}
+ as a unit for distances you modify.
+
+@cindex @code{linewidth}
+ @item @code{linewidth}
+ Sets the width of the lines. If set to -1.0, a single
+ unjustified line is produced. If you use this variable, you
+ probably want to define it in staff spaces, ie
+ @example
+ linewidth = 30 * \staffspace;
+ @end example
+@cindex @code{textheight}
-For more information on what is possible, see the @ref{Tricks} and the
-automatically generated documentation.
+ @item @code{textheight}
+ Sets the total height of the music on each page. Only used by
+ ly2dvi.
+@cindex @code{interscoreline}
+ @item @code{interscoreline}
+ Sets the spacing between the score lines. Defaults to 16 pt.
+@cindex @code{interscorelinefill}
-@node Ambiguities
-@section Ambiguities
-@cindex ambiguities
-@cindex grammar
+ @item @code{interscorelinefill}
+ If set to a positive number, the distance between the score
+ lines will stretch in order to fill the full page. In that
+ case @code{interscoreline} specifies the minimum spacing.
+ Defaults to 0.
+@cindex @code{stafflinethickness}
+ @item @code{stafflinethickness}
+ Determines the thickness of staff lines, and also acts as a scaling
+ parameter for other line thicknesses.
+@end table
-The grammar contains a number of ambiguities. We hope to resolve them at
-some time.
-@itemize @bullet
- @item The assignment
+@c_ {Font size}
+@node Font Size
+@subsection Font size
+@cindex font size
- @example
-foo = bar
-@end example
+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.
- can be interpreted as making a string identifier @code{\foo}
- containing @code{"bar"}, or a music identifier @code{\foo}
- containing the syllable `bar'.
+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.
- @item The assignment
+The font definitions are generated using a Scheme function. For more
+details, see the file @file{font.scm}.
- @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
+@c_ {Paper size}
+@node Paper size
+@subsection Paper size
+@cindex Paper size
- @quotation
+@cindex paper size
+@cindex page size
+@cindex @code{papersize}
-@example
-\repeat @dots{}
-\repeat @dots{}
-\alternative
-@end example
+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.
- @end quotation
+@example
+ papersize = "a4"
+ \include "paper16.ly"
- 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.
+ \score @{
+ ...
+ \paper @{ \paperSixteen @}
+ @}
+@end example
- @item (an as yet unidentified ambiguity :-)
-@end itemize
+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})
-@node Automatic Beaming
-@section Automatic Beaming
-@cindex automatic beam generation
-@cindex autobeam
-@cindex @code{Voice.noAutoBeaming}
-By default, LilyPond will generate beams automatically. This feature
-can be disabled by setting the @code{Voice.noAutoBeaming} property to
-true. It can be overridden for specific cases by specifying explicit
-beams.
-@cindex @code{Voice.autoBeamSettings}
-@cindex @code{(end * * * *)}
-@cindex @code{(begin * * * *)}
-A large number of Voice properties are used to decide how to generate
-beams. Their default values appear in @file{scm/auto-beam.scm}. In
-general, beams can begin anywhere, but their ending location is
-significant. Beams can end on a beat, or at durations specified by the
-properties in
-@code{Voice.autoBeamSettings}.
-To end beams every quarter note, for example, you could set the property
-@code{(end * * * *)} to @code{(make-moment 1
-4)}. To end beams at every three eighth notes you would set
-it to @code{(make-moment 1 8)}.
-The same syntax can be used to specify beam
-starting points using
-@code{(begin * * * *)}, eg:
-@quotation
+@c_ {Line break}
+@node Line break
+@subsection Line break
+@cindex Line break
+
+
+@cindex @code{\penalty}
+
@example
-\property Voice.autoBeamSettings \override
- #'(end * * * *) = #(make-moment 1 4)
-\property Voice.autoBeamSettings \override
- #'(begin * * * *) = #(make-moment 1 8)
+ \penalty @var{int} @code{;}
@end example
-@end quotation
-To allow different settings for different time signatures, instead of
-the first two asterisks @code{* *} you can specify a time signature; use
-@code{(end N M * *)} to restrict the definition to
-`@var{N}@code{/}@var{M}' time. For example, to specify beams ending
-only for 6/8 time you would use the property @code{(end 6 8 * *)}.
+Discourage or encourage line breaks. See @ref{Page layout}.
-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)}.
-@node Printing named chords
-@section Printing named chords
-@cindex chord names
-@cindex chords
+@cindex line breaks
+@cindex breaking lines
-@cindex printing!chord names
-@cindex @code{ChordNames}
-@cindex @code{ChordNameVoice}
+Line breaks are normally computed automatically. They are chosen such
+that the resulting spacing has low variation, and looks neither cramped
+nor loose.
-For displaying printed chord names, use the @code{ChordNames} and
-@code{ChordNameVoice} contexts. The chords may be entered either using
-the notation described above, or directly using simultaneous music.
+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 "";}.
-@quotation
-@lilypond[verbatim]
-scheme = \notes {
- \chords {a1 b c} <d f g> <e g b>
-}
-\score {
- \notes<
- \context ChordNamesVoice \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper { linewidth = -1.; }
-}
-@end lilypond
-@end quotation
-You can make the chord changes stand out more by setting property
-@code{ChordNames.chordChanges} to true. This will only display chord
-names when there's a change in the chords scheme, but always display the
-chord name after a line break:
-@c bug
-@quotation
-@lilypond[verbatim]
-scheme = \chords {
- c1:m \break c:m c:m c:m d
-}
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper{
- linewidth = 40 * \staffspace;
- \translator {
- \ChordNamesContext
- chordChanges = ##t
- }
- }
-}
-@end lilypond
-@end quotation
+@c_ {Page break}
+@node Page break
+@subsection Page break
+@cindex Page break
+Not implemented, but see @ref{Tricks}
-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:
+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}
-@quotation
-@lilypond[verbatim,center]
-scheme = \notes {
- <c'1 e' g'>
- <e' g' c''>
- <e e' g' c''>
-}
-\score {
- <
- \context ChordNamesVoice \scheme
- \context Staff \scheme
- >
- \paper { linewidth = -1.; }
-}
-@end lilypond
-@end quotation
+@cindex page breaks
+@cindex breaking pages
-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
-}
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper { linewidth = -1.; }
-}
-@end lilypond
-@end quotation
-The chord names that LilyPond should print are fully customizable. The
-code to print chord names is written in Scheme. It can be found in
-@file{scm/chord-name.scm}. Chord names are based on Banter style
-naming, which is unambiguous and has a logical structure. Typical
-American style chord names are implemented as a variation on Banter
-names, they can be selected by setting property @code{ChordName.style}
-to @code{american}:
-@quotation
-@lilypond[verbatim]
-\include "english.ly"
+@c_ {Sound}
+@node Sound
+@section Sound
+@cindex Sound
+@menu
+* MIDI block::
+* MIDI instrument names::
+* Tempo::
+@end menu
-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
-}
+@c_ {MIDI block}
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper {
- \translator {
- \ChordNamesContext
- ChordName \override #'word-space = #1
- ChordName \override #'style = #'american
- }
- }
-}
-@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
+The MIDI block is analogous to the paper block, but it is somewhat
+simpler. The @code{\midi} block can contain:
+@cindex MIDI block
- % 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
+@itemize @bullet
+ @item a @code{\tempo} definition
+ @item context definitions
+@end itemize
- % 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)
+Assignments in the @code{\midi} block are not allowed.
- % half diminished chords
- c:m5-.7 % slashed o = m7b5
- c:9.3-.5- % o/7(pure 9)
- % diminished chords
- c:m5-.7- % o = diminished seventh chord
-}
-\score {
- \notes <
- \context ChordNames \scheme
- \context Staff \transpose c'' \scheme
- >
- \paper {
- \translator {
- \ChordNamesContext
- ChordName \override #'word-space = #1
- ChordName \override #'style = #'jazz
- }
- }
-}
-@end lilypond
-@end quotation
+@cindex context definition
+Context definitions follow precisely the same syntax as within the
+\paper block. Translation modules for sound are called performers.
+The contexts for MIDI output are defined in @file{ly/performer.ly}.
-@node Printing lyrics
-@section lyricprint
-@cindex lyrics
-@cindex printing!lyrics
+@c_ {MIDI instrument names}
+@node MIDI instrument names
+@subsection MIDI instrument names
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+@cindex @code{Staff.instrument}
+The MIDI instrument name is set by the @code{Staff.midiInstrument}
+property or, if that property is not set, the @code{Staff.instrument}
+property. The instrument name should be chosen from the following list.
+If the selected string does not exactly match, then LilyPond uses the
+default piano.
-Lyric syllables must be interpreted within a @code{Lyrics} context
+[FIXME: to appendix ]
-@cindex context!Lyrics
- for printing them.
-Here is a full example:
+@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_ {Tempo}
+@node Tempo
+@subsection Tempo
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
+
+@cindex @code{\tempo}
+@example
+ \tempo @var{duration} = @var{perminute} @code{;}
+@end example
+
+Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
+output with 76 quarter notes per minute.
+
+
+
+
+
+@c_ {Music entry}
+@node Music entry
+@section Music entry
+@cindex Music entry
+@menu
+* Pre-defined Identifiers::
+* Point and click::
+@end menu
+
+@c_ {Music entry}
+@node Pre-defined Identifiers
+@subsection Pre-defined Identifiers
+@cindex pre-defined identifiers
+
+
+Various identifiers are defined in the initialization files to
+provide shorthands for some settings. Most of them are in
+@file{ly/declarations.ly} and @file{ly/property.ly}.
+
+@table @code
+@cindex @code{\break}
+ @item @code{\break}
+ Force a line break in music by using a large argument for the
+ keyword @code{\penalty}.
+
+@cindex @code{\nobreak}
+ @item @code{\nobreak}
+ Prevent a line break in music by using a large negative argument
+ for the keyword @code{\penalty}.
+
+@cindex @code{\shiftOff}
+ @item @code{\shiftOff}
+ Disable horizontal shifting of note heads that collide.
+
+@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, beams, and slurs to point either upwards or
+ downwards, decided automatically by LilyPond.
+
+@cindex @code{\stemDown}
+ @item @code{\stemDown}
+ Force stems, beams, and slurs to point down.
+
+@cindex @code{\stemUp}
+ @item @code{\stemUp}
+ Force stems, beams and slurs to point up.
+
+@end table
+
+
+@c_ {Point and click}
+@node Point and click
+@subsection Point and click
+
+[todo]
+
+@c_ {Engravers}
+@node Engravers
+@section Engravers
+@cindex engravers
+@menu
+* Context definitions::
+* Notation Contexts::
+@end menu
+
+@c_ {Context definitions}
+@node Context definitions
+@subsection Context definitions
+
+@cindex context definition
+@cindex translator definition
+@cindex engraver hacking
+
+
+A notation contexts is defined by the following information
+
+@enumerate 1
+ @item A name.
+
+ @item The LilyPond modules that do the actual conversion of music to
+ notation. Each module is a so-called
+ @emph{engraver}
+@cindex engraver
+.
+
+ @item How these modules should cooperate, i.e. which ``cooperation
+ module'' should be used. This cooperation module is a special
+ type of engraver.
+
+ @item What other contexts the context can contain,
+
+ @item What properties are defined.
+@end enumerate
+
+A context definition has this syntax:
+
+@example
+
+ \translator @code{@{}
+ @var{translatorinit} @var{translatormodifierlist}
+ @code{@}}
+@end example
+
+@var{translatorinit} can be an identifier or of the form
+
+@example
+
+ \type @var{typename} @code{;}
+@end example
+
+@var{typename} is one of
+
+@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.
+@cindex @code{Grace_engraver_group}
+
+ @item @code{Grace_engraver_group}
+ This is a special cooperation module (resembling
+ @code{Score_engraver}) that is used to created an embedded
+ `miniscore'.
+@end table
+
+@var{translatormodifierlist} is a list of items where each item is
+one of
+
+@itemize @bullet
+ @item @code{\consists} @var{engravername} @code{;}
+ Add @var{engravername} to the list of modules in this context.
+ The order of engravers added with @code{\consists} is
+ significant.
+
+ @item @code{\consistsend} @var{engravername} @code{;}
+ Analogous to @code{\consists}, but makes sure that
+ @var{engravername} is always added to the end of the list of
+ engravers.
+
+ Some engraver types need to be at the end of the list; this
+ insures they are put there, and stay there, if a user adds or
+ removes engravers. This command is usually not needed for
+ end-users.
+
+ @item @code{\accepts} @var{contextname} @code{;}
+ Add @var{contextname} to the list of context this context can
+ contain. The first listed context is the context to create by
+ default.
+
+ @item @code{\denies}. The opposite of @code{\accepts}. Added for
+completeness, but is never used in practice.
+
+
+ @item @code{\remove} @var{engravername} @code{;}
+ Remove a previously added (with @code{\consists}) engraver.
+
+ @item @code{\name} @var{contextname} @code{;}
+ This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
+ the name is not specified, the translator won't do anything.
+
+ @item @var{propname} @code{=} @var{value} @code{;}
+ A property assignment. It is allowed to use reals for
+ @var{value}.
+@end itemize
+
+In the @code{\paper} block, it is also possible to define translator
+identifiers. Like other block identifiers, the identifier can only
+be used as the very first item of a translator. In order to define
+such an identifier outside of @code{\score}, you must do
@quotation
-@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
+@example
+\paper @{
+ foo = \translator @{ @dots{} @}
+@}
+\score @{
+ \notes @{
+ @dots{}
+ @}
+ \paper @{
+ \translator @{ \foo @dots{} @}
+ @}
+@}
+@end example
+
+@end quotation
+
+
+@cindex paper types, engravers, and pre-defined translators
+
+Some pre-defined identifiers can simplify modification of
+translators. The pre-defined identifiers are:
+
+@table @code
+@cindex @code{StaffContext}
+ @item @code{StaffContext}
+ Default Staff context.
+@cindex @code{RhythmicStaffContext}
+
+ @item @code{RhythmicStaffContext}
+ Default RhythmicStaff context.
+@cindex @code{VoiceContext}
+
+ @item @code{VoiceContext}
+ Default Voice context.
+@cindex @code{ScoreContext}
+
+ @item @code{ScoreContext}
+ Default Score context.
+@cindex @code{ScoreWithNumbers}
-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{_}).
+ @item @code{ScoreWithNumbers}
+ Score context with numbering at the Score level.
+@cindex @code{BarNumberingStaffContext}
-@quotation
+ @item @code{BarNumberingStaffContext}
+ Staff context with numbering at the Staff level.
+@cindex @code{HaraKiriStaffContext}
-@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 __
- }
- >
-}
+ @item @code{HaraKiriStaffContext}
+ Staff context that does not print if it only contains rests.
+ Useful for orchestral scores.@footnote{Harakiri, also called
+ Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
+@cindex @code{OrchestralPartStaffContext}
-@end lilypond
-@end quotation
+ @item @code{OrchestralPartStaffContext}
+@cindex @code{OrchestralScoreContext}
-
-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:
+ @item @code{OrchestralScoreContext}
+@end table
+
+Using these pre-defined values, you can remove or add items to the
+translator:
@quotation
-@lilypond[verbatim]
-\score {
- <
- \notes \transpose c'' {
- c d e c | c d e c |
- e f g2 | e4 f g2 \bar "|.";
- }
- \context Lyrics \lyrics {
- Va4 -- der Ja -- cob | Va -- der Ja -- cob |
- Slaapt gij nog?2 | Slaapt4 gij nog?2
- }
- >
-}
+@example
+\paper @{
+ \translator @{
+ \StaffContext
+ \remove Some_engraver;
+ \consists Different_engraver;
+ @}
+@}
+@end example
-@end lilypond
@end quotation
+
+@c_ {Notation Contexts}
@node Notation Contexts
-@section Notation Contexts
+@subsection Notation Contexts
@cindex notation contexts
called @emph{performers}.
-@mbinclude properties.itely
-@node Page layout
-@section Page layout
+@c_ {Lexer innards}
+@node Lexer innards
+@section Lexer innards
+@cindex Lexer innards
+@menu
+* Top level::
+* Identifiers::
+* Assignments::
+* Lexical details::
+* Lexical modes::
+* Ambiguities::
+@end menu
-@subsection Paper block
+@c_ {Top level}
+@node Top level
+@subsection Top level
+@cindex Top level
-The most important output definition is the @code{\paper} block, for
-music notation. The syntax is
+This section describes what you may enter at top level.
+
+
+@unnumberedsubsec Score definition
+@cindex score definition
+
+The output is generated combining a music expression with an output
+definition. A score block has the following syntax:
@example
- @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
+ \score @{ @var{musicexpr} @var{outputdefs} @}
@end example
-where each of the items is one of
+@var{outputdefs} are zero or more output definitions. If no output
+definition is supplied, the default @code{\paper} block will be added.
-@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.
+@c_ {Score}
+@subsubsection Score
+@cindex Score
-@ignore
+@c_ {Paper}
+@subsubsection Paper
+@cindex Paper
- FIXME
+@c_ {Midi}
+@subsubsection Midi
+@cindex Midi
+@c_ {Header}
+@subsubsection Header
+@cindex Header
+@cindex @code{\header}
- @item
-
- A margin shape declaration. The syntax is
-@cindex @code{\shape}
- @example
+The syntax is
- \shape @var{indent1}@code{,} @var{width1}@code{,}
- @var{indent2}@code{,} @var{width2} @dots{} @code{;}
- @end example
+@example
+ \header @{ @var{key1} = @var{val1};
+@cindex @code{ly2dvi}
+ @var{key2} = @var{val2}; @dots{} @}
+@end example
-
- 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
+A header describes the file's contents. It can also appear in a
+@code{\score} block. Tools like @code{ly2dvi} can use this
+information for generating titles. Key values that are used by
+@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
+metre, arranger, piece and tagline.
- @item \stylesheet declaration. Its syntax is
- @example
- \stylesheet @var{alist}
- @end example
+It is customary to put the @code{\header} at the top of the file.
- See @file{font.scm} for details of @var{alist}.
+@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: see @ref{Music expressions}
+@item Identifier
+@item Translator_def:
+See section @ref{contextdefs} for more information
+@item Duration
+@item Pitch
+@item Score
+@item Music_output_def
+@item Moment (rational number)
@end itemize
+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.
-@subsection Paper variables
+@itemize @bullet
+@item Grob: short for Graphical object. See @ref{Grobs}.
+@item Molecule: device-independent page output object,
+including dimensions. Produced by some Grob functions
+See @ref{Molecules}
+@item Translator: object that produces audio objects or Grobs. This is
+not yet user accessible.
+@item Font_metric: object representing a font. (See @ref{Font metrics})
+@c @item Audio_element: (todo, smobme)
+@end itemize
-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}
+@c_ {Assignments}
+@node Assignments
+@subsection Assignments
+@cindex Assignments
- @item @code{staffspace}
- The distance between two staff lines, calculated from the center
- of the lines. You should use either this or @code{rulethickness}
- as a unit for distances you modify.
-
-@cindex @code{linewidth}
- @item @code{linewidth}
- Sets the width of the lines. If set to -1.0, a single
- unjustified line is produced. If you use this variable, you
- probably want to define it in staff spaces, ie
- @example
- linewidth = 30 * \staffspace;
- @end example
-@cindex @code{textheight}
+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.
- @item @code{textheight}
- Sets the total height of the music on each page. Only used by
- ly2dvi.
-@cindex @code{interscoreline}
+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.
- @item @code{interscoreline}
- Sets the spacing between the score lines. Defaults to 16 pt.
-@cindex @code{interscorelinefill}
+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.
- @item @code{interscorelinefill}
- If set to a positive number, the distance between the score
- lines will stretch in order to fill the full page. In that
- case @code{interscoreline} specifies the minimum spacing.
- Defaults to 0.
-@cindex @code{stafflinethickness}
+The right hand side of an identifier assignment is parsed completely
+before the assignment is done, so it is allowed to redefine an
+identifier in terms of its old value, e.g.
- @item @code{stafflinethickness}
- Determines the thickness of staff lines, and also acts as a scaling
- parameter for other line thicknesses.
-@end table
+@example
+foo = \foo * 2.0
+@end example
+
+When an identifier is referenced, the information it points to is
+copied. For this reason, an identifier reference must always be the
+first item in a block.
+@example
+\paper @{
+foo = 1.0
+\paperIdent % wrong and invalid
+@}
+
+\paper @{
+\paperIdent % correct
+foo = 1.0
+@}
+@end example
+
+
+
+@c_ {Lexical details}
+@node Lexical details
+@subsection Lexical details
+@cindex Lexical details
+@menu
+@end menu
+
+@c_ {Comments}
+@subsubsection Comments
+@cindex Comments
+@cindex @code{%}
-@subsection Line breaks
-@cindex line breaks
-@cindex breaking lines
+A one line comment is introduced by a @code{%} character.
+Block comments are started by @code{%@{} and ended by `@code{%@}}'.
+They cannot be nested.
-Line breaks are normally computed automatically. They are chosen such
-that the resulting spacing has low variation, and looks neither cramped
-nor loose.
+@c_ {Direct Scheme}
+@subsubsection Direct Scheme
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
-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 "";}.
+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
-@subsection Page breaks
+@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).
-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}
+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.
-@cindex page breaks
-@cindex breaking pages
+@c_ {Keywords}
+@subsubsection Keywords
+@cindex Keywords
-@subsection Font size
+Keywords start with a backslash, followed by a number of lower case
+alphabetic characters. These are all the keywords.
-@cindex font size
+@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
-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.
+@c_ {Integers}
+@subsubsection Integers
-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.
+@cindex integers
+@cindex @code{+}
+@cindex @code{-}
+@cindex @code{*}
+@cindex @code{/}
-The font definitions are generated using a Scheme function. For more
-details, see the file @file{font.scm}.
+Formed from an optional minus sign followed by digits. Arithmetic
+operations cannot be done with integers, and integers cannot be mixed
+with reals.
-@subsection Paper size
+@c_ {Reals}
+@subsubsection Reals
+@cindex real numbers
-@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"
- \score @{
- ...
- \paper @{ \paperSixteen @}
- @}
-@end example
-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})
+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.
-@node Context definitions
-@section Context definitions
+@cindex @code{\mm},
+@cindex @code{\in}
+@cindex @code{\cm}
+@cindex @code{\pt}
+@cindex dimensions
-@cindex context definition
-@cindex translator definition
-@cindex engraver hacking
+A real constant can be followed by one of the dimension keywords:
+@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
+points, inches and centimeters, respectively. This converts the number
+to a real that is the internal representation of dimensions.
-A notation contexts is defined by the following information
+@c_ {Strings}
+@subsubsection Strings
+@cindex string
+@cindex concatenate
-@enumerate 1
- @item A name.
+Begins and ends with the @code{"} character. To include a @code{"}
+character in a string write @code{\"}. Various other backslash
+sequences have special interpretations as in the C language. A string
+that contains no spaces can be written without the quotes. See
+@ref{Lexical modes} for details on unquoted strings; their interpretation varies
+depending on the situation. Strings can be concatenated with the
+@code{+} operator.
- @item The LilyPond modules that do the actual conversion of music to
- notation. Each module is a so-called
- @emph{engraver}
-@cindex engraver
-.
+The tokenizer accepts the following commands. They have no grammatical
+function, hence they can appear anywhere in the input.
- @item How these modules should cooperate, i.e. which ``cooperation
- module'' should be used. This cooperation module is a special
- type of engraver.
- @item What other contexts the context can contain,
+@c_ {Main input}
+@subsubsection Main input
+@cindex Main input
- @item What properties are defined.
-@end enumerate
+@cindex @code{\maininput}
-A context definition has this syntax:
+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.
-@example
+@c_ {File inclusion}
+@subsubsection Main input
+@cindex Main input
- \translator @code{@{}
- @var{translatorinit} @var{translatormodifierlist}
- @code{@}}
+@subsubsection File inclusion
+@cindex @code{\include}
+@example
+ \include @var{filename}
@end example
-@var{translatorinit} can be an identifier or of the form
+Include @var{filename}. The argument @var{filename} may be a quoted string (an
+unquoted string will not work here!) or a string identifier. The full
+filename including the @file{.ly} extension must be given,
+@subsubsection Version information
+@cindex @code{\version}
@example
-
- \type @var{typename} @code{;}
+ \version @var{string} ;
@end example
-@var{typename} is one of
-
-@table @code
-@cindex @code{Engraver_group_engraver}
- @item @code{Engraver_group_engraver}
- The standard cooperation engraver.
-@cindex @code{Score_engraver}
+Specify the version of LilyPond that a file was written for. The
+argument is a version string in quotes, for example @code{"1.2.0"}.
+This is used to detect invalid input, and to aid
+@code{convert-ly} a tool that automatically upgrades input files. See
+See @ref{convert-ly} for more information on @code{convert-ly}.
- @item @code{Score_engraver}
- This is cooperation module that should be in the top level context.
-@cindex @code{Grace_engraver_group}
+@cindex convert-ly
- @item @code{Grace_engraver_group}
- This is a special cooperation module (resembling
- @code{Score_engraver}) that is used to created an embedded
- `miniscore'.
-@end table
-@var{translatormodifierlist} is a list of items where each item is
-one of
-@itemize @bullet
- @item @code{\consists} @var{engravername} @code{;}
- Add @var{engravername} to the list of modules in this context.
- The order of engravers added with @code{\consists} is
- significant.
-
- @item @code{\consistsend} @var{engravername} @code{;}
- Analogous to @code{\consists}, but makes sure that
- @var{engravername} is always added to the end of the list of
- engravers.
- Some engraver types need to be at the end of the list; this
- insures they are put there, and stay there, if a user adds or
- removes engravers. This command is usually not needed for
- end-users.
-
- @item @code{\accepts} @var{contextname} @code{;}
- Add @var{contextname} to the list of context this context can
- contain. The first listed context is the context to create by
- default.
+@c_ {Pitch names}
+@subsubsection Pitch names
+@cindex Lexical modes
+@cindex pitch names
- @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.
+@cindex note names
+@cindex chord modifier names
- @item @var{propname} @code{=} @var{value} @code{;}
- A property assignment. It is allowed to use reals for
- @var{value}.
-@end itemize
+Note names and chord modifiers can be customised for nationalities.
+languages and conventions. The syntax is as follows.
+@cindex @code{\pitchnames}
+@cindex @code{\chordmodifiers}
-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
+@example
+ \pitchnames @var{scheme-alist}
+ \chordmodifiers @var{scheme-alist}
+@end example
-@quotation
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+specific examples how to do this. tables can be tailored specified
+using. Some national note names have been provided, see
+section @ref{Other languages}.
+A @code{\paper} block at top level sets the default paper block. A
+@code{\midi} block at top level works similarly.
-@example
-\paper @{
- foo = \translator @{ @dots{} @}
-@}
-\score @{
- \notes @{
- @dots{}
- @}
- \paper @{
- \translator @{ \foo @dots{} @}
- @}
-@}
-@end example
+@c_ {Assignments}
+@subsubsection Assignments
+@cindex assignments
+@cindex @code{#}
-@end quotation
+Identifier assignments may appear at top level. @ref{Assignments}
-@cindex paper types, engravers, and pre-defined translators
-Some pre-defined identifiers can simplify modification of
-translators. The pre-defined identifiers are:
+@c_ {Direct scheme}
+@subsubsection Direct scheme
+@cindex Direct scheme
-@table @code
-@cindex @code{StaffContext}
- @item @code{StaffContext}
- Default Staff context.
-@cindex @code{RhythmicStaffContext}
+Scheme statements maybe issued to produce interesting side-effects.
- @item @code{RhythmicStaffContext}
- Default RhythmicStaff context.
-@cindex @code{VoiceContext}
- @item @code{VoiceContext}
- Default Voice context.
-@cindex @code{ScoreContext}
+@c_ {Lexical modes}
+@node Lexical modes
+@subsection Lexical modes
+@cindex Lexical modes
- @item @code{ScoreContext}
- Default Score context.
-@cindex @code{ScoreWithNumbers}
+@cindex Lexical modes
+@cindex modes
- @item @code{ScoreWithNumbers}
- Score context with numbering at the Score level.
-@cindex @code{BarNumberingStaffContext}
+To simplify entering notes, lyrics, and chords, LilyPond has three
+special input modes on top of the default mode. In each mode, words
+are identified on the input. If @code{"word"} is encountered, it is
+treated as a string. If @code{\word} is encountered, it is treated as
+a keyword or as an identifier. The behavior of the modes differs in
+two ways: Different modes treat unquoted words differently, and
+different modes have different rules for deciding what is a word.
- @item @code{BarNumberingStaffContext}
- Staff context with numbering at the Staff level.
-@cindex @code{HaraKiriStaffContext}
+@table @asis
+@item Normal mode.
+@cindex normal mode
+
+At the start of parsing, LilyPond is in Normal mode. In Normal
+mode, a word is an alphabetic character followed by alphanumeric
+characters. If @code{word} is encountered on the input it is
+treated as a string.
- @item @code{HaraKiriStaffContext}
- Staff context that does not print if it only contains rests.
- Useful for orchestral scores.@footnote{Harakiri, also called
- Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
-@cindex @code{OrchestralPartStaffContext}
+@item Note mode
+See @ref{Note entry}.
- @item @code{OrchestralPartStaffContext}
-@cindex @code{OrchestralScoreContext}
+@item Lyrics mode
+See @ref{Lyrics entry}.
- @item @code{OrchestralScoreContext}
+@item Chord mode
+See @ref{Chord entry}.
@end table
-Using these pre-defined values, you can remove or add items to the
-translator:
+@cindex input modes
-@quotation
+@cindex mode switch
-@example
-\paper @{
- \translator @{
- \StaffContext
- \remove Some_engraver;
- \consists Different_engraver;
- @}
-@}
-@end example
+@cindex @code{\notes}
+@cindex @code{\chords}
+@cindex @code{\lyrics}
-@end quotation
+Mode switching keywords form compound music expressions: @code{\notes}
+@var{musicexpr}, @code{\chords} @var{musicexpr},
+and @code{\lyrics} @var{musicexpr}. These
+expressions do not add anything to the meaning of their arguments. They
+are just a way to indicate that the arguments should be parsed in
+indicated mode. See @ref{Lexical modes} for more information on modes.
-
-@node Sound output
-@section Sound output
+@c_ {Ambiguities}
+@node Ambiguities
+@subsection Ambiguities
+@cindex ambiguities
+@cindex grammar
-The MIDI block is analogous to the paper block, but it is somewhat
-simpler. The @code{\midi} block can contain:
-@cindex MIDI block
+
+The grammar contains a number of ambiguities. We hope to resolve them at
+some time.
@itemize @bullet
- @item a @code{\tempo} definition
- @item context definitions
-@end itemize
+ @item The assignment
-Assignments in the @code{\midi} block are not allowed.
+ @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
-@cindex context definition
+ @example
+foo = -6
+@end example
-Context definitions follow precisely the same syntax as within the
-\paper block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/performer.ly}.
+ 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
-@node midilist
-@section MIDI instrument names
-@cindex instrument names
-@cindex @code{Staff.midiInstrument}
-@cindex @code{Staff.instrument}
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property or, if that property is not set, the @code{Staff.instrument}
-property. The instrument name should be chosen from the following list.
-If the selected string does not exactly match, then LilyPond uses the
-default piano.
+ @end quotation
-[FIXME: to appendix ]
+ 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 @quotation
+ @item (an as yet unidentified ambiguity :-)
+@end itemize
-@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
+@c_ {Unsorted}
+@node Unsorted
+@section Unsorted
-@cindex pre-defined identifiers
+[mucho todo]
+Translation?
-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}.
+@cindex properties
+@unnumberedsubsec Translation property
-@table @code
-@cindex @code{\break}
- @item @code{\break}
- Force a line break in music by using a large argument for the
- keyword @code{\penalty}.
+@cindex @code{\property}
+@example
+ \property @var{contextname}.@var{propname} = @var{value}
+@end example
-@cindex @code{\nobreak}
- @item @code{\nobreak}
- Prevent a line break in music by using a large negative argument
- for the keyword @code{\penalty}.
+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 @code{\shiftOff}
- @item @code{\shiftOff}
- Disable horizontal shifting of note heads that collide.
+@cindex translator switches
+@unnumberedsubsec Translator switches
-@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{\translator}
+@example
+ \translator @var{contexttype} = @var{name}
+@end example
-@cindex @code{\stemBoth}
- @item @code{\stemBoth}
- Allow stems, beams, and slurs to point either upwards or
- downwards, decided automatically by LilyPond.
+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{\stemDown}
- @item @code{\stemDown}
- Force stems, beams, and slurs to point down.
+Usually this is used to switch staffs in Piano music, e.g.
-@cindex @code{\stemUp}
- @item @code{\stemUp}
- Force stems, beams and slurs to point up.
+@example
+ \translator Staff = top @var{Music}
+@end example
-@end table
+@cindex output properties
+@unnumberedsubsec Output properties
+These allow you to tweak what is happening in the back-end
+directly. If you want to control every detail of the output
+formatting, this is the feature to use. The downside to this is that
+you need to know exactly how the backend works. Example:
-@node Point and click
-@section Point and click
-[todo]
+@lilypond[fragment,verbatim]
+\relative c'' { c4
+ \context Staff \outputproperty
+ #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(5.0 . 7.5)
+<c8 e g> }
+@end lilypond
+
+This selects all note heads occurring at current staff level, and sets
+the @code{extra-offset} of those heads to @code{(5,7.5)}, shifting them
+up and right.
+
+Use of this feature is entirely on your own risk: if you use this, the
+result will depend very heavily on the implementation of the backend,
+which we change regularly and unscrupulously.
+
+@c_{Local emacs vars}
+@c Local variables:
+@c mode: texinfo
+@c minor-mode: font-lock
+@c minor-mode: outline
+@c xoutline-layout: (0 : -1 -1 0)
+@c outline-layout: (-1 : 0)
+@c outline-primary-bullet: "{"
+@c outline-stylish-prefixes: nil
+@c outline-override-protect: t
+@c End:
projects / lilypond.git / commitdiff