X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=ea338517a1b0256f555108d0c32ef8a247a15958;hb=af51453530b95aee167fe02ee3f4cb0c8dcd1fe2;hp=3862e3ad4dbbe2e134c43ffdb077fe301170c6f6;hpb=87b001c5f102fbf121dd2d5c0361cf4499021a89;p=lilypond.git diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 3862e3ad4d..ea338517a1 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,587 +1,667 @@ - - -@node Reference Manual, , , Top +@c Note: +@c +@c A menu is needed before every deeper *section nesting of @nodes +@c Run M-x texinfo-all-menus-update +@c to automagically fill in these menus +@c before saving changes + +@c_{Reference Manual} +@node Reference Manual +@chapter Reference Manual @menu -* Overview:: Overview -* Top level:: Top level -* notenames:: notenames -* Lexical conventions:: Lexical conventions -* Other languages:: notelang -* modes:: modes -* Types:: Types -* Music expressions:: Music expressions -* Atomic music expressions:: Atomic music expressions -* Note specification:: notedesc -* barlines:: barlines -* Manual beams:: Manual beam -* tremolo:: tremolo -* Compound music expressions:: Compound music expressions -* relative:: relative -* Repeats:: Repeats -* transpose:: transpose -* Ambiguities:: Ambiguities -* Notation conversion specifics:: Notation conversion specifics -* autobeam:: autobeam -* lyricprint:: lyricprint -* Notation Contexts:: Notation Contexts -* Properties:: Changing formatting -* Notation output definitions:: Notation output definitions -* paper:: paper -* Paper variables:: papervars -* contextdefs:: contextdefs -* engravers:: engravers -* Sound output:: Sound output -* midilist:: midilist -* Pre-defined Identifiers:: Pre-defined Identifiers +* Overview:: +* 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 -@chapter Reference Manual +@c_ {Overview} +@node Overview +@section Overview +This document +describes the the GNU LilyPond input format This format represents a +piece of music in an elegant way, but contains enough information for +both automatic typesetting and automatic performances. +This document has been revised for LilyPond 1.3.125 -@node Overview, , , Reference Manual -@section Overview +[todo: ] -This document@footnote{This document has been revised for -LilyPond 1.2.} describes the the GNU LilyPond input format, which is -a language for defining music. We call this language @emph{Music -Definition Language} or @emph{Mudela}, for short.@footnote{If anybody -comes up with a better name, we'd gladly take this. Gourlay already -uses a ``Musical Description Language,'' ISO standard 10743 defines a -``Standard Music Description Language.'' We're not being original -here.} +There are two things to note here. The format contains musical +concepts like pitches and durations, instead of symbols and positions: +the input format tries to capture the meaning of @emph{music}, and not +notation. Second, the format tries to be @emph{context-free}: +a note will sound the same regardless of the current time signature, +the key, etc. -@emph{Mudela} is a language that allows you to +The purpose of LilyPond is explained informally by the term `music +typesetter'. This is not a fully correct name: not only does the +program print musical symbols, it also makes esthetic decisions. All +symbols and their placement is @emph{generated} from a high-level musical +description. In other words, LilyPond would be best +described by `music compiler' or `music to notation compiler'. +LilyPond input can be classified into three types: @itemize @bullet - @item create musical expressions by combining pitches, durations - @item output those musical expressions to various formats - @item give those musical expressions and output definitions names, so - you can enter them in manageable chunks. + @item musical expressions: a musical expression is some combination of +rest, notes, lyrics + @item output definitions: recipes for translating those musical +expressions into performances (MIDI) or graphics (eg. PostScript). + + @item declarations: by declaring and naming musical expressions, you +can enter and edit them in manageable chunks. @end itemize -@emph{Mudela} aims to define a piece of music completely, both from -typesetting and from a performance point of view. +@c_ {Music constructs} +@node Music constructs +@section Music constructs +@cindex Music constructs +@menu +* Music expressions:: +* Sequential music:: +* Simultanious music:: +* Compound music expressions:: +* Grace music:: +* Explicit atomic music:: +@end menu +@c_ {Music expressions} +@node Music expressions +@subsection Music expressions -@node Top level, , , Reference Manual -@section Top level +@cindex music expressions -@cindex top level +Music in LilyPond is entered as a music expression. Notes, rests, +lyric syllables are music expressions (the atomic +expressions), +@cindex atomic music expressions +and you can combine music expressions to form new ones. This example +forms a compound expressions out of the quarter @code{c} note and a +@code{d} note: -This section describes what you may enter at top level. +@example +\sequential @{ c4 d4 @} +@end example +The meaning of this compound expression is to play the @code{c} +first, and then the @code{d} (as opposed to playing them +simultaneously, for instance). +Atomic music expression are discussed in +subsection @ref{Atomic music expressions}. Compound music expressions are +discussed in subsection @ref{Compound music expressions}. -@cindex score definition -The output is generated combining a music expression with an output -definition. A score block has the following syntax: +@c_ {Sequential music} +@node Sequential music +@subsection Sequential music +@cindex Sequential music +@cindex @code{\sequential} +@cindex sequential music @example - \score @{ @var{musicexpr} @var{outputdefs} @} + \sequential @code{@{} @var{musicexprlist} @code{@}} @end example -@var{outputdefs} are zero or more output definitions. If no output -definition is supplied, the default @code{\paper} block will be added. - - +This means that list should be played or written in sequence, i.e., +the second after the first, the third after the second. The duration +of sequential music is the the sum of the durations of the elements. +There is a shorthand, which leaves out the keyword: -@cindex header +@example +@cindex @code{<} +@cindex @code{>} -@keyindex{header} + @code{@{} @var{musicexprlist} @code{@}} +@end example -The syntax is +@c_ {Simultanious music} +@node Simultanious music +@subsection Simultanious music +@cindex Simultanious music +@cindex @code{\simultaneous} @example - \header @{ @var{key1} = @var{val1}; - @var{key2} = @var{val2}; @dots{} @} + \simultaneous @code{@{} @var{musicexprlist} @code{@}} @end example -A header describes the file's contents. It can also appear in a -@code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this -information for generating titles. Key values that are used by -@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, -metre, arranger, piece and tagline. - -It is customary to put the @code{\header} at the top of the file. +It constructs a music expression where all of its arguments start at +the same moment. The duration is the maximum of the durations of the +elements. The following shorthand is a common idiom: +@example + @code{<} @var{musicexprlist} @code{>} +@end example -@node notenames, , , Reference Manual +If you try to use a chord as the first thing in your score, you might +get multiple staffs instead of a chord. -Note name tables can be specified using +@lilypond[verbatim,center] + \score { + \notes + \paper { + linewidth = -1.; + } + } +@end lilypond -@example - \notenames@keyindex{notenames} - @{ @var{assignmentlist} @} -@end example +This happens because the chord is interpreted by a score context. +Each time a note is encountered a default Voice context (along with a +Staff context) is created. The solution is to explicitly instantiate +a Voice context: -@var{assignmentlist} is a list of definitions of the form +@lilypond[verbatim,center] + \score { + \notes\context Voice + \paper { + linewidth = -1.; + } + } +@end lilypond -@example - @var{name} = @var{pitch} -@end example +@c_ {Compound music expressions} +@node Compound music expressions +@subsection Compound music expressions -Chord modifiers can be set analogously, with -@code{\chordmodifiers}@keyindex{chordmodifiers}. +@cindex Compound music expressions -A @code{\paper} block at top level sets the default paper block. A -@code{\midi} block at top level works similarly. +Music expressions are compound data structures. You can nest music +expressions any way you like. This simple example shows how three +chords can be expressed in two different ways: +@lilypond[fragment,verbatim,center] + \notes \context Staff { + + < { a b c' } { c' d' e' } > + } +@end lilypond -LilyPond contains a Scheme interpreter (the GUILE library) for -internal use. The following commands access the interpreter -directly. +@cindex @code{\context} +@cindex context selection @example - \scm @keyindex{scm} @var{scheme} ; + \context @var{contexttype} [= @var{contextname}] @var{musicexpr} @end example -Evaluates the specified Scheme code. The result is discarded. +Interpret @var{musicexpr} within a context of type @var{contexttype}. +If the context does not exist, it will be created. The new context +can optionally be given a name. + + +@c_ {Grace music} <-> Grace notes +@node Grace music +@subsection Grace music +@cindex Grace music +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes +@cindex @code{graceAlignPosition} @example -\scmfile@keyindex{scmfile} @var{filename}; + \grace @var{musicexpr} @end example -Reads Scheme code from the specified file. The result is discarded. - +A grace note expression has duration 0; the next real note is +assumed to be the main note. +You cannot have the grace note after the main note, in terms of +duration, and main notes, but you can typeset the grace notes to the +right of the main note using the property +@code{graceAlignPosition}. +@cindex @code{flagStyle} -Identifier assignments may appear at top level. Semicolons are -forbidden after top level assignments. +When grace music is interpreted, a score-within-a-score is set up: +@var{musicexpr} has its own time bookkeeping, and you could (for +example) have a separate time signature within grace notes. While in +this score-within-a-score, you can create notes, beams, slurs, etc. +Unbeamed eighth notes and shorter by default have a slash through the +stem. This behavior can be controlled with the +@code{flagStyle} property. +@quotation +@lilypond[fragment,verbatim] +\relative c'' { + \grace c8 c4 \grace { [c16 c16] } c4 + \grace { \property Grace.flagStyle = "" c16 } c4 +} +@end lilypond +@end quotation +@cindex @code{\grace} -@node Lexical conventions, , , Reference Manual -@section Lexical conventions +At present, nesting @code{\grace} notes is not supported. The following +may cause run-time errors: +@example + @code{\grace @{ \grace c32 c16 @} c4} +@end example +Since the meaning of such a construct is unclear, we don't consider +this a loss. Similarly, juxtaposing two @code{\grace} sections is +syntactically valid, but makes no sense and may cause runtime errors. -@cindex lexical conventions +Ending a staff or score with grace notes may also generate a run-time +error, since there will be no main note to attach the grace notes to. +The present implementation is not robust and generally kludgy. We expect +it to change after LilyPond 1.4 -@cindex comment +@c_ {Explicit atomic music} +@node Explicit atomic music +@subsection Explicit atomic music +@cindex Explicit atomic music -@indexcode{%} +@cindex pitch -A one line comment is introduced by a `@code{%}' character. -Block comments are started by `@code{%@{}' and ended by `@code{%@}}'. -They cannot be nested. +The syntax for pitch specification is +@cindex @code{\pitch} +@example + \pitch @var{scmpitch} +@end example +@var{scmpitch} is a pitch scheme object, see @ref{Pitch}. -@cindex keyword +In Note and Chord mode, pitches may be designated by names. See +section @ref{Other languages} for pitch names in different languages. -Keywords start with a backslash, followed by a number of lower case -alphabetic characters. These are all the keywords. +@cindex duration +@cindex @code{\duration} +The syntax for duration specification is @example - \accepts - \addlyrics - \alternative - \bar - \breathe - \chordmodifiers - \chords - \clef - \cm - \consists - \consistsend - \context - \duration - \font - \grace - \header - \in - \key - \keysignature - \lyrics - \mark - \midi - \mm - \musicalpitch - \name - \notenames - \notes - \paper - \partial - \penalty - \property - \pt - \relative - \remove - \repeat - \repetitions - \scm - \scmfile - \score - \script - \sequential - \simultaneous - \skip - \spanrequest - \tempo - \textscript - \time - \times - \translator - \transpose - \type + \duration @var{scmduration} @end example +In Note, Chord, and Lyrics mode, durations may be designated by +numbers and dots. -@cindex integer -Formed from an optional minus sign followed by digits. Arithmetic -operations cannot be done with integers, and integers cannot be mixed -with reals. +@c_ {Modifying music} +@node Modifying music +@section Modifying music +@cindex Modifying music +@menu +* Relative:: +* Transpose:: +* Repeat:: +* Times :: +* Apply:: +* Transform:: +@end menu +@c_ {Relative} +@node Relative +@subsection Relative +@cindex Relative +@cindex relative octave specification +It is easy to get confused by octave changing marks and accidentally +putting a pitch in the wrong octave. A much better way of entering a +note's octave is `the relative octave' mode. +@cindex @code{\relative} +@example + \relative @var{startpitch} @var{musicexpr} +@end example -@cindex real - +The octave of notes that appear in @var{musicexpr} are calculated as +follows: If no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or +less.@footnote{The interval is determined without regarding +accidentals. A @code{fisis} following a @code{ceses} will be put above +the @code{ceses}.} The octave changing marks @code{'} and @code{,} +can then be added to raise or lower the pitch by an extra octave. +Upon entering relative mode, an absolute starting pitch must be +specified that will act as the predecessor of the first note of +@var{musicexpr}. -Formed from an optional minus sign and a sequence of digits followed -by a @emph{required} decimal point and an optional exponent such as -@code{-1.2e3}. Reals can be built up using the usual operations: -`@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and -`@code{/}@indexcode{/}', with parentheses for grouping. +Entering scales is straightforward in relative mode. -A real constant can be followed by one of the dimension -keywords: -@cindex dimensions - @code{\mm}@keyindex{mm}, -@code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or -@code{\cm}@keyindex{cm}, for millimeters, points, inches and -centimeters, respectively. This converts the number to a real that -is the internal representation of dimensions. +@lilypond[fragment,verbatim,center] + \relative c' { + c d e f g a b c c, + } +@end lilypond +And octave changing marks are used for intervals greater than a fourth. +@lilypond[fragment,verbatim,center] + \relative c'' { + c g c f, c' a, e'' } +@end lilypond -@cindex string - +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord. But other notes +within the second chord are determined by looking at the immediately +preceding note. -Begins and ends with the `@code{"}' character. To include a `@code{"}' -character in a string write `@code{\"}'. Various other backslash -sequences have special interpretations as in the C language. A -string that contains no spaces can be written without the quotes. -See section XREF-modes [FIXME] for details on unquoted strings; their -interpretation varies depending on the situation. Strings can be -concatenated with the `@code{+}' operator. +@lilypond[fragment,verbatim,center] + \relative c' { + c + + + } +@end lilypond +@cindex @code{\notes} +The pitch after the @code{\relative} contains a notename. To parse +the pitch as a notename, you have to be in note mode, so there must +be a surrounding @code{\notes} keyword (which is not +shown here). -The tokenizer accepts the following commands. They can appear -anywhere. +The relative conversion will not affect @code{\transpose} or +@code{\relative} sections in its argument. If you want to use +relative within transposed music, you must place an additional +@code{\relative} inside the @code{\transpose}. -@example - \maininput@keyindex{maininput} -@end example +It is strongly recommended to use relative pitch mode: less work, +less error-prone, and more readable. -This command is used in init files to signal that the user file must -be read. This command cannot be used in a user file. +@c_ {Transpose} +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} +A music expression can be transposed with @code{\transpose}. The syntax +is @example - \include@keyindex{include} @var{file} + \transpose @var{pitch} @var{musicexpr} @end example -Include @var{file}. The argument @var{file} may be a quoted string (an -unquoted string will not work here!) or a string identifier. The full -filename including the @file{.ly} extension must be given, +This means that middle C in @var{musicexpr} is transposed to +@var{pitch}. -@example - \version@keyindex{version} @var{string} ; -@end example +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose cis'} or @code{\transpose des'} will transpose up half +a tone. The first version will print sharps and the second version +will print flats. -Specify the version of LilyPond that a file was written for. The -argument is a version string in quotes, for example @code{"1.2.0"}. -This is used to detect invalid input, and to aid -@code{convert-mudela}, a tool that automatically upgrades input files. +@quotation +@lilypond[fragment,verbatim] +\context Staff { + \clef "F"; + { \key e \major; c d e f } + \clef "G"; + \transpose des'' { \key e \major; c d e f } + \transpose cis'' { \key e \major; c d e f } +} +@end lilypond +@end quotation +If you want to use both @code{\transpose} and @code{\relative}, then +you must use @code{\transpose} first. @code{\relative} will have no +effect music that appears inside a @code{\transpose}. -@cindex other languages +@c_ {Repeat} +@node Repeat +@subsection Repeat +@cindex Repeat +@cindex repeats -@node Other languages, , , Reference Manual +@ref{Volta} +[TODO: document #'repeatCommands.] -Note name definitions have been provided in various languages. -Simply include the language specific init file. For example: -`@code{\include "english.ly"}'. The available language files and the -names they define are: +@cindex @code{\repeat} -@quotation +In order to specify repeats, use the @code{\repeat} +keyword. Since repeats look and sound differently when played or +printed, there are a few different variants of repeats. -@example - Note Names sharp flat -nederlands.ly c d e f g a bes b -is -es -english.ly c d e f g a bf b -s/-sharp -f/-flat -deutsch.ly c d e f g a b h -is -es -norsk.ly c d e f g a b h -iss/-is -ess/-es -svenska.ly c d e f g a b h -iss -ess -italiano.ly do re mi fa sol la sid si -d -b -catalan.ly do re mi fa sol la sid si -d/-s -b -@end example +@table @asis +@item unfolded +Repeated music is fully written (played) out. Useful for MIDI +output. -@end quotation +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (voltas) are printed, left to right. -Pitch names can be redefined using the -@code{\notenames}@keyindex{notenames} command, see -subsection XREF-notenames [FIXME]. +@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 -@cindex lexical modes +@example + \repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example -@cindex modes +If you have alternative endings, you may add -@node modes, , , Reference Manual +@cindex @code{\alternative} +@example + \alternative @code{@{} @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @code{@}} +@end example -To simplify entering notes, lyrics, and chords, @emph{Mudela} has three -special input modes on top of the default mode. In each mode, words -are identified on the input. If @code{"word"} is encountered, it is -treated as a string. If @code{\word} is encountered, it is treated as -a keyword or as an identifier. The behavior of the modes differs in -two ways: Different modes treat unquoted words differently, and -different modes have different rules for deciding what is a word. +where each @var{alternative} is a Music expression. -@table @samp - @item Normal mode. -@cindex mode!normal - - At the start of parsing, @emph{Mudela} is in Normal mode. In Normal - mode, a word is an alphabetic character followed by alphanumeric - characters. If @code{word} is encountered on the input it is - treated as a string. - - @item Note mode. -@cindex mode!note - - Note mode is introduced by the keyword - @code{\notes}@keyindex{notes}. In Note mode, words can only - contain alphabetic characters. If @code{word} is encountered, - LilyPond first checks for a notename of @code{word}. If no - notename is found, then @code{word} is treated as a string. - - Since combinations of numbers and dots are used for indicating - durations, it is not possible to enter real numbers in this mode. - - @item Chord mode. -@cindex mode!chord - - Chord mode is introduced by the keyword - @code{\chords}@keyindex{chords}. It is similar to Note mode, but - words are also looked up in a chord modifier table (containing - @code{maj}, @code{dim}, etc). - - Since combinations of numbers and dots are used for indicating - durations, you can not enter real numbers in this mode. Dashes - and carets are used to indicate chord additions and subtractions, - so scripts can not be entered in Chord mode. - - @item Lyrics mode. -@cindex mode!lyric - - Lyrics mode is introduced by the keyword - @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it - easy to include punctuation and diacritical marks in words. A - word in Lyrics mode begins with: an alphabetic character, - `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the - control characters @code{^A} through @code{^F}, @code{^Q} through - @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code - over 127, or a two-character combination of a backslash followed - by one of `@code{`}', `@code{'}', `@code{"}', or - `@code{^}'.@footnote{The purpose of Lyrics mode is that you can - enter lyrics in TeX format or a standard encoding without - needing quotes. The precise definition of this mode indeed is - ludicrous. This will remain so until the authors of LilyPond - acquire a deeper understanding of character encoding, or someone - else steps up to fix this.} - - Subsequent characters of a word can be any character that is not - a digit and not white space. One important consequence of this - is that a word can end with `@code{@}}', which may be confusing if - you thought the closing brace was going to terminate Lyrics - mode.@footnote{LilyPond will issue a warning, though.} Any - `@code{_}' characters which appear in an unquoted word are - converted to spaces. This provides a mechanism for introducing - spaces into words without using quotes. Quoted words can also be - used in Lyrics mode to specify words that cannot be written with - the above rules. Here are some examples. Not all of these words - are printable by TeX. - - - @quotation +Normal notation repeats are used like this: -@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 +@quotation - @end quotation +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 { c'4 d' e' f' } + \repeat volta 2 { f' e' d' c' } - Since combinations of numbers and dots are used for indicating - durations, you can not enter real numbers in this mode. -@end table +@end lilypond +@end quotation -It is possible to create words that break the rules by prefixing them -with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a -word beginning with `@code{$}' extends until the next white space -character. Such words can contain numbers (even in Note mode), or -other forbidden characters. The dollar sign can be used to create -and access identifiers that could not otherwise be used.@footnote{Use -of `@code{$}' hampers readability and portability to future LilyPond -versions, thus the use of the dollar sign is discouraged.} +With alternative endings: +@quotation +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } -@node Types, , , Reference Manual -@section Types +@end lilypond +@end quotation -@cindex types and identifiers - -@emph{Mudela} has a limited set of types: - -@itemize @bullet - @item integers - @item reals - @item strings - @item music expressions - @item durations of notes and rests (specified with - @code{\notenames}@keyindex{notenames}) - @item note name tables - @item context definitions, part of output definitions. See - section XREF-contextdefs [FIXME] for more information - @item output definitions (like @code{\paper}@keyindex{paper} blocks - and @code{\midi}@keyindex{midi} blocks) - @item score definitions (@code{\score}@keyindex{score} blocks) -@end itemize - -Type is a syntactical property: @emph{Mudela} has no real type system, -so there is no support for generic expressions, functions, or user -defined types. For the same reason, it is not possible to mix reals -and integers in arithmetic expressions, and ``type -errors'' -@cindex type error - (e.g., using a string identifier to -initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse -error''. - -Identifiers allow objects to be assigned to names. To assign an -identifier, you use `@var{name}=@var{value}' and to refer to an -identifier, you preceed its name with a backslash: -`@code{\}@var{name}'. Identifier assignments must appear at top level -in the @emph{Mudela} file. Semicolons are forbidden after assignments -appearing at top level but they are obligatory after assignments -appearing in the @code{\paper} block, see Section XREF-paper [FIXME]. - -@var{value} is any of the types listed above. - -An identifier can be created with any string for its name, but you -will only be able to refer to identifiers whose names begin with a -letter, being entirely alphanumeric. It is impossible to refer to an -identifier whose name is the same as the name of a keyword. - -The right hand side of an identifier assignment is parsed completely -before the assignment is done, so it is allowed to redefine an -identifier in terms of its old value, e.g. - -@example - foo = \foo * 2.0 -@end example - -When an identifier is referenced, the information it points to is -copied. Therefore it only makes sense to put identifiers for -translators, output definitions, and @code{\score}@keyindex{score} -blocks as the first item in a block. For this reason, if you -reference a @code{\foo} variable in a @code{\foo} block, it must be the -first item in the list following @code{\foo}.@footnote{@code{\paper@{\one -\two@}} does not make sense, because the information of @code{\two} -would overwrite the information of @code{\one}, thereby making the -reference to the first identifier useless.} +Folded repeats look like this:@footnote{Folded repeats offer little +more over simultaneous music. However, it is to be expected that +more functionality -- especially for the MIDI backend -- will be +implemented.} +@quotation +@lilypond[fragment,verbatim] + c'1 + \repeat fold 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } -@node Music expressions, , , Reference Manual -@section Music expressions +@end lilypond +@end quotation -@cindex music expressions +@quotation -Music in @emph{Mudela} is entered as a music expression. Notes, rests, -lyric syllables are music expressions (the atomic -expressions) -@cindex atomic music expressions -, and you can combine -music expressions to form new ones. This example forms a compound -expressions out of the quarter @code{c} note and a @code{d} -note: +@lilypond[fragment,verbatim] +\context Staff { + \relative c' { + \partial 4; + \repeat volta 2 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b1 } } + } +} -@example -\sequential @{ c4 d4 @} -@end example +@end lilypond +@end quotation -The meaning of this compound expression is to play the `@code{c}' -first, and then the `@code{d}' (as opposed to playing them -simultaneously, for instance). +If you don't give enough alternatives for all of the repeats, then +the first alternative is assumed to be repeated often enough to equal +the specified number of repeats. -Atomic music expression are discussed in -subsection XREF-atomicmusic [FIXME]. Compound music expressions are -discussed in subsection XREF-compoundmusic [FIXME]. +@quotation +@lilypond[fragment,verbatim] +\context Staff { + \relative c' { + \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } + {\partial 1; e4 e e } + {\partial 1; a a a a | b1 } } + } +} +@end lilypond +@end quotation +As you can see, LilyPond doesn't remember the timing information, nor +are slurs or ties repeated. We hope to fix this after 1.4. +It is possible to nest @code{\repeat}. This is not entirely +supported: the notes will come be in the right places, but the repeat +bars will not. -@node Atomic music expressions, , , Reference Manual -@section Atomic music expressions +To place tremolo marks between notes, use @code{\repeat} with tremolo +style. +@cindex tremolo beams +To create tremolo beams on a single note, simply attach +`@code{:}@var{length}' to the note itself. + +@lilypond[verbatim,center] +\score { + \context Voice \notes\relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } + } + \paper { + linewidth = 40*\staffspace; + } +} +@end lilypond +@cindex @code{__} +@lilypond[fragment,verbatim,center] + c'4:32 +@end lilypond +@c_ {Times} +@node Times +@subsection Times +@cindex Times +@ref{Tuplets} +Tuplets are made out of a music expression by multiplying their +duration with a fraction. -@cindex pitch +@cindex @code{\times} +@example + \times @var{fraction} @var{musicexpr} +@end example -@cindex duration - +The duration of @var{musicexpr} will be multiplied by the fraction. +In print, the fraction's denominator will be printed over the notes, +optionally with a bracket. The most common tuplet is the triplet in +which 3 notes have the length of 2, so the notes are 2/3 of +their written length: -The syntax for pitch specification is +@lilypond[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond +@c_ {Apply} +@node Apply +@subsection Apply +@cindex Apply +Apply allows a Scheme-function to operate directly on the internal +representation of music. @example - \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @} + \apply #@var{func} @var{music} @end example +The function takes two arguments, being a function and an musical +argument for that function. The function should return a music +expression. -@var{octave} is specified by an integer, zero for the octave -containing middle C. @var{note} is a number from 0 to 7, with 0 -corresponding to C and 7 corresponding to B. The shift is zero for a -natural, negative to add flats, or positive to add sharps. +This example replaces the text string of a script. It also shows a dump +of the music it processes. +@lilypond[verbatim] +#(define (testfunc x) + (if (eq? (ly-get-mus-property x 'text) "foo") + (ly-set-mus-property x 'text "bar")) + ;; recurse + (ly-set-mus-property x 'elements + (map testfunc (ly-get-mus-property x 'elements))) + (display x) + x +) +\score { \notes + \apply #testfunc { c4_"foo" } +} +@end lilypond + +For more information on what is possible, see the @ref{Tricks} and the +automatically generated documentation. + +@c_ {Transform} +@node Transform +@subsection Transform +@cindex Transform + + +@c_ {Note entry} +@node Note entry +@section Note entry +@cindex Note entry -In Note and Chord mode, pitches may be designated by names. See -section XREF-notelang [FIXME] for pitch names in different languages. +@menu +* Notes mode:: +* Pitch names:: +@end menu -The syntax for duration specification is +@c_ {Notes mode} +@node Notes mode +@subsection Notes mode -@example - \duration@keyindex{duration} - @{ @var{length} @var{dotcount} @} -@end example +@cindex note mode -@var{length} is the negative logarithm (base 2) of the duration: -1 is a half note, 2 is a quarter note, 3 is an eighth -note, etc. The number of dots after the note is given by -@var{dotcount}. +@cindex @code{\notes} +Note mode is introduced by the keyword +@code{\notes}. In Note mode, words can only +contain alphabetic characters. If @code{word} is encountered, +LilyPond first checks for a notename of @code{word}. If no +notename is found, then @code{word} is treated as a string. -In Note, Chord, and Lyrics mode, durations may be designated by -numbers and dots. See Section XREF-notelang [FIXME] for details. +Since combinations of numbers and dots are used for indicating +durations, it is not possible to enter real numbers in this mode. -@node Note specification, , , Reference Manual +@cindex Notes mode -@cindex note specification +@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 @@ -594,519 +674,621 @@ The pitch of the note is specified by the note's name. The default names are the Dutch note names. The notes are specified -by the letters `@code{c}' through `@code{b}', where `@code{c}' is an +by the letters @code{c} through @code{b}, where @code{c} is an octave below middle C and the letters span the octave above that C. -In Dutchcindex(notenames!Dutch), a sharp is formed by adding -`@code{-is}' to the end of a pitch name. A flat is formed by adding -`@code{-es}'. Double sharps and double flats are obtained by adding -`@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are -contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will -be accepted. +In Dutch, +@cindex note names, Dutch +a sharp is formed by adding @code{-is} to the end of a pitch name. A +flat is formed by adding @code{-es}. Double sharps and double flats are +obtained by adding @code{-isis} or @code{-eses}. @code{aes} and +@code{ees} are contracted to @code{as} and @code{es} in Dutch, but both +forms will be accepted. + +LilyPond has predefined sets of notenames for various other languages. +To use them, simply include the language specific init file. For +example: @code{\include "english.ly"}. The available language files and +the names they define are: + +@example + Note Names sharp flat +nederlands.ly c d e f g a bes b -is -es +english.ly c d e f g a bf b -s/-sharp -f/-flat +deutsch.ly c d e f g a b h -is -es +norsk.ly c d e f g a b h -iss/-is -ess/-es +svenska.ly c d e f g a b h -iss -ess +italiano.ly do re mi fa sol la sib si -d -b +catalan.ly do re mi fa sol la sib si -d/-s -b +@end example +@cindex @code{'} +@cindex @code{,} + +Pitch names can be redefined using the @code{\pitchnames} command, see +@ref{Pitch names}. + -LilyPond has predefined sets of notenames for various languages. See -section XREF-notelang [FIXME] for details. The optional octave specification takes the form of a series of -single quote (`@code{'}@indexcode{'}') characters or a series of comma -(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one +single quote (`@code{'}') characters or a series of comma +(`@code{,}') characters. Each @code{'} raises the pitch by one octave; each @code{,} lowers the pitch by an octave. -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] c' d' e' f' g' a' b' c'' -@end mudela +@end lilypond -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] cis' dis' eis' fis' gis' ais' bis' -@end mudela +@end lilypond -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] ces' des' es' fes' ges' as' bes' -@end mudela +@end lilypond -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] cisis' eisis' gisis' aisis' beses' -@end mudela +@end lilypond -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] ceses' eses' geses' ases' beses' -@end mudela +@end lilypond -Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond -will determine what accidentals to typeset depending on the key and -context. A reminder accidental +LilyPond will determine what accidentals to typeset depending on the key +and context, so alteration refer to what note is heard, not to whether +accidentals are printed. A reminder accidental @cindex reminder accidental - can be -forced by adding an exclamation mark `@code{!}' after the pitch. A -cautionary accidental, +@cindex @code{?} +can be forced by adding an exclamation mark @code{!} after the pitch. +A cautionary accidental, @cindex cautionary accidental - i.e., an -accidental within parentheses can be obtained by adding the question -mark `@code{?}@indexcode{?}' after the pitch. -@mudela[fragment,verbatim,center] - cis' d' e' cis' c'? d' e' c'! -@end mudela +i.e., an accidental within parentheses can be obtained by adding the +question mark `@code{?}' after the pitch. +@lilypond[fragment,verbatim,center] + cis' d' e' cis' c'? d' e' c'! +@end lilypond -@cindex duration -Durations are entered as their reciprocal values. For notes longer -than a whole note, use identifiers. +@c_ {Rests} +@menu +* Rests:: +* Durations:: +* Multi measure rests:: +* Skip:: +@end menu -@quotation +@node Rests +@subsection Rests +@cindex Rests -@example -c'\longa c'\breve -c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 -@end example +Rests are entered like notes, with note name `@code{r}'. +There is also a note name +`@code{s}', which produces a space of the specified +duration. -@end quotation -@quotation +@c_ {Durations} +@node Durations +@subsection Durations +@cindex Durations -@mudela[] -\score { - \notes \relative c'' { - a\longa a\breve - a1 a2 a4 a8 a16 a32 a64 a64 - } - \paper { -%{ \translator { - \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - } %} - } -} -@end mudela -@end quotation +Durations are entered as their reciprocal values. For notes longer +than a whole note, use identifiers. @quotation @example +c'\longa c'\breve +c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r64 @end example -@end quotation - -@quotation -@mudela[] +@lilypond[] \score { \notes \relative c'' { + a\longa a\breve \autoBeamOff + a1 a2 a4 a8 a16 a32 a64 a64 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r64 } \paper { - loose_column_distance = 2.5 * \interline; - linewidth = -1.0; \translator { - \type "Score_engraver"; - \name "Score"; - \consists "Rest_engraver"; - \consists "Stem_engraver"; - \consists "Rhythmic_column_engraver"; + \StaffContext + \remove "Clef_engraver"; + \remove "Staff_symbol_engraver"; + \remove "Time_signature_engraver"; + \consists "Pitch_squash_engraver"; } } } -@end mudela +@end lilypond @end quotation -If the duration is omitted then it is set equal to the previous -duration. If there is no previous duration, a quarter note is -assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}') -to obtain dotted note lengths. - -@mudela[fragment,verbatim,center] - a'4. b'4. -@end mudela - -You can alter the length of duration by writing -`@code{*}@var{fraction}' after it. This will not affect the -appearance of note heads or rests. - - -Rests are entered like notes, with note name `@code{r}@indexcode{r}', -or `@code{R}@indexcode{R}'. There is also a note name `@code{s}@indexcode{s}', -which produces a space of the specified duration. -`@code{R}' is specifically meant for entering parts: the @code{R} rest -can expand to fill a score with rests, or it can be printed as a -single multimeasure rest. - +As you can see, the longa is not printed. To get a longa note head, you +have to use a different style of note heads. See [TODO]. -@cindex lyrics expressions +@cindex @code{.} -Syllables are entered like notes, with pitches replaced by text. For -example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each -with quarter note duration. Note that the hyphen has no special -meaning for lyrics, and does not introduce special symbols. See -section XREF-modes [FIXME] for a description of what is interpreted as -lyrics. -Spaces can be introduced into a lyric either by using quotes -(`@code{"}') or by using an underscore without quotes: `@code{He_could4 -not4}'. All unquoted underscores are converted to spaces. Printing -lyrics is discussed in section XREF-lyricprint [FIXME]. +If the duration is omitted then it is set equal to the previous duration +entered. At the start of parsing there is no previous duration, so then +a quarter note is assumed. The duration can be followed by a dot +(`@code{.}') to obtain dotted note lengths. -@cindex properties +@lilypond[fragment,verbatim,center] + a'4. b'4. +@end lilypond +@cindex @code{r} +@cindex @code{s} -@example - \property@keyindex{property} - @var{contextname}.@var{propname} = @var{value} -@end example +You can alter the length of duration by writing `@code{*}@var{fraction}' +after it. This will not affect the appearance of note heads or rests. -Sets the @var{propname} property of the context @var{contextname} to -the specified @var{value}. All three arguments are strings. -Depending on the context, it may be necessary to quote the strings or -to leave space on both sides of the dot. +@c_ {Multi measure rests} +@node Multi measure rests +@subsection Multi measure rests +@cindex Multi measure rests +@cindex @code{R} +Multi_measure_rest are entered using `@code{R}'. It is specifically +meant for entering parts: the rest can expand to fill a score with +rests, or it can be printed as a single multimeasure rest This expansion +is controlled by the property @code{Score.skipBars}. If this is set to true, +Lily will not expand empty measures, and the multimeasure rests +automatically adds the appropriate number. -@cindex translator switches +@lilypond[fragment] + \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 +@end lilypond -@example - \translator@keyindex{translator} - @var{contexttype} = @var{name} -@end example +Note that there is currently no way to condense multiple rests into a +single multimeasure rest. -A music expression indicating that the context which is a direct -child of the a context of type @var{contexttype} should be shifted to -a context of type @var{contexttype} and the specified name. +@c_ {Skip} +@node Skip +@subsection Skip +@cindex Skip -Usually this is used to switch staffs in Piano music, e.g. @example - \translator Staff = top @var{Music} + \skip @var{duration} @code{;} @end example +@cindex @code{\skip} +Skips the amount of time specified by @var{duration}. If no other +music is played, a gap will be left for the skipped time with no +notes printed. It works in Note Mode or Lyrics Mode. In Note mode, +this has the same effect as the spacer rest. -@cindex output properties - - -These allow you to tweak what is happening in the back-end -directly. If you want to control every detail of the output -formatting, this is the feature to use. The downside to this is that -you need to know exactly how the backend works. Example: - - -@mudela[fragment,verbatim] -\relative c'' { c4 - \context Staff \outputproperty - #(make-type-checker 'Note_head) - #'extra-offset = #'(5.0 . 7.5) - } -@end mudela - -This selects all note heads occurring at current staff level, and sets -the extra-offset of those heads to (5,7.5), shifting them up and -right. - -Use of this feature is entirely on your own risk: if you use this, the -result will depend very heavily on the implentation of the backend, -which we change unscrupulously. -@cindex commands +@c_ {Music notation} +@node Music notation +@section Music notation +@cindex Music notation +@menu +* Key:: +* Clef:: +* Time signature:: +* Spanners:: +* Ornaments:: +* Bar check:: +@end menu -Commands are music expressions that have no duration. +@c_ {Key} +@node Key +@subsection Key +@cindex Key +@cindex @code{\key} @example - - @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;} + @code{\key} @var{pitch} @var{type} @code{;} @end example - -Change the key signature. @var{type} should be -@code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get -@var{pitch}-major or @var{pitch}-minor, respectively. The second -argument is optional; the default is major keys. The @var{\context} -argument can also be given as an integer, which tells the number of -semitones that should be added to the pitch given in the subsequent -@code{\key}@keyindex{key} commands to get the corresponding major key, -e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard -mode names @code{\ionian}@keyindex{ionian}, -@code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian}, -@code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian}, -@code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian} -are also defined. - +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} + +Change the key signature. @var{type} should be @code{\major} or +@code{\minor} to get @var{pitch}-major or @var{pitch}-minor, +respectively. The second argument is optional; the default is major +keys. The @var{\context} argument can also be given as an integer, +which tells the number of semitones that should be added to the pitch +given in the subsequent @code{\key} commands to get the corresponding +major key, e.g., @code{\minor} is defined as 3. The standard mode names +@code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, +@code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined. + + +@c_ {Clef} +@node Clef +@subsection Clef +@cindex Clef + + +@c_ {Clef changes} +@subsubsection Clef changes +@cindex @code{\clef} @example - - @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;} + \clef @var{clefname} @code{;} @end example -Specify an arbitrary key signature. The pitches from @var{pitch} will -be printed in the key signature in the order that they appear on the -list. +Short-cut for - @example - \mark@keyindex{mark} @var{unsigned}; - \mark @var{string}; + \property Clef.clefGlyph = @var{symbol associated with clefname} + \property Clef.clefPosition = @var{clef Y-position for clefname} + \property Clef.clefOctavation = @var{extra pitch of clefname} @end example -Prints a mark over or under (depending on the -@code{markDirection}@indexcode{markDirection} property) the staff. You must add -@code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for -this to work. - -@node barlines, , , Reference Manual - -@example - \bar@keyindex{bar} @var{bartype}; -@end example +Supported clef-names include -This is a request to print a special bar symbol. It replaces the -regular bar symbol with a special -symbol. The argument @var{bartype} is a string which specifies the -kind of bar to print. Options are @code{":|"} -@cindex "|A@@@code{:|} -, -@code{"|:"} -@cindex "|B@@@code{|:} -, @code{":|:"} -@cindex "|C@@@code{:|:} -, -@code{"||"} -@cindex "|D@@@code{||} -, @code{"|."} -@cindex "|E@@@code{|.} -, -@code{".|"} -@cindex "|F@@@code{.|} -, and @code{".|."} -@cindex "|G@@@code{.|.} -. -These produce, respectively, a right repeat, a left repeat, a double -repeat, a double bar, a start bar, an end bar, and a thick double -bar. If @var{bartype} is set to @code{"empty"} then nothing is -printed, but a line break is allowed at that spot. - -You are encouraged to use @code{\repeat} for repetitions. -See section XREF-sec-repeats [FIXME]. +[todo] - +@c_ {Time signature} +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} @example - - \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;} + \time @var{numerator}@code{/}@var{denominator} @code{;} @end example -Change the time signature. The default time signature is 4/4. -The time signature is used to generate bar lines. - +A short-cut for doing @example - - \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;} + \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator}) @end example -Used to specify the tempo. For example, `@code{\tempo 4 = 76;}' -requests output with 76 quarter notes per minute. - -@example +See the documentation of @code{timeSignatureFraction} - \partial@keyindex{partial} @var{duration} @code{;} -@end example +@c_ {Partial} +@subsubsection Partial +@cindex Partial @cindex anacrusis - @cindex upstep - -This creates an incomplete measure (anacrusis, upbeat) at the start of -the music, e.g., `@code{\partial 8*2;}' creates a starting measure -lasting two eighth notes. - +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} @example + \partial @var{duration} @code{;} +@end example - @code{|}@indexcode{|} -@cindex bar check +Short cut for +@example + \property Score.measurePosition = @var{length of duration} @end example +@cindex @code{|} -@cindex shorten measures - -@cindex upstep +See the documentation of @code{measurePosition}. -`@code{|}' is a barcheck. Whenever a barcheck is encountered during -interpretation, a warning message is issued if it doesn't fall at a -measure boundary. This can help you finding errors in the input. -The beginning of the measure will be relocated, so this can also -be used to shorten measures. -@example +@c_ {Spanners} +@node Spanners +@subsection Spanners +@cindex Spanners - \penalty@keyindex{penalty} @var{int} @code{;} -@end example +@menu +* Beam:: +* Slur:: +* Tie:: +* Tuplet:: +* Volta:: +* Crescendo and Decrescendo:: +* Text spanner:: +* Ottava:: +* Span requests:: +@end menu +@c_ {Beam} +@node Beam +@subsubsection Beam +@cindex Beam +@c_ {Automatic beams} +@unnumberedsubsubsec Automatic beams -Discourage or encourage line breaks. See identifiers -@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in -section [on identifiers] [FIXME]. +@cindex automatic beam generation +@cindex autobeam -@example +@cindex @code{Voice.noAutoBeaming} - \clef@keyindex{clef} @var{clefname} @code{;} -@end example +By default, LilyPond will generate beams automatically. This feature +can be disabled by setting the @code{Voice.noAutoBeaming} property to +true. It can be overridden for specific cases by specifying explicit +beams. -Music expression that sets the current clef. The argument is a -string which specifies the name of the clef. Several clef names are -supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef -name, then the clef lowered or raised an octave will be generated. -Here are the supported clef names with middle C shown in each -clef: +@cindex @code{Voice.autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} +A large number of Voice properties are used to decide how to generate +beams. Their default values appear in @file{scm/auto-beam.scm}. In +general, beams can begin anywhere, but their ending location is +significant. Beams can end on a beat, or at durations specified by the +properties in +@code{Voice.autoBeamSettings}. +To end beams every quarter note, for example, you could set the property +@code{(end * * * *)} to @code{(make-moment 1 +4)}. To end beams at every three eighth notes you would set +it to @code{(make-moment 1 8)}. +The same syntax can be used to specify beam +starting points using +@code{(begin * * * *)}, eg: @quotation - -@mudela[] -\score { - \notes { - \cadenzaOn - %\property Voice.textStyle = typewriter - \clef subbass; c'4-"\kern -5mm subbass" - \clef bass; c'4^"\kern -2mm bass" - \clef baritone; c'4_"\kern -5mm baritone" - \clef varbaritone; c'4^"\kern -6mm varbaritone" - \clef tenor; c'4_"\kern -3mm tenor" - \clef "G_8"; c'4^"\kern -2mm G\\_8" - } - \paper { - linewidth = -1.0; - } -} -@end mudela +@example +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(make-moment 1 4) +\property Voice.autoBeamSettings \override + #'(begin * * * *) = #(make-moment 1 8) +@end example @end quotation -@quotation - -@mudela[] -\score { - \notes { - \cadenzaOn - \clef alto; c'4_"\kern -2mm alto" - \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano" - \clef soprano; c'4_"\kern -6mm soprano" - \clef treble; c'4^"\kern -4mm treble" - \clef french; c'4_"\kern -4mm french" - } - \paper { - linewidth = 4.5 \in; - } -} -@end mudela -@end quotation +To allow different settings for different time signatures, instead of +the first two asterisks @code{* *} you can specify a time signature; use +@code{(end N M * *)} to restrict the definition to +`@var{N}@code{/}@var{M}' time. For example, to specify beams ending +only for 6/8 time you would use the property @code{(end 6 8 * *)}. -The three clef symbols can also be obtained using the names `@code{G}', -`@code{C}' or `@code{F}', optionally followed by an integer which -indicates at which note line the clef is located. An as example, the -@code{mezzosoprano} clef can also be given as `@code{C2}'. +To allow different endings for notes of different durations, instead of +th last two asterisks you can specify a duration; use @code{(end * * N +M)} to restrict the definition to beams that contain notes of +`@var{N}@code{/}@var{M}' duration. -@example +For example, to specify beam endings for beams that contain 32nd notes, +you would use @code{(end * * 1 32)}. - \skip@keyindex{skip} @var{duration} @code{;} -@end example -Skips the amount of time specified by @var{duration}. If no other -music is played, a gap will be left for the skipped time with no -notes printed. It works in Note Mode or Lyrics Mode. In Note mode, -this has the same effect as the space rest `@code{s}'. +@c_ {Manual beams} +@cindex Automatic beams +@unnumberedsubsubsec Manual beams -@cindex beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} -@node Manual beams, , , Reference Manual +FIXME +Beaming can be generated automatically; see section @ref{Automatic Beaming}. A beam is specified by surrounding the beamed notes with brackets -`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'. +`@code{[}' and `@code{]}'. -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] [a'8 a'] [a'16 a' a' a'] -@end mudela - -Some more elaborate constructions: - -@mudela[fragment,verbatim,center] [a'16 c'' ] \times 2/3 { [e'8 f' g'] } -@end mudela +@end lilypond -Beaming can be generated automatically; see section XREF-autobeam [FIXME]. -To place tremolo marks -@cindex tremolo beams - between two notes, begin -with `@code{[:}@var{length}' and end with `@code{]}'. Tremolo marks -will appear instead of beams. Putting more than two notes in such a -construction will produce odd effects. To create tremolo beams on a -single note, simply attach `@code{:}@var{length}' to the note itself -(see also section XREF-tremolo [FIXME]). - -@ignore -@mu dela[fragment,verbatim,center] - [:16 e'1 g'] [:8 e'4 f'] -@end mudela - -@mud ela[fragment,verbatim,center] - c'4:32 [:16 c'8 d'8] -@end mudela -@end ignore +@cindex @code{-}@code{-} -@cindex --@@@code{-}@code{-} -@indexcode{__} +@c_ {Adjusting beams} +@unnumberedsubsubsec Adjusting beams +@cindex Adjusting beams -@cindex extender -@cindex hyphen +@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 -The syntax for an extender mark is `@code{__}'. This syntax can only -be used within lyrics mode. The syntax for a spanning hyphen (i.e., -a hyphen that will be printed between two lyric syllables) is -`@code{-}@code{-}'. +@c_ {Adjusting slurs} +@unnumberedsubsubsec Adjusting slurs +@c_ {Tie} +@cindex Adusting slurs +@node Tie +@subsubsection Tie + +@cindex Tie @cindex ties +@cindex @code{~} A tie connects two adjacent note heads of the same pitch. When used with chords, it connects all of the note heads whose pitches match. -Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'. +Ties are indicated using the tilde symbol `@code{~}'. If you try to tie together chords which have no common pitches, a warning message will appear and no ties will be created. -@mudela[fragment,verbatim,center] +@lilypond[fragment,verbatim,center] e' ~ e' ~ -@end mudela +@end lilypond +[sparseTies] -[TODO: explain Requests] +@c_ {Tuplet} +@node Tuplet +@subsubsection Tuplet +@cindex Tuplet +See @ref{Times}. -@cindex articulations +@c_ {Volta} +@node Volta +@subsubsection Volta +@cindex Volta -@cindex scripts +See @ref{Repeat}. -@cindex ornaments +@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 -A variety of symbols can appear above and below notes to indicate -different characteristics of the performance. These symbols can be -added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols +[todo: text cr] + + +@c_ {Text spanner} +@node Text spanner +@subsubsection Text spanner +@cindex Text spanner + +Have crescendo set a text spanner instead of hairpin + +@lilypond[fragment,relative,verbatim] + \context Voice { + \property Voice.crescendoText = "cresc." + \property Voice.crescendoSpanner = #'dashed-line + a''2\mf\< a a \!a + } +@end lilypond + +@c_ {Ottava} +@node Ottava +@subsubsection Ottava +@cindex Ottava +@unnumberedsubsubsec Ottava + +@lilypond[fragment,relative,verbatim] + a'''' b c a + \property Voice.TextSpanner \set #'type = #'dotted-line + \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) + \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") + \property Staff.centralCPosition = #-13 + a\spanrequest \start "text" b c a \spanrequest \stop "text" +@end lilypond + + + +@c_ {Text crescendo and decrescendo} +@unnumberedsubsubsec Text crescendo and decrescendo + +TODO + +@c_ {Span requests} +@node Span requests +@subsubsection Span requests +@cindex Span requests + +@cindex @code{\spanrequest} + +@example + \spanrequest @var{startstop} @var{type} +@end example +@cindex @code{\start} +@cindex @code{\stop} + +Define a spanning request. The @var{startstop} parameter is either -1 +(@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that +describes what should be started. Supported types are @code{crescendo}, +@code{decrescendo}, @code{beam}, @code{slur}. This is an internal +command. Users should use the shorthands which are defined in the +initialization file @file{spanners.ly}. + +You can attach a (general) span request to a note using + +@lilypond[fragment,verbatim,center] + c'4-\spanrequest \start "slur" + c'4-\spanrequest \stop "slur" +@end lilypond + +The slur syntax with parentheses is a shorthand for this. + + +@c_ {Ornaments} +@node Ornaments +@subsection Ornaments +@cindex Ornaments +@menu +* Articulation:: +* Text scripts:: +* Grace notes:: +* Stem tremolo:: +* Arpeggio:: +* Glissando :: +* Dynamics:: +* Bar lines:: +* Breath marks:: +* Rehearsal marks:: +@end menu + +@c_ {Articulation} +@node Articulation +@subsubsection Articulation +@cindex Articulation + +@cindex articulations +@cindex scripts +@cindex ornaments + +A variety of symbols can appear above and below notes to indicate +different characteristics of the performance. These symbols can be +added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols are defined in @file{script.ly} and @file{script.scm}. Symbols can be forced to appear above or below the note by writing `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}' respectively. Here is a chart showing symbols above notes, with the name of the corresponding symbol appearing underneath. -@mudela[] +@lilypond[] \score { < \notes { + \property Score.LyricSyllable \override #'font-family = +#'typewriter + \property Score.LyricSyllable \override #'font-shape = #'upright c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata c''-\stopped c''-\staccato c''-\tenuto c''-\upbow c''-\downbow c''^\lheel c''-\rheel c''^\ltoe @@ -1115,7 +1297,7 @@ name of the corresponding symbol appearing underneath. c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall c''-\thumb c''-\segno c''-\coda } - \context Lyrics \lyrics { + \context Lyrics \lyrics { accent__ marcato__ staccatissimo__ fermata stopped__ staccato__ tenuto__ upbow downbow__ lheel__ rheel__ ltoe @@ -1131,26 +1313,35 @@ name of the corresponding symbol appearing underneath. } } -@end mudela +@end lilypond + +@c_ {Text scripts} +@node Text scripts +@subsubsection Text scripts +@cindex Text scripts + +FIXME: markup In addition, it is possible to place arbitrary strings of text or -TeX above or below notes by using a string instead of an -identifier: `@code{c^"text"}'. Fingerings -@cindex fingering - can be -placed by simply using digits. All of these note ornaments appear in -the printed output but have no effect on the MIDI rendering of the -music. +@TeX{} above or below notes by using a string instead of an +identifier: @code{c^"text"}. Fingerings +can be placed by simply using digits. All of these note ornaments +appear in the printed output but have no effect on the MIDI rendering of +the music. + +@c_ {Fingerings} +@unnumberedsubsubsec Fingerings +@cindex Fingerings To save typing, fingering instructions (digits 0 to 9 are supported) and single characters shorthands exist for a few common symbols -@mudela[] - +@lilypond[] \score { - \notes { - \property Voice.textStyle = typewriter + \notes \context Voice { + \property Voice.TextScript \set #'font-family = #'typewriter + \property Voice.TextScript \set #'font-shape = #'upright c''4-._"c-." s4 c''4--_"c-{}-" s4 c''4-+_"c-+" s4 @@ -1168,24 +1359,14 @@ common symbols } } -@end mudela +@end lilypond -Dynamic marks are specified by using an identifier after a note: -`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'. -The available dynamic marks are: -@code{\ppp}@keyindex{ppp}, -@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp}, -@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff}, -@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff}, -@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf}, -@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp}, -@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and -@code{\rfz}@keyindex{rfz}. +@cindex @code{\textscript} @example - \textscript@keyindex{textscript} @var{text} @var{style} + \textscript @var{text} @var{style} @end example Defines a text to be printed over or under a note. @var{style} is a @@ -1203,909 +1384,1470 @@ c4-\textscript "foo" "normal" @end quotation -This is equivalent to `@code{c4-6 c4-"foo"}'. - +This is equivalent to @code{c4-6 c4-"foo"}. +@cindex @code{\script} @cindex scripts @example - \script@keyindex{script} @var{alias} + \script @var{alias} @end example +@cindex @code{\script} -Prints a symbol above or below a note. The argument is a string -which points into the script-alias table defined in @file{script.scm}. -The scheme definitions specify whether the symbol follows notes into -the staff, dependence of symbol placement on staff direction, and a -priority for placing several symbols over one note. Usually the -@code{\script}@keyindex{script} keyword is not used directly. Various +Prints a symbol above or below a note. The argument is a string which +points into the script-alias table defined in @file{scm/script.scm}, for +information on how to add scripts, read the comments in that file. +Usually the @code{\script} keyword is not used directly. Various helpful identifier definitions appear in @file{script.ly}. -@cindex slur - -Slurs connects chords and try to avoid crossing stems. A slur is -started with `@code{(}' and stopped with `@code{)}'. The -starting `@code{(}' appears to the right of the first note in -the slur. The terminal `@code{)}' appears to the left of the -first note in the slur. This makes it possible to put a note in -slurs from both sides: - -@mudela[fragment,verbatim,center] - f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 -@end mudela - - -@cindex crescendo - -A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated -with @code{\rc}@keyindex{rc}. A decrescendo mark is started with -@code{\decr}@keyindex{decr} and terminated with -@code{\rced}@keyindex{rced}. There are also shorthands for these -marks. A crescendo can be started with @code{\<}@keyindex{<} and a -decrescendo can be started with @code{\>}@keyindex{>}. Either one can -be terminated with @code{\!}@keyindex{"!}. Note that @code{\!} -must go before the last note of the dynamic mark whereas @code{\rc} -and @code{\rced} go after the last note. Because these marks are -bound to notes, if you want to get several marks during one note, you -must use spacer notes. - -@mudela[fragment,verbatim,center] - c'' \< \! c'' d'' \decr e'' \rced - < f''1 { s4 \< \! s2 \> \! s4 } > -@end mudela - - -@example - - \spanrequest@keyindex{spanrequest} @var{startstop} @var{type} -@end example - -Define a spanning request. The @var{startstop} parameter is either -1 -(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and -@var{type} is a string that describes what should be started. -Supported types are @code{crescendo}, @code{decrescendo}, -@code{beam}, @code{slur}. This is an internal command. Users should -use the shorthands which are defined in the initialization file -@file{spanners.ly}. - -You can attach a (general) span request to a note using - -@mudela[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" -@end mudela -The slur syntax with parentheses is a shorthand for this. +@c_ {Grace notes} +@node Grace notes +@subsubsection Grace notes +@cindex Grace notes +See @ref{Grace music}. +@c_ {Stem tremolo} +@node Stem tremolo +@subsubsection Stem tremolo @cindex tremolo marks +@cindex @code{tremoloFlags} -@node stem tremolo, , , Reference Manual +[FIXME: should be \repeat] Tremolo marks can be printed on a single note by adding `@code{:}[@var{length}]' after the note. The length must be at least 8. A @var{length} value of 8 gives one line across the note stem. If the length is omitted, then the last value is -used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was +used, or the value of the @code{tremoloFlags} property if there was no last value. -@mudela[verbatim,fragment,center] +@lilypond[verbatim,fragment,center] c'2:8 c':32 -@end mudela +@end lilypond +@c_ {Arpeggio} +@node Arpeggio +@subsubsection Arpeggio +@cindex Arpeggio -@node Compound music expressions, , , Reference Manual -@section Compound music expressions +@cindex broken arpeggio +@cindex @code{\arpeggio} -@cindex compound music expressions +You can specify an @rgrob{Arpeggio} sign on a chord by issuing an +@c FIXME +@c @code{\arpeggio} request: +@code{\arpeggio} request: -Music expressions are compound data structures. You can nest music -expressions any way you like. This simple example shows how three -chords can be expressed in two different ways: -@mudela[fragment,verbatim,center] - \notes \context Staff { - \cadenzaOn - - < { a b c' } { c' d' e' } > - } -@end mudela +@quotation +@lilypond[fragment,relative,verbatim] + \context Voice +@end lilypond +@end quotation -@cindex context selection -@c @keyindex{context} +Typesetting of simultanious chords with arpeggios can be controlled with +the property @code{PianoStaff.connectArpeggios} @footnote{ FIXME: +connectArpeggios. Can't find the English terms for two kinds of +arpeggio (Dutch: gebroken arpeggio vs doorlopend arpeggio).} By +default, LilyPond prints broken arpeggios; when set to true, one +extended arpeggio sign is printed. -@example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example +@quotation +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.connectArpeggios = ##t + \context Staff \context Voice + \context Staff=other \context Voice + > +@end lilypond +@end quotation -Interpret @var{musicexpr} within a context of type @var{contexttype}. -If the context does not exist, it will be created. The new context -can optionally be given a name. See -section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more -information on interpretation contexts. +@c_ {Glissando} +@node Glissando +@subsubsection Glissando +@cindex Glissando +@cindex @code{\glissando} -@cindex input modes +A @rgrob{Glissando} line can be requested by issuing a +@c FIXME +@c @code{\glissando} request: +@code{\glissando} request: -@cindex mode switch -Mode switching keywords form compound music expressions: @code{\notes} -@keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords} -@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}. -These expressions do not add anything to the meaning of their -arguments. They are just a way to indicate that the arguments should -be parsed in indicated mode. See section XREF-modes [FIXME] for more -information on modes. +@quotation +@lilypond[fragment,relative,verbatim] + c'' \glissando c' +@end lilypond +@end quotation -More information on context selection can be found in -section XREF-contextselection [FIXME]. +Printing of the additional text @samp{gliss.} must be done manually. +@c_ {Follow Thread} +@subsubsection Follow Thread +@cindex follow thread +@cindex staff switching +@cindex cross staff -@cindex sequential music +@c Documented here because it looks like a glissando... +@cindex @code{followThread} +A glissando-like line can be printed to connect notes whenever a thread +switches to another staff. This is enabled if the property +@code{PianoStaff.followThread} is set to true: +@quotation +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.followThread = ##t + \context Staff \context Voice { + c'1 + \translator Staff=two + b2 a + } + \context Staff=two {\clef bass; \skip 1*2;} + > +@end lilypond +@end quotation -@example - \sequential@keyindex{sequential} - @code{@{} @var{musicexprlist} @code{@}} -@end example +@c_ {Dynamics} +@node Dynamics +@subsubsection Dynamics +@cindex Dynamics -This means that list should be played or written in sequence, i.e., -the second after the first, the third after the second. The duration -of sequential music is the the sum of the durations of the elements. -There is a shorthand, which leaves out the keyword: +@unnumberedsubsec Dynamics -@example +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} - @code{@{} @var{musicexprlist} @code{@}} -@end example +Dynamic marks are specified by using an identifier after a note: +@code{c4-\ff} (the dash is optional for dynamics: `@code{c4 \ff})'. +The available dynamic marks are: +@code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, +@code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, +@code{\fp}, @code{\sf}, +@code{\sff}, @code{\sp}, +@code{\spp}, @code{\sfz}, and +@code{\rfz}. +See also @ref{Crescendo and Decrescendo} -@cindex simultaneous music +@c_ {Bar lines} +@node Bar lines +@subsubsection Bar lines +@cindex Bar lines -@indexcode{<} -@indexcode{>} +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars @example + \bar @var{bartype}; +@end example - \simultaneous@keyindex{simultaneous} - @code{@{} @var{musicexprlist} @code{@}} +This is a short-cut for doing +@example + \property Score.whichBar = @var{bartype} @end example -It constructs a music expression where all of its arguments start at -the same moment. The duration is the maximum of the durations of the -elements. The following shorthand is a common idiom: +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeat}, @ref{Volta}, and the documentation of @code{whichBar} in +@ref{(lilypond-internals)LilyPond context properties}. -@example - @code{<} @var{musicexprlist} @code{>} -@end example +[FIXME] -If you try to use a chord as the first thing in your score, you might -get multiple staffs instead of a chord. +@c_ {Breath marks} +@node Breath marks +@subsubsection Breath marks +@cindex Breath marks -@mudela[verbatim,center] - \score { - \notes - \paper { - linewidth = -1.; - } - } -@end mudela +@c_ {Rehearsal marks} +@node Rehearsal marks +@subsubsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} -This happens because the chord is interpreted by a score context. -Each time a note is encountered a default Voice context (along with a -Staff context) is created. The solution is to explicitly instantiate -a Voice context: +@example + \mark @var{unsigned}; +@cindex @code{Mark_engraver} + \mark @var{string}; +@end example -@mudela[verbatim,center] - \score { - \notes\context Voice - \paper { - linewidth = -1.; - } - } -@end mudela +Prints a mark over or under the staff. +@c_ {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check -@cindex relative pitch specification +@cindex bar check +@cindex @code{barCheckNoSynchronize} +@cindex @code{|} -@node relative, , , Reference Manual -It is easy to get confused by octave changing marks and accidentally -putting a pitch in the wrong octave. A much better way of entering a -note's octave is `the relative octave' mode. +Bar checks help you find errors in the input: Whenever one is +encountered during interpretation, a warning message is issued if it +doesn't fall at a measure boundary. Depending on the value of +@code{barCheckNoSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. -@example +A bar check is entered using the bar symbol, @code{|} - \relative@keyindex{relative} @var{startpitch} @var{musicexpr} -@end example +This can help you finding errors in the input. -The octave of notes that appear in @var{musicexpr} are calculated as -follows: If no octave changing marks are used, the basic interval -between this and the last note is always taken to be a fourth or -less.@footnote{The interval is determined without regarding -accidentals. A @code{fisis} following a @code{ceses} will be put above -the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}' -can then be added to raise or lower the pitch by an extra octave. -Upon entering relative mode, an absolute starting pitch must be -specified that will act as the predecessor of the first note of -@var{musicexpr}. -Entering scales is straightforward in relative mode. +@c_ {Lyrics entry} +@node Lyrics entry +@section Lyrics entry +@cindex Lyrics entry -@mudela[fragment,verbatim,center] - \relative c' { - c d e f g a b c c, - } -@end mudela +@menu +* Lyrics mode:: +* Printing lyrics:: +* Lyric hyphen:: +* Lyric extender:: +* Addlyrics:: +@end menu -And octave changing marks are used for intervals greater than a fourth. +@c_ {Lyrics mode} +@node Lyrics mode +@subsection Lyrics mode +@cindex Lyrics mode + +@cindex lyric mode +@cindex @code{\lyrics} + +Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has +rules that make it easy to include punctuation and diacritical marks in +words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{} +format or a standard encoding without needing quotes. The precise +definition of this mode is ludicrous, and this will remain so until the +authors of LilyPond acquire a deeper understanding of character +encoding, or someone else steps up to fix this. + +A word in Lyrics mode begins with: an alphabetic character, @code{_}, +@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} +through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, +any 8-bit character with ASCII code over 127, or a two-character +combination of a backslash followed by one of @code{`}, @code{'}, +@code{"}, or @code{^}. + +Subsequent characters of a word can be any character that is not a digit +and not white space. One important consequence of this is that a word +can end with `@code{@}}', which may be confusing. However, LilyPond will +issue a warning. Any @code{_} character which appears in an unquoted +word is converted to a space. This provides a mechanism for introducing +spaces into words without using quotes. Quoted words can also be used +in Lyrics mode to specify words that cannot be written with the above +rules. Here are some examples. Not all of these words are printable by +@TeX{}. -@mudela[fragment,verbatim,center] - \relative c'' { - c g c f, c' a, e'' } -@end mudela +@example +Ah! % a word +2B_||_!2B % not a word because it starts with a digit +``Hello'' % not a word because it starts with ` +_ _ _ _ % 4 words, each one a space +@end example -If the preceding item is a chord, the first note of the chord is used -to determine the first note of the next chord. But other notes -within the second chord are determined by looking at the immediately -preceding note. +Since combinations of numbers and dots are used for indicating +durations, you can not enter real numbers in this mode. -@mudela[fragment,verbatim,center] - \relative c' { - c - - - } -@end mudela +[todo: include short table showing differences] -The pitch after the @code{\relative} contains a notename. To parse -the pitch as a notename, you have to be in note mode, so there must -be a surrounding @code{\notes}@keyindex{notes} keyword (which is not -shown here). +@cindex lyrics expressions -The relative conversion will not affect @code{\transpose} or -@code{\relative} sections in its argument. If you want to use -relative within transposed music, you must place an additional -@code{\relative} inside the @code{\transpose}. +Syllables are entered like notes, with pitches replaced by text. For +example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each +with quarter note duration. Note that the hyphen has no special +meaning for lyrics, and does not introduce special symbols. See +section @ref{Lexical modes} for a description of what is interpreted as +lyrics. -It is strongly recommended to use relative pitch mode: less work, -less error-prone, and more readable. +Spaces can be introduced into a lyric either by using quotes +(@code{"}) or by using an underscore without quotes: @code{He_could4 +not4}. All unquoted underscores are converted to spaces. Printing +lyrics is discussed in section @ref{lyricprint}. +@c_ {Printing Lyrics} +@node Printing lyrics +@subsection lyricprint +@cindex lyrics -Chord names are a way to generate simultaneous music expressions that -correspond with traditional chord names. It can only be used in -Chord mode (see section XREF-modes [FIXME]). -@example +@cindex printing!lyrics - @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. -@end example -@var{tonic} should be the tonic note of the chord, and @var{duration} -is the chord duration in the usual notation. There are two kinds of -modifiers. One type is @emph{chord additions}, which are obtained by -listing intervals separated by dots. An interval is written by its -number with an optional `@code{+}' or `@code{-}' to indicate raising or -lowering by half a step. Chord additions has two effects: It adds -the specified interval and all lower odd numbered intervals to the -chord, and it may lower or raise the specified interval. Intervals -must be separated by a dot (`@code{.}'). +Lyric syllables must be interpreted within a @code{Lyrics} context -@quotation +@cindex context!Lyrics + for printing them. -@mudela[fragment,verbatim] -\transpose c'' { - \chords { - c1 c:3- c:7 c:8 - c:9 c:9-.5+.7+ c:3-.5- c:4.6.8 - } +Here is a full example: + +@quotation +@lilypond[verbatim] +\score { + < + \notes \transpose c'' { + c d e c | c d e c | + e f g2 | e4 f g2 \bar "|."; + } + \context Lyrics \lyrics { + Va-4 der Ja- cob Va- der Ja- cob + Slaapt gij nog?2 Slaapt4 gij nog?2 + } + > } -@end mudela +@end lilypond @end quotation -The second type of modifier that may appear after the `@code{:}' is a -named modifier. Named modifiers are listed in the file -@file{chord-modifiers.ly}. The available modifiers are `@code{m}' and -`@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which -raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th, -`@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}' -which replaces the 5th with a 4th. +You may want a continuous line after the syllables to show melismata. +To achieve this effect, add a @code{__} lyric as a separate word +after the lyric to be extended. This will create an extender, a line +that extends over the entire duration of the lyric. This line will +run all the way to the start of the next lyric, so you may want to +shorten it by using a blank lyric (using @code{_}). @quotation -@mudela[fragment,verbatim] -\transpose c'' { - \chords { - c1:m c:min7 c:maj c:aug c:dim c:sus - } +@lilypond[verbatim] +\score { + < + \notes \relative c'' { + a4 () b () c () d | c () d () b () a | c () d () b () a + } + \context Lyrics \lyrics { + foo1 __ | bar2. __ _4 | baz1 __ + } + > } -@end mudela +@end lilypond @end quotation - - -Chord subtractions are used to eliminate notes from a chord. The -notes to be subtracted are listed after a `@code{^}' character, -separated by dots. -@mudela[fragment,verbatim,center] - \transpose c'' { - \chords { - c1^3 c:7^5.3 c:8^7 - } - } -@end mudela + +If you want to have hyphens centered between syllables (rather than +attached to the end of the first syllable) you can use the special +`@code{-}@code{-}' lyric as a separate word between syllables. This +will result in a hyphen which length varies depending on the space +between syllables, and which will be centered between the syllables. +For example: -Chord inversions can be specified by appending `@code{/}@indexcode{/}' and -the name of a single note to a chord. This has the effect of -lowering the specified note by an octave so it becomes the lowest -note in the chord. If the specified note is not in the chord, a -warning will be printed. +@quotation -@mudela[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/e c/g c:7/e +@lilypond[verbatim] +\score { + < + \notes \transpose c'' { + c d e c | c d e c | + e f g2 | e4 f g2 \bar "|."; } - } - -@end mudela - -Bass notes can be added by `@code{/+}@indexcode{/+}' and -the name of a single note to a chord. This has the effect of -adding the specified note to the chord, lowered by an octave, -so it becomes the lowest note in the chord. - -@mudela[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/+c c/+g c:7/+b + \context Lyrics \lyrics { + Va4 -- der Ja -- cob | Va -- der Ja -- cob | + Slaapt gij nog?2 | Slaapt4 gij nog?2 } - } + > +} -@end mudela +@end lilypond +@end quotation -Throughout these examples, chords have been shifted around the staff -using @code{\transpose}. -You should not combine @code{\relative} with named chords. +@c_ {Lyric hyphen} +@node Lyric hyphen +@subsection Lyric hyphen +@cindex Lyric hyphen -@cindex tuplets +The syntax for a spanning hyphen (i.e., a hyphen that will be printed +between two lyric syllables) is `@code{-}@code{-}'. -Tuplets are made out of a music expression by multiplying their -duration with a fraction. +@c_ {Lyric extender} +@node Lyric extender +@subsection Lyric extender +@cindex Lyric extender +@cindex extender +@cindex lyric extender +@cindex hyphen -@example +The syntax for an extender mark is @code{__}. This syntax can only +be used within lyrics mode. - \times@keyindex{times} @var{fraction} @var{musicexpr} -@end example -The duration of @var{musicexpr} will be multiplied by the fraction. -In print, the fraction's denominator will be printed over the notes, -optionally with a bracket. The most common tuplet is the triplet in -which 3 notes have the length of 2, so the notes are 2/3 of -their written length: -@mudela[fragment,verbatim,center] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 -@end mudela +@c_ {Addlyrics} +@node Addlyrics +@subsection Addlyrics +@cindex Addlyrics -@cindex grace notes +[explain automatic phrasing] +@cindex automatic lyric durations +@cindex @code{\addlyrics} +If you have lyrics that are set to a melody, you can import the rhythm +of that melody into the lyrics using @code{\addlyrics}. The syntax for +this is @example - - \grace@keyindex{grace} @var{musicexpr} + \addlyrics @var{musicexpr1 musicexpr2} @end example -A grace note expression has duration 0; the next real note is -assumed to be the main note. - -You cannot have the grace note after the main note, in terms of -duration, and main notes, but you can typeset the grace notes to the -right of the main note using the property -@code{graceAlignPosition}@indexcode{graceAlignPosition}. +This means that both @var{musicexpr1} and @var{musicexpr2} are +interpreted, but that every non-command atomic music expression +(``every syllable'') in @var{musicexpr2} is interpreted using timing +of @var{musicexpr1}. +@cindex @code{automaticMelismata} -When grace music is interpreted, a score-within-a-score is set up: -@var{musicexpr} has its own time bookkeeping, and you could (for -example) have a separate time signature within grace notes. While in -this score-within-a-score, you can create notes, beams, slurs, etc. -Unbeamed eighth notes and shorter by default have a slash through the -stem. This behavior can be controlled with the -@code{stemStyle}@indexcode{stemStyle} property. +If the property @code{automaticMelismata} is set in the +context of @var{musicexpr1}, no lyrics will be put on slurred or tied +notes. @quotation - -@mudela[fragment,verbatim] -\relative c'' { - \grace c8 c4 \grace { [c16 c16] } c4 - \grace { \property Grace.stemStyle = "" c16 } c4 +@lilypond[verbatim,fragment] +\addlyrics +\transpose c'' { + \property Voice.automaticMelismata = ##t + c8 () cis d8. e16 f2 } - -@end mudela +\context Lyrics \lyrics { + do4 re mi fa } +@end lilypond @end quotation -At present, nesting @code{\grace}@keyindex{grace} notes, e.g. - -@example - - @code{\grace @{ \grace c32 c16 @} c4} -@end example - -may result in run-time errors of LilyPond. Since the meaning of such -a construct is unclear, we don't consider this a loss. Similarly, -juxtaposing two @code{\grace} sections is syntactically valid, but -makes no sense and may cause runtime errors. - -Ending a staff or score with grace notes may also generate a run-time -error, since there will be no main note to attach the grace notes to. +You should use a single rhythm melody, and single rhythm lyrics (a +constant duration is the obvious choice). If you do not, you will get +undesired effects when using multiple stanzas: +@quotation +@lilypond[verbatim,fragment] +\addlyrics +\transpose c'' { + c8 () cis d8. e16 f2 +} +\context Lyrics \lyrics +< { do4 re mi fa } + { do8 re mi fa } > +@end lilypond +@end quotation -@cindex repeats +It is valid (but probably not very useful) to use notes instead of +lyrics for @var{musicexpr2}. -@node Repeats, , , Reference Manual -In order to specify repeats, use the @code{\repeat}@keyindex{repeat} -keyword. Since repeats look and sound differently when played or -printed, there are a few different variants of repeats. -@table @samp - @item unfolded - Repeated music is fully written (played) out. Useful for MIDI - output. +@c_ {Chord entry} +@node Chord entry +@section Chord entry +@cindex Chord entry - @item volta - This is the normal notation: Repeats are not written out, but - alternative endings (voltas) are printed, left to right. +@menu +* Chords mode:: +* Entering named chords:: +* Printing named chords:: +@end menu - @item folded - Alternative endings are written stacked, which is useful for - lyrics. -@end table +@c_ {Chords mode} +@node Chords mode +@subsection Chords mode +@cindex Chords mode -The syntax for repeats is +Chord mode is introduced by the keyword +@code{\chords}. It is similar to Note mode, but +words are also looked up in a chord modifier table (containing +@code{maj}, @code{dim}, etc). -@example +Since combinations of numbers and dots are used for indicating +durations, you can not enter real numbers in this mode. Dashes +and carets are used to indicate chord additions and subtractions, +so scripts can not be entered in Chord mode. - \repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example +@c_ {Entering named chords} +@node Entering named chords +@subsection Entering named chords +@cindex Chords names -If you have alternative endings, you may add +Chord names are a way to generate simultaneous music expressions that +correspond with traditional chord names. It can only be used in +Chord mode (see section @ref{Lexical modes}). @example - \alternative@keyindex{alternative} - @code{@{} @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @code{@}} + @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. @end example -where each @var{alternative} is a Music expression. - -Normal notation repeats are used like this: - -@quotation +@var{tonic} should be the tonic note of the chord, and @var{duration} +is the chord duration in the usual notation. There are two kinds of +modifiers. One type is @emph{chord additions}, which are obtained by +listing intervals separated by dots. An interval is written by its +number with an optional @code{+} or @code{-} to indicate raising or +lowering by half a step. Chord additions has two effects: It adds +the specified interval and all lower odd numbered intervals to the +chord, and it may lower or raise the specified interval. Intervals +must be separated by a dot (@code{.}). -@mudela[fragment,verbatim] - c'1 - \repeat volta 2 { c'4 d' e' f' } - \repeat volta 2 { f' e' d' c' } -@end mudela -@end quotation +Throughout these examples, chords have been shifted around the staff +using @code{\transpose}. -With alternative endings: @quotation -@mudela[fragment,verbatim] - c'1 - \repeat volta 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1 c:3- c:7 c:8 + c:9 c:9-.5+.7+ c:3-.5- c:4.6.8 + } +} -@end mudela +@end lilypond @end quotation -Folded repeats look like this:@footnote{Folded repeats offer little -more over simultaneous music. However, it is to be expected that -more functionality -- especially for the MIDI backend -- will be -implemented.} - -@quotation - -@mudela[fragment,verbatim] - c'1 - \repeat fold 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } +@cindex @code{aug} +@cindex @code{dim} +@cindex @code{maj} +@cindex @code{sus} -@end mudela -@end quotation +The second type of modifier that may appear after the @code{:} is a +named modifier. Named modifiers are listed in the file +@file{chord-modifiers.ly}. The available modifiers are @code{m} and +@code{min} which lower the 3rd half a step, `@code{aug}' which +raises the 5th, `@code{dim}' which lowers the 5th, +`@code{maj}' which adds a raised 7th, and `@code{sus}' +which replaces the 5th with a 4th. @quotation -@mudela[fragment,verbatim] -\context Staff { - \relative c' { - \partial 4; - \repeat volta 2 { e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } { a | a a a a | b1 } } +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1:m c:min7 c:maj c:aug c:dim c:sus } } -@end mudela +@end lilypond @end quotation + -If you don't give enough alternatives for all of the repeats, then -the first alternative is assumed to be repeated often enough to equal -the specified number of repeats. - -@quotation +Chord subtractions are used to eliminate notes from a chord. The +notes to be subtracted are listed after a @code{^} character, +separated by dots. -@mudela[fragment,verbatim] -\context Staff { - \relative c' { - \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } - {\partial 1; e4 e e } - {\partial 1; a a a a | b1 } } +@lilypond[fragment,verbatim,center] + \transpose c'' { + \chords { + c1^3 c:7^5.3 c:8^7 + } } -} +@end lilypond +@cindex @code{/} -@end mudela -@end quotation +Chord inversions can be specified by appending `@code{/}' and +the name of a single note to a chord. This has the effect of +lowering the specified note by an octave so it becomes the lowest +note in the chord. If the specified note is not in the chord, a +warning will be printed. -It is possible to nest @code{\repeat}. This is not entirely -supported: the notes will come be in the right places, but the repeat -bars will not. +@lilypond[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/e c/g c:7/e + } + } +@end lilypond +@cindex @code{/+} +Bass notes can be added by `@code{/+}' and +the name of a single note to a chord. This has the effect of +adding the specified note to the chord, lowered by an octave, +so it becomes the lowest note in the chord. -@cindex transposition of pitches +@lilypond[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/+c c/+g c:7/+b + } + } -@node transpose, , , Reference Manual +@end lilypond -A music expression can be transposed with -@code{\transpose}@keyindex{transpose}. The syntax is +The most interesting application is printing chords using chord names, +See @ref{Chord names}. -@example +You should not combine @code{\relative} with named chords. [FIXME] - \transpose @var{pitch} @var{musicexpr} -@end example +@c_ {Printing named chords} +@node Printing named chords +@subsection Printing named chords -This means that middle C in @var{musicexpr} is transposed to -@var{pitch}. +@cindex chord names +@cindex chords -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose cis'} or @code{\transpose des'} will transpose up half -a tone. The first version will print sharps and the second version -will print flats. +@cindex printing!chord names +@cindex @code{ChordNames} +@cindex @code{ChordNameVoice} + +For displaying printed chord names, use the @code{ChordNames} and +@code{ChordNameVoice} contexts. The chords may be entered either using +the notation described above, or directly using simultaneous music. @quotation +@lilypond[verbatim] +scheme = \notes { + \chords {a1 b c} +} +\score { + \notes< + \context ChordNamesVoice \scheme + \context Staff \transpose c'' \scheme + > + \paper { linewidth = -1.; } +} +@end lilypond +@end quotation -@mudela[fragment,verbatim] -\context Staff { - \clef "F"; - { \key e; c d e f } - \clef "G"; - \transpose des'' { \key e; c d e f } - \transpose cis'' { \key e; c d e f } +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 } -@end mudela +\score { + \notes < + \context ChordNames \scheme + \context Staff \transpose c'' \scheme + > + \paper{ + linewidth = 40 * \staffspace; + \translator { + \ChordNamesContext + chordChanges = ##t + } + } +} +@end lilypond @end quotation -If you want to use both @code{\transpose} and @code{\relative}, then -you must use @code{\transpose} first. @code{\relative} will have no -effect music that appears inside a @code{\transpose}. +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: -@cindex automatic lyric durations +@quotation +@lilypond[verbatim,center] +scheme = \notes { + + + +} -If you have lyrics that are set to a melody, you can import the -rhythm of that melody into the lyrics using @code{\addlyrics}. -@keyindex{addlyrics} The syntax for this is +\score { + < + \context ChordNamesVoice \scheme + \context Staff \scheme + > + \paper { linewidth = -1.; } +} +@end lilypond +@end quotation -@example +To specify chord inversions, append @code{/}. To specify an +added bass note, append @code{/+ + \paper { linewidth = -1.; } +} +@end lilypond +@end quotation -If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the -context of @var{musicexpr1}, no lyrics will be put on slurred or tied -notes. +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 - -@mudela[verbatim,fragment] -\addlyrics -\transpose c'' { - \property Voice.automaticMelismata = "1" - c8 () cis d8. e16 f2 +@lilypond[verbatim] +\include "english.ly" + +scheme = \chords { + c % Major triad + cs:m % Minor triad + df:m5- % Diminished triad + c:5^3 % Root-fifth chord + c:4^3 % Suspended fourth triad + c:5+ % Augmented triad + c:2^3 % "2" chord + c:m5-.7- % Diminished seventh + c:7+ % Major seventh + c:7.4^3 % Dominant seventh suspended fourth + c:5+.7 % Augmented dominant seventh + c:m5-.7 % "Half" diminished seventh + c:5-.7 % Dominant seventh flat fifth + c:5-.7+ % Major seventh flat fifth + c:m7+ % Minor-major seventh + c:m7 % Minor seventh + c:7 % Dominant seventh + c:6 % Major sixth + c:m6 % Minor sixth + c:9^7 % Major triad w/added ninth + c:6.9^7 % Six/Nine chord + c:9 % Dominant ninth + c:7+.9 % Major ninth + c:m7.9 % Minor ninth } -\context Lyrics \lyrics { - do4 re mi fa } -@end mudela +\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 -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: - +Similarly, Jazz style chord names are implemented as a variation on +American style names: @quotation - -@mudela[verbatim,fragment] -\addlyrics -\transpose c'' { - c8 () cis d8. e16 f2 +@lilypond[verbatim] +scheme = \chords { + % major chords + c + c:6 % 6 = major triad with added sixth + c:maj % triangle = maj + c:6.9^7 % 6/9 + c:9^7 % add9 + + % minor chords + c:m % m = minor triad + c:m.6 % m6 = minor triad with added sixth + c:m.7+ % m triangle = minor major seventh chord + c:3-.6.9^7 % m6/9 + c:m.7 % m7 + c:3-.9 % m9 + c:3-.9^7 % madd9 + + % dominant chords + c:7 % 7 = dominant + c:7.5+ % +7 = augmented dominant + c:7.5- % 7b5 = hard diminished dominant + c:9 % 7(9) + c:9- % 7(b9) + c:9+ % 7(#9) + c:13^9.11 % 7(13) + c:13-^9.11 % 7(b13) + c:13^11 % 7(9,13) + c:13.9-^11 % 7(b9,13) + c:13.9+^11 % 7(#9,13) + c:13-^11 % 7(9,b13) + c:13-.9-^11 % 7(b9,b13) + c:13-.9+^11 % 7(#9,b13) + + % half diminished chords + c:m5-.7 % slashed o = m7b5 + c:9.3-.5- % o/7(pure 9) + + % diminished chords + c:m5-.7- % o = diminished seventh chord } -\context Lyrics \lyrics -< { do4 re mi fa } - { do8 re mi fa } > -@end mudela +\score { + \notes < + \context ChordNames \scheme + \context Staff \transpose c'' \scheme + > + \paper { + \translator { + \ChordNamesContext + ChordName \override #'word-space = #1 + ChordName \override #'style = #'jazz + } + } +} +@end lilypond @end quotation -It is valid (but probably not very useful) to use notes instead of -lyrics for @var{musicexpr2}. +@c_ {Page layout} +@node Page layout +@section Page layout +@cindex Page layout -@node Ambiguities, , , Reference Manual -@section Ambiguities +@menu +* Paper block:: +* Paper variables:: +* Font Size:: +* Paper size:: +* Line break:: +* Page break:: +@end menu -@cindex ambiguities +@c_ {Paper block} +@node Paper block +@subsection Paper block +@cindex Paper block + +The most important output definition is the @code{\paper} block, for +music notation. The syntax is -The grammar contains a number of ambiguities.@footnote{The authors -hope to resolve them at a later time.} +@example + @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} +@end example + +where each of the items is one of @itemize @bullet - @item The assignment + @item An assignment. The assignment must be terminated by a + semicolon. - @example -foo = bar -@end example + @item A context definition. See section @ref{contextdefs} for + more information on context definitions. - can be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. +@ignore - @item The assignment + FIXME - @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 + + A margin shape declaration. The syntax is +@cindex @code{\shape} + @example - @item If you do a nested repeat like + \shape @var{indent1}@code{,} @var{width1}@code{,} + @var{indent2}@code{,} @var{width2} @dots{} @code{;} + @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 + + @item \stylesheet declaration. Its syntax is + @example + \stylesheet @var{alist} + @end example + + See @file{font.scm} for details of @var{alist}. +@end itemize + +@c_ {Paper variables} +@node Paper variables +@subsection Paper variables +@cindex Paper variables + +The paper block has some variables you may want to use or change: + +@table @code +@cindex @code{indent} + @item @code{indent} + The indentation of the first line of music. +@cindex @code{staffspace} + + @item @code{staffspace} + The distance between two staff lines, calculated from the center + of the lines. You should use either this or @code{rulethickness} + as a unit for distances you modify. + +@cindex @code{linewidth} + @item @code{linewidth} + Sets the width of the lines. If set to -1.0, a single + unjustified line is produced. If you use this variable, you + probably want to define it in staff spaces, ie + @example + linewidth = 30 * \staffspace; + @end example +@cindex @code{textheight} + + @item @code{textheight} + Sets the total height of the music on each page. Only used by + ly2dvi. +@cindex @code{interscoreline} + + @item @code{interscoreline} + Sets the spacing between the score lines. Defaults to 16 pt. +@cindex @code{interscorelinefill} + + @item @code{interscorelinefill} + If set to a positive number, the distance between the score + lines will stretch in order to fill the full page. In that + case @code{interscoreline} specifies the minimum spacing. + Defaults to 0. +@cindex @code{stafflinethickness} + + @item @code{stafflinethickness} + Determines the thickness of staff lines, and also acts as a scaling + parameter for other line thicknesses. +@end table + + +@c_ {Font size} +@node Font Size +@subsection Font size +@cindex font size + +The Feta font provides musical symbols at six different sizes. These +fonts are 11 point, 13 point, 16 point, 20 point, +23 point, and 26 point. The point size of a font is the +height of the five lines in a staff when displayed in the font. + +Definitions for these sizes are the files @file{paperSZ.ly}, where +@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of +these files, the identifiers @code{paperEleven}, @code{paperThirteen}, +@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and +@code{paperTwentysix} are defined respectively. The default +@code{\paper} block is also set. + +The font definitions are generated using a Scheme function. For more +details, see the file @file{font.scm}. + + + +@c_ {Paper size} +@node Paper size +@subsection Paper size +@cindex Paper size + +@cindex paper size +@cindex page size +@cindex @code{papersize} + +To change the paper size, you must first set the +@code{papersize} variable at top level. Set it to +the strings @code{a4}, @code{letter}, or @code{legal}. After this +specification, you must set the font as described above. If you want +the default font, then use the 20 point font. The new paper size will +not take effect if the font is not loaded and selected afterwards. + +@example + papersize = "a4" + \include "paper16.ly" + + \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}) + + + + + + + +@c_ {Line break} +@node Line break +@subsection Line break +@cindex Line break + + +@cindex @code{\penalty} + +@example + \penalty @var{int} @code{;} +@end example + +Discourage or encourage line breaks. See @ref{Page layout}. + + + + +@cindex line breaks +@cindex breaking lines + +Line breaks are normally computed automatically. They are chosen such +that the resulting spacing has low variation, and looks neither cramped +nor loose. + +Occasionally you might want to override the automatic breaks; you can do +this by specifying @code{\break} (see also @ref{Pre-defined +Identifiers}). This will force a line break at this point. Do remember +that line breaks can only occur at places where there are barlines. If +you want to have a line break where there is no barline, you can force a +barline by entering @code{\bar "";}. + + + + +@c_ {Page break} +@node Page break +@subsection Page break +@cindex Page break + + +Not implemented, but see @ref{Tricks} + +Page breaks are normally computed by @TeX{}, so they are not under direct +control. However, you can insert a commands into the .tex output to +instruct @TeX{} where to break pages. For more details, see the +example file @file{input/test/between-systems.ly} + + +@cindex page breaks +@cindex breaking pages + + + + + +@c_ {Sound} +@node Sound +@section Sound +@cindex Sound +@menu +* MIDI block:: +* MIDI instrument names:: +* Tempo:: +@end menu + +@c_ {MIDI block} +@node MIDI block +@subsection MIDI block +@cindex MIDI block + + +The MIDI block is analogous to the paper block, but it is somewhat +simpler. The @code{\midi} block can contain: +@cindex MIDI block + +@itemize @bullet + @item a @code{\tempo} definition + @item context definitions +@end itemize + +Assignments in the @code{\midi} block are not allowed. + + + +@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}. + + +@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. + +[FIXME: to appendix ] - @quotation @example -\repeat @dots{} -\repeat @dots{} -\alternative +"acoustic grand" "contrabass" "lead 7 (fifths)" +"bright acoustic" "tremolo strings" "lead 8 (bass+lead)" +"electric grand" "pizzicato strings" "pad 1 (new age)" +"honky-tonk" "orchestral strings" "pad 2 (warm)" +"electric piano 1" "timpani" "pad 3 (polysynth)" +"electric piano 2" "string ensemble 1" "pad 4 (choir)" +"harpsichord" "string ensemble 2" "pad 5 (bowed)" +"clav" "synthstrings 1" "pad 6 (metallic)" +"celesta" "synthstrings 2" "pad 7 (halo)" +"glockenspiel" "choir aahs" "pad 8 (sweep)" +"music box" "voice oohs" "fx 1 (rain)" +"vibraphone" "synth voice" "fx 2 (soundtrack)" +"marimba" "orchestra hit" "fx 3 (crystal)" +"xylophone" "trumpet" "fx 4 (atmosphere)" +"tubular bells" "trombone" "fx 5 (brightness)" +"dulcimer" "tuba" "fx 6 (goblins)" +"drawbar organ" "muted trumpet" "fx 7 (echoes)" +"percussive organ" "french horn" "fx 8 (sci-fi)" +"rock organ" "brass section" "sitar" +"church organ" "synthbrass 1" "banjo" +"reed organ" "synthbrass 2" "shamisen" +"accordion" "soprano sax" "koto" +"harmonica" "alto sax" "kalimba" +"concertina" "tenor sax" "bagpipe" +"acoustic guitar (nylon)" "baritone sax" "fiddle" +"acoustic guitar (steel)" "oboe" "shanai" +"electric guitar (jazz)" "english horn" "tinkle bell" +"electric guitar (clean)" "bassoon" "agogo" +"electric guitar (muted)" "clarinet" "steel drums" +"overdriven guitar" "piccolo" "woodblock" +"distorted guitar" "flute" "taiko drum" +"guitar harmonics" "recorder" "melodic tom" +"acoustic bass" "pan flute" "synth drum" +"electric bass (finger)" "blown bottle" "reverse cymbal" +"electric bass (pick)" "skakuhachi" "guitar fret noise" +"fretless bass" "whistle" "breath noise" +"slap bass 1" "ocarina" "seashore" +"slap bass 2" "lead 1 (square)" "bird tweet" +"synth bass 1" "lead 2 (sawtooth)" "telephone ring" +"synth bass 2" "lead 3 (calliope)" "helicopter" +"violin" "lead 4 (chiff)" "applause" +"viola" "lead 5 (charang)" "gunshot" +"cello" "lead 6 (voice)" @end example - @end quotation - then it is ambiguous to which @code{\repeat} the - @code{\alternative} belongs. This is the classic if-then-else - dilemma. It may be solved by using braces. - @item (an as yet unidentified ambiguity :-) -@end itemize +@c_ {Tempo} +@node Tempo +@subsection Tempo +@cindex Tempo +@cindex beats per minute +@cindex metronome marking -@node Notation conversion specifics, , , Reference Manual -@section Notation conversion specifics +@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. -@cindex automatic beam generation -@node autobeam, , , Reference Manual -By default, LilyPond will generate beams automatically. This feature -can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming} -property to 1. It can be overridden for specific cases by -specifying explicit beams as described in -section XREF-manualbeam [FIXME]. -A large number of Voice properties are used to decide how to generate -beams. Their default values appear in @file{auto-beam-settings.ly}. -In general, beams can begin anywhere, but their ending location is -significant. Beams can end on a beat, or at durations specified by -the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every -quarter note, for example, you could set -@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams -at every three eighth notes you would set it to `@code{"3/8"}'. The -same syntax can be used to specify beam starting points using -@code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}. - -To allow different settings for different time signatures, these -property names can start with `@code{time}@var{N}@code{_}@var{M}' to -restrict the definition to `@var{N}@code{/}@var{M}' time. For example, -to specify beams ending only for 6/8 time you would use the -property @code{Voice.time6_8beamAutoEnd}. To allow different endings -for notes of different durations, the duration can be tacked onto the -end of the property. To specify beam endings for beams that contain -32nd notes, you would use @code{Voice.beamAutoEnd_32}. +@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 -@cindex chord names +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 chords +@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. -@cindex printing!chord names + @item @var{propname} @code{=} @var{value} @code{;} + A property assignment. It is allowed to use reals for + @var{value}. +@end itemize -For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames} -and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered -either using the notation described above, or directly using -simultaneous music. +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 -@mudela[fragment,verbatim] -< - \context ChordNames { - \chords{a b c} \notes{ } - } - \context Staff \notes { - a b c' d' e' - } -> +@example +\paper @{ + foo = \translator @{ @dots{} @} +@} +\score @{ + \notes @{ + @dots{} + @} + \paper @{ + \translator @{ \foo @dots{} @} + @} +@} +@end example -@end mudela @end quotation -LilyPond examines chords specified as lists of notes to determine a -name to give the chord. By default, LilyPond will not try to -identify chord inversions: - -@mudela[fragment,verbatim,center] - < - \context ChordNameVoice \notes { - - } - \context Thread \notes { - - } - > -@end mudela - -If you want inversions to be recognized, you must set the property -@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}: - -@mudela[fragment,verbatim,center] - < - \property Score.chordInversion = 1 - \context ChordNameVoice \notes { - - } - \context Thread \notes { - - } - > -@end mudela - - - -@cindex lyrics - -@cindex printing!lyrics -@node lyricprint, , , Reference Manual +@cindex paper types, engravers, and pre-defined translators -Lyric syllables must be interpreted within a @code{Lyrics} context +Some pre-defined identifiers can simplify modification of +translators. The pre-defined identifiers are: -@cindex context!Lyrics - for printing them. +@table @code +@cindex @code{StaffContext} + @item @code{StaffContext} + Default Staff context. +@cindex @code{RhythmicStaffContext} -Here is a full example: + @item @code{RhythmicStaffContext} + Default RhythmicStaff context. +@cindex @code{VoiceContext} -@quotation + @item @code{VoiceContext} + Default Voice context. +@cindex @code{ScoreContext} -@mudela[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va-4 der Ja- cob Va- der Ja- cob - Slaapt gij nog?2 Slaapt4 gij nog?2 - } - > -} + @item @code{ScoreContext} + Default Score context. +@cindex @code{ScoreWithNumbers} -@end mudela -@end quotation + @item @code{ScoreWithNumbers} + Score context with numbering at the Score level. +@cindex @code{BarNumberingStaffContext} -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{BarNumberingStaffContext} + Staff context with numbering at the Staff level. +@cindex @code{HaraKiriStaffContext} -@quotation + @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} -@mudela[verbatim] -\score { - < - \notes \relative c'' { - a4 () b () c () d | c () d () b () a | c () d () b () a - } - \context Lyrics \lyrics { - foo1 __ | bar2. __ _4 | baz1 __ - } - > -} + @item @code{OrchestralPartStaffContext} +@cindex @code{OrchestralScoreContext} -@end mudela -@end quotation + @item @code{OrchestralScoreContext} +@end table - -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: +Using these pre-defined values, you can remove or add items to the +translator: @quotation -@mudela[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - 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 mudela @end quotation + -@node Notation Contexts, , , Reference Manual -@section Notation Contexts +@c_ {Notation Contexts} +@node Notation Contexts +@subsection Notation Contexts @cindex notation contexts @@ -2119,10 +2861,10 @@ A context is an object that holds the reading state of the expression; it contains information like @itemize @bullet - @item What notes are playing at this point? - @item What symbols will be printed at this point? - @item In what style will they printed? - @item What is the current key signature, time signature, point within + @item What notes are playing at this point? + @item What symbols will be printed at this point? + @item In what style will they printed? + @item What is the current key signature, time signature, point within the measure, etc.? @end itemize @@ -2133,30 +2875,24 @@ a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because these can all contain multiple staffs). Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called playing contexts. +contexts}, those for sound output are called performance contexts. -Contexts are created either manually or automatically. Initially, -the top level music expression is interpreted by the top level -context (the @code{Score} context). When a atomic music expression -(i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested -set of contexts is created that can process these atomic expressions, -as in this example: +Contexts are created either manually or automatically. Initially, the +top level music expression is interpreted by the top level context (the +@code{Score} context). When a atomic music expression (i.e. a note, a +rest, etc.), a nested set of contexts is created that can process these +atomic expressions, as in this example: @example - - @example -\score @{ \notes < c4 > @} +\score @{ \notes @{ c4 @} @} @end example -@end example - The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score} -context. When the note `@code{c4}' itself is interpreted, a set of +context. When the note @code{c4} itself is interpreted, a set of contexts is needed that will accept notes. The default for this is a @code{Voice} context, contained in a @code{Staff} context. Creation of these contexts results in the staff being printed. - @cindex context You can also create contexts manually, and you probably have to do so @@ -2166,24 +2902,26 @@ during the interpretation phase, the @var{musicexpr} argument will be interpreted with a context of type @var{name}. If you specify a name, the specific context with that name is searched. +[type vs id] + If a context of the specified type and name can not be found, a new one is created. For example, @quotation -@mudela[verbatim] +@lilypond[verbatim] \score { \notes \relative c'' { c4 f } } -@end mudela +@end lilypond @end quotation In this example, the @code{c} and @code{d} are printed on the default staff. For the @code{e}, a context Staff called -`@code{another}' is specified; since that does not exist, a new +@code{another} is specified; since that does not exist, a new context is created. Within @code{another}, a (default) Voice context is created for the @code{e4}. When all music referring to a context is finished, the context is ended as well. So after the @@ -2218,7 +2956,7 @@ Lastly, you may wonder, why this: doesn't result in this: -@mudela[] +@lilypond[] \score { \notes \relative c'' { @@ -2226,7 +2964,7 @@ doesn't result in this: } } -@end mudela +@end lilypond For the @code{c4}, a default @code{Staff} (with a contained @code{Voice}) context is created. After the @code{c4} ends, no @@ -2238,95 +2976,6 @@ sequential music is also the default @code{Voice} context. The @code{d4} gets interpreted in the same context as @code{c4}. - - -These are the contexts supplied with the package. They are defined -in the initialization file @file{ly/engraver.ly}. - -@table @samp - @item @code{Grace}@indexcode{Grace} - The context for handling grace notes. It is instantiated - automatically when you use @code{\grace}. Basically, it is an - `embedded' miniature of the Score context. Since this context - needs special interaction with the rest of LilyPond, you should - not explicitly instantiate it. - - @item @code{LyricVoice}@indexcode{LyricVoice} - Corresponds to a voice with lyrics. Handles the printing of a - single line of lyrics. - - @item @code{Thread}@indexcode{Thread} - Handles note heads, and is contained in the Voice context. You - have to instantiate this explicitly if you want to adjust the - style of individual note heads. - - @item @code{Voice}@indexcode{Voice} - Corresponds to a voice on a staff. This context handles the - conversion of dynamic signs, stems, beams, super- and subscripts, - slurs, ties, and rests. - - You have to instantiate this explicitly if you want to have - multiple voices on the same staff. - - @item @code{ChordNamesVoice}@indexcode{ChordNamesVoice} - A voice with chord names. Handles printing of a line of chord - names. - - @item @code{ChordNames}@indexcode{ChordNames} - Typesets chord names. Can contain @code{ChordNamesVoice} - contexts. - - @item @code{Lyrics}@indexcode{Lyrics} - Typesets lyrics. It can contain @code{LyricVoice} contexts. - - @item @code{Staff}@indexcode{Staff} - Handles clefs, bar lines, keys, accidentals. It can contain - @code{Voice} contexts. - - @item @code{RhythmicStaff}@indexcode{RhythmicStaff} - A context like @code{Staff} but for printing rhythms. Pitches are - ignored; the notes are printed on one line. It can contain - @code{Voice} contexts. - - @item @code{GrandStaff}@indexcode{GrandStaff} - Contains @code{Staff} or @code{RhythmicStaff} contexts. It adds a - brace on the left side, grouping the staffs together. The bar - lines of the contained staffs are connected vertically. It can - contain @code{Staff} contexts. - - @item @code{PianoStaff}@indexcode{PianoStaff} - Just like @code{GrandStaff} but with @code{minVerticalAlign} set - equal to @code{maxVerticalAlign} so that interstaff beaming and - slurring can be used. - - @item @code{StaffGroup}@indexcode{StaffGroup} - Contains @code{Staff} or @code{RhythmicStaff} contexts. Adds a - bracket on the left side, grouping the staffs together. The bar - lines of the contained staffs are connected vertically. It can - contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or - @code{Lyrics} contexts. - - @item @code{ChoirStaff}@indexcode{ChoirStaff} - Identical to @code{StaffGroup} except that the contained staffs - are not connected vertically. - - @item @code{Score}@indexcode{Score} - This is the top level notation context. No other context can - contain a @code{Score} context. This context handles the - administration of time signatures. It also makes sure that items - such as clefs, time signatures, and key-signatures are aligned - across staffs. It can contain @code{Lyrics}, @code{Staff}, - @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and - @code{ChoirStaff} contexts. - - You cannot explicitly instantiate a Score context (since it is - not contained in any other context). It is instantiated - automatically when an output definition (a @code{\score} or - @code{\paper} block) is processed. -@end table - - - Properties that are set in one context are inherited by all of the contained contexts. This means that a property valid for the @code{Voice} context can be set in the @code{Score} context (for @@ -2337,670 +2986,567 @@ corresponding to the appropriate context. In this case, the syntax is @example - @var{propname} @code{=} @var{value} @end example This assignment happens before interpretation starts, so a @code{\property} expression will override any predefined settings. -The @code{\property} expression will create any property you specify. -There is no guarantee that a property will be used. So if you spell -a property name wrong, there will be no error message. - The property settings are used during the interpretation phase. They are read by the LilyPond modules where interpretation contexts are built of. These modules are called @emph{translators}. Translators for notation are called @emph{engravers}, and translators for sound are called @emph{performers}. -The precise result of a property is determined by the implementation -of the translator that reads them. Therefore, the result of a -property can vary, since it is implementation and configuration -dependent. - -In order to fully find out what properties are used, you must -currently search the source code for calls to @code{get_property}. -The rest of the section is devoted to an (incomplete) overview of -available properties. -@mbinclude properties.itely -@node Notation output definitions, , , Reference Manual -@section Notation output definitions +@c_ {Lexer innards} +@node Lexer innards +@section Lexer innards +@cindex Lexer innards +@menu +* Top level:: +* Identifiers:: +* Assignments:: +* Lexical details:: +* Lexical modes:: +* Ambiguities:: +@end menu -@cindex output +@c_ {Top level} +@node Top level +@subsection Top level +@cindex Top level -@cindex notation output +This section describes what you may enter at top level. -@cindex output definition -@node paper, , , Reference Manual +@unnumberedsubsec Score definition +@cindex score definition -The most important output definition is the @code{\paper} block, for -music notation. The syntax is +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 - -@itemize @bullet - @item An assignment. The assignment must be terminated by a - semicolon. See section XREF-papervars [FIXME] for information on - paper variables. - - @item A context definition. See section XREF-contextdefs [FIXME] for - more information on context definitions. - - @item - FIXME now in SCM - - A margin shape declaration. The syntax is - - @example - - \shape @var{indent1}@code{,} @var{width1}@code{,} - @var{indent2}@code{,} @var{width2} @dots{} @code{;} - @end example - - @keyindex{shape} - - Each pair of @var{indent} and @var{width} values is a dimension - specifying how far to indent and how wide to make the line. - The indentation and width of successive lines are specified by - the successive pairs of dimensions. The last pair of - dimensions will define the characeristics of all lines beyond - those explicitly specified. - - @item A font declaration. Its syntax is - - @example - - @var{fontsize} @code{=} \font@keyindex{font} @var{fontname} - @end example - - @var{fontsize} is an integer describing the font to be used. - 0 is the default font. @var{fontname} is the basename of - a font (usually a member of the Feta family). -@end itemize - - - -@cindex changing font size and paper size - -The Feta font provides musical symbols at six different sizes. These -fonts are 11 point, 13 point, 16 point, 20 point, -23 point, and 26 point. The point size of a font is the -height of the five lines in a staff when displayed in the font. - -Definitions for these sizes are the files @file{paperSZ.ly}, where -@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include -any of these files, the identifiers @code{paper_eleven}, -@code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty}, -@code{paper_twentythree}, and @code{paper_twentysix} are defined -respectively. The default @code{\paper} block is also set. - -To change the paper size, you must first set the -@code{papersize}@indexcode{papersize} variable at top level. Set it to the strings -@code{a4}, @code{letter}, or @code{legal}. After this specification, -you must set the font as described above. If you want the default -font, then use the 20 point font. The new paper size will not -take effect if the font is not loaded and selected afterwards. Paper -size selection works by loading a file named after the paper size you -select. - - - -@cindex paper variables - -@node Paper variables, , , Reference Manual - -There is a large number of paper variables that are used to control -details of the layout. These variables control the defaults for the -entire score. Usually, they do not have to be changed; they are by -default set to values that depend on the font size in use. The -values are used by the graphic objects while formatting the score; -they are therefore implementation dependent. Most variables are -accompanied by documentation in the initalization file -@file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff -height in points. - -Nevertheless, here are some variables you may want to use or change: - -@table @samp - @item @code{indent}@indexcode{indent} - The indentation of the first line of music. - - @item @code{interline}@indexcode{interline} - The distance between two staff lines, calculated from the center - of the lines. You should use either this or @code{rulethickness} - as a unit for distances you modify. - - @item @code{linewidth}@indexcode{linewidth} - Sets the width of the lines. If set to -1.0, a single - unjustified line is produced. - - @item @code{output}@indexcode{output} - Specifies an alternate name for the the output @file{s}. - A @file{.tex}, @file{.midi} or @file{.ps} extension will be - added to the string you specify. - - @item @code{rulethickness}@indexcode{rulethickness} - Determines the thickness of staff and bar lines. -@end table - - -@node contextdefs, , , Reference Manual - -@cindex context definition - -A notation contexts is defined by the following information +@var{outputdefs} are zero or more output definitions. If no output +definition is supplied, the default @code{\paper} block will be added. -@enumerate i - @item A name. - @item The LilyPond modules that do the actual conversion of music to - notation. Each module is a so-called - @emph{engraver} -@cindex engraver -. +@c_ {Score} +@subsubsection Score +@cindex Score - @item How these modules should cooperate, i.e. which ``cooperation - module'' should be used. This cooperation module is a special - type of engraver. +@c_ {Paper} +@subsubsection Paper +@cindex Paper - @item What other contexts the context can contain, +@c_ {Midi} +@subsubsection Midi +@cindex Midi - @item What properties are defined. -@end enumerate +@c_ {Header} +@subsubsection Header +@cindex Header +@cindex @code{\header} -A context definition has this syntax: +The syntax is @example - - \translator @code{@{} - @var{translatorinit} @var{translatormodifierlist} - @code{@}} + \header @{ @var{key1} = @var{val1}; +@cindex @code{ly2dvi} + @var{key2} = @var{val2}; @dots{} @} @end example -@var{translatorinit} can be an identifier or of the form - -@example - \type @var{typename} @code{;} -@end example +A header describes the file's contents. It can also appear in a +@code{\score} block. Tools like @code{ly2dvi} can use this +information for generating titles. Key values that are used by +@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, +metre, arranger, piece and tagline. -@var{typename} is one of +It is customary to put the @code{\header} at the top of the file. -@table @samp - @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver} - The standard cooperation engraver. +@subsubsection Default output - @item @code{Score_engraver}@indexcode{Score_engraver} - This is cooperation module that should be in the top level context. +A @code{\midi} or @code{\paper} block at top-level sets the default - @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group} - This is a special cooperation module (resembling - @code{Score_engraver}) that is used to created an embedded - `miniscore'. -@end table +paper block for all scores that lack an explicit paper block. -@var{translatormodifierlist} is a list of items where each item is -one of +@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 @code{\consists} @var{engravername} @code{;} - Add @var{engravername} to the list of modules in this context. - Section XREF-engravers [FIXME] contains an overview of the engravers - available. The order of engravers added with @code{\consists} is - significant. - - @item @code{\consistsend} @var{engravername} @code{;} - Analogous to @code{\consists}, but makes sure that - @var{engravername} is always added to the end of the list of - engravers. +@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 - Some engraver types need to be at the end of the list; this - insures they are put there, and stay there, if a user adds or - removes engravers. This command is usually not needed for - end-users. - - @item @code{\accepts} @var{contextname} @code{;} - Add @var{contextname} to the list of context this context can - contain. The first listed context the context to create by - default. - - @item @code{\remove} @var{engravername} @code{;} - Remove a previously added (with @code{\consists}) engraver. - - @item @code{\name} @var{contextname} @code{;} - This sets name of the context, e.g. @code{Staff}, @code{Voice}. If - the name is not specified, the translator won't do anything. +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. - @item @var{propname} @code{=} @var{value} @code{;} - A property assignment. It is allowed to use reals for - @var{value}. +@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 -In the @code{\paper} block, it is also possible to define translator -identifiers. Like other block identifiers, the identifier can only -be used as the very first item of a translator. In order to define -such an identifier outside of @code{\score}, you must do - -@quotation -@example -\paper @{ - foo = \translator @{ @dots{} @} -@} -\score @{ - \notes @{ - @dots{} - @} - \paper @{ - \translator @{ \foo @dots{} @} - @} -@} -@end example +@c_ {Assignments} +@node Assignments +@subsection Assignments +@cindex Assignments -@end 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. +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. -@cindex paper types, engravers, and pre-defined translators +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. -Some pre-defined identifiers can simplify modification of -translators. The pre-defined identifiers are: +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. -@table @samp - @item @code{StaffContext}@indexcode{StaffContext} - Default Staff context. +@example +foo = \foo * 2.0 +@end example - @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext} - Default RhythmicStaff context. +When an identifier is referenced, the information it points to is +copied. For this reason, an identifier reference must always be the +first item in a block. +@example +\paper @{ +foo = 1.0 +\paperIdent % wrong and invalid +@} - @item @code{VoiceContext}@indexcode{VoiceContext} - Default Voice context. +\paper @{ +\paperIdent % correct +foo = 1.0 +@} +@end example - @item @code{ScoreContext}@indexcode{ScoreContext} - Default Score context. - @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers} - Score context with numbering at the Score level. - @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext} - Staff context with numbering at the Staff level. +@c_ {Lexical details} +@node Lexical details +@subsection Lexical details +@cindex Lexical details +@menu +@end menu - @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext} - Staff context that does not print if it only contains rests. - Useful for orchestral scores.@footnote{Harakiri, also called - Seppuku, is the ritual suicide of the Samourai.} +@c_ {Comments} +@subsubsection Comments +@cindex Comments - @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext} +@cindex @code{%} - @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext} -@end table -Using these pre-defined values, you can remove or add items to the -translator: +A one line comment is introduced by a @code{%} character. +Block comments are started by @code{%@{} and ended by `@code{%@}}'. +They cannot be nested. -@quotation +@c_ {Direct Scheme} +@subsubsection Direct Scheme +@cindex Scheme +@cindex GUILE +@cindex Scheme, in-line code -@example -\paper @{ - \translator @{ - \StaffContext - \remove Some_engraver; - \consists Different_engraver; - @} -@} -@end example -@end quotation +LilyPond contains a Scheme interpreter (the GUILE library) for +internal use. In some places Scheme expressions also form valid syntax: +whereever it is allowed, +@example + #@var{scheme} +@end example +evaluates the specified Scheme code. If this is used at toplevel, then +the result is discarded. Example: +@example + \property Staff.TestObject \override #'foobar = #(+ 1 2) +@end example - +@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). -@node engravers, , , Reference Manual +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. -The engravers for paper output are: -[incomplete, FIXME] +@c_ {Keywords} +@subsubsection Keywords +@cindex Keywords -@table @samp - @item @code{Bar_engraver}@indexcode{Bar_engraver} - Engraves bar lines. Normally in @code{Staff} and - @code{RhythmicStaff}. - @item @code{Bar_number_engraver}@indexcode{Bar_number_engraver} - Engrave bar numbers. These numbers appear at the start of each - line. Not normally in any translator. Can be added to - @code{Score} for score-wide numbering or to @code{Staff} for - numbering on each staff. +Keywords start with a backslash, followed by a number of lower case +alphabetic characters. These are all the keywords. - @item @code{Beam_engraver}@indexcode{Beam_engraver} - Handles beam requests by engraving beams. Normally appears in - the @code{Voice} translator. If omitted, then notes will be - printed with flags instead of beams. +@example +apply arpeggio autochange spanrequest commandspanrequest +simultaneous sequential accepts alternative bar breathe +char chordmodifiers chords clef cm consists consistsend +context denies duration dynamicscript elementdescriptions +font grace header in lyrics key mark pitch +time times midi mm name pitchnames notes outputproperty +override set revert partial paper penalty property pt +relative remove repeat addlyrics partcombine score +script stylesheet skip textscript tempo translator +transpose type +@end example - @item @code{Beam_req_swallow_translator} - @indexcode{Beam_req_swallow_translator} - Swallows beam requests. In @code{LyricVoice}. +@c_ {Integers} +@subsubsection Integers - @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver} - Engraves chord names. Normally in @code{ChordNameVoice} . +@cindex integers +@cindex @code{+} +@cindex @code{-} +@cindex @code{*} +@cindex @code{/} - @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver} +Formed from an optional minus sign followed by digits. Arithmetic +operations cannot be done with integers, and integers cannot be mixed +with reals. - @item @code{Clef_engraver}@indexcode{Clef_engraver} - Engraves the clef symbol. Normally in @code{Staff}. +@c_ {Reals} +@subsubsection Reals +@cindex real numbers - @item @code{Collision_engraver}@indexcode{Collision_engraver} - @item @code{Dot_column_engraver}@indexcode{Dot_column_engraver} - Engraves dots on dotted notes shifted to the right of the note. - Normally in @code{Voice}. If omitted, then dots appear on top of - the notes. - @item @code{Dynamic_engraver}@indexcode{Dynamic_engraver} - Engraves dynamics symbols. Normally in @code{Voice}. - @item @code{Font_size_engraver}@indexcode{Font_size_engraver} - @item @code{Key_engraver}@indexcode{Key_engraver} - Engraves the key signature. Normally in @code{Staff}. +Formed from an optional minus sign and a sequence of digits followed +by a @emph{required} decimal point and an optional exponent such as +@code{-1.2e3}. Reals can be built up using the usual operations: +`@code{+}', `@code{-}', `@code{*}', and +`@code{/}', with parentheses for grouping. - @item @code{Local_key_engraver}@indexcode{Local_key_engraver} +@cindex @code{\mm}, +@cindex @code{\in} +@cindex @code{\cm} +@cindex @code{\pt} +@cindex dimensions - @item @code{Lyric_engraver}@indexcode{Lyric_engraver} - Engraves lyrics. Normally in @code{LyricVoice}. +A real constant can be followed by one of the dimension keywords: +@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters, +points, inches and centimeters, respectively. This converts the number +to a real that is the internal representation of dimensions. - @item @code{Multi_measure_rest_engraver} - @indexcode{Multi_measure_rest_engraver} - Engraves multi-measure rests that are produced with @code{R}. - Normally in @code{Voice}. - @item @code{Piano_bar_engraver}@indexcode{Piano_bar_engraver} +@c_ {Strings} +@subsubsection Strings +@cindex string +@cindex concatenate - @item @code{Pitch_squash_engraver}@indexcode{Pitch_squash_engraver} - Treat all pitches as middle C. Used in @code{RhythmicStaff}. - Note that the notes move, but the locations of accidentals stay - the same. +Begins and ends with the @code{"} character. To include a @code{"} +character in a string write @code{\"}. Various other backslash +sequences have special interpretations as in the C language. A string +that contains no spaces can be written without the quotes. See +@ref{Lexical modes} for details on unquoted strings; their interpretation varies +depending on the situation. Strings can be concatenated with the +@code{+} operator. - @item @code{Priority_horizontal_align_engraver} - @indexcode{Priority_horizontal_align_engraver} +The tokenizer accepts the following commands. They have no grammatical +function, hence they can appear anywhere in the input. - @item @code{Repeat_engraver}@indexcode{Repeat_engraver} - Handles repeats? In @code{Staff} and @code{RhythmicStaff}. - @item @code{Rest_collision_engraver}@indexcode{Rest_collision_engraver} - Handles collisions of rests. In @code{Staff}. +@c_ {Main input} +@subsubsection Main input +@cindex Main input - @item @code{Rest_engraver}@indexcode{Rest_engraver} - Engraves rests. Normally in @code{Voice}. +@cindex @code{\maininput} - @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver} +The @code{\maininput} command is used in init files to signal that the +user file must be read. This command cannot be used in a user file. - @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver} +@c_ {File inclusion} +@subsubsection Main input +@cindex Main input - @item @code{Script_engraver}@indexcode{Script_engraver} - Handles note ornaments generated by @code{\script}. Normally in - @code{Voice}. +@subsubsection File inclusion +@cindex @code{\include} +@example + \include @var{filename} +@end example - @item @code{Separating_line_group_engraver} - @indexcode{Separating_line_group_engraver} +Include @var{filename}. The argument @var{filename} may be a quoted string (an +unquoted string will not work here!) or a string identifier. The full +filename including the @file{.ly} extension must be given, - @item @code{Skip_req_swallow_translator} - @indexcode{Skip_req_swallow_translator} +@subsubsection Version information +@cindex @code{\version} +@example + \version @var{string} ; +@end example - @item @code{Slur_engraver}@indexcode{Slur_engraver} - Engraves slurs. Normally in @code{Voice}. +Specify the version of LilyPond that a file was written for. The +argument is a version string in quotes, for example @code{"1.2.0"}. +This is used to detect invalid input, and to aid +@code{convert-ly} a tool that automatically upgrades input files. See +See @ref{convert-ly} for more information on @code{convert-ly}. - @item @code{Span_bar_engraver}@indexcode{Span_bar_engraver} - Engraves lines across multiple staffs. Normally in - @code{Staffgroup} and @code{GrandStaff}. Removing this from - @code{StaffGroup} gives the definition of @code{ChoirStaff}. +@cindex convert-ly - @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver} - @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver} - @item @code{Staff_margin_engraver}@indexcode{Staff_margin_engraver} - Prints the name of the instrument (specified by - @code{Staff.instrument} and @code{Staff.instr}) at the left of the - staff. - @item @code{Staff_sym_engraver}@indexcode{Staff_sym_engraver} +@c_ {Pitch names} +@subsubsection Pitch names +@cindex Lexical modes +@cindex pitch names - @item @code{Stem_engraver}@indexcode{Stem_engraver} - Engraves stems. Normally in @code{Voice}. +@cindex note names +@cindex chord modifier names - @item @code{Ties_engraver}@indexcode{Ties_engraver} - Engraves ties. Normally in @code{Voice}. +Note names and chord modifiers can be customised for nationalities. +languages and conventions. The syntax is as follows. +@cindex @code{\pitchnames} +@cindex @code{\chordmodifiers} - @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver} - Engraves the time signature. Normally in @code{Staff} and - @code{RhythmicStaff}. +@example + \pitchnames @var{scheme-alist} + \chordmodifiers @var{scheme-alist} +@end example - @item @code{Timing_engraver}@indexcode{Timing_engraver} - Responsible for synchronizing timing information from staffs. - Normally in @code{Score}. In order to create polyrhythmic music, - this engraver should be removed from @code{Score} and placed in - @code{Staff}. +See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for +specific examples how to do this. tables can be tailored specified +using. Some national note names have been provided, see +section @ref{Other languages}. +A @code{\paper} block at top level sets the default paper block. A +@code{\midi} block at top level works similarly. - @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver} - Engraves tuplet brackets? In @code{Staff}. +@c_ {Assignments} +@subsubsection Assignments +@cindex assignments +@cindex @code{#} - @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver} -@end table +Identifier assignments may appear at top level. @ref{Assignments} -@node Sound output, , , Reference Manual -@section Sound output +@c_ {Direct scheme} +@subsubsection Direct scheme +@cindex Direct scheme +Scheme statements maybe issued to produce interesting side-effects. -The MIDI block is analogous to the paper block, but it is simpler. -The @code{\midi} block can contain: -@cindex MIDI block +@c_ {Lexical modes} +@node Lexical modes +@subsection Lexical modes +@cindex Lexical modes -@itemize @bullet - @item a @code{\tempo} definition - @item context definitions -@end itemize +@cindex Lexical modes +@cindex modes -Assignments in the @code{\midi} block are not allowed. +To simplify entering notes, lyrics, and chords, LilyPond has three +special input modes on top of the default mode. In each mode, words +are identified on the input. If @code{"word"} is encountered, it is +treated as a string. If @code{\word} is encountered, it is treated as +a keyword or as an identifier. The behavior of the modes differs in +two ways: Different modes treat unquoted words differently, and +different modes have different rules for deciding what is a word. +@table @asis +@item Normal mode. +@cindex normal mode + +At the start of parsing, LilyPond is in Normal mode. In Normal +mode, a word is an alphabetic character followed by alphanumeric +characters. If @code{word} is encountered on the input it is +treated as a string. +@item Note mode +See @ref{Note entry}. -@cindex context definition +@item Lyrics mode +See @ref{Lyrics entry}. -Context definitions follow precisely the same syntax as within the -\paper block. Translation modules for sound are called performers. -The contexts for MIDI output are defined in @file{ly/performer.ly}. +@item Chord mode +See @ref{Chord entry}. +@end table +@cindex input modes +@cindex mode switch -@cindex MIDI instrument names +@cindex @code{\notes} +@cindex @code{\chords} +@cindex @code{\lyrics} -@node midilist, , , Reference Manual +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. + +@c_ {Ambiguities} +@node Ambiguities +@subsection Ambiguities +@cindex ambiguities +@cindex grammar -The MIDI instrument name is set by the -@code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or, -if that property is not set, the -@code{Staff.instrument}@indexcode{Staff.instrument} property. The -instrument name should be chosen from the following list. If the -selected string does not exactly match, then LilyPond uses the default -piano. +The grammar contains a number of ambiguities. We hope to resolve them at +some time. -@quotation +@itemize @bullet + @item The assignment -@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)" + @example +foo = bar @end example -@end quotation - - -@cindex MIDI types and performers + can be interpreted as making a string identifier @code{\foo} + containing @code{"bar"}, or a music identifier @code{\foo} + containing the syllable `bar'. -The types available for MIDI translators are: + @item The assignment -@table @samp - @item @code{Performer_group_performer}@indexcode{Performer_group_performer} - @item @code{Score_performer}@indexcode{Score_performer} - @item @code{Staff_performer}@indexcode{Staff_performer} -@end table + @example +foo = -6 +@end example -The performers for MIDI translators are: + can be interpreted as making an integer identifier + containing -6, or a Request identifier containing the + fingering `6' (with neutral direction). -@table @samp - @item @code{Key_performer}@indexcode{Key_performer} - @item @code{Time_signature_performer}@indexcode{Time_signature_performer} - @item @code{Note_performer}@indexcode{Note_performer} - @item @code{Lyric_performer}@indexcode{Lyric_performer} - @item @code{Swallow_performer}@indexcode{Swallow_performer} -@end table + @item If you do a nested repeat like + @quotation +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example -@node Pre-defined Identifiers, , , Reference Manual + @end quotation -@section Pre-defined Identifiers + then it is ambiguous to which @code{\repeat} the + @code{\alternative} belongs. This is the classic if-then-else + dilemma. It may be solved by using braces. -@cindex pre-defined identifiers + @item (an as yet unidentified ambiguity :-) +@end itemize -Various identifiers are defined in the initialization files to -provide shorthands for some settings. Most of them are in -@file{ly/declarations.ly}. -@table @samp - @item @code{\break}@keyindex{break} - Force a line break in music by using a large argument for the - keyword @code{\penalty}. - @item @code{\center}@keyindex{center} - Used for setting direction properties. Equals 0. - @item @code{\down}@keyindex{down} - Used for setting direction setting properties. Is equal - to -1. +@c_ {Unsorted} +@node Unsorted +@section Unsorted - @item @code{\free}@keyindex{free} - Used for setting direction setting properties. Is equal - to 0. +[mucho todo] - @item @code{\left}@keyindex{left} - Used for setting text alignment property. Is equal to -1. +Translation? - @item @code{\nobreak}@keyindex{nobreak} - Prevent a line break in music by using a large negative argument - for the keyword @code{\penalty}. +@cindex properties +@unnumberedsubsec Translation property - @item @code{\none}@keyindex{none} - Used for setting @code{Score.beamslopedamping} and - @code{Score.beamquantisation} properties. Is equal to 0. +@cindex @code{\property} +@example + \property @var{contextname}.@var{propname} = @var{value} +@end example - @item @code{\normal}@keyindex{normal} - Used for setting @code{Score.beamslopedamping} and - @code{Score.beamquantisation} properties. Is equal to 1. +Sets the @var{propname} property of the context @var{contextname} to +the specified @var{value}. All three arguments are strings. +Depending on the context, it may be necessary to quote the strings or +to leave space on both sides of the dot. - @item @code{\normalkey}@keyindex{normalkey} - Select normal key signatures where each octave has the same key - signature. This sets the @code{Staff.keyoctaviation} property. +@cindex translator switches +@unnumberedsubsec Translator switches - @item @code{\right}@keyindex{right} - Used for setting text alignment property. Is set to 1. +@cindex @code{\translator} +@example + \translator @var{contexttype} = @var{name} +@end example - @item @code{\shiftoff}@keyindex{shiftoff} - Disable horizontal shifting of note heads that collide. Sets the - @code{Voice.horizontalNoteShift} property. +A music expression indicating that the context which is a direct +child of the a context of type @var{contexttype} should be shifted to +a context of type @var{contexttype} and the specified name. - @item @code{\shifton}@keyindex{shifton} - Enable note heads that collide with other note heads to be - shifted horiztonally. Sets the @code{Voice.horizontalNoteShift} - property. +Usually this is used to switch staffs in Piano music, e.g. - @item @code{\slurboth}@keyindex{slurboth} - Allow slurs to be above or below notes. This sets the - @code{Voice.slurVerticalDirection} property. +@example + \translator Staff = top @var{Music} +@end example - @item @code{\slurdown}@keyindex{slurdown} - Force slurs to be below notes. This sets the - @code{Voice.slurVerticalDirection} property. - @item @code{\slurup}@keyindex{slurup} - Force slurs to be above notes. This sets the - @code{Voice.slurVerticalDirection} property. +@cindex output properties +@unnumberedsubsec Output properties - @item @code{\specialkey}@keyindex{specialkey} - Allow key signatures do differ in different octaves. This sets - the @code{Staff.keyoctaviation} property. +These allow you to tweak what is happening in the back-end +directly. If you want to control every detail of the output +formatting, this is the feature to use. The downside to this is that +you need to know exactly how the backend works. Example: - @item @code{\stemboth}@keyindex{stemboth} - Allow stems, beams, and slurs to point either upwards or - downwards, decided automatically by LilyPond. This sets the - @code{Voice.verticalDirection} property. - @item @code{\stemdown}@keyindex{stemdown} - Force stems, beams, and slurs to point down. This sets the - @code{Voice.verticalDirection} property. +@lilypond[fragment,verbatim] +\relative c'' { c4 + \context Staff \outputproperty + #(make-type-checker 'note-head-interface) + #'extra-offset = #'(5.0 . 7.5) + } +@end lilypond - @item @code{\stemup}@keyindex{stemup} - Force stems, beams and slurs to point up. This sets the - @code{Voice.verticalDirection} property. +This selects all note heads occurring at current staff level, and sets +the @code{extra-offset} of those heads to @code{(5,7.5)}, shifting them +up and right. - @item @code{\traditional}@keyindex{traditional} - Used for setting the @code{Score.beamquantisation} property. Is - equal to 2. +Use of this feature is entirely on your own risk: if you use this, the +result will depend very heavily on the implementation of the backend, +which we change regularly and unscrupulously. + + +@c_{Local emacs vars} +@c Local variables: +@c mode: texinfo +@c minor-mode: font-lock +@c minor-mode: outline +@c xoutline-layout: (0 : -1 -1 0) +@c outline-layout: (-1 : 0) +@c outline-primary-bullet: "{" +@c outline-stylish-prefixes: nil +@c outline-override-protect: t +@c End: - @item @code{\up}@keyindex{up} - Used for setting various direction properties. Is equal - to 1. -@end table