X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=6bbaa275642af05de1f5b38fffddc28046703ba8;hb=3abcf40ffcc86fa452df2d3e79cc2c27b60fc6bd;hp=90e9e53e42441d1174090dbc90c6e4ac77602e1f;hpb=3379da1fe0fe84cd2c8939abf97bc9f48102f8f8;p=lilypond.git diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 90e9e53e42..6bbaa27564 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -1,1006 +1,1188 @@ -@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 +@strong{BUGS} + +@end macro + + +@c .{Reference Manual} + +@node Reference Manual @chapter Reference Manual +This document describes GNU LilyPond and its input format. The last +revision of this document was made for LilyPond 1.3.145. It supposes a +passing familiarity with how LilyPond input works. New users are +encouraged to study the tutorial first. + + @menu -* Overview:: Overview -* Top level:: Top level -* Pitch names:: Pitch names -* Lexical conventions:: Lexical conventions -* Other languages:: Note names in various languages -* Lexical modes:: modes -* Types:: Types -* Music expressions:: Music expressions -* Atomic music expressions:: Atomic music expressions -* Note specification:: notedesc -* barlines:: barlines -* Manual beams:: Manual beam -* stem tremolo:: tremolo -* Compound music expressions:: Compound music expressions -* relative:: relative -* Repeats:: Repeats -* transpose:: transpose -* Ambiguities:: Ambiguities -* Notation conversion specifics:: Notation conversion specifics -* 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 -* Grobs:: Graphical objects -* Molecule:: Molecules -* 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. +* Overview:: +* Note entry:: +* Staff notation:: +* Polyphony:: +* Beaming:: +* Expressive marks:: +* Ornaments:: +* Repeats:: +* Rhythmic music:: +* Piano music:: +* Lyrics:: +* Chords:: +* Writing parts:: +* Custodes:: +* Tuning output:: +* Page layout:: +* Output formats:: +* Sound:: +* Music entry:: +* Skipping corrected music:: +* Interpretation context:: +* Syntactic details:: +* Lexical details:: @end menu +@c . {Overview} +@node Overview +@section Overview -@node Overview, , , Reference Manual -@section Overview +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 aesthetic 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'. -This document@footnote{This document has been revised for LilyPond 1.2.} -describes the the GNU LilyPond input format This format represents a -piece of music in an elegant way, but contains enough information for -both automatic typesetting and automatic performances. +LilyPond is linked to GUILE, GNU's Scheme library for extension +programming. The Scheme library provides the glue that holds together +the low-level routines and separate modules which are written in C++. -LilyPond input can be classified into three types: +When lilypond is run to typeset sheet music, the following happens: @itemize @bullet - @item musical expressions: a musical expression is some combination of -rest, notes, lyrics - @item output definitions: recipes for translating those musical -expressions into performances (MIDI) or graphics (eg. PostScript). - - @item declarations: by declaring and naming musical expressions, you -can enter and edit 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. The result of this step is a typesetting +specification. + +@item typesetting: +The typesetting specification is solved: positions and formatting is +calculated. + +@item the visible results ("virtual ink") are written to the output file. @end itemize +During these stages different types of data play the the main role: +during parsing, @strong{Music} objects are created. During the +interpretation, @strong{contexts} are constructed, and with these contexts +a network of @strong{graphical objects} (``grobs'') is created. These +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. -@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 obligatory 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:: +@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}. -@cindex header +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. -@keyindex{header} +@cindex note names, Dutch -The syntax is +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. -@example - \header @{ @var{key1} = @var{val1}; - @var{key2} = @var{val2}; @dots{} @} -@end example +LilyPond has predefined sets of note names for various other languages. +To use them, simply include the language specific init file. For +example: @code{\include "english.ly"}. The available language files and +the names they define are: + +@example + Note Names sharp flat +nederlands.ly c d e f g a bes b -is -es +english.ly c d e f g a bf b -s/-sharp -f/-flat +deutsch.ly c d e f g a b h -is -es +norsk.ly c d e f g a b h -iss/-is -ess/-es +svenska.ly c d e f g a b h -iss -ess +italiano.ly do re mi fa sol la sib si -d -b +catalan.ly do re mi fa sol la sib si -d/-s -b +@end example + +@cindex @code{'} +@cindex @code{,} -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. + +@lilypond[fragment,verbatim,center] + c' c'' es' g' as' gisis' ais' +@end lilypond + +@c . {Defining pitch names} +@node Defining pitch names +@subsection Defining pitch names -@node Pitch names, , , Reference Manual +@cindex defining pitch names +@cindex pitch names, defining -Note names and chord modifiers can be customised for nationalities. -languages and conventions. The syntax is as follows. +Note names and chord modifiers can be customized for nationalities. The +syntax is as follows. + +@cindex @code{\pitchnames} +@cindex @code{\chordmodifiers} @example - \pitchnames @keyindex{pitchnames} @var{scheme-alist} - \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist} + \pitchnames @var{scheme-alist} + \chordmodifiers @var{scheme-alist} @end example See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for -specific examples how to do this. tables can be tailored specified -using. Some national note names have been provided, see @ref{Other -languages}. +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 -Identifier assignments may appear at top level. Semicolons are -forbidden after top level assignments. +@cindex duration +@cindex @code{\duration} +The syntax for a verbose duration specification is +@example + \duration @var{scmduration} +@end example +Here, @var{scmduration} is a Scheme object of type @code{Duration}. See +@ref{Duration} for more information. -@node Lexical conventions, , , Reference Manual -@section Lexical conventions -@cindex lexical conventions +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 you must use identifiers. +@example + c'\breve +c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 +r\longa r\breve +r1 r2 r4 r8 r16 r32 r64 r64 +@end example -@cindex comment +@lilypond[] +\score { + \notes \relative c'' { + 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 -@indexcode{%} + To get a longa note head, you have to use mensural note heads. This +is accomplished by setting the @code{style} property of the +NoteHead grob to @code{mensural}. +@lilypond[fragment,singleline,verbatim] + \property Voice.NoteHead \set #'style = #'mensural + a'\longa +@end lilypond -A one line comment is introduced by a `@code{%}' character. -Block comments are started by `@code{%@{}' and ended by `@code{%@}}'. -They cannot be nested. +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 dots (`@code{.}') to obtain dotted note +lengths. +@cindex @code{.} -@indexcode{#} +@lilypond[fragment,verbatim,center] + a'4. b'4.. c'8. +@end lilypond +@cindex @code{r} +@cindex @code{s} -LilyPond contains a Scheme interpreter (the GUILE library) for -internal use. The interpreter is accessed by the pound sign: +You can alter the length of duration by a fraction @var{N/M} by +appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This +will not affect the appearance of the notes or rests produced. -Whereever the syntax allows Scheme expressions, you may enter one as +@c . {Notes} +@node Notes +@subsection Notes -@example - #@var{scheme} -@end example +A note specification has the form -Evaluates the specified Scheme code. If this is used at toplevel, then -the result is discarded. Example: @example - \property Staff.TestObject \override #'symbol = #(+ 1 2) + @var{pitch}[!][?][@var{duration}] @end example -(in this case, @code{\override} expects two Scheme expressions. +The alteration refers to what note is heard, not to whether an +accidental is printed. This is done depending on the key and context. +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 +@cindex parenthesized accidental +i.e., an accidental within parentheses can be obtained by adding the +question mark `@code{?}' after the pitch. -[refer appendix/ online intro on Scheme] +@lilypond[fragment,verbatim,center] + cis' d' e' cis' c'? d' e' c'! +@end lilypond -@cindex keyword -Keywords start with a backslash, followed by a number of lower case -alphabetic characters. These are all the keywords. +@node Easy Notation note heads +@subsection Easy Notation note heads -@example -apply arpeggio autochange spanrequest commandspanrequest -simultaneous sequential accepts alternative bar breathe -char chordmodifiers chords clef cm consists consistsend -context denies duration dynamicscript elementdescriptions -font grace header in lyrics key mark musicalpitch -time times midi mm name pitchnames notes outputproperty -override set revert partial paper penalty property pt -relative remove repeat addlyrics partcombine score -script stylesheet skip textscript tempo translator -transpose type -@end example +@cindex easy notation +@cindex Hal Leonard -@cindex integer +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. -Formed from an optional minus sign followed by digits. Arithmetic -operations cannot be done with integers, and integers cannot be mixed -with reals. +@lilypond[singleline,verbatim] +\include "paper23.ly" +\score { + \notes { c'2 e'4 f' | g'1 } + \paper { \translator { \EasyNotation } } +} +@end lilypond -@cindex real - +Note that @code{EasyNotation} overrides a @code{Score} context. You +probably will want to print it with magnification to make it better +readable, see @ref{Output scaling}. -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. -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. +@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 produces the correct result. -@cindex string - +@node Tie +@subsection Tie -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. +@cindex Tie +@cindex ties +@cindex @code{~} +A tie connects two adjacent note heads of the same pitch. When used +with chords, it connects all 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 then no ties will be +created. -The tokenizer accepts the following commands. They have no grammatical -function, hence they can appear anywhere in the input. +@lilypond[fragment,verbatim,center] + e' ~ e' ~ +@end lilypond -@example - \maininput@keyindex{maininput} -@end example +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 -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. +In its meaning a tie is just a way of extending a note duration, similar +to the augmentation dot: the following example are two ways of notating +exactly the same concept. +@c +@lilypond[fragment, singleline] +c'2 c'4 ~ c'4 +@end lilypond -@example - \include@keyindex{include} @var{file} -@end example +The name of the tie grob is @code{Voice.Tie}. -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, +@refbugs -@example - \version@keyindex{version} @var{string} ; -@end example +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. -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. +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 the Thread +context and turning on and off ties per Thread. +@node Tuplets +@subsection Tuplets -@cindex other languages +@cindex tuplets +@cindex triplets +@cindex @code{\times} -@node Other languages, , , Reference Manual +Tuplets are made out of a music expression by multiplying their duration +with a fraction. -Note name definitions have been provided in various languages. -Simply include the language specific init file. For example: -`@code{\include "english.ly"}'. The available language files and the -names they define are: +@cindex @code{\times} +@example + \times @var{fraction} @var{musicexpr} +@end example -@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 +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: -Pitch names can be redefined using the @code{\pitchnames} command, see -@ref{Pitch names}. +@lilypond[fragment,verbatim,center] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond -@cindex Lexical Modes +The property @code{tupletSpannerDuration} specifies how long each bracket +should last. With this, you can make lots of tuplets while typing +@code{\times} only once, thus saving typing work. -@cindex modes +@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 Lexical modes, , , Reference Manual +The format of the number is determined by the property +@code{tupletNumberFormatFunction}. The default prints only the +denominator, but if you set it to the Scheme function +@code{fraction-tuplet-formatter} will print @var{num}:@var{den} instead. -To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three -special input modes on top of the default mode. In each mode, words -are identified on the input. If @code{"word"} is encountered, it is -treated as a string. If @code{\word} is encountered, it is treated as -a keyword or as an identifier. The behavior of the modes differs in -two ways: Different modes treat unquoted words differently, and -different modes have different rules for deciding what is a word. +@cindex @code{tupletNumberFormatFunction} +@cindex tuplet formatting -@table @samp - @item Normal mode. -@cindex mode!normal - - At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal - mode, a word is an alphabetic character followed by alphanumeric - characters. If @code{word} is encountered on the input it is - treated as a string. - - @item Note mode. -@cindex mode!note - - Note mode is introduced by the keyword - @code{\notes}@keyindex{notes}. In Note mode, words can only - contain alphabetic characters. If @code{word} is encountered, - LilyPond first checks for a notename of @code{word}. If no - notename is found, then @code{word} is treated as a string. - - Since combinations of numbers and dots are used for indicating - durations, it is not possible to enter real numbers in this mode. - - @item Chord mode. -@cindex mode!chord - - Chord mode is introduced by the keyword - @code{\chords}@keyindex{chords}. It is similar to Note mode, but - words are also looked up in a chord modifier table (containing - @code{maj}, @code{dim}, etc). - - Since combinations of numbers and dots are used for indicating - durations, you can not enter real numbers in this mode. Dashes - and carets are used to indicate chord additions and subtractions, - so scripts can not be entered in Chord mode. - - @item Lyrics mode. -@cindex mode!lyric - - Lyrics mode is introduced by the keyword - @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it - easy to include punctuation and diacritical marks in words. A - word in Lyrics mode begins with: an alphabetic character, - `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the - control characters @code{^A} through @code{^F}, @code{^Q} through - @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code - over 127, or a two-character combination of a backslash followed - by one of `@code{`}', `@code{'}', `@code{"}', or - `@code{^}'.@footnote{The purpose of Lyrics mode is that you can - enter lyrics in @TeX{} format or a standard encoding without - needing quotes. The precise definition of this mode indeed is - ludicrous. This will remain so until the authors of LilyPond - acquire a deeper understanding of character encoding, or someone - else steps up to fix this.} - - Subsequent characters of a word can be any character that is not - a digit and not white space. One important consequence of this - is that a word can end with `@code{@}}', which may be confusing if - you thought the closing brace was going to terminate Lyrics - mode.@footnote{LilyPond will issue a warning, though.} Any - `@code{_}' character which appears in an unquoted word is - converted to a space. This provides a mechanism for introducing - spaces into words without using quotes. Quoted words can also be - used in Lyrics mode to specify words that cannot be written with - the above rules. Here are some examples. Not all of these words - are printable by @TeX{}. +Tuplet brackets are printed as @code{TupletBracket} grobs -@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 +@c . {Rests} +@node Rests +@subsection Rests +@cindex Rests -[todo: include short table showign differences] +Rests are entered like notes, with note name `@code{r}'. The grob is +@code{Rest}. Whole bar rests centered in the bar are specified using +@code{R}, see @ref{Multi measure rests}. -@node Types, , , Reference Manual -@section Types -@cindex Identifiers +@c . {Skip} +@node Skip +@subsection Skip +@cindex Skip -[say something about types] -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, +@example + \skip @var{duration} + s@var{duration} +@end example +@cindex @code{\skip} -@itemize @bullet - @item Input - @item c++-function - @item Music: see @ref{Music expressions} - @item Identifier - @item Translator_def: -See section @ref{contextdefs} for more information - - @item Duration - @item Pitch - @item Score (TODO, smobme) -@item Music_output_def (TODO, smobme) - - @item Moment (rational number) -@end itemize +Skips the amount of time specified by @var{duration}. If no other music +is played, a gap will be left for the skipped time without any notes +printed. The shorthand is only available in Note and Chord mode. -LilyPond also includes some transient object types. Objects of these -types are built during a LilyPond run, and do not `exist' per se within -your input file. These objects are created as a result of your input -file, so you can include commands in the input to manipulate them, -during a lilypond run . -@itemize @bullet - @item Grob: short for Graphical object. See @ref{Grobs}. - @item Molecule: device-independent paper output object, - including dimensions. Produced by some Grob functions - @item Translator: object that produces audio objects or Grobs - @item Font_metric: object representing a font. (Not yet user accessible.) - @item Audio_element: (TODO, smobme) -@end itemize +@node Staff notation +@section Staff notation -Identifiers allow objects to be assigned to names during the parse -stage. To assign an identifier, you use `@var{name}=@var{value}' and to -refer to an identifier, you preceed its name with a backslash: -`@code{\}@var{name}'. Identifier assignments must appear at top level -in the @emph{Lilypond} file. Semicolons are forbidden after assignments -appearing at top level but they are obligatory after assignments -appearing in the @code{\paper} block, see Section @ref{paper}. +@cindex Staff notation -@var{value} is any valid Scheme value or any of the input-types listed -above. +@menu +* Key signature:: +* Clef:: +* Time signature:: +* Unmetered music:: +* Bar lines:: +@end menu -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} +Setting or changing the key signature is done with the @code{\key} +command. @example - foo = \foo * 2.0 + @code{\key} @var{pitch} @var{type} @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. +@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 standard mode names @code{\ionian}, +@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian}, +@code{\phrygian}, and @code{\dorian} are also defined. + +This command sets the context property @code{Staff.keySignature}. +Non-standard key signatures can be specified by setting this property +directly, see the generated documentation for @rgrob{KeySignature}. + +The printed signature is a @code{KeySignature} grob. + +@cindex @code{keySignature} + +@c . {Clef} +@node Clef +@subsection Clef +@cindex @code{\clef} + +The clef can be set or changed with the @code{\clef} command. @example -\paper @{ - foo = 1.0 - \paperIdent % wrong and invalid -@} - -\paper @{ - \paperIdent % correct - foo = 1.0 -@} + \clef @var{clefname} @end example +Shortcut for -@node Music expressions, , , Reference Manual -@section Music expressions +@example + \property Staff.clefGlyph = @var{glyph associated with clefname} + \property Staff.clefPosition = @var{clef Y-position for clefname} + \property Staff.clefOctavation = @var{extra transposition of clefname} +@end example -@cindex music expressions +Any change in these properties creates a clef (a @code{Clef} grob). -Music in @emph{Lilypond} is entered as a music expression. Notes, rests, -lyric syllables are music expressions (the atomic -expressions) -@cindex atomic music expressions -, and you can combine -music expressions to form new ones. This example forms a compound -expressions out of the quarter @code{c} note and a @code{d} -note: +Supported clef-names include -@example -\sequential @{ c4 d4 @} -@end example +@table @code +@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 table -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). +By adding @code{_8} or @code{^8} to the clef name, the clef is +transposed one octave down or up, respectively. + +Supported associated glyphs (for @code{Staff.clefGlyph}) are: + +@table @code +@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 table -Atomic music expression are discussed in -subsection @ref{Atomic music expressions}. Compound music expressions are -discussed in subsection @ref{Compound music expressions}. +@emph{Modern style} means ``as is typeset in current editions.'' +@emph{Historic style} means ``as was typeset or written in contemporary +historic editions''. @emph{Editio XXX style} means ``as is/was printed in +Editio XXX.'' +@cindex Vaticana, Editio +@cindex Medicaea, Editio +@cindex hufnagel clefs -@node Atomic music expressions, , , Reference Manual -@section Atomic music expressions +@c . {Time signature} +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} +The time signature is set or changed by the @code{\time} +command. Syntax: +@example + \time @var{n}@code{/}@var{d} +@end example +Internally, this is a shortcut for doing +@example +\property Score.timeSignatureFraction = #'(@var{n} . @var{d}) +\property Score.beatLength = #(make-moment 1 @var{d}) +\property Score.measureLength = #(make-moment @var{n} @var{d}) +@end example +These properties @code{timeSignatureFraction} determine where bar lines +should be inserted, and how automatic beams should be +generated. + +Changing the value of @code{timeSignatureFraction} also causes a +fraction to be printed. This grob is @code{TimeSignature}. + +The actual symbol that's printed can be customised with the style +property. +@lilypond[fragment, verbatim, singleline] +\time 3/4 s2 +\property Staff.TimeSignature \override #'style = #'C +\time 4/4 s2 +\property Staff.TimeSignature \override #'style = #'() +\time 4/4 s2 +\property Staff.TimeSignature \override #'style = #'C +\time 2/2 s2 +@end lilypond +There are many more options for the layout of this grob. They are +selected through the @code{style} grob property. -@cindex pitch +@c FIXME: this isn't documented except in example? +See +@file{input/test/time.ly} for examples. -@cindex duration - +@c . {Partial} +@subsection Partial +@cindex Partial +@cindex anacrusis +@cindex upbeat +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} -The syntax for pitch specification is +Partial measures, for example in upbeats, are entered using the +@code{\partial} command: +@example + \partial @var{duration} +@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{|} -@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 @ref{Other languages} for pitch names in different languages. +The property @code{measurePosition} contains a rational number +indicating how much of the measure has passed at this point. -The syntax for duration specification is -@example - \duration@keyindex{duration} - @{ @var{length} @var{dotcount} @} -@end example +@node Unmetered music +@subsection Unmetered music -@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}. +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 -In Note, Chord, and Lyrics mode, durations may be designated by -numbers and dots. +@lilypond[fragment,relative,singleline,verbatim] +c'2. +\property Score.timing = ##f +c2 +\property Score.timing = ##t +c4 c4 c4 +@end lilypond +The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used to +achieve the same effect. -@node Note specification, , , Reference Manual -@cindex note specification -@cindex pitches +@c . {Bar lines} +@node Bar lines +@subsection Bar lines +@cindex Bar lines -@cindex entering notes +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars -A note specification has the form +@example + \bar @var{bartype} +@end example +This is a shortcut for doing @example - @var{pitch}[@var{octavespec}][!][?][@var{duration}] + \property Score.whichBar = @var{bartype} @end example -The pitch of the note is specified by the note's name. +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeats}. -The default names are the Dutch note names. The notes are specified -by the letters `@code{c}' through `@code{b}', where `@code{c}' is an -octave below middle C and the letters span the octave above that C. -In Dutch, -@cindex notenames!Dutch -a sharp is formed by adding `@code{-is}' to the end of a pitch name. A -flat is formed by adding `@code{-es}'. Double sharps and double flats -are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}' -and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch, -but both forms will be accepted. +@cindex Bar_line_engraver +@cindex whichBar +@cindex repeatCommands +@cindex defaultBarType -LilyPond has predefined sets of notenames for various languages. See -@ref{Other languages}. +Whenever @code{whichBar} is set to a string, a bar line of that type is +created. @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. +@code{whichBar} can also be set directly, using @code{\property} or +@code{\bar }. These settings take precedence over the automatic +@code{whichBar} settings. +@code{Bar_engraver} creates @code{BarLine} grobs. -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. +@c . {Polyphony} +@node Polyphony +@section Polyphony +@cindex polyphony -@lilypond[fragment,verbatim,center] - c' d' e' f' g' a' b' c'' +Polyphonic parts, i.e. parts with more than one voice on a staff can be +typeset with LilyPond. To use this, instantiate a separate Voice +context for each part, and assign a stem direction to each part. +@lilypond[fragment,verbatim] +\context Staff +< \context Voice = VA { \stemUp b'4 a' g' f' e' } + \context Voice = VB { \stemDown g'4 g' g' g' g' } > @end lilypond -@lilypond[fragment,verbatim,center] - cis' dis' eis' fis' gis' ais' bis' +When there are more than two voices on a staff, you must also indicate +which voice should moved horizontally in case of a collision. This can +be done with the identifiers @code{\shiftOff}, @code{\shiftOn}, +@code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift} +in @code{NoteColumn}). + +@lilypond[fragment, verbatim] + \context Staff \notes\relative c''< + \context Voice=one { + \shiftOff \stemUp e4 + } + \context Voice=two { + \shiftOn \stemUp cis + } + \context Voice=three { + \shiftOnn \stemUp ais + } + \context Voice=four { + \shiftOnnn \stemUp fis + } + > @end lilypond -@lilypond[fragment,verbatim,center] - ces' des' es' fes' ges' as' bes' -@end lilypond +The most convenient way is to use the identifiers @code{\voiceOne} +through @code{\voiceFour}, which also set slur and tie directions in the +correct manner. -@lilypond[fragment,verbatim,center] - cisis' eisis' gisis' aisis' beses' +@lilypond[singleline, verbatim] +\relative c'' +\context Staff < \context Voice = VA { \voiceOne cis2 b } + \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } + \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } > @end lilypond -@lilypond[fragment,verbatim,center] - ceses' eses' geses' ases' beses' +Normally, note heads with a different number of dots are not merged, but +if you set the grob property @code{merge-differently-dotted}, they are: + +@lilypond[verbatim,fragment,singleline] + \context Staff < + \context Voice = VA { \voiceOne + g'8 g'8 + \property Staff.NoteCollision \override #'merge-differently-dotted = ##t + g'8 g'8 + } + \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] } + > @end lilypond -Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond -will determine what accidentals to typeset depending on the key and -context. A reminder accidental -@cindex reminder accidental - can be -forced by adding an exclamation mark `@code{!}' after the pitch. A -cautionary accidental, -@cindex cautionary accidental - i.e., an -accidental within parentheses can be obtained by adding the question -mark `@code{?}@indexcode{?}' after the pitch. +LilyPond also vertically shifts rests that are opposite of a stem. -@lilypond[fragment,verbatim,center] - cis' d' e' cis' c'? d' e' c'! +@lilypond[singleline,verbatim] +\context Staff < +\context Voice { \stemUp c''4 } +\context Voice =VB { r4 } +> @end lilypond +Note head collisions (horizontal shifting of note heads) are handled by +the @code{NoteCollision} grob. @code{RestCollision} handles vertical +shifting of rests. -@cindex duration +@cindex @code{NoteCollision} +@cindex @code{RestCollision} -Durations are entered as their reciprocal values. For notes longer -than a whole note, use identifiers. -@quotation +@refbugs -@example -c'\longa c'\breve -c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 -@end example +Resolving collisions is a very intricate subject, and LilyPond only +handles a few situations. When it can not cope, you are advised to use +@code{force-hshift} of the NoteColumn grob and @code{staff-position} of +the Rest grob to override typesetting decisions. -@end quotation +@node Beaming +@section Beaming -@quotation +Beams are used to group short notes into chunks that are aligned with +the metrum. LilyPond guesses where beams should be inserted. If you're +not satisfied with the automatic beaming, you can specify which patterns +to beam automatically. In specific cases, you can also enter the beams +explicitly. -@lilypond[] -\score { - \notes \relative c'' { - a\longa a\breve - a1 a2 a4 a8 a16 a32 a64 a64 - } - \paper { -%{ \translator { - \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - } %} - } -} -@end lilypond -@end quotation -@quotation +@c . {Automatic beams} +@subsection Automatic beams -@example -r\longa r\breve -r1 r2 r4 r8 r16 r32 r64 r64 -@end example +@cindex @code{Voice.autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} -@end quotation -@quotation - -@lilypond[] -\score { - \notes \relative c'' { - r\longa r\breve - r1 r2 r4 r8 r16 r32 r64 r64 - } - \paper { - loose_column_distance = 2.5 * \staffspace; - linewidth = -1.0; - \translator { - \StaffContext - \remove "Clef_engraver"; - \remove "Staff_symbol_engraver"; - \remove "Bar_engraver"; - } - } -} -@end lilypond -@end quotation - -If the duration is omitted then it is set equal to the previous -duration. If there is no previous duration, a quarter note is -assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}') -to obtain dotted note lengths. - -@lilypond[fragment,verbatim,center] - a'4. b'4. -@end lilypond - -You can alter the length of duration by writing -`@code{*}@var{fraction}' after it. This will not affect the -appearance of note heads or rests. - - -Rests are entered like notes, with note name `@code{r}@indexcode{r}', -or `@code{R}@indexcode{R}'. There is also a note name -`@code{s}@indexcode{s}', which produces a space of the specified -duration. `@code{R}' is specifically meant for entering parts: the -@code{R} rest can expand to fill a score with rests, or it can be -printed as a single multimeasure rest. - -You can control the expansion by setting the property -@code{Score.skipBars}. If this is set to true, Lily will not expand -empty measures, and the multimeasure rests automatically adds the -appropriate number. - - -@cindex lyrics expressions - -Syllables are entered like notes, with pitches replaced by text. For -example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each -with quarter note duration. Note that the hyphen has no special -meaning for lyrics, and does not introduce special symbols. See -section @ref{Lexical modes} for a description of what is interpreted as -lyrics. - -Spaces can be introduced into a lyric either by using quotes -(`@code{"}') or by using an underscore without quotes: `@code{He_could4 -not4}'. All unquoted underscores are converted to spaces. Printing -lyrics is discussed in section @ref{lyricprint}. - - - -@cindex properties +In normal time signatures, automatic beams can start on any note but can +only end in a few positions within the measure: beams can end on a beat, +or at durations specified by the properties in +@code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings} +are defined in @file{scm/auto-beam.scm}. +The value of @code{autoBeamSettings} is changed using +@code{\override} and unset using @code{\revert}: @example - \property@keyindex{property} - @var{contextname}.@var{propname} = @var{value} +\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 - -Sets the @var{propname} property of the context @var{contextname} to -the specified @var{value}. All three arguments are strings. -Depending on the context, it may be necessary to quote the strings or -to leave space on both sides of the dot. - - - -@cindex translator switches - +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 (wildcards, `@code{* *}' may +be entered to designate all time signatures), @var{P}/@var{Q} refers to +the length of the beamed notes (and `@code{* *}' designates notes of any +length). + +For example, if you want automatic beams to end on every quarter note, +you can use the following: @example - \translator@keyindex{translator} - @var{contexttype} = @var{name} +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(make-moment 1 4) @end example +Since the duration of a quarter note is 1/4 of a whole note, it is +entered as @code{(make-moment 1 4)}. -A music expression indicating that the context which is a direct -child of the a context of type @var{contexttype} should be shifted to -a context of type @var{contexttype} and the specified name. - -Usually this is used to switch staffs in Piano music, e.g. - +The same syntax can be used to specify beam starting points. In this +example, automatic beams can only end on a dotted quarter note. @example - \translator Staff = top @var{Music} +\property Voice.autoBeamSettings \override + #'(end * * * *) = #(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 +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)}. -@cindex output properties - - -These allow you to tweak what is happening in the back-end -directly. If you want to control every detail of the output -formatting, this is the feature to use. The downside to this is that -you need to know exactly how the backend works. Example: +@c not true +@c Automatic beams can not be put on the last note in a score. +If a score ends while an automatic beam has not been ended and is still +accepting notes, this last beam will not be typeset at all. -@lilypond[fragment,verbatim] -\relative c'' { c4 - \context Staff \outputproperty - #(make-type-checker 'Note_head) - #'extra-offset = #'(5.0 . 7.5) - } +@cindex automatic beam generation +@cindex autobeam +@cindex @code{Voice.noAutoBeaming} + +Automatic beaming is on by default, but can be switched off by setting +@code{Voice.noAutoBeaming} to true. You you may find this necessary for +a melody that goes with lyrics. + +@refbugs + +It is not possible to specify beaming parameters for beams with mixed +durations, that differ from the beaming parameters of all separate +durations, i.e., you'll have to specify manual beams to get: +@lilypond[fragment,singleline,relative] + \property Voice.autoBeamSettings + \override #'(end * * * *) = #(make-moment 3 8) + \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4 @end lilypond -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. +It is not possible to specify beaming parameters that act differently in +different parts of a measure. This means that it is not possible to use +automatic beaming in irregular meters such as @code{5/8}. + +@c . {Manual beams} +@cindex Automatic beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} + +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, If you want that, specify the begin and end point +manually using a @code{[} before the first beamed note and a @code{]} +after the last note: + +@lilypond[fragment,relative,verbatim] + \context Staff { + r4 [r8 g'' a r8] r8 [g | a] r8 + } +@end lilypond +Whenever an manual beam is busy, the automatic beamer will not produce +anything. -Use of this feature is entirely on your own risk: if you use this, the -result will depend very heavily on the implementation of the backend, -which we change regularly and unscrupulously. +@cindex @code{stemLeftBeamCount} +Normally, beaming patterns within a beam are determined automatically. +When this mechanism fouls up, the properties +@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. can +be used to control the beam subdivision on a stem. If you set either +property, it's value will be used only once, and then it is erased. -@cindex commands +@lilypond[fragment,relative,verbatim] + \context Staff { + [f'8 r16 f g a] + [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] + } +@end lilypond +@cindex @code{stemRightBeamCount} -Commands are music expressions that have no duration. +The beam symbol (grob @code{Voice.Beam}, both for automatic and manual +beams) can be tweaked through grob-properties @code{height} and +@code{staff-position}. These specify vertical location and vertical +span. Both are measured in half staff-spaces, @code{staff-position=0} +corresponds to the middle staff line. -@example +Set @code{height} to zero, to get horizontal beams: - @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;} -@end example +@lilypond[fragment,relative,verbatim] + \property Voice.Beam \set #'direction = #1 + \property Voice.Beam \set #'height = #0 + [a''8 e' d c] +@end lilypond -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. +Here's how you'd specify a weird looking beam that instead of being +horizontal, falls two staff spaces: -@example - @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;} -@end example +@lilypond[fragment,relative,verbatim] + \property Voice.Beam \set #'staff-position = #4 + \property Voice.Beam \set #'height = #-4 + [c'8 c] +@end lilypond +@cindex @code{default-neutral-direction} -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 +@node Expressive marks +@section Expressive marks -Prints a mark over or under the staff. You must add -@code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for -this to work. +@c . {Slur} +@menu +* Slur :: +* Phrasing slur:: +* Breath marks:: +* Tempo:: +* Text spanner:: +@end menu -@node barlines, , , Reference Manual +@node Slur +@subsection Slur +@cindex slur -@example - \bar@keyindex{bar} @var{bartype}; -@end example +A slur indicates that notes are to be played bound or @emph{legato}. +They are entered using parentheses: -This is a short-cut for doing -@example - \property Score.whichBar = @var{bartype} -@end example +@lilypond[fragment,verbatim,center] + f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 +@end lilypond -You are encouraged to use @code{\repeat} for repetitions. See -@ref{Repeats}, and the documentation of @code{whichBar}. +Slurs avoid crossing stems, and are generally attached to note heads. +However, in some situations with beams, slurs may be attached to stem +ends. If you want to override this layout you can do this through the +@code{Voice.Slur}'s grob-property @code{attachment}. It's value is a +pair of symbols, specifying the attachment type of the left and right end points. -@example - \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;} -@end example +@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 -A short-cut for doing -@example - \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator}) -@end example +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: -See the documentation of @code{timeSignatureFraction} +@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 -@example - \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;} -@end example +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 +indicate this preference by increasing the @code{beautiful} value: + +@lilypond[verbatim,singleline,relative] + \property Voice.Beam \override #'direction = #-1 + \property Voice.Slur \override #'direction = #1 + c'16( a' f' a a f a, )c, + c( a' f' a a f d, )c + \property Voice.Slur \override #'beautiful = #5.0 + c( a' f' a a f d, )c +@end lilypond -Used to specify the tempo. For example, `@code{\tempo 4 = 76;}' -requests output with 76 quarter notes per minute. +@refbugs -@example - \partial@keyindex{partial} @var{duration} @code{;} -@end example +@code{beautiful} is an arbitrary parameter in the slur formatter. +Useful values can only be determined by trial and error. -Short cut for +@cindex Adjusting slurs -@example - \property Score.measurePosition = @var{length of duration} -@end example +@node Phrasing slur +@subsection Phrasing slur -See the documentation of @code{measurePosition}. +@cindex phrasing slur +@cindex phrasing mark -@cindex anacrusis +A phrasing slur (or phrasing mark) connects chords and is used to +indicate a musical sentence. It is started using @code{\(} and @code{\)} +respectively. -@cindex upstep +@lilypond[fragment,verbatim,center,relative] + \time 6/4 c''\((d)e f(e)\)d +@end lilypond -@example +Typographically, the phrasing slur behaves almost exactly like a normal +slur. The grob associated with it is @code{Voice.PhrasingSlur}. - @code{|}@indexcode{|} -@cindex bar check +@node Breath marks +@subsection Breath marks -@end example +Breath marks are entered using @code{\breathe}. The result is a +@code{Voice.BreathingSign} grob. -@cindex shorten measures +@lilypond[fragment,relative] +c'4 \breathe d4 +@end lilypond -@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. -Depending on the value of @code{barCheckNoSynchronize} -@indexcode{barCheckNoSynchronize} The beginning of the measure will be -relocated, so this can also be used to shorten measures. -@example +@refbugs - \penalty@keyindex{penalty} @var{int} @code{;} -@end example + Currently, only tick marks are supported, not comma style breath marks. -Discourage or encourage line breaks. See identifiers -@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in -section [on identifiers] [FIXME]. -@example - \clef@keyindex{clef} @var{clefname} @code{;} -@end example +@c . {Tempo} +@node Tempo +@subsection Tempo +@cindex Tempo +@cindex beats per minute +@cindex metronome marking -Short-cut for +Metronome settings can be entered as follows: +@cindex @code{\tempo} @example - \property Clef.clefGlyph = @var{symbol associated with clefname} - \property Clef.clefPosition = @var{clef Y-position for clefname} - \property Clef.clefOctavation = @var{extra pitch of clefname} + \tempo @var{duration} = @var{perminute} @end example -Supported clef-names include +For example, @code{\tempo 4 = 76} requests output with 76 quarter notes +per minute. + +@refbugs + +The tempo setting is not printed, but is only used in the MIDI +output. You can trick lily into producing a metronome mark, +though. Details are in @ref{Text markup}. + -[todo] -@example +@node Text spanner +@subsection Text spanner +@cindex Text spanner - \skip@keyindex{skip} @var{duration} @code{;} +Some textual indications, e.g. rallentando, accelerando, often extend +over many measures. This is indicated by following the text with a +dotted line. You can create such texts using text spanners. The syntax +is as follows: +@example +\spanrequest \start "text" +\spanrequest \stop "text" @end example +LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The +string to be printed, as well as the style is set through grob +properties. -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{]}'. - -@lilypond[fragment,verbatim,center] - [a'8 a'] [a'16 a' a' a'] -@end lilypond - -Some more elaborate constructions: - -@lilypond[fragment,verbatim,center] - [a'16 c'' ] - \times 2/3 { [e'8 f' g'] } -@end lilypond - -Beaming can be generated automatically; see section @ref{autobeam}. - -[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. - -@lilypond[fragment,verbatim,center] - \repeat "tremolo" 8 { c16 d16 } - \repeat "tremolo" 4 { c16 d16 } -@end lilypond - -@lilypond[fragment,verbatim,center] - c'4:32 -@end lilypond - - -@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. - -@lilypond[fragment,verbatim,center] - e' ~ e' ~ +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:: +* Glissando :: +* Dynamics:: +@end menu -[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 different characteristics of the performance. These symbols can be added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols -are defined in @file{script.ly} and @file{script.scm}. Symbols can be -forced to appear above or below the note by writing -`@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}' -respectively. Here is a chart showing symbols above notes, with the -name of the corresponding symbol appearing underneath. +are defined in @file{script.ly}. Symbols can be forced to appear above +or below the note by writing `@var{note}@code{^\}@var{name}' and +`@var{note}@code{_\}@var{name}' respectively. Here is a chart showing +symbols on notes, with the name of the corresponding symbol appearing +underneath. @lilypond[] - \score { - < \notes { - c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata + < + \property Score.LyricSyllable \override #'font-family =#'typewriter + \property Score.LyricSyllable \override #'font-shape = #'upright + \context Staff \notes { + c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata c''-\stopped c''-\staccato c''-\tenuto c''-\upbow c''-\downbow c''^\lheel c''-\rheel c''^\ltoe c''-\rtoe c''-\turn c''-\open c''-\flageolet @@ -1008,7 +1190,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 @@ -1019,709 +1201,791 @@ name of the corresponding symbol appearing underneath. } > \paper { - linewidth = 5.875\in; - indent = 0.0; + linewidth = 5.875\in + indent = 0.0 } } - @end lilypond -In addition, it is possible to place arbitrary strings of text or -@TeX{} above or below notes by using a string instead of an -identifier: `@code{c^"text"}'. Fingerings -@cindex fingering - can be -placed by simply using digits. All of these note ornaments appear in -the printed output but have no effect on the MIDI rendering of the -music. - -To save typing, fingering instructions (digits 0 to 9 are -supported) and single characters shorthands exist for a few -common symbols - -@lilypond[] - +To save typing work, some shorthands are available: +@lilypond[singleline] \score { - \notes { - \property Voice.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 + +@cindex fingering +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 -Dynamic marks are specified by using an identifier after a note: -`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'. -The available dynamic marks are: -@code{\ppp}@keyindex{ppp}, -@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp}, -@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff}, -@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff}, -@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf}, -@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp}, -@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and -@code{\rfz}@keyindex{rfz}. +@cindex @code{\script} +@cindex scripts +@cindex superscript +@cindex subscript + +You can add scripts by editing @file{scm/script.scm}. This file contains +a table, listing script definitions and aliases. The following syntax +accesses a script definition from the table: @example - - \textscript@keyindex{textscript} @var{text} @var{style} + \script @var{alias} @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: +Usually the @code{\script} keyword is not used directly. Various +helpful identifier definitions appear in @file{script.ly}. -@quotation +Grobs for these objects are @code{Script} and @code{Fingering}. -@example -c4-\textscript "6" "finger" -c4-\textscript "foo" "normal" -@end example +@refbugs -@end quotation +All of these note ornaments appear in the printed output but have no +effect on the MIDI rendering of the music. -This is equivalent to `@code{c4-6 c4-"foo"}'. +Unfortunately, there is no support for adding fingering instructions or +ornaments to individual note heads. Some hacks exist, though. See +@file{input/test/script-horizontal.ly}. -@cindex scripts +@c . {Text scripts} +@node Text scripts +@subsection Text scripts +@cindex Text scripts -@example +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"}. - \script@keyindex{script} @var{alias} -@end example +By default, these indications do not influence the note spacing, but +if @code{Voice.textNonEmpty} is set to true the widths will be taken +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 -Prints a symbol above or below a note. The argument is a string -which points into the script-alias table defined in @file{script.scm}. -The scheme definitions specify whether the symbol follows notes into -the staff, dependence of symbol placement on staff direction, and a -priority for placing several symbols over one note. Usually the -@code{\script}@keyindex{script} keyword is not used directly. Various -helpful identifier definitions appear in @file{script.ly}. +Text scripts are created in form of @code{Voice.TextScript} grobs. +@ref{Text markup} describes how to change the font or access +special symbols in text scripts. -@cindex slur +@c . {Grace notes} +@node Grace notes +@subsection Grace notes -Slurs connects chords and try to avoid crossing stems. A slur is -started with `@code{(}' and stopped with `@code{)}'. The -starting `@code{(}' appears to the right of the first note in -the slur. The terminal `@code{)}' appears to the left of the -first note in the slur. This makes it possible to put a note in -slurs from both sides: -@lilypond[fragment,verbatim,center] - f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 -@end lilypond -@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. -@lilypond[fragment,verbatim,center] - c'' \< \! c'' d'' \decr e'' \rced - < f''1 { s4 \< \! s2 \> \! s4 } > -@end lilypond +@cindex Grace music +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes +@cindex @code{graceAlignPosition} +Grace notes are ornaments that are written out, but do not take up any +logical time in a measure. LilyPond has limited support for grace notes. +The syntax is as follows. @example - - \spanrequest@keyindex{spanrequest} @var{startstop} @var{type} + \grace @var{musicexpr} @end example -Define a spanning request. The @var{startstop} parameter is either -1 -(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and -@var{type} is a string that describes what should be started. -Supported types are @code{crescendo}, @code{decrescendo}, -@code{beam}, @code{slur}. This is an internal command. Users should -use the shorthands which are defined in the initialization file -@file{spanners.ly}. - -You can attach a (general) span request to a note using +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 the 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. -@lilypond[fragment,verbatim,center] - c'4-\spanrequest \start "slur" - c'4-\spanrequest \stop "slur" +@lilypond[fragment,verbatim] +\relative c'' { + \grace c8 c4 \grace { [c16 c16] } c4 + \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4 +} @end lilypond -The slur syntax with parentheses is a shorthand for this. +A grace note expression has duration 0; the next real note is assumed to +be the main note. If you want the note to appear after the main note, +set @code{Voice.graceAlignPosition} to @code{1}. +@refbugs -@cindex tremolo marks - -@node stem tremolo, , , Reference Manual +At present, slurs or ties from the grace notes to the following notes +are not supported. Also, nesting @code{\grace} notes is not +supported. The following may cause run-time errors: +@example + @code{\grace @{ \grace c32 c16 @} c4} +@end example +Since the meaning of such a construct is unclear, we don't consider this +a loss. Similarly, juxtaposing two @code{\grace} sections is +syntactically valid, but makes no sense and may cause runtime errors. +Ending a staff or score with grace notes may also generate a run-time +error, since there will be no main note to attach the grace notes to. -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. +The present implementation of grace notes is not robust and generally +kludgey. We expect it to change after LilyPond 1.4. Syntax changes might +also be implemented. -@lilypond[verbatim,fragment,center] - c'2:8 c':32 -@end lilypond +@menu +* Glissando :: +* Dynamics:: +@end menu -@node Compound music expressions, , , Reference Manual -@section Compound music expressions +@c . {Glissando} +@node Glissando +@subsection Glissando +@cindex Glissando -@cindex compound music expressions +@cindex @code{\glissando} -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: +A glissando line (grob @code{Voice.Glissando}) can be requested by attaching a +@code{\glissando} to a note: -@lilypond[fragment,verbatim,center] - \notes \context Staff { - \cadenzaOn - - < { a b c' } { c' d' e' } > - } +@lilypond[fragment,relative,verbatim] + c''-\glissando c' @end lilypond -@cindex context selection -@c @keyindex{context} +@refbugs -@example - \context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example +Printing of an additional text (such as @emph{gliss.}) must be done +manually. -Interpret @var{musicexpr} within a context of type @var{contexttype}. -If the context does not exist, it will be created. The new context -can optionally be given a name. -@cindex input modes -@cindex mode switch +@c . {Dynamics} +@node Dynamics +@subsection Dynamics +@cindex Dynamics -Mode switching keywords form compound music expressions: @code{\notes} -@keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords} -@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}. -These expressions do not add anything to the meaning of their -arguments. They are just a way to indicate that the arguments should -be parsed in indicated mode. See @ref{Lexical modes} for more -information on modes. -@cindex sequential music +@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} -@example +Absolute dynamic marks are specified 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}. - \sequential@keyindex{sequential} - @code{@{} @var{musicexprlist} @code{@}} -@end example +@lilypond[verbatim,singleline,fragment,relative] + c''\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff + c2\sf c\rfz +@end lilypond -This means that list should be played or written in sequence, i.e., -the second after the first, the third after the second. The duration -of sequential music is the the sum of the durations of the elements. -There is a shorthand, which leaves out the keyword: +@cindex @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 several marks during one note, you have to use spacer notes. -@example +@lilypond[fragment,verbatim,center] + c'' \< \! c'' d'' \decr e'' \rced + < f''1 { s4 s4 \< \! s4 \> \! s4 } > +@end lilypond - @code{@{} @var{musicexprlist} @code{@}} -@end example +You can also use a text saying @emph{cresc.} instead of hairpins. Here +is an example how to do it: + +@cindex crescendo +@cindex decrescendo +@lilypond[fragment,relative,verbatim] + \context Voice { + \property Voice.crescendoText = "cresc." + \property Voice.crescendoSpanner = #'dashed-line + a''2\mf\< a a \!a + } +@end lilypond +For everyday use, we recommend the identifiers @code{\cresc}, +@code{endcresc}, @code{\dim} and @code{\enddim}. -@cindex simultaneous music +@cindex diminuendo -@indexcode{<} -@indexcode{>} +Dynamics are grobs of @code{Voice.DynamicText} and +@code{Voice.Hairpin}. They are put together on +@code{Voice.DynamicLineSpanner} to align them vertically. -@example - \simultaneous@keyindex{simultaneous} - @code{@{} @var{musicexprlist} @code{@}} -@end example +@c . {Repeats} +@node Repeats +@section Repeats -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 +@cindex repeats +@cindex @code{\repeat} - @code{<} @var{musicexprlist} @code{>} -@end example +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. -If you try to use a chord as the first thing in your score, you might -get multiple staffs instead of a chord. +@table @asis +@item unfold +Repeated music is fully written (played) out. Useful for MIDI +output, and entering repetitive music. -@lilypond[verbatim,center] - \score { - \notes - \paper { - linewidth = -1.; - } - } -@end lilypond +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (voltas) are printed, left to right. -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: +@item fold +Alternative endings are written stacked. This has limited use but may be +used to typeset two lines of lyrics in songs with repeats, see +@file{input/star-spangled-banner.ly}. -@lilypond[verbatim,center] - \score { - \notes\context Voice - \paper { - linewidth = -1.; - } - } -@end lilypond +@item tremolo +Make tremolo beams. +@item percent +Make measure repeats. These look like percent signs. +@end table -@cindex relative pitch specification +@menu +* Repeat syntax:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivision:: +* Measure repeats:: +@end menu -@node relative, , , Reference Manual +@node Repeat syntax +@subsection Repeat syntax -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. +The syntax for repeats is @example - - \relative@keyindex{relative} @var{startpitch} @var{musicexpr} + \repeat @var{variant} @var{repeatcount} @var{repeatbody} @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. +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. -@lilypond[fragment,verbatim,center] - \relative c' { - c d e f g a b c c, - } +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 -And octave changing marks are used for intervals greater than a fourth. +With alternative endings: +@lilypond[fragment,verbatim] + c'1 + \repeat volta 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } +@end lilypond + +Folded repeats look like this: + + +@lilypond[fragment,verbatim] + c'1 + \repeat fold 2 {c'4 d' e' f'} + \alternative { {d'2 d'} {f' f} } -@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. +If you don't give enough alternatives for all of the repeats, then +the first alternative is assumed to be repeated often enough to equal +the specified number of repeats. -@lilypond[fragment,verbatim,center] +@lilypond[fragment,verbatim] +\context Staff { \relative c' { - c - - + \partial 4 + \repeat volta 4 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b2. } } } -@end lilypond - -The pitch after the @code{\relative} contains a notename. To parse -the pitch as a notename, you have to be in note mode, so there must -be a surrounding @code{\notes}@keyindex{notes} keyword (which is not -shown here). - -The relative conversion will not affect @code{\transpose} or -@code{\relative} sections in its argument. If you want to use -relative within transposed music, you must place an additional -@code{\relative} inside the @code{\transpose}. +} +@end lilypond -It is strongly recommended to use relative pitch mode: less work, -less error-prone, and more readable. +@refbugs +Notice that timing information is not remembered at the start of an +alternative, so you have to reset timing information after a repeat, +e.g. using a bar-check (See @ref{Bar check}), setting +@code{Score.measurePosition} or entering @code{\partial}. Slurs or ties +are also not repeated. +It is possible to nest @code{\repeat}s, although this probably is only +meaningful for unfolded repeats. -Chord names are a way to generate simultaneous music expressions that -correspond with traditional chord names. It can only be used in -Chord mode (see section @ref{Lexical modes}). +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. +Volta repeats are printed over all staffs in a score. You must turn them +off explicitly, for example by doing @example - - @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}]. + \property Staff.VoltaBracket = \turnOff @end example -@var{tonic} should be the tonic note of the chord, and @var{duration} -is the chord duration in the usual notation. There are two kinds of -modifiers. One type is @emph{chord additions}, which are obtained by -listing intervals separated by dots. An interval is written by its -number with an optional `@code{+}' or `@code{-}' to indicate raising or -lowering by half a step. Chord additions has two effects: It adds -the specified interval and all lower odd numbered intervals to the -chord, and it may lower or raise the specified interval. Intervals -must be separated by a dot (`@code{.}'). +@node Manual repeat commands +@subsection Manual repeat commands -@quotation +@cindex @code{repeatCommands} -@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 - } -} +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 + +@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 +@lilypond[verbatim, fragment] + c''4 + \property Score.repeatCommands = #'((volta "93") end-repeat) + c''4 c''4 + \property Score.repeatCommands = #'((volta #f)) + c''4 c''4 @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 +Repeats brackets are @code{Staff.VoltaBracket} grobs. -@lilypond[fragment,verbatim] -\transpose c'' { - \chords { - c1:m c:min7 c:maj c:aug c:dim c:sus +@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 -@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. +Tremolo beams are @code{Voice.Beam} grobs. Single stem tremolos are +@code{Voice.StemTremolo}. -@lilypond[fragment,verbatim,center] - \transpose c'' { - \chords { - c1^3 c:7^5.3 c:8^7 - } - } -@end lilypond +@refbugs -Chord inversions can be specified by appending `@code{/}@indexcode{/}' and -the name of a single note to a chord. This has the effect of -lowering the specified note by an octave so it becomes the lowest -note in the chord. If the specified note is not in the chord, a -warning will be printed. -@lilypond[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/e c/g c:7/e - } - } +At present, the spacing between tremolo beams is not regular, since the +spacing engine does not notice that not all notes are printed. -@end lilypond +@node Tremolo subdivision +@subsection Tremolo subdivision +@cindex tremolo marks +@cindex @code{tremoloFlags} -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. +Tremolo marks can be printed on a single note by adding +`@code{:}[@var{length}]' after the note. The length must be at least 8. +A @var{length} value of 8 gives one line across the note stem. If the +length is omitted, then then the last value (stored in +@code{Voice.tremoloFlags}) is used. -@lilypond[fragment,verbatim,center] - \transpose c''' { - \chords { - c1 c/+c c/+g c:7/+b - } - } +@lilypond[verbatim,fragment,center] + c'2:8 c':32 | c': c': | +@end lilypond +Using this mechanism pays off when you enter many tremolos, since the +default argument saves typing. -@end lilypond +@refbugs -Throughout these examples, chords have been shifted around the staff -using @code{\transpose}. -You should not combine @code{\relative} with named chords. +Tremolos in this style do not carry over into the MIDI output. +@node Measure repeats +@subsection Measure repeats -@cindex tuplets +@cindex percent repeats +@cindex measure repeats -Tuplets are made out of a music expression by multiplying their -duration with a fraction. +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. +Patterns of a one and two measures are replaced by percent signs, +patterns that divide the measure length are replaced by slashes. -@example +@lilypond[verbatim,singleline] + \context Voice { \repeat "percent" 4 { c'4 } + \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 } +} +@end lilypond - \times@keyindex{times} @var{fraction} @var{musicexpr} -@end example +The signs are represented by these grobs: @code{Voice.RepeatSlash} and +@code{Voice.PercentRepeat} and @code{Voice.DoublePercentRepeat}. -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: +@refbugs -@lilypond[fragment,verbatim,center] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 -@end lilypond +You can not nest percent repeats, e.g. by filling in the first measure +with slashes, and repeating that measure with percents. +@node Rhythmic music +@section Rhythmic music -@cindex grace notes +@menu +* Rhythmic staffs:: +@end menu -@example +@node Rhythmic staffs +@subsection Rhythmic staffs - \grace@keyindex{grace} @var{musicexpr} -@end example +Sometimes 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: -A grace note expression has duration 0; the next real note is -assumed to be the main note. +@lilypond[fragment,relative,verbatim] + \context RhythmicStaff { + \time 4/4 + c4 e8 f g2 | r4 g r2 | g1:32 | r1 | + } +@end lilypond -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}. -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. +@c . {Piano music} +@node Piano music +@section Piano music -@quotation +Piano music is an odd type of notation. Piano staffs are two normal +staffs coupled with a brace. The 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. -@lilypond[fragment,verbatim] -\relative c'' { - \grace c8 c4 \grace { [c16 c16] } c4 - \grace { \property Grace.flagStyle = "" c16 } c4 -} +@menu +* Automatic staff changes:: +* Manual staff switches:: +* Pedals:: +* Arpeggio:: +* Voice follower line:: +@end menu -@end lilypond -@end quotation -At present, nesting @code{\grace}@keyindex{grace} notes, e.g. +@c . {Automatic staff changes} +@node Automatic staff changes +@subsection Automatic staff changes +@cindex Automatic staff changes +Voices can switch automatically between the top and the bottom +staff. The syntax for this is @example - - @code{\grace @{ \grace c32 c16 @} c4} + \autochange @var{contexttype} @var{musicexp} @end example +This will switch the interpretation 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 -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. +Note how spacer rests are used to prevent the bottom staff from +terminating too soon. -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. +@node Manual staff switches +@subsection Manual staff switches +@cindex manual staff switches +@cindex staff switch, manual -@cindex repeats +Voices can be switched between staffs manually, using the following command: +@example + \translator Staff = @var{staffname} @var{music} +@end example +The string @var{staffname} is the name of the staff. It switches the +current voice from its current staff to the Staff called +@var{staffname}. Typically @var{staffname} is @code{"up"} or +@code{"down"}. + +The formal definition of this construct is obtuse, but for the sake of +completeness we give it here. +@cindex @code{\translator} +@example + \translator @var{contexttype} = @var{name} +@end example +Formally, this construct is a music expression indicating +that the context which is a direct child of the context of type +@var{contexttype} should be shifted to a context of type +@var{contexttype} and the specified name. -@node Repeats, , , Reference Manual -In order to specify repeats, use the @code{\repeat}@keyindex{repeat} -keyword. Since repeats look and sound differently when played or -printed, there are a few different variants of repeats. +@c . {Pedals} +@node Pedals +@subsection Pedals +@cindex Pedals -@table @samp - @item unfolded - Repeated music is fully written (played) out. Useful for MIDI - output. +Piano pedal instruction can be expressed using +@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda}, +@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}. - @item volta - This is the normal notation: Repeats are not written out, but - alternative endings (voltas) are printed, left to right. +These identifiers are shorthands for spanner commands of the types +@code{Sustain}, @code{UnaCorda} and @code{Sostenuto}: - @item folded - Alternative endings are written stacked, which is useful for - lyrics. -@end table +@lilypond[fragment,verbatim] +c''4 \spanrequest \start "Sustain" c''4 +c''4 \spanrequest \stop "Sustain" +@end lilypond -The syntax for repeats is +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 of @rgrob{PianoPedal} for +more information. -@example +@refbugs - \repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example -If you have alternative endings, you may add +Currently, brackets are not supported, only text markings (i.e. `*Ped' +style). -@example - \alternative@keyindex{alternative} - @code{@{} @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @code{@}} -@end example +@c . {Arpeggio} +@node Arpeggio +@subsection Arpeggio +@cindex Arpeggio -where each @var{alternative} is a Music expression. +@cindex broken arpeggio +@cindex @code{\arpeggio} -Normal notation repeats are used like this: +You can specify an arpeggio sign on a chord by attaching an +@code{\arpeggio} to a note of the chord. -@quotation -@lilypond[fragment,verbatim] - c'1 - \repeat volta 2 { c'4 d' e' f' } - \repeat volta 2 { f' e' d' c' } +@lilypond[fragment,relative,verbatim] + \context Voice +@end lilypond + +When an arpeggio crosses staffs in piano music, you attach an arpeggio +to the chords in both staffs, and set +@code{PianoStaff.connectArpeggios}. +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.connectArpeggios = ##t + \context Voice = one { } + \context Voice = other { \clef bass } + > @end lilypond -@end quotation -With alternative endings: +This command creates @code{Voice.Arpeggio} grobs. Cross staff arpeggios +are @code{PianoStaff.Arpeggio}. -@quotation +@refbugs -@lilypond[fragment,verbatim] - c'1 - \repeat volta 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } +It is not possible to mix connected arpeggios and unconnected arpeggios +at the same time. -@end lilypond -@end quotation -Folded repeats look like this:@footnote{Folded repeats offer little -more over simultaneous music. However, it is to be expected that -more functionality -- especially for the MIDI backend -- will be -implemented.} -@quotation +@node Voice follower line +@subsection Voice follower line -@lilypond[fragment,verbatim] - c'1 - \repeat fold 2 {c'4 d' e' f'} - \alternative { {d'2 d'} {f' f} } +@cindex follow voice +@cindex staff switching +@cindex cross staff +@cindex @code{followVoice} + +Whenever a voice switches to another staff a line connecting the notes +can be printed automatically. This is enabled if the property +@code{PianoStaff.followVoice} is set to true: + +@lilypond[fragment,relative,verbatim] + \context PianoStaff < + \property PianoStaff.followVoice = ##t + \context Staff \context Voice { + c'1 + \translator Staff=two + b2 a + } + \context Staff=two {\clef bass \skip 1*2 } + > @end lilypond -@end quotation -@quotation +The associated grob is @code{Voice.VoiceFollower}. -@lilypond[fragment,verbatim] -\context Staff { - \relative c' { - \partial 4; - \repeat volta 2 { e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } { a | a a a a | b1 } } - } -} -@end lilypond -@end quotation +@node Lyrics +@section Lyrics -If you don't give enough alternatives for all of the repeats, then -the first alternative is assumed to be repeated often enough to equal -the specified number of repeats. -@quotation +@menu +* Lyrics mode:: +* Printing lyrics:: +* Automatic syllable durations:: +* More stanzas:: +@end menu -@lilypond[fragment,verbatim] -\context Staff { - \relative c' { - \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } - {\partial 1; e4 e e } - {\partial 1; a a a a | b1 } } - } -} +@c . {Lyrics mode} +@node Lyrics mode +@subsection Lyrics mode +@cindex Lyrics mode -@end lilypond -@end quotation +To print lyrics, you must first make a music expression from the lyric +text. That music expression can be printed by selecting an appropriate +context. -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. +@cindex lyric mode +@cindex @code{\lyrics} +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. +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. -@cindex transposition of pitches +Spaces can be introduced into a lyric either by using quotes: +@code{"He could"4 not4} or by using an underscore without quotes: +@code{He_could4 not4}. All unquoted underscores are converted to +spaces. -@node transpose, , , Reference Manual +The precise definition of this mode is in @ref{Lyrics mode +definition}. -A music expression can be transposed with -@code{\transpose}@keyindex{transpose}. The syntax is +@c . {Printing lyrics} +@node Printing lyrics +@subsection Printing lyrics +@cindex lyrics -@example +Lyrics are printed by interpreting them in the @code{Lyrics} context. - \transpose @var{pitch} @var{musicexpr} -@end example +@lilypond[verbatim,singleline] +\addlyrics \notes \relative c' { + \time 7/4 + \property Staff.automaticMelismata = ##t + d'2 c4 b16 ( a g a b a b ) c a2 + b2 c4 b8 ( a16 g ) a4 g2 } + \context Lyrics \lyrics { + Join us now __ and + share the soft -- ware; } +@end lilypond -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. +Notes and syllable durations are 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. -@quotation +The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs. -@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 } -} +@cindex extender +@cindex lyric extender +@cindex melisma -@end lilypond -@end quotation +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{_}). +The grob for this symbol is @code{LyricsVoice.LyricExtender}. -If you want to use both @code{\transpose} and @code{\relative}, then -you must use @code{\transpose} first. @code{\relative} will have no -effect music that appears inside a @code{\transpose}. +@cindex hyphen + +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 whose length varies depending on the space +between syllables. It will be centered between the syllables. The grob +for this symbol is @code{LyricsVoice.LyricHyphen}. + +@cindex Lyric hyphen +@node Automatic syllable durations +@subsection Automatic syllable durations +@cindex Automatic syllable durations @cindex automatic lyric durations +@cindex @code{\addlyrics} -If you have lyrics that are set to a melody, you can import the -rhythm of that melody into the lyrics using @code{\addlyrics}. -@keyindex{addlyrics} The syntax for this is - +If you have lyrics that are set to a melody, you can copy the rhythm +of that melody into the lyrics using @code{\addlyrics}. The syntax for +this is @example - \addlyrics @var{musicexpr1 musicexpr2} @end example -This means that both @var{musicexpr1} and @var{musicexpr2} are -interpreted, but that every non-command atomic music expression -(``every syllable'') in @var{musicexpr2} is interpreted using timing -of @var{musicexpr1}. +Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every +music event (``every syllable'') in @var{musicexpr2} is interpreted only +when there are events in @var{musicexpr1}. + +@cindex @code{automaticMelismata} -If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the +If the property @code{automaticMelismata} is set in the context of @var{musicexpr1}, no lyrics will be put on slurred or tied notes. -@quotation - @lilypond[verbatim,fragment] \addlyrics \transpose c'' { @@ -1730,15 +1994,24 @@ notes. } \context Lyrics \lyrics { do4 re mi fa } - @end lilypond -@end quotation -You should use a single rhythm melody, and single rhythm lyrics (a -constant duration is the obvious choice). If you do not, you will get -undesired effects when using multiple stanzas: +If you want the lyric lines to be above the melody staff, or in some +other, more complex configuration, then build that configuration first +using simultaneous music, and use @code{\addlyrics} after that. + +@lilypond[verbatim, singleline] +\notes < + \context Lyrics = LA { s1 } + \context Staff = SA { s1 } + \addlyrics + \context Staff = SA \relative c' { c4 e g g } + \context Lyrics = LA \lyrics { geen ge -- don -- der } > +@end lilypond -@quotation +For @code{\addlyrics} you should use a single rhythm melody, and single +rhythm lyrics (a constant duration is the obvious choice). If you do +not, you can get undesired effects when using multiple stanzas: @lilypond[verbatim,fragment] \addlyrics @@ -1746,652 +2019,2213 @@ undesired effects when using multiple stanzas: c8 () cis d8. e16 f2 } \context Lyrics \lyrics -< { do4 re mi fa } - { do8 re mi fa } > - +< { do4 re fa sol } + { do8 re fa sol } > @end lilypond -@end quotation It is valid (but probably not very useful) to use notes instead of lyrics for @var{musicexpr2}. +@node More stanzas +@subsection More stanzas +@cindex phrasing +If you have multiple stanzas printed underneath each other, the vertical +groups of syllables should be aligned around punctuation. LilyPond can +do this if you tell it which lyric lines belong to which melody. -@node Ambiguities, , , Reference Manual -@section Ambiguities +To this end, give the Voice context an identity, and set the LyricsVoice +to a name starting with that identity followed by a dash. +In the following example, the Voice +identity is @code{duet}, and the identities of the LyricsVoices are +@code{duet-1} and @code{duet-2}. -@cindex ambiguities -The grammar contains a number of ambiguities.@footnote{The authors -hope to resolve them at a later time.} +@lilypond[singleline,verbatim] +\score { +\addlyrics + \notes \relative c'' \context Voice = duet { \time 3/4 + g2 e4 a2 f4 g2. } + \lyrics \context Lyrics < + \context LyricsVoice = "duet-1" { + \property LyricsVoice . stanza = "Bert" + Hi, my name is bert. } + \context LyricsVoice = "duet-2" { + \property LyricsVoice . stanza = "Ernie" + Ooooo, ch\'e -- ri, je t'aime. } + > +} +@end lilypond -@itemize @bullet - @item The assignment +You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the +first system) and @code{LyricsVoice.stz} for the following +systems. Notice how you must surround dots with spaces in @code{\lyrics} +mode. - @example -foo = bar -@end example - can be interpreted as making a string identifier @code{\foo} - containing @code{"bar"}, or a music identifier @code{\foo} - containing the syllable `bar'. - - @item The assignment - - @example -foo = -6 -@end example - - can be interpreted as making an integer identifier - containing -6, or a Request identifier containing the - fingering `6' (with neutral direction). - - @item If you do a nested repeat like - - @quotation - -@example -\repeat @dots{} -\repeat @dots{} -\alternative -@end example - @end quotation - - then it is ambiguous to which @code{\repeat} the - @code{\alternative} belongs. This is the classic if-then-else - dilemma. It may be solved by using braces. - - @item (an as yet unidentified ambiguity :-) -@end itemize +@cindex stanza numbering -@node Notation conversion specifics, , , Reference Manual -@section Notation conversion specifics +@c . {Chords} +@node Chords +@section Chords +@cindex Chords +LilyPond has support for both entering and printing chords. Chords are +characterized by a set of pitches. They are +internally stored as simultaneous music expressions. This means you can +enter chords by name and print them as note head, enter them as notes +and print them as chord names, or (the most common case) enter them by +name, and print them as name. -@cindex automatic beam generation +@lilypond[verbatim,singleline] +twoWays = \notes \transpose c'' { + \chords { + c1 f:sus4 bes/f + } + + + + } -@node autobeam, , , Reference Manual +\score { + < \context ChordNames \twoWays + \context Voice \twoWays > } +@end lilypond -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. +Note that this example also shows that the chord printing routines do +not attempt to be intelligent. If you enter @code{f bes d}, it does not +interpret this as an inversion. +@menu +* Chords mode:: +* Printing named chords:: +@end menu -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}. +@c . {Chords mode} +@node Chords mode +@subsection Chords mode +@cindex Chords mode -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}. +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 -@cindex chord names +@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 formed by @emph{chord additions}. Additions 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 have two effects: they adds +the specified interval and all lower odd numbered intervals to the +chord, and they may lower or raise the specified interval. -@cindex chords +Throughout these examples, chords have been shifted around the staff +using @code{\transpose}. -@cindex printing!chord names +@lilypond[fragment,verbatim] +\transpose c'' { + \chords { + c1 c:3- c:7 c:8 + c:9 c:9-.5+.7+ c:3-.5- + } +} +@end lilypond -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. +@cindex @code{aug} +@cindex @code{dim} +@cindex @code{maj} +@cindex @code{sus} -@quotation +The second type of modifier that may appear after the @code{:} is a +named modifier. Named modifiers are listed in the file +@file{chord-modifiers.ly}. The available modifiers are @code{m} and +@code{min} which lower the 3rd half a step, `@code{aug}' which +raises the 5th, `@code{dim}' which lowers the 5th, +`@code{maj}' which adds a raised 7th, and `@code{sus}' +which replaces the 5th with a 4th. @lilypond[fragment,verbatim] -< - \context ChordNames { - \chords{a b c} \notes{ } - } - \context Staff \notes { - a b c' d' e' +\transpose c'' { + \chords { + c1:m c:min7 c:maj c:aug c:dim c:sus } -> - +} @end lilypond -@end quotation + -LilyPond examines chords specified as lists of notes to determine a -name to give the chord. By default, LilyPond will not try to -identify chord inversions: +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] - < - \context ChordNameVoice \notes { - - } - \context Thread \notes { - + \transpose c'' { + \chords { + c1^3 c:7^5.3 c:8^7 } - > -@end lilypond + } +@end lilypond +@cindex @code{/} -If you want inversions to be recognized, you must set the property -@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}: +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 note +is not in the chord, a warning will be printed. @lilypond[fragment,verbatim,center] - < - \property Score.chordInversion = ##t - \context ChordNameVoice \notes { - - } - \context Thread \notes { - + \transpose c''' { + \chords { + c1 c/e c/g c:7/e } - > -@end lilypond + } + +@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 -@cindex lyrics +@refbugs -@cindex printing!lyrics +Implementation details are quite gory. For example @code{c:4} not only +adds a fourth, but also removes the third. -@node lyricprint, , , Reference Manual -Lyric syllables must be interpreted within a @code{Lyrics} context +@c . {Printing named chords} +@node Printing named chords +@subsection Printing named chords -@cindex context!Lyrics - for printing them. +@cindex printing chord names +@cindex chord names +@cindex chords +@cindex @code{ChordNames} -Here is a full example: -@quotation +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. -@lilypond[verbatim] +@lilypond[verbatim,singleline] +scheme = \notes { + \chords {a1 b c} +} \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 - } + \notes< + \context ChordNames \scheme + \context Staff \transpose c'' \scheme > } +@end lilypond + +You can make the chord changes stand out by setting +@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. +@lilypond[verbatim] +scheme = \chords { + c1:m c:m \break c:m c:m d +} +\score { + \notes < + \context ChordNames { + \property ChordNames.chordChanges = ##t + \scheme } + \context Staff \transpose c'' \scheme + > } @end lilypond -@end quotation -You may want a continuous line after the syllables to show melismata. -To achieve this effect, add a `@code{__}' lyric as a separate word -after the lyric to be extended. This will create an extender, a line -that extends over the entire duration of the lyric. This line will -run all the way to the start of the next lyric, so you may want to -shorten it by using a blank lyric (using `@code{_}'). +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 +an added bass note, which may result in strange chord names when chords +are entered as a list of pitches: -@quotation +@lilypond[verbatim,center,singleline] +scheme = \notes { + + + +} -@lilypond[verbatim] \score { < - \notes \relative c'' { - a4 () b () c () d | c () d () b () a | c () d () b () a - } - \context Lyrics \lyrics { - foo1 __ | bar2. __ _4 | baz1 __ - } + \context ChordNames \scheme + \context Staff \scheme > } - @end lilypond -@end quotation - -If you want to have hyphens centered between syllables (rather than -attached to the end of the first syllable) you can use the special -`@code{-}@code{-}' lyric as a separate word between syllables. This -will result in a hyphen which length varies depending on the space -between syllables, and which will be centered between the syllables. -For example: -@quotation +By default, a chord name system proposed by Harald Banter (See +@ref{Literature}) is used. The system is very regular and predictable. +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}. Here's an example showing the differences in +chord name styles: + +@c too long? +@c maybe just junk verbatim option? +@lilypond[verbatim,singleline] +scheme = \chords { + c1 c:5^3 c:4^3 c:5+ + c:m7+ c:m5-.7 + c:5-.7 c:5+.7 + c:9^7 +} -@lilypond[verbatim] \score { - < - \notes \transpose c'' { - c d e c | c d e c | - e f g2 | e4 f g2 \bar "|."; - } - \context Lyrics \lyrics { - Va4 -- der Ja -- cob | Va -- der Ja -- cob | - Slaapt gij nog?2 | Slaapt4 gij nog?2 - } + \notes < + \context ChordNames = banter \scheme + \context ChordNames = american { + \property ChordNames.ChordName \override + #'style = #'american \scheme } + \context ChordNames = jazz { + \property ChordNames.ChordName \override + #'style = #'jazz \scheme } + \context Staff \transpose c'' \scheme > } - @end lilypond -@end quotation +@node Writing parts +@section Writing parts -@node Notation Contexts, , , Reference Manual -@section Notation Contexts +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. -@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. +@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 -A context is an object that holds the reading state of the -expression; it contains information like +@c . {Rehearsal marks} +@node Rehearsal marks +@subsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} +@cindex @code{Mark_engraver} -@itemize @bullet - @item What notes are playing at this point? - @item What symbols will be printed at this point? - @item In what style will they printed? - @item What is the current key signature, time signature, point within - the measure, etc.? -@end itemize +@example + \mark @var{unsigned} + \mark @var{string} + \mark \default +@end example -Contexts are grouped hierarchically: A @code{Voice} context is -contained in a @code{Staff} context (because a staff can contain -multiple voices at any point), a @code{Staff} context is contained in -a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because -these can all contain multiple staffs). +This command prints a rehearsal mark above the system. You can provide +a number, a string or a markup text as argument. If you use +@code{\default}, the value of property @code{rehearsalMark} is used and +automatically incremented. -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called playing contexts. +@lilypond[fragment,verbatim] +\relative c'' { + c1 \mark "A2" + c1 \mark \default + c1 \mark \default + c1 \mark "12" + c1 \mark #'(music "scripts-segno") + c1 +} +@end lilypond -Contexts are created either manually or automatically. Initially, -the top level music expression is interpreted by the top level -context (the @code{Score} context). When a atomic music expression -(i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested -set of contexts is created that can process these atomic expressions, -as in this example: +The grob is @code{Score.RehearsalMark}. See +@code{input/test/boxed-molecule.ly} if you need boxes around the marks. -@example +@node Bar numbers +@subsection Bar numbers - @example -\score @{ \notes < c4 > @} -@end example +Bar numbers (grob: @code{BarNumber}) are printed at the start of the +line. See @code{input/test/boxed-molecule.ly} for boxed bar numbers. -@end example +@refbugs -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. +It is not possible to have bar numbers printed at regular intervals +only. +@node Instrument names +@subsection Instrument names -@cindex context +You can specify an instrument name for a staff by setting +@code{Staff.instrument} and @code{Staff.instr}. This will print a string +before the start of the staff. For the first start, @code{instrument} is +used, for the next ones @code{instr} is used. -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. +@lilypond[verbatim,singleline] + \property Staff.instrument = "ploink " { c''4 } +@end lilypond -If a context of the specified type and name can not be found, a new -one is created. For example, +You can also use markup texts to construct more complicated instrument +names: -@quotation -@lilypond[verbatim] -\score { - \notes \relative c'' { - c4 f - } -} +@lilypond[verbatim,singleline] +#(define text-flat + '((font-relative-size . -2 ) (music "accidentals--1"))) +\score { \notes { + \property Staff.instrument = #`((kern . 0.5) (lines + "2 Clarinetti" (columns " (B" ,text-flat ")"))) + c'' 4 } +} @end lilypond -@end quotation -In this example, the @code{c} and @code{d} are printed on the -default staff. For the @code{e}, a context Staff called -`@code{another}' is specified; since that does not exist, a new -context is created. Within @code{another}, a (default) Voice context -is created for the @code{e4}. When all music referring to a -context is finished, the context is ended as well. So after the -third quarter, @code{another} is removed. -Almost all music expressions inherit their interpretation context -from their parent. In other words, suppose that the syntax for a -music expression is +@refbugs -@example +When you put a name on a grand staff or piano staff the width of the +brace is not taken into account. You must add extra spaces to the end of +the name to avoid a collision. + +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} - \keyword @var{musicexpr1} @var{musicexpr2} @dots{} +A music expression can be transposed with @code{\transpose}. The syntax +is +@example + \transpose @var{pitch} @var{musicexpr} @end example -When the interpretation of this music expression starts, the context -for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total -expression. +This means that middle C in @var{musicexpr} is transposed to +@var{pitch}. -Lastly, you may wonder, why this: +@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 -@example -\score @{ - \notes \relative c'' @{ - c4 d4 e4 - @} -@} -@end example +If you want to use both @code{\transpose} and @code{\relative}, then +you must use @code{\transpose} first. @code{\relative} will have no +effect music that appears inside a @code{\transpose}. -@end quotation +@node Sound output for transposing instruments +@subsection Sound output transposing instruments -doesn't result in this: +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. -@lilypond[] +@cindex @code{transposing} - \score { - \notes \relative c'' { - - } - } +@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 full bar rests and 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. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4 @end lilypond -For the @code{c4}, a default @code{Staff} (with a contained -@code{Voice}) context is created. After the @code{c4} ends, no -music refers to this default staff, so it would be ended, with the -result shown. To prevent this inconvenient behavior, the context to -which the sequential music refers is adjusted during the -interpretation. So after the @code{c4} ends, the context of the -sequential music is also the default @code{Voice} context. -The @code{d4} gets interpreted in the same context -as @code{c4}. +Notice that the @code{R2.} is printed as a whole rest, centered in the +measure. +@cindex whole rests for a full measure +@refbugs -These are the contexts supplied with the package. They are defined -in the initialization file @file{ly/engraver.ly}. +Currently, there is no way to condense multiple rests into a single +multimeasure rest. -@table @samp -@end table +@cindex condensing rests +@node Automatic part combining +@subsection Automatic part combining +@cindex automatic part combining +@cindex part combiner -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. +Automatic part combining is used to merge two parts of music onto a +staff in an intelligent way. It is aimed primarily at typesetting +orchestral scores. When the two parts are identical for a period of +time, only one is shown. In places where the two parts differ, they are +typeset as separate voices, and stem directions are set automatically. +Also, solo and @emph{a due} parts can be identified and marked. -Properties can be preset within the @code{\translator} block -corresponding to the appropriate context. In this case, the syntax -is +The syntax for part combining is @example - - @var{propname} @code{=} @var{value} + \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 of type @var{context}. The music expressions +must be interpreted by contexts whose names should start with @code{one} +and @code{two}. + +The most useful function of the part combiner is to combine parts 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 r4 r f + } + > +@end lilypond + +Notice that the first @code{g} appears only once, although it was +specified twice (once in each part). Stem, slur and tie directions are +set automatically, depending whether there is a solo or unisono. The +first part (with context called @code{one}) always gets up stems, and +`solo', while the second (called @code{two}) always gets down stems and +`Solo II'. + +If you just want the merging parts, and not the textual markings, you +may set the property @var{soloADue} to false. + +@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 -This assignment happens before interpretation starts, so a -@code{\property} expression will override any predefined settings. +There are a number of other properties that you can use to tweak the +behavior of part combining, refer to the automatically generated +documentation of @reng{Thread_devnull_engraver} and +@reng{Voice_devnull_engraver}. Look at the documentation of the +responsible engravers, @code{Thread_devnull_engraver}, +@code{Voice_devnull_engraver} and @code{A2_engraver}. -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. +@refbugs -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}. +In @code{soloADue} mode, when the two voices play the same notes on and +off, the part combiner may typeset @code{a2} more than once in a +measure. -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. +@lilypond[fragment,singleline] + \context Staff < + \context Voice=one \partcombine Voice + \context Thread=one \relative c'' { + c b c b c a c a + } + \context Thread=two \relative c'' { + b b b b f a f a + } + > +@end lilypond -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. +@cindex @code{Thread_devnull_engraver} +@cindex @code{Voice_engraver} +@cindex @code{A2_engraver} -@mbinclude properties.itely +@node Hara kiri staffs +@subsection Hara kiri staffs -@node Notation output definitions, , , Reference Manual -@section Notation output definitions +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. It will +not disappear when it contains normal rests, you must use multi measure +rests. -@cindex output +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. -@cindex notation output +@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 -@cindex output definition -@node paper, , , Reference Manual -The most important output definition is the @code{\paper} block, for -music notation. The syntax is +@c . {Custodes} +@node Custodes +@section Custodes +@cindex Custos +@cindex Custodes + +A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a +staff context symbol that appears at the end of a staff line. It +anticipates the pitch of the first note(s) of the following line and +thus helps the player or singer to manage line breaks during +performance, thus enhancing readability of a score. + +@lilypond[verbatim] +\score { + \notes { c'1 \break + \property Staff.Custos \set #'style = #'mensural + d' } + \paper { + \translator { + \StaffContext + \consists Custos_engraver + } + } +} +@end lilypond + +Custodes were frequently used in music notation until the 16th century. +There were different appearances 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 - @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}} +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 -where each of the items is one of +@c . {Tuning output} +@node Tuning output +@section Tuning output -@itemize @bullet - @item An assignment. The assignment must be terminated by a - semicolon. +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. + +Formatting is internally done by manipulating 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 direct way of tuning the output is by altering 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 in that object. + +@menu +* Tuning groups of grobs :: +* Tuning per grob :: +* What to tune?:: +* Font selection:: +* Text markup:: +* Invisible grobs:: +* Dirty tricks:: +@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 = #'((meta . ((interfaces . ())))) c'4 +@end lilypond + +The @code{\property} assignment effectively empties the definition of +the Stem object. One of the effects is the recipe of how it should be +printed is erased, with the effect of rendering it invisible. The above +assignment is available as a standard identifier, for the case that you +find this useful: + +@example + \property Voice.Stem = \turnOff +@end example + +@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. + +The definition of a grob is actually a list of default grob +properties. For example, the definition of the Stem grob (available in +@file{scm/grob-description.scm}), defines the following values for +@code{Stem} + +@example + (thickness . 0.8) + (beamed-lengths . (0.0 2.5 2.0 1.5)) + (Y-extent-callback . ,Stem::height) + @var{...} +@end example + +You can add a property on top of the existing definition, or remove a +property, thus overriding the system defaults: +@lilypond[verbatim] +c'4 \property Voice.Stem \override #'thickness = #4.0 +c'4 \property Voice.Stem \revert #'thickness +c'4 +@end lilypond +You should balance @code{\override} and @code{\revert}. If that's too +much work, you can use the @code{\set} shorthand. It performs a revert +followed by an override. The following example gives exactly the same +result as the previous one. +@lilypond[verbatim] +c'4 \property Voice.Stem \set #'thickness = #4.0 +c'4 \property Voice.Stem \set #'thickness = #0.8 +c'4 +@end lilypond +If you use @code{\set}, you must explicitly restore the default. + + +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. + + +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, @code{\override} and @code{\revert}, +must be carefully balanced. + +These are examples of correct nesting of @code{\override}, @code{\set}, +@code{\revert}. + +A clumsy but correct form: +@example + \override \revert \override \revert \override \revert +@end example + +Shorter version of the same: +@example + \override \set \set \revert +@end example + +A short form, using only @code{\set}. This requires you to know the +default value: +@example + \set \set \set \set @var{to default value} +@end example + +If there is no default (i.e. by default, the grob property is unset), +then you can use +@example + \set \set \set \revert +@end example + +For the digirati, the grob description is an Scheme association +list. Since a Scheme list is a singly linked list, 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. + +@refbugs + +LilyPond will hang or crash if @var{value} contains cyclic references. +The backend is not very strict in type-checking grob properties. If you +@code{\revert} properties that are expected to be set by default, +LilyPond may crash. + +Some grobs are created at the moment that their context is created. An +example of such a grob is the staff itself (i.e. the horizontal lines). +You can not change the appearance of the staff symbol by manipulating +@code{\property Staff.StaffSymbol}. At the moment that @code{\property +Staff} is interpreted, a Staff context is made, and the StaffSymbol is +created before any @code{\override} is effective. You can deal with this +either overriding properties in a @code{\translator} definition, or by +using @code{\outputproperty}. + + + + +@node Tuning per grob +@subsection Tuning per grob + +@cindex \outputproperty + +A second way of tuning grobs is the more arcane @code{\outputproperty} +feature. The 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. + +Here are some random examples. + + +In the following example, all note heads occurring at current staff +level, are shifted up and right by setting their @code{extra-offset} +property. + +@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} + +In this example, the predicate checks the @code{text} grob property, to +shift only the `m.d.' text, 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 + +@refbugs + +If possible, avoid this feature: the semantics are not very clean, and +the syntax and semantics are up for rewrite. + + + + +@node What to tune? +@subsection What to tune? + +This all tells you how to tune grobs, but you don't know what variables +to set? 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 is in the +automatically generated documentation. Description of properties are +generated from the source code for each version. This documentation is +therefore more up to date. 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. Selecting a grob will take you to an overview of the +properties available for that grob. + +There is also a master list of contexts. Selecting one takes you to an +overview of that context which lists 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 La@TeX{}'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 + A symbol indicating the general class of the typeface. Supported are +@code{roman} (Computer Modern), @code{braces} (for piano staff braces), +@code{music} (the standard music font), @code{dynamic} (font for dynamic +signs) and @code{typewriter} + +@item font-shape + A symbol indicating the shape of the font, a finer gradation than + font-family. Choices are @code{italic}, @code{caps} and @code{upright} + +@item font-series +A symbol indicating the series of the font. @code{font-series} form a +finer gradation + than @code{font-shape}. Choices are @code{medium} and @code{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, e.g. @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 @code{volta}, @code{finger}, @code{tuplet}, +@code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large} +and @code{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 magnification of particular fonts, +meaning that you don't have access to continuously scaled fonts. You +can scale the entire output, of course, see @ref{Output scaling}. + +There is no style sheet provided for other fonts besides the @TeX{} +family. + +@cindex font selection +@cindex font magnification +@cindex @code{font-interface} + + +@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" ((raise . 2.4) "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{columns lines roman music bold italic named super sub +overstrike 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. A list of properties available is included in +the generated documentation for @rint{Text_interface}. + +The following abbreviations are currently defined: +@table @code +@item columns + horizontal mode: set all text on one line (default) +@item lines + vertical mode: set every text on a new line +@item roman + select roman font +@item music + selects the Feta font (the standard font for music notation glyphs), +and uses named lookup + +@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 overstrike + the next text or character overstrikes this one +@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 + + +@cindex metronome mark + +One practical application of complicated markup is to fake a metronome +marking: + +@lilypond[verbatim] +#(define note '(columns + (music "noteheads-2" ((kern . -0.1) "flags-stem")))) +#(define eight-note `(columns ,note ((kern . -0.1) + (music ((raise . 3.5) "flags-u3"))))) +#(define dotted-eight-note + `(columns ,eight-note (music "dots-dot"))) + +\score { + \notes\relative c'' { + a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64") + } + \paper { + linewidth = -1. + \translator{ + \ScoreContext + TextScript \override #'font-shape = #'upright + } + } +} +@end lilypond + +@node Invisible grobs +@subsection Invisible grobs +@cindex invisible grobs + +@ignore + +ben nog steeds niet kapot van de informatiedichtheid hier. + +--hwn + +@end ignore + +You can imagine a number of situations where you would want to make +certain grobs not show up in the output. There may be aesthetic +reasons, to make the output resemble an (old) manuscript as close as +possible, or to make lessons or exercises for students. + +Grobs can be made invisible in a number of ways: + +Here's an example with blanked-out notes and stems: +@lilypond[singleline,verbatim] +blanknotes = { + \property Voice.NoteHead \override + #'transparent = ##t + \property Voice.Stem \override + #'transparent = ##t } + +unblanknotes = { + \property Voice.NoteHead \revert #'transparent + \property Voice.Stem \revert #'transparent } + +\score { + \notes\relative c'' { + \time 6/4 + a b c b \blanknotes c \unblanknotes d + } +} +@end lilypond + +A very rigorous way of removing grobs from the output is to remove the +engraver that creates them. For example, + +@lilypond[verbatim] +\score {\notes { c'4 d'8 e'8 g2 } + \paper { \translator { + \VoiceContext + \remove Stem_engraver + } } +} +@end lilypond + + +@node Dirty tricks +@subsection Dirty tricks +@cindex embedded tex + +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 (see @ref{PostScript +output}). + +@lilypond[fragment,relative,verbatim] + a''^"3 $\\times$ \\`a deux" +@end lilypond + +You can also use raw PostScript commands embedded in text scripts. This +offers ultimate flexibility, but requires you to learn PostScript. +Currently, embedded PostScript will @strong{not} work with direct +PostScript output. Note that all dimensions that you use are in staff +space. + +@lilypond[verbatim] +\score { + \notes \relative c'' { + a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}" + -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}" + b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}" + s2 + a'1 + } + \paper { linewidth = 70*\staffspace } +} +@end lilypond + + +@c . {Page layout} +@node Page layout +@section Page layout +@cindex Page layout + +The page layout is the combined product of LilyPond formatting notation, +and (La)@TeX{} putting the notation on a page, including page breaks. +The part of LilyPond is documented here. + +@menu +* Paper block:: +* Paper variables:: +* Font Size:: +* Paper size:: +* Line break:: +* Page break:: +* Output scaling:: +@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. + + @item A context definition. See @ref{Interpretation context} 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 @code{\elementdescriptions} declaration. + @example + \elementdescriptions @var{alist} + @end example + See @file{scm/grob-description.scm} for details of +@var{alist}. This command is not user-serviceable. + +@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. + +@cindex @code{linewidth} + @item @code{linewidth} + Sets the width of the lines. + +If set to a negative value, a single unjustified line is produced. +@c rename to singleLinePaper ? +The shorthand @code{\singleLine} defines a default paper block that +produces a single line. + +@cindex @code{textheight} + + @item @code{textheight} + Sets the total height of the music on each page. Only used by +@code{ly2dvi}. + +@cindex @code{interscoreline} + + @item @code{interscoreline} + Sets the spacing between systems. +Not set by default. +@cindex @code{interscorelinefill} + + @item @code{interscorelinefill} + If set to a positive number, the distance between the score + lines will stretch in order to fill the full page. In that + case @code{interscoreline} specifies the minimum spacing. + + Not set by default. + + +@cindex @code{stafflinethickness} + + @item @code{stafflinethickness} + Determines the thickness of staff lines, and also acts as a scaling + parameter for other line thicknesses. +@end table + +You may enter these dimension using units (@code{cm}, @code{in}, +@code{mm}, @code{pt}), or relative to another dimension +@example + linewidth = 20.0 * \staffspace + indent = 0.5 \cm +@end example + + +@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{scm/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. + +@example + papersize = "a4" + \include "paper16.ly" +@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}) + +@c . {Line break} +@node Line break +@subsection Line break + +@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 bar lines. If you want to have a line break where there is no +bar line, you can force an invisible bar line by entering @code{\bar +""}. Similarly, @code{\noBreak} forbids a line break at a certain point. + +@cindex @code{\penalty} + +The @code{\break} and @code{\noBreak} commands are defined in terms of +the penalty command: +@example + \penalty @var{int} +@end example + +This encourages or discourages LilyPond to make a line break at this +point. + +@refbugs + +The scaling of the @code{\penalty} argument is not well-defined. The +command is rather kludgey, 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, by inserting +the command @code{\newpage} +@cindex @code{\newpage} + +@example + \newpage +@end example + +@c why do so difficult? +@c maybe should explain contents of between-system.ly, +@c but not now, we're talking about page breaks here. +@c For more +@c details, see the example file @file{input/test/between-systems.ly} + + +@c . {Output scaling} +@node Output scaling +@subsection Output scaling + +[TODO] + +@example +dvips ... +@end example + +@example +pstops ... +@end example + + +@refbugs +There is no mechanism to select magnification of particular fonts, +meaning that you don't have access to continuously scaled fonts. + + + +@c . {Output formats} +@node Output formats +@section Output formats + +LilyPond can output processed music in different output formats. + +@menu +* TeX output:: +* PostScript output:: +* Scheme output:: +* ASCIIScript output:: +@end menu + +@node TeX output +@subsection TeX output +@cindex TeX output + +LilyPond will use @TeX{} by default. Even if you want to produce +PostScript output for viewing or printing, you should normally have +LilyPond produce @TeX{} first. The .tex output must be processed by +@TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips} +is used to generate PostScript. Alternatively, @file{ly2dvi} can be +used to generate the .dvi for you. + +@refbugs + +Titling is not generated. + + +@node PostScript output +@subsection PostScript output +@cindex PostScript output +@cindex direct PostScript output + +LilyPond can produce PostScript directly, without going through @TeX{}. +Currently, this is mainly useful if you cannot use TeX, because direct +PostScript output has some problems; see Bugs below. + +@example +$ lilypond -fps foo.ly +GNU LilyPond 1.3.144 +Now processing: `foo.ly' +Parsing... +Interpreting music...[3] +Preprocessing elements... +Calculating column positions... +paper output to foo.ps... + +$ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr +@end example + + +@refbugs + +Text font selection is broken. + +The .ps file does not contain the .pfa font files. To print a .ps +created through direct postscript output, you should prepend the +necessary .pfa files to LilyPond's .ps output, or upload them to the +printer before printing. + +The line height calculation is broken, you must set @var{lineheight} in +the paperblock if you have more than one staff in your score, e.g. + +@example + ... + \paper @{ + % Set line height to 40 staff spaces + lineheight = 40 + @} +@end example + +@node Scheme output +@subsection Scheme output +@cindex Scheme output + +In the typesetting stage, LilyPond builds a page description, which is +then written to disk in postscript, @TeX{} or ASCII art. Before it is +written, the page description is represented as Scheme expressions. You +can also dump these Scheme expressions to a file, which may be +convenient for debugging output routines. This done with the Scheme +output format + +@example +$ lilypond -fscm foo.ly +GNU LilyPond 1.3.144 +Now processing: `foo.ly' +Parsing... +Interpreting music...[3] +Preprocessing elements... +Calculating column positions... +paper output to foo.scm... + +$ head -4 foo.scm +;;; Usage: guile -s x.scm > x.tex + (primitive-load-path 'standalone.scm) +; (scm-tex-output) + (scm-ps-output) + +$ guile -s foo.scm > foo.tex +@end example + + +@node ASCIIScript output +@subsection ASCIIScript output +@cindex ASCIIScript output +@cindex ascii script +@cindex ascii art + +LilyPond can output ASCII Art. This is a two step process, LilyPond +produces an ASCII description file, dubbed ASCIIScript (extension +@file{.as}). ASCIIScript has a small and simple command set that +includes font selection, character and string printing and line drawing +commands. The program @file{as2text} is used to translate an .as file +to text. + +To produce ASCII Art, you must include an ASCII Art paper definition +file in your .ly, one of: +@example +\include "paper-as5.ly" +\include "paper-as9.ly" +@end example + +Here's an example use for ASCII Art output (the example file +@file{as-email.ly} is included in the LilyPond distribution), the staff +symbol has been made invisible: + +@example +$ lilypond -fas as-email.ly +GNU LilyPond 1.3.144 +Now processing: `as-email.ly' +Parsing... +Interpreting music...[3] +Preprocessing elements... +Calculating column positions... [2] +paper output to as-email.as... + +$ as2text as-email.as 2>/dev/null + |\ + |/ |##|##| | | | | | + /| | | | | |\ |\ |\ |\ |\ | + / |_ 3 | | | | 5 | )| )| )| )| )| + | /| \ 8 * * * | 8 * * * * * | + \_|_/ | | + *_| + + lily +@end example + + +@refbugs + +The ASCII Art fonts are far from complete and not very well designed. +It's easy to change the glyphs, though; if you think you can do better, +have a look at @file{mf/*.af}. + +Lots of resizable symbols such as slurs, ties, tuplets are missing. + +The poor looks of most ASCII Art output and its limited general +usefulness make that ASCII Art output has a low priority; it may be +dropped in future versions. + +@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, etc., but it +is good enough for proof-hearing the music you have entered. Ties, +dynamics and tempo changes are interpreted. + +Dynamic marks, crescendi and decrescendi translate into MIDI volume +levels. Dynamic marks translate to a fixed fraction of the available +MIDI volume range, crescendi and decrescendi make the the volume vary +linearly between their two extremities. The fractions be adjusted by +overriding the @code{absolute-volume-alist} defined in +@file{scm/midi.scm}. + +For each type of musical instrument (that MIDI supports), a volume range +can be defined. This gives you basic equalizer control, which can +enhance the quality of the MIDI output remarkably. You can add +instruments and ranges or change the default settings by overriding the +@code{instrument-equalizer-alist} defined in @file{scm/midi.scm}. + +Both loudness controls are combined to produce the final MIDI volume. + + +@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 (Grand 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 + +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 +(This distance is determined without regarding alterations; a +@code{fisis} following a @code{ceses} will be put above the +@code{ceses}) + +The octave changing marks @code{'} and @code{,} can 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 music that changes octave frequently is easy in relative mode. +@lilypond[fragment,singleline,verbatim,center] + \relative c'' { + b c d c b c bes a + } +@end lilypond + +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} + +The pitch after the @code{\relative} contains a note name. To parse +the pitch as a note name, you have to be in note mode, so there must +be a surrounding @code{\notes} keyword (which is not +shown here). + +The relative conversion will not affect @code{\transpose}, +@code{\chords} or @code{\relative} sections in its argument. If you +want to use relative within transposed music, you must place an +additional @code{\relative} inside the @code{\transpose}. + + +@c . {Bar check} +@node Bar check +@subsection Bar check +@cindex Bar check + +@cindex bar check +@cindex @code{barCheckNoSynchronize} +@cindex @code{|} + + +Whenever a bar check is encountered during interpretation, a warning +message is issued if it doesn't fall at a measure boundary. This can +help you find errors in the input. Depending on the value of +@code{barCheckNoSynchronize}, the beginning of the measure will be +relocated, so this can also be used to shorten measures. + +A bar check is entered using the bar symbol, @code{|}: +@example + \time 3/4 c2 e4 | g2. +@end example + +@c . {Point and click} +@node Point and click +@subsection Point and click + +Point and click lets you find notes in the input by clicking on them in +the Xdvi window. This makes it very easy to find input that causes some +error in the sheet music. + +To use it, you need the following software + +@unnumberedsubsec Installation + +@itemize @bullet +@item +@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain +Xdvi} version 22.36 or newer. + + Note that most @TeX{} distributions ship with xdvik, which is a + different and less well maintained program. To find out which xdvi you + are running, try @code{xdvi --version} or @code{xdvi.bin --version}. +@item emacs +@end itemize + +Xdvi must be configured to find the TeX fonts and music +fonts. Refer to the Xdvi documentation for more information. + + +@unnumberedsubsec Using it + +Add one of 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} and @code{server.el}. + +@example +#(set! point-and-click line-location) +@end example + +In the emacs startup file (usually @file{~/.emacs}), add the following +@example +(server-start) +@end example + +Make sure that the environment variable @code{XEDITOR} is set +to +@example +emacsclient --no-wait +%l %f +@end example +The second one, that also specifies the column, only works if you have +patched your emacsclient and server, and have compiled your @code{.ly} +file using the @code{line-column-location} setting. + +When viewing, control-mousebutton 1 will take you to the originating +spot in the @file{.ly} file. Control-mousebutton 2 will show all +clickable boxes. + + +@unnumberedsubsec Column location + +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 +(e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs} +init file, before invoking server-start. + +@example + (setq load-path (cons "~/usr/share/emacs" load-path)) +@end example + +Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f} + +At the top of the @code{ly} file, replace the @code{set!} line with the +following line +@example +#(set! point-and-click line-column-location) +@end example + + + +@refbugs + +When you convert the @TeX{} file to PostScript using @code{dvips}, it +will complain about not finding @code{src:X:Y} files. Those complaints +are harmless, and can be ignored. + +When using @code{line-colum-location}, the cursor will be one off; it +will not jump to the exact note that you clicked, but to the next one. + +[FIXME] + +@node Skipping corrected music +@section Skipping corrected music + +The property @code{Score.skipTypesetting} can be used to switch on and +off typesetting completely during the interpretation phase. When +typesetting is switched off, the music is processed much more quickly. +You can use this to skip over the parts of a score that you have already +checked for errors. + +@lilypond[fragment,singleline,verbatim] +\relative c'' { c8 d +\property Score.skipTypesetting = ##t + e f g a g c, f e d +\property Score.skipTypesetting = ##f +c d b bes a g c2 } +@end lilypond + + +@node Interpretation context +@section Interpretation context + +@menu +* Creating contexts:: +* Default contexts:: +* Context properties:: +* Engravers and performers:: +* Changing context definitions:: +* Defining new contexts:: +@end menu + + +Interpretation contexts are objects that only exist during a run of +LilyPond. During the interpretation phase of LilyPond (when it prints +"interpreting music"), the music expression in a @code{\score} block is +interpreted in time order. This is the same order that humans hear and +play music. + +During this interpretation, the interpretation context is holds the +state for the current point within the music. It contains information +like + +@itemize @bullet + @item What notes are playing at this point? + @item What symbols will be printed at this point? + @item What is the current key signature, time signature, point within + the measure, etc.? +@end itemize + +Contexts are grouped hierarchically: A @code{Voice} context is +contained in a @code{Staff} context (because a staff can contain +multiple voices at any point), a @code{Staff} context is contained in +@code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context. + +Contexts associated with sheet music output are called @emph{notation +contexts}, those for sound output are called @emph{performance +contexts}. + + +@node Creating contexts +@subsection Creating contexts + +@cindex @code{\context} +@cindex context selection + +Contexts for a music expression can be selected manually, using the +following music expression. + +@example + \context @var{contexttype} [= @var{contextname}] @var{musicexpr} +@end example + +This instructs lilypond to interpret @var{musicexpr} within the context + of type @var{contexttype} and with name @var{contextname}. If this +context does not exist, it will be created. + +@lilypond[verbatim,singleline] +\score { + \notes \relative c'' { + c4 f + } +} + +@end lilypond + +In this example, the @code{c} and @code{d} are printed on the +default staff. For the @code{e}, a context Staff called +@code{another} is specified; since that does not exist, a new +context is created. Within @code{another}, a (default) Voice context +is created for the @code{e4}. When all music referring to a +context is finished, the context is ended as well. So after the +third quarter, @code{another} is removed. - @item A context definition. See section @ref{contextdefs} for - more information on context definitions. - @item - FIXME now in SCM - A margin shape declaration. The syntax is +@node Default contexts +@subsection Default contexts - @example +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. - \shape @var{indent1}@code{,} @var{width1}@code{,} - @var{indent2}@code{,} @var{width2} @dots{} @code{;} - @end example +@lilypond[verbatim,singleline] +\score { \notes \context Voice = goUp { c'4 d' e' } } +@end lilypond - @keyindex{shape} +There are some quirks that you must keep in mind when dealing with +defaults: - 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. +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 - @item \stylesheet declaration. Its syntax is +Second, sequential music follows the contexts of its +``children''. Consider the following example. - @example - \stylesheet @var{scm} - @end 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. - See font.scm for details of @var{scm} -@end itemize +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 -@cindex changing font size and paper size -The Feta font provides musical symbols at six different sizes. These -fonts are 11 point, 13 point, 16 point, 20 point, -23 point, and 26 point. The point size of a font is the -height of the five lines in a staff when displayed in the font. -Definitions for these sizes are the files @file{paperSZ.ly}, where -@code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include -any of these files, the identifiers @code{paper_eleven}, -@code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty}, -@code{paper_twentythree}, and @code{paper_twentysix} are defined -respectively. The default @code{\paper} block is also set. +@node Context properties +@subsection Context properties -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. +Notation contexts have properties. These properties are from +the @file{.ly} file using the following expression: +@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. -@cindex paper variables +Properties can be unset using the following expression: +@example + \property @var{contextname}.@var{propname} \unset +@end example -@node Paper variables, , , Reference Manual +@cindex properties, unsetting +@cindex @code{\unset} -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. +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. -Nevertheless, here are some variables you may want to use or change: -@table @samp - @item @code{indent}@indexcode{indent} - The indentation of the first line of music. +@refbugs - @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. +The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not +the inverse of @code{\property \set}. - @item @code{textheight}@indexcode{textheight} - Sets the total height of the music on each page. Only used by - ly2dvi. +@node Engravers and performers +@subsection Engravers and performers - @item @code{interscoreline}@indexcode{interscoreline} - Sets the spacing between the score lines. Defaults to 16 pt. +[TODO] - @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. +Basic building blocks of translation are called engravers; they are +special C++ classes. - @item @code{stafflinethickness}@indexcode{stafflinethickness} - Determines the thickness of staff and bar lines. -@end table -@node contextdefs, , , Reference Manual +@c . {Context definitions} +@node Changing context definitions +@subsection Changing context definitions @cindex context definition +@cindex translator definition -A notation contexts is defined by the following information - -@enumerate i - @item A name. +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 and remove engravers using the following syntax: +@example + \remove @var{engravername} + \consists @var{engravername} +@end example - @item The LilyPond modules that do the actual conversion of music to - notation. Each module is a so-called - @emph{engraver} -@cindex engraver -. - @item How these modules should cooperate, i.e. which ``cooperation - module'' should be used. This cooperation module is a special - type of engraver. +Here @var{engravername} is a string, the name of an engraver in the +system. - @item What other contexts the context can contain, - @item What properties are defined. -@end enumerate +@lilypond[verbatim,singleline] +\score { \notes { + c'4 c'4 } + \paper { + \translator { \StaffContext + \remove Clef_engraver + } } } +@end lilypond -A context definition has this syntax: +@cindex engraver +You can also set properties in a translator definition. The syntax is as +follows: @example - - \translator @code{@{} - @var{translatorinit} @var{translatormodifierlist} - @code{@}} + @var{propname} = @var{value} + @var{propname} \set @var{grob-propname} = @var{pvalue} + @var{propname} \override @var{grob-propname} = @var{pvalue} + @var{propname} \revert @var{grob-propname} @end example +@var{propname} is a string, @var{grob-propname} a symbol, @var{value} +and @code{pvalue} are Scheme expressions. These type of property +assignments happen before interpretation starts, so a @code{\property} +command will override any predefined settings. -@var{translatorinit} can be an identifier or of the form -@example + To simplify editing translators, all standard contexts have standard +identifiers called @var{name}@code{Context}, e.g. @code{StaffContext}, +@code{VoiceContext}. - \type @var{typename} @code{;} -@end example +@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}}. -@var{typename} is one of + @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 -@table @samp - @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver} +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. - @item @code{Score_engraver}@indexcode{Score_engraver} - This is cooperation module that should be in the top level context. +@cindex @code{Score_engraver} - @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group} + @item @code{Score_engraver} + This is cooperation module that should be in the top level context, +and only the top level context. + +@cindex @code{Grace_engraver_group} + + @item @code{Grace_engraver_group} This is a special cooperation module (resembling - @code{Score_engraver}) that is used to created an embedded + @code{Score_engraver}) that is used to create an embedded `miniscore'. @end table -@var{translatormodifierlist} is a list of items where each item is -one of +Other modifiers are @itemize @bullet - @item @code{\consists} @var{engravername} @code{;} - Add @var{engravername} to the list of modules in this context. - The order of engravers added with @code{\consists} is - significant. - - @item @code{\consistsend} @var{engravername} @code{;} + @item @code{\alias} @var{alternate-name} + 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} 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. + insures they stay there even if a user adds or removes engravers. +End-users generally don't need this command. - @item @code{\accepts} @var{contextname} @code{;} + @item @code{\accepts} @var{contextname} Add @var{contextname} to the list of context this context can - contain. The first listed context the context to create by + contain. The first listed context is the context to create by default. + + @item @code{\denies}. The opposite of @code{\accepts}. Added for +completeness, but is never used in practice. + - @item @code{\remove} @var{engravername} @code{;} - Remove a previously added (with @code{\consists}) engraver. - - @item @code{\name} @var{contextname} @code{;} + @item @code{\name} @var{contextname} 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 @@ -2400,7 +4234,6 @@ 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{} @} @@ -2420,471 +4253,593 @@ such an identifier outside of @code{\score}, you must do @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. +@c . {Syntactic details} +@node Syntactic details +@section Syntactic details +@cindex Syntactic details - @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers} - Score context with numbering at the Score level. +This section describes details that were too boring to be put elsewhere. - @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext} - Staff context with numbering at the Staff level. +@menu +* Top level:: +* Identifiers:: +* Music expressions:: +* Manipulating music expressions:: +* Assignments:: +* Lexical modes:: +* Ambiguities:: +@end menu - @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext} - Staff context that does not print if it only contains rests. - Useful for orchestral scores.@footnote{Harakiri, also called - Seppuku, is the ritual suicide of the Samourai.} +@c . {Top level} +@node Top level +@subsection Top level +@cindex Top level - @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext} +This section describes what you may enter at top level. - @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext} -@end table -Using these pre-defined values, you can remove or add items to the -translator: +@c . {Score} +@subsubsection Score +@cindex Score -@quotation +@cindex score definition -@example -\paper @{ - \translator @{ - \StaffContext - \remove Some_engraver; - \consists Different_engraver; - @} -@} -@end example +The output is generated combining a music expression with an output +definition. A score block has the following syntax: -@end quotation +@example + \score @{ @var{musicexpr} @var{outputdefs} @} +@end example - -@node Sound output, , , Reference Manual -@section Sound output +@var{outputdefs} are zero or more output definitions. If none is +supplied, the default @code{\paper} block will be added. -The MIDI block is analogous to the paper block, but it is simpler. -The @code{\midi} block can contain: -@cindex MIDI block +@c . {Default output} +@subsubsection Default output -@itemize @bullet - @item a @code{\tempo} definition - @item context definitions -@end itemize +Default values for the @code{\paper} and @code{\midi} block are set by +entering such a block at top-level. -Assignments in the @code{\midi} block are not allowed. +@c . {Header} +@subsubsection Header +@cindex Header +@cindex @code{\header} +A header describes bibliographic information of the file's contents. It +can also appear in a @code{\score} block. Tools like @code{ly2dvi} can +use this information for generating titles. Key values that are used by +@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument, +metre, arranger, piece and tagline. -@cindex context definition +@cindex @code{ly2dvi} -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}. +The syntax is +@example + \header @{ @var{key1} = @var{val1} + @var{key2} = @var{val2} @dots{} @} +@end example + +It is customary to put the @code{\header} at the top of the file. + +@subsubsection Default output + +A @code{\midi} or @code{\paper} block at top-level sets the default +paper block for all scores that lack an explicit paper block. + +@c . {Identifiers} +@node Identifiers +@subsection Identifiers +@cindex Identifiers + +All of the information in a LilyPond input file, is represented as a +Scheme value. In addition to normal Scheme data types (such as pair, +number, boolean, etc.), LilyPond has a number of specialized data types, + +@itemize @bullet +@item Input +@item c++-function +@item Music +@item Identifier +@item Translator_def +@item Duration +@item Pitch +@item Score +@item Music_output_def +@item Moment (rational number) +@end itemize + +LilyPond also includes some transient object types. Objects of these +types are built during a LilyPond run, and do not `exist' per se within +your input file. These objects are created as a result of your input +file, so you can include commands in the input to manipulate them, +during a lilypond run. +@itemize @bullet +@item Grob: short for Graphical object. See @ref{Grobs}. +@item Molecule: device-independent page output object, +including dimensions. Produced by some Grob functions +See @ref{Molecules} +@item Translator: object that produces audio objects or Grobs. This is +not yet user accessible. +@item Font_metric: object representing a font. (See @ref{Font metrics}) +@end itemize -@cindex MIDI instrument names -@node midilist, , , Reference Manual +@node Music expressions +@subsection Music expressions -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. +@cindex music expressions -@c @quotation +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 -"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)" +\sequential @{ c4 d4 @} @end example -@c @end quotation +@cindex Sequential music +@cindex @code{\sequential} +@cindex sequential music +@cindex @code{<} +@cindex @code{>} +@cindex Simultaneous music +@cindex @code{\simultaneous} + +The two basic compound music expressions are simultaneous and +sequential music. + +@example + \sequential @code{@{} @var{musicexprlist} @code{@}} + \simultaneous @code{@{} @var{musicexprlist} @code{@}} +@end example +For both, there is a shorthand: +@example + @code{@{} @var{musicexprlist} @code{@}} +@end example +for sequential and +@example + @code{<} @var{musicexprlist} @code{>} +@end example +for simultaneous music. +In principle, the way in which you nest sequential and simultaneous to +produce music is not relevant. In the following example, three chords +are expressed in two different ways: + +@lilypond[fragment,verbatim,center] + \notes \context Voice { + + < { a b c' } { c' d' e' } > + } +@end lilypond + + +Other compound music expressions include +@example + \repeat @var{expr} + \transpose @var{pitch} @var{expr} + \apply @var{func} @var{expr} + \context @var{type} = @var{id} @var{expr} + \times @var{fraction} @var{expr} +@end example + +@c . {Manipulating music expressions} +@node Manipulating music expressions +@subsection Manipulating music expressions +The @code{\apply} mechanism gives you access to the internal +representation of music. You can write Scheme-functions that operate +directly on it. The syntax is +@example + \apply #@var{func} @var{music} +@end example +This means that @var{func} is applied to @var{music}. The function +@var{func} should return a music expression. + +This example replaces the text string of a script. It also shows a dump +of the music it processes, which is useful if you want to know more +about how music is stored. + +@lilypond[verbatim,singleline] +#(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 { c'4_"foo" } +} +@end lilypond + +For more information on what is possible, see the automatically +generated documentation. -@node Pre-defined Identifiers, , , Reference Manual -@section Pre-defined Identifiers +Directly accessing internal representations is dangerous: the +implementation is subject to changes, so you should avoid this feature +if possible. -@cindex pre-defined identifiers +A final example is a function that reverses a piece of music in time: +@lilypond[verbatim,singleline] +#(define (reverse-music music) + (let* ((elements (ly-get-mus-property music 'elements)) + (reversed (reverse elements)) + (span-dir (ly-get-mus-property music 'span-direction))) + (ly-set-mus-property music 'elements reversed) + (if (dir? span-dir) + (ly-set-mus-property music 'span-direction (- span-dir))) + (map reverse-music reversed) + music)) -Various identifiers are defined in the initialization files to -provide shorthands for some settings. Most of them are in -@file{ly/declarations.ly}. +music = \notes { c'4 d'4( e'4 f'4 } -@table @samp - @item @code{\break}@keyindex{break} - Force a line break in music by using a large argument for the - keyword @code{\penalty}. +\score { \context Voice { + \music + \apply #reverse-music \music + } +} +@end lilypond - @item @code{\nobreak}@keyindex{nobreak} - Prevent a line break in music by using a large negative argument - for the keyword @code{\penalty}. +More examples are given in the distributed example files in +@code{input/test/}. - @item @code{\normalkey}@keyindex{normalkey} - Select normal key signatures where each octave has the same key - signature. This sets the @code{Staff.keyoctaviation} property. +@c . {Span requests} +@menu +* Span requests:: +@end menu - @item @code{\shiftoff}@keyindex{shiftOff} - Disable horizontal shifting of note heads that collide. +@node Span requests +@subsubsection Span requests +@cindex Span requests - @item @code{\shiftOn}@keyindex{shiftOn} - Enable note heads that collide with other note heads to be - shifted horiztonally. +Notational constructs that start and end on different notes can be +entered using span requests. The syntax is as follows: - @item @code{\slurBoth}@keyindex{slurBoth} - Allow slurs to be above or below notes. - @item @code{\slurDown}@keyindex{slurDown} - Force slurs to be below notes. +@example + \spanrequest @var{startstop} @var{type} +@end example - @item @code{\slurUp}@keyindex{slurUp} - Force slurs to be above notes. - @item @code{\specialkey}@keyindex{specialkey} - Allow key signatures do differ in different octaves. This sets - the @code{Staff.keyoctaviation} property. +@cindex @code{\start} +@cindex @code{\stop} - @item @code{\stemBoth}@keyindex{stemBoth} - Allow stems, beams, and slurs to point either upwards or - downwards, decided automatically by LilyPond. +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, - @item @code{\stemdown}@keyindex{stemdown} - Force stems, beams, and slurs to point down. +@lilypond[fragment,verbatim,center] + c'4-\spanrequest \start "slur" + c'4-\spanrequest \stop "slur" +@end lilypond - @item @code{\stemUp}@keyindex{stemUp} - Force stems, beams and slurs to point up. +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}. -@end table -@node Grobs, , , Reference Manual -@section Grobs +@c . {Assignments} +@node Assignments +@subsection Assignments +@cindex Assignments -This section is about Grobs (short for Graphical Objects), which are -formatting objects used to create the final output. This material is -normally the domain of LilyPond gurus, but occasionally, a normal user -also has to deal with grobs. +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 precede 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. + +An identifier can be created with any string for its name, but you will +only be able to refer to identifiers whose names begin with a letter, +being entirely alphabetical. It is impossible to refer to an identifier +whose name is the same as the name of a keyword. -The most simple interaction with Grobs are when you use -@code{\override}: +The right hand side of an identifier assignment is parsed completely +before the assignment is done, so it is allowed to redefine an +identifier in terms of its old value, e.g. @example - \property Voice.Stem \override #'direction = #1 +foo = \foo * 2.0 @end example -This piece of lily input causes all stem objects to be stem-up -henceforth. In effect, you are telling lilypond to extend the defintion -of the "Stem" grob with the setting @code{direction := 1}. Of course -there are many more ways of customizing Lily output, and since most of -them involve Grobs in some form, this section explains some details of -how grobs work. +When an identifier is referenced, the information it points to is +copied. For this reason, an identifier reference must always be the +first item in a block. +@example +\paper @{ + foo = 1.0 + \paperIdent % wrong and invalid +@} + +\paper @{ + \paperIdent % correct + foo = 1.0 @} +@end example -@menu -* What is a grob?:: -* Callbacks:: -* Setting grob properties:: -* Items and Spanners:: -* Pointer substitution:: -@end menu -@node What is a grob?, , , Grobs +@c . {Lexical modes} +@node Lexical modes +@subsection Lexical modes +@cindex Lexical modes +@cindex input mode +@cindex mode, input +@cindex @code{\notes} +@cindex @code{\chords} +@cindex @code{\lyrics} + +To simplify entering notes, lyrics, and chords, LilyPond has three +special input modes on top of the default mode: note, lyrics and chords +mode. These input modes change the way that normal, unquoted words are +interpreted: for example, the word @code{cis} may be interpreted as a +C-sharp, as a lyric syllable `cis' or as a C-sharp major triad +respectively. + +A mode switch is entered as a compound music expressions +@example +@code{\notes} @var{musicexpr} +@code{\chords} @var{musicexpr} +@code{\lyrics} @var{musicexpr}. +@end example -All grobs have an X and Y-position on the page. These X and Y positions -are stored in a relative format, so they can easily be combined by -stacking them, hanging one grob to the side of another, and coupling -them into a grouping-grob. +In each of these cases, these expressions do not add anything to the +meaning of their arguments. They just instruct the parser in what mode +to parse their arguments. The modes are treated in more detail in +@ref{Lyrics} and @ref{Chords}. -Each grob has a reference point, or parent: the position of a grob is -stored relative to that reference point. For example the X-reference -point of a staccato dot usually is the note head that it applies -to. Whenever the note head is moved, the staccato dot moves along -automatically. +Different input modes may be nested. -If you keep following offset reference points, you will always end up at -the root-object. This root object is called @code{Line_of_score} -@ref{(lilypond-internals)Element Line_of_score}, and it represents a -system (ie. a line of music). +@c . {Ambiguities} +@node Ambiguities +@subsection Ambiguities +@cindex ambiguities +@cindex grammar -All grobs carry a set of grob-properties. In the Stem example above, -the property @code{direction} is set to value @code{1}. The function -that draws the symbol (@code{Stem::brew_molecule}) uses the value of -@code{direction} to determine how to print the stem and the flag. The -appearance of a grob is determined solely by the values of its -properties. -Often, a grob also is associated with a symbol. On the other hand, Some -grobs do not print any symbols, but take care of grouping objects. For -example, there is a separate grob that stacks staffs vertically, so they -are not printed in overstrike. The NoteCollision @ref{(lilypond-internals)Element -NoteCollision} is another example of an abstract grob. It only moves -around chords, but doesn't print anything. +The grammar contains a number of ambiguities. We hope to resolve them at +some time. -A complete list of grob types is found in @ref{(lilypond-internals)Elements} +@itemize @bullet + @item The assignment -Grobs are created in the "Interpreting music" phase, by things in -LilyPond called engravers. In this phase of the translation, a load of -grobs are created, and they are linked into a giant network of objects. -This network of grobs forms the "specification" of the print -problem. This problem is then solved: configurations, directions, -dimensions, line breaks, etc. are calculated. Finally, the printing -description in the form of Molecules (@ref{Molecule}) is extracted from -the network. These are then dumped into the output file +@example +foo = bar +@end example + is interpreted as the string identifier assignment. However, +it can also be interpreted as making a string identifier @code{\foo} + containing @code{"bar"}, or a music identifier @code{\foo} + containing the syllable `bar'. -@node Callbacks, , , Grobs + @item If you do a nested repeat like -Offsets of grobs are relative to a parent reference point. Most -positions are not known when an object is created, so these are -calculated as needed. This is done by adding a callback for a specific -direction. + @quotation -Suppose you have the following code in a .ly file. -@example - #(define (my-callback gr axis) - (* 2.0 (get-gr-property grob 'direction)) - ) +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example -.... + @end quotation - \property Voice.Stem \override #'Y-offset-callbacks = #(list - my-callback) -@end example + 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 The parser is not sophisticated enough to distinguish at the +right time between + @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode). -When the Y-offset of a Stem object is needed, LilyPond will -automatically execute all callbacks for that object. In this case, it -will find @code{my-callback}, and execute that. The result is that the -stem is translated by two staff spaces in its direction. +[checkme] -(note: Y-offset-callbacks is also a property) +@end itemize -Offset callbacks can be stacked, ie. +@c . {Lexical details} +@node Lexical details +@section Lexical details -@example - \property .... \override #'Y-offset-callbacks = #(list - callback1 callback2 callback3) +Even more boring details, now on lexical side of the input parser. -@end example +@menu +* Comments:: +* Direct Scheme:: +* Keywords:: +* Integers:: +* Reals:: +* Strings:: +* Main input:: +* File inclusion:: +* Version information:: +@end menu -The callbacks will be executed in the order callback3 callback2 -callback1. This is used for quantized positioning: the staccato dot is -above or below a note head, and it must not be on a staff-line. -To achieve this, for the staccato there are two callbacks: one callback -that positions the grob above or below the note head, and one callback -that rounds the Y-position of the grob to the nearest open space. +@node Comments +@subsection Comments -Similarly, the size of a grob are determined through callbacks, settable -with grob properties @code{X-extent-callback} and @code{Y-extent-callback}. -There can be only one extent-callback for each axis. No callback (value #f) -means: "empty in this direction". If you fill in a pair, that pair -hard-codes the extent in that coordinate. +@cindex comments +@cindex block comment +@cindex line comment +@cindex @code{%} -@node Setting grob properties, , , Grobs +A one line comment is introduced by a @code{%} character. +Block comments are started by @code{%@{} and ended by @code{%@}}. +They cannot be nested. -Grob properties are stored as GUILE association lists, with symbols as -keys. From C++, element properties can be accessed using the functions +@node Direct Scheme +@subsection Direct Scheme -@example - SCM get_grob_property (SCM) const; - void set_grob_property (const char * , SCM val); - void set_immutable_grob_property (const char * , SCM val); - void set_immutable_grob_property (SCM key, SCM val); - void set_grob_property (SCM , SCM val); - void set_grob_pointer (const char*, SCM val); - SCM remove_grob_property (const char* nm); -@end example +@cindex Scheme +@cindex GUILE +@cindex Scheme, in-line code -In GUILE, LilyPond provides +LilyPond contains a Scheme interpreter (the GUILE library) for +internal use. In some places Scheme expressions also form valid syntax: +wherever it is allowed, +@example + #@var{scheme} +@end example +evaluates the specified Scheme code. Example: @example - ly-get-grob-property GROB SYMBOL - ly-set-grob-property GROB SYMBOL VALUE + \property Staff.TestObject \override #'foobar = #(+ 1 2) @end example +@code{\override} expects two Scheme expressions, so there are two Scheme +expressions. The first one is a symbol (@code{foobar}), the second one +an integer (namely, 3). -All lookup functions identify undefined properties with -end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C) +In-line scheme may be used at top level. In this case the result is +discarded. -Properties are stored in two ways: -@itemize @bullet -@item mutable properties: -element properties that change from object to object. The storage of -these are private to a grob. Typically this is used to store lists of -pointers to other grobs - -@item immutable properties: -element properties that are shared across different grobs of the same -type. The storage is shared, and hence it is read-only. Typically, this -is used to store function callbacks, and values for shared element -properties are read from @file{scm/element-description.scm}. -@end itemize +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. -There are two ways to manually set grob properties. -You can change immutable grob properties. This is done with the -\override syntax: +@node Keywords +@subsection Keywords +@cindex Keywords -@example - \property Voice.Stem \override #'direction = #1 -@end example -This will push the entry @code{'(direction . 1)} on the immutable -property list for stems, in effect overriding the setting from -@file{scm/element-description.scm}. This can be undone by +Keywords start with a backslash, followed by a number of lower case +alphabetic characters. These are all the keywords. @example - \property Voice.stem \revert #'direction +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 -If you use this a lot, this gets old quickly. So we also have a -shorthand, +@node Integers +@subsection Integers -@example - \property Context.GrobType \set #'prop = #VAL -@end example +@cindex integers +@cindex @code{+} +@cindex @code{-} +@cindex @code{*} +@cindex @code{/} + +Formed from an optional minus sign followed by digits. Arithmetic +operations cannot be done with integers, and integers cannot be mixed +with reals. -this does a @code{\revert} followed by a @code{\override} +@node Reals +@subsection Reals +@cindex real numbers -The second way is \outputproperty. This construct looks like -@example - \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val} -@end example -In this case, in every grob that satisfies @var{pred}, the property -assignment @var{sym} = @var{val} is done. For example -@example - \outputproperty - #(lambda (gr) (string? (ly-get-grob-property gr - 'text))) - #'extra-offset = #'(-1.0 . 0.0) -@end example -This shifts all elements that have a @code{text} property one staff -space to the left. +Formed from an optional minus sign and a sequence of digits followed +by a @emph{required} decimal point and an optional exponent such as +@code{-1.2e3}. Reals can be built up using the usual operations: +`@code{+}', `@code{-}', `@code{*}', and +`@code{/}', with parentheses for grouping. -@node Items and Spanners, , , Grobs +@cindex @code{\mm}, +@cindex @code{\in} +@cindex @code{\cm} +@cindex @code{\pt} +@cindex dimensions -Grobs can also be distinguished in their role in the horizontal spacing. -A lot of grobs define constraints on the spacing by their sizes. For -example, note heads, clefs, stems, and all other symbols with a fixed -shape. These grobs form a subtype called @code{Item}. +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. -Other grobs have a shape that depends on the horizontal spacing. For -example, slur, beam, tie, etc. These grobs form a subtype called -@code{Spanner}. All spanners have two span-points (these must be -@code{Item}s), one on the left and one on the right. The left bound is -also the X-reference point. -Some items need special treatment for line breaking. For example, a -clef is normally only printed at the start of a line (ie. after a line -break). To model this, `breakable' items (clef, key signature, bar lines, -etc.) are copied twice. Then we have three versions of each breakable -item: one version if there is no line break, one version that is printed -before the line break (at the end of a system), one version that is -printed after the line break. +@node Strings +@subsection Strings +@cindex string +@cindex concatenate -Whether these versions are visible and take up space, is determined by -the outcome of the visibility-lambda. This is a function taking a -direction (-1, 0 or 1) and returns a cons of booleans, signifying wether -this grob should be transparent and invisible. +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. Strings can +be concatenated with the @code{+} operator. -@node Pointer substitution, , , Grobs +@node Main input +@subsection Main input +@cindex Main input -@node Molecule, , , Reference Manual +@cindex @code{\maininput} -The objective of any typesetting system is to put ink on paper in the -right places. For LilyPond, this final stage is left to the TeX and the -printer subsystem. For lily, the last stage in processing a score is -outputting a description of what to put where. This description roughly -looks like +The @code{\maininput} command is used in init files to signal that the +user file must be read. This command cannot be used in a user file. +@node File inclusion +@subsection File inclusion +@cindex @code{\include} @example - PUT glyph AT (x,y) - PUT glyph AT (x,y) - PUT glyph AT (x,y) + \include @var{filename} @end example -you merely have to look at the tex output of lily to see this. -Internally these instructions are encoded in Molecules:@footnote{At some -point LilyPond also contained Atom-objects, but they have been replaced -by Scheme expressions.}. A molecule is an object that combines -dimension information (how large is this glyph ?) with -what-to-print-where. +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, -Conceptually, Molecules can be constructed from Scheme code, by -translating a Molecule and by combining two molecules. In BNF notation: +@node Version information +@subsection Version information +@cindex @code{\version} @example - Molecule = COMBINE Molecule Molecule - | TRANSLATE Offset Molecule - | GLYPH-DESCRIPTION - ; + \version @var{string} @end example -(refer to the C++ code for more details). All visible, -ie. non-transparent, grobs have a callback to create a Molecule. The -name of the property is @code{molecule-callback}, and its value should -be a Scheme function taking one argument (the grob) and returning a -Molecule. +Specify the version of LilyPond that a file was written for. The +argument is a version string in quotes, for example @code{"1.2.0"}. +This is used to detect invalid input, and to aid +@code{convert-ly} a tool that automatically upgrades input files. See +See @ref{convert-ly} for more information on @code{convert-ly}. + +@cindex convert-ly + + + + + + +@c .{Local emacs vars} +@c Local variables: +@c mode: texinfo +@c minor-mode: font-lock +@c minor-mode: outline +@c outline-layout: (-1 : 0) +@c outline-use-mode-specific-leader: "@c \." +@c outline-primary-bullet: "{" +@c outline-stylish-prefixes: nil +@c outline-override-protect: t +@c End: +