X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=fd009a91b0b3aaca77dcb11606da42282a92af69;hb=194c87ed054aaec8ba2acd4c377b52853d291d85;hp=77f40dfcd7a5c318ffd1c2db4dbb0e30c0649ece;hpb=6ccdc33b67af16bed0b445d54c880941bb6c4596;p=lilypond.git diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 77f40dfcd7..fd009a91b0 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,1096 +1,1084 @@ -@c -*-texinfo-*- -@c TODO: -@c - Reinsert subsection commands that were lost in the -@c ancient conversion from YODL! /MB -@c - Restructure! Separate internal commands from user level commands. /MB -@c - Add some words about Guile. /MB -@c - Fix indexing (keyindex) so it doesn't add line breaks /MB - -@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 + + +@macro refbugs +@unnumberedsubsec Bugs + +@end macro + + +@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 -* stem 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 -* Sound output:: Sound output -* midilist:: midilist -* Pre-defined Identifiers:: Pre-defined Identifiers -@c May be fragile. Better make single link to generated doco? -* Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts. -* Engravers:(lilypond-internals)LilyPond engravers. -* Backend:(lilypond-internals)LilyPond backend. -@end menu +This document describes GNU LilyPond and its input format. The last +revision of this document was for LilyPond 1.3.138. +@menu +* Overview:: +* Note entry:: +* Staff notation:: +* Polyphony:: +* Beaming:: +* Expressive marks:: +* Ornaments:: +* Repeats:: +* Rhythmic music:: +* Piano music:: +* Lyrics:: +* Chords:: +* Writing parts:: +* Custodes:: +* Tuning output:: +* Page layout:: +* Sound:: +* Music entry:: +* Interpretation context:: +* Syntactic details:: +* Lexical details:: +@end menu -@node Overview, , , Reference Manual +@c . {Overview} +@node Overview @section Overview -This document@footnote{This document has been revised for -LilyPond 1.2.} describes the the GNU LilyPond input format, which is -a language for defining music. We call this language @emph{Music -Definition Language} or @emph{Mudela}, for short.@footnote{If anybody -comes up with a better name, we'd gladly take this. Gourlay already -uses a ``Musical Description Language,'' ISO standard 10743 defines a -``Standard Music Description Language.'' We're not being original -here.} -@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. +Symbols and their placements are @emph{generated} from a high-level +musical description. In other words, LilyPond would be best described +by `music compiler' or `music to notation compiler'. + +LilyPond is linked to GUILE, GNU's Scheme library for extension. The +Scheme library provides the glue that holds together the low-level +routines and separate modules general, which are C++ +When lilypond is run to typeset sheet music, the following happens: @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 GUILE Initialization: various scheme files are read +@item parsing: first standard @code{ly} initialization files are read, and +then the user @file{ly} file is read. +@item interpretation: the music in the file is processed ``in playing +order'', i.e. the order that you use to read sheet music, or the +order in which notes are played. + +@item typesetting: +in this step, the results of the interpretation, a typesetting +specification, is solved. + +@item the visible results ("virtual ink") is written to the output file. @end itemize -@emph{Mudela} aims to define a piece of music completely, both from -typesetting and from a performance point of view. +During these stages different types of data play the the main role: +during parsing, @strong{Music} objects are created. During the +interpretation, @strong{context} is constructed, and with this context +af network of @strong{graphical objects} (``grobs'') is created. The +grobs contain unknown variables, and the network forms a set of +equations. After solving the equations and filling in these variables, +the printed output (in the form of @strong{molecules}) is written to an +output file. +These threemanship of tasks (parsing, translating, typesetting) and +data-structures (music, context, graphical objects) permeates the entire +design of the program. This manual is ordered in terms of user +tasks. With each concept will be explained to which of the three parts +it belongs. -@node Top level, , , Reference Manual -@section Top level +@c . {Note entry} +@node Note entry +@section Note entry +@cindex Note entry -@cindex top level +The most basic forms of music are notes. We discuss how you enter them +here. Notes on their own don't form valid input, but for the sake of +brevity we omit obligotary lint such as @code{\score} blocks and +@code{\paper} declarations. -This section describes what you may enter at top level. +@menu +* Pitches:: +* Defining pitch names:: +* Durations:: +* Notes:: +* Easy Notation note heads :: +* Tie:: +* Tuplets:: +* Rests:: +* Skip:: +* Note mode:: +@end menu +@c . {Pitches} +@node Pitches +@subsection Pitches -@cindex score definition +@cindex Pitch names +@cindex Note specification +@cindex pitches +@cindex entering notes -The output is generated combining a music expression with an output -definition. A score block has the following syntax: +The verbose syntax for pitch specification is +@cindex @code{\pitch} @example - \score @{ @var{musicexpr} @var{outputdefs} @} + \pitch @var{scmpitch} @end example -@var{outputdefs} are zero or more output definitions. If no output -definition is supplied, the default @code{\paper} block will be added. +@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}. +In Note and Chord mode, pitches may be designated by names. The default +names are the Dutch note names. The notes are specified by the letters +@code{a} through @code{g} (where the octave is formed by notes ranging +from @code{c}, to @code{b}). The pitch @code{c} is an octave below +middle C and the letters span the octave above that C. +@cindex note names, Dutch -@cindex header +In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch +name. A flat is formed by adding @code{-es}. Double sharps and double +flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes} +and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but +both forms are accepted. -@keyindex{header} +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: -The syntax is +@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 -@example - \header @{ @var{key1} = @var{val1}; - @var{key2} = @var{val2}; @dots{} @} -@end example +@cindex @code{'} +@cindex @code{,} -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. +The optional octave specification takes the form of a series of +single quote (`@code{'}') characters or a series of comma +(`@code{,}') characters. Each @code{'} raises the pitch by one +octave; each @code{,} lowers the pitch by an octave. -@node notenames, , , Reference Manual +@lilypond[fragment,verbatim,center] + c' c'' es' g' as' gisis' ais' +@end lilypond -Note name tables can be specified using +@c . {Defining pitch names} +@node Defining pitch names +@subsection Defining pitch names -@example - \notenames@keyindex{notenames} - @{ @var{assignmentlist} @} -@end example +@cindex defining pitch names +@cindex pitch names, defining -@var{assignmentlist} is a list of definitions of the form +Note names and chord modifiers can be customised for nationalities. The +syntax is as follows. +@cindex @code{\pitchnames} +@cindex @code{\chordmodifiers} @example - @var{name} = @var{pitch} + \pitchnames @var{scheme-alist} + \chordmodifiers @var{scheme-alist} @end example -Chord modifiers can be set analogously, with -@code{\chordmodifiers}@keyindex{chordmodifiers}. +See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for +specific examples how to do this. -A @code{\paper} block at top level sets the default paper block. A -@code{\midi} block at top level works similarly. +@c . {Durations} +@node Durations +@subsection Durations -LilyPond contains a Scheme interpreter (the GUILE library) for -internal use. The following commands access the interpreter -directly. +@cindex duration +@cindex @code{\duration} + +The syntax for a verbose duration specification is @example - #@var{scheme} + \duration @var{scmduration} @end example +Here, @var{scmduration} is a Scheme object of type Duration. See +@ref{Duration} for more information. + -Evaluates the specified Scheme code. The result is discarded. +In Note, Chord, and Lyrics mode, durations may be designated by numbers +and dots: durations are entered as their reciprocal values. For notes +longer than a whole note, use identifiers. -Identifier assignments may appear at top level. Semicolons are -forbidden after top level assignments. +@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 +@lilypond[] +\score { + \notes \relative c'' { + a\longa a\breve \autoBeamOff + a1 a2 a4 a8 a16 a32 a64 a64 + r\longa r\breve + r1 r2 r4 r8 r16 r32 r64 r64 + } + \paper { + \translator { + \StaffContext + \remove "Clef_engraver"; + \remove "Staff_symbol_engraver"; + \remove "Time_signature_engraver"; + \consists "Pitch_squash_engraver"; + } + } +} +@end lilypond +@end quotation + +As you can see, the longa is not printed. To get a longa note head, you +have to use a mensural note heads. This is done accomplished by setting +the @code{style} property of the NoteHead grob to @code{mensural}. -@node Lexical conventions, , , Reference Manual -@section Lexical conventions +If the duration is omitted then it is set to the previous duration +entered. At the start of parsing a quarter note is assumed. The +duration can be followed by a dot (`@code{.}') to obtain dotted note +lengths. +@cindex @code{.} -@cindex lexical conventions +@lilypond[fragment,verbatim,center] + a'4. b'4.. c'8. +@end lilypond +@cindex @code{r} +@cindex @code{s} +You can alter the length of duration by appending +`@code{*}@var{fraction}'. This will not affect the appearance of the +notes or rests produced. +@c . {Notes} +@node Notes +@subsection Notes -@cindex comment +A note specification has the form -@indexcode{%} +@example + @var{pitch}[@var{octavespec}][!][?][@var{duration}] +@end example +LilyPond will determine what accidentals to typeset depending on the key +and context. The alteration refers to what note is heard, not to whether +an accidental is printed. A reminder accidental +@cindex reminder accidental +@cindex @code{?} +can be forced by adding an exclamation mark @code{!} after the pitch. A +cautionary accidental, +@cindex cautionary accidental +i.e., an accidental within parentheses can be obtained by adding the +question mark `@code{?}' after the pitch. -A one line comment is introduced by a `@code{%}' character. -Block comments are started by `@code{%@{}' and ended by `@code{%@}}'. -They cannot be nested. +@lilypond[fragment,verbatim,center] + cis' d' e' cis' c'? d' e' c'! +@end lilypond +@node Easy Notation note heads +@subsection Easy Notation note heads -@cindex keyword +@cindex easy notation +@cindex Hal Leonard -Keywords start with a backslash, followed by a number of lower case -alphabetic characters. These are all the keywords. +A entirely different type of note head is the "easyplay" note head: a +note head that includes a note name. It is used in some publications by +Hal-Leonard Inc. music publishers. -[FIXME] +@lilypond[singleline,verbatim] +\include "paper26.ly" +\score { + \notes { c'2 e'4 f' | g'1 } + \paper { \translator { \EasyNotation } } +} +@end lilypond -@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 -@end example - - - - -@cindex integer +Note that @code{EasyNotation} overrides a @code{Score} context. You +probably will want to print it with magnification to make it better +readable. -Formed from an optional minus sign followed by digits. Arithmetic -operations cannot be done with integers, and integers cannot be mixed -with reals. +@cindex Xdvi +@cindex ghostscript +If you view the result with Xdvi, then staff lines will show through the +letters. Printing the postscript file obtained either by using dvips or +the @code{-f ps} option of lilypond will produce the desired result. -@cindex real - +@node Tie +@subsection Tie -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. +@cindex Tie +@cindex ties +@cindex @code{~} -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. +A tie connects two adjacent note heads of the same pitch. When used +with chords, it connects all of the note heads whose pitches match. +Ties are indicated using the tilde symbol `@code{~}'. +If you try to tie together chords which have no common pitches, a +warning message will appear and no ties will be created. +@lilypond[fragment,verbatim,center] + e' ~ e' ~ +@end lilypond +If you dislike the amount of ties created for a chord, you set +@code{Voice.sparseTies} to true, resulting in a smaller number of +ties: +@lilypond[fragment,verbatim,center] + \property Voice.sparseTies = ##t + ~ +@end lilypond -@cindex string - +In its meaning a tie is just a way of extending a note duration, similar +to the augmentation dot: the following example are three ways of notating +exactly the same concept. +@lilypond[fragment, singleline] +c'2 c'4 ~ c'4 +@end lilypond -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. +@refbugs +At present, the tie is implemented as a separate thing, temporally +located in between the notes. There is also no way to convert +between tied notes, dotted notes and plain notes. -The tokenizer accepts the following commands. They can appear -anywhere. +Tieing only a subset of the note heads of a chord is not supported in a +simple way. It can be achieved by moving the tie-engraver into Thread +context and turning off ties per Thread. -@example - \maininput@keyindex{maininput} -@end example -This command is used in init files to signal that the user file must -be read. This command cannot be used in a user file. +@node Tuplets +@subsection Tuplets -@example - \include@keyindex{include} @var{file} -@end example +@cindex tuplets +@cindex triplets +@cindex @code{\times} -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, +Tuplets are made out of a music expression by multiplying their duration +with a fraction. +@cindex @code{\times} @example - \version@keyindex{version} @var{string} ; + \times @var{fraction} @var{musicexpr} @end example -Specify the version of LilyPond that a file was written for. The -argument is a version string in quotes, for example @code{"1.2.0"}. -This is used to detect invalid input, and to aid -@code{convert-mudela}, a tool that automatically upgrades input files. +The duration of @var{musicexpr} will be multiplied by the fraction. +In print, the fraction's denominator will be printed over the notes, +optionally with a bracket. The most common tuplet is the triplet in +which 3 notes have the length of 2, so the notes are 2/3 of +their written length: +@lilypond[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond +The property @code{tupletSpannerDuration} specifies how long brackets +should last. With this, you can make lots of tuplets while typing +@code{\times} only once. This saves typing work when you must make lots +of tuplets. -@cindex other languages +@lilypond[fragment, relative, singleline, verbatim] +\property Voice.tupletSpannerDuration = #(make-moment 1 4) +\times 2/3 { c''8 c c c c c } +@end lilypond -@node Other languages, , , Reference Manual +@c . {Rests} +@node Rests +@subsection Rests +@cindex Rests -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: +Rests are entered like notes, with note name `@code{r}'. -@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 -Pitch names can be redefined using the -@code{\notenames}@keyindex{notenames} command, see -subsection XREF-notenames [FIXME]. +@c . {Skip} +@node Skip +@subsection Skip +@cindex Skip +@example + \skip @var{duration} @code{;} + s@var{duration} +@end example +@cindex @code{\skip} -@cindex lexical modes +Skips the amount of time specified by @var{duration}. If no other music +is played, a gap will be left for the skipped time with no notes +printed. The short hand is only available in Note and Chord mode. -@cindex modes -@node modes, , , Reference Manual -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. +@node Note mode +@subsection Note mode -@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{_}' character which appears in an unquoted word is - converted to a space. This provides a mechanism for introducing - spaces into words without using quotes. Quoted words can also be - used in Lyrics mode to specify words that cannot be written with - the above rules. Here are some examples. Not all of these words - are printable by @TeX{}. -@example -Ah! % a word -2B_||_!2B % not a word because it starts with a digit -``Hello'' % not a word because it starts with ` -_ _ _ _ % 4 words, each one a space -@end example - Since combinations of numbers and dots are used for indicating - durations, you can not enter real numbers in this mode. -@end table +@cindex note mode +@cindex @code{\notes} -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.} +Note mode is the lexical mode generally used for inputting notes. The +syntax is +@example +\notes @var{expr} +@end example +This instructs the tokenizer to interpret @var{expr} in note mode. If a +a sequence of alfabetical characters, like @code{foobar}, LilyPond first +checks if @code{foobar} is a pitch name. If it is not a pitch name, +then it is treated as a string. +Numbers and dots indicate durations, so you can enter floating point +numbers in this mode. -@node Types, , , Reference Manual -@section Types -@cindex types and identifiers +@node Staff notation +@section Staff notation -@emph{Mudela} has a limited set of types: +@cindex Staff notation -@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 +@menu +* Key signature:: +* Clef:: +* Time signature:: +* Unmetered music:: +* Bar lines:: +@end menu -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. +@c . {Key} +@node Key signature +@subsection Key signature +@cindex Key -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. +@cindex @code{\key} +Changing the key signature is done with the @code{\key} command. @example - foo = \foo * 2.0 + @code{\key} @var{pitch} @var{type} @code{;} @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.} +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} + +Here, @var{type} should be @code{\major} or @code{\minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. The second +argument is optional; the default is major keys. The @var{\context} +argument can also be given as an integer, which tells the number of +semitones that should be added to the pitch given in the subsequent +@code{\key} commands to get the corresponding major key, e.g., +@code{\minor} is defined as 3. The standard mode names @code{\ionian}, +@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, +@code{\phrygian}, and @code{\dorian} are also defined. +This command sets context property @code{Staff.keySignature}. +@cindex @code{keySignature} -@node Music expressions, , , Reference Manual -@section Music expressions +@c . {Clef} +@node Clef +@subsection Clef +@cindex @code{\clef} +@example + \clef @var{clefname} @code{;} +@end example -@cindex music expressions +Shortcut for -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: +@example + \property Staff.clefGlyph = @var{glyph associated with clefname} + \property Staff.clefPosition = @var{clef Y-position for clefname} + \property Staff.clefOctavation = @var{extra pitch of clefname} +@end example -@example -\sequential @{ c4 d4 @} -@end example +Supported clef-names include -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). +@itemize @bullet +@item treble, violin, G, G2: G clef on 2nd line +@item french: G clef on 1st line +@item soprano: C clef on 1st line +@item mezzosoprano: C clef on 2nd line +@item alto: C clef on 3rd line +@item tenor: C clef on 4th line +@item baritone: C clef on 5th line +@item varbaritone: F clef on 3rd line +@item bass, F: F clef on 4th line +@item subbass: F clef on 5th line +@item percussion: percussion clef +@end itemize -Atomic music expression are discussed in -subsection XREF-atomicmusic [FIXME]. Compound music expressions are -discussed in subsection XREF-compoundmusic [FIXME]. +Supported associated glyphs (for @code{Staff.clefGlyph}) are: +@itemize @bullet +@item clefs-C: modern style C clef +@item clefs-F: modern style F clef +@item clefs-G: modern style G clef +@item clefs-vaticana_do: Editio Vaticana style do clef +@item clefs-vaticana_fa: Editio Vaticana style fa clef +@item clefs-medicaea_do: Editio Medicaea style do clef +@item clefs-medicaea_fa: Editio Medicaea style fa clef +@item clefs-mensural1_c: modern style mensural C clef +@item clefs-mensural2_c: historic style small mensural C clef +@item clefs-mensural3_c: historic style big mensural C clef +@item clefs-mensural1_f: historic style traditional mensural F clef +@item clefs-mensural2_f: historic style new mensural F clef +@item clefs-mensural_g: historic style mensural G clef +@item clefs-hufnagel_do: historic style hufnagel do clef +@item clefs-hufnagel_fa: historic style hufnagel fa clef +@item clefs-hufnagel_do_fa: historic style hufnagel combined do/fa clef +@item clefs-percussion: modern style percussion clef +@end itemize +@emph{Modern style} means ``as is typeset in current editions.'' +@emph{Historic style} means ``as was typeset or written in contemporary +historic editions''. @emph{Editio XXX style} means ``as is/was printed in +Editio XXX.'' -@node Atomic music expressions, , , Reference Manual -@section Atomic music expressions +@cindex Vaticana, Editio +@cindex Medicaea, Editio +@cindex hufnagel clefs +@c . {Time signature} +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} +The time signature is changed by the @code{\time} command. Syntax: +@example + \time @var{numerator}@code{/}@var{denominator} @code{;} +@end example +Internally, this is a shortcut for doing +@example + \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator}) +@end example -@cindex pitch +[TODO: discuss options for layout] -@cindex duration - +@c . {Partial} +@subsection Partial +@cindex Partial +@cindex anacrusis +@cindex upstep +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} -The syntax for pitch specification is +Partial measures are entered using the @code{\partial} command: +@example + \partial @var{duration} @code{;} +@end example +Internally, this is a shortcut for @example - \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @} + \property Score.measurePosition = -@var{length of duration} @end example +@cindex @code{|} + + +@node Unmetered music +@subsection Unmetered music + +Bar lines and bar numbers are calculated automatically. For unmetered +music (e.g. cadenzas), this is not desirable. The property +@code{Score.timing} can be used to switch off this automatic timing + +@lilypond[fragment,relative,singleline,verbatim] +c'2. +\property Score.timing = ##f +c4 c4 c4 +\property Score.timing = ##t +c4 c4 c4 +@end lilypond + +The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used to +achieve the same effect. -@var{octave} is specified by an integer, zero for the octave -containing middle C. @var{note} is a number from 0 to 7, with 0 -corresponding to C and 7 corresponding to B. The shift is zero for a -natural, negative to add flats, or positive to add sharps. -In Note and Chord mode, pitches may be designated by names. See -section XREF-notelang [FIXME] for pitch names in different languages. -The syntax for duration specification is +@c . {Bar lines} +@node Bar lines +@subsection Bar lines +@cindex Bar lines + +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars @example - \duration@keyindex{duration} - @{ @var{length} @var{dotcount} @} + \bar @var{bartype}; @end example -@var{length} is the negative logarithm (base 2) of the duration: -1 is a half note, 2 is a quarter note, 3 is an eighth -note, etc. The number of dots after the note is given by -@var{dotcount}. - -In Note, Chord, and Lyrics mode, durations may be designated by -numbers and dots. See Section XREF-notelang [FIXME] for details. +This is a shortcut for doing +@example + \property Score.whichBar = @var{bartype} +@end example +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeats}, and the documentation of @code{whichBar} in the generated +documentation. -@node Note specification, , , Reference Manual -@cindex note specification +@cindex Bar_line_engraver +@cindex whichBar +@cindex repeatCommands +@cindex defaultBarType -@cindex pitches +Bar lines are created by the @code{Bar_line_engraver}. That engraver examines +@code{whichBar} at every moment. Whenever it is set to a string, it will +create a bar with that type. @code{whichBar} is usually set +automatically: at the start of a measure it is set to +@code{defaultBarType}. The contents of @code{repeatCommands} is used to +override default measure bars. -@cindex entering notes +@code{whichBar} can also be set directly, using @code{\property} or +@code{\bar ; }. These settings take precedence over automatic @code{whichBar} +settings. -A note specification has the form -@example - @var{pitch}[@var{octavespec}][!][?][@var{duration}] -@end example +@c . {Polyphony} +@node Polyphony +@section Polyphony +@cindex Polyphony -The pitch of the note is specified by the note's name. +[TODO: collisions, rest-collisinos, voiceX identifiers, how to +which contexts to instantiate. some small examples? ] -The default names are the Dutch note names. The notes are specified -by the letters `@code{c}' through `@code{b}', where `@code{c}' is an -octave below middle C and the letters span the octave above that C. -In 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. +@table @code +@cindex @code{\shiftOff} + @item @code{\shiftOff} + Disable horizontal shifting of note heads that collide. -LilyPond has predefined sets of notenames for various languages. See -section XREF-notelang [FIXME] for details. +@cindex @code{\shiftOn} + @item @code{\shiftOn} + Enable note heads that collide with other note heads to be + shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn} +set different shift values. +@cindex @code{\stemBoth} + @item @code{\stemBoth} + Allow stems and beams to point either upwards or + downwards, decided automatically by LilyPond. -The optional octave specification takes the form of a series of -single quote (`@code{'}@indexcode{'}') characters or a series of comma -(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one -octave; each @code{,} lowers the pitch by an octave. +@cindex @code{\stemDown} + @item @code{\stemDown} + Force stems and beams to point down. -@mudela[fragment,verbatim,center] - c' d' e' f' g' a' b' c'' -@end mudela +@cindex @code{\stemUp} + @item @code{\stemUp} + Force stems and beams to point up. +@end table -@mudela[fragment,verbatim,center] - cis' dis' eis' fis' gis' ais' bis' -@end mudela +@cindex @code{\slurBoth} +@cindex @code{\slurDown} +@cindex @code{\slurUp} +Similarly, for slurs use +@code{\slurBoth}, +@code{\slurDown}, +@code{\slurUp}. + +@cindex @code{\tieBoth} +@cindex @code{\tieDown} +@cindex @code{\tieUp} +For ties use +@code{\tieBoth}, +@code{\tieDown}, +@code{\tieUp}. + +@cindex @code{\dynacmicBoth} +@cindex @code{\dynamicDown} +@cindex @code{\dynamicUp} +For dynamics use +@code{\dynamicBoth}, +@code{\dynamicDown}, +@code{\dynamicUp}. + +@c text scripts? articulation scripts? fingering? + +@cindex @code{\voiceOne} +@cindex @code{\voiceTwo} +@cindex @code{\voiceThree} +@cindex @code{\voiceFour} +@cindex @code{\oneVoice} +@cindex @code{\shiftOn} +@cindex @code{\shiftOff} + +If two voices sharing one staff have the same stem directions, their +note heads may collide. You can shift the note heads of one voice by +setting @code{\shiftOn}. This can be undone by setting +@code{\shiftOff}. + +For simple polyphonic music, shorthands are available that combine +directions and shift settings: @code{\voiceOne}, @code{\voiceTwo}, +@code{\voiceThree}, @code{\voiceFour} and @code{\oneVoice}. + + +@node Beaming +@section Beaming + +Beams are used to group short notes into chunks that are aligned with +the metrum. LilyPond guesses where beams should be inserted, but if +you're not satisfied with the automatic beaming, you can either instruct +lilypond which patterns to beam automatically. In specific cases, you +can also specify explicitly what to beam and what not. + + +@c . {Automatic beams} +@subsection Automatic beams + +@cindex @code{Voice.autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} -@mudela[fragment,verbatim,center] - ces' des' es' fes' ges' as' bes' -@end mudela +A large number of Voice properties are used to decide how to generate +beams. Their default values appear in @file{scm/auto-beam.scm}. -@mudela[fragment,verbatim,center] - cisis' eisis' gisis' aisis' beses' -@end mudela +By default, automatic beams can start on any note@footnote{In exotic +time signatures such as 1/8 and 1/16 this is not true} but can only end +in a few positions within the measure: they can end on a beat, or at +durations specified by the properties in +@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings} +are defined in @file{scm/auto-beam.scm}. -@mudela[fragment,verbatim,center] - ceses' eses' geses' ases' beses' -@end mudela +The syntax for changing the value @code{autoBeamSettings} is set using +@code{\override} and unset using @code{\revert}: +@example +\property Voice.autoBeamSettings \override #'(@var{BE} @var{N} @var{M} @var{P} @var{Q}) = @var{dur} +\property Voice.autoBeamSettings \revert #'(@var{BE} @var{N} @var{M} @var{P} @var{Q}) +@end example +Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines +whether the rule applies to begin or end-points. The quantity +@var{N}/@var{M} refers to a time signature (@code{* *} may be entered to +designate all time signatures), @var{P}/@var{Q} refers to the length of +the beamed notes (@code{* *} designate notes of any length). + +If you want automatic beams to end on every quarter note, you can +use the following: +@example +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(make-moment 1 4) +@end example +The duration a quarter note is 1/4 of a whole note. It is entered as +@code{(make-moment 1 4)}. -Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond -will determine what accidentals to typeset depending on the key and -context. A reminder accidental -@cindex reminder accidental - can be -forced by adding an exclamation mark `@code{!}' after the pitch. A -cautionary accidental, -@cindex cautionary accidental - i.e., an -accidental within parentheses can be obtained by adding the question -mark `@code{?}@indexcode{?}' after the pitch. +The same syntax can be used to specify beam starting points. In this +example, you automatic beams can only end on a dotted quarter note. +@example +\property Voice.autoBeamSettings \override + #'(begin * * * *) = #(make-moment 3 8) +@end example +In 4/4 time signature, this means that automatic beams could end only on +3/8 and on the fourth beat of the measure (after 3/4, that is 2 times +3/8 has passed within the measure). + +You can also restrict rules to specific time signatures. A rule that +should only be applied in @var{N}/@var{M} time signature is formed by +replacing the first asterisks by @var{N} and @var{M}. For example, a +rule for 6/8 time exclusively looks like +@example +\property Voice.autoBeamSettings \override + #'(begin 6 8 * *) = ... +@end example -@mudela[fragment,verbatim,center] - cis' d' e' cis' c'? d' e' c'! -@end mudela +If you want a rule to apply to certain types of beams, you can use the +second pair of asterisks. Beams are classified according to the shortest +note they contain. For a beam ending rule that only applies to beams +with 32nd notes (and no shorter notes), you would use @code{(end * * 1 +32)}. +[say something about irregular meters. eg 5/8 = 2+3/8, 3+2/8] -@cindex duration +Automatic beams can not be put on the last note in a score. -Durations are entered as their reciprocal values. For notes longer -than a whole note, use identifiers. +@cindex automatic beam generation +@cindex autobeam +@cindex @code{Voice.noAutoBeaming} -@quotation +Automatic beaming is on by default, but it can switched off by setting +@code{Voice.noAutoBeaming} to true. You you may find this necessary for +a melody that goes with lyrics. -@example -c'\longa c'\breve -c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 -@end example +@c . {Manual beams} +@cindex Automatic beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} -@end quotation +In some cases it may be necessary to override LilyPond's automatic +beaming algorithm. For example, the auto beamer will not beam over +rests or bar lines, so if you want that, specify the begin and end point +manually using @code{[} and @code{]}: @quotation - -@mudela[] -\score { - \notes \relative c'' { - a\longa a\breve - a1 a2 a4 a8 a16 a32 a64 a64 +@lilypond[fragment,relative,verbatim] + \context Staff { + r4 [r8 g'' a r8] r8 [g | a] r8 } - \paper { -%{ \translator { - \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - } %} +@end lilypond +Whenever an manual beam is busy, the auto beam will not produce +anything. + +@cindex @code{stemLeftBeamCount} + +If you have specific wishes for the number of beams, you can fully +control the number of beams through the properties +@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. + +@lilypond[fragment,relative,verbatim] + \context Staff { + [f'8 r16 f g a] + [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] } -} -@end mudela +@end lilypond @end quotation +@cindex @code{stemRightBeamCount} -@quotation +The beam symbol can be tweaked through @code{Voice.Beam}'s +grob-properties @code{height} and @code{staff-position}, +in staff-spaces. -@example -r\longa r\breve -r1 r2 r4 r8 r16 r32 r64 r64 -@end example +Set @code{height} to zero, to get horizontal beams: +@quotation +@lilypond[fragment,relative,verbatim] + \property Voice.Beam \set #'direction = #1 + \property Voice.Beam \set #'height = #0 + [a''8 e' d c] +@end lilypond @end quotation -@quotation +Here's how you'd specify a weird looking beam that instead of being +horizontal, falls two staff spaces: -@mudela[] -\score { - \notes \relative c'' { - r\longa r\breve - r1 r2 r4 r8 r16 r32 r64 r64 - } - \paper { - loose_column_distance = 2.5 * \staffspace; - linewidth = -1.0; - \translator { - \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - \remove "Bar_engraver"; - } - } -} -@end mudela +@quotation +@lilypond[fragment,relative,verbatim] + \property Voice.Beam \set #'staff-position = #2 + \property Voice.Beam \set #'height = #-2 + [c'8 c] +@end lilypond @end quotation +@cindex @code{default-neutral-direction} -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. +@node Expressive marks +@section Expressive marks -@mudela[fragment,verbatim,center] - a'4. b'4. -@end mudela +@c . {Slur} +@menu +* Slur :: +* Phrasing slur:: +* Breath marks:: +* Tempo:: +* Text spanner:: +@end menu -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. +@node Slur +@subsection Slur +@cindex slur +A slur indicates that notes are to be played bound or @emph{legato}. In +lilypond, they are entered using parentheses: +@lilypond[fragment,verbatim,center] + f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 +@end lilypond -Rests are entered like notes, with note name `@code{r}@indexcode{r}', -or `@code{R}@indexcode{R}'. There is also a note name -`@code{s}@indexcode{s}', which produces a space of the specified -duration. `@code{R}' is specifically meant for entering parts: the -@code{R} rest can expand to fill a score with rests, or it can be -printed as a single multimeasure rest. -You can control the expansion by setting the property -@code{Score.skipBars}. If this is set to true, Lily will not expand -empty measures, and the multimeasure rests automatically adds the -appropriate number. +Slurs avoid crossing stems, and are attached to note heads whenever +possible. In some instances involving beams slurs may be attached to a +stem end. If you want to override this layout you can do this through +@code{Voice.Slur}'s grob-property @code{attachment}: +Maybe reinclude other slur features and move back to tricks? Esp. the +second example, how to fix, can be very helpful. -@cindex lyrics expressions +@quotation +@lilypond[fragment,relative,verbatim] + \property Voice.Slur \set #'direction = #1 + \property Voice.Stem \set #'length = #5.5 + g''8(g)g4 + \property Voice.Slur \set #'attachment = #'(stem . stem) + g8(g)g4 +@end lilypond +@end quotation -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. +If a slur would strike through a stem or beam, the slur will be moved +away upward or downward. If this happens, attaching the slur to the +stems might look better: -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]. +@quotation +@lilypond[fragment,relative,verbatim] + \property Voice.Stem \set #'direction = #1 + \property Voice.Slur \set #'direction = #1 + d'32( d'4 )d8.. + \property Voice.Slur \set #'attachment = #'(stem . stem) + d,32( d'4 )d8.. +@end lilypond +@end quotation +Similarly, the curvature of a slur is adjusted to stay clear of note +heads and stems. When that would increase the curvature too much, the +slur is reverted to its default shape. The threshold for this decision +is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely +related to the enclosed area between the slur and the notes. Usually, +the default setting works well, but in some cases you may prefer a +curved slur when LilyPond decides for a vertically moved one. You can +express this by increasing the @code{beautiful} value: -@cindex properties +@lilypond[verbatim,singleline,relative] + \property Voice.Beam \override #'direction = #-1 + \property Voice.Slur \override #'direction = #1 + c'16( a' f' a a f a, )c, + c( a' f' a a f d, )c + \property Voice.Slur \override #'beautiful = #5.0 + c( a' f' a a f d, )c +@end lilypond -@example - \property@keyindex{property} - @var{contextname}.@var{propname} = @var{value} -@end example +@refbugs -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. +The definition for @code{beautiful} is vague, the default setting is +experimental computer science. +@cindex Adusting slurs +@node Phrasing slur +@subsection Phrasing slur -@cindex translator switches +@cindex phrasing slur +@cindex phrasing mark -@example - \translator@keyindex{translator} - @var{contexttype} = @var{name} -@end example +A phrasing slur (or phrasing mark) connects chords and is used to +indicate a musical sentence. It is entered using @code{\(} and +@code{\)}. -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. +@lilypond[fragment,verbatim,center,relative] + \time 6/4; c''\((d)e f(e)\)d +@end lilypond -Usually this is used to switch staffs in Piano music, e.g. +Typographically, the phrasing slur behaves almost exactly like a normal +slur. The grob associated with it is @code{Voice.PhrasingSlur}. -@example - \translator Staff = top @var{Music} -@end example +@node Breath marks +@subsection Breath marks +Breath marks are entered using @code{\breathe}: -@cindex output properties +@lilypond[fragment,relative] +c'4 \breathe d4 +@end lilypond +Currently, only tick marks are supported, comma style breath marks are +not. The grob for this object is called @code{Voice.BreathingSign}. -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: +@refbugs -@mudela[fragment,verbatim] -\relative c'' { c4 - \context Staff \outputproperty - #(make-type-checker 'Note_head) - #'extra-offset = #'(5.0 . 7.5) - } -@end mudela + Currently, only tick marks are supported, comma style breath marks are +not. -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 - -Commands are music expressions that have no duration. - - -@example - - @code{\key}@keyindex{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. - -@example - - @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @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. - - -@example - \mark@keyindex{mark} @var{unsigned}; - \mark @var{string}; -@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 - -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]. - - - - -@example - - \time@keyindex{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. - -@example - - \tempo@keyindex{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. - -@example - - \partial@keyindex{partial} @var{duration} @code{;} -@end example - -@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. - -@example - - @code{|}@indexcode{|} -@cindex bar check - -@end example - -@cindex shorten measures - -@cindex upstep - -`@code{|}' is a bar check. Whenever a bar check is encountered during -interpretation, a warning message is issued if it doesn't fall at a -measure boundary. This can help you finding errors in the input. -The beginning of the measure will be relocated, so this can also -be used to shorten measures. - - -@example - - \penalty@keyindex{penalty} @var{int} @code{;} -@end example - -Discourage or encourage line breaks. See identifiers -@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in -section [on identifiers] [FIXME]. +@c . {Tempo} +@node Tempo +@subsection Tempo +@cindex Tempo +@cindex beats per minute +@cindex metronome marking +@cindex @code{\tempo} @example - - \clef@keyindex{clef} @var{clefname} @code{;} + \tempo @var{duration} = @var{perminute} @code{;} @end example -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: - -@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 -@end quotation - -@quotation +Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests +output with 76 quarter notes per minute. + +@refbugs + +The tempo setting is not printed, but is currently only used in the MIDI +output. + -@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 -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}'. +@node Text spanner +@subsection Text spanner +@cindex Text spanner +Some textual indications, e.g. rallentando, accelerando, often extend +over a many measures. This is indicated by following the text with a +dotted line. You can create such texts in LilyPond using +text spanners. The syntax is as follows: @example - - \skip@keyindex{skip} @var{duration} @code{;} +\spanrequest \start "text" +\spanrequest \stop "text" @end example +LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The +string to be printed, as well as the style is set through grob +properties. + +An application---or rather, a hack---is to fake octavation indications. +@lilypond[fragment,relative,verbatim] + \relative c' { a'''' b c a + \property Voice.TextSpanner \set #'type = #'dotted-line + \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) + \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") + \property Staff.centralCPosition = #-13 + a\spanrequest \start "text" b c a \spanrequest \stop "text" } +@end lilypond + + +@c . {Ornaments} +@node Ornaments +@section Ornaments +@cindex Ornaments +@menu +* Articulation:: +* Text scripts:: +* Grace notes:: +@end menu -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}'. - - -@cindex beams - -@node Manual beams, , , Reference Manual - -A beam is specified by surrounding the beamed notes with brackets -`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'. - -@mudela[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 - -Beaming can be generated automatically; see section XREF-autobeam [FIXME]. - -[OUTDATED, FIXME] - -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 (see also section -XREF-tremolo [FIXME]). - - -@mudela[fragment,verbatim,center] - \repeat "tremolo" 8 { c16 d16 } - \repeat "tremolo" 4 { c16 d16 } -@end mudela - -@mudela[fragment,verbatim,center] - c'4:32 -@end mudela - - -@cindex --@@@code{-}@code{-} - -@indexcode{__} - -@cindex extender - -@cindex hyphen - -The syntax for an extender mark is `@code{__}'. This syntax can only -be used within lyrics mode. The syntax for a spanning hyphen (i.e., -a hyphen that will be printed between two lyric syllables) is -`@code{-}@code{-}'. - - -@cindex ties - -A tie connects two adjacent note heads of the same pitch. When used -with chords, it connects all of the note heads whose pitches match. -Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'. -If you try to tie together chords which have no common pitches, a -warning message will appear and no ties will be created. - -@mudela[fragment,verbatim,center] - e' ~ e' ~ -@end mudela - - - -[TODO: explain Requests] - +@c . {Articulation} +@node Articulation +@subsection Articulation +@cindex Articulation @cindex articulations - @cindex scripts - @cindex ornaments A variety of symbols can appear above and below notes to indicate @@ -1102,10 +1090,12 @@ forced to appear above or below the note by writing 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 @@ -1114,7 +1104,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 @@ -1129,700 +1119,769 @@ name of the corresponding symbol appearing underneath. indent = 0.0; } } +@end lilypond -@end mudela - -In addition, it is possible to place arbitrary strings of text or -@TeX{} above or below notes by using a string instead of an -identifier: `@code{c^"text"}'. Fingerings -@cindex fingering - can be -placed by simply using digits. All of these note ornaments appear in -the printed output but have no effect on the MIDI rendering of the -music. - -To save typing, fingering instructions (digits 0 to 9 are -supported) and single characters shorthands exist for a few -common symbols - -@mudela[] - +To save typing work, some shorthands are available: +@lilypond[singleline] \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 c''4-|_"c-|" s4 c''4->_"c->" s4 c''4-^_"c-\\^{ }" s4 - c''4-1_"c-1" s4 - c''4-2_"c-2" s4 - c''4-3_"c-3" s4 - c''4-4_"c-4" s4 - } - \paper { - linewidth = 5.875 \in; - indent = 0.0; } } +@end lilypond -@end mudela - -Dynamic marks are specified by using an identifier after a note: -`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'. -The available dynamic marks are: -@code{\ppp}@keyindex{ppp}, -@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp}, -@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff}, -@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff}, -@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf}, -@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp}, -@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and -@code{\rfz}@keyindex{rfz}. - - -@example - - \textscript@keyindex{textscript} @var{text} @var{style} -@end example - -Defines a text to be printed over or under a note. @var{style} is a -string that may be one of @code{roman}, @code{italic}, @code{typewriter}, -@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}. - -You can attach a general textscript request using this syntax: - -@quotation - -@example -c4-\textscript "6" "finger" -c4-\textscript "foo" "normal" -@end example - -@end quotation +@cindex fingering -This is equivalent to `@code{c4-6 c4-"foo"}'. +Fingering instructions can also be entered in this shorthand. +@lilypond[verbatim, singleline, fragment] + c'4-1 c'4-2 c'4-3 c'4-4 +@end lilypond +@cindex @code{\script} @cindex scripts +@cindex superscript +@cindex subscript @example - - \script@keyindex{script} @var{alias} + \script @var{alias} @end example -Prints a symbol above or below a note. The argument is a string -which points into the script-alias table defined in @file{script.scm}. -The scheme definitions specify whether the symbol follows notes into -the staff, dependence of symbol placement on staff direction, and a -priority for placing several symbols over one note. Usually the -@code{\script}@keyindex{script} keyword is not used directly. Various +Defines a script printing request. The argument is a string which +points into the script-alias table defined in @file{scm/script.scm}. +Usually the @code{\script} keyword is not used directly. Various helpful identifier definitions appear in @file{script.ly}. +For information on how to add scripts, consult @file{scm/script.scm}. -@cindex slur -Slurs connects chords and try to avoid crossing stems. A slur is -started with `@code{(}' and stopped with `@code{)}'. The -starting `@code{(}' appears to the right of the first note in -the slur. The terminal `@code{)}' appears to the left of the -first note in the slur. This makes it possible to put a note in -slurs from both sides: +@refbugs -@mudela[fragment,verbatim,center] - f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 -@end mudela +All of these note ornaments appear in the printed output but have no +effect on the MIDI rendering of the music. +Unfortunately, there is no support adding fingering instructions or +ornaments to individual note heads. Some hacks exist, though. See +@file{input/test/script-horizontal.ly}. -@cindex crescendo -A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated -with @code{\rc}@keyindex{rc}. A decrescendo mark is started with -@code{\decr}@keyindex{decr} and terminated with -@code{\rced}@keyindex{rced}. There are also shorthands for these -marks. A crescendo can be started with @code{\<}@keyindex{<} and a -decrescendo can be started with @code{\>}@keyindex{>}. Either one can -be terminated with @code{\!}@keyindex{"!}. Note that @code{\!} -must go before the last note of the dynamic mark whereas @code{\rc} -and @code{\rced} go after the last note. Because these marks are -bound to notes, if you want to get several marks during one note, you -must use spacer notes. - -@mudela[fragment,verbatim,center] - c'' \< \! c'' d'' \decr e'' \rced - < f''1 { s4 \< \! s2 \> \! s4 } > -@end mudela +@c . {Text scripts} +@node Text scripts +@subsection Text scripts +@cindex Text scripts +In addition, it is possible to place arbitrary strings of text or markup +text (see @ref{Text markup}) above or below notes by using a string: +@code{c^"text"}. The text is typeset in italic by default. -@example +The amount of space taken by these indications by default does not +influence, spacing, but setting @code{Voice.textNonEmpty} to true will +take the widths into account. The identifier @code{\fattext} is defined +in the standard includes. +@lilypond[fragment,singleline,verbatim] +\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 } +@end lilypond + +Text scripts are created in form of @code{Voice.TextScript} grobs. - \spanrequest@keyindex{spanrequest} @var{startstop} @var{type} +For purposes of defining identifiers, a more verbose form also exists: + +@example + \textscript @var{text} @end example -Define a spanning request. The @var{startstop} parameter is either -1 -(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and -@var{type} is a string that describes what should be started. -Supported types are @code{crescendo}, @code{decrescendo}, -@code{beam}, @code{slur}. This is an internal command. Users should -use the shorthands which are defined in the initialization file -@file{spanners.ly}. +Defines a text to be printed over or under a note. @var{text} is a +string or a markup text. +@quotation -You can attach a (general) span request to a note using +@example +foo = \textscript #'(finger "6") + [..] +c4-\foo +@end example -@mudela[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" -@end mudela +@end quotation -The slur syntax with parentheses is a shorthand for this. +This is equivalent to @code{c4-6 c4-"foo"}. +@c . {Grace notes} +@node Grace notes +@subsection Grace notes + -@cindex tremolo marks -@node stem tremolo, , , Reference Manual -Tremolo marks can be printed on a single note by adding -`@code{:}[@var{length}]' after the note. The length must be at -least 8. A @var{length} value of 8 gives one line across -the note stem. If the length is omitted, then the last value is -used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was -no last value. -@mudela[verbatim,fragment,center] - c'2:8 c':32 -@end mudela +@cindex Grace music +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes +@cindex @code{graceAlignPosition} -@node Compound music expressions, , , Reference Manual -@section Compound music expressions +Grace notes are ornaments that are written out, but do not take up any +logical time in a measure. LilyPond has limited support for grace notes. +The syntax is as follows. +@example + \grace @var{musicexpr} +@end example -@cindex compound music expressions +When grace music is interpreted, a score-within-a-score is set up: +@var{musicexpr} has its own time bookkeeping, and you could (for +example) have a separate time signature within grace notes. While in +this score-within-a-score, you can create notes, beams, slurs, etc. +Unbeamed eighth notes and shorter by default have a slash through the +stem. This behavior can be controlled with the +@code{Stem}.@code{flag-style} property. -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: +@quotation +@lilypond[fragment,verbatim] +\relative c'' { + \grace c8 c4 \grace { [c16 c16] } c4 + \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4 +} -@mudela[fragment,verbatim,center] - \notes \context Staff { - \cadenzaOn - - < { a b c' } { c' d' e' } > - } -@end mudela +@end lilypond +@end quotation -@cindex context selection -@c @keyindex{context} +At present, nesting @code{\grace} notes is not supported. The following +may cause run-time errors: @example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} + @code{\grace @{ \grace c32 c16 @} c4} @end example - -Interpret @var{musicexpr} within a context of type @var{contexttype}. -If the context does not exist, it will be created. The new context -can optionally be given a name. See -section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more -information on interpretation contexts. - +Since the meaning of such a construct is unclear, we don't consider this +a loss. Similarly, juxtaposing two @code{\grace} sections is +syntactically valid, but makes no sense and may cause runtime errors. +Ending a staff or score with grace notes may also generate a run-time +error, since there will be no main note to attach the grace notes to. -@cindex input modes +A grace note expression has duration 0; the next real note is assumed to +be the main note. If you want the note to appear after the main note, +set @code{Voice.graceAlignPosition} to @code{1}. -@cindex mode switch +@refbugs -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. +The present implementation of grace notes is not robust and generally +kludgy. We expect it to change after LilyPond 1.4. Syntax changes might +also be implemented. -More information on context selection can be found in -section XREF-contextselection [FIXME]. +@menu +* Glissando :: +* Dynamics:: +@end menu -@cindex sequential music +@c . {Glissando} +@node Glissando +@subsubsection Glissando +@cindex Glissando -@example +@cindex @code{\glissando} - \sequential@keyindex{sequential} - @code{@{} @var{musicexprlist} @code{@}} -@end example +A glissando line can be requested by attaching a @code{\glissando} to a +note: -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: +@quotation +@lilypond[fragment,relative,verbatim] + c'' \glissando c' +@end lilypond +@end quotation -@example +@refbugs - @code{@{} @var{musicexprlist} @code{@}} -@end example +Printing of an additional text (such as @emph{gliss.}) must be done +manually. -@cindex simultaneous music +@c . {Dynamics} +@node Dynamics +@subsubsection Dynamics +@cindex Dynamics -@indexcode{<} -@indexcode{>} -@example - \simultaneous@keyindex{simultaneous} - @code{@{} @var{musicexprlist} @code{@}} -@end example +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} -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 +Absolute dynamic marks are specified by using an identifier after a +note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}. - @code{<} @var{musicexprlist} @code{>} -@end example -If you try to use a chord as the first thing in your score, you might -get multiple staffs instead of a chord. +@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 -@mudela[verbatim,center] - \score { - \notes - \paper { - linewidth = -1.; - } - } -@end mudela +[BUG in \> ! ] -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: +You can also use a text saying @emph{cresc.} instead of hairpins. Here +is an example how to do it: -@mudela[verbatim,center] - \score { - \notes\context Voice - \paper { - linewidth = -1.; - } +@lilypond[fragment,relative,verbatim] + \context Voice { + \property Voice.crescendoText = "cresc." + \property Voice.crescendoSpanner = #'dashed-line + a''2\mf\< a a \!a } -@end mudela +@end lilypond -@cindex relative pitch specification -@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. -@example +@c . {Repeats} +@node Repeats +@section Repeats - \relative@keyindex{relative} @var{startpitch} @var{musicexpr} -@end example -The octave of notes that appear in @var{musicexpr} are calculated as -follows: If no octave changing marks are used, the basic interval -between this and the last note is always taken to be a fourth or -less.@footnote{The interval is determined without regarding -accidentals. A @code{fisis} following a @code{ceses} will be put above -the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}' -can then be added to raise or lower the pitch by an extra octave. -Upon entering relative mode, an absolute starting pitch must be -specified that will act as the predecessor of the first note of -@var{musicexpr}. - -Entering scales is straightforward in relative mode. - -@mudela[fragment,verbatim,center] - \relative c' { - c d e f g a b c c, - } -@end mudela +@cindex repeats +@cindex @code{\repeat} -And octave changing marks are used for intervals greater than a fourth. +To specify repeats, use the @code{\repeat} keyword. Since repeats +should work differently when played or printed, there are a few +different variants of repeats. -@mudela[fragment,verbatim,center] - \relative c'' { - c g c f, c' a, e'' } -@end mudela +@table @asis +@item unfolded +Repeated music is fully written (played) out. Useful for MIDI +output. -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. +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (voltas) are printed, left to right. -@mudela[fragment,verbatim,center] - \relative c' { - c - - - } -@end mudela +@item folded +Alternative endings are written stacked. Which is unfortunately not +practical for anything right now. -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). +@item tremolo +Make tremolo beams. -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}. +@item percent +Make measure repeats. These look like percent signs. -It is strongly recommended to use relative pitch mode: less work, -less error-prone, and more readable. +@end table +@menu +* Repeat syntax:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivision:: +* Measure repeats:: +@end menu +@node Repeat syntax +@subsection Repeat syntax -Chord names are a way to generate simultaneous music expressions that -correspond with traditional chord names. It can only be used in -Chord mode (see section XREF-modes [FIXME]). +The syntax for repeats is @example + \repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example - @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. +If you have alternative endings, you may add +@cindex @code{\alternative} +@example + \alternative @code{@{} @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @code{@}} @end example +where each @var{alternative} is a music expression. -@var{tonic} should be the tonic note of the chord, and @var{duration} -is the chord duration in the usual notation. There are two kinds of -modifiers. One type is @emph{chord additions}, which are obtained by -listing intervals separated by dots. An interval is written by its -number with an optional `@code{+}' or `@code{-}' to indicate raising or -lowering by half a step. Chord additions has two effects: It adds -the specified interval and all lower odd numbered intervals to the -chord, and it may lower or raise the specified interval. Intervals -must be separated by a dot (`@code{.}'). +Normal notation repeats are used like this: +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 { c'4 d' e' f' } + \repeat volta 2 { f' e' d' c' } +@end lilypond +With alternative endings: @quotation +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } +@end lilypond +@end quotation -@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 - } -} +Folded repeats look like this:@footnote{Folded repeats offer little +more over simultaneous music. However, it is to be expected that +more functionality -- especially for the MIDI backend -- will be +implemented at some point in the future.} + +@quotation +@lilypond[fragment,verbatim] + c'1 + \repeat fold 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } -@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. -@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. -@mudela[fragment,verbatim] -\transpose c'' { - \chords { - c1:m c:min7 c:maj c:aug c:dim c:sus +@quotation +@lilypond[fragment,verbatim] +\context Staff { + \relative c' { + \partial 4; + \repeat volta 3 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b2. } } } } - -@end 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. +@refbugs -@mudela[fragment,verbatim,center] - \transpose c'' { - \chords { - c1^3 c:7^5.3 c:8^7 - } - } -@end mudela +As you can see, LilyPond doesn't remember the timing information, nor +are slurs or ties repeated, so you have to reset timing information +after a repeat, e.g. using a bar-check (See @ref{Bar check}), +@code{Score.measurePosition} or @code{\partial}. We hope to fix this +after 1.4. -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. +It is possible to nest @code{\repeat}, although it probably is only +meaningful for unfolded repeats. -@mudela[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/e c/g c:7/e - } - } +@node Manual repeat commands +@subsection Manual repeat commands -@end mudela +@cindex @code{repeatCommands} -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. +The property @code{repeatCommands} can be used to control the layout of +repeats. Its value is a Scheme list of repeat commands, where each repeat +command can be -@mudela[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/+c c/+g c:7/+b - } - } +@table @code +@item 'start-repeat + Print a |: bar line +@item 'stop-repeat + Print a :| bar line +@item (volta . @var{text}) + Print a volta bracket saying @var{text}. +@item (volta . #f) + Stop a running volta bracket +@end table -@end mudela +@lilypond[verbatim, fragment] + c''4 + \property Score.repeatCommands = #'((volta "93") end-repeat) + c4 c4 + \property Score.repeatCommands = #'((volta #f)) + c4 c4 +@end lilypond -Throughout these examples, chords have been shifted around the staff -using @code{\transpose}. -You should not combine @code{\relative} with named chords. +@node Tremolo repeats +@subsection Tremolo repeats +@cindex tremolo beams +To place tremolo marks between notes, use @code{\repeat} with tremolo +style. +@lilypond[verbatim,center,singleline] +\score { + \context Voice \notes\relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } + \repeat "tremolo" 4 c16 + } +} +@end lilypond +@refbugs -@cindex tuplets -Tuplets are made out of a music expression by multiplying their -duration with a fraction. +At present, the spacing between tremolo beams is not regular, since the +spacing engine does not notice that not all notes are printed. -@example +@node Tremolo subdivision +@subsection Tremolo subdivision +@cindex tremolo marks +@cindex @code{tremoloFlags} - \times@keyindex{times} @var{fraction} @var{musicexpr} -@end example +Tremolo marks can be printed on a single note by adding +`@code{:}[@var{length}]' after the note. The length must be at least 8. +A @var{length} value of 8 gives one line across the note stem. If the +length is omitted, then then the last value (stored in +@code{Voice.tremoloFlags}) is used. -The duration of @var{musicexpr} will be multiplied by the fraction. -In print, the fraction's denominator will be printed over the notes, -optionally with a bracket. The most common tuplet is the triplet in -which 3 notes have the length of 2, so the notes are 2/3 of -their written length: +@lilypond[verbatim,fragment,center] + c'2:8 c':32 +@end lilypond +Using this mechanism pays off when you entering many tremolos, since the +default argument saves a lot of typing. -@mudela[fragment,verbatim,center] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 -@end mudela +@refbugs +Tremolos in this style do not carry over into the MIDI output. -@cindex grace notes -@example +@node Measure repeats +@subsection Measure repeats - \grace@keyindex{grace} @var{musicexpr} -@end example +@cindex percent repeats +@cindex measure repeats -A grace note expression has duration 0; the next real note is -assumed to be the main note. +In the @code{percent} style, a note pattern can be repeated. It is +printed once, and then the pattern is replaced with a special sign. -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}. +@lilypond[verbatim,singleline] + \context Voice { \repeat "percent" 5 { c'1 } } +@end lilypond -When grace music is interpreted, a score-within-a-score is set up: -@var{musicexpr} has its own time bookkeeping, and you could (for -example) have a separate time signature within grace notes. While in -this score-within-a-score, you can create notes, beams, slurs, etc. -Unbeamed eighth notes and shorter by default have a slash through the -stem. This behavior can be controlled with the -@code{flagStyle}@indexcode{flagStyle} property. +At present, only repeats of whole measures are supported. -@quotation +@node Rhythmic music +@section Rhythmic music -@mudela[fragment,verbatim] -\relative c'' { - \grace c8 c4 \grace { [c16 c16] } c4 - \grace { \property Grace.flagStyle = "" c16 } c4 -} -@end mudela -@end quotation +@menu +* Rhythmic staffs:: +@end menu -At present, nesting @code{\grace}@keyindex{grace} notes, e.g. +@node Rhythmic staffs +@subsection Rhythmic staffs -@example +Some times you might want to show only the rhythm of a melody. This can +be done with the rhythmic staff. All pitches of notes on such a staff +are squashed, and the staff itself looks has a single staff line: - @code{\grace @{ \grace c32 c16 @} c4} -@end example +@lilypond[fragment,relative ] + \context RhythmicStaff { + \time 4/4; + c4 e8 f g2 | r4 g r2 | g1:32 | r1 | + } +@end lilypond -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. +@c . {Piano music} +@node Piano music +@section Piano music +Piano music is an odd type of notation: two staffs are largely +independent, but sometimes voices can cross between the two staffs. The +@code{PianoStaff} is especially built to handle this cross-staffing +behavior. In this section we discuss the @code{PianoStaff} and some +other pianistic peculiarities. +@menu +* Automatic staff changes:: +* Manual staff switches:: +* Pedals:: +* Arpeggio:: +* VoiceFollower:: +@end menu -@cindex repeats -@node Repeats, , , Reference Manual +@c . {Automatic staff changes} +@node Automatic staff changes +@subsection Automatic staff changes +@cindex Automatic staff changes -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. +Voices can be switched from top to bottom staff automatically. The +syntax for this is +@example + \autochange @var{contexttype} @var{musicexp} +@end example +This will switch notation context of @var{musicexp} between a +@var{contexttype} named @code{up} and @code{down}. Typically, you use +@code{Staff} for @var{contexttype}. The autochanger switches on basis +of pitch (central C is the turning point), and it looks ahead skipping +over rests to switch rests in advance. + +@lilypond[verbatim,singleline] +\score { \notes \context PianoStaff < + \context Staff = "up" { + \autochange Staff \context Voice = VA < \relative c' { + g4 a b c d r4 a g } > } + \context Staff = "down" { + \clef bass; + s1*2 +} > } +@end lilypond -@table @samp - @item unfolded - Repeated music is fully written (played) out. Useful for MIDI - output. +Note how spacer rests are used to prevent the bottom staff from +terminating too soon. - @item volta - This is the normal notation: Repeats are not written out, but - alternative endings (voltas) are printed, left to right. - @item folded - Alternative endings are written stacked, which is useful for - lyrics. -@end table +@node Manual staff switches +@subsection Manual staff switches -The syntax for repeats is +@cindex manual staff switches +@cindex staff switch, manual +Voices can be switched between staffs manually, using the following command: @example - - \repeat @var{variant} @var{repeatcount} @var{repeatbody} + \translator Staff = @var{which} @var{music} @end example +The string @var{which} is the name of the staff. Typically it is +@code{"up"} or @code{"down"}. -If you have alternative endings, you may add +Formally, this construct is a music expression indicating that the +context which is a direct child of the a context of type +@var{contexttype} should be shifted to a context of type +@var{contexttype} and the specified name. +@cindex @code{\translator} @example - - \alternative@keyindex{alternative} - @code{@{} @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @code{@}} + \translator @var{contexttype} = @var{name} @end example -where each @var{alternative} is a Music expression. -Normal notation repeats are used like this: +@c . {Pedals} +@node Pedals +@subsection Pedals +@cindex Pedals -@quotation +Piano pedal instruction can be expressed using +@code{\sustainDown}, @code{\sustainUp}, @code{\unaChorda}, +@code{\treChorde}, @code{\sostenutoDown} and @code{\sostenutoUp}. -@mudela[fragment,verbatim] - c'1 - \repeat volta 2 { c'4 d' e' f' } - \repeat volta 2 { f' e' d' c' } +These identifiers are short hands for spanner commands of the types +@code{Sustain}, @code{UnaChorda} and @code{Sostenuto}: -@end mudela -@end quotation +@lilypond[fragment,verbatim] +c''4 \spanrequest \start "Sustain" c''4 c''4 \spanrequest \stop "Sustain" +@end lilypond -With alternative endings: +The symbols that are printed can be modified by setting +@code{pedal@var{X}Strings}, where @var{X} is one of the pedal +types. Refer to the generated documentation for more information. -@quotation +@refbugs -@mudela[fragment,verbatim] - c'1 - \repeat volta 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } -@end mudela -@end quotation +Currently, brackets are not supported, only text markings (ie. *Ped +style). -Folded repeats look like this:@footnote{Folded repeats offer little -more over simultaneous music. However, it is to be expected that -more functionality -- especially for the MIDI backend -- will be -implemented.} -@quotation +@c . {Arpeggio} +@node Arpeggio +@subsection Arpeggio +@cindex Arpeggio -@mudela[fragment,verbatim] - c'1 - \repeat fold 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } +@cindex broken arpeggio +@cindex @code{\arpeggio} + +You can specify an arpeggio sign on a chord by attaching an +@code{\arpeggio} to a note of the chord. -@end mudela -@end quotation @quotation +@lilypond[fragment,relative,verbatim] + \context Voice +@end lilypond +@end 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 } } - } -} +When an arpeggio crosses staffs in piano music, you attach an arpeggio +to the chords in both staffs, and set +@code{PianoStaff.connectArpeggios}. -@end mudela +@quotation +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.connectArpeggios = ##t + \context Voice = one { } + \context Voice = other { \clef bass; } + > +@end lilypond @end quotation -If you don't give enough alternatives for all of the repeats, then -the first alternative is assumed to be repeated often enough to equal -the specified number of repeats. +This command creates @code{Arpeggio} grobs. -@quotation +@refbugs -@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 } } - } -} + It is not possible to mix +connected arpeggios and unconnected arpeggios at the same time. + + +@c . {VoiceFollower} +@node VoiceFollower +@subsection VoiceFollower + +@cindex follow voice +@cindex staff switching +@cindex cross staff + +@cindex @code{followVoice} -@end mudela +Whenever a voice switches to another staff a line connecting the notes +can be printed automatically. This is enabled if the property +@code{PianoStaff.followVoice} is set to true: + +@quotation +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.followVoice = ##t + \context Staff \context Voice { + c'1 + \translator Staff=two + b2 a + } + \context Staff=two {\clef bass; \skip 1*2;} + > +@end lilypond @end quotation -It is possible to nest @code{\repeat}. This is not entirely -supported: the notes will come be in the right places, but the repeat -bars will not. +@c . {Lyrics} +@node Lyrics +@section Lyrics -@cindex transposition of pitches +@menu +* Lyrics mode:: +* Printing lyrics:: +* Automatic syllable durations:: +* More stanzas:: +@end menu -@node transpose, , , Reference Manual +@c . {Lyrics mode} +@node Lyrics mode +@subsection Lyrics mode +@cindex Lyrics mode -A music expression can be transposed with -@code{\transpose}@keyindex{transpose}. The syntax is +To print lyrics in LilyPond, you must first make a music expression from +the lyric text. When they're in a music expression, that music +expression can be printed by selecting an appropriate context. We shall +discuss lyric printing in this order. -@example - \transpose @var{pitch} @var{musicexpr} -@end example +@cindex lyric mode +@cindex @code{\lyrics} -This means that middle C in @var{musicexpr} is transposed to -@var{pitch}. +You can enter lyrics in a special input mode of LilyPond. This mode is +called Lyrics mode, and it is introduced by the keyword @code{\lyrics}. +The purpose of this mode is that you can enter lyrics as plain text, +punctuation and accents without any hassle. -@code{\transpose} distinguishes between enharmonic pitches: both -@code{\transpose cis'} or @code{\transpose des'} will transpose up half -a tone. The first version will print sharps and the second version -will print flats. +The precise definition of this mode is in @ref{Lyrics mode +definition}. The definition itself is ludicrous, and this will remain so +until the authors of LilyPond acquire a deeper understanding of +character encoding, or someone else steps up to fix this. -@quotation +Syllables are entered like notes, with pitches replaced by text. For +example, @code{Twin- kle twin- kle} enters four syllables. Note that +the hyphen has no special meaning for lyrics, and does not introduce +special symbols. -@mudela[fragment,verbatim] -\context Staff { - \clef "F"; - { \key e \major; c d e f } - \clef "G"; - \transpose des'' { \key e \major; c d e f } - \transpose cis'' { \key e \major; c d e f } -} +Spaces can be introduced into a lyric either by using quotes +(@code{"}) or by using an underscore without quotes: @code{He_could4 +not4}. All unquoted underscores are converted to spaces. -@end mudela -@end quotation +@c . {Printing lyrics} +@node Printing lyrics +@subsection Printing lyrics +@cindex lyrics -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}. +Normally, you will want to have notes and syllables matched +automatically. This is accomplished using @code{\addlyrics}, which is +documented in @ref{Automatic syllable durations}. Setting +@code{automaticMelismata} in the melody staff, will cause slurs to be +interpreted as melismata. Lyric syllables must be interpreted within a +@code{Lyrics} context in order to printing them. + +@lilypond[verbatim,singleline] +\addlyrics \notes \relative c' { + \time 7/4; + \property Staff.automaticMelismata = ##t + d'2 c4 b2 a2 + b2 c4 b4 () a4 g2 } + \context Lyrics \lyrics { + Join us now and + share the so -- ftware; } +@end lilypond + +@cindex extender +@cindex lyric extender +@cindex melisma +As you can see, extender lines are entered as @code{__}. This will +create an extender, a line that extends over the entire duration of the +lyric. This line will run all the way to the start of the next lyric, +so you may want to shorten it by using a blank lyric (using @code{_}). +@cindex hyphen -@cindex automatic lyric durations +If you want to have hyphens centered between syllables (rather than +attached to the end of the first syllable) you can use the special +`@code{-}@code{-}' lyric as a separate word between syllables. This +will result in a hyphen which length varies depending on the space +between syllables, and which will be centered between the syllables. -If you have lyrics that are set to a melody, you can import the -rhythm of that melody into the lyrics using @code{\addlyrics}. -@keyindex{addlyrics} The syntax for this is +@cindex Lyric hyphen -@example +@node Automatic syllable durations +@subsection Automatic syllable durations +@cindex Automatic syllable durations + +@cindex automatic lyric durations +@cindex @code{\addlyrics} +If you have lyrics that are set to a melody, you can import the rhythm +of that melody into the lyrics using @code{\addlyrics}. The syntax for +this is +@example \addlyrics @var{musicexpr1 musicexpr2} @end example @@ -1830,14 +1889,13 @@ This means that both @var{musicexpr1} and @var{musicexpr2} are interpreted, but that every non-command atomic music expression (``every syllable'') in @var{musicexpr2} is interpreted using timing of @var{musicexpr1}. +@cindex @code{automaticMelismata} -If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the +If the property @code{automaticMelismata} is set in the context of @var{musicexpr1}, no lyrics will be put on slurred or tied notes. -@quotation - -@mudela[verbatim,fragment] +@lilypond[verbatim,fragment] \addlyrics \transpose c'' { \property Voice.automaticMelismata = ##t @@ -1845,17 +1903,26 @@ notes. } \context Lyrics \lyrics { do4 re mi fa } +@end lilypond -@end mudela -@end quotation +If you want the lyric lines to be above the melody staff, or in some +other, more complex configuration, then build that configuration first +using simultaneous music, and use @code{\addlyrics} after that. -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: +@lilypond[verbatim, singleline] +\notes < + \context Lyrics = LA { s1 } + \context Staff = SA { s1 } + \addlyrics + \context Staff = SA \relative c' { c4 e g g } + \context Lyrics = LA \lyrics { geen ge -- don -- der } > +@end lilypond -@quotation +For @code{\addlyrics} you should use a single rhythm melody, and single +rhythm lyrics (a constant duration is the obvious choice). If you do +not, you can get undesired effects when using multiple stanzas: -@mudela[verbatim,fragment] +@lilypond[verbatim,fragment] \addlyrics \transpose c'' { c8 () cis d8. e16 f2 @@ -1863,265 +1930,1454 @@ undesired effects when using multiple stanzas: \context Lyrics \lyrics < { do4 re mi fa } { do8 re mi fa } > - -@end mudela -@end quotation +@end lilypond It is valid (but probably not very useful) to use notes instead of lyrics for @var{musicexpr2}. +@node More stanzas +@subsection More stanzas +@cindex phrasing +If you have multiple stanzas printed underneath each other, the separate +syllables should be aligned around punctuation. LilyPond can do this if +you explain it which lyric lines belong to which melody. -@node Ambiguities, , , Reference Manual -@section Ambiguities - -@cindex ambiguities - -The grammar contains a number of ambiguities.@footnote{The authors -hope to resolve them at a later time.} +To this end, give the Voice context an identity, and set the LyricsVoice +to name starting with that identity. In the following example, the Voice +identity is @code{duet}, and the identities of the LyricsVoices are +@code{duet-1} and @code{duet-2}. -@itemize @bullet - @item The assignment - @example -foo = bar -@end example +@lilypond[singleline,verbatim] +\score { +\addlyrics + \notes \relative c'' \context Voice = duet { \time 3/4; + g2 e4 a2 f4 g2. } + \lyrics \context Lyrics < + \context LyricsVoice = "duet-1" { + \property LyricsVoice . stanza = "Bert" + Hi, my name is bert. } + \context LyricsVoice = "duet-2" { + \property LyricsVoice . stanza = "Ernie" + Ooooo, ch\'e -- ri, je t'aime. } + > +} +@end lilypond - can be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. +You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the +first system) and @code{LyricsVoice.stz} for the following systems. - @item The assignment +@cindex stanza numbering - @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). +@c . {Chords} +@node Chords +@section Chords +@cindex Chords - @item If you do a nested repeat like +LilyPond has support for both entering and printing chords. Chords are +a harmonic device that is characterized by a set of pitches. It is +something different from simultaneous music, although you can express a +chord using simultaneous music. In fact, chords are internally stored as +simultaneous music expressions. This means you can enter chords by name, +and print them as note head, or enter as notes and print as chord names: - @quotation -@example -\repeat @dots{} -\repeat @dots{} -\alternative -@end example +@lilypond[verbatim,singleline] +twoWays = \notes \transpose c'' { + \chords { + c1 f:sus4 bes/f + } + + + + } - @end quotation +\score { + < \context ChordNames \twoWays + \context Staff \twoWays > } +@end lilypond - 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. +Note that this example also shows that the LilyPond chord does not +attempt to be intelligent, if you enter @code{f bes d}, it does no +attempt to find out whether it this is an inversion. - @item (an as yet unidentified ambiguity :-) -@end itemize +@menu +* Chords mode:: +* Printing named chords:: +@end menu +@c . {Chords mode} +@node Chords mode +@subsection Chords mode +@cindex Chords mode + +Chord mode is a mode where you can input sets of pitches using common +names. It is introduced by the keyword @code{\chords}. It is similar +to note mode, but words are also looked up in a chord modifier table +(containing @code{maj}, @code{dim}, etc). + +Dashes and carets are used to indicate chord additions and subtractions, +so articulation scripts can not be entered in Chord mode. + +The syntax for named chords is as follows: +@example + + @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. +@end example + +@var{tonic} should be the tonic note of the chord, and @var{duration} +is the chord duration in the usual notation. There are two kinds of +modifiers. One type is @emph{chord additions}, which are obtained by +listing intervals separated by dots. An interval is written by its +number with an optional @code{+} or @code{-} to indicate raising or +lowering by half a step. Chord additions has two effects: It adds +the specified interval and all lower odd numbered intervals to the +chord, and it may lower or raise the specified interval. Intervals +must be separated by a dot (@code{.}). + +Throughout these examples, chords have been shifted around the staff +using @code{\transpose}. + + +@quotation + +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1 c:3- c:7 c:8 + c:9 c:9-.5+.7+ c:3-.5- c:4.6.8 + } +} + +@end lilypond +@end quotation + +@cindex @code{aug} +@cindex @code{dim} +@cindex @code{maj} +@cindex @code{sus} + +The second type of modifier that may appear after the @code{:} is a +named modifier. Named modifiers are listed in the file +@file{chord-modifiers.ly}. The available modifiers are @code{m} and +@code{min} which lower the 3rd half a step, `@code{aug}' which +raises the 5th, `@code{dim}' which lowers the 5th, +`@code{maj}' which adds a raised 7th, and `@code{sus}' +which replaces the 5th with a 4th. + +@quotation + +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1:m c:min7 c:maj c:aug c:dim c:sus + } +} + +@end lilypond +@end quotation + + +Chord subtractions are used to eliminate notes from a chord. The +notes to be subtracted are listed after a @code{^} character, +separated by dots. + +@lilypond[fragment,verbatim,center] + \transpose c'' { + \chords { + c1^3 c:7^5.3 c:8^7 + } + } +@end lilypond +@cindex @code{/} + +Chord inversions can be specified by appending `@code{/}' and the name +of a single note to a chord. In a chord inversion, the inverted note is +transposed down until it is the lowest note in the chord. If the +specified note is not in the chord, a warning will be printed. + +@lilypond[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/e c/g c:7/e + } + } + +@end lilypond +@cindex @code{/+} + +Bass notes can be added by `@code{/+}' and +the name of a single note to a chord. This has the effect of +adding the specified note to the chord, lowered by an octave, +so it becomes the lowest note in the chord. + +@lilypond[fragment,verbatim,center] + \transpose c''' { + \chords { + c1 c/+c c/+g c:7/+b + } + } + +@end lilypond + + + + +@c . {Printing named chords} +@node Printing named chords +@subsection Printing named chords + +@cindex printing chord names +@cindex chord names +@cindex chords +@cindex @code{ChordNames} + + +For displaying printed chord names, use the @code{ChordNames} context. +The chords may be entered either using the notation described above, or +directly using simultaneous music. + +@quotation +@lilypond[verbatim,singleline] +scheme = \notes { + \chords {a1 b c} +} +\score { + \notes< + \context ChordNames \scheme + \context Staff \transpose c'' \scheme + > +} +@end lilypond +@end quotation + +You can make the chord changes stand out by setting property +@code{ChordNames.chordChanges} to true. This will only display chord +names when there's a change in the chords scheme and at the start of the +line. + +@quotation +@lilypond[verbatim] +scheme = \chords { + c1:m \break c:m c:m c:m d +} + +\score { + \notes < + \context ChordNames { + \property ChordNames.chordChanges = ##t + \scheme } + \context Staff \transpose c'' \scheme + > } +@end lilypond +@end quotation + +LilyPond examines chords specified as lists of notes to determine a name +to give the chord. LilyPond will not try to identify chord inversions or +added base, which may result in strange chord names when chords are +entered as a list of pitches: + +[base vs. bass ?] + +@quotation +@lilypond[verbatim,center,singleline] +scheme = \notes { + + + +} + +\score { + < + \context ChordNamesVoice \scheme + \context Staff \scheme + > +} +@end lilypond +@end quotation + + +By default LilyPond uses chord name system proposed by Harald Banter +(See @ref{Literature}). The system is is unambiguous and has a logical +structure. Typical American style chord names may be selected by +setting the @code{style} property of the @code{ChordNames.ChordName} +grob to @code{'american}. Similarly @code{'jazz} selects Jazz +chordnames. + +Routines that determine the names to be printed are written in Scheme, +and may be customized by the user. The code can be found in +@file{scm/chord-name.scm}. + +[3 short examples showing differences between american, banter and jazz] + +@node Writing parts +@section Writing parts + +Orchestral music involves some special notation, both in the full score, +as in the individual parts. This section explains how to tackle common +problems in orchestral music. + + +@c . {Transpose} +@menu +* Rehearsal marks:: +* Bar numbers:: +* Instrument names:: +* Transpose:: +* Sound output for transposing instruments:: +* Multi measure rests:: +* Automatic part combining:: +* Hara-kiri staffs:: +@end menu + +@c . {Rehearsal marks} +@node Rehearsal marks +@subsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} +@cindex @code{Mark_engraver} + +@example + \mark @var{unsigned}; + \mark @var{string}; + \mark ; +@end example + +With this command, you can print a rehearsal mark above the system. You +can provide a number, a string or a markup text as argument. If there is +no argument, the property @code{rehearsalMark} is used and automatically +incremented. + +@lilypond[fragment,verbatim] +\relative c'' { + c1 \mark "A2"; + c1 \mark ; + c1 \mark ; + c1 \mark "12"; + c1 \mark #'(music "scripts-segno") ; + c1 +} +@end lilypond + +@node Bar numbers +@subsection Bar numbers + +Bar numbers are printed at the start of the line by default. This is +done by the @code{Bar_number_engraver} in the Score context. + +@refbugs + +It is currently not possible to make boxed bar numbers, or print them at +regular intervals. + + +@node Instrument names +@subsection Instrument names + +You can specify an instrument name for a staff by setting +@code{Staff.instrument} and @code{Staff.instr}. This will print a string +before the start of the staff. For the first start, @code{instrument} is +used, for the next ones @code{instr} is used. + +@lilypond[verbatim,singleline] +\score { \notes { + \property Staff.instrument = "ploink " { c''4 } } + \paper { + \translator { \StaffContext + \consists "Instrument_name_engraver"; } } } +@end lilypond + +This requires that you add the @code{Instrument_name_engraver} to the +staff context. + + +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} + +A music expression can be transposed with @code{\transpose}. The syntax +is +@example + \transpose @var{pitch} @var{musicexpr} +@end example + +This means that middle C in @var{musicexpr} is transposed to +@var{pitch}. + +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose cis'} or @code{\transpose des'} will transpose up half +a tone. The first version will print sharps and the second version +will print flats. + +@quotation +@lilypond[fragment,verbatim] +\context Staff { + \clef "F"; + { \key e \major; c d e f } + \clef "G"; + \transpose des'' { \key e \major; c d e f } + \transpose cis'' { \key e \major; c d e f } +} + +@end lilypond +@end quotation + +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}. + +@node Sound output for transposing instruments +@subsection Sound output transposing instruments + +When you want to play a score containing transposed and untransposed +instruments, you have to instruct LilyPond the pitch offset (in +semitones) for the transposed instruments. This is done using the +@code{transposing} property. It does not affect printed output. + +@cindex @code{transposing} + +@example + \property Staff.instrument = #"Cl. in B-flat" + \property Staff.transposing = #-2 +@end example + + +@c . {Multi measure rests} +@node Multi measure rests +@subsection Multi measure rests +@cindex Multi measure rests + +@cindex @code{R} + +Multi measure rests are entered using `@code{R}'. It is specifically +meant for entering parts: the rest can expand to fill a score with +rests, or it can be printed as a single multimeasure rest This expansion +is controlled by the property @code{Score.skipBars}. If this is set to true, +Lily will not expand empty measures, and the appropriate number is added +automatically. + +@lilypond[fragment,verbatim] + \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 +@end lilypond + +Currently, there is no way to condense multiple rests into a single +multimeasure rest. + +@cindex condensing rests + +@node Automatic part combining +@subsection Automatic part combining +@cindex automatic part combining +@cindex part combiner + +Automatic part combining is used to merge two parts of music onto on +staff in an intelligent way. It is aimed primarily at typesetting Hymns +and orchestral scores. When the two parts are identical for a period of +time, only one is shown. In places where the two parts differ, stem +directions are set automatically. Also, soli and @emph{a due} parts can be +identified and marke. + +The syntax for part combining is + +@example + \partcombine @var{context} @var{musicexpr1} @var{musicexpr2} +@end example + +where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be +combined into one context @var{context}. The names of the music +expressions must start with the prefixes @code{one} and @code{two}. + +[Name of music expressions? is that context name? ] + +The most useful function of the part combiner to combining threads into +one voice, as common for wind parts in orchestral scores: + +@lilypond[verbatim,singleline,fragment] + \context Staff < + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + g a b r + } + \context Thread=two \relative c'' { + g r2 f4 + } + > +@end lilypond + +Notice that the first @code{g} appears only once, although it was +specified twice (once in each Thread). Also note that stem, slur and tie +directions are set automatically, depending whether there is a solo or +unisono. The Thread called @code{one} always gets up stems, and "solo", +while @code{two} always gets down stems and "Solo II". + +If you just want the splitting of Threads and setting of directions, and +not the textual markings, you may set the property @var{soloADue} to +false. This mode can be used to set hymns: + +@lilypond[verbatim,singleline,fragment] + \context Staff < + \property Staff.soloADue = ##f + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + b4 a c g + } + \context Thread=two \relative c'' { + d,2 a4 g' + } + > +@end lilypond + +There are a number of other properties that you can use to tweak +the behavior of part combining, refer to the automatically generated +documentation. Look for @code{Thread_devnull_engraver} +@code{Voice_devnull_engraver} and @code{A2_engraver}. + +@cindex @code{Thread_devnull_engraver} +@cindex @code{Voice_engraver} +@cindex @code{A2_engraver} + +@node Hara-kiri staffs +@subsection Hara-kiri staffs + +In orchestral scores, staffs that only have rests are usually removed. +This saves some space. LilyPond also supports this through the +hara-kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide +of the Japanese Samourai warriors.} staff. This staff commits suicide +when it finds itself to be empty after the line-breaking process---note +that it will not disappear when it contains normal rests, you must use +multi measure rests. + +The hara kiri staff is specialized version of the Staff context. It is +available as the context identifier @code{\HaraKiriStaffContext}. +Observe how the second staff in this example disappears in the second +line. + +@lilypond[verbatim] +\score { + \notes \relative c' < + \context Staff = SA { e4 f g a \break c1 } + \context Staff = SB { c4 d e f \break R1 } + > + \paper { + linewidth = 6.\cm ; + \translator { \HaraKiriStaffContext } + } +} +@end lilypond + + + +@c . {Custodes} +@node Custodes +@section Custodes +@cindex Custos +@cindex Custodes + +A @emph{custos} (plural: @emph{custodes}; latin word for "guard") is a +staff context symbol that appears at the end of a staff line. It +anticipates the pitch of the first note(s) of the following line and +thus helps the player or singer to manage line breaks during +performance, thus enhancing readability of a score. + +@quotation +@lilypond[verbatim] +\score { + \notes { c'1 d' e' d' \break c' d' e' d' } + \paper { + \translator { + \StaffContext + \consists Custos_engraver; + Custos \override #'style = #'mensural; + } + } +} +@end lilypond +@end quotation + +Custodes were frequently used in music notation until the 16th century. +There were different appearences for different notation styles. +Nowadays, they have survived only in special forms of musical notation +such as via the @emph{editio vaticana} dating back to the beginning of +the 20th century. + +For typesetting custodes, just put a @code{Custos_engraver} into the +@code{StaffContext} when declaring the @code{\paper} block. In this +block, you can also globally control the appearance of the custos symbol +by setting the custos @code{style} property. Currently supported styles +are @code{vaticana}, @code{medicaea}, @code{hufnagel} and +@code{mensural}. + +@example +\paper @{ + \translator @{ + \StaffContext + \consists Custos_engraver; + Custos \override #'style = #'mensural; + @} +@} +@end example + +The property can also be set locally, for example in a @code{\notes} +block: + +@example +\notes @{ + \property Staff.Custos \override #'style = #'vaticana + c'1 d' e' d' \break c' d' e' d' +@} +@end example + +@c . {Tuning output} +@node Tuning output +@section Tuning output + +LilyPond tries to take as much formatting as possible out of your +hands. Nevertheless, there are situations where it needs some help, or +where you want to override its decisions. In this section we discuss +ways to do just that. + +Notation output is specified in so called grobs (graphic objects). Each +grob carries with it a set of properties (grob properties) specific to +that object. For example, a stem grob has properties that specify its +direction, length and thickness. + + +The most common way of tuning the output is to alter the values of these +properties. There are two ways of doing that: first, you can temporarily +change the definition of a certain type of grob, thus affecting a whole +set of objects. Second, you can select one specific object, and set a +grob property. + +@menu +* Tuning groups of grobs :: +* Tuning per grob :: +* What to tune?:: +* Font selection:: +* Text markup:: +@end menu + +@node Tuning groups of grobs +@subsection Tuning groups of grobs + +@cindex grob description + +A grob definition is a Scheme association list, that is stored in a context +property. By assigning to that property (using plain @code{\property}), +you can change the resulting grobs. + +@lilypond[verbatim, fragment] +c'4 \property Voice.Stem \override #'meta = #'((interfaces . ())) c'4 +@end lilypond + +The @code{\property} statement effectively empties the definition of the +Stem object. One of the effects is that property specifying how it +should be printed is erased, with the effect of rendering it invisible. + +@cindex \override +@cindex \revert +@cindex \set + +This mechanism is fairly crude, since you can only set, but not modify, +the definition of a grob. For this reason, there is a more advanced +mechanism: you can add a property on top of an existing definition, or +remove a property: @code{\override} adds a settings, @code{\revert} +removes that setting. + +@lilypond[verbatim] +c'4 \property Voice.Stem \override #'thickness = #4.0 +c'4 \property Voice.Stem \revert #'thickness +c'4 +@end lilypond + +For the digirati, the grob description is an Scheme association +list. Since it is singly linked, we can treat it as a stack, and +@code{\override} and @code{\revert} are just push and pop +operations. This pushing and popping is also used for overriding automatic +beaming settings. + +If you revert a setting which was not set in the first place, then it +has no effect. However, if the setting was set as a system default, it +may remove the default value, and this may give surprising results, +including crashes. In other words, if you use @code{\override} and +@code{\revert}, be sure to balance the overrides and reverts. + +If balancing them is too much work, use the @code{\set} shorthand. It +performs a revert followed by an override: +@example +\property Voice.Stem \set #'thickness = #2.0 +@end example + +Formally the syntax for these constructions is +@example +\property @var{context}.@var{grobname} \override @var{symbol} = @var{value} +\property @var{context}.@var{grobname} \set @var{symbol} = @var{value} +\property @var{context}.@var{grobname} \revert @var{symbol} +@end example +Here @var{symbol} is a Scheme expression of symbol type, @var{context} +and @var{grobname} are strings and @var{value} is a Scheme expression. + +@refbugs + +LilyPond will hang or crash if @var{value} contains cyclic references. + + + +@node Tuning per grob +@subsection Tuning per grob + +@cindex \outputproperty + +A second way of tuning grobs is the more arcane @code{\outputproperty} +feature. +Syntax is as follows +@example +\outputproperty @var{predicate} @var{symbol} = @var{value} +@end example +Here @code{predicate} is a Scheme function taking a grob argument, and +returning a boolean. This statement is processed by the +@code{Output_property_engraver}. It instructs the engraver to feed all +grobs that it sees to @var{predicate}. Whenever the predicate returns +true, the grob property @var{symbol} will be set to @var{value}. + +You will need to combine this statement with @code{\context} to select +the appropriate context to apply this to. + +If possible, avoid this feature: the semantics are not very clean, and +the syntax and semantics are up for rewrite. + +Here are some random examples: + +@lilypond[fragment,verbatim,singleline] +\relative c'' { c4 + \context Staff \outputproperty + #(make-type-checker 'note-head-interface) + #'extra-offset = #'(0.5 . 0.75) + } +@end lilypond + +@cindex @code{extra-offset} + +This selects all note heads occurring at current staff level, and sets +the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting +them up and right. + +Move the text "m.d.", but not the fingering instruction "2". +@lilypond[verbatim,singleline] +#(define (make-text-checker text) + (lambda (grob) (equal? text (ly-get-grob-property grob 'text)))) + +\score { + \notes\relative c''' { + \property Voice.Stem \set #'direction = #1 + \outputproperty #(make-text-checker "m.d.") + #'extra-offset = #'(-3.5 . -4.5) + a^2^"m.d." + } +} +@end lilypond + + + + +@node What to tune? +@subsection What to tune? + +This all tells you how to tune grobs, but what variables are there? The +question is not answered in this manual (although you may encounter +some examples.). + +Grob properties are tied directly to the implementation of LilyPond, and +they are thus a moving target. Documentation of such variables are part +of the generated documentation: this documentation is generated from the +sourcecode of lily for each version, so it is usually mch more up to +date than this manual. It should be available from the same place where +you got this manual. + +To decide how to tune a grob, you need to find the following information +@itemize @bullet +@item +which grob to modify +@item +which property to modify +@item +which context the grob comes from. +@end itemize + +Included with the automatically generated documentation is a master list +of grobs. Each one can be clicked, taking you to a overview of the +available properties. + +There is also a master list of contexts. Clicking each takes you to an +overview of the context, listing which grob types are created there. + + +@node Font selection +@subsection Font selection + +Most graphics in LilyPond are composed of characters of fonts. You can +alter the characteristics of the font by setting certain grob +properties. The mechanism that is used for this resembles LaTeX's New +Font Selection Scheme. Within this scheme, a font is entirely +characterized by its font name. + +For each grob that uses fonts (in other words, each grob that supports +@code{font-interface}) a font-name must be selected before it can be +printed. The font name is selected by looking at a number of grob +properties: + +@table @code +@item font-family + The general class of the typeface. Supported are roman (Computer +Modern), braces (for piano staff braces), music (the standard music +font), dynamic (font for dynamic signs) and typewriter + +@item font-shape + A symbol indicating the shape of the font, a finer gradation than + font-family. Choices are italic and upright +@item font-series + Symbol indicating the serie of the font. Series form a finer gradation + than font-shape. Choices are medium and bold. + +@item font-relative-size + A number indicating the size relative the standard size. For example, + with 20pt staff height, relative size -1 corresponds to 16pt staff + height, and relative size +1 corresponds to 23 pt staff height. + +@item font-design-size +A number indicating the design size of the font. + +This is a feature of the Computer Modern Font: each point size has a +slightly different design. Smaller design sizes are relatively wider, +which enhances readability. Scalable type faces such TrueType and Adobe +Type1 usually come as ``one design fits all sizes''. + +@item font-name + The name of the font, without the design size, eg. @code{cmr}, +@code{cmti}, etc. Setting this overrides font-family, font-shape and +font-series. + +@end table + +The font is selected by taking the first font that satisfies all +qualifiers specified. You can override any of these fields through +@code{\override} and @code{\revert}. The special value @code{*} matches +any value for that qualifier. + +@example + \property Lyrics.LyricText \override #'font-series = #'bold + \property Lyrics.LyricText \override #'font-shape = #'* +@end example + +@cindex @code{font-style} + +There are also pre-cooked font selection qualifiers. These are selected +through the grob property @code{font-style}. For example, the style +@code{finger} selects family @code{number} and relative size @code{-3}. +Styles available include: volta, finger, tuplet, timesig, mmrest, +script, large, Large and dynamic. + +The style sheets and tables for selecting fonts are located in +@file{scm/font.scm}. Refer to this file for more information. + +@refbugs + +Relative size is not linked to any real size. There is no mechanism to +select magnifications of fonts, meaning that you can not scale fonts +continuoussly. There is no style sheet provided for other fonts besides +the @TeX{} family. + +@cindex font selection +@cindex font magnification +@cindex @code{font-interface} + +@refbugs + + +@node Text markup +@subsection Text markup +@cindex text markup +@cindex markup text + +LilyPond has an internal mechanism to typeset texts. You can +form text markup expressions by composing scheme expressions +in the following way. + +@lilypond[verbatim, singleline] + \relative c' { + \fatText + a^#"upright" + b_#'(bold "bold") + c^#'(italic "italic") + d_#'((bold italic) "ff") + e^#'(dynamic "ff") + f_#'(lines "one" (bold "two")) + g^#'(music "noteheads-2" "flags-u3") + } +@end lilypond + +Normally, the Scheme markup text is stored in the @code{text} property +of a grob. Formally, it is defined as follows: + +@example +text: string | (head? text+) +head: markup | (markup+) +markup-item: property | abbrev +property: (@var{key} . @var{value}) +abbrev: @code{rows lines roman music bold italic named super sub text} + @code{finger volta timesig mmrest mark script large Large dynamic} +@end example + +The markup is broken down and converted into a list of grob properties, +which are prepended to the property list. The @var{key}-@var{value} +pair is a grob property. + +The following abbreviations are currently defined: + +@table @code +@item rows +horizontal mode: set all text on one line (default) +@item lines + vertical mode: set every text on new line +@item roman + select roman font +@item music + select feta font +@item bold + select bold series +@item italic + select italic shape +@item named + lookup by character name +@item text + plain text lookup (by character value) +@item super + superscript +@item sub + subscript +@item finger + select fingering number fontstyle +@item volta + select volta number fontstyle +@item timesig + select time signature number fontstyle +@item mmrest + select multi measure rest number fontstyle +@item mark + select mark number fontstyle +@item script + select scriptsize roman fontstyle +@item large + select large roman fontstyle +@item Large + select Large roman fontstyle +@item dynamic + select dynamics fontstyle +@end table + +It is possible to use @TeX{} commands in the strings, but this should be +avoided because this makes it impossible for LilyPond to compute the +exact length of the string, which may lead to collisions. Also, @TeX{} +commands won't work with direct postscript output. + +@c . {Page layout} +@node Page layout +@section Page layout +@cindex Page layout + +@menu +* Paper block:: +* Paper variables:: +* Font Size:: +* Paper size:: +* Line break:: +* Page break:: +@end menu + +@c . {Paper block} +@node Paper block +@subsection Paper block +@cindex Paper block + +The most important output definition is the @code{\paper} block, for +music notation. The syntax is + +@example + @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} +@end example + +where each of the items is one of + +@itemize @bullet + @item An assignment. The assignment must be terminated by a + semicolon. + + @item A context definition. See @ref{Notation Contexts} for + more information on context definitions. + + @item \stylesheet declaration. Its syntax is + @example + \stylesheet @var{alist} + @end example + + See @file{scm/font.scm} for details of @var{alist}. + @item an \elementdescriptions declaration. + @example + \elementdescriptions @var{alist} + @end example + See @file{scm/grob-description.scm} for details of @var{alist}. + +@end itemize + +@c . {Paper variables} +@node Paper variables +@subsection Paper variables +@cindex Paper variables + +The paper block has some variables you may want to use or change: + +@table @code +@cindex @code{indent} + @item @code{indent} + The indentation of the first line of music. +@cindex @code{staffspace} + + @item @code{staffspace} + The distance between two staff lines, calculated from the center + of the lines. If you want scale independent output, then you should +use either this or @code{stafflinethickness} + as a unit for distances you modify. + +@cindex @code{linewidth} + @item @code{linewidth} + Sets the width of the lines. + +If set to a negative value, a single + unjustified line is produced. + +@cindex @code{textheight} + + @item @code{textheight} + Sets the total height of the music on each page. Only used by +@code{ly2dvi}. + +@cindex @code{interscoreline} + + @item @code{interscoreline} + Sets the spacing between systems. +Not set by default. +@cindex @code{interscorelinefill} + + + + @item @code{interscorelinefill} + If set to a positive number, the distance between the score + lines will stretch in order to fill the full page. In that + case @code{interscoreline} specifies the minimum spacing. + + Not set by default. + + +@cindex @code{stafflinethickness} + + @item @code{stafflinethickness} + Determines the thickness of staff lines, and also acts as a scaling + parameter for other line thicknesses. +@end table + + + +@c . {Font size} +@node Font Size +@subsection Font size +@cindex font size + +The Feta font provides musical symbols at six different sizes. These +fonts are 11 point, 13 point, 16 point, 20 point, +23 point, and 26 point. The point size of a font is the +height of the five lines in a staff when displayed in the font. + +Definitions for these sizes are the files @file{paperSZ.ly}, where +@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of +these files, the identifiers @code{paperEleven}, @code{paperThirteen}, +@code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and +@code{paperTwentysix} are defined respectively. The default +@code{\paper} block is also set. + +The font definitions are generated using a Scheme function. For more +details, see the file @file{font.scm}. + + + +@c . {Paper size} +@node Paper size +@subsection Paper size +@cindex Paper size + +@cindex paper size +@cindex page size +@cindex @code{papersize} + +To change the paper size, you must first set the +@code{papersize} variable at top level. Set it to +the strings @code{a4}, @code{letter}, or @code{legal}. After this +specification, you must set the font as described above. If you want +the default font, then use the 20 point font. The new paper size will +not take effect if the font is not loaded and selected afterwards. + +@example + papersize = "a4" + \include "paper16.ly" + + \score @{ + ... + \paper @{ \paperSixteen @} + @} +@end example + +The file @code{paper16.ly} will now include a file named @file{a4.ly}, which +will set the paper variables @code{hsize} and @code{vsize} (used by +@code{ly2dvi}) -@node Notation conversion specifics, , , Reference Manual -@section Notation conversion specifics -@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]. +@c . {Line break} +@node Line break +@subsection Line break -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}. +@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}. This will force a line break at this +point. Do remember that line breaks can only occur at places where there +are barlines. If you want to have a line break where there is no +barline, you can force an invisible barline by entering @code{\bar "";}. -@cindex chord names +Similarly, @code{\noBreak} forbids a line break at a certain point. -@cindex chords +@cindex @code{\penalty} + +The @code{\break} and @code{\noBreak} commands are defined in terms of +the penalty command: +@example + \penalty @var{int} @code{;} +@end example -@cindex printing!chord names +This encourages or discourages LilyPond to make a line break at this +point. -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. +@refbugs -@quotation +The scaling of the @code{\penalty} argument is not well-defined. The +command is rather kludgy, and slated for rewriting. + +@c . {Page break} +@node Page break +@subsection Page break + +@cindex page breaks +@cindex breaking pages + + +Page breaks are normally computed by @TeX{}, so they are not under +direct control of LilyPond. However, you can insert a commands into the +@file{.tex} output to instruct @TeX{} where to break pages. For more +details, see the example file @file{input/test/between-systems.ly} + + + + + +@c . {Sound} +@node Sound +@section Sound +@cindex Sound + +LilyPond can produce MIDI output. The performance lacks lots of +interesting effects, such as swing, articulation, slurring, tieing, +etc., but it is good enough for proof-hearing the music you enter. + +Dynamics and tempo changes are interpreted. + +[TODO: mention volume control/Instrument Equaliser] + + +@refbugs + +It is currently not possible to use the percussion channel (generally +channel 10 of a MIDI file). + +@menu +* MIDI block:: +* MIDI instrument names:: +@end menu + +@c . {MIDI block} +@node MIDI block +@subsection MIDI block +@cindex MIDI block + + +The MIDI block is analogous to the paper block, but it is somewhat +simpler. The @code{\midi} block can contain: +@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}. + + +@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 list in +@ref{MIDI instruments}. + +@refbugs + +If the selected string does not exactly match, then LilyPond uses the +default piano. It is not possible to select an instrument by number. + + + + + + + + + +@c . {Music entry} +@node Music entry +@section Music entry +@cindex Music entry +@menu +* Relative:: +* Bar check:: +* Point and click:: +@end menu + +One of the applications of LilyPond is to enter music from existing +written or printed material. When you're doing this kind of copying +work, you can easily make mistakes. This section deals with tricks and +features that help you enter music, and find and correct mistakes. + +@c . {Relative} +@node Relative +@subsection Relative +@cindex Relative +@cindex relative octave specification -@mudela[fragment,verbatim] -< - \context ChordNames { - \chords{a b c} \notes{ } +Octaves are specified by adding @code{'} and @code{,} to pitch names. +When you copy existing music, it is easy to accidentally put a pitch in +the wrong octave and hard to find such an error. To prevent these +errors, LilyPond features octave entry. + +@cindex @code{\relative} +@example + \relative @var{startpitch} @var{musicexpr} +@end example + +The octave of notes that appear in @var{musicexpr} are calculated as +follows: If no octave changing marks are used, the basic interval +between this and the last note is always taken to be a fourth or less. + The octave changing marks @code{'} and @code{,} can then +be added to raise or lower the pitch by an extra octave. Upon entering +relative mode, an absolute starting pitch must be specified that will +act as the predecessor of the first note of @var{musicexpr}. + +This distance is determined without regarding accidentals: a +@code{fisis} following a @code{ceses} will be put above the +@code{ceses}. + +Entering music that changes octave frequently is easy in relative mode. +@lilypond[fragment,singleline,verbatim,center] + \relative c'' { + b c d c b c bes a } - \context Staff \notes { - a b c' d' e' +@end lilypond + +And octave changing marks are used for intervals greater than a fourth. +@lilypond[fragment,verbatim,center] + \relative c'' { + c g c f, c' a, e'' } +@end lilypond + +If the preceding item is a chord, the first note of the chord is used +to determine the first note of the next chord. But other notes +within the second chord are determined by looking at the immediately +preceding note. + +@lilypond[fragment,verbatim,center] + \relative c' { + c + + } -> +@end lilypond +@cindex @code{\notes} -@end mudela -@end quotation +The pitch after the @code{\relative} contains a notename. To parse +the pitch as a notename, you have to be in note mode, so there must +be a surrounding @code{\notes} keyword (which is not +shown here). -LilyPond 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: +The relative conversion will not affect @code{\transpose}, +@code{\chords} or @code{\relative} sections in its argument. If you +want to use relative within transposed music, you must place an +additional @code{\relative} inside the @code{\transpose}. -@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}: +@c . {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check -@mudela[fragment,verbatim,center] - < - \property Score.chordInversion = ##t - \context ChordNameVoice \notes { - - } - \context Thread \notes { - - } - > -@end mudela +@cindex bar check +@cindex @code{barCheckNoSynchronize} +@cindex @code{|} +Whenever a bar check is encountered during interpretation, a warning +message is issued if it doesn't fall at a measure boundary. This can +help you find errors in the input. Depending on the value of +@code{barCheckNoSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. -@cindex lyrics +A bar check is entered using the bar symbol, @code{|} -@cindex printing!lyrics -@node lyricprint, , , Reference Manual -Lyric syllables must be interpreted within a @code{Lyrics} context +@c . {Point and click} +@node Point and click +@subsection Point and click -@cindex context!Lyrics - for printing them. +Point and click lets you find notes in the input by clicking on them in +the Xdvi window. This makes it very easy to find input that causes some +error in the sheet music. -Here is a full example: +To use it, you need the following software -@quotation +@itemize +@item +@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain +Xdvi} version 22.36 or newer. -@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 - } - > -} + Note that most @TeX{} distributions ship with xdvik, which is a + different and less well maintained program. To find out which xdvi you + are running, try @code{xdvi --version} or @code{xdvi.bin --version}. +@item emacs +@end itemize -@end mudela -@end quotation -You may want a continuous line after the syllables to show melismata. -To achieve this effect, add a `@code{__}' lyric as a separate word -after the lyric to be extended. This will create an extender, a line -that extends over the entire duration of the lyric. This line will -run all the way to the start of the next lyric, so you may want to -shorten it by using a blank lyric (using `@code{_}'). +Add one these lines to the top of your .ly file. The first one is for +line location only. The second one is more convenient, but requires +patching @code{emacsclient}. -@quotation +@example +#(set! point-and-click line-location) +#(set! point-and-click line-column-location) +@end example -@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 __ - } - > -} +In the emacs startup file (usually @file{~/.emacs}), add the following +@example +(server-start) +@end example -@end mudela -@end quotation +If you want emacs to jump to the exact spot (and not just the line) on a +click, you must enable column positioning. To do so, you need to patch +emacsclient. Apply @file{emacsclient.patch} (included with the source +package) to @file{emacsclient.c} and @file{server.el} from the emacs +source code. Recompile and stick the recompiled emacsclient into a bin +directory, and put @file{server.el} into a elisp directory +(eg. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs} +init file, before invoking server-start. - -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: +@example + (setq load-path (cons "~/usr/share/emacs" load-path)) +@end example -@quotation -@mudela[verbatim] -\score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va4 -- der Ja -- cob | Va -- der Ja -- cob | - Slaapt gij nog?2 | Slaapt4 gij nog?2 - } - > -} +Xdvi must be configured to use the emacs editor. Before starting, set +the environment variable @code{XEDITOR} to +@example +emacsclient --no-wait +%c:%l %f +@end example +Xdvi also must be configured to find the fonts. Refer to the +xdvi documentation for more information. -@end mudela -@end quotation +When viewing, control-mousebutton 1 will take you to the originating +line and column. Control-mousebutton 2 will show all clickable boxes. + +@refbugs + +When you convert the TeX file to PostScript using dvips, dvips +will complain about not finding @code{src:X:Y} files. Those complaints are +harmless, and can be ignored. +@node Interpretation context +@section Interpretation context + +@menu +* Notation Contexts:: +* Creating contexts:: +* Default contexts:: +* Context properties:: +* Changing context definitions:: +* Defining new contexts:: +@end menu + -@node Notation Contexts, , , Reference Manual -@section Notation Contexts +@c . {Notation Contexts} +@node Notation Contexts +@subsection Notation Contexts @cindex notation contexts -Notation contexts are objects that only exist during a run of -LilyPond. During the interpretation phase of LilyPond, the Music -expression contained in a @code{\score} block is interpreted in time -order. This is the order in which humans read, play, and write -music. +Notation contexts are objects that only exist during a run of LilyPond. +During the interpretation phase of LilyPond (when it prints +"interpreting music"), the music expresiion in a @code{\score} block is +interpreted in time order. This is the same order that humans hear and +play music. -A context is an object that holds the reading state of the -expression; it contains information like +During this interpretation, the notation context is holds the state for +the current point within the music. It contains information like @itemize @bullet - @item What notes are playing at this point? - @item What symbols will be printed at this point? - @item 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 What is the current key signature, time signature, point within the measure, etc.? @end itemize @@ -2131,665 +3387,890 @@ multiple voices at any point), a @code{Staff} context is contained in a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because these can all contain multiple staffs). -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called playing 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: - -@example - @example -\score @{ \notes < c4 > @} -@end example +Contexts associated with sheet music output are called @emph{notation +contexts}, those for sound output are called performance contexts. -@end example -The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score} -context. When the note `@code{c4}' itself is interpreted, a set of -contexts is needed that will accept notes. The default for this is a -@code{Voice} context, contained in a @code{Staff} context. Creation of -these contexts results in the staff being printed. +@node Creating contexts +@subsection Creating contexts +@cindex @code{\context} +@cindex context selection -@cindex context +Contexts for a music expression can be selected manually, using the +following music expression. -You can also create contexts manually, and you probably have to do so -if you want to typeset complicated multiple part material. If a -`@code{\context} @var{name} @var{musicexpr}' expression is encountered -during the interpretation phase, the @var{musicexpr} argument will be -interpreted with a context of type @var{name}. If you specify a name, -the specific context with that name is searched. +@example + \context @var{contexttype} [= @var{contextname}] @var{musicexpr} +@end example -If a context of the specified type and name can not be found, a new -one is created. For example, +This instructs lilypond to interpret @var{musicexpr} within the context + of type @var{contexttype} and with name @var{contextname}. If this +context does not exist, it will be created. @quotation -@mudela[verbatim] +@lilypond[verbatim,singleline] \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 third quarter, @code{another} is removed. -Almost all music expressions inherit their interpretation context -from their parent. In other words, suppose that the syntax for a -music expression is + +@node Default contexts +@subsection Default contexts + +Most music expressions don't need @code{\context}: they inherit the +notation context from their parent. Each note is a music expression, and +as you can see in the following example, only the sequential music +enclosing the three notes has an explicit context. + +@lilypond[verbatim,singleline] +\score { \notes \context Voice = goUp { c'4 d' e' } } +@end lilypond + +There are some quirks that you must keep in mind when dealing with +defaults: + +First, every top-level music is interpreted by the Score context, in other +words, you may think of @code{\score} working like +@example + \score @{ + \context Score @var{music} + @} +@end example + +Second, sequential music follows the contexts of its +``children''. Consider the following example. + +@lilypond[verbatim, singleline] +\score { \context Score \notes { c'4 ( d' )e' } } +@end lilypond + +The sequential music is interpreted by the Score context initially +(notice that the @code{\context} specification is redundant), but when a +note is encountered, contexts are setup to accept that note. In this +case, a Thread, Voice and Staff are created. The rest of the sequential +music is also interpreted with the same Thread, Voice and Staff context, +putting the notes on the same staff, in the same voice. + +This is a convenient mechanism, but do not expect opening chords to work +without @code{\context}. For every note, a separate staff is +instantiated. + +@lilypond[verbatim, singleline] +\score { \notes } +@end lilypond + +Of course, if the chord is preceded by a normal note in sequential +music, the chord will be interpreted by the Thread of the preceding +note: +@lilypond[verbatim,singleline] +\score { \notes { c'4 } } +@end lilypond + + + +@node Context properties +@subsection Context properties + +Notation contexts can be modified from within the @file{.ly} file. The +following music expression does that job: + +@cindex @code{\property} +@example + \property @var{contextname}.@var{propname} = @var{value} +@end example + +Sets the @var{propname} property of the context @var{contextname} to the +specified Scheme expression @var{value}. All @var{propname} and +@var{contextname} are strings, which are typically unquoted. + +Properties that are set in one context are inherited by all of the +contained contexts. This means that a property valid for the +@code{Voice} context can be set in the @code{Score} context (for +example) and thus take effect in all @code{Voice} contexts. + +Properties can be unset using the following expression: +@example + \property @var{contextname}.@var{propname} \unset +@end example + +This removes the definition of @var{propname} in @var{contextname}. If +@var{propname} was not defined in @var{contextname} (but was inherited +from a higher context), then this has no effect. + + +@refbugs + +@code{\property \unset} is not the inverse of @code{\property \set} + + + + +@c . {Context definitions} +@node Changing context definitions +@subsection Changing context definitions + +@cindex context definition +@cindex translator definition + +The most common way to define a context is by extending an existing +context. You can change an existing context from the paper block, by +first initializing a translator with an existing context identifier: +@example +\paper @{ + \translator @{ + @var{context-identifier} + @} @} +@end example +Then you can add engravers, remove engravers. +The syntax for these operations are respectively @example + \remove @var{engravername} + \consists @var{engravername} +@end example + - \keyword @var{musicexpr1} @var{musicexpr2} @dots{} +Here @var{engravername} is a string, the name of an engraver in the +system. +@example + @var{propname} = @var{value} @end example -When the interpretation of this music expression starts, the context -for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total + +@lilypond[verbatim,singleline] +\score { \notes { + c'4 c'4 } + \paper { + \translator { \StaffContext + \remove Clef_engraver; + } } } +@end lilypond + +@cindex engraver + +You can also set properties in a translator definition. The syntax is as +follows: + +@var{propname} is a string and @var{value} is a Scheme expression. +@example + @var{propname} = @var{value} + @var{propname} \set @var{symbol} = @var{value} + @var{propname} \override @var{symbol} = @var{value} + @var{propname} \revert @var{symbol} + +@end example + +These type of property assignments happen before interpretation starts, +so a @code{\property} expression will override any predefined settings. + + + To simplify editing translators, all standard contexts have standard +identifiers called @var{name}@code{Context}, e.g. @code{StaffContext}, +@code{VoiceContext}. + +@node Defining new contexts +@subsection Defining new contexts + +If you want to build a context from scratch, you must also supply the +following extra information: +@itemize @bullet + @item A name, specified by @code{\name @var{contextname};}. + + @item A cooperation module. This is specified by @code{\type +@var{typename};}. +@end itemize + +This is an example: +@example +\translator @code{ + \type "Engraver_group_engraver"; + \name "SimpleStaff"; + \alias "Staff"; + \consists "Staff_symbol_engraver"; + \consists "Note_head_engraver"; + \consistsend "Axis_group_engraver"; +}@ +@end example + +Basic building blocks of translation are called engravers; they are +special C++ classes. + +The argument of @code{\type} is the name for a special engraver that +handles cooperation between simple engravers such as +@code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives +for this engraver are the following: +@table @code +@cindex @code{Engraver_group_engraver} + @item @code{Engraver_group_engraver} + The standard cooperation engraver. + +@cindex @code{Score_engraver} + + @item @code{Score_engraver} + This is cooperation module that should be in the top level context, +and only the toplevel context. + +@cindex @code{Grace_engraver_group} + + @item @code{Grace_engraver_group} + This is a special cooperation module (resembling + @code{Score_engraver}) that is used to created an embedded + `miniscore'. +@end table + +Other modifiers are + +@itemize @bullet + @item @code{\alias} @var{alternate-name} @code{;} + This specifies a different name. In the above example, +@code{\property Staff.X = Y} will also work on @code{SimpleStaff}s + + @item @code{\consistsend} @var{engravername} @code{;} + Analogous to @code{\consists}, but makes sure that + @var{engravername} is always added to the end of the list of + engravers. + + Some engraver types need to be at the end of the list; this + insures they are put there, and stay there, if a user adds or + removes engravers. This command is usually not needed for + end-users. + + @item @code{\accepts} @var{contextname} @code{;} + Add @var{contextname} to the list of context this context can + contain. The first listed context is the context to create by + default. + + @item @code{\denies}. The opposite of @code{\accepts}. Added for +completeness, but is never used in practice. + + + @item @code{\name} @var{contextname} @code{;} + This sets name of the context, e.g. @code{Staff}, @code{Voice}. If + the name is not specified, the translator won't do anything. +@end itemize -Lastly, you may wonder, why this: +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 \relative c'' @{ - c4 d4 e4 + \notes @{ + @dots{} + @} + \paper @{ + \translator @{ \foo @dots{} @} @} @} @end example @end quotation -doesn't result in this: - -@mudela[] - - \score { - \notes \relative c'' { - - } - } -@end mudela +@cindex paper types, engravers, and pre-defined translators -For the @code{c4}, a default @code{Staff} (with a contained -@code{Voice}) context is created. After the @code{c4} ends, no -music refers to this default staff, so it would be ended, with the -result shown. To prevent this inconvenient behavior, the context to -which the sequential music refers is adjusted during the -interpretation. So after the @code{c4} ends, the context of the -sequential music is also the default @code{Voice} context. -The @code{d4} gets interpreted in the same context -as @code{c4}. + -These are the contexts supplied with the package. They are defined -in the initialization file @file{ly/engraver.ly}. -@table @samp -@end table +@c . {Syntactic details} +@node Syntactic details +@section Syntactic details +@cindex Syntactic details +This section describes details that were too boring to be put elsewhere. +@menu +* Top level:: +* Identifiers:: +* Music expressions:: +* Manipulating music expressions:: +* Assignments:: +* Lexical modes:: +* Ambiguities:: +@end menu -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@code{Voice} context can be set in the @code{Score} context (for -example) and thus take effect in all @code{Voice} contexts. +@c . {Top level} +@node Top level +@subsection Top level +@cindex Top level -Properties can be preset within the @code{\translator} block -corresponding to the appropriate context. In this case, the syntax -is +This section describes what you may enter at top level. -@example - @var{propname} @code{=} @var{value} -@end example +@c . {Score} +@subsubsection Score +@cindex Score -This assignment happens before interpretation starts, so a -@code{\property} expression will override any predefined settings. +@cindex score definition -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 output is generated combining a music expression with an output +definition. A score block has the following syntax: -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}. +@example + \score @{ @var{musicexpr} @var{outputdefs} @} +@end example -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. +@var{outputdefs} are zero or more output definitions. If none is +supplied, the default @code{\paper} block will be added. -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 . {Default output} +@subsubsection Default output -@cindex output +Default values for the @code{\paper} and @code{\midi} block are set by +entering such a block at top-level. -@cindex notation output +@c . {Header} +@subsubsection Header +@cindex Header +@cindex @code{\header} -@cindex output definition -@node paper, , , Reference Manual +A header describes bibilographic information of the file's contents. It +can also appear in a @code{\score} block. Tools like @code{ly2dvi} can +use this information for generating titles. Key values that are used by +@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, +metre, arranger, piece and tagline. -The most important output definition is the @code{\paper} block, for -music notation. The syntax is +@cindex @code{ly2dvi} +The syntax is @example - - @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} + \header @{ @var{key1} = @var{val1}; + @var{key2} = @var{val2}; @dots{} @} @end example -where each of the items is one of +It is customary to put the @code{\header} at the top of the file. -@itemize @bullet - @item An assignment. The assignment must be terminated by a - semicolon. See section XREF-papervars [FIXME] for information on - paper variables. +@subsubsection Default output - @item A context definition. See section XREF-contextdefs [FIXME] for - more information on context definitions. +A @code{\midi} or @code{\paper} block at top-level sets the default - @item - FIXME now in SCM +paper block for all scores that lack an explicit paper block. - A margin shape declaration. The syntax is +@c . {Identifiers} +@node Identifiers +@subsection Identifiers +@cindex Identifiers - @example +All of the information in a LilyPond input file, is represented as a +Scheme value. In addition to normal Scheme data types (such as pair, +number, boolean, etc.), LilyPond has a number of specialized data types, - \shape @var{indent1}@code{,} @var{width1}@code{,} - @var{indent2}@code{,} @var{width2} @dots{} @code{;} - @end example +@itemize @bullet +@item Input +@item c++-function +@item Music +@item Identifier +@item Translator_def +@item Duration +@item Pitch +@item Score +@item Music_output_def +@item Moment (rational number) +@end itemize - @keyindex{shape} +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. - 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. +@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}) - @item \stylesheet declaration. Its syntax is +@end itemize - @example - \stylesheet @var{scm} - @end example +@node Music expressions +@subsection Music expressions - See font.scm for details of @var{scm} -@end itemize +@cindex music expressions +Music in LilyPond is entered as a music expression. Notes, rests, lyric +syllables are music expressions, and you can combine music expressions +to form new ones, for example by enclosing a list of expressions in +@code{\sequential @{ @}} or @code{< >}. In the following example, a +compound expression is formed out of the quarter note @code{c} and a +quarter note @code{d}: +@example +\sequential @{ c4 d4 @} +@end example -@cindex changing font size and paper size +@cindex Sequential music +@cindex @code{\sequential} +@cindex sequential music +@cindex @code{<} +@cindex @code{>} +@cindex Simultaneous music +@cindex @code{\simultaneous} -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. +The two basic compound music expressions are simultaneous and +sequential music. -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. +@example + \sequential @code{@{} @var{musicexprlist} @code{@}} + \simultaneous @code{@{} @var{musicexprlist} @code{@}} +@end example +For both, there is a shorthand: +@example + @code{@{} @var{musicexprlist} @code{@}} +@end example +for sequential and +@example + @code{<} @var{musicexprlist} @code{>} +@end example +for simultaneous music. +In principle, the way in which you nest sequential and simultaneous to +produce music is not relevant. In the following example, three chords +are expressed in two different ways: -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. +@lilypond[fragment,verbatim,center] + \notes \context Voice { + + < { a b c' } { c' d' e' } > + } +@end lilypond +Other compound music expressions include +@example + \repeat @var{expr} + \transpose @var{pitch} @var{expr} + \apply @var{func} @var{expr} + \context @var{type} = @var{id} @var{expr} + \times @var{fraction} @var{expr} +@end example -@cindex paper variables -@node Paper variables, , , Reference Manual +@c . {Manipulating music expressions} +@node Manipulating music expressions +@subsection Manipulating music expressions -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. +The @code{\apply} mechanism gives you access to the internal +representation of music. You can write Scheme-functions that operate +directly on it. The syntax is +@example + \apply #@var{func} @var{music} +@end example +This means that @var{func} is applied to @var{music}. The function +@var{func} should return a music expression. + +This example replaces the text string of a script. It also shows a dump +of the music it processes, which is useful if you want to know more +about how music is stored. +@lilypond[verbatim] +#(define (testfunc x) + (if (equal? (ly-get-mus-property x 'text) "foo") + (ly-set-mus-property x 'text "bar")) + ;; recurse + (ly-set-mus-property x 'elements + (map testfunc (ly-get-mus-property x 'elements))) + (display x) + x +) +\score { \notes + \apply #testfunc { c4_"foo" } +} +@end lilypond + +For more information on what is possible, see the @ref{Tricks} and the +automatically generated documentation. + + +Directly accessing internal representations is dangerous: the +implementation is subject to changes, so you should avoid this feature +if possible. + + -Nevertheless, here are some variables you may want to use or change: +@c . {Span requests} +@menu +* Span requests:: +@end menu -@table @samp - @item @code{indent}@indexcode{indent} - The indentation of the first line of music. +@node Span requests +@subsubsection Span requests +@cindex Span requests - @item @code{staffspace}@indexcode{staffspace} - The distance between two staff lines, calculated from the center - of the lines. You should use either this or @code{rulethickness} - as a unit for distances you modify. - - @item @code{linewidth}@indexcode{linewidth} - Sets the width of the lines. If set to -1.0, a single - unjustified line is produced. +Notational constructs that start and end on different notes can be +entered using span requests. The syntax is as follows: - @item @code{textheight}@indexcode{textheight} - Sets the total height of the music on each page. Only used by - ly2dvi. - @item @code{interscoreline}@indexcode{interscoreline} - Sets the spacing between the score lines. Defaults to 16 pt. +@example + \spanrequest @var{startstop} @var{type} +@end example - @item @code{interscorelinefill}@indexcode{interscorelinefill} - If set to a positive number, the distance between the score - lines will stretch in order to fill the full page. In that - case @code{interscoreline} specifies the minimum spacing. - Defaults to 0. - @item @code{stafflinethickness}@indexcode{stafflinethickness} - Determines the thickness of staff and bar lines. -@end table +@cindex @code{\start} +@cindex @code{\stop} +This defines a spanning request. The @var{startstop} parameter is either +-1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that +describes what should be started. Much of the syntactic sugar is a +shorthand for @code{\spanrequest}, for example, -@node contextdefs, , , Reference Manual +@lilypond[fragment,verbatim,center] + c'4-\spanrequest \start "slur" + c'4-\spanrequest \stop "slur" +@end lilypond -@cindex context definition +Among the supported types are @code{crescendo}, @code{decrescendo}, +@code{beam}, @code{slur}. This is an internal command. Users are +encouraged to use the shorthands which are defined in the initialization +file @file{spanners.ly}. -A notation contexts is defined by the following information -@enumerate i - @item A name. +@c . {Assignments} +@node Assignments +@subsection Assignments +@cindex Assignments - @item The LilyPond modules that do the actual conversion of music to - notation. Each module is a so-called - @emph{engraver} -@cindex engraver -. +Identifiers allow objects to be assigned to names during the parse +stage. To assign an identifier, you use @var{name}@code{=}@var{value} +and to refer to an identifier, you preceed its name with a backslash: +`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of +the input-types listed above. Identifier assignments can appear at top +level in the LilyPond file, but also in @code{\paper} blocks. - @item How these modules should cooperate, i.e. which ``cooperation - module'' should be used. This cooperation module is a special - type of engraver. +Semicolons are forbidden after top level assignments, but mandatory in +other places. The rules about semicolons and assignments are very +confusing, but when LilyPond input evolves more towards Scheme, we hope +that this problem will grow smaller. - @item What other contexts the context can contain, +An identifier can be created with any string for its name, but you will +only be able to refer to identifiers whose names begin with a letter, +being entirely alphabetical. It is impossible to refer to an identifier +whose name is the same as the name of a keyword. - @item What properties are defined. -@end enumerate +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. -A context definition has this syntax: +@example +foo = \foo * 2.0 +@end example +When an identifier is referenced, the information it points to is +copied. For this reason, an identifier reference must always be the +first item in a block. @example +\paper @{ + foo = 1.0 + \paperIdent % wrong and invalid +@} - \translator @code{@{} - @var{translatorinit} @var{translatormodifierlist} - @code{@}} +\paper @{ + \paperIdent % correct + foo = 1.0 @} @end example -@var{translatorinit} can be an identifier or of the form +@c . {Lexical modes} +@node Lexical modes +@subsection Lexical modes +@cindex Lexical modes +@cindex input mode +@cindex mode, input +@cindex @code{\notes} +@cindex @code{\chords} +@cindex @code{\lyrics} + +To simplify entering notes, lyrics, and chords, LilyPond has three +special input modes on top of the default mode: note, lyrics and chords +mode. These input modes change the way that normal, unquoted words are +interpreted: for example, the word @code{cis} may be interpreted as a +C-sharp, as a lyric syllable `cis' or as a C-sharp major triad +respectively. + +A mode switch is entered as a compound music expressions @example - - \type @var{typename} @code{;} +@code{\notes} @var{musicexpr} +@code{\chords} @var{musicexpr} +@code{\lyrics} @var{musicexpr}. @end example -@var{typename} is one of +In each of these cases, these expressions do not add anything to the +meaning of their arguments. They are just a way to indicate that the +arguments should be parsed in indicated mode. The modes are treated in +more detail in the @ref{Note entry}, @ref{Lyrics} and +@ref{Chords}. -@table @samp - @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver} - The standard cooperation engraver. +You may nest different input modes. - @item @code{Score_engraver}@indexcode{Score_engraver} - This is cooperation module that should be in the top level context. +@c . {Ambiguities} +@node Ambiguities +@subsection Ambiguities +@cindex ambiguities +@cindex grammar - @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group} - This is a special cooperation module (resembling - @code{Score_engraver}) that is used to created an embedded - `miniscore'. -@end table -@var{translatormodifierlist} is a list of items where each item is -one of +The grammar contains a number of ambiguities. We hope to resolve them at +some time. @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. - - 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. - - @item @var{propname} @code{=} @var{value} @code{;} - A property assignment. It is allowed to use reals for - @var{value}. -@end itemize - -In the @code{\paper} block, it is also possible to define translator -identifiers. Like other block identifiers, the identifier can only -be used as the very first item of a translator. In order to define -such an identifier outside of @code{\score}, you must do - -@quotation + @item The assignment -@example -\paper @{ - foo = \translator @{ @dots{} @} -@} -\score @{ - \notes @{ - @dots{} - @} - \paper @{ - \translator @{ \foo @dots{} @} - @} -@} + @example +foo = bar @end example -@end quotation - - -@cindex paper types, engravers, and pre-defined translators - -Some pre-defined identifiers can simplify modification of -translators. The pre-defined identifiers are: - -@table @samp - @item @code{StaffContext}@indexcode{StaffContext} - Default Staff context. - - @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext} - Default RhythmicStaff context. - - @item @code{VoiceContext}@indexcode{VoiceContext} - Default Voice context. - - @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. + can be interpreted as making a string identifier @code{\foo} + containing @code{"bar"}, or a music identifier @code{\foo} + containing the syllable `bar'. - @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext} - Staff context that does not print if it only contains rests. - Useful for orchestral scores.@footnote{Harakiri, also called - Seppuku, is the ritual suicide of the Samourai.} + @item The assignment - @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext} + @example +foo = -6 +@end example - @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext} -@end table + can be interpreted as making an integer identifier + containing -6, or a Request identifier containing the + fingering `6' (with neutral direction). -Using these pre-defined values, you can remove or add items to the -translator: + @item If you do a nested repeat like -@quotation + @quotation @example -\paper @{ - \translator @{ - \StaffContext - \remove Some_engraver; - \consists Different_engraver; - @} -@} +\repeat @dots{} +\repeat @dots{} +\alternative @end example -@end quotation + @end quotation - -@node Sound output, , , Reference Manual -@section Sound output + 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 -The MIDI block is analogous to the paper block, but it is simpler. -The @code{\midi} block can contain: -@cindex MIDI block +@c . {Lexical details} +@node Lexical details +@section Lexical details -@itemize @bullet - @item a @code{\tempo} definition - @item context definitions -@end itemize +Even more boring details, now on lexical side of the input parser. -Assignments in the @code{\midi} block are not allowed. +@menu +* Comments:: +* Direct Scheme:: +* Keywords:: +* Integers:: +* Reals:: +* Strings:: +* Main input:: +* File inclusion:: +* Version information:: +@end menu +@node Comments +@subsection Comments -@cindex context definition +@cindex comments +@cindex block comment +@cindex line comment -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}. +@cindex @code{%} + +A one line comment is introduced by a @code{%} character. +Block comments are started by @code{%@{} and ended by @code{%@}}. +They cannot be nested. + +@node Direct Scheme +@subsection Direct Scheme +@cindex Scheme +@cindex GUILE +@cindex Scheme, in-line code -@cindex MIDI instrument names +LilyPond contains a Scheme interpreter (the GUILE library) for +internal use. In some places Scheme expressions also form valid syntax: +whereever it is allowed, +@example + #@var{scheme} +@end example +evaluates the specified Scheme code. If this is used at toplevel, then +the result is discarded. Example: +@example + \property Staff.TestObject \override #'foobar = #(+ 1 2) +@end example -@node midilist, , , Reference Manual +@code{\override} expects two Scheme expressions, so there are two Scheme +expressions. The first one is a symbol (@code{foobar}), the second one +an integer (namely, 3). -The 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. +Scheme is a full-blown programming language, and a full discussion is +outside the scope of this document. Interested readers are referred to +the website @uref{http://www.schemers.org/} for more information on +Scheme. -@c @quotation -@example -"acoustic grand" "contrabass" "lead 7 (fifths)" -"bright acoustic" "tremolo strings" "lead 8 (bass+lead)" -"electric grand" "pizzicato strings" "pad 1 (new age)" -"honky-tonk" "orchestral strings" "pad 2 (warm)" -"electric piano 1" "timpani" "pad 3 (polysynth)" -"electric piano 2" "string ensemble 1" "pad 4 (choir)" -"harpsichord" "string ensemble 2" "pad 5 (bowed)" -"clav" "synthstrings 1" "pad 6 (metallic)" -"celesta" "synthstrings 2" "pad 7 (halo)" -"glockenspiel" "choir aahs" "pad 8 (sweep)" -"music box" "voice oohs" "fx 1 (rain)" -"vibraphone" "synth voice" "fx 2 (soundtrack)" -"marimba" "orchestra hit" "fx 3 (crystal)" -"xylophone" "trumpet" "fx 4 (atmosphere)" -"tubular bells" "trombone" "fx 5 (brightness)" -"dulcimer" "tuba" "fx 6 (goblins)" -"drawbar organ" "muted trumpet" "fx 7 (echoes)" -"percussive organ" "french horn" "fx 8 (sci-fi)" -"rock organ" "brass section" "sitar" -"church organ" "synthbrass 1" "banjo" -"reed organ" "synthbrass 2" "shamisen" -"accordion" "soprano sax" "koto" -"harmonica" "alto sax" "kalimba" -"concertina" "tenor sax" "bagpipe" -"acoustic guitar (nylon)" "baritone sax" "fiddle" -"acoustic guitar (steel)" "oboe" "shanai" -"electric guitar (jazz)" "english horn" "tinkle bell" -"electric guitar (clean)" "bassoon" "agogo" -"electric guitar (muted)" "clarinet" "steel drums" -"overdriven guitar" "piccolo" "woodblock" -"distorted guitar" "flute" "taiko drum" -"guitar harmonics" "recorder" "melodic tom" -"acoustic bass" "pan flute" "synth drum" -"electric bass (finger)" "blown bottle" "reverse cymbal" -"electric bass (pick)" "skakuhachi" "guitar fret noise" -"fretless bass" "whistle" "breath noise" -"slap bass 1" "ocarina" "seashore" -"slap bass 2" "lead 1 (square)" "bird tweet" -"synth bass 1" "lead 2 (sawtooth)" "telephone ring" -"synth bass 2" "lead 3 (calliope)" "helicopter" -"violin" "lead 4 (chiff)" "applause" -"viola" "lead 5 (charang)" "gunshot" -"cello" "lead 6 (voice)" -@end example +@node Keywords +@subsection Keywords +@cindex Keywords -@c @end quotation +Keywords start with a backslash, followed by a number of lower case +alphabetic characters. These are all the keywords. -@cindex MIDI types and performers +@example +apply arpeggio autochange spanrequest commandspanrequest +simultaneous sequential accepts alternative bar breathe +char chordmodifiers chords clef cm consists consistsend +context denies duration dynamicscript elementdescriptions +font grace header in lyrics key mark pitch +time times midi mm name pitchnames notes outputproperty +override set revert partial paper penalty property pt +relative remove repeat addlyrics partcombine score +script stylesheet skip textscript tempo translator +transpose type +@end example -The types available for MIDI translators are: +@node Integers +@subsection Integers -@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 +@cindex integers +@cindex @code{+} +@cindex @code{-} +@cindex @code{*} +@cindex @code{/} -The performers for MIDI translators are: +Formed from an optional minus sign followed by digits. Arithmetic +operations cannot be done with integers, and integers cannot be mixed +with reals. -@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 +@node Reals +@subsection Reals +@cindex real numbers -@node Pre-defined Identifiers, , , Reference Manual -@section Pre-defined Identifiers -@cindex pre-defined identifiers +Formed from an optional minus sign and a sequence of digits followed +by a @emph{required} decimal point and an optional exponent such as +@code{-1.2e3}. Reals can be built up using the usual operations: +`@code{+}', `@code{-}', `@code{*}', and +`@code{/}', with parentheses for grouping. +@cindex @code{\mm}, +@cindex @code{\in} +@cindex @code{\cm} +@cindex @code{\pt} +@cindex dimensions -Various identifiers are defined in the initialization files to -provide shorthands for some settings. Most of them are in -@file{ly/declarations.ly}. +A real constant can be followed by one of the dimension keywords: +@code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters, +points, inches and centimeters, respectively. This converts the number +a number that is the internal representation of that dimension. -@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. +@node Strings +@subsection Strings +@cindex string +@cindex concatenate - @item @code{\down}@keyindex{down} - Used for setting direction setting properties. Is equal - to -1. +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{\free}@keyindex{free} - Used for setting direction setting properties. Is equal - to 0. +The tokenizer accepts the following commands. They have no grammatical +function, hence they can appear anywhere in the input. - @item @code{\left}@keyindex{left} - Used for setting text alignment property. Is equal to -1. - @item @code{\nobreak}@keyindex{nobreak} - Prevent a line break in music by using a large negative argument - for the keyword @code{\penalty}. +@node Main input +@subsection Main input +@cindex Main input - @item @code{\none}@keyindex{none} - Used for setting @code{Score.beamslopedamping} and - @code{Score.beamquantisation} properties. Is equal to 0. +@cindex @code{\maininput} - @item @code{\normal}@keyindex{normal} - Used for setting @code{Score.beamslopedamping} and - @code{Score.beamquantisation} properties. Is equal to 1. +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{\normalkey}@keyindex{normalkey} - Select normal key signatures where each octave has the same key - signature. This sets the @code{Staff.keyoctaviation} property. +@node File inclusion +@subsection File inclusion +@cindex @code{\include} +@example + \include @var{filename} +@end example - @item @code{\right}@keyindex{right} - Used for setting text alignment property. Is set to 1. +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{\shiftoff}@keyindex{shiftOff} - Disable horizontal shifting of note heads that collide. Sets the - @code{Voice.horizontalNoteShift} property. - @item @code{\shiftOn}@keyindex{shiftOn} - Enable note heads that collide with other note heads to be - shifted horiztonally. Sets the @code{Voice.horizontalNoteShift} - property. +@node Version information +@subsection Version information +@cindex @code{\version} +@example + \version @var{string} ; +@end example - @item @code{\slurBoth}@keyindex{slurBoth} - Allow slurs to be above or below notes. This sets the - @code{Voice.slurVerticalDirection} property. +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{\slurDown}@keyindex{slurDown} - Force slurs to be below notes. This sets the - @code{Voice.slurVerticalDirection} property. +@cindex convert-ly - @item @code{\slurUp}@keyindex{slurUp} - Force slurs to be above notes. This sets the - @code{Voice.slurVerticalDirection} property. - @item @code{\specialkey}@keyindex{specialkey} - Allow key signatures do differ in different octaves. This sets - the @code{Staff.keyoctaviation} property. - @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. - @item @code{\stemUp}@keyindex{stemUp} - Force stems, beams and slurs to point up. This sets the - @code{Voice.verticalDirection} property. - @item @code{\traditional}@keyindex{traditional} - Used for setting the @code{Score.beamquantisation} property. Is - equal to 2. +@c .{Local emacs vars} +@c Local variables: +@c mode: texinfo +@c minor-mode: font-lock +@c minor-mode: outline +@c outline-layout: (-1 : 0) +@c outline-use-mode-specific-leader: "@c \." +@c outline-primary-bullet: "{" +@c outline-stylish-prefixes: nil +@c outline-override-protect: t +@c End: - @item @code{\up}@keyindex{up} - Used for setting various direction properties. Is equal - to 1. -@end table