From: Han-Wen Nienhuys Date: Sun, 7 Mar 2004 00:13:44 +0000 (+0000) Subject: * Documentation/user/changing-defaults.itely (Changing defaults): X-Git-Tag: release/2.1.29~1 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c53d0cabdf9361e448cdd02a338aa5d696f4f466;p=lilypond.git * Documentation/user/changing-defaults.itely (Changing defaults): new file. * Documentation/user/notation.itely (Notation manual): rename from refman.itely * Documentation/user/notation-appendices.itely (The Feta font): new file. * Documentation/user/advanced.itely: add aborted attempt for advanced topics manual. --- diff --git a/ChangeLog b/ChangeLog index dcf795a3d0..d5b68ddb60 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,22 @@ +2004-03-07 Han-Wen Nienhuys + + * Documentation/user/changing-defaults.itely (Changing defaults): + new file. + + * Documentation/user/notation.itely (Notation manual): rename from + refman.itely + + * Documentation/user/notation-appendices.itely (The Feta font): + new file. + + * Documentation/user/advanced.itely: add aborted attempt for + advanced topics manual. + +2004-03-06 Han-Wen Nienhuys + + * scm/new-markup.scm: display Markups in sane format. Patch by + Nicolas Sceaux. + 2004-03-05 Jan Nieuwenhuizen * lily/main.cc: Cleanups. diff --git a/Documentation/user/advanced.itely b/Documentation/user/advanced.itely new file mode 100644 index 0000000000..33b0df372a --- /dev/null +++ b/Documentation/user/advanced.itely @@ -0,0 +1,175 @@ +@c UNUSED !! -*-texinfo-*- + +@node Advanced concepts +@section Advanced concepts + + +Although LilyPond was designed to produce standard music notation, its +architecture is flexible, and it is possible to manipulate the +translation from a @file{.ly} file to a PDF file in many ways. This +chapter discusses outlines the options for customization. + +Before we can explain what is possible, it it is necessary to +understand the general architecture of LilyPond. The following +diagram shows the different steps in producing a PDF file: + +@verbatim + + Parsing Interpretation Formatting + +.ly file -> Music -> Notation -> + + + Formatting Dumping Titling + + -> Typography -> .tex -> .pdf file + +@end verbatim + +@enumerate + +@item @emph{Parsing} means reading a file, and translating letters and + numbers into data structures. + +@item The central data structure is the @emph{Music} expression. It is +the structure that stores music events (notes, chords, lyric +syllables, etc.) and their combinations. + +@item In order to print a piece music, separate events have to be +synchronized. For example, notes that sound together must be combined +horizontally, while syllables must be combined on a line. This happens +in the @emph{interpretating} step. + +@item The result of @emph{interpreting} is @emph{notation}, a +collection of layout objects. + +@item The exact appearance of the layout objects is determined during +@emph{formatting}. For example, in this step spacing and beam slopes +are determined. + +@item After formatting, LilyPond dumps a @TeX{} file containing the +symbols and their offsets. + +@item In a final step, titles are added to the music, resulting in a +PostScript, DVI or PDF file. + +@end enumerate + +This chapter discusses Steps@tie{}1. to@tie{}4. Step@tie{}5 is +discussed in @ref{Tuning output}, while Step@tie{}6 is discussed in +@ref{Invoking LilyPond}. + +The diagram above shows how music typesetting has been split-up in +multiple subproblems. However, splitting up problems always produces +the new problem of putting together the subsolutions to these +subproblems. Therefore, we will start our advanced topics class with a +discussion of the programming language Scheme, which lubricates the +interactions between different modules of LilyPond. + + + +@section Scheme in LilyPond +@node Scheme in LilyPond + +LilyPond includes an interpreter for the programming language Scheme, +a member of the LISP family. This interpreter, +@uref{GUILE,http://www.gnu.org/software/guile/}, +forms the basis of the + +**************************************************************** + +@c -*-texinfo-*- +@c Note: +@c +@c A menu is needed before every deeper *section nesting of @nodes +@c Run M-x texinfo-all-menus-update +@c to automatically fill in these menus +@c before saving changes + + +@node Technical manual +@chapter Technical manual + + +When LilyPond is run, it reads music from a file, translates that into +notation, and outputs the result to a file. The most important steps +are the first three. Consequently, there are three important basic +concepts within LilyPond: music, translation and layout. The +following diagram illustrates the concepts, and list the terminology +associated with each step. + + +@verbatim + + +-------------+ Translation +----------+ + | | | | + | Music | ------------------> | Layout | + | | | | + +-------------+ +----------+ + + +Syntax: c4 \context \set #'padding = + \override + +Objects: Music expressions Contexts Layout object + Engravers (aka. Grob) + +Example objects: NoteEvent Voice NoteHead + Note_heads_engraver + +Example properties: #'pitch keySignature #'line-count + +User applications: none various tuning layout + +@end verbatim + +The objects passed around in LilyPond have @emph{properties}, +variables that can contain many different types of information. Users +can set these variables, to modify the default behavior. Since there +are three different main concepts, there are also three types of +properties: + +@cindex properties +@cindex concepts, main +@cindex context +@cindex music expressions +@cindex layout +@cindex grob + + +@table @b +@item Music properties +These are used internally, and most users will not see or use them. + +They use Scheme-style naming, i.e. lowercase words separated with +dashes: @code{pitch}, @code{tremolo-type}. + +@item Translation properties +These influence the translation process, and most users will encounter them +regularly. For example, beaming behavior is tuned with +@code{autoBeamSettings}. + +These use mixed-caps naming: @code{autoBeamSettings}, +@code{ignoreMelismata}. They are assigned as follows: +@example + \set ignoreMelismata = ... +@end example + +@item Layout properties +These are internally used in the formatting process. Consequently, to +tune formatting details, it is necessary to adjust these +properties. For example, some objects may be moved around vertically +by setting their @code{padding} property. + +These properties use Scheme-style naming: @code{c0-position}, +@code{break-align-symbol}. They most often assigned as follows: + +@example + \override Score.RehearsalMark #'break-align-symbol = ... +@end example + +@noindent +Here, @code{RehearsalMark} is the type of the layout object. + +@end table + diff --git a/Documentation/user/appendices.itely b/Documentation/user/appendices.itely deleted file mode 100644 index a70d26fb45..0000000000 --- a/Documentation/user/appendices.itely +++ /dev/null @@ -1,89 +0,0 @@ -@node Reference manual details -@appendix Reference manual details - -@menu -* Chord name chart:: -* MIDI instruments:: -* The Feta font:: -* Scheme functions:: -* Layout property overview:: -* Context property overview:: -* Literature list:: -@end menu - - - -@node Chord name chart -@section Chord name chart - -@lilypondfile{chord-names-jazz.ly} - -@node MIDI instruments -@section MIDI instruments - -@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)" "shakuhachi" "guitar fret noise" -"fretless bass" "whistle" "breath noise" -"slap bass 1" "ocarina" "seashore" -"slap bass 2" "lead 1 (square)" "bird tweet" -"synth bass 1" "lead 2 (sawtooth)" "telephone ring" -"synth bass 2" "lead 3 (calliope)" "helicopter" -"violin" "lead 4 (chiff)" "applause" -"viola" "lead 5 (charang)" "gunshot" -"cello" "lead 6 (voice)" -@end example - -@node The Feta font -@section The Feta font -The following symbols are available in the Feta font and may be -accessed directly using text markup such as -@code{g^\markup @{ \musicglyph #"scripts-segno" @}}, see @ref{Text markup}. - - -@lilypondfile[noindent]{feta16list.ly} - - -@lilypondfile[noindent]{parmesan16list.ly} - - -@include scheme-functions.tely - -@include context-properties.tely - -@include layout-properties.tely - -@include literature.itely diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely new file mode 100644 index 0000000000..7d5fd57dcb --- /dev/null +++ b/Documentation/user/changing-defaults.itely @@ -0,0 +1,1626 @@ +@c -*-texinfo-*- +@node Changing defaults +@chapter Changing defaults + +TODO: reorganise. + +@menu +* Scheme integration:: +* Setting variables:: +* Fine tuning layout:: +* Tuning output:: +* Text markup:: +* Global layout:: +* Interpretation context:: +* Output details:: +@end menu + + + +@node Scheme integration +@section Scheme integration + +@cindex Scheme +@cindex GUILE +@cindex Scheme, in-line code +@cindex accessing Scheme +@cindex evaluating Scheme +@cindex LISP + +LilyPond internally uses GUILE, a Scheme-interpreter, to represent +data throughout the whole program, and glue together different program +modules. For advanced usage, it is sometimes necessary to access and +program the Scheme interpreter. + +Scheme is a full-blown programming language, from the LISP +family. and a full discussion is outside the scope of this document. +Interested readers are referred to the website +@uref{http://www.schemers.org/} for more information on Scheme. + +The GUILE library for extension is documented at +@uref{http://www.gnu.org/software/guile}. +@ifinfo +When it is installed, the following link should take you to its manual +@ref{(guile.info)guile} +@end ifinfo + +@menu +* Inline Scheme:: +@end menu + +@node Inline Scheme +@subsection Inline Scheme + +Scheme expressions can be entered in the input file by entering a +hash-sign (@code{#}). The expression following the hash-sign is +evaluated as Scheme. For example, the boolean value @var{true} is +@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t}, +and can be used in property assignments: +@example + \set Staff.autoBeaming = ##f +@end example + + +@node Setting variables +@section Setting variables + +When the music is converted from notes to print it is interpreted +in left-to-right order. This is similar to what happens when we read +music. During this step context-sensitive information such as the +accidentals to print, and where bar lines must be placed, are stored in +variables. These variables are called @emph{context properties}. +The properties can also be manipulated from input files. Consider this input: +@example +\set Staff.autoBeaming = ##f +@end example + +@noindent +It sets the property named @code{autoBeaming} in the current staff at +this point in the music to @code{##f}, which means `false'. This +property controls whether beams are printed automatically: +@c +@lilypond[relative=1,fragment,verbatim] + c8 c c c + \set Staff.autoBeaming = ##f + c8 c c c +@end lilypond + +@noindent +LilyPond includes a built-in programming language, namely, a dialect +of Scheme. The argument to @code{\set}, @code{##f}, is an +expression in that language. The first hash-mark signals that a piece +of Scheme code follows. The second hash character is part of the +boolean value true (@code{#t}). Values of other types may be +entered as follows: +@itemize @bullet +@item a string, enclosed in double quotes, for example, +@example + \set Staff.instrument = #"French Horn" +@end example +@item a boolean: either @code{#t} or @code{#f}, for true and false +respectively, e.g. +@example + \set autoBeaming = ##f + \set Score.skipBars = ##t +@end example + +@item a number, such as +@example + \set Score.currentBarNumber = #20 +@end example + +@item a symbol, which is introduced by a quote character, as in +@example + \set Staff.crescendoSpanner = #'dashed-line +@end example + +@item a pair, which is also introduced by a quote character, like in +the following statements, which set properties to the pairs (-7.5, 6) +and (3, 4) respectively: + +@example + \set Staff.minimumVerticalExtent = #'(-7.5 . 6) + \set Staff.timeSignatureFraction = #'(3 . 4) +@end example + +@item a list, which is also introduced by a quote character. In the +following example, the @code{breakAlignOrder} property is set to a +list of symbols: +@example + \set Score.breakAlignOrder = + #'(left-edge time-signature key-signatures) +@end example + + +@end itemize + +There are many different properties. Not all of them are listed in +this manual. However, the program reference lists them all in the +section @internalsref{Context-properties}, and most properties are +demonstrated in one of the +@ifhtml +@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks} +@end ifhtml +@ifnothtml +tips-and-tricks +@end ifnothtml +examples. + + +@node Fine tuning layout +@section Fine tuning layout + +Sometimes it is necessary to change music layout by hand. When music +is formatted, layout objects are created for each symbol. For +example, every clef and every note head is represented by a layout +object. These layout objects also carry variables, which we call +@emph{layout properties}. By changing these variables from their +values, we can alter the look of a formatted score: + +@lilypond[verbatim,relative] + c4 + \override Stem #'thickness = #3.0 + c4 c4 c4 +@end lilypond + +@noindent +In the example shown here, the layout property @code{thickness} (a +symbol) is set to 3 in the @code{Stem} layout objects of the current +As a result, the notes following @code{\override} have thicker +stems. + +For the most part, a manual override is needed only on a case by +case basis and not for all subsequent instances of the altered +property. To accomplish this, simply prefix @code{\once} to the +@code{\override} statement and the override will apply only once, +immediately reverting to its default setting, i.e. + +@example + \once \override Stem #'thickness = #3.0 +@end example + +@lilypond[relative] + c4 + \once \override Stem #'thickness = #3.0 + c4 c4 c4 +@end lilypond + +@noindent +Some overrides are so common that predefined commands are provided as +a short cut. For example, @code{\slurUp} and @code{\stemDown}. These +commands are described in +@ifhtml +the +@end ifhtml +@ref{Notation manual}, under the sections for slurs and stems +respectively. + +The exact tuning possibilities for each type of layout object are +documented in the program reference of the respective +object. However, many layout objects share properties, which can be +used to apply generic tweaks. We mention a couple of these: + +@itemize @bullet +@item The @code{extra-offset} property, which +@cindex @code{extra-offset} +has a pair of numbers as value, moves around objects in the printout. +The first number controls left-right movement; a positive number will +move the object to the right. The second number controls up-down +movement; a positive number will move it higher. The units of these +offsets are staff-spaces. The @code{extra-offset} property is a +low-level feature: the formatting engine is completely oblivious to +these offsets. + +In the following example, the second fingering is moved a little to +the left, and 1.8 staff space downwards: + +@cindex setting object properties + +@lilypond[relative=1,verbatim] +\stemUp +f-5 +\once \override Fingering + #'extra-offset = #'(-0.3 . -1.8) +f-5 +@end lilypond + +@item +Setting the @code{transparent} property will cause an object to be printed +in `invisible ink': the object is not printed, but all its other +behavior is retained. The object still takes up space, it takes part in +collisions, and slurs, and ties and beams can be attached to it. + +@cindex transparent objects +@cindex removing objects +@cindex invisible objects +The following example demonstrates how to connect different voices +using ties. Normally, ties only connect two notes in the same +voice. By introducing a tie in a different voice, and blanking a stem +in that voice, the tie appears to cross voices: + +@lilypond[fragment,relative=1,verbatim] + c4 << { + \once \override Stem #'transparent = ##t + b8~ b8 + } \\ { + b[ g8] + } >> +@end lilypond + +@item +The @code{padding} property for objects with +@cindex @code{padding} +@code{side-position-interface} can be set to increase distance between +symbols that are printed above or below notes. We only give an +example; a more elaborate explanation is in @ref{Constructing a +tweak}: + +@lilypond[relative=1,verbatim] + c2\fermata + \override Script #'padding = #3 + b2\fermata +@end lilypond + +@end itemize + +More specific overrides are also possible. The notation manual +discusses in depth how to figure out these statements for yourself, in +@ref{Tuning output}. + + + + +@node Tuning output +@section Tuning output + +There are situations where default layout decisions are not +sufficient. In this section we discuss ways to override these +defaults. + +Formatting is internally done by manipulating so called objects +(graphic objects). Each object carries with it a set of properties +(object or layout properties) specific to that object. For example, a +stem object 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 one type of object, thus +affecting a whole set of objects. Second, you can select one specific +object, and set a layout property in that object. + +Do not confuse layout properties with translation +properties. Translation properties always use a mixed caps style +naming, and are manipulated using @code{\set} and @code{\unset}: +@example + \set Context.propertyName = @var{value} +@end example + +Layout properties are use Scheme style variable naming, i.e. lower +case words separated with dashes. They are symbols, and should always +be quoted using @code{#'}. For example, this could be an imaginary +layout property name: +@example + #'layout-property-name +@end example + + +@menu +* Tuning objects:: +* Constructing a tweak:: +* Font selection:: +@end menu + + + +@node Tuning objects +@subsection Tuning objects + +@cindex object description + +The definition of an object is a list of default object +properties. For example, the definition of the Stem object (available +in @file{scm/define-grobs.scm}), includes the following definitions +for @internalsref{Stem}: + +@example + (thickness . 1.3) + (beamed-lengths . (3.5 3.5 3.5 4.5 5.0)) + (Y-extent-callback . ,Stem::height) + @var{...} +@end example + + +Adding variables on top of this existing definition overrides the +system default, and alters the resulting appearance of the layout +object. + +@syntax + + +Changing a variable for only one object is commonly achieved with +@code{\once}: + +@example +\once \override @var{context}.@var{objectname} + @var{symbol} = @var{value} +@end example +Here @var{symbol} is a Scheme expression of symbol type, @var{context} +and @var{objectname} is a string and @var{value} is a Scheme expression. +This command applies a setting only during one moment in the score. + +In the following example, only one @internalsref{Stem} object is +changed from its original setting: + +@lilypond[verbatim,fragment,relative=1] + c4 + \once \override Voice.Stem #'thickness = #4 + c4 + c4 +@end lilypond +@cindex @code{\once} + +For changing more objects, the same command, without @code{\once} can +be used: +@example +\override @var{context}.@var{objectname} @var{symbol} = @var{value} +@end example +This command adds @code{@var{symbol} = @var{value}} to the definition +of @var{objectname} in the context @var{context}, and this definition +stays in place until it is removed. + +An existing definition may be removed by the following command: +@c +@example +\property @var{context}.@var{objectname} \revert @var{symbol} +@end example +@c + +Some examples: +@lilypond[verbatim] +c'4 \override Stem #'thickness = #4.0 +c'4 +c'4 \revert Stem #'thickness +c'4 +@end lilypond + +The following example gives exactly the same result as the previous +one (assuming the system default for stem thickness is 1.3): +@c +@lilypond[verbatim] + c'4 \override Stem #'thickness = #4.0 + c'4 + c'4 \override Stem #'thickness = #1.3 + c'4 +@end lilypond + +Reverting a setting which was not set in the first place has no +effect. + + +@seealso + +Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty}, +@internalsref{PropertySet}, @internalsref{All-backend-properties}, and +@internalsref{All-layout-objects}. + + +@refbugs + +The back-end is not very strict in type-checking object properties. +Cyclic references in Scheme values for properties can cause hangs +and/or crashes. + +@menu +* Constructing a tweak:: +* Applyoutput:: +* Font selection:: +* Text markup:: +@end menu + +@node Constructing a tweak +@subsection Constructing a tweak + + +@cindex internal documentation +@cindex finding graphical objects +@cindex graphical object descriptions +@cindex tweaking +@cindex @code{\override} +@cindex @code{\set} +@cindex internal documentation + + + +Three pieces of information are required to use @code{\override} and +@code{\set}: the name of the layout object, the context and the name +of the property. We demonstrate how to glean this information from +the notation manual and the generated documentation. + +The generated documentation is a set of HTML pages which should be +included if you installed a binary distribution, typically in +@file{/usr/share/doc/lilypond}. They are also available on the web: +go to the @uref{http://lilypond.org,LilyPond website}, click +``Documentation'', select the correct version, and click then +``Program reference.'' It is advisable to bookmark the local HTML +files. They will load faster than the ones on the web. If you use the +version from the web, you must check whether the documentation matches +the program version: it is generated from the definitions that the +program uses, and therefore it is strongly tied to the LilyPond +version. + + +@c [TODO: revise for new site.] + +Suppose we want to move the fingering indication in the fragment below: + +@lilypond[relative=2,verbatim] +c-2 +\stemUp +f +@end lilypond + +If you visit the documentation of @code{Fingering} (in @ref{Fingering +instructions}), you will notice that there is written: + +@quotation +@seealso + +Internals: @internalsref{FingerEvent} and @internalsref{Fingering}. + +@end quotation + +@separate + +@noindent +In other words, the fingerings once entered, are internally stored as +@code{FingerEvent} music objects. When printed, a @code{Fingering} +layout object is created for every @code{FingerEvent}. + +The Fingering object has a number of different functions, and each of +those is captured in an interface. The interfaces are listed under +@internalsref{Fingering} in the program reference. + + + +The @code{Fingering} object has a fixed size +(@internalsref{item-interface}), the symbol is a piece of text +(@internalsref{text-interface}), whose font can be set +(@internalsref{font-interface}). It is centered horizontally +(@internalsref{self-alignment-interface}), it is placed next to other +objects (@internalsref{side-position-interface}) vertically, and its +placement is coordinated with other scripts +(@internalsref{text-script-interface}). It also has the standard +@internalsref{grob-interface} (grob stands for Graphical object) +@cindex grob +@cindex graphical object +@cindex layout object +@cindex object, layout +with all the variables that come with +it. Finally, it denotes a fingering instruction, so it has +@internalsref{finger-interface}. + +For the vertical placement, we have to look under +@code{side-position-interface}: +@quotation +@code{side-position-interface} + + Position a victim object (this one) next to other objects (the + support). In this case, the property @code{direction} signifies where to put the + victim object relative to the support (left or right, up or down?) +@end quotation + +@cindex padding +@noindent +below this description, the variable @code{padding} is described as +@quotation +@table @code +@item padding + (dimension, in staff space) + + add this much extra space between objects that are next to each +other. Default value: @code{0.6} +@end table +@end quotation + +By increasing the value of @code{padding}, we can move away the +fingering. The following command inserts 3 staff spaces of white +between the note and the fingering: +@example +\once \override Fingering #'padding = #3 +@end example + +Inserting this command before the Fingering object is created, +i.e. before @code{c2}, yields the following result: + +@lilypond[relative=2,fragment,verbatim] +\once \override Fingering + #'padding = #3 +c-2 +\stemUp +f +@end lilypond + +The context name @code{Voice} in the example above can be determined +as follows. In the documentation for @internalsref{Fingering}, it says +@quotation +Fingering grobs are created by: @internalsref{Fingering_engraver} @c +@end quotation + +Clicking @code{Fingering_engraver} shows the documentation of +the module responsible for interpreting the fingering instructions and +translating them to a @code{Fingering} object. Such a module is called +an @emph{engraver}. The documentation of the @code{Fingering_engraver} +says +@example +Fingering_engraver is part of contexts: Voice +@end example +so tuning the settings for Fingering should be done with +@example + \override Fingering @dots{} +@end example + +Of course, the tweak may also done in a larger context than +@code{Voice}, for example, @internalsref{Staff} or +@internalsref{Score}. + +@seealso + +Internals: the program reference also contains alphabetical lists of +@internalsref{Contexts}, @internalsref{All-layout-objects} and +@internalsref{Music-expressions}, so you can also find which objects +to tweak by browsing the internals document. + + + + +@node Font selection +@subsection Font selection + +The most common thing to change about the appearance of fonts is their +size. The font size of any context can be easily changed by setting +the @code{fontSize} property for that context. Its value is a number: +negative numbers make the font smaller, positive numbers larger. An +example is given below: +@c +@lilypond[fragment,relative=1,verbatim] + c4 c4 \set fontSize = #-1 + f4 g4 +@end lilypond +This command will set @code{font-size} (see below), and does +not change the size of variable symbols, such as beams or slurs. + +One of the uses of @code{fontSize} is to get smaller symbols for cue +notes. An elaborate example of those is in +@inputfileref{input/test,cue-notes.ly}. + +@cindex magnification +@cindex cue notes + +The font used for printing a object can be selected by setting +@code{font-name}, e.g. +@example + \override Staff.TimeSignature + #'font-name = #"cmr17" +@end example + +@noindent +Any font can be used, as long as it is available to @TeX{}. Possible +fonts include foreign fonts or fonts that do not belong to the +Computer Modern font family. The size of fonts selected in this way +can be changed with the @code{font-magnification} property. For +example, @code{2.0} blows up all letters by a factor 2 in both +directions. + +@cindex font size +@cindex font magnification + +Font selection for the standard fonts, @TeX{}'s Computer Modern fonts, +can also be adjusted with a more fine-grained mechanism. By setting +the object properties described below, you can select a different font; +all three mechanisms work for every object that supports +@code{font-interface}: + + +@table @code +@item font-family + is 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, including ancient +glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}. + +@item font-shape + is a symbol indicating the shape of the font, there are typically several + font shapes available for each font family. Choices are @code{italic}, + @code{caps} and @code{upright}. + +@item font-series +is a symbol indicating the series of the font. There are typically several +font series for each font family and shape. Choices are @code{medium} +and @code{bold}. + +@end table + +For any of these properties, the value @code{*} (i.e. the symbol +@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used +to override default setting, which are always present. For example: +@example + \override Lyrics .LyricText #'font-series = #'bold + \override Lyrics .LyricText #'font-family = #'typewriter + \override Lyrics .LyricText #'font-shape = #'* +@end example + +@cindex @code{font-style} + +The font size is set by modifying the @code{font-size} property. Its +value is a number indicating the size relative to the standard size. +Each step up is an increase of approximately 12% of the font size. Six +steps is exactly a factor two. The Scheme function @code{magstep} +converts a @code{font-size} number to a scaling factor. + +LilyPond has fonts in different design sizes: the music fonts for +smaller sizes are chubbier, while the text fonts are relatively wider. +Font size changes are achieved by scaling the design size that is +closest to the desired size. + +The @code{font-size} mechanism does not work for fonts selected +through @code{font-name}. These may be scaled with +@code{font-magnification}. + +@refcommands + +The following commands set @code{fontSize} for the current voice. + +@cindex @code{\tiny} +@code{\tiny}, +@cindex @code{\small} +@code{\small}, +@cindex @code{\normalsize} +@code{\normalsize}. + +@seealso + +Init files: @file{ly/declarations-init.ly} contains hints how new +fonts may be added to LilyPond. + +@refbugs + +There is no style sheet provided for other fonts besides the @TeX{} +Computer Modern family. + +@cindex font selection +@cindex font magnification +@cindex @code{font-interface} + + +@node Text markup +@section Text markup +@cindex text markup +@cindex markup text + + +@cindex typeset text + +LilyPond has an internal mechanism to typeset texts. You can access it +with the keyword @code{\markup}. Within markup mode, you can enter texts +similar to lyrics: simply enter them, surrounded by spaces: +@cindex markup + +@lilypond[verbatim,fragment,relative=1] + c1^\markup { hello } + c1_\markup { hi there } + c1^\markup { hi \bold there, is \italic anyone home? } +@end lilypond + +@cindex font switching + +The markup in the example demonstrates font switching commands. The +command @code{\bold} and @code{\italic} only apply to the first +following word; enclose a set of texts with braces to apply a command +to more words: +@example + \markup @{ \bold @{ hi there @} @} +@end example + +@noindent +For clarity, you can also do this for single arguments, e.g. + +@verbatim + \markup { is \italic { anyone } home } +@end verbatim + +@cindex font size, texts + + +In markup mode you can compose expressions, similar to mathematical +expressions, XML documents and music expressions. The braces group +notes into horizontal lines. Other types of lists also exist: you can +stack expressions grouped with @code{<}, and @code{>} vertically with +the command @code{\column}. Similarly, @code{\center-align} aligns +texts by their center lines: + +@lilypond[verbatim,fragment,relative=1] + c1^\markup { \column < a bbbb c > } + c1^\markup { \center-align < a bbbb c > } + c1^\markup { \line < a b c > } +@end lilypond + + +Markups can be stored in variables, and these variables +may be attached to notes, like +@verbatim +allegro = \markup { \bold \large { Allegro } } +\notes { a^\allegro b c d } +@end verbatim + + +Some objects have alignment procedures of their own, which cancel out +any effects of alignments applied to their markup arguments as a +whole. For example, the @internalsref{RehearsalMark} is horizontally +centered, so using @code{\mark \markup @{ \left-align .. @}} has no +effect. Similarly, whole texts over notes cannot be moved vertically +with @code{\raise}. For moving and aligning complete objects, grob +properties should be used. + + + +@seealso + +Init files: @file{scm/new-markup.scm}. + + +@refbugs + +Text layout is ultimately done by @TeX{}, which does kerning of +letters. LilyPond does not account for kerning, so texts will be +spaced slightly too wide. + +Syntax errors for markup mode are confusing. + +Markup texts cannot be used in the titling of the @code{\header} +field. Titles are made by La@TeX{}, so La@TeX{} commands should be used +for formatting. + + + +@menu +* Overview of text markup commands:: +@end menu + +@node Overview of text markup commands +@subsection Overview of text markup commands + +@include markup-commands.tely + + +@node Global layout +@section Global layout + +The global layout determined by three factors: the page layout, the +line breaks and the spacing. These all influence each other. The +choice of spacing determines how densely each system of music is set, +which influences where line breaks breaks are chosen, and thus +ultimately how many pages a piece of music takes. This section +explains how to tune the algorithm for spacing. + +Globally spoken, this procedure happens in three steps: first, +flexible distances (``springs'') are chosen, based on durations. All +possible line breaking combination are tried, and the one with the +best results---a layout that has uniform density and requires as +little stretching or cramping as possible---is chosen. When the score +is processed by @TeX{}, each page is filled with systems, and page breaks +are chosen whenever the page gets full. + + + +@menu +* Vertical spacing:: +* Horizontal spacing:: +* Font Size:: +* Line breaking:: +* Page layout:: +@end menu + + +@node Vertical spacing +@subsection Vertical spacing + +@cindex vertical spacing +@cindex distance between staves +@cindex staff distance +@cindex between staves, distance +@cindex staffs per page +@cindex space between staves + +The height of each system is determined automatically by LilyPond, to +keep systems from bumping into each other, some minimum distances are +set. By changing these, you can put staves closer together, and thus +put more systems onto one page. + +Normally staves are stacked vertically. To make +staves maintain a distance, their vertical size is padded. This is +done with the property @code{minimumVerticalExtent}. It takes a pair +of numbers, so if you want to make it smaller from its, then you could +set +@example + \set Staff.minimumVerticalExtent = #'(-4 . 4) +@end example +This sets the vertical size of the current staff to 4 staff spaces on +either side of the center staff line. The argument of +@code{minimumVerticalExtent} is interpreted as an interval, where the +center line is the 0, so the first number is generally negative. The +staff can be made larger at the bottom by setting it to @code{(-6 +. 4)}. + +The piano staves are handled a little differently: to make cross-staff +beaming work correctly, it is necessary that the distance between staves +is fixed beforehand. This is also done with a +@internalsref{VerticalAlignment} object, created in +@internalsref{PianoStaff}. In this object the distance between the +staves is fixed by setting @code{forced-distance}. If you want to +override this, use a @code{\translator} block as follows: +@example + \paper @{ + \translator @{ + \PianoStaffContext + \override VerticalAlignment #'forced-distance = #9 + @} + @dots{} + @} +@end example +This would bring the staves together at a distance of 9 staff spaces, +measured from the center line of each staff. + +@seealso + +Internals: Vertical alignment of staves is handled by the +@internalsref{VerticalAlignment} object. + + + + +@node Horizontal spacing +@subsection Horizontal Spacing + +The spacing engine translates differences in durations into +stretchable distances (``springs'') of differing lengths. Longer +durations get more space, shorter durations get less. The shortest +durations get a fixed amount of space (which is controlled by +@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object). +The longer the duration, the more space it gets: doubling a +duration adds a fixed amount (this amount is controlled by +@code{spacing-increment}) of space to the note. + +For example, the following piece contains lots of half, quarter and +8th notes, the eighth note is followed by 1 note head width (NHW). +The quarter note is followed by 2 NHW, the half by 3 NHW, etc. +@lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8 +c8 c4 c4 c4 +@end lilypond + +Normally, @code{shortest-duration-space} is set to 1.2, which is the +width of a note head, and @code{shortest-duration-space} is set to +2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times +@code{shortest-duration-space}) of space. For normal notes, this space +is always counted from the left edge of the symbol, so the shortest +notes are generally followed by one NHW of space. + +If one would follow the above procedure exactly, then adding a single +32th note to a score that uses 8th and 16th notes, would widen up the +entire score a lot. The shortest note is no longer a 16th, but a 32nd, +thus adding 1 NHW to every note. To prevent this, the +shortest duration for spacing is not the shortest note in the score, +but the most commonly found shortest note. Notes that are even +shorter this are followed by a space that is proportional to their +duration relative to the common shortest note. So if we were to add +only a few 16th notes to the example above, they would be followed by +half a NHW: + +@lilypond[fragment,verbatim,relative=2] + c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4 +@end lilypond + +The most common shortest duration is determined as follows: in every +measure, the shortest duration is determined. The most common short +duration, is taken as the basis for the spacing, with the stipulation +that this shortest duration should always be equal to or shorter than +1/8th note. The shortest duration is printed when you run lilypond +with @code{--verbose}. These durations may also be customized. If you +set the @code{common-shortest-duration} in +@internalsref{SpacingSpanner}, then this sets the base duration for +spacing. The maximum duration for this base (normally 1/8th), is set +through @code{base-shortest-duration}. + +@cindex @code{common-shortest-duration} +@cindex @code{base-shortest-duration} +@cindex @code{stem-spacing-correction} +@cindex @code{spacing} + +In the introduction it was explained that stem directions influence +spacing. This is controlled with @code{stem-spacing-correction} +property in @internalsref{NoteSpacing}, which are generated for every +@internalsref{Voice} context. The @code{StaffSpacing} object +(generated at @internalsref{Staff} context) contains the same property +for controlling the stem/bar line spacing. The following example +shows these corrections, once with default settings, and once with +exaggerated corrections: + +@lilypond + \score { \notes { + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + \override Staff.NoteSpacing #'stem-spacing-correction + = #1.5 + \override Staff.StaffSpacing #'stem-spacing-correction + = #1.5 + c'4 e''4 e'4 b'4 | + b'4 e''4 b'4 e''4| + } + \paper { raggedright = ##t } } +@end lilypond + +@cindex SpacingSpanner, overriding properties + +Properties of the @internalsref{SpacingSpanner} must be overridden +from the @code{\paper} block, since the @internalsref{SpacingSpanner} is +created before any property commands are interpreted. +@example +\paper @{ \translator @{ + \ScoreContext + SpacingSpanner \override #'spacing-increment = #3.0 +@} @} +@end example + + +@seealso + +Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, +@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and +@internalsref{SeparatingGroupSpanner}. + +@refbugs + +Spacing is determined on a score wide basis. If you have a score that +changes its character (measured in durations) halfway during the +score, the part containing the longer durations will be spaced too +widely. + +There is no convenient mechanism to manually override spacing. + + + +@node Font Size +@subsection Font size +@cindex font size, setting +@cindex staff size, setting +@cindex @code{paper} file + +The Feta font provides musical symbols at eight seven different +sizes. Each font is tuned for a different staff size: at smaller sizes +the font gets heavier, to match the relatively heavier staff lines. +The recommended font sizes are listed in the following table: + +@multitable @columnfractions .25 .25 .25 .25 + +@item @b{name} +@tab @b{staff height (pt)} +@tab @b{staff height (mm)} +@tab @b{use} + +@item feta11 +@tab 11.22 +@tab 3.9 +@tab pocket scores + +@item feta13 +@tab 12.60pt +@tab 4.4mm +@tab + +@item feta14 +@tab 14.14pt +@tab 5.0mm +@tab + +@item feta16 +@tab 15.87pt +@tab 5.6mm +@tab + +@item feta18 +@tab 17.82pt +@tab 6.3mm +@tab song books + +@item feta20 +@tab 17.82pt +@tab 7.0mm +@tab standard parts + +@item feta23 +@tab 22.45 pt +@tab 7.9mm +@tab + +@item feta20 +@tab 25.2 pt +@tab 8.9mm +@tab +@c modern rental material ? + +@end multitable + +These fonts are available in any sizes. The context property +@code{fontSize} and the layout property @code{staff-space} (in +@internalsref{StaffSymbol}) can be used to tune size for individual +staffs. The size of individual staffs are relative to the global size, +which can be set in the following manner: + +@example + #(set-global-staff-size 14) +@end example + +This sets the global default size to 14pt staff height, and scales all +fonts accordingly. + + + +@node Line breaking +@subsection Line breaking + +@cindex line breaks +@cindex breaking lines + +Line breaks are normally computed automatically. They are chosen such +that lines look neither cramped nor loose, and that consecutive lines +have similar density. + +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. 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 +point. + + +@cindex regular line breaks +@cindex four bar music. + +For line breaks at regular intervals use @code{\break} separated by +skips and repeated with @code{\repeat}: +@example +<< \repeat unfold 7 @{ + s1 \noBreak s1 \noBreak + s1 \noBreak s1 \break @} + @emph{the real music} +>> +@end example + +@noindent +This makes the following 28 measures (assuming 4/4 time) be broken every +4 measures, and only there. + +@refcommands + +@code{\break}, @code{\noBreak} +@cindex @code{\break} +@cindex @code{\noBreak} + +@seealso + +Internals: @internalsref{BreakEvent}. + + +@node Page layout +@subsection Page layout + +@cindex page breaks +@cindex breaking pages + +@cindex @code{indent} +@cindex @code{linewidth} + +The most basic settings influencing the spacing are @code{indent} and +@code{linewidth}. They are set in the @code{\paper} block. They +control the indentation of the first line of music, and the lengths of +the lines. + +If @code{raggedright} is set to true in the @code{\paper} +block, then the lines are justified at their natural length. This +useful for short fragments, and for checking how tight the natural +spacing is. + +@cindex page layout +@cindex vertical spacing + +The page layout process happens outside the LilyPond formatting +engine: variables controlling page layout are passed to the output, +and are further interpreted by @code{lilypond} wrapper program. It +responds to the following variables in the @code{\paper} block. The +variable @code{textheight} sets the total height of the music on each +page. The spacing between systems is controlled with +@code{interscoreline}, its default is 16pt. The distance between the +score lines will stretch in order to fill the full page +@code{interscorelinefill} is set to a positive number. In that case +@code{interscoreline} specifies the minimum spacing. + +@cindex @code{textheight} +@cindex @code{interscoreline} +@cindex @code{interscorelinefill} + +If the variable @code{lastpagefill} is defined, +@c fixme: this should only be done if lastpagefill= #t +systems are evenly distributed vertically on the last page. This +might produce ugly results in case there are not enough systems on the +last page. The @command{lilypond-book} command ignores +@code{lastpagefill}. See @ref{lilypond-book manual} for more +information. + +@cindex @code{lastpagefill} + +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. This +is done by setting the @code{between-systems-strings} on the +@internalsref{NonMusicalPaperColumn} where the system is broken. +An example is shown in @inputfileref{input/regression,between-systems.ly}. +The predefined command @code{\newpage} also does this. + +@cindex paper size +@cindex page size +@cindex @code{papersize} + +To change the paper size, use the following Scheme code: +@example + \paper@{ + #(set-paper-size "a4") + @} +@end example + + +@refcommands + +@cindex @code{\newpage} +@code{\newpage}. + + +@seealso + +In this manual: @ref{Invoking lilypond}. + +Examples: @inputfileref{input/regression,between-systems.ly}. + +Internals: @internalsref{NonMusicalPaperColumn}. + +@refbugs + +LilyPond has no concept of page layout, which makes it difficult to +reliably choose page breaks in longer pieces. + + +@node Interpretation context +@section Interpretation context + +@menu +* Creating contexts:: +* Default contexts:: +* Context properties:: +* Defining contexts:: +* Changing contexts locally:: +* Engravers and performers:: +* Defining new contexts:: +@end menu + + +Interpretation contexts are objects that only exist during program +run. During the interpretation phase (when @code{interpreting music} +is printed on the standard output), the music expression in a +@code{\score} block is interpreted in time order, the same order in +which we hear and play the music. During this phase, the interpretation +context holds the state for the current point within the music, for +example: +@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 @internalsref{Voice} context is +contained in a @internalsref{Staff} context (because a staff can contain +multiple voices at any point), a @internalsref{Staff} context is contained in +@internalsref{Score}, @internalsref{StaffGroup}, or +@internalsref{ChoirStaff} context. + +Contexts associated with sheet music output are called @emph{notation +contexts}, those for sound output are called @emph{performance +contexts}. The default definitions of the standard notation and +performance contexts can be found in @file{ly/engraver-init.ly} and +@file{ly/performer-init.ly}, respectively. + + +@node Creating contexts +@subsection Creating contexts +@cindex @code{\context} +@cindex context selection + +Contexts for a music expression can be selected manually, using one of +the following music expressions: + +@example +\new @var{contexttype} @var{musicexpr} +\context @var{contexttype} [= @var{contextname}] @var{musicexpr} +@end example + +@noindent +This means that @var{musicexpr} should be interpreted within a context +of type @var{contexttype} (with name @var{contextname} if specified). +If no such context exists, it will be created: + +@lilypond[verbatim,raggedright] +\score { + \notes \relative c'' { + c4 <> f + } +} +@end lilypond + +@noindent +In this example, the @code{c} and @code{d} are printed on the default +staff. For the @code{e}, a context @code{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}. A context is ended when when all music referring it has +finished, so after the third quarter, @code{another} is removed. + +The @code{\new} construction creates a context with a +generated, unique @var{contextname}. An expression with +@code{\new} always leads to a new context. This is convenient +for creating multiple staffs, multiple lyric lines, etc. + +When using automatic staff changes, automatic phrasing, etc., the +context names have special meanings, so @code{\new} cannot be +used. + + +@node Default contexts +@subsection Default contexts + +Every top level music is interpreted by the @code{Score} context; in +other words, you may think of @code{\score} working like + +@example +\score @{ + \context Score @var{music} +@} +@end example + +Music expressions inherit their context from the enclosing music +expression. Hence, it is not necessary to explicitly specify +@code{\context} for most expressions. In +the following example, only the sequential expression has an explicit +context. The notes contained therein inherit the @code{goUp} context +from the enclosing music expression. + +@lilypond[verbatim,raggedright] + \notes \context Voice = goUp { c'4 d' e' } +@end lilypond + + +Second, contexts are created automatically to be able to interpret the +music expressions. Consider the following example: + +@lilypond[verbatim,raggedright] + \score { \notes { c'4-( d' e'-) } } +@end lilypond + +@noindent +The sequential music is interpreted by the Score context initially, +but when a note is encountered, contexts are setup to accept that +note. In this case, a @code{Voice}, and @code{Staff} +context are created. The rest of the sequential music is also +interpreted with the same @code{Voice}, and +@code{Staff} context, putting the notes on the same staff, in the same +voice. + +@node Context properties +@subsection Context properties + +Contexts have properties. These properties are set from the @file{.ly} +file using the following expression: +@cindex context properties +@cindex properties, context + +@example +\set @var{contextname}.@var{propname} = @var{value} +@end example + +@noindent +Sets the @var{propname} property of the context @var{contextname} to +the specified Scheme expression @var{value}. Both @var{propname} and +@var{contextname} are strings, which can often be written unquoted. + +@cindex inheriting +Properties that are set in one context are inherited by all of the +contained contexts. This means that a property valid for the +@internalsref{Voice} context can be set in the @internalsref{Score} context +(for example) and thus take effect in all @internalsref{Voice} contexts. + +Properties can be unset using the following statement. +@example +\unset @var{contextname}.@var{propname} +@end example + +@cindex properties, unsetting +@cindex @code{\unset} + +@noindent +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. + +If @var{contextname} is left out, then it defaults to the current +``bottom'' context: this is a context like @internalsref{Voice} that +cannot contain any other contexts. + + +@node Defining contexts +@subsection Defining contexts + +@cindex context definition +@cindex translator definition + +The most common way to create a new context definition is by extending +an existing one. An existing context from the paper block is copied +by referencing a context identifier: + +@example +\paper @{ + \translator @{ + @var{context-identifier} + @} +@} +@end example + +@noindent +Every predefined context has a standard identifier. For example, the +@code{Staff} context can be referred to as @code{\StaffContext}. + +The context can then be modified by setting or changing properties, +e.g. +@example +\translator @{ + \StaffContext + Stem \set #'thickness = #2.0 + defaultBarType = #"||" +@} +@end example +These assignments happen before interpretation starts, so a property +command will override any predefined settings. + +@cindex engraver + +@refbugs + +It is not possible to collect multiple property assignments in a +variable, and apply to one @code{\translator} definition by +referencing that variable. + +@node Changing contexts locally +@subsection Changing contexts locally + + +Extending an existing context can also be done locally. A piece of +music can be interpreted in a changed context by using the following syntax + +@example + \with @{ + @var{context modifications} + @} +@end example + +These statements comes between @code{\new} or @code{\context} and the +music to be interpreted. The @var{context modifications} property +settings and @code{\remove}, @code{\consists} and @code{\consistsend} +commands. The syntax is similar to the @code{\translator} block. + +The following example shows how a staff is created with bigger spaces, +and without a @code{Clef_engraver}. + +@lilypond[relative=1,fragment,verbatim] +<< + \new Staff { c4 es4 g2 } + \new Staff \with { + \override StaffSymbol #'staff-space = #(magstep 1.5) + fontSize = #1.5 + \remove "Clef_engraver" + } { + c4 es4 g2 + } >> +@end lilypond + +@refbugs + +The command @code{\with} has no effect on contexts that already +exist. + + +@node Engravers and performers +@subsection Engravers and performers + + +Each context is composed of a number of building blocks, or plug-ins +called engravers. An engraver is a specialized C++ class that is +compiled into the executable. Typically, an engraver is responsible +for one function: the @code{Slur_engraver} creates only @code{Slur} +objects, and the @code{Skip_event_swallow_translator} only swallows +(silently gobbles) @code{SkipEvent}s. + + + +@cindex engraver +@cindex plug-in + +An existing context definition can be changed by adding or removing an +engraver. The syntax for these operations is +@example +\consists @var{engravername} +\remove @var{engravername} +@end example + +@cindex @code{\consists} +@cindex @code{\remove} + +@noindent +Here @var{engravername} is a string, the name of an engraver in the +system. In the following example, the @code{Clef_engraver} is removed +from the Staff context. The result is a staff without a clef, where +the middle C is at its default position, the center line: + +@lilypond[verbatim,raggedright] +\score { + \notes { + c'4 f'4 + } + \paper { + \translator { + \StaffContext + \remove Clef_engraver + } + } +} +@end lilypond + +A list of all engravers is in the internal documentation, +see @internalsref{Engravers}. + +@node Defining new contexts +@subsection Defining new contexts + + +It is also possible to define new contexts from scratch. To do this, +you must define give the new context a name. In the following +example, a very simple Staff context is created: one that will put +note heads on a staff symbol. + +@example +\translator @{ + \type "Engraver_group_engraver" + \name "SimpleStaff" + \alias "Staff" + \consists "Staff_symbol_engraver" + \consists "Note_head_engraver" + \consistsend "Axis_group_engraver" +@} +@end example + +@noindent +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}. This +should always be @code{Engraver_group_engraver} (unless you are +defining a Score context from scratch, in which case +@code{Score_engraver} must be used). + +The complete list of context modifiers is the following: +@itemize @bullet +@item @code{\alias} @var{alternate-name}: +This specifies a different name. In the above example, +@code{\set 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. + +Engravers that group context objects into axis groups or alignments +need to be at the end of the list. @code{\consistsend} insures that +engravers stay at the end even if a user adds or removes engravers. + +@item @code{\accepts} @var{contextname}: +This context can contains @var{contextname} contexts. The first +@code{\accepts} is created as a default context when events (e.g. notes +or rests) are encountered. + +@item @code{\denies}: +The opposite of @code{\accepts}. + +@item @code{\name} @var{contextname}: +This sets the type name of the context, e.g. @code{Staff}, +@code{Voice}. If the name is not specified, the translator will not +do anything. +@end itemize + +@c EOF + + + + +@node Output details +@section Output details + +The default output format is La@TeX{}, which should be run +through La@TeX{}. Using the option @option{-f} +(or @option{--format}) other output formats can be selected also, but +currently none of them work reliably. + +At the beginning of the output file, various global parameters are +defined. Then the file @file{lilyponddefs.tex} is loaded to define +the macros used in the code which follows. @file{lilyponddefs.tex} +includes various other files, partially depending on the global +parameters. + +Now the music is output system by system (a `system' consists of all +staves belonging together). From @TeX{}'s point of view, a system is an +@code{\hbox} which contains a lowered @code{\vbox} so that it is centered +vertically on the baseline of the text. Between systems, +@code{\interscoreline} is inserted vertically to have stretchable space. +The horizontal dimension of the @code{\hbox} is given by the +@code{linewidth} parameter from LilyPond's @code{\paper} block. + +After the last system LilyPond emits a stronger variant of +@code{\interscoreline} only if the macro +@code{\lilypondpaperlastpagefill} is not defined (flushing the systems +to the top of the page). You can avoid that by setting the variable +@code{lastpagefill} in LilyPond's @code{\paper} block. + +It is possible to fine-tune the vertical offset further by defining the +macro @code{\lilypondscoreshift}: + +@example +\def\lilypondscoreshift@{0.25\baselineskip@} +@end example + +@noindent +where @code{\baselineskip} is the distance from one text line to the next. + +Here an example how to embed a small LilyPond file @code{foo.ly} into +running La@TeX{} text without using the @code{lilypond-book} script +(@pxref{lilypond-book manual}): + +@example +\documentclass@{article@} + +\def\lilypondpaperlastpagefill@{@} +\lineskip 5pt +\def\lilypondscoreshift@{0.25\baselineskip@} + +\begin@{document@} +This is running text which includes an example music file +\input@{foo.tex@} +right here. +\end@{document@} +@end example + +The file @file{foo.tex} has been simply produced with + +@example + lilypond-bin foo.ly +@end example + +The call to @code{\lineskip} assures that there is enough vertical space +between the LilyPond box and the surrounding text lines. + diff --git a/Documentation/user/internals.itely b/Documentation/user/internals.itely deleted file mode 100644 index b152463824..0000000000 --- a/Documentation/user/internals.itely +++ /dev/null @@ -1,966 +0,0 @@ -@c -*-texinfo-*- -@c Note: -@c -@c A menu is needed before every deeper *section nesting of @nodes -@c Run M-x texinfo-all-menus-update -@c to automatically fill in these menus -@c before saving changes - - -@node Technical manual -@chapter Technical manual - - -When LilyPond is run, it reads music from a file, translates that into -notation, and outputs the result to a file. The most important steps -are the first three. Consequently, there are three important basic -concepts within LilyPond: music, translation and layout. The -following diagram illustrates the concepts, and list the terminology -associated with each step. - - -@verbatim - - +-------------+ Translation +----------+ - | | | | - | Music | ------------------> | Layout | - | | | | - +-------------+ +----------+ - - -Syntax: c4 \context \set #'padding = - \override - -Objects: Music expressions Contexts Layout object - Engravers (aka. Grob) - -Example objects: NoteEvent Voice NoteHead - Note_heads_engraver - -Example properties: #'pitch keySignature #'line-count - -User applications: none various tuning layout - -@end verbatim - -The objects passed around in LilyPond have @emph{properties}, -variables that can contain many different types of information. Users -can set these variables, to modify the default behavior. Since there -are three different main concepts, there are also three types of -properties: - -@cindex properties -@cindex concepts, main -@cindex context -@cindex music expressions -@cindex layout -@cindex grob - - -@table @b -@item Music properties -These are used internally, and most users will not see or use them. - -They use Scheme-style naming, i.e. lowercase words separated with -dashes: @code{pitch}, @code{tremolo-type}. - -@item Translation properties -These influence the translation process, and most users will encounter them -regularly. For example, beaming behavior is tuned with -@code{autoBeamSettings}. - -These use mixed-caps naming: @code{autoBeamSettings}, -@code{ignoreMelismata}. They are assigned as follows: -@example - \set ignoreMelismata = ... -@end example - -@item Layout properties -These are internally used in the formatting process. Consequently, to -tune formatting details, it is necessary to adjust these -properties. For example, some objects may be moved around vertically -by setting their @code{padding} property. - -These properties use Scheme-style naming: @code{c0-position}, -@code{break-align-symbol}. They most often assigned as follows: - -@example - \override Score.RehearsalMark #'break-align-symbol = ... -@end example - -@noindent -Here, @code{RehearsalMark} is the type of the layout object. - -@end table - -This chapter discusses details of the three concepts in more detail, -and explains how they are glued together in LilyPond with the embedded -Scheme interpreter. - -@menu -* Interpretation context:: -* Scheme integration:: -* Music storage format:: -* Lexical details:: -* Output details:: -@end menu - - -@node Interpretation context -@section Interpretation context - -@menu -* Creating contexts:: -* Default contexts:: -* Context properties:: -* Context evaluation:: -* Defining contexts:: -* Changing contexts locally:: -* Engravers and performers:: -* Defining new contexts:: -@end menu - - -Interpretation contexts are objects that only exist during program -run. During the interpretation phase (when @code{interpreting music} -is printed on the standard output), the music expression in a -@code{\score} block is interpreted in time order, the same order in -which we hear and play the music. During this phase, the interpretation -context holds the state for the current point within the music, for -example: -@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 @internalsref{Voice} context is -contained in a @internalsref{Staff} context (because a staff can contain -multiple voices at any point), a @internalsref{Staff} context is contained in -@internalsref{Score}, @internalsref{StaffGroup}, or -@internalsref{ChoirStaff} context. - -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called @emph{performance -contexts}. The default definitions of the standard notation and -performance contexts can be found in @file{ly/engraver-init.ly} and -@file{ly/performer-init.ly}, respectively. - - -@node Creating contexts -@subsection Creating contexts -@cindex @code{\context} -@cindex context selection - -Contexts for a music expression can be selected manually, using one of -the following music expressions: - -@example -\new @var{contexttype} @var{musicexpr} -\context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example - -@noindent -This means that @var{musicexpr} should be interpreted within a context -of type @var{contexttype} (with name @var{contextname} if specified). -If no such context exists, it will be created: - -@lilypond[verbatim,raggedright] -\score { - \notes \relative c'' { - c4 <> f - } -} -@end lilypond - -@noindent -In this example, the @code{c} and @code{d} are printed on the default -staff. For the @code{e}, a context @code{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}. A context is ended when when all music referring it has -finished, so after the third quarter, @code{another} is removed. - -The @code{\new} construction creates a context with a -generated, unique @var{contextname}. An expression with -@code{\new} always leads to a new context. This is convenient -for creating multiple staffs, multiple lyric lines, etc. - -When using automatic staff changes, automatic phrasing, etc., the -context names have special meanings, so @code{\new} cannot be -used. - - -@node Default contexts -@subsection Default contexts - -Every top level music is interpreted by the @code{Score} context; in -other words, you may think of @code{\score} working like - -@example -\score @{ - \context Score @var{music} -@} -@end example - -Music expressions inherit their context from the enclosing music -expression. Hence, it is not necessary to explicitly specify -@code{\context} for most expressions. In -the following example, only the sequential expression has an explicit -context. The notes contained therein inherit the @code{goUp} context -from the enclosing music expression. - -@lilypond[verbatim,raggedright] - \notes \context Voice = goUp { c'4 d' e' } -@end lilypond - - -Second, contexts are created automatically to be able to interpret the -music expressions. Consider the following example: - -@lilypond[verbatim,raggedright] - \score { \notes { c'4-( d' e'-) } } -@end lilypond - -@noindent -The sequential music is interpreted by the Score context initially, -but when a note is encountered, contexts are setup to accept that -note. In this case, a @code{Voice}, and @code{Staff} -context are created. The rest of the sequential music is also -interpreted with the same @code{Voice}, and -@code{Staff} context, putting the notes on the same staff, in the same -voice. - -@node Context properties -@subsection Context properties - -Contexts have properties. These properties are set from the @file{.ly} -file using the following expression: -@cindex context properties -@cindex properties, context - -@example -\set @var{contextname}.@var{propname} = @var{value} -@end example - -@noindent -Sets the @var{propname} property of the context @var{contextname} to -the specified Scheme expression @var{value}. Both @var{propname} and -@var{contextname} are strings, which can often be written unquoted. - -@cindex inheriting -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@internalsref{Voice} context can be set in the @internalsref{Score} context -(for example) and thus take effect in all @internalsref{Voice} contexts. - -Properties can be unset using the following statement. -@example -\unset @var{contextname}.@var{propname} -@end example - -@cindex properties, unsetting -@cindex @code{\unset} - -@noindent -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. - -If @var{contextname} is left out, then it defaults to the current -``bottom'' context: this is a context like @internalsref{Voice} that -cannot contain any other contexts. - - - -@node Context evaluation -@subsection Context evaluation - -Contexts can be modified during interpretation with Scheme code. The -syntax for this is -@example - \applycontext @var{function} -@end example - -@var{function} should be a Scheme function taking a single argument, -being the context to apply it to. The following code will print the -current bar number on the standard output during the compile: - -@example - \applycontext - #(lambda (x) - (format #t "\nWe were called in barnumber ~a.\n" - (ly:context-property x 'currentBarNumber))) -@end example - - - -@node Defining contexts -@subsection Defining contexts - -@cindex context definition -@cindex translator definition - -The most common way to create a new context definition is by extending -an existing one. An existing context from the paper block is copied -by referencing a context identifier: - -@example -\paper @{ - \translator @{ - @var{context-identifier} - @} -@} -@end example - -@noindent -Every predefined context has a standard identifier. For example, the -@code{Staff} context can be referred to as @code{\StaffContext}. - -The context can then be modified by setting or changing properties, -e.g. -@example -\translator @{ - \StaffContext - Stem \set #'thickness = #2.0 - defaultBarType = #"||" -@} -@end example -These assignments happen before interpretation starts, so a property -command will override any predefined settings. - -@cindex engraver - -@refbugs - -It is not possible to collect multiple property assignments in a -variable, and apply to one @code{\translator} definition by -referencing that variable. - -@node Changing contexts locally -@subsection Changing contexts locally - - -Extending an existing context can also be done locally. A piece of -music can be interpreted in a changed context by using the following syntax - -@example - \with @{ - @var{context modifications} - @} -@end example - -These statements comes between @code{\new} or @code{\context} and the -music to be interpreted. The @var{context modifications} property -settings and @code{\remove}, @code{\consists} and @code{\consistsend} -commands. The syntax is similar to the @code{\translator} block. - -The following example shows how a staff is created with bigger spaces, -and without a @code{Clef_engraver}. - -@lilypond[relative=1,fragment,verbatim] -<< - \new Staff { c4 es4 g2 } - \new Staff \with { - \override StaffSymbol #'staff-space = #(magstep 1.5) - fontSize = #1.5 - \remove "Clef_engraver" - } { - c4 es4 g2 - } >> -@end lilypond - -@refbugs - -The command @code{\with} has no effect on contexts that already -exist. - - -@node Engravers and performers -@subsection Engravers and performers - - -Each context is composed of a number of building blocks, or plug-ins -called engravers. An engraver is a specialized C++ class that is -compiled into the executable. Typically, an engraver is responsible -for one function: the @code{Slur_engraver} creates only @code{Slur} -objects, and the @code{Skip_event_swallow_translator} only swallows -(silently gobbles) @code{SkipEvent}s. - - - -@cindex engraver -@cindex plug-in - -An existing context definition can be changed by adding or removing an -engraver. The syntax for these operations is -@example -\consists @var{engravername} -\remove @var{engravername} -@end example - -@cindex @code{\consists} -@cindex @code{\remove} - -@noindent -Here @var{engravername} is a string, the name of an engraver in the -system. In the following example, the @code{Clef_engraver} is removed -from the Staff context. The result is a staff without a clef, where -the middle C is at its default position, the center line: - -@lilypond[verbatim,raggedright] -\score { - \notes { - c'4 f'4 - } - \paper { - \translator { - \StaffContext - \remove Clef_engraver - } - } -} -@end lilypond - -A list of all engravers is in the internal documentation, -see @internalsref{Engravers}. - -@node Defining new contexts -@subsection Defining new contexts - - -It is also possible to define new contexts from scratch. To do this, -you must define give the new context a name. In the following -example, a very simple Staff context is created: one that will put -note heads on a staff symbol. - -@example -\translator @{ - \type "Engraver_group_engraver" - \name "SimpleStaff" - \alias "Staff" - \consists "Staff_symbol_engraver" - \consists "Note_head_engraver" - \consistsend "Axis_group_engraver" -@} -@end example - -@noindent -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}. This -should always be @code{Engraver_group_engraver} (unless you are -defining a Score context from scratch, in which case -@code{Score_engraver} must be used). - -The complete list of context modifiers is the following: -@itemize @bullet -@item @code{\alias} @var{alternate-name}: -This specifies a different name. In the above example, -@code{\set 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. - -Engravers that group context objects into axis groups or alignments -need to be at the end of the list. @code{\consistsend} insures that -engravers stay at the end even if a user adds or removes engravers. - -@item @code{\accepts} @var{contextname}: -This context can contains @var{contextname} contexts. The first -@code{\accepts} is created as a default context when events (e.g. notes -or rests) are encountered. - -@item @code{\denies}: -The opposite of @code{\accepts}. - -@item @code{\name} @var{contextname}: -This sets the type name of the context, e.g. @code{Staff}, -@code{Voice}. If the name is not specified, the translator will not -do anything. -@end itemize - - -@node Scheme integration -@section Scheme integration - -@cindex Scheme -@cindex GUILE -@cindex Scheme, in-line code -@cindex accessing Scheme -@cindex evaluating Scheme -@cindex LISP - -LilyPond internally uses GUILE, a Scheme-interpreter, to represent -data throughout the whole program, and glue together different program -modules. For advanced usage, it is sometimes necessary to access and -program the Scheme interpreter. - -Scheme is a full-blown programming language, from the LISP -family. and a full discussion is outside the scope of this document. -Interested readers are referred to the website -@uref{http://www.schemers.org/} for more information on Scheme. - -The GUILE library for extension is documented at -@uref{http://www.gnu.org/software/guile}. -@ifinfo -When it is installed, the following link should take you to its manual -@ref{(guile.info)guile} -@end ifinfo - -@menu -* Inline Scheme:: -* Input variables and Scheme:: -* Assignments:: -@end menu - -@node Inline Scheme -@subsection Inline Scheme - -Scheme expressions can be entered in the input file by entering a -hash-sign (@code{#}). The expression following the hash-sign is -evaluated as Scheme. For example, the boolean value @var{true} is -@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t}, -and can be used in property assignments: -@example - \set Staff.autoBeaming = ##f -@end example - - -@node Input variables and Scheme -@subsection Input variables and Scheme - - -The input format supports the notion of variable: in the following -example, a music expression is assigned to a variable with the name -@code{traLaLa}. -@example - traLaLa = \notes @{ c'4 d'4 @} -@end example - -@noindent - -There is also a form of scoping: in the following example, the -@code{\paper} block also contains a @code{traLaLa} variable, which is -independent of the outer @code{\traLaLa}. -@example - traLaLa = \notes @{ c'4 d'4 @} - \paper @{ traLaLa = 1.0 @} -@end example -@c -In effect, each input file is a scope, and all @code{\header}, -@code{\midi} and @code{\paper} blocks are scopes nested inside that -toplevel scope. - -Both variables and scoping are implemented in the GUILE module system. -An anonymous Scheme module is attached to each scope. An assignment of -the form -@example - traLaLa = \notes @{ c'4 d'4 @} -@end example - -@noindent -is internally converted to a Scheme definition -@example - (define traLaLa @var{Scheme value of ``@code{\notes ... }''}) -@end example - -This means that input variables and Scheme variables may be freely -mixed. In the following example, a music fragment is stored in the -variable @code{traLaLa}, and duplicated using Scheme. The result is -imported in a @code{\score} by means of a second variable -@code{twice}: -@example - traLaLa = \notes @{ c'4 d'4 @} - - #(define newLa (map ly:music-deep-copy - (list traLaLa traLaLa))) - #(define twice - (make-sequential-music newLa)) - - \score @{ \twice @} -@end example - -In the above example, music expressions can be `exported' from the -input to the Scheme interpreter. The opposite is also possible. By -wrapping a Scheme value in the function @code{ly:export}, a Scheme -value is interpreted as if it were entered in LilyPond syntax: instead -of defining @code{\twice}, the example above could also have been -written as -@example - @dots{} - \score @{ #(ly:export (make-sequential-music newLa)) @} -@end example - - - - - -@node Assignments -@subsection Assignments -@cindex Assignments - -Variables allow objects to be assigned to names during the parse -stage. To assign a variable, use -@example -@var{name}@code{=}@var{value} -@end example -To refer to a variable, precede its name with a backslash: -`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of -the input-types listed above. Variable assignments can appear at top -level in the LilyPond file, but also in @code{\paper} blocks. - -A variable can be created with any string for its name, but for -accessing it in the LilyPond syntax, its name must consist of -alphabetic characters only, and may not be a keyword of the syntax. -There are no restrictions for naming and accessing variables in the -Scheme interpreter, - -The right hand side of a variable assignment is parsed completely -before the assignment is done, so variables may be redefined in terms -of its old value, e.g. -@c -@example -foo = \foo * 2.0 -@end example - -When a variable is referenced in LilyPond syntax, the information it -points to is copied. For this reason, a variable reference must -always be the first item in a block. - -@example -\paper @{ - foo = 1.0 - \paperIdent % wrong and invalid -@} -@end example - -@example -\paper @{ - \paperIdent % correct - foo = 1.0 -@} -@end example - - - -@node Music storage format -@section Music storage format - -Music in LilyPond is entered as music expressions. This section -discusses different types of music expressions, and explains how -information is stored internally. This internal storage is accessible -through the Scheme interpreter, so music expressions may be -manipulated using Scheme functions. - -@menu -* Music expressions:: -* Internal music representation:: -* Manipulating music expressions:: -@end menu - -@node Music expressions -@subsection Music expressions -@cindex music expressions - -Notes, rests, lyric syllables are music expressions. Small music -expressions may be combined to form larger ones, for example, by -enclosing a list of expressions in @code{\sequential @{ @}} or @code{<< ->>}. In the following example, a compound expression is formed out of -the quarter note @code{c} and a quarter note @code{d}: - -@example -\sequential @{ c4 d4 @} -@end example - -@cindex Sequential music -@cindex @code{\sequential} -@cindex sequential music -@cindex @code{<<} -@cindex @code{>>} -@cindex Simultaneous music -@cindex @code{\simultaneous} - -The two basic compound music expressions are simultaneous and -sequential music: - -@example -\sequential @code{@{} @var{musicexprlist} @code{@}} -\simultaneous @code{@{} @var{musicexprlist} @code{@}} -@end example - -For both, there is a shorthand: - -@example -@code{@{} @var{musicexprlist} @code{@}} -@end example - -@noindent -for sequential and - -@example -@code{<<} @var{musicexprlist} @code{>>} -@end example - -@noindent -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 -However, using @code{<<} and @code{>>} for entering chords leads to -various peculiarities. For this reason, a special syntax -for chords was introduced in version 1.7: @code{< >}. - - - - - -Other compound music expressions include: -@example -\repeat @var{expr} -\transpose @var{from} @var{to} @var{expr} -\apply @var{func} @var{expr} -\context @var{type} = @var{id} @var{expr} -\times @var{fraction} @var{expr} -@end example - -@node Internal music representation -@subsection Internal music representation - - - - - - -When a music expression is parsed, it is converted into a set of -Scheme music objects. The defining property of a music object is that -it takes up time. Time is a rational number that measures the length -of a piece of music, in whole notes. - -A music object has three kinds of types: -@itemize @bullet -@item - music name: Each music expression has a name, for example, a note -leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to -a @internalsref{SimultaneousMusic}. A list of all expressions -available is in the internals manual, under @internalsref{Music -expressions}. - -@item - `type' or interface: Each music name has several `types' or interface, - for example, a note is an @code{event}, but it is also a @code{note-event}, - a @code{rhythmic-event} and a @code{melodic-event}. - - All classes of music are listed in the internals manual, under - @internalsref{Music classes}. -@item -C++ object: Each music object is represented by a C++ object. For technical -reasons, different music objects may be represented by different C++ -object types. For example, a note is @code{Event} object, while -@code{\grace} creates a @code{Grace_music} object. - -We expect that distinctions between different C++ types will disappear -in the future. -@end itemize - -The actual information of a music expression is stored in properties. -For example, a @internalsref{NoteEvent} has @code{pitch} and -@code{duration} properties that store the pitch and duration of that -note. A list of all properties available is in the internals manual, -under @internalsref{Music properties}. - -A compound music expression is a music object that contains other -music objects in its properties. A list of objects can be stored in -the @code{elements} property of a music object, or a single `child' -music object in the @code{element} object. For example, -@internalsref{SequentialMusic} has its children in @code{elements}, -and @internalsref{GraceMusic} has its single argument in -@code{element}. The body of a repeat is in @code{element} property of -@internalsref{RepeatedMusic}, and the alternatives in @code{elements}. - -@node Manipulating music expressions -@subsection Manipulating music expressions - -Music objects and their properties can be accessed and manipulated -directly, through the @code{\apply} mechanism. -The syntax for @code{\apply} is -@example -\apply #@var{func} @var{music} -@end example - -@noindent -This means that the scheme function @var{func} is called with -@var{music} as its argument. The return value of @var{func} is the -result of the entire expression. @var{func} may read and write music -properties using the functions @code{ly:music-property} and -@code{ly:music-set-property!}. - -An example is a function that reverses the order of elements in -its argument: -@lilypond[verbatim,raggedright] - #(define (rev-music-1 m) - (ly:music-set-property! m 'elements (reverse - (ly:music-property m 'elements))) - m) - \score { \notes \apply #rev-music-1 { c4 d4 } } -@end lilypond - -The use of such a function is very limited. The effect of this -function is void when applied to an argument which is does not have -multiple children. The following function application has no effect: - -@example - \apply #rev-music-1 \grace @{ c4 d4 @} -@end example - -@noindent -In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no -@code{elements}, only a single @code{element}. Every generally -applicable function for @code{\apply} must -- like music expressions -themselves -- be recursive. - -The following example is such a recursive function: It first extracts -the @code{elements} of an expression, reverses them and puts them -back. Then it recurses, both on @code{elements} and @code{element} -children. -@example -#(define (reverse-music music) - (let* ((elements (ly:music-property music 'elements)) - (child (ly:music-property music 'element)) - (reversed (reverse elements))) - - ; set children - (ly:music-set-property! music 'elements reversed) - - ; recurse - (if (ly:music? child) (reverse-music child)) - (map reverse-music reversed) - - music)) -@end example - -A slightly more elaborate example is in -@inputfileref{input/test,reverse-music.ly}. - -Some of the input syntax is also implemented as recursive music -functions. For example, the syntax for polyphony -@example - <> -@end example - -@noindent -is actually implemented as a recursive function that replaces the -above by the internal equivalent of -@example - << \context Voice = "1" @{ \voiceOne a @} - \context Voice = "2" @{ \voiceTwo b @} >> -@end example - -Other applications of @code{\apply} are writing out repeats -automatically (@inputfileref{input/test,unfold-all-repeats.ly}), -saving keystrokes (@inputfileref{input/test,music-box.ly}) and -exporting -LilyPond input to other formats (@inputfileref{input/test,to-xml.ly}) - -@seealso - -@file{scm/music-functions.scm}, @file{scm/music-types.scm}, -@inputfileref{input/test,add-staccato.ly}, -@inputfileref{input/test,unfold-all-repeats.ly}, and -@inputfileref{input/test,music-box.ly}. - -@node Lexical details -@section Lexical details - - -@cindex string -@cindex concatenate - -By enclosing text in quotes (@code{"}), strings are formed. 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 does not contain spaces or special characters -can be written without the quotes. The exact form of such unquoted -strings depends on the input mode; there are different rules for -lyrics, notes and markups. Strings can be concatenated with the -@code{+} operator. - - -@node Output details -@section Output details - -The default output format is La@TeX{}, which should be run -through La@TeX{}. Using the option @option{-f} -(or @option{--format}) other output formats can be selected also, but -currently none of them work reliably. - -At the beginning of the output file, various global parameters are -defined. Then the file @file{lilyponddefs.tex} is loaded to define -the macros used in the code which follows. @file{lilyponddefs.tex} -includes various other files, partially depending on the global -parameters. - -Now the music is output system by system (a `system' consists of all -staves belonging together). From @TeX{}'s point of view, a system is an -@code{\hbox} which contains a lowered @code{\vbox} so that it is centered -vertically on the baseline of the text. Between systems, -@code{\interscoreline} is inserted vertically to have stretchable space. -The horizontal dimension of the @code{\hbox} is given by the -@code{linewidth} parameter from LilyPond's @code{\paper} block. - -After the last system LilyPond emits a stronger variant of -@code{\interscoreline} only if the macro -@code{\lilypondpaperlastpagefill} is not defined (flushing the systems -to the top of the page). You can avoid that by setting the variable -@code{lastpagefill} in LilyPond's @code{\paper} block. - -It is possible to fine-tune the vertical offset further by defining the -macro @code{\lilypondscoreshift}: - -@example -\def\lilypondscoreshift@{0.25\baselineskip@} -@end example - -@noindent -where @code{\baselineskip} is the distance from one text line to the next. - -Here an example how to embed a small LilyPond file @code{foo.ly} into -running La@TeX{} text without using the @code{lilypond-book} script -(@pxref{lilypond-book manual}): - -@example -\documentclass@{article@} - -\def\lilypondpaperlastpagefill@{@} -\lineskip 5pt -\def\lilypondscoreshift@{0.25\baselineskip@} - -\begin@{document@} -This is running text which includes an example music file -\input@{foo.tex@} -right here. -\end@{document@} -@end example - -The file @file{foo.tex} has been simply produced with - -@example - lilypond-bin foo.ly -@end example - -The call to @code{\lineskip} assures that there is enough vertical space -between the LilyPond box and the surrounding text lines. - -@c EOF diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 63d11155e3..ccf6611e67 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -644,10 +644,9 @@ The @ifhtml The @end ifhtml -@emph{@ref{Technical manual}} +@emph{@ref{Changing defaults}} @c -discusses the general design of the program, and how to extend its -functionality. +Explains how to fine tune layout. @item @ifhtml The chapter diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index 0e0b88ba94..1b3b612bc6 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -410,6 +410,7 @@ be skipped. Something is definitely wrong, and LilyPond cannot continue. This happens rarely. The most usual cause is misinstalled fonts. +@cindex trace, Scheme @cindex call trace @cindex Scheme error @item Scheme error diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index 8a187a9b08..7c6ecbe512 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -149,13 +149,14 @@ this and other documentation. * Tutorial:: A tutorial introduction. * Notation manual:: All notation supported, and how to produce it. -* Using LilyPond:: How it all works. -* Technical manual:: How it all works. +* Changing defaults:: Tuning output * Invoking LilyPond:: Operation. * Converting from other formats:: Converting to lilypond source format. * lilypond-book manual:: Integrating text and music with lilypond-book. * Unified index:: -* Reference manual details:: +* Notation manual details:: +* Literature list:: +* Interfaces for programmers:: * Cheat sheet:: * GNU Free Documentation License:: FDL. @end menu @@ -168,9 +169,8 @@ this and other documentation. @include preface.itely @include introduction.itely @include tutorial.itely -@include refman.itely -@include running.itely -@include internals.itely +@include notation.itely +@include changing-defaults.itely @include invoking.itexi @include lilypond-book.itely @include converters.itely @@ -182,8 +182,14 @@ this and other documentation. @printindex cp -@include appendices.itely +@include notation-appendices.itely + +@include literature.itely + +@include programming-interface.itely + @include cheatsheet.itely + @include fdl.itexi @bye diff --git a/Documentation/user/literature.itely b/Documentation/user/literature.itely index 9c9e938c7e..76eca96d05 100644 --- a/Documentation/user/literature.itely +++ b/Documentation/user/literature.itely @@ -1,5 +1,5 @@ @node Literature list -@section Literature list +@appendix Literature list If you need to know more about music notation, here are some interesting titles to read. The source archive includes a more diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely index c52bf5b2e5..369a2b7b06 100644 --- a/Documentation/user/music-glossary.tely +++ b/Documentation/user/music-glossary.tely @@ -944,7 +944,7 @@ also the contrapunctal technique used in the @emph{fugue} which, since the music of the baroque era, has been one of the most popular polyphonic composition methods. -@lilypond[staffsize=11,noquote] +@lilypond[staffsize=11] \override Score.TimeSignature #'style =\turnOff \notes\context PianoStaff << \context Staff = SA \relative c' { diff --git a/Documentation/user/notation-appendices.itely b/Documentation/user/notation-appendices.itely new file mode 100644 index 0000000000..a52168b642 --- /dev/null +++ b/Documentation/user/notation-appendices.itely @@ -0,0 +1,93 @@ +@node Notation manual details +@appendix Notation manual details + +@menu +* Chord name chart:: +* MIDI instruments:: +* The Feta font:: +* All context properties:: +* Layout properties:: +@end menu + + + +@node Chord name chart +@appendixsec Chord name chart + +@lilypondfile{chord-names-jazz.ly} + +@node MIDI instruments +@appendixsec MIDI instruments + +@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 appendixsection" "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)" "shakuhachi" "guitar fret noise" +"fretless bass" "whistle" "breath noise" +"slap bass 1" "ocarina" "seashore" +"slap bass 2" "lead 1 (square)" "bird tweet" +"synth bass 1" "lead 2 (sawtooth)" "telephone ring" +"synth bass 2" "lead 3 (calliope)" "helicopter" +"violin" "lead 4 (chiff)" "applause" +"viola" "lead 5 (charang)" "gunshot" +"cello" "lead 6 (voice)" +@end example + +@node The Feta font +@appendixsec The Feta font + +The following symbols are available in the Feta font and may be +accessed directly using text markup such as @code{g^\markup @{ +\musicglyph #"scripts-segno" @}}, see @ref{Text markup}. + + +@lilypondfile[noindent]{feta16list.ly} + + +@lilypondfile[noindent]{parmesan16list.ly} + + + +@node All context properties +@appendixsec All context properties + +@include context-properties.tely + + +@node Layout properties +@appendixsec Layout properties + +@include layout-properties.tely + diff --git a/Documentation/user/notation.itely b/Documentation/user/notation.itely new file mode 100644 index 0000000000..670e3047e3 --- /dev/null +++ b/Documentation/user/notation.itely @@ -0,0 +1,7648 @@ +@c Note: -*-texinfo-*- +@c This file is part of lilypond.tely + +@c A menu is needed before every deeper *section nesting of @node's; run +@c M-x texinfo-all-menus-update +@c to automatically fill in these menus before saving changes + +@node Notation manual +@chapter Notation manual + +This chapter describes all the different types of notation supported +by LilyPond. It is intended as a reference for users that are already +somewhat familiar with using LilyPond. + +@menu +* Note entry:: +* Easier music entry:: +* Staff notation:: +* Polyphony:: +* Beaming:: +* Accidentals:: +* Expressive marks:: +* Repeats:: +* Rhythmic music:: +* Piano music:: +* Vocal music:: +* Tablatures:: +* Chord names:: +* Orchestral music:: +* Ancient notation:: +* Contemporary notation:: +* Special notation:: +* Sound:: +@end menu + +@c FIXME: Note entry vs Music entry at top level menu is confusing. + +@node Note entry +@section Note entry +@cindex Note entry + +The basic elements of any piece of music are the notes. This section +is about basic notation elements notes, rests and related constructs, +such as stems, tuplets and ties. + +@menu +* Notes:: +* Pitches:: +* Chromatic alterations:: +* Chords:: +* Rests:: +* Skips:: +* Durations:: +* Stems:: +* Ties:: +* Tuplets:: +@end menu + + +@node Notes +@subsection Notes + + +A note is printed by specifying its pitch and then its duration: +@footnote{Notes constitute the most basic elements of LilyPond input, +but they do not form valid input on their own without a @code{\score} +block. However, for the sake of brevity and simplicity we will +generally omit @code{\score} blocks and @code{\paper} declarations in +this manual.} + +@lilypond[fragment,verbatim] + cis'4 d'8 e'16 c'16 +@end lilypond + + +@node Pitches +@subsection Pitches + +@cindex Pitch names +@cindex Note specification +@cindex pitches +@cindex entering notes + +The most common syntax for pitch entry is used in @code{\chords} and +@code{\notes} mode. In Note and Chord mode, pitches may be designated +by names. The notes are specified by the letters @code{a} through +@code{g}, while the octave is formed with 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: + +@lilypond[fragment,verbatim] +\clef bass + a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c'' +@end lilypond + +@cindex note names, Dutch + +A sharp is formed by adding @code{-is} to the end of a pitch name and +a flat is formed by adding @code{-es}. Double sharps and double flats +are obtained by adding @code{-isis} or @code{-eses}. These +names are the Dutch note names. In Dutch, @code{aes} is contracted to +@code{as}, but both forms are accepted. Similarly, both +@code{es} and @code{ees} are accepted. + +Half-flats and half-sharps are formed by adding @code{-eh} and +@code{-ih}; the following is a series of Cs with increasing pitches: + +@cindex quarter tones +@cindex semi-flats, semi-sharps + +@lilypond[verbatim,relative=2] + ceses4 + ceseh + ces + ceh + c + cih + cis + cisih + cisis +@end lilypond + +There are predefined sets of note names for various other languages. +To use them, include the language specific init file. For +example: @code{\include "english.ly"}. The available language files +and the note names they define are: + +@anchor{note name} +@anchor{note names} +@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 + -x (double) +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 +espanol.ly do re mi fa sol la sib si -s -b + +@end example + +@cindex @code{'} +@cindex @code{,} + + + +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] + c' c'' es' g' as' gisis' ais' +@end lilypond + + +@refcommands + +Notes can be hidden and unhidden with the following commands: + +@cindex @code{\hideNotes} +@code{\hideNotes}, +@cindex @code{\unHideNotes} +@code{\unHideNotes}. + + +@seealso + +Internals: @internalsref{NoteEvent}, and @internalsref{NoteHead}. + +@node Chromatic alterations +@subsection Chromatic alterations + +Normally accidentals are printed automatically, but you may also +print them manually. 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: + +@lilypond[fragment,verbatim] + cis' cis' cis'! cis'? +@end lilypond + + +The automatic production of accidentals can be tuned in many +ways. For more information, refer to @ref{Accidentals}. + +@node Chords +@subsection Chords + +A chord is formed by a enclosing a set of pitches in @code{<} and +@code{>}. A chord may be followed by a duration, and a set of +articulations, just like simple notes. + + +@node Rests +@subsection Rests +@cindex Rests + + + + +Rests are entered like notes, with the note name @code{r}: + +@lilypond[raggedright,verbatim] +r1 r2 r4 r8 +@end lilypond + +Whole bar rests, centered in middle of the bar, +must be done with multi measure rests. They are discussed in +@ref{Multi measure rests}. + + +A rest's vertical position may be explicitly specified by entering a +note with the @code{\rest} keyword appended. This makes manual +formatting in polyphonic music easier. Rest collision testing will +leave these rests alone: + +@lilypond[raggedright,verbatim] +a'4\rest d'4\rest +@end lilypond + +@seealso + +Internals: @internalsref{RestEvent}, and @internalsref{Rest}. + + +@c FIXME: naming. +@node Skips +@subsection Skips +@cindex Skip +@cindex Invisible rest +@cindex Space note + +An invisible rest (also called a `skip') can be entered like a note +with note name `@code{s}' or with @code{\skip @var{duration}}: + +@lilypond[raggedright,verbatim] +a2 s4 a4 \skip 1 a4 +@end lilypond + +The @code{s} syntax is only available in note mode and chord mode. In +other situations, you should use the @code{\skip} command: + +@lilypond[raggedright,verbatim] +\score { + \new Staff << + { \time 4/8 \skip 2 \time 4/4 } + \notes\relative c'' { a2 a1 } + >> +} +@end lilypond + +The skip command is merely an empty musical placeholder. It does not +produce any output, not even transparent output. + +The @code{s} skip command does create @internalsref{Staff} and +@internalsref{Voice} when necessary, similar to note and rest +commands. For example, the following results in an empty staff. + +@lilypond[raggedright,verbatim] +\score { \notes { s4 } } +@end lilypond + +The same fragment using @code{\skip} results in an empty page. + +@seealso + +Internals: @internalsref{SkipEvent}, @internalsref{SkipMusic}. + + + +@node Durations +@subsection Durations + + +@cindex duration + + +In Note, Chord, and Lyrics mode, durations are designated by numbers +and dots: durations are entered as their reciprocal values. For example, +a quarter note is entered using a @code{4} (since it is a 1/4 note), while +a half note is entered using a @code{2} (since it is a 1/2 note). For notes +longer than a whole you must use variables: + +@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 + +@lilypond[noindent] +\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" + \override StaffSymbol #'transparent = ##t + \override TimeSignature #'transparent = ##t + \consists "Pitch_squash_engraver" + } + } +} +@end lilypond + + +If the duration is omitted then it is set to the previously entered +duration. The default for the first note is a quarter note. The duration +can be followed by dots (`@code{.}') in order to obtain dotted note +lengths: +@cindex @code{.} + +@lilypond[fragment,verbatim] + a' b' c''8 b' a'4 a'4. b'4.. c'8. +@end lilypond +@cindex @code{r} +@cindex @code{s} + +You can alter the length of duration by a fraction @var{N/M} +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. +In the following example, the first three notes take up exactly two +beats: +@lilypond[fragment,relative=2,verbatim] + \time 2/4 + a4*2/3 gis4*2/3 a4*2/3 + a4 +@end lilypond + + +@refcommands + +Dots are normally moved up to avoid staff lines, except in polyphonic +situations. The following commands may be used to force a particular +direction manually: + +@cindex @code{\dotsUp} +@code{\dotsUp}, +@cindex @code{\dotsDown} +@code{\dotsDown}, +@cindex @code{\dotsBoth} +@code{\dotsBoth}. + +@seealso + +Internals: @internalsref{Dots}, and @internalsref{DotColumn}. + +@node Stems +@subsection Stems + +Whenever a note is found, a @internalsref{Stem} object is created +automatically. For whole notes and rests, they are also created but +made invisible. + +@refcommands + +@cindex @code{\stemUp} +@code{\stemUp}, +@cindex @code{\stemDown} +@code{\stemDown}, +@cindex @code{\stemBoth} +@code{\stemBoth}. + + +@node Ties +@subsection Ties + +@cindex Tie +@cindex ties +@cindex @code{~} + +A tie connects two adjacent note heads of the same pitch. The tie in +effect extends the length of a note. Ties should not be confused with +slurs, which indicate articulation, or phrasing slurs, which indicate +musical phrasing. A tie is entered using the tilde symbol `@code{~}': + +@lilypond[fragment,verbatim] + e' ~ e' ~ +@end lilypond + +When a tie is applied to a chord, all note heads whose pitches match +are connected. When no note heads match, no ties will be created. + +In its meaning a tie is just a way of extending a note duration, similar +to the augmentation dot; in the following example there are two ways of +notating exactly the same concept: +@c +@lilypond[fragment,raggedright] +\time 3/4 c'2. c'2 ~ c'4 +@end lilypond +If you need to tie a lot of notes over bars, it may be easier to use automatic +note splitting (see @ref{Automatic note splitting}). + +@refcommands + + +@cindex @code{\tieUp} +@code{\tieUp}, +@cindex @code{\tieDown} +@code{\tieDown}, +@cindex @code{\tieBoth} +@code{\tieBoth}, +@cindex @code{\tieDotted} +@code{\tieDotted}, +@cindex @code{\tieSolid} +@code{\tieSolid}. + +@seealso + +In this manual: @ref{Automatic note splitting}. + +Internals: @internalsref{TieEvent}, @internalsref{Tie}. + +For tying only a subset of the note heads of a pair of chords, see +@inputfileref{input/regression,tie-chord-partial.ly}. + +@refbugs + + +Switching staves when a tie is active will not produce a slanted tie. + +Formatting of ties is a difficult subject. The results are often not +optimal. + + + +@node Tuplets +@subsection Tuplets + +@cindex tuplets +@cindex triplets +@cindex @code{\times} + +Tuplets are made out of a music expression by multiplying all durations +with a fraction: + +@cindex @code{\times} +@example + \times @var{fraction} @var{musicexpr} +@end example + +@noindent +The duration of @var{musicexpr} will be multiplied by the fraction. +The fraction's denominator will be printed over the notes, optionally +with a bracket. The most common tuplet is the triplet in which 3 +notes have the length of 2, so the notes are 2/3 of their written +length: + +@lilypond[fragment,verbatim] + g'4 \times 2/3 {c'4 c' c'} d'4 d'4 +@end lilypond + +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, saving lots of typing. In the next +example, there are two triplets shown, while @code{\times} was only +used once: + +@lilypond[fragment,relative,raggedright,verbatim] +\set tupletSpannerDuration = #(ly:make-moment 1 4) +\times 2/3 { c'8 c c c c c } +@end lilypond + +The format of the number is determined by the property +@code{tupletNumberFormatFunction}. The default prints only the +denominator, but if it is set to the Scheme function +@code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed +instead. + + +@cindex @code{tupletNumberFormatFunction} +@cindex tuplet formatting + + +@refcommands + +@cindex @code{\tupletUp} +@code{\tupletUp}, +@cindex @code{\tupletDown} +@code{\tupletDown}, +@cindex @code{\tupletBoth} +@code{\tupletBoth}. + +@seealso + +Internals: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}. + +Examples: @inputfileref{input/regression,tuplet-nest.ly}. + +@refbugs + +Nested tuplets are not formatted automatically. In this case, outer +tuplet brackets should be moved manually, which is demonstrated in +@inputfileref{input/regression,tuplet-nest.ly}. + + + +@node Easier music entry +@section Easier music entry +@cindex Music entry + +When entering music it is easy to introduce errors. This section deals +with tricks and features of the input language that were added solely +to help entering music, and find and correct mistakes. + +It is also possible to use external programs, for example GUI +interfaces, or MIDI transcription programs, to enter or edit +music. Refer to the website for more information. Finally, there are +tools make debugging easier, by linking the input file and the output +shown on screen. See @ref{Point and click} for more information. + + +@menu +* Relative octaves:: +* Octave check:: +* Bar check:: +* Skipping corrected music:: +* Automatic note splitting:: +@end menu + + + + +@node Relative octaves +@subsection Relative octaves +@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. The relative +octave mode prevents these errors: a single error puts the rest of the +piece off by one octave: + +@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}. + +Here is the relative mode shown in action: +@lilypond[fragment,raggedright,verbatim] + \relative c'' { + b c d c b c bes a + } +@end lilypond + +Octave changing marks are used for intervals greater than a fourth: +@lilypond[fragment,verbatim] + \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: + +@lilypond[fragment,verbatim] + \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}. + +@node Octave check +@subsection Octave check + + +Octave checks make octave errors easier to correct: a note may be +followed by @code{=}@var{quotes} which indicates what its absolute +octave should be. In the following example, +@example + \relative c'' @{ c='' b=' d,='' @} +@end example + +@noindent +@c take care with @code, adds confusing quotes. +the d will generate a warning, because a d'' is expected, but a d' is +found. In the output, the octave is corrected this and the following +notes. + + + +There is also a syntax that is separate from the notes. +@example + \octave @var{pitch} +@end example + +This checks that @var{pitch} (without octave) yields @var{pitch} (with +octave) in \relative mode. If not, a warning is printed, and the +octave is corrected, for example, the first check is passed +successfully. The second check fails with an error message. The +octave is adjusted so the following notes are in the correct octave +once again. +@example + \relative c' @{ + e + \octave a' + \octave b' + @} +@end example + + +The octave of a note following an octave check is determined with +respect to the note preceding it. In the next fragment, the last note +is a @code{a'}, above middle C. Hence, the @code{\octave} check may +be deleted without changing the meaning of the piece. + +@lilypond[verbatim,fragment] + \relative c' { + e + \octave b + a + } +@end lilypond + +@node Bar check +@subsection Bar check +@cindex Bar check + +@cindex bar check +@cindex @code{barCheckSynchronize} +@cindex @code{|} + +Bar checks help detect errors in the durations. A bar check is +entered using the bar symbol, `@code{|}'. Whenever it is encountered +during interpretation, it should fall on a measure boundary. If it +does not, a warning is printed. Depending on the value of +@code{barCheckSynchronize}, the beginning of the measure will be +relocated. + +In the next example, the second bar check will signal an error: +@example + \time 3/4 c2 e4 | g2 | +@end example + +Bar checks can also be used in lyrics, for example + +@example + \lyrics @{ + \time 2/4 + Twin -- kle | Twin -- kle + @} +@end example + + +@cindex skipTypesetting + +Failed bar checks are caused by entering incorrect +durations. Incorrect durations often completely garble up the score, +especially if it is polyphonic, so you should start correcting the +score by scanning for failed bar checks and incorrect durations. To +speed up this process, you can use @code{skipTypesetting}, described +in the next section. + +@node Skipping corrected music +@subsection 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. +This can be used to skip over the parts of a score that have already +been checked for errors: + +@lilypond[fragment,raggedright,verbatim] +\relative c'' { c8 d +\set Score.skipTypesetting = ##t + e f g a g c, f e d +\set Score.skipTypesetting = ##f +c d b bes a g c2 } +@end lilypond + +@node Automatic note splitting +@subsection Automatic note splitting + +Long notes can be converted automatically to tied notes. This is done +by replacing the @internalsref{Note_heads_engraver} by the +@internalsref{Completion_heads_engraver}. +In the following examples, notes crossing the bar line are split and tied. + + +@lilypond[noindent,verbatim,relative=1] +\new Voice \with { + \remove "Note_heads_engraver" + \consists "Completion_heads_engraver" +} { + c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 +} +@end lilypond + +This engraver splits all running notes at the bar line, and inserts +ties. One of its uses is to debug complex scores: if the measures are +not entirely filled, then the ties exactly show how much each measure +is off. + +@refbugs + +Not all durations (especially those containing tuplets) can be +represented exactly; the engraver will not insert tuplets. + +@seealso + +Examples: @inputfileref{input/regression,completion-heads.ly}. + +Internals: @internalsref{Completion_heads_engraver}. + + +@node Staff notation +@section Staff notation + +This section describes music notation that occurs on staff level, +such as keys, clefs and time signatures. + +@cindex Staff notation + +@menu +* Staff symbol:: +* Key signature:: +* Clef:: +* Ottava brackets:: +* Time signature:: +* Partial measures:: +* Unmetered music:: +* Bar lines:: +@end menu + +@node Staff symbol +@subsection Staff symbol + +@cindex adjusting staff symbol + +Notes, dynamic signs, etc. are grouped +with a set of horizontal lines, into a staff (plural `staves'). In our +system, these lines are drawn using a separate layout object called +staff symbol. + + +@cindex staff lines, setting number of +@cindex staff lines, setting thickness of +@cindex thickness of staff lines, setting +@cindex number of staff lines, setting + +@seealso + +Internals: @internalsref{StaffSymbol}. + +Examples: @inputfileref{input/test,staff-lines.ly}, +@inputfileref{input/test,staff-size.ly}. + +@refbugs + +If a staff is ended halfway a piece, the staff symbol may not end +exactly on the bar line. + + +@node Key signature +@subsection Key signature +@cindex Key signature + +@cindex @code{\key} + +The key signature indicates the scale in which a piece is played. It +is denoted by a set of alterations (flats or sharps) at the start of +the staff. + +@syntax + +Setting or changing the key signature is done with the @code{\key} +command: +@example + @code{\key} @var{pitch} @var{type} +@end example + +@cindex @code{\minor} +@cindex @code{\major} +@cindex @code{\minor} +@cindex @code{\ionian} +@cindex @code{\locrian} +@cindex @code{\aeolian} +@cindex @code{\mixolydian} +@cindex @code{\lydian} +@cindex @code{\phrygian} +@cindex @code{\dorian} + +Here, @var{type} should be @code{\major} or @code{\minor} to get +@var{pitch}-major or @var{pitch}-minor, respectively. +The 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 +@internalsref{Staff}.@code{keySignature}. Non-standard key signatures +can be specified by setting this property directly. + +Accidentals and key signatures often confuse new users, because +unaltered notes get natural signs depending on the key signature. The +tutorial explains why this is so in @ref{More about pitches}. + +@refbugs + +The ordering of a key cancellation is wrong when it is combined with +repeat bar lines. The cancellation is also printed after a line break. + +@seealso + +Internals: @internalsref{KeyChangeEvent}, and @internalsref{KeySignature}. + +@cindex @code{keySignature} + + +@node Clef +@subsection Clef +@cindex @code{\clef} + +The clef indicates which lines of the staff correspond to which +pitches. + +@syntax + +The clef can be set or changed with the @code{\clef} command: +@lilypond[fragment,verbatim] + \key f\major c''2 \clef alto g'2 +@end lilypond + +Supported clef-names include: +@c Moved standard clefs to the top /MB +@table @code +@cindex treble clef +@cindex violin clef +@item treble, violin, G, G2 +G clef on 2nd line +@item alto, C +@cindex alto clef + C clef on 3rd line +@item tenor +@cindex tenor clef + C clef on 4th line. +@item bass, F +@cindex bass clef + F clef on 4th line +@item french +@cindex french clef + G clef on 1st line, so-called French violin clef +@item soprano +@cindex soprano clef + C clef on 1st line +@item mezzosoprano +@cindex mezzosoprano clef + C clef on 2nd line +@item baritone +@cindex baritone clef + C clef on 5th line +@item varbaritone +@cindex varbaritone clef + F clef on 3rd line +@item subbass +@cindex subbass clef + F clef on 5th line +@item percussion + percussion clef +@end table + +By adding @code{_8} or @code{^8} to the clef name, the clef is +transposed one octave down or up, respectively, and @code{_15} and +@code{^15} transposes by two octaves. The argument @var{clefname} +must be enclosed in quotes when it contains underscores or digits. For +example, + + +@cindex choral tenor clef +@lilypond[verbatim,fragment,relative] + \clef "G_8" c4 +@end lilypond + +This command is equivalent to setting @code{clefGlyph}, +@code{clefPosition} (which controls the Y position of the clef), +@code{centralCPosition} and @code{clefOctavation}. A clef is printed +when any of these properties are changed. + +@seealso + +Internals: the object for this symbol is @internalsref{Clef}. + + + +@node Ottava brackets +@subsection Ottava brackets + +``Ottava'' brackets introduce an extra transposition of an octave for +the staff. They are created by invoking the function +@code{set-octavation}: + +@cindex ottava +@cindex 15ma +@cindex octavation + +@lilypond[verbatim,fragment] +\relative c''' { + a2 b + #(set-octavation 1) + a b + #(set-octavation 0) + a b } +@end lilypond + +The @code{set-octavation} function also takes -1 (for 8va bassa) and 2 +(for 15ma) as arguments. Internally the function sets the properties +@code{ottavation} (e.g. to @code{"8va"}) and +@code{centralCPosition}. For overriding the text of the bracket, set +@code{ottavation} after invoking @code{set-octavation}, i.e., + +@example + #(set-octavation 1) + \set Staff.ottavation = #"8" +@end example + +@seealso + +Internals: @internalsref{OttavaBracket}. + +Examples: @inputfileref{input/regression,ottava.ly}, +@inputfileref{input/regression,ottava-broken.ly}. + +@refbugs + +@code{set-octavation} will get confused when clef changes happen +during an octavation bracket. + +@node Time signature +@subsection Time signature +@cindex Time signature +@cindex meter +@cindex @code{\time} + +Time signature indicates the metrum of a piece: a regular pattern of +strong and weak beats. It is denoted by a fraction at the start of the +staff. + +@syntax + +The time signature is set or changed by the @code{\time} +command: +@lilypond[fragment,verbatim] + \time 2/4 c'2 \time 3/4 c'2. +@end lilypond + +The symbol that is printed can be customized with the @code{style} +property. Setting it to @code{#'()} uses fraction style for 4/4 and +2/2 time. There are many more options for its layout. See +@inputfileref{input/test,time.ly} for more examples. + + +This command sets the property @code{timeSignatureFraction}, +@code{beatLength} and @code{measureLength} in the @code{Timing} +context, which is normally aliased to @internalsref{Score}. The +property @code{measureLength} determines where bar lines should be +inserted, and how automatic beams should be generated. Changing the +value of @code{timeSignatureFraction} also causes the symbol to be +printed. + +More options are available through the Scheme function +@code{set-time-signature}. In combination with the +@internalsref{Measure_grouping_engraver}, it will create +@internalsref{MeasureGrouping} signs. Such signs ease reading +rhythmically complex modern music. In the following example, the 9/8 +measure is subdivided in 2, 2, 2 and 3. This is passed to +@code{set-time-signature} as the third argument @code{(2 2 2 3)}: + +@lilypond[verbatim] +\score { \notes \relative c'' { + #(set-time-signature 9 8 '(2 2 2 3)) + g8[ g] d[ d] g[ g] a8[( bes g]) | + #(set-time-signature 5 8 '(3 2)) + a4. g4 + } + \paper { + raggedright = ##t + \translator { \StaffContext + \consists "Measure_grouping_engraver" + }}} +@end lilypond + +@seealso + +Internals: @internalsref{TimeSignature}, and @internalsref{Timing_engraver}. + + +@refbugs + +Automatic beaming does not use measure grouping specified with +@code{set-time-signature}. + +@node Partial measures +@subsection Partial measures +@cindex Partial +@cindex anacrusis +@cindex partial measure +@cindex measure, partial +@cindex shorten measures +@cindex @code{\partial} + +Partial measures, for example in upsteps, are entered using the +@code{\partial} command: +@lilypond[fragment,verbatim,relative=1] +\partial 16*5 c16 cis d dis e | a2. c,4 | b2 +@end lilypond + +The syntax for this command is +@example + \partial @var{duration} +@end example +This is internally translated into +@example + \set Timing.measurePosition = -@var{length of duration} +@end example +@cindex @code{|} +The property @code{measurePosition} contains a rational number +indicating how much of the measure has passed at this point. + +@node Unmetered music +@subsection Unmetered music + +Bar lines and bar numbers are calculated automatically. For unmetered +music (e.g. cadenzas), this is not desirable. By setting +@code{Score.timing} to false, this automatic timing can be switched +off. + + +@refcommands + +@cindex @code{\cadenzaOn} +@code{\cadenzaOn}, +@cindex @code{\cadenzaOff} +@code{\cadenzaOff}. + +@node Bar lines +@subsection Bar lines +@cindex Bar lines + +@cindex @code{\bar} +@cindex measure lines +@cindex repeat bars + + +Bar lines delimit measures, but are also used to indicate repeats. +Normally, they are inserted automatically. Line breaks may only +happen on bar lines. + +@syntax + + Special types +of bar lines can be forced with the @code{\bar} command: +@c +@lilypond[relative=1,fragment,verbatim] + c4 \bar "|:" c4 +@end lilypond + +The following bar types are available: +@lilypond[fragment,relative,raggedright,verbatim] +c4 +\bar "|" c +\bar "" c +\bar "|:" c +\bar "||" c +\bar ":|" c +\bar ".|" c +\bar ".|." c +\bar ":|:" c +\bar "|." c +\bar ":" c +@end lilypond +For allowing line breaks, there is a special command, +@example + \bar "empty" +@end example +This will insert an invisible bar line, and allow line breaks at this +point. + +In scores with many staves, a @code{\bar} command in one staff is +automatically applied to all staves. The resulting bar lines are +connected between different staves of a @internalsref{StaffGroup}: +@c +@lilypond[fragment,verbatim] +<< \context StaffGroup << + \new Staff { e'4 d' + \bar "||" + f' e' } + \new Staff { \clef bass c4 g e g } >> +\new Staff { \clef bass c2 c2 } >> +@end lilypond + + +The command @code{\bar @var{bartype}} is a short cut for doing +@code{\set Score.whichBar = @var{bartype}} Whenever +@code{whichBar} is set to a string, a bar line of that type is +created. At the start of a measure it is set to +@code{defaultBarType}. The contents of @code{repeatCommands} are used +to override default measure bars. + +Property @code{whichBar} can also be set directly, using @code{\set} +or @code{\bar}. These settings take precedence over the automatic +@code{whichBar} settings. + +@cindex whichBar +@cindex repeatCommands +@cindex defaultBarType + +You are encouraged to use @code{\repeat} for repetitions. See +@ref{Repeats}. + + + +@seealso + +In this manual: @ref{Repeats}. + + +Internals: the bar line objects that are created at +@internalsref{Staff} level are called @internalsref{BarLine}, the bar +lines that span staves are @internalsref{SpanBar}s. + +@cindex bar lines at start of system +@cindex start of system + +The bar lines at the start of each system are +@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and +@internalsref{SystemStartBracket}. Only one of these types is created +in every context, and that type is determined by the property +@code{systemStartDelimiter}. + +Examples: @inputfileref{input/test,bar-lines.ly}, + +@node Polyphony +@section Polyphony +@cindex polyphony + +The easiest way to enter fragments with more than one voice on a staff +is to split chords using the separator @code{\\}. You can use it for +small, short-lived voices or for single chords: + +@lilypond[verbatim,fragment] +\context Staff \relative c'' { + c4 << { f d e } \\ { b c2 } >> + c4 << g' \\ b, \\ f' \\ d >> +} +@end lilypond + +The separator causes @internalsref{Voice} contexts@footnote{Polyphonic +voices are sometimes called "layers" other notation packages} +@cindex layers +to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In +each of these contexts, vertical direction of slurs, stems, etc. is set +appropriately. + +@cindex @code{\voiceOne} +@cindex @code{\voiceFour} + +This can also be done by instantiating @internalsref{Voice} contexts +by hand, and using @code{\voiceOne}, up to @code{\voiceFour} to assign +a stem directions and horizontal shift for each part: +@c + +@lilypond[raggedright,verbatim] +\relative c'' +\context Staff << \new Voice { \voiceOne cis2 b } + \new Voice { \voiceThree b4 ais ~ ais4 gis4 } + \new Voice { \voiceTwo fis4~ fis4 f ~ f } >> +@end lilypond + +@noindent +The command @code{\oneVoice} will revert back to the normal setting. +@cindex @code{\oneVoice} + + +Normally, note heads with a different number of dots are not merged, but +when the object property @code{merge-differently-dotted} is set in +the @internalsref{NoteCollision} object, they are merged: +@lilypond[verbatim,fragment,raggedright] +\relative c'' \context Voice << { + g8 g8 + \override Staff.NoteCollision + #'merge-differently-dotted = ##t + g8 g8 + } \\ { g8.[ f16] g8.[ f16] } + >> +@end lilypond + +Similarly, you can merge half note heads with eighth notes, by setting +@code{merge-differently-headed}: +@lilypond[fragment,relative=2,verbatim] +\context Voice << { + c8 c4. + \override Staff.NoteCollision + #'merge-differently-headed = ##t + c8 c4. } \\ { c2 c2 } >> +@end lilypond + +LilyPond also vertically shifts rests that are opposite of a stem: + + +@lilypond[raggedright,fragment,verbatim] +\context Voice << c''4 \\ r4 >> +@end lilypond + + +@refcommands + + + +@cindex @code{\oneVoice} +@code{\oneVoice}, +@cindex @code{\voiceOne} +@code{\voiceOne}, +@cindex @code{\voiceTwo} +@code{\voiceTwo}, +@cindex @code{\voiceThree} +@code{\voiceThree}, +@cindex @code{\voiceFour} +@code{\voiceFour}. + + +The following commands specify in what chords of the current voice +should be shifted: the outer voice has @code{\shiftOff}, and the inner +voices have @code{\shiftOn}, @code{\shiftOnn}, etc. + + +@cindex @code{\shiftOn} +@code{\shiftOn}, +@cindex @code{\shiftOnn} +@code{\shiftOnn}, +@cindex @code{\shiftOnnn} +@code{\shiftOnnn}, +@cindex @code{\shiftOff} +@code{\shiftOff}. + + + +@seealso + +Internals: the objects responsible for resolving collisions are +@internalsref{NoteCollision} and @internalsref{RestCollision}. + +Examples: See also example files +@inputfileref{input/regression,collision-dots.ly}, +@inputfileref{input/regression,collision-head-chords.ly}, +@inputfileref{input/regression,collision-heads.ly}, +@inputfileref{input/regression,collision-mesh.ly}, and +@inputfileref{input/regression,collisions.ly}. + + +@refbugs + +Resolving collisions is a intricate subject, and only a few situations +are handled. When LilyPond cannot cope, the @code{force-hshift} +property of the @internalsref{NoteColumn} object and pitched rests can +be used to override typesetting decisions. + +When using @code{merge-differently-headed} with an upstem 8th or a shorter +note, and a downstem half note, the 8th note gets the wrong offset. + +There is no support for clusters where the same note occurs with +different accidentals in the same chord. In this case, it is +recommended to use enharmonic transcription, or to use special cluster +notation (see @ref{Clusters}). + +@node Beaming +@section Beaming + +Beams are used to group short notes into chunks that are aligned with +the metrum. They are inserted automatically in most cases: + +@lilypond[fragment,verbatim,relative=2] +\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 +@end lilypond + +When these automatic decisions are not good enough, beaming can be +entered explicitly. It is also possible to define beaming patterns +that differ from the defaults. + +Individual notes may be marked with @code{\noBeam}, to prevent them +from being beamed: + +@lilypond[fragment,verbatim,relative=2] + \time 2/4 c8 c\noBeam c c +@end lilypond + + +@seealso + +Internals: @internalsref{Beam}. + + +@cindex Automatic beams +@menu +* Manual beams:: +* Setting automatic beam behavior:: +@end menu + +@node Manual beams +@subsection Manual beams +@cindex beams, manual +@cindex @code{]} +@cindex @code{[} + +In some cases it may be necessary to override the automatic beaming +algorithm. For example, the autobeamer will not put beams over rests +or bar lines. Such beams are specified by manually: the begin and end +point are marked with @code{[} and @code{]}: + +@lilypond[fragment,relative,verbatim] + \context Staff { + r4 r8[ g' a r8] r8 g[ | a] r8 + } +@end lilypond + +@cindex @code{stemLeftBeamCount} + +Normally, beaming patterns within a beam are determined automatically. +When this mechanism fouls up, the properties +@code{stemLeftBeamCount} and @code{stemRightBeamCount} can +be used to control the beam subdivision on a stem. If either property +is set, its value will be used only once, and then it is erased: + +@lilypond[fragment,relative,verbatim] + \context Staff { + f8[ r16 f g a] + f8[ r16 \set stemLeftBeamCount = #1 f g a] + } +@end lilypond +@cindex @code{stemRightBeamCount} + + +The property @code{subdivideBeams} can be set in order to subdivide +all 16th or shorter beams at beat positions, as defined by the +@code{beatLength} property. This accomplishes the same effect as +twiddling with @code{stemLeftBeamCount} and @code{stemRightBeamCount}, +but it take less typing: + + +@lilypond[relative=1,verbatim,noindent] + c16[ c c c c c c c] + \set subdivideBeams = ##t + c16[ c c c c c c c] + \set Score.beatLength = #(ly:make-moment 1 8) + c16[ c c c c c c c] +@end lilypond +@cindex subdivideBeams + +Kneed beams are inserted automatically, when a large gap is detected +between the note heads. This behavior can be tuned through the object +property @code{auto-knee-gap}. + +Normally, line breaks are forbidden when beams cross bar lines. This +behavior can be changed by setting @code{allowBeamBreak}. + +@cindex @code{allowBeamBreak} +@cindex beams and line breaks + +@cindex beams, kneed +@cindex kneed beams +@cindex auto-knee-gap + + + +@refbugs + +@cindex Frenched staves + +Automatically kneed beams cannot be used together with hidden staves. + + + + +@node Setting automatic beam behavior +@subsection Setting automatic beam behavior + +@cindex @code{autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} +@cindex automatic beams, tuning +@cindex tuning automatic beaming + +@c [TODO: use \applycontext] + +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{autoBeamSettings}. The defaults for @code{autoBeamSettings} +are defined in @file{scm/auto-beam.scm}. + +The value of @code{autoBeamSettings} is changed with two functions: +@example + #(override-auto-beam-setting + '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b} + [@var{context}]) + #(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})) +@end example +Here, @var{be} is the symbol @code{begin} or @code{end}. It determines +whether the rule applies to begin or end-points. The quantity +@var{p}/@var{q} refers to the length of the beamed notes (and `@code{* +*}' designates notes of any length), @var{n}/@var{M} refers to a time +signature (wildcards `@code{* *}' may be entered to designate all time +signatures), @var{a}/@var{b} is a duration. By default, this command +changes settings for the current voice. It is also possible to adjust +settings at higher contexts, by adding a @var{context} argument. + +For example, if automatic beams should end on every quarter note, use +the following: +@example + #(override-auto-beam-setting '(end * * * *) 1 4) +@end example +Since the duration of a quarter note is 1/4 of a whole note, it is +entered as @code{(ly:make-moment 1 4)}. + +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 + #(override-auto-beam-setting '(end * * * *) 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). + +Rules can also be restricted to specific time signatures. A rule that +should only be applied in @var{N}/@var{M} time signature is formed by +replacing the second asterisks by @var{N} and @var{M}. For example, a +rule for 6/8 time exclusively looks like +@example + #(override-auto-beam-setting '(begin * * 6 8) @dots{}) +@end example + +If a rule should be to applied only to certain types of beams, use the +first 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), use @code{(end 1 32 * +*)}. + +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. + +@cindex automatic beam generation +@cindex autobeam +@cindex @code{autoBeaming} +@cindex lyrics + +For melodies that have lyrics, you may want to switch off +automatic beaming. This is done by setting @code{autoBeaming} to +@code{#f}. + +@refcommands + +@cindex @code{\autoBeamOff} +@code{\autoBeamOff}, +@cindex @code{\autoBeamOn} +@code{\autoBeamOn}. + + +@refbugs + +The rules for ending a beam depend on the shortest note in a beam. +So, while it is possible to have different ending rules for eight +beams and sixteenth beams, a beam that contains both eight and +sixteenth notes will use the rules for the sixteenth beam. + +In the example below, the autobeamer makes eight beams and sixteenth +end at 3 eights; the third beam can only be corrected by specifying +manual beaming. + +@lilypond[raggedright,fragment,relative] + #(override-auto-beam-setting '(end * * * *) 3 8) + % rather show case where it goes wrong + %\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4 + \time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4 +@end lilypond +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}. + +@node Accidentals +@section Accidentals +@cindex Accidentals + +This section describes how to change the way that accidentals are +inserted automatically before the running notes. + + +@menu +* Using the predefined accidental variables:: +* Customized accidental rules:: +@end menu + +@node Using the predefined accidental variables +@subsection Using the predefined accidental variables + + +Common rules for typesetting macros have been canned in a +function. This function is called as follows: + +@cindex @code{set-accidental-style} +@example + #(set-accidental-style 'modern 'Voice) +@end example + +The function takes two arguments: a symbol that denotes the style (in +the example, @code{modern}), and another symbol that denotes the +context name (in this example, @code{Staff}). If no context name is +supplied, @code{Staff} is the default. + +The following styles are supported: +@table @code +@item default + This is the default typesetting behavior. It should correspond + to 18th century common practice: Accidentals are + remembered to the end of the measure in which they occur and + only on their own octave. + +@item voice +@c + The normal behavior is to remember the accidentals on +Staff-level. This variable, however, typesets accidentals +individually for each voice. Apart from that, the rule is similar to +@code{code}. + + This leads to some weird and often unwanted results + because accidentals from one voice do not get canceled in other + voices: +@lilypond[raggedright,relative,fragment,verbatim] + \context Staff << + #(set-accidental-style 'voice) + << + { es g } \\ + { c, e } + >> >> +@end lilypond + Hence you should only use @code{voice} if the voices +are to be read solely by individual musicians. If the staff is to be +used by one musician (e.g. a conductor) then you use +@code{modern} or @code{modern-cautionary} +instead. + +@item modern +@cindex @code{modern} style accidentals + This rule corresponds to the common practice in the 20th + century. + This rule prints the same accidentals as @code{default}, but temporary + accidentals also are canceled in other octaves. Furthermore, + in the same octave, they also get canceled in the following + measure: + +@lilypond[raggedright,fragment,verbatim] + #(set-accidental-style 'modern) + cis' c'' cis'2 | c'' c' +@end lilypond + +@item @code{modern-cautionary} + @cindex @code{modern-cautionary} + This rule is similar to @code{modern}, but the + ``extra'' accidentals (the ones not typeset by + @code{default}) are typeset as cautionary accidentals. + They are printed in reduced size or with parentheses: +@lilypond[raggedright,fragment,verbatim] + #(set-accidental-style 'modern-cautionary) + cis' c'' cis'2 | c'' c' +@end lilypond + + @cindex @code{modern-voice} +@item modern-voice +is used for multivoice accidentals to be read both by musicians +playing one voice and musicians playing all voices. Accidentals are +typeset for each voice, but they @emph{are} canceled across voices in +the same @internalsref{Staff}. + + @cindex @code{modern-voice-cautionary} +@item modern-voice-cautionary +is the same as @code{modern-voice}, but with the extra +accidentals (the ones not typeset by @code{voice}) typeset +as cautionaries. Even though all accidentals typeset by +@code{default} @emph{are} typeset by this variable then +some of them are typeset as cautionaries. + +@item piano + @cindex @code{piano} accidentals + 20th century practice for piano notation. Very similar to + @code{modern} but accidentals also get canceled + across the staves in the same @internalsref{GrandStaff} or + @internalsref{PianoStaff}. + +@item piano-cautionary + @cindex @code{#(set-accidental-style 'piano-cautionary)} + As @code{#(set-accidental-style 'piano)' , str)} but with the extra accidentals + typeset as cautionaries. + +@item no-reset + @cindex @code{no-reset} accidental style + Same as @code{default} but with accidentals lasting + ``forever'' and not only until the next measure: +@lilypond[raggedright,fragment,verbatim,relative] + #(set-accidental-style 'no-reset) + c1 cis cis c +@end lilypond + +@item forget + This is sort of the opposite of @code{no-reset}: Accidentals + are not remembered at all---and hence all accidentals are + typeset relative to the key signature, regardless of what was + before in the music: + +@lilypond[raggedright,fragment,verbatim,relative] + #(set-accidental-style 'forget) + \key d\major c4 c cis cis d d dis dis +@end lilypond +@end table + +@node Customized accidental rules +@subsection Customized accidental rules + +For determining when to print an accidental, several different rules +are tried. The rule that gives the highest number of accidentals is +used. Each rule consists of +@table @var +@item context: + In which context is the rule applied. For example, if +@var{context} is @internalsref{Score} then all staves share +accidentals, and if @var{context} is @internalsref{Staff} then all +voices in the same staff share accidentals, but staves do not. + +@item octavation: + Whether the accidental changes all octaves or only the current + octave. Valid choices are + + @table @samp + @item same-octave: + This is the default algorithm. Accidentals are typeset if the note changes + the accidental of that note in that octave. Accidentals lasts to the end of the measure + and then as many measures as specified in the value. I.e. 1 means to the end + of next measure, -1 means to the end of previous measure (that is: no duration at all), etc. #t means forever. + @item any-octave: + Accidentals are typeset if the note is different from + the previous note on the same pitch in any octave. The value has same meaning as in + same-octave. + @end table + +@item laziness + + Over how many bar lines the accidental lasts. + If @var{laziness} is @code{-1} then the accidental is forget + immediately, and if @var{laziness} is @code{#t} then the accidental + lasts forever. +@end table + + +@seealso + +Internals: @internalsref{Accidental_engraver}, +@internalsref{Accidental}, and @internalsref{AccidentalPlacement}. + + +@refbugs + +Currently the simultaneous notes are considered to be entered in +sequential mode. This means that in a chord the accidentals are +typeset as if the notes in the chord happened once at a time - in the +order in which they appear in the input file. + +This is only a problem when there are simultaneous notes whose +accidentals depend on each other. The problem only occurs when using +non-default accidentals. In the default scheme, accidentals only +depend on other accidentals with the same pitch on the same staff, so +no conflicts possible. + +This example shows two examples of the same music giving different +accidentals depending on the order in which the notes occur in the +input file: + +@lilypond[raggedright,fragment,verbatim] +\set Staff.autoAccidentals = #'( Staff (any-octave . 0) ) +cis'4 r2 | cis'4 r2 +| r | r | +@end lilypond + +This problem can be solved by manually inserting @code{!} and @code{?} +for the problematic notes. + +@node Expressive marks +@section Expressive marks + + +@c todo: should change ordering +@c where to put text spanners, metronome marks, +@c fingering? + +@menu +* Slurs:: +* Phrasing slurs:: +* Breath marks:: +* Metronome marks:: +* Text spanners:: +* Analysis brackets:: +* Articulations:: +* Fingering instructions:: +* Text scripts:: +* Grace notes:: +* Glissando:: +* Dynamics:: +@end menu + +@node Slurs +@subsection Slurs +@cindex Slurs + +A slur indicates that notes are to be played bound or @emph{legato}. + +@syntax + +They are entered using parentheses: +@lilypond[relative=1,fragment,verbatim] + f( g)( a) a8 b( a4 g2 f4) + 2( 2) +@end lilypond + + +@c TODO: should explain that ^( and _( set directions +@c should set attachments with ^ and _ ? + +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 +object property @code{attachment} of @internalsref{Slur} in +@internalsref{Voice} context. Its value is a pair of symbols, specifying +the attachment type of the left and right end points: + +@lilypond[fragment,relative,verbatim] + \slurUp + \override Stem #'length = #5.5 + g'8(g g4) + \override Slur #'attachment = #'(stem . stem) + g8( g g4) +@end lilypond + +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: + +@lilypond[fragment,relative,verbatim] + \stemUp \slurUp + d32( d'4 d8..) + \override Slur #'attachment = #'(stem . stem) + d,32( d'4 d8..) +@end lilypond + +@refcommands + + +@cindex @code{\slurUp} +@code{\slurUp}, +@cindex @code{\slurDown} +@code{\slurDown}, +@cindex @code{\slurBoth} +@code{\slurBoth}, +@cindex @code{\slurDotted} +@code{\slurDotted}, +@cindex @code{\slurSolid} +@code{\slurSolid}. + +@seealso + +Internals: @seeinternals{Slur}, and @internalsref{SlurEvent}. + + +@refbugs + +Producing nice slurs is a difficult problem, and LilyPond currently +uses a simple, empiric method to produce slurs. In some cases, its +results are ugly. + + +@cindex Adjusting slurs + +@node Phrasing slurs +@subsection Phrasing slurs + +@cindex phrasing slurs +@cindex phrasing marks + +A phrasing slur (or phrasing mark) connects chords and is used to +indicate a musical sentence. It is started using @code{\(} and @code{\)} +respectively: + +@lilypond[fragment,verbatim,relative] + \time 6/4 c'\( d( e) f( e) d\) +@end lilypond + +Typographically, the phrasing slur behaves almost exactly like a +normal slur. However, they are treated as different objects. A +@code{\slurUp} will have no effect on a phrasing slur; instead, you +should use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and +@code{\phrasingSlurBoth}. + +The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurBoth} +will only affect normal slurs and not phrasing slurs. + +@refcommands + +@cindex @code{\phrasingSlurUp} +@code{\phrasingSlurUp}, +@cindex @code{\phrasingSlurDown} +@code{\phrasingSlurDown}, +@cindex @code{\phrasingSlurBoth} +@code{\phrasingSlurBoth}. + +@seealso + +Internals: see also @internalsref{PhrasingSlur}, and +@internalsref{PhrasingSlurEvent}. + +@refbugs + +Phrasing slurs have the same limitations in their formatting as normal +slurs. Putting phrasing slurs over rests leads to spurious warnings. + +@node Breath marks +@subsection Breath marks + +Breath marks are entered using @code{\breathe}: + + +@lilypond[fragment,relative,verbatim] +c'4 \breathe d4 +@end lilypond + +The glyph of the breath mark can be tweaked by overriding the +@code{text} property of the @code{BreathingSign} layout object with +any markup text. For example, +@lilypond[fragment,verbatim,relative] +c'4 +\override BreathingSign #'text + = #(make-musicglyph-markup "scripts-rvarcomma") +\breathe +d4 +@end lilypond + +@seealso + +Internals: @internalsref{BreathingSign}, +@internalsref{BreathingSignEvent}. + +Examples: @inputfileref{input/regression,breathing-sign.ly}. + + +@node Metronome marks +@subsection Metronome marks + +@cindex Tempo +@cindex beats per minute +@cindex metronome marking + +Metronome settings can be entered as follows: +@example + \tempo @var{duration} = @var{per-minute} +@end example + +In the MIDI output, they are interpreted as a tempo change, and in the +paper output, a metronome marking is printed: +@cindex @code{\tempo} +@lilypond[fragment,verbatim] + \tempo 8.=120 c''1 +@end lilypond + +@seealso + +Internals: @internalsref{MetronomeChangeEvent}. + + + +@node Text spanners +@subsection Text spanners +@cindex Text spanners + +Some performance indications, e.g. @i{rallentando} or @i{accelerando}, +are written as texts, and extended over many measures with dotted +lines. You can create such texts using text spanners: attach +@code{\startTextSpan} and @code{\stopTextSpan} to the +start and ending note of the spanner. + +The string to be printed, as well as the style, is set through object +properties: + +@lilypond[fragment,relative,verbatim] + \relative c' { c1 + \override TextSpanner #'direction = #-1 + \override TextSpanner #'edge-text = #'("rall " . "") + c2\startTextSpan b c\stopTextSpan a } +@end lilypond + + +@seealso + +Internals @internalsref{TextSpanEvent}, +@internalsref{TextSpanner}. + +Examples: @inputfileref{input/regression,text-spanner.ly}. + + +@node Analysis brackets +@subsection Analysis brackets +@cindex brackets +@cindex phrasing brackets +@cindex musicological analysis +@cindex note grouping bracket + +Brackets are used in musical analysis to indicate structure in musical +pieces. LilyPond supports a simple form of nested horizontal brackets. +To use this, add the @internalsref{Horizontal_bracket_engraver} to +@internalsref{Staff} context. A bracket is started with +@code{\startGroup} and closed with @code{\stopGroup}: + +@lilypond[raggedright,verbatim] +\score { \notes \relative c'' { + c4\startGroup\startGroup + c4\stopGroup + c4\startGroup + c4\stopGroup\stopGroup + } + \paper { \translator { + \StaffContext \consists "Horizontal_bracket_engraver" + }}} +@end lilypond + +@seealso + +Internals: @internalsref{HorizontalBracket}, +@internalsref{NoteGroupingEvent}. + +Examples: @inputfileref{input/regression,note-group-bracket.ly}. + + +@node Articulations +@subsection Articulations +@cindex Articulations + +@cindex articulations +@cindex scripts +@cindex ornaments + +A variety of symbols can appear above and below notes to indicate +different characteristics of the performance. They are added to a note +by adding a dash and the character signifying the +articulation. They are demonstrated here: + +@lilypondfile[]{script-abbreviations.ly} + +The meanings of these shorthands can be changed: see +@file{ly/script-init.ly} for examples. + + +The script is automatically placed, but if you need to force +directions, you can use @code{_} to force them down, or @code{^} to +put them up: +@lilypond[fragment,verbatim] + c''4^^ c''4_^ +@end lilypond + +Other symbols can be added using the syntax +@var{note}@code{\}@var{name}, e.g. @code{c4\fermata}. Again, they +can be forced up or down using @code{^} and @code{_}, +e.g. + +@lilypond[verbatim,fragment,relative=2] + c\fermata c^\fermata c_\fermata +@end lilypond + + + +@cindex accent +@cindex marcato +@cindex staccatissimo +@cindex fermata +@cindex stopped +@cindex staccato +@cindex portato +@cindex tenuto +@cindex upbow +@cindex downbow +@cindex foot marks +@cindex organ pedal marks +@cindex turn +@cindex open +@cindex flageolet +@cindex reverseturn +@cindex trill +@cindex prall +@cindex mordent +@cindex prallprall +@cindex prallmordent +@cindex prall, up +@cindex prall, down +@cindex mordent +@cindex thumb marking +@cindex segno +@cindex coda +@cindex varcoda + +@lilypondfile[]{script-chart.ly} + + +@refcommands + +@cindex @code{\scriptUp} +@code{\scriptUp}, +@cindex @code{\scriptDown} +@code{\scriptDown}, +@cindex @code{\scriptBoth} +@code{\scriptBoth}. + +@seealso + +Internals: @internalsref{ScriptEvent}, and @internalsref{Script}. + +@refbugs + +These note ornaments appear in the printed output but have no +effect on the MIDI rendering of the music. + + +@node Fingering instructions +@subsection Fingering instructions + +@cindex fingering + +Fingering instructions can be entered using +@example + @var{note}-@var{digit} +@end example +For finger changes, use markup texts: +@c +@lilypond[verbatim,raggedright,fragment] + c'4-1 c'4-2 c'4-3 c'4-4 + c'^\markup { \fontsize #-3 \number "2-3" } +@end lilypond + +@cindex finger change +@cindex scripts +@cindex superscript +@cindex subscript + +You can use the thumb-script to indicate that a note should be +played with the thumb (e.g. in cello music): + +@lilypond[verbatim,raggedright,fragment] + 8(_\thumb )_\thumb + (_\thumb )_\thumb +@end lilypond + +Fingerings for chords can also be added to individual notes +of the chord by adding them after the pitches: +@lilypond[verbatim,raggedright,fragment,relative=1] + < c-1 e-2 g-3 b-5 > 4 +@end lilypond + +@noindent +In this case, setting @code{fingeringOrientations} will put fingerings next +to note heads: + +@lilypond[verbatim,raggedright,fragment,relative=1] + \set fingeringOrientations = #'(left down) + 4 + \set fingeringOrientations = #'(up right down) + 4 +@end lilypond + +By using single note chords, fingering instructions can be put close +to note heads in monophonic music. + +@seealso + +Internals: @internalsref{FingerEvent}, and @internalsref{Fingering}. + +Examples: @inputfileref{input/regression,finger-chords.ly}. + +@node Text scripts +@subsection Text scripts +@cindex Text scripts + +@cindex text items, non-empty +@cindex non-empty texts + +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"}. By default, these indications do not influence the +note spacing, but by using the command @code{\fatText}, the widths +will be taken into account: +@c +@lilypond[fragment,raggedright,verbatim] \relative c' { +c4^"longtext" \fatText c4_"longlongtext" c4 } +@end lilypond + +It is possible to use @TeX{} commands in the strings, but this should +be avoided because the exact dimensions of the string can then no +longer be computed. + +@refcommands + +@cindex @code{\fatText} +@code{\fatText}, +@cindex @code{\emptyText} +@code{\emptyText}. + +@seealso + +In this manual: @ref{Text markup}. + +Internals: @internalsref{TextScriptEvent}, @internalsref{TextScript}. + + + + +@node Grace notes +@subsection Grace notes + + +@c should have blurb about accaciatura / appogiatura + +@cindex @code{\grace} +@cindex ornaments +@cindex grace notes + +Grace notes are ornaments that are written out. The most common ones +are acciaccatura, which should be played as very short. It is denoted +by a slurred small note with a slashed stem. The appoggiatura is a +grace note that takes a fixed fraction of the main note, is and +denoted as a slurred note in small print without a slash. +They are entered with the commands @code{\acciaccatura} and +@code{\appoggiatura}, as demonstrated in the following example: + + +@cindex appoggiatura +@cindex acciaccatura + +@lilypond[relative=2,verbatim,fragment] +b4 \acciaccatura d8 c4 \appoggiatura e8 d4 +\acciaccatura { g16[ f] } e4 +@end lilypond + +Both are special forms of the @code{\grace} command. By prefixing this +keyword to a music expression, a new one is formed, which will be +printed in a smaller font and takes up no logical time in a measure. +@lilypond[relative=2,verbatim,fragment] + c4 \grace c16 c4 + \grace { c16[ d16] } c2 c4 +@end lilypond + +@noindent +Unlike @code{\acciaccatura} and @code{\appoggiatura}, the +@code{\grace} command does not start a slur. + +Internally, timing for grace notes is done using a second, `grace' +time. Every point in time consists of two rational numbers: one +denotes the logical time, one denotes the grace timing. The above +example is shown here with timing tuples: + +@lilypond[raggedright] +<< + \relative c''{ + c4 \grace c16 c4 \grace { + c16[ d16] } c2 c4 + } + \new Lyrics \lyrics { + \markup { (0,0) } 4 + \grace { \markup { + ( \fraction 1 4 , \fraction -1 16 ) } 16 } + \markup { (\fraction 1 4 , 0 ) } 4 + \grace { + \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 + \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16 + } + \markup { ( \fraction 2 4 , 0 ) } + } >> +@end lilypond + + +The placement of grace notes is synchronized between different staves. +In the following example, there are two sixteenth graces notes for +every eighth grace note: + +@lilypond[relative=2,verbatim,fragment] +<< \new Staff { e4 \grace { c16[ d e f] } e4 } + \new Staff { c'4 \grace { g8[ b] } c4 } >> +@end lilypond + + + +If you want to end a note with a grace, then the standard trick +is to put the grace notes after a ``space note'', e.g. +@lilypond[fragment,verbatim,relative=2] +\context Voice { + << { d1^\trill ( } + { s2 \grace { c16[ d] } } >> + c4) +} +@end lilypond + +@noindent +By adjusting the duration of the skip note (here it is a half-note), +the space between the main-note and the grace is adjusted. + + +A @code{\grace} section will introduce special typesetting settings, +for example, to produce smaller type, and set directions. Hence, when +introducing layout tweaks, they should be inside the grace section, +for example, +@lilypond[fragment,verbatim,relative=1] +\new Voice { + \acciaccatura { + \override Stem #'direction = #-1 + f16-> + \revert Stem #'direction + } + g4 +} +@end lilypond + +@noindent +The overrides should also be reverted inside the grace section. + +If the layout of grace sections must be changed throughout the music, +then this can be accomplished through the function +@code{add-grace-property}. The following example +undefines the Stem direction grace section, so stems do not always +point up. + +@example + \new Staff @{ + #(add-grace-property "Voice" Stem direction '()) + @dots{} + @} +@end example + +@noindent +Another option is to change the variables @code{startGraceMusic}, +@code{stopGraceMusic}, @code{startAccacciaturaMusic}, +@code{stopAccacciaturaMusic}, @code{startAppoggiaturaMusic}, +@code{stopAppoggiaturaMusic}. More information is in the file +@file{ly/grace-init.ly}. + + +@seealso + +Internals: @internalsref{GraceMusic}. + +@refbugs + +A score that starts with an @code{\grace} section needs an explicit +@code{\context Voice} declaration, otherwise the main note and grace +note end up on different staves. + +Grace note synchronization can also lead to surprises. Staff notation, +such as key signatures, bar lines, etc. are also synchronized. Take +care when you mix staves with grace notes and staves without, for example, + +@lilypond[relative=2,verbatim,fragment] +<< \new Staff { e4 \bar "|:" \grace c16 d4 } + \new Staff { c4 \bar "|:" d4 } >> +@end lilypond + +Grace sections should only be used within sequential music +expressions. Nesting or juxtaposing grace sections is not supported, +and might produce crashes or other errors. + + +@node Glissando +@subsection Glissando +@cindex Glissando + +@cindex @code{\glissando} + +A glissando is a smooth change in pitch. It is denoted by a line or a +wavy line between two notes. + +@syntax + +A glissando line can be requested by attaching a @code{\glissando} to +a note: + +@lilypond[fragment,relative,verbatim] + c'\glissando c' +@end lilypond + +@seealso + +Internals: @internalsref{Glissando}, and @internalsref{GlissandoEvent}. + + +@refbugs + +Adding additional texts (such as @emph{gliss.}) is not supported. + + +@node Dynamics +@subsection Dynamics +@cindex Dynamics + + + +@cindex @code{\ppp} +@cindex @code{\pp} +@cindex @code{\p} +@cindex @code{\mp} +@cindex @code{\mf} +@cindex @code{\f} +@cindex @code{\ff} +@cindex @code{\fff} +@cindex @code{\ffff} +@cindex @code{\fp} +@cindex @code{\sf} +@cindex @code{\sff} +@cindex @code{\sp} +@cindex @code{\spp} +@cindex @code{\sfz} +@cindex @code{\rfz} + + +Absolute dynamic marks are specified using a command after a note: +@code{c4\ff}. The available dynamic marks are @code{\ppp}, +@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, +@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, +@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}: + +@lilypond[verbatim,raggedright,fragment,relative] + c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff + c2\sf c\rfz +@end lilypond + +@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{\<} and terminated with +@code{\!}. A decrescendo is started with @code{\>} and also terminated +with @code{\!}. Because these marks are bound to notes, if you must +use spacer notes if multiple marks during one note are needed: + +@lilypond[fragment,verbatim] + c''\< c''\! d''\decr e''\rced + << f''1 { s4 s4\< s4\! \> s4\! } >> +@end lilypond +This may give rise to very short hairpins. Use @code{minimum-length} +in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for +example: + +@example + \override Staff.Hairpin #'minimum-length = #5 +@end example + +You can also use a text saying @emph{cresc.} instead of hairpins. Here +is an example how to do it: + +@lilypond[fragment,relative=2,verbatim] + c4 \cresc c4 c c c \endcresc c4 +@end lilypond + +@cindex crescendo +@cindex decrescendo + +You can also supply your own texts: +@lilypond[fragment,relative,verbatim] + \context Voice { + \set crescendoText = \markup { \italic "cresc. poco" } + \set crescendoSpanner = #'dashed-line + a'2\< a a a\!\mf + } +@end lilypond + +@cindex diminuendo + + +@refcommands + +@cindex @code{\dynamicUp} +@code{\dynamicUp}, +@cindex @code{\dynamicDown} +@code{\dynamicDown}, +@cindex @code{\dynamicBoth} +@code{\dynamicBoth}. + +@cindex direction, of dynamics + +@seealso + +Internals: @internalsref{CrescendoEvent}, @internalsref{DecrescendoEvent}, and +@internalsref{AbsoluteDynamicEvent}. + +Dynamics are objects of @internalsref{DynamicText} and +@internalsref{Hairpin}. Vertical positioning of these symbols is +handled by the @internalsref{DynamicLineSpanner} object. + +If you want to adjust padding or vertical direction of the dynamics, you +must set properties for the @internalsref{DynamicLineSpanner} object. + + +@node Repeats +@section Repeats + + +@cindex repeats +@cindex @code{\repeat} + + +Repetition is a central concept in music, and multiple notations exist +for repetitions. In LilyPond, most of these notations can be captured +in a uniform syntax. One of the advantages is that they can be +rendered in MIDI accurately. + +The following types of repetition are supported: + +@table @code +@item unfold +Repeated music is fully written (played) out. Useful for MIDI +output, and entering repetitive music. + +@item volta +This is the normal notation: Repeats are not written out, but +alternative endings (volte) are printed, left to right. + +@ignore +@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 +@inputfileref{input,star-spangled-banner.ly}. +@end ignore + +@c tremolo, beamed +@item tremolo +Make tremolo beams. + +@item percent +Make beat or measure repeats. These look like percent signs. + +@end table + +@menu +* Repeat syntax:: +* Repeats and MIDI:: +* Manual repeat commands:: +* Tremolo repeats:: +* Tremolo subdivisions:: +* Measure repeats:: +@end menu + +@node Repeat syntax +@subsection Repeat syntax + +@syntax + +LilyPond has one syntactic construct for specifying different types of +repeats. The syntax is + +@example + \repeat @var{variant} @var{repeatcount} @var{repeatbody} +@end example + +If you have alternative endings, you may add +@cindex @code{\alternative} +@example + \alternative @code{@{} @var{alternative1} + @var{alternative2} + @var{alternative3} @dots{} @code{@}} +@end example +where each @var{alternative} is a music expression. If you do not +give enough alternatives for all of the repeats, then the first +alternative is assumed to be played more than once. + +Normal notation repeats are used like this: +@lilypond[fragment,verbatim,relative=1] + c1 + \repeat volta 2 { c4 d e f } + \repeat volta 2 { f e d c } +@end lilypond + +With alternative endings: +@lilypond[fragment,verbatim,relative=1] + c1 + \repeat volta 2 {c4 d e f} + \alternative { {d2 d} {f f,} } +@end lilypond + + +@lilypond[fragment,verbatim,relative=1] +\context Staff { + \partial 4 + \repeat volta 4 { e | c2 d2 | e2 f2 | } + \alternative { { g4 g g } { a | a a a a | b2. } } +} +@end lilypond + +@refbugs + +If you do a nested repeat like + +@example +\repeat @dots{} +\repeat @dots{} +\alternative +@end example + +@noindent +then it is ambiguous to which @code{\repeat} the @code{\alternative} +belongs. This ambiguity is resolved by always having the +@code{\alternative} belong to the inner @code{\repeat}. For clarity, +it is advisable to use braces in such situations. +@cindex ambiguity + +@node Repeats and MIDI +@subsection Repeats and MIDI + +@cindex expanding repeats + +For instructions on how to unfold repeats for MIDI output, see the +example file @inputfileref{input/test,unfold-all-repeats.ly}. + + +@refbugs + +Timing information is not remembered at the start of an alternative, +so after a repeat timing information must be reset by hand, for +example by setting @code{Score.measurePosition} or entering +@code{\partial}. Similarly, slurs or ties are also not repeated. + + +@node Manual repeat commands +@subsection Manual repeat commands + +@cindex @code{repeatCommands} + +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 @asis +@item the symbol @code{start-repeat}, + which prints a @code{|:} bar line, +@item the symbol @code{end-repeat}, + which prints a @code{:|} bar line, +@item the list @code{(volta @var{text})}, + which prints a volta bracket saying @var{text}: The text can be specified as +a text string or as a markup text, see @ref{Text markup}. Do not +forget to change the font, as the default number font does not contain +alphabetic characters. Or, +@item the list @code{(volta #f)}, which + stops a running volta bracket: +@end table + +@lilypond[verbatim,fragment,relative=2] + c4 + \set Score.repeatCommands = #'((volta "93") end-repeat) + c4 c4 + \set Score.repeatCommands = #'((volta #f)) + c4 c4 +@end lilypond + + +@seealso + +Internals: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, +@internalsref{VoltaRepeatedMusic}, +@internalsref{UnfoldedRepeatedMusic}, and +@internalsref{FoldedRepeatedMusic}. + +@node Tremolo repeats +@subsection Tremolo repeats +@cindex tremolo beams + +To place tremolo marks between notes, use @code{\repeat} with tremolo +style: +@lilypond[verbatim,raggedright] +\score { + \context Voice \notes\relative c' { + \repeat "tremolo" 8 { c16 d16 } + \repeat "tremolo" 4 { c16 d16 } + \repeat "tremolo" 2 { c16 d16 } + } +} +@end lilypond + +Tremolo marks can also be put on a single note. In this case, the +note should not be surrounded by braces. +@lilypond[verbatim,raggedright] + \repeat "tremolo" 4 c16 +@end lilypond + +A similar mechanism is the tremolo subdivision, described in +@ref{Tremolo subdivisions}. + +@seealso + +In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}. + +Internals: tremolo beams are @internalsref{Beam} objects. Single stem +tremolos are @internalsref{StemTremolo} objects. The music expression is +@internalsref{TremoloEvent}. + +Example files: @inputfileref{input/regression,chord-tremolo.ly}, +@inputfileref{input/regression,stem-tremolo.ly}. + +@node Tremolo subdivisions +@subsection Tremolo subdivisions +@cindex tremolo marks +@cindex @code{tremoloFlags} + +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{tremoloFlags}) is used: + +@lilypond[verbatim,fragment] + c'2:8 c':32 | c': c': | +@end lilypond + +@c [TODO : stok is te kort bij 32en] + +@refbugs + +Tremolos in this style do not carry over into the MIDI output. + +@seealso + +In this manual: @ref{Tremolo repeats}. + +Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}. + +@node Measure repeats +@subsection Measure repeats + +@cindex percent repeats +@cindex measure repeats + +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-like signs, +patterns that divide the measure length are replaced by slashes: + +@lilypond[verbatim,raggedright] + \context Voice { \repeat "percent" 4 { c'4 } + \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 } +} +@end lilypond + +@seealso + +Internals: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, +@internalsref{PercentRepeatedMusic}, and +@internalsref{DoublePercentRepeat}. + + + +@node Rhythmic music +@section Rhythmic music + + +@menu +* Showing melody rhythms:: +* Entering percussion:: +* Percussion staves:: +@end menu + + +@node Showing melody rhythms +@subsection Showing melody rhythms + +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 has a single line: + +@lilypond[fragment,relative,verbatim] + \context RhythmicStaff { + \time 4/4 + c4 e8 f g2 | r4 g r2 | g1:32 | r1 | + } +@end lilypond + +@seealso + +Internals: @internalsref{RhythmicStaff}. + +Examples: @inputfileref{input/regression,rhythmic-staff.ly}. + + +@node Entering percussion +@subsection Entering percussion + +@cindex percussion +@cindex drums + +@syntax + +Percussion notes may be entered in @code{\drums} mode, which is +similar to @code{notes}. Each piece of percussion has a full name and +an abbreviated name, and both be used in input files: + +@lilypond[raggedright] + \drums { hihat4 hh4 } +@end lilypond + +The complete list of drum names is in the init file +@file{ly/drumpitch-init.ly}. +@c TODO: properly document this. + +@seealso + +Internals: @internalsref{DrumNoteEvent}. + +@node Percussion staves +@subsection Percussion staves +@cindex percussion +@cindex drums + +A percussion part for more than one instrument typically uses a +multiline staff where each position in the staff refers to one piece +of percussion. + + +To typeset the music, the notes must be interpreted in a +@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts: + +@c +@lilypond[raggedright,verbatim] +up = \drums { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } +down = \drums { bassdrum4 snare8 bd r bd sn4 } +\score { + \new DrumStaff + << \new DrumVoice { \voiceOne \up } + \new DrumVoice { \voiceTwo \down } +>> } +@end lilypond + +The above example shows verbose polyphonic notation. The short +polyphonic notation, described in @ref{Polyphony}, can also be used if +the @internalsref{DrumVoices} are instantiated by hand first. For example, + +@lilypond[fragment] +\drums \new DrumStaff << + \context DrumVoice = "1" { s1 *2 } + \context DrumVoice = "2" { s1 *2 } + { + bd4 sn4 bd4 sn4 + << + { \repeat unfold 16 hh16 } + \\ + { bd4 sn4 bd4 sn4 } + >> + } +>> +@end lilypond + + +There are also other layout possibilities. To use these, set the +property @code{drumStyleTable} in context @internalsref{DrumVoice}. +The following variables have been predefined: + +@table @code +@item drums-style +is the default. It typesets a typical drum kit on a five-line staff + +@lilypond[noindent] +nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc + bd sn ss tomh tommh tomml toml tomfh tomfl } +mus = \drums { cymc cyms cymr hh | hhc hho hhho hhp | \break cb hc + bd sn ss tomh tommh tomml toml tomfh tomfl s16 } +\score { + << \new DrumStaff\with { + \remove Bar_engraver + \remove Time_signature_engraver + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + minimumVerticalExtent = #'(-4.0 . 5.0) + } \mus + \context Lyrics \nam + >> + \paper { + %% need to do this, because of indented @itemize + linewidth= 9 \cm + \translator { \ScoreContext + \override BarNumber #'transparent =##T +}}} +@end lilypond + +The drum scheme supports six different toms. When there fewer toms, simply +select the toms that produce the desired result, i.e. to get toms on +the three middle lines you use @code{tommh}, @code{tomml} and +@code{tomfh}. + +@item timbales-style +to typeset timbales on a two line staff: + +@lilypond[raggedright] +nam = \lyrics { timh ssh timl ssl cb } +mus = \drums { timh ssh timl ssl cb s16 } +\score { + << + \context DrumStaff \with { + \remove Bar_engraver + \remove Time_signature_engraver + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + \override StaffSymbol #'line-count = #2 + \override StaffSymbol #'staff-space = #2 + minimumVerticalExtent = #'(-3.0 . 4.0) + drumStyleTable = #timbales-style + } \mus + \context Lyrics \nam + >> +} +@end lilypond +@item congas-style +to typeset congas on a two line staff: + +@lilypond[raggedright] +nam = \lyrics { cgh cgho cghm ssh cgl cglo cglm ssl } +mus = \drums { cgh cgho cghm ssh cgl cglo cglm ssl s16 } +\score { + << + \context DrumStaff\with { + \remove Bar_engraver + \remove Time_signature_engraver + drumStyleTable = #congas-style + \override StaffSymbol #'line-count = #2 + + %% this sucks; it will lengthen stems. + \override StaffSymbol #'staff-space = #2 + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + } \mus + \context Lyrics \nam + >> +} +@end lilypond +@item bongos-style +to typeset bongos on a two line staff: + +@lilypond[raggedright] +nam = \lyrics { boh boho bohm ssh bol bolo bolm ssl } +mus = \drums { boh boho bohm ssh bol bolo bolm ssl s16 } +\score { + << + \context DrumStaff\with { + \remove Bar_engraver + \remove Time_signature_engraver + \override StaffSymbol #'line-count = #2 + drumStyleTable = #bongos-style + + %% this sucks; it will lengthen stems. + \override StaffSymbol #'staff-space = #2 + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + } \mus + \context Lyrics \nam + >> +} +@end lilypond + +@item percussion-style +to typeset all kinds of simple percussion on one line staves: +@lilypond[raggedright] +nam = \lyrics { tri trio trim gui guis guil cb cl tamb cab mar hc } +mus = \drums { tri trio trim gui guis guil cb cl tamb cab mar hc s16 } +\score { + << + \context DrumStaff\with{ + \remove Bar_engraver + drumStyleTable = #percussion-style + \override StaffSymbol #'line-count = #1 + \remove Time_signature_engraver + \override Stem #'transparent = ##t + \override Stem #'Y-extent-callback = ##f + } \mus + \context Lyrics \nam + >> +} +@end lilypond +@end table + +If you do not like any of the predefined lists you can define your own +list at the top of your file: + +@lilypond[raggedright,verbatim] +#(define mydrums '( + (bassdrum default #f -1) + (snare default #f 0) + (hihat cross #f 1) + (pedalhihat xcircle "stopped" 2) + (lowtom diamond #f 3) +)) +up = \drums { hh8 hh hh hh hhp4 hhp } +down = \drums { bd4 sn bd toml8 toml } +\score { + \new DrumStaff << + \set DrumStaff.drumStyleTable + = #(alist->hash-table mydrums) + \new DrumVoice { \voiceOne \up } + \new DrumVoice { \voiceTwo \down } + >> +} +@end lilypond + + +@seealso + +Init files: @file{ly/drumpitch-init.ly}. + +Internals: @internalsref{DrumStaff}, @internalsref{DrumVoice}. + +@refbugs + +Short polyphonic notation, @code{<< @dots{} \\ @dots{} >>}, does not +work for @internalsref{DrumVoices}. + +Because general MIDI does not contain rim shots, the sidestick is used +for this purpose instead. + +@node Piano music +@section Piano music + +Piano staves are two normal staves coupled with a brace. The staves +are largely independent, but sometimes voices can cross between the +two staves. The same notation is also used for harps and other key +instruments. The @internalsref{PianoStaff} is especially built to +handle this cross-staffing behavior. In this section we discuss the +@internalsref{PianoStaff} and some other pianistic peculiarities. + + +@menu +* Automatic staff changes:: +* Manual staff switches:: +* Pedals:: +* Arpeggio:: +* Staff switch lines:: +@end menu + +@refbugs + +There is no support for putting chords across staves. You can get +this result by increasing the length of the stem in the lower stave so +it reaches the stem in the upper stave, or vice versa. An example is +included with the distribution as +@inputfileref{input/test,stem-cross-staff.ly}. + +Dynamics are not centered, but kludges do exist. See +@inputfileref{input/template,piano-dynamics.ly}. + +@cindex cross staff stem +@cindex stem, cross staff + +The distance between the two staves is normally fixed across the +entire score. It is possible to tune this per system, but it does +require arcane command incantations. See +@inputfileref{input/test,piano-staff-distance.ly}. + + + + + + +@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 + \autochange \context Voice @{ @dots{}@var{music}@dots{} @} +@end example +The two staffs of the piano staff must be named @code{up} and +@code{down}. + +The autochanger switches on basis of pitch (middle C is the turning +point), and it looks ahead skipping over rests to switch in +advance. Here is a practical example: + +@lilypond[verbatim,raggedright] +\score { \notes \context PianoStaff << + \context Staff = "up" { + \autochange \new Voice \relative c' { + g4 a b c d r4 a g } } + \context Staff = "down" { + \clef bass + s1*2 +} >> } +@end lilypond + +@noindent +In this example, spacer rests are used to prevent the bottom staff from +terminating too soon. + + +@seealso + +In this manual: @ref{Manual staff switches}. + +Internals: @internalsref{AutoChangeMusic}. + + + +@refbugs + +The staff switches often do not end up in optimal places. For high +quality output, staff switches should be specified manually. + + + +@node Manual staff switches +@subsection Manual staff switches + +@cindex manual staff switches +@cindex staff switch, manual + +Voices can be switched between staves manually, using the following command: +@example + \change Staff = @var{staffname} @var{music} +@end example + +@noindent +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"}. + + + +@node Pedals +@subsection Pedals +@cindex Pedals + +Pianos have pedals that alter the way sound are produced. Generally, a +piano has three pedals, sustain, una corda, and sostenuto. + +@syntax + +Piano pedal instruction can be expressed by attaching +@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda}, +@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a +note or chord: + +@lilypond[fragment,verbatim] + c'4\sustainDown c'4\sustainUp +@end lilypond + +What is printed can be modified by setting @code{pedal@var{X}Strings}, +where @var{X} is one of the pedal types: @code{Sustain}, +@code{Sostenuto} or @code{UnaCorda}. Refer to the generated +documentation of @internalsref{SustainPedal} for more information. + +Pedals can also be indicated by a sequence of brackets, by setting the +@code{pedalSustainStyle} property to @code{bracket} objects: + +@lilypond[fragment,verbatim] + \set Staff.pedalSustainStyle = #'bracket + c''4\sustainDown d''4 e''4 + a'4\sustainUp\sustainDown + f'4 g'4 a'4\sustainUp +@end lilypond + +A third style of pedal notation is a mixture of text and brackets, +obtained by setting the @code{pedalSustainStyle} style property to +@code{mixed}: + +@lilypond[fragment,verbatim] + \set Staff.pedalSustainStyle = #'mixed +c''4\sustainDown d''4 e''4 +c'4\sustainUp\sustainDown + f'4 g'4 a'4\sustainUp +@end lilypond + +The default `*Ped.' style for sustain and damper pedals corresponds to +style @code{#'text}. The sostenuto pedal uses @code{mixed} style by +default. + +@lilypond[fragment,verbatim] +c''4\sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4\sostenutoUp +@end lilypond + +For fine-tuning of the appearance of a pedal bracket, the properties +@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of +@code{PianoPedalBracket} objects (see +@internalsref{PianoPedalBracket} in the Program reference) can be modified. For example, the +bracket may be extended to the end of the note head: + +@lilypond[fragment,verbatim] +\override Staff.PianoPedalBracket + #'shorten-pair = #'(0 . -1.0) +c''4\sostenutoDown d''4 e''4 c'4 +f'4 g'4 a'4\sostenutoUp +@end lilypond + +@node Arpeggio +@subsection Arpeggio +@cindex Arpeggio + +@cindex broken arpeggio +@cindex @code{\arpeggio} + +You can specify an arpeggio sign on a chord by attaching an +@code{\arpeggio} to a chord: + + +@lilypond[fragment,relative,verbatim] + \arpeggio +@end lilypond + +When an arpeggio crosses staves, you attach an arpeggio to the chords +in both staves, and set +@internalsref{PianoStaff}.@code{connectArpeggios}: + +@lilypond[fragment,relative,verbatim] + \context PianoStaff << + \set PianoStaff.connectArpeggios = ##t + \new Staff { \arpeggio } + \new Staff { \clef bass \arpeggio } + >> +@end lilypond + +The direction of the arpeggio is sometimes denoted by adding an +arrowhead to the wiggly line: + +@lilypond[fragment,relative,verbatim] + \context Voice { + \arpeggioUp + \arpeggio + \arpeggioDown + \arpeggio + } +@end lilypond + +A square bracket on the left indicates that the player should not +arpeggiate the chord: + +@lilypond[fragment,relative,verbatim] + \arpeggioBracket + \arpeggio +@end lilypond + +@refcommands + +@cindex @code{\arpeggio} +@code{\arpeggio}, +@cindex @code{\arpeggioUp} +@code{\arpeggioUp}, +@cindex @code{\arpeggioDown} +@code{\arpeggioUp}, +@cindex @code{\arpeggioBoth} +@code{\arpeggioBoth}, +@cindex @code{\arpeggioBracket} +@code{\arpeggioBracket}. + +@seealso + +Internals: @internalsref{ArpeggioEvent} music expressions lead to +@internalsref{Arpeggio} objects. Cross staff arpeggios are +@internalsref{PianoStaff}.@internalsref{Arpeggio}. + +@refbugs + +It is not possible to mix connected arpeggios and unconnected +arpeggios in one @internalsref{PianoStaff} at the same time. + +@node Staff switch lines +@subsection Staff switch lines + + +@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 << + \set PianoStaff.followVoice = ##t + \context Staff \context Voice { + c1 + \change Staff=two + b2 a + } + \context Staff=two { \clef bass \skip 1*2 } + >> +@end lilypond + +The associated object is @internalsref{VoiceFollower}. + +@refcommands + +@cindex @code{\showStaffSwitch} +@code{\showStaffSwitch}, +@cindex @code{\hideStaffSwitch} +@code{\hideStaffSwitch}. + + +@node Vocal music +@section Vocal music + +This section discusses how to enter and print lyrics. + +@menu +* Entering lyrics:: +* The Lyrics context:: +* More stanzas:: +* Ambitus:: +@end menu + +@node Entering lyrics +@subsection Entering lyrics + + +@cindex lyrics +@cindex @code{\lyrics} +@cindex punctuation + +Lyrics are entered in a special input mode. This mode is is introduced +by the keyword @code{\lyrics}. In this mode you can enter lyrics, with +punctuation and accents without any hassle. Syllables are entered like +notes, but with pitches replaced by text. For example, +@example + \lyrics @{ Twin-4 kle4 twin- kle litt- le star2 @} +@end example + +A word in Lyrics mode begins with: an alphabetic character, @code{_}, +@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} +through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, +any 8-bit character with ASCII code over 127, or a two-character +combination of a backslash followed by one of @code{`}, @code{'}, +@code{"}, or @code{^}. + +Subsequent characters of a word can be any character that is not a digit +and not white space. One important consequence of this is that a word +can end with @code{@}}. The following example is usually a bug. The +syllable includes a @code{@}}, and hence the opening brace is not balanced: +@example + \lyrics @{ twinkle@} +@end example + +@cindex @code{\property}, in @code{\lyrics} +Similarly, a period following a alphabetic sequence, is included in +the resulting string. As a consequence, spaces must be inserted around +property commands: +@example + \override Score . LyricText #'font-shape = #'italic +@end example + +@cindex @code{_} +@cindex spaces, in lyrics +@cindex quotes, in lyrics + +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: + +@example + \lyrics @{ He said: "\"Let" my peo ple "go\"" @} +@end example + +@cindex hyphens +Hyphens can be entered as ordinary hyphens at the end of a syllable, i.e. +@example + soft- ware +@end example + +These will be attached to the end of the first syllable. + +Centered hyphens are entered using the special `@code{-}@code{-}' lyric +as a separate word between syllables. The hyphen will have variable +length depending on the space between the syllables and it will be +centered between the syllables. + +@cindex melisma +@cindex extender + +When a lyric is sung over many notes (this is called a melisma), this is +indicated with a horizontal line centered between a syllable and the +next one. Such a line is called an extender line, and it is entered as +@code{__}. + +@seealso + +Internals: @internalsref{LyricEvent}, @internalsref{HyphenEvent}, and +@internalsref{ExtenderEvent}. + +Examples: @inputfileref{input/test,lyric-hyphen-retain.ly}. + +@refbugs + +The definition of lyrics mode is too complex. + + + +@node The Lyrics context +@subsection The Lyrics context + +Lyrics are printed by interpreting them in a @internalsref{Lyrics} context: +@example + \context Lyrics \lyrics @dots{} +@end example + +@cindex automatic syllable durations +@cindex @code{\lyricsto} +@cindex lyrics and melodies + +This will place the lyrics according to the durations that were +entered. The lyrics can also be aligned under a given melody +automatically. In this case, it is no longer necessary to enter the +correct duration for each syllable. This is achieved by combining the +melody and the lyrics with the @code{\lyricsto} expression: +@example +\lyricsto @var{name} \new Lyrics @dots{} +@end example + +This aligns the lyrics to the +@c +notes of the @internalsref{Voice} context called @var{name}, which has +to exist. Therefore, normally the @code{Voice} is specified first, and +then the lyrics are specified with @code{\lyricsto}. + +For different or more complex orderings, the best way is to setup the +hierarchy of staves and lyrics first, e.g. +@example +\context ChoirStaff \notes << + \context Lyrics = sopranoLyrics @{ s1 @} + \context Voice = soprano @{ @emph{music} @} + \context Lyrics = tenorLyrics @{ s1 @} + \context Voice = tenor @{ @emph{music} @} +>> +@end example +and then combine the appropriate melodies and lyric lines: +@example + \lyricsto "soprano" \new Lyrics @emph{the lyrics} +@end example + +@noindent +The final input would resemble + +@example + << \context ChoirStaff \notes << @emph{setup the music} >> + \lyricsto "soprano" @emph{etc} + \lyricsto "alto" @emph{etc} + @emph{etc} + >> +@end example + + +The @code{\lyricsto} command detects melismata: it only puts one +syllable under a tied or slurred group of notes. If you want to force +an unslurred group of notes to be a melisma, then insert +@code{\melisma} after the first note of the group, and +@code{\melismaEnd} after the last one, e.g. + +@lilypond[relative=1,raggedright,fragment,verbatim] +<< \context Voice = "lala" { \time 3/4 + f4 g8 + \melisma + f e f + \melismaEnd + e2 } + \lyricsto "lala" \new Lyrics \lyrics { + la di __ daah + } >> +@end lilypond + +In addition, notes are considered a melisma if they are manually +beamed, and automatic beaming (see @ref{Setting automatic beam +behavior}) is switched off. The criteria for deciding melismata +can be tuned with the property @code{melismaBusyProperties}. See +@internalsref{Melisma_translator} for more information. + +When multiple stanzas are put on the same melody, it can happen that +two stanzas have melismata in different locations. This can be +remedied by switching off melismata for one +@internalsref{Lyrics}. This is achieved by setting +the @code{ignoreMelismata} property to @code{#t}. An example is shown +in @inputfileref{input/regression,lyric-combine-new.ly}. + +@cindex SATB +@cindex choral score + +A complete example of a SATB score setup is in the file +@inputfileref{input/template,satb.ly}. + + +@refcommands + +@code{\melisma}, @code{\melismaEnd} +@cindex @code{\melismaEnd} +@cindex @code{\melisma} + +@seealso + +Internals: Music expressions: @internalsref{LyricCombineMusic}, +Contexts: @internalsref{Lyrics}, @internalsref{Melisma_translator}. + +Examples: @inputfileref{input/template,satb.ly}, +@inputfileref{input/regression,lyric-combine-new.ly}. + +@refbugs + +Melismata are not detected automatically, and extender lines must be +inserted by hand. + + +For proper processing of extender lines, the +@internalsref{Lyrics} and @internalsref{Voice} should be +linked. This can be achieved either by using @code{\lyricsto} or by +setting corresponding names for both contexts. The latter is explained +in @ref{More stanzas}. + +@node More stanzas +@subsection More stanzas + +@cindex phrasing, in lyrics + + +The lyrics should be aligned with the note heads of the melody. To +achieve this, each line of lyrics should be marked to correspond with +the melodic line. This is done automatically when @code{\lyricsto}, +but it can also be done manually. + +To this end, give the @internalsref{Voice} context an identity: +@example +\context Voice = duet @{ + \time 3/4 + g2 e4 a2 f4 g2. @} +@end example + +Then set the @internalsref{Lyrics} contexts to names starting with +that identity followed by a dash. In the preceding example, the +@internalsref{Voice} identity is @code{duet}, so the identities of the +@internalsref{Lyrics}s are marked @code{duet-1} and @code{duet-2}: +@example + \context Lyrics = "duet-1" @{ + Hi, my name is bert. @} + \context Lyrics = "duet-2" @{ + Ooooo, ch\'e -- ri, je t'aime. @} +@end example + +The complete example is shown here: +@lilypond[raggedright,verbatim] +\score { + << \notes \relative c'' \context Voice = duet { \time 3/4 + g2 e4 a2 f4 g2. } + \lyrics << \lyricsto "duet" \new Lyrics { + \set stanza = "B." + \set vocNam = "Bert" + Hi, my name is bert. } + \lyricsto "duet" \new Lyrics { + \set stanza = "E." + \set vocNam = "Ernie" + Ooooo, ch\'e -- ri, je t'aime. + } + >> >> +} +@end lilypond + +@cindex stanza number +@cindex singer's names +@cindex name of singer + +Stanza numbers can be added by setting @code{stanza}, e.g. + +@example + \set stanza = "B." + @dots{} + \set stanza = "E." +@end example + +Notice how dots are surrounded with spaces in @code{\lyrics} mode, to +prevent @code{stanza} being interpreted as a single +string. + +This example also demonstrates how names of the singers can be added +using @code{vocalName} analogous to instrument annotations for staves. +A short version may be entered as @code{vocNam}. + +To make empty spaces in lyrics, use @code{\skip}. + + +@seealso + +Internals: Layout objects @internalsref{LyricText} and +@internalsref{VocalName}. Music expressions: +@internalsref{LyricEvent}. + +@refbugs + +@cindex ambiguity + +Input for lyrics introduces a syntactical ambiguity: + +@example +foo = bar +@end example + +@noindent +is interpreted as assigning a string identifier @code{\foo} such that +it contains @code{"bar"}. However, it could also be interpreted as +making or a music identifier @code{\foo} containing the syllable +`bar'. The force the latter interpretation, use +@example + foo = \lyrics bar4 +@end example + + +@node Ambitus +@subsection Ambitus +@cindex ambitus + +The term @emph{ambitus} (plural: ambituses) denotes a range of pitches +for a given voice in a part of music. It also may denote the pitch +range that a musical instrument is capable of playing. Most musical +instruments have their ambitus standardized (or at least there is +agreement upon the minimal ambitus of a particular type of +instrument), such that a composer or arranger of a piece of music can +easily meet the ambitus constraints of the targeted instrument. +However, the ambitus of the human voice depends on individual +physiological state, including education and training of the voice. +Therefore, a singer potentially has to check for each piece of music +if the ambitus of that piece meets his individual capabilities. This +is why the ambitus of a piece may be of particular value to vocal +performers. + +The ambitus is typically notated on a per-voice basis at the very +beginning of a piece, e.g. nearby the initial clef or time signature of +each staff. The range is graphically specified by two note heads, that +represent the minimum and maximum pitch. Some publishers use a textual +notation: they put the range in words in front of the corresponding +staff. LilyPond only supports the graphical ambitus notation. + +To apply, add the @internalsref{Ambitus_engraver} to the +@internalsref{Voice} context, i.e. + +@example + \paper @{ + \translator @{ + \VoiceContext + \consists Ambitus_engraver + @} + @} +@end example + +This results in the following output: + +@lilypond[raggedright] +upper = \notes \relative c { + \clef "treble" + \key c \minor + as'' c e2 bes f cis d4 e f2 g +} +lower = \notes \relative c { + \clef "treble" + \key e \major + e'4 b g a c es fis a cis b a g f e d2 +} +\score { + \context ChoirStaff { + << + \new Staff { \upper } + \new Staff { \lower } + >> + } + \paper { + \translator { + \StaffContext + \consists Ambitus_engraver + } + } +} +@end lilypond + +If you have multiple voices in a single staff, and you want a single +ambitus per staff rather than per each voice, then add the +@internalsref{Ambitus_engraver} to the @internalsref{Staff} context +rather than to the @internalsref{Voice} context. + +It is possible to tune individual ambituses for multiple voices on a +single staff, for example by erasing or shifting them horizontally. An +example is in @inputfileref{input/test,ambitus-mixed.ly}. + +@seealso + +Internals: @internalsref{Ambitus}. + +Examples: @inputfileref{input/regression,ambitus.ly}, +@inputfileref{input/test,ambitus-mixed.ly}. + +@refbugs + +There is no collision handling in the case of multiple per-voice +ambitus. + +@node Tablatures +@section Tablatures + +Tablature notation is used for notating music for plucked string +instruments. It notates pitches not by using note heads, but by +indicating on which string and fret a note must be played. LilyPond +offers limited support for tablature. + +@menu +* Tablatures basic:: +* Non-guitar tablatures:: +@end menu + +@node Tablatures basic +@subsection Tablatures basic +@cindex Tablatures basic + +The string number associated to a note is given as a backslash +followed by a number, e.g. @code{c4\3} for a C quarter on the third +string. By default, string 1 is the highest one, and the tuning +defaults to the standard guitar tuning (with 6 strings). The notes +are printed as tablature, by using @internalsref{TabStaff} and +@internalsref{TabVoice} contexts: + +@lilypond[fragment,verbatim] +\notes \context TabStaff { + a,4\5 c'\2 a\3 e'\1 + e\4 c'\2 a\3 e'\1 +} +@end lilypond + +@cindex minimumFret + +When no string is specified, the first string that does not give a +fret number less than @code{minimumFret} is selected. The default +value for @code{minimumFret} is 0: + + +@example +e8 fis gis a b cis' dis' e' +\set TabStaff.minimumFret = #8 +e8 fis gis a b cis' dis' e' +@end example +@lilypond[noindent] +frag = \notes { + \key e \major + e8 fis gis a b cis' dis' e' + \set TabStaff.minimumFret = #8 + e8 fis gis a b cis' dis' e' +} +\score { + \context StaffGroup << + \context Staff { \clef "G_8" \frag } + \context TabStaff { \frag } + >> +} +@end lilypond + +@seealso + +Internals: @internalsref{TabStaff}, @internalsref{TabVoice}, and +@internalsref{StringNumberEvent}. + +@refbugs + +Chords are not handled in a special way, and hence the automatic +string selector may easily select the same string to two notes in a +chord. + + +@node Non-guitar tablatures +@subsection Non-guitar tablatures +@cindex Non-guitar tablatures + +You can change the number of strings, by setting the number of lines +in the @internalsref{TabStaff}. + +You can change the tuning of the strings. A string tuning is given as +a Scheme list with one integer number for each string, the number +being the pitch (measured in semitones relative to middle C) of an +open string. The numbers specified for @code{stringTuning} are the +numbers of semitones to subtract or add, starting the specified pitch +by default middle C, in string order. Thus, the notes are e, a, d, and +g: + +@lilypond[fragment,verbatim] + \context TabStaff << + \set TabStaff.stringTunings = #'(-5 -10 -15 -20) + + \notes { + a,4 c' a e' e c' a e' + } + >> +@end lilypond + +It is possible to change the Scheme function to format the tablature +note text. The default is @code{fret-number-tablature-format}, which +uses the fret number. For instruments that do not use this notation, +you can create a special tablature formatting function. This function +takes three argument: string number, string tuning and note pitch. + +@refbugs + +No guitar special effects have been implemented. + + + +@node Chord names +@section Chord names +@cindex Chords + +LilyPond has support for both printing chord names. Chords may be +entered in musical chord notation, i.e. @code{< .. >}, but they can +also be entered by name. Internally, the chords are represented as a +set of pitches, so they can be transposed: + + +@lilypond[verbatim,raggedright] +twoWays = \notes \transpose c c' { + \chords { + c1 f:sus4 bes/f + } + + + + } + +\score { + << \context ChordNames \twoWays + \context Voice \twoWays >> } +@end lilypond + +This example also shows that the chord printing routines do not try to +be intelligent. The last chord (@code{f bes d}) is not interpreted as +an inversion. + + +@menu +* Chords mode:: +* Printing chord names:: +@end menu + + +@node Chords mode +@subsection Chords mode +@cindex Chords mode + +Chord mode is a mode where you can input sets of pitches using common +names. It is introduced by the keyword @code{\chords}. +In chords mode, a chord is entered by the root, which is entered +like a common pitch: +@lilypond[fragment,verbatim,relative=1] +\chords { es4. d8 c2 } +@end lilypond +@cindex chord entry +@cindex chord mode + +Other chords may be entered by suffixing a colon, and introducing a +modifier, and optionally, a number: +@c +@lilypond[fragment,verbatim] +\chords { e1:m e1:7 e1:m7 } +@end lilypond +The first number following the root is taken to be the `type' of the +chord, thirds are added to the root until it reaches the specified +number: +@lilypond[fragment,verbatim] + \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 } +@end lilypond + +@cindex root of chord +@cindex additions, in chords +@cindex removals, in chords + +More complex chords may also be constructed adding separate steps +to a chord. Additions are added after the number following +the colon, and are separated by dots: +@c +@lilypond[verbatim,fragment] + \chords { c:5.6 c:3.7.8 c:3.6.13 } +@end lilypond +Chord steps can be altered by suffixing a @code{-} or @code{+} sign +to the number: +@lilypond[verbatim,fragment] + \chords { c:7+ c:5+.3- c:3-.5-.7- } +@end lilypond +Removals are specified similarly, and are introduced by a caret. They +must come after the additions: +@lilypond[verbatim,fragment] + \chords { c^3 c:7^5 c:9^3.5 } +@end lilypond + +Modifiers can be used to change pitches. The following modifiers are +supported: +@table @code +@item m + is the minor chord. This modifier lowers the 3rd and (if present) the 7th step. +@item dim + is the diminished chord. This modifier lowers the 3rd, 5th and (if present) + the 7th step. +@item aug + is the augmented chord. This modifier raises the 5th step. +@item maj + is the major 7th chord. This modifier raises the 7th step if present. +@item sus + is the suspended 4th or 2nd. This modifier removes the 3rd +step. Append either @code{2} or @code{4} to add the 2nd or 4th step to +the chord. +@end table +Modifiers can be mixed with additions: +@lilypond[verbatim,fragment] + \chords { c:sus4 c:7sus4 c:dim7 c:m6 } +@end lilypond + +@cindex modifiers, in chords. +@cindex @code{aug} +@cindex @code{dim} +@cindex @code{maj} +@cindex @code{sus} +@cindex @code{m} + +Since an unaltered 11 does not sound good when combined with an +unaltered 13, the 11 is removed in this case (unless it is added +explicitly): +@c +@lilypond[fragment,verbatim] + \chords { c:13 c:13.11 c:m13 } +@end lilypond + +@cindex @code{/} + +An inversion (putting one pitch of the chord on the bottom), as well +as bass notes, can be specified by appending +@code{/}@var{pitch} to the chord: +@lilypond[fragment,verbatim] + \chords { c1 c/g c/f } +@end lilypond +@cindex @code{/+} + +A bass note can be added instead of transposed out of the chord, +by using @code{/+}@var{pitch}. + +@lilypond[fragment,verbatim] + \chords { c1 c/+g c/+f } +@end lilypond + +Chords is a mode similar to @code{\lyrics}, @code{\notes} etc. Most +of the commands continue to work, for example, @code{r} and +@code{\skip} can be used to insert rests and spaces, and property +commands may be used to change various settings. + + + +@refbugs + +Each step can only be present in a chord once. The following +simply produces the augmented chord, since @code{5+} is interpreted +last: +@cindex clusters +@lilypond[verbatim,fragment] + \chords { c:5.5-.5+ } +@end lilypond + + +@node Printing chord names +@subsection Printing chord names + +@cindex printing chord names +@cindex chord names +@cindex chords + +For displaying printed chord names, use the @internalsref{ChordNames} context. +The chords may be entered either using the notation +described above, or directly using @code{<} and @code{>}: + +@lilypond[verbatim,raggedright] +scheme = \notes { + \chords {a1 b c} +} +\score { + \notes<< + \context ChordNames \scheme + \context Staff \scheme + >> +} +@end lilypond + +You can make the chord changes stand out by setting +@internalsref{ChordNames}.@code{chordChanges} to true. This will only +display chord names when there is a change in the chords scheme and at +the start of a new line: + +@lilypond[verbatim,linewidth=9\cm] +scheme = \chords { + c1:m c:m \break c:m c:m d +} +\score { + \notes << + \context ChordNames { + \set chordChanges = ##t + \scheme } + \context Staff \transpose c c' \scheme + >> +} +@end lilypond + +The default chord name layout is a system for Jazz music, proposed by +Klaus Ignatzek (see @ref{Literature list}). It can be tuned through the +following properties: + +@table @code +@cindex chordNameExceptions +@item chordNameExceptions +This is a list that contains the chords that have special formatting. +For an example, see +@inputfileref{input/regression,chord-name-exceptions.ly}. +@cindex exceptions, chord names. + + +@cindex majorSevenSymbol +@item majorSevenSymbol +This property contains the markup object used for the 7th step, when +it is major. Predefined options are @code{whiteTriangleMarkup} and +@code{blackTriangleMarkup}. See +@inputfileref{input/regression,chord-name-major7.ly} for an example. + +@cindex chordNameSeparator +@item chordNameSeparator +Different parts of a chord name are normally separated by a +slash. By setting @code{chordNameSeparator}, you can specify other +separators, e.g. +@lilypond[fragment,verbatim] +\context ChordNames \chords { + c:7sus4 + \set chordNameSeparator + = \markup { \typewriter "|" } + c:7sus4 } +@end lilypond + +@cindex chordRootNamer +@item chordRootNamer +The root of a chord is usually printed as a letter with an optional +alteration. The transformation from pitch to letter is done by this +function. Special note names (for example, the German ``H'' for a +B-chord) can be produced by storing a new function in this property. + +The predefined variables @code{\germanChords}, +@code{\semiGermanChords} set these variables. + + +@cindex chordNoteNamer +@item chordNoteNamer +The default is to print single pitch, e.g. the bass note, using the +@code{chordRootNamer}. The @code{chordNoteNamer} property can be set +to a specialized function to change this behavior. For example, the +base can be printed in lower case. + +@end table + + +There are also two other chord name schemes implemented: an alternate +Jazz chord notation, and a systematic scheme called Banter chords. The +alternate jazz notation is also shown on the chart in @ref{Chord name +chart}. Turning on these styles is described in the input file +@inputfileref{input/test,chord-names-jazz.ly}. + +@cindex Banter +@cindex jazz chords +@cindex chords, jazz + + +@refcommands + +@cindex @code{\germanChords} +@code{\germanChords}, +@cindex @code{\semiGermanChords} +@code{\semiGermanChords}. + + + + +@seealso + +Examples: @inputfileref{input/regression,chord-name-major7.ly}, +@inputfileref{input/regression,chord-name-exceptions.ly}, +@inputfileref{input/test,chord-names-jazz.ly}, +@inputfileref{input/test,chord-names-german.ly}. + +Init files: @file{scm/chords-ignatzek.scm}, and @file{scm/chord-entry.scm}. + + +@refbugs + +Chord names are determined solely from the list of pitches. Chord +inversions are not identified, and neither are added bass notes. This +may result in strange chord names when chords are entered with the +@code{< .. >} syntax. + + + + +@node Orchestral music +@section Orchestral music + +@cindex Writing parts + +Orchestral music involves some special notation, both in the full +score and the individual parts. This section explains how to tackle +some common problems in orchestral music. + + + +@menu +* Multiple staff contexts:: +* Rehearsal marks:: +* Bar numbers:: +* Instrument names:: +* Transpose:: +* Instrument transpositions:: +* Multi measure rests:: +* Automatic part combining:: +* Hiding staves:: +* Different editions from one source:: +* Quoting other voices:: +@end menu + +@node Multiple staff contexts +@subsection Multiple staff contexts + +Polyphonic scores consist of many staves. These staves can be +constructed in three different ways: +@itemize @bullet +@item The group is started with a brace at the left. This is done with the +@internalsref{GrandStaff} context. +@item The group is started with a bracket. This is done with the +@internalsref{StaffGroup} context +@item The group is started with a vertical line. This is the default +for the score. +@end itemize + +@cindex Staff, multiple +@cindex bracket, vertical +@cindex brace, vertical +@cindex grand staff +@cindex staff group + + + + +@node Rehearsal marks +@subsection Rehearsal marks +@cindex Rehearsal marks +@cindex mark +@cindex @code{\mark} + +To print a rehearsal mark, use the @code{\mark} command: +@lilypond[fragment,verbatim] +\relative c'' { + c1 \mark \default + c1 \mark \default + c1 \mark #8 + c1 \mark \default + c1 \mark \default +} +@end lilypond + +@noindent +(The letter I is skipped in accordance with engraving traditions.) + +The mark is incremented automatically if you use @code{\mark +\default}, but you can also use an integer argument to set the mark +manually. The value to use is stored in the property +@code{rehearsalMark}. + +The style is defined by the property @code{markFormatter}. It is a +function taking the current mark (an integer) and the current context +as argument. It should return a markup object. In the following +example, @code{markFormatter} is set to a canned procedure. After a +few measures, it is set to function that produces a boxed number. + +@lilypond[verbatim,fragment,relative=1] + \set Score.markFormatter = #format-mark-numbers + c1 \mark \default + c1 \mark \default + \set Score.markFormatter + = #(lambda (mark context) + (make-bold-markup (make-box-markup (number->string mark)))) + c1 \mark \default + c1 \mark \default +@end lilypond + +The file @file{scm/translation-functions.scm} contains the definitions +of @code{format-mark-numbers} (the default format) and +@code{format-mark-letters}. They can be used as inspiration for other +formatting functions. + + +@cindex coda on bar line +@cindex segno on bar line +@cindex fermata on bar line +@cindex bar lines, symbols on + +The @code{\mark} command can also be used to put signs like coda, +segno and fermatas on a bar line. Use @code{\markup} to +to access the appropriate symbol: + +@lilypond[fragment,verbatim,relative=1] + c1 \mark \markup { \musicglyph #"scripts-ufermata" } + c1 +@end lilypond + +In this case, during line breaks, marks must also be printed at the +end of the line, and not at the beginning. Use the following to force +that behavior: +@example +\override Score.RehearsalMark + #'break-visibility = #begin-of-line-invisible +@end example + +@cindex fermatas +@cindex coda +@cindex segno +@cindex bar lines, putting symbols on + +@seealso + +Internals: @internalsref{MarkEvent}, @internalsref{RehearsalMark}. + +Init files: @file{scm/translation-functions.scm} contains the +definition of @code{format-mark-numbers} and +@code{format-mark-letters}. They can be used as inspiration for other +formatting functions. + +Examples: @inputfileref{input/regression,rehearsal-mark-letter.ly}, +@inputfileref{input/regression,rehearsal-mark-number.ly}. + + +@node Bar numbers +@subsection Bar numbers + + +@cindex bar numbers +@cindex measure numbers +@cindex currentBarNumber + +Bar numbers are printed by default at the start of the line. The +number itself is stored in the +@code{currentBarNumber} property, +which is normally updated automatically for every measure. + +Bar numbers can be typeset at regular intervals instead of at the +beginning of each line. This is illustrated in the following example, +whose source is available as +@inputfileref{input/test,bar-number-regular-interval.ly}: + +@lilypondfile[]{bar-number-regular-interval.ly} + + +@seealso + +Internals: @internalsref{BarNumber}. + +Examples: @inputfileref{input/test,bar-number-every-five-reset.ly}, +and @inputfileref{input/test,bar-number-regular-interval.ly}. + +@refbugs + +Bar numbers can collide with the @internalsref{StaffGroup} bracket, if +there is one at the top. To solve this, the +@code{padding} property of @internalsref{BarNumber} can be +used to position the number correctly. + +@node Instrument names +@subsection Instrument names + +In an orchestral score, instrument names are printed left side of the +staves. + +This can be achieved by setting @internalsref{Staff}.@code{instrument} +and @internalsref{Staff}.@code{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: + +@quotation +@lilypond[verbatim,raggedright] + \set Staff.instrument = "ploink " { c''4 } +@end lilypond +@end quotation + +You can also use markup texts to construct more complicated instrument +names: + +@quotation +@lilypond[fragment,verbatim,raggedright] + \notes { + \set Staff.instrument = \markup { + \column < "Clarinetti" + { "in B" + \smaller \flat + } + > + } + { c''1 } + } +@end lilypond +@end quotation + +@seealso + +Internals: @internalsref{InstrumentName}. + +@refbugs + +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} + +A music expression can be transposed with @code{\transpose}. The syntax +is +@example + \transpose @var{from} @var{to} @var{musicexpr} +@end example + +This means that @var{musicexpr} is transposed by the interval between +the pitches @var{from} and @var{to}: any note with pitch @code{from} +is changed to @code{to}. + + +For example, consider a piece written in the key of D major. If +this piece is a little too low for its performer, it can be +transposed up to E major with +@example + \transpose d e @dots{} +@end example + +Consider a part written for violin (a C instrument). If +this part is to be played on the A clarinet, the following +transposition will produce the appropriate part + +@example + \transpose a c @dots{} +@end example + +Since @var{from} and @var{to} are pitches, @code{\transpose} must be +inside a @code{\notes} section. @code{\transpose} distinguishes +between enharmonic pitches: both @code{\transpose c cis} or +@code{\transpose c des} will transpose up half a tone. The first +version will print sharps and the second version will print flats: + +@lilypond[raggedright,verbatim] +mus =\notes { \key d \major cis d fis g } +\score { \notes \context Staff { + \clef "F" \mus + \clef "G" + \transpose c g' \mus + \transpose c f' \mus +}} +@end lilypond + + +@seealso + +Internals: @internalsref{TransposedMusic}, and +@internalsref{UntransposableMusic}. + +@refbugs + +If you want to use both @code{\transpose} and @code{\relative}, then +you must put @code{\transpose} outside of @code{\relative}, since +@code{\relative} will have no effect music that appears inside a +@code{\transpose}. + +@node Instrument transpositions +@subsection Instrument transpositions + +The key of a transposing instrument can also be specified. This +applies to many wind instruments, for example, clarinets (B-flat, A and +E-flat), horn (F) and trumpet (B-flat, C, D and E-flat). + +@syntax + +The transposition is entered after the keyword @code{\transposition}: + +@example + \transposition bes %% B-flat clarinet +@end example + +This command sets the property @code{instrumentTuning}. The value of +this property is used for MIDI output and quotations. It does not +affect how notes are printed in the current staff. + +@cindex transposition, MIDI +@cindex transposition, instrument + + +@node Multi measure rests +@subsection Multi measure rests +@cindex multi measure rests +@cindex Rests, multi measure + +@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, empty measures will not +be expanded, and the appropriate number is added automatically: + +@lilypond[fragment,verbatim] + \time 4/4 r1 | R1 | R1*2 + \set Score.skipBars = ##t R1*17 R1*4 +@end lilypond + +The @code{1} in @code{R1} is similar to the duration notation used for +notes. Hence, for time signatures other than 4/4, you must enter other +durations. This can be done with augmentation dots or fractions: + +@lilypond[fragment,verbatim] + \set Score.skipBars = ##t + \time 3/4 + R2. | R2.*2 + \time 13/8 + R1*13/8 + R1*13/8*12 +@end lilypond + +An @code{R} spanning a single measure is printed as either a whole rest +or a breve, centered in the measure regardless of the time signature. + +@cindex text on multi-measure rest +@cindex script on multi-measure rest +@cindex fermata on multi-measure rest + +Texts can be added to multi-measure rests by using the +@var{note}-@code{markup} syntax (see @ref{Text markup}). In this case, the number is +replaced. If you need both texts and the number, you must add the +number by hand. A variable (@code{\fermataMarkup}) is provided for +adding fermatas: + + +@lilypond[verbatim,fragment] + \time 3/4 + R2._\markup { "Ad lib" } + R2.^\fermataMarkup +@end lilypond + +If you want to have a text on the left end of a multi-measure rest, +attach the text to a zero-length skip note, i.e. + +@example + s1*0^"Allegro" + R1*4 +@end example + + +@cindex whole rests for a full measure + +@seealso + +Internals: @internalsref{MultiMeasureRestEvent}, +@internalsref{MultiMeasureTextEvent}, +@internalsref{MultiMeasureRestMusicGroup}, and +@internalsref{MultiMeasureRest}. + +The layout object @internalsref{MultiMeasureRestNumber} is for the +default number, and @internalsref{MultiMeasureRestText} for user +specified texts. + +@refbugs + +It is not possible to use fingerings (e.g. @code{R1-4}) to put numbers +over multi-measure rests. + +@cindex condensing rests + +There is no way to automatically condense multiple rests into a single +multimeasure rest. Multi measure rests do not take part in rest +collisions. + +Be careful when entering multimeasure rests followed by whole +notes. The following will enter two notes lasting four measures each: +@example + R1*4 cis cis +@end example +When @code{skipBars} is set, then the result will look OK, but the +bar numbering will be off. + +@node Automatic part combining +@subsection Automatic part combining +@cindex automatic part combining +@cindex part combiner + + +Automatic part combining is used to merge two parts of music onto a +staff. It is aimed 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 are identified and can be marked. + +@syntax + +The syntax for part combining is + +@example + \partcombine @var{musicexpr1} @var{musicexpr2} +@end example + +The music expressions will be interpreted as @internalsref{Voice} contexts. + +The following example demonstrates the basic functionality of the part +combiner: putting parts on one staff, and setting stem directions and +polyphony: + +@lilypond[verbatim,raggedright,fragment,relative=1] + \new Staff \partcombine + { + g a( b) r + } + { + g r4 r f + } +@end lilypond + +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,raggedright,fragment,relative=1] + \new Staff << + \set Staff.soloADue = ##f + \partcombine + { + g a( b) r + } + { + g r4 r f + } >> +@end lilypond + +@seealso + +Internals: @internalsref{PartCombineMusic}, +@internalsref{SoloOneEvent}, and +@internalsref{SoloTwoEvent}, and +@internalsref{UnisonoEvent}. + +@refbugs + +In @code{soloADue} mode, when the two voices play the same notes on and +off, the part combiner may typeset @code{a2} more than once in a +measure. + +@code{\partcombine} can not be inside @code{\times}. + +Internally, the @code{\partcombine} interprets both arguments as +@code{Voice}s named @code{one} and @code{two}, and then decides when +the parts can be combined. Consequently, if the arguments switch to +differently named @internalsref{Voice} contexts, then the events in +those will be ignored. + +@node Hiding staves +@subsection Hiding staves + +@cindex Frenched scores +@cindex Hiding staves + +In orchestral scores, staff lines that only have rests are usually +removed. This saves some space. This style is called `French Score'. +For @internalsref{Lyrics}, +@internalsref{ChordNames} and @internalsref{FiguredBass}, this is +switched on by default. When these line of these contexts turn out +empty after the line-breaking process, they are removed. + +For normal staves, a specialized @internalsref{Staff} context is +available, which does the same: staves containing nothing (or only +multi measure rests) are removed. The context definition is stored in +@code{\RemoveEmptyStaffContext} variable. Observe how the second staff +in this example disappears in the second line: + + +@lilypond[verbatim] +\score { + \notes \relative c' << + \new Staff { e4 f g a \break c1 } + \new Staff { c4 d e f \break R1 } + >> + \paper { + linewidth = 6.\cm + \translator { \RemoveEmptyStaffContext } + } +} +@end lilypond + +The first page shows all staffs in full. If they should be removed +from the first page too, set @code{remove-first} to false +in @internalsref{RemoveEmptyVerticalGroup}. + +Another application is making ossia sections, i.e. alternative +melodies on a separate piece of staff, with help of a Frenched +staff. See @inputfileref{input/test,ossia.ly} for an example. + + +@node Different editions from one source +@subsection Different editions from one source + +The @code{\tag} command marks music expressions with a name. These +tagged expressions can be filtered out later. With this mechanism it +is possible to make different versions of the same music source. + +In the following example, we see two versions of a piece of music, one +for the full score, and one with cue notes for the instrumental part: + +@example + c1 + \relative c' << + \tag #'part << + R1 \\ + @{ + \set fontSize = #-1 + c4_"cue" f2 g4 @} + >> + \tag #'score R1 + >> + c1 +@end example + +The same can be applied to articulations, texts, etc.: they are +made by prepending +@example + -\tag #@var{your-tag} +@end example +to an articulation, for example, +@example + c1-\tag #'part ^4 +@end example + +This defines a note with a conditional fingering indication. + +By applying the @code{remove-tag} function, tagged expressions can be +filtered. For example, +@example +\simultaneous @{ + @var{the music} + \apply #(remove-tag 'score) @var{the music} + \apply #(remove-tag 'part) @var{the music} +@} +@end example +would yield + +@lilypondfile[]{tag-filter.ly} + +The argument of the @code{\tag} command should be a symbol, or a list +of symbols, for example, +@example + \tag #'(original-part transposed-part) @dots{} +@end example + +@seealso + +Examples: @inputfileref{input/regression,tag-filter.ly}. + + +@node Quoting other voices +@subsection Quoting other voices + +With quotations, fragments of other parts can be inserted into a part +directly. Before a part can be quoted, it must be marked especially as +quotable. This is done with code @code{\addquote} command. The +quotation may then be done with @code{\quote} + +@example + \addquote @var{name} @var{music} + \quote @var{name} @var{duration} +@end example + +@noindent + +Here, @var{name} is an identifying string. The @var{music} is any kind +of music. This is an example of @code{\addquote}: + +@verbatim +\addquote clarinet \notes\relative c' { + f4 fis g gis +} +@end verbatim + +During a part, a piece of music can be quoted with the @code{\quote} +command. + +@verbatim + \quote clarinet 2. +@end verbatim + +This would cite 3 quarter notes (a dotted half note) of the previously +added clarinet voice. + +Quotations take into account the transposition both source and target +instruments, if they are specified using the @code{\transposition} command. + +@lilypond[verbatim,fragment] +\addquote clarinet \notes\relative c' { + \transposition bes + f4 fis g gis +} +\score { + \notes { + e'8 f'8 \quote clarinet 2 +} } +@end lilypond + +@refbugs + +Only the contents of the first @internalsref{Voice} occurring in an +@code{\addquote} command will be considered for quotation, so +@var{music} can not contain @code{\new} and @code{\context Voice} +statements that would switch to a different Voice. + + +@seealso + +In this manual: @ref{Instrument transpositions}. + +Examples: @inputfileref{input/regression,quote.ly} +@inputfileref{input/regression,quote-transposition.ly} + +Internals: @internalsref{QuoteMusic}. + +@node Ancient notation +@section Ancient notation + +@cindex Vaticana, Editio +@cindex Medicaea, Editio +@cindex hufnagel +@cindex Petrucci +@cindex mensural + +@c [TODO: write more comprehensive introduction on ancient notation] + +Support for ancient notation is still under heavy development. +Regardless of all of the current limitations (see the bugs section +below for details), it includes features for mensural +notation and Gregorian Chant notation. There is also limited support +for figured bass notation. + +Many graphical objects provide a @code{style} property, see +@ref{Ancient note heads}, @ref{Ancient accidentals}, @ref{Ancient +rests}, @ref{Ancient clefs}, @ref{Ancient flags} and @ref{Ancient time +signatures}. By manipulating such a grob property, the typographical +appearance of the affected graphical objects can be accommodated for a +specific notation flavor without need for introducing any new +notational concept. + + +Other aspects of ancient notation can not that easily be expressed as +in terms of just changing a style property of a graphical object. +Therefore, some notational concepts are introduced specifically for +ancient notation, see @ref{Custodes}, @ref{Divisiones}, +@ref{Ligatures}, and @ref{Figured bass}. + + +@menu +* Ancient note heads:: +* Ancient accidentals:: +* Ancient rests:: +* Ancient clefs:: +* Ancient flags:: +* Ancient time signatures:: +* Custodes:: +* Divisiones:: +* Ligatures:: +* Figured bass:: +* Vaticana style contexts:: +@end menu + +If this all is way too much of documentation for you, and you just +want to dive into typesetting without worrying too much about the +details on how to customize a context, then you may have a look at the +predefined contexts (see @ref{Vaticana style contexts}). Use them to +set up predefined style-specific voice and staff contexts, and +directly go ahead with the note entry. + +@refbugs + +Ligatures need special spacing that has not yet been implemented. As +a result, there is too much space between ligatures most of the time, +and line breaking often is unsatisfactory. Also, lyrics do not +correctly align with ligatures. + +Accidentals must not be printed within a ligature, but instead need to +be collected and printed in front of it. + +Augmentum dots within ligatures are not handled correctly. + + +@node Ancient note heads +@subsection Ancient note heads + +@cindex note heads + +@syntax + +For ancient notation, a note head style other than the @code{default} +style may be chosen. This is accomplished by setting the @code{style} +property of the NoteHead object to the desired value (@code{baroque}, +@code{neo_mensural} or @code{mensural}). The @code{baroque} style +differs from the @code{default} style only in using a square shape for +@code{\breve} note heads. The @code{neo_mensural} style differs from +the @code{baroque} style in that it uses rhomboidal heads for whole +notes and all smaller durations. Stems are centered on the note +heads. This style is in particular useful when transcribing mensural +music, e.g. for the incipit. The @code{mensural} style finally +produces note heads that mimic the look of note heads in historic +printings of the 16th century. + +The following example demonstrates the @code{neo_mensural} style: + +@lilypond[fragment,raggedright,verbatim] + \override NoteHead #'style = #'neo_mensural + a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 +@end lilypond + +When typesetting a piece in Gregorian Chant notation, a Gregorian +ligature engraver will automatically select the proper note heads, +such there is no need to explicitly set the note head style. Still, +the note head style can be set e.g. to @code{vaticana_punctum} to +produce punctum neumes. Similarly, a mensural ligature engraver is +used to automatically assemble mensural ligatures. See +@ref{Ligatures} for how ligature engravers work. + +@seealso + +In this manual: +@ref{Percussion staves} use note head styles of their own that are +frequently used in contemporary music notation. + +Examples: @inputfileref{input/regression,note-head-style.ly} gives an +overview over all available note head styles. + + +@node Ancient accidentals +@subsection Ancient accidentals + +@cindex accidentals + +@syntax + +Use the @code{style} property of grob @internalsref{Accidental} to +select ancient accidentals. Supported styles are +@code{mensural}, @code{vaticana}, @code{hufnagel} and @code{medicaea}. + +@lilypond[raggedright,staffsize=26] +\score { + \notes { + \fatText + s + ^\markup { + \column < + "vaticana" + { " " \musicglyph #"accidentals-vaticana-1" + " " \musicglyph #"accidentals-vaticana0" } + > + \column < + "medicaea" + { " " \musicglyph #"accidentals-medicaea-1" } + > + \column < + "hufnagel" + { " " \musicglyph #"accidentals-hufnagel-1" } + > + \column < + "mensural" + { " " \musicglyph #"accidentals-mensural-1" + " " \musicglyph #"accidentals-mensural1" } + > + } + } + \paper { + raggedright = ##t + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator{ + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \remove "Time_signature_engraver" + \remove "Staff_symbol_engraver" + minimumVerticalExtent = ##f + } + } +} +@end lilypond + +As shown, not all accidentals are supported by each style. When +trying to access an unsupported accidental, LilyPond will switch to a +different style, as demonstrated in +@inputfileref{input/test,ancient-accidentals.ly}. + +Similarly to local accidentals, the style of the key signature can be +controlled by the @code{style} property of the +@internalsref{KeySignature} grob. + +@seealso + +In this manual: @ref{Pitches}, @ref{Chromatic alterations} and +@ref{Accidentals} give a general introduction into the use of +accidentals. @ref{Key signature} gives a general introduction into +the use of key signatures. + +Internals: @internalsref{KeySignature}. + +Examples: @inputfileref{input/test,ancient-accidentals.ly}. + +@node Ancient rests +@subsection Ancient rests + +@cindex rests + +@syntax + +Use the @code{style} property of grob @internalsref{Rest} to select +ancient accidentals. Supported styles are @code{classical}, +@code{neo_mensural} and @code{mensural}. @code{classical} differs +from the @code{default} style only in that the quarter rest looks like +a horizontally mirrored 8th rest. The @code{neo_mensural} style suits +well for e.g. the incipit of a transcribed mensural piece of music. +The @code{mensural} style finally mimics the appearance of rests as +in historic prints of the 16th century. + +The following example demonstrates the @code{neo_mensural} style: + +@lilypond[fragment,raggedright,verbatim] + \override Rest #'style = #'neo_mensural + r\longa r\breve r1 r2 r4 r8 r16 +@end lilypond + +There are no 32th and 64th rests specifically for the mensural or +neo-mensural style. Instead, the rests from the default style will be +taken. See @inputfileref{input/test,rests.ly} for a chart of all +rests. + +There are no rests in Gregorian Chant notation; instead, it uses +@ref{Divisiones}. + +@seealso + +In this manual: @ref{Rests} gives a general introduction into the use of rests. + + +@node Ancient clefs +@subsection Ancient clefs + +@cindex clefs + +@syntax + +LilyPond supports a variety of clefs, many of them ancient. + +The following table shows all ancient clefs that are supported via the +@code{\clef} command. Some of the clefs use the same glyph, but +differ only with respect to the line they are printed on. In such +cases, a trailing number in the name is used to enumerate these clefs. +Still, you can manually force a clef glyph to be typeset on an +arbitrary line, as described in @ref{Clef}. The note printed to the +right side of each clef in the example column denotes the @code{c'} +with respect to that clef. + +@multitable @columnfractions .3 .3 .3 .1 + +@item +@b{Glyph Name} @tab +@b{Description} @tab +@b{Supported Clefs} @tab +@b{Example} + +@item +@code{clefs-neo_mensural_c} @tab +modern style mensural C clef @tab +@code{neo_mensural_c1}, @code{neo_mensural_c2}, +@code{neo_mensural_c3}, @code{neo_mensural_c4} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "neo_mensural_c2" c +@end lilypond + +@item +@code{clefs-petrucci_c1} +@code{clefs-petrucci_c2} +@code{clefs-petrucci_c3} +@code{clefs-petrucci_c4} +@code{clefs-petrucci_c5} + +@tab +petrucci style mensural C clefs, for use on different staff lines +(the examples shows the 2nd staff line C clef). + +@tab +@code{petrucci_c1} +@code{petrucci_c2} +@code{petrucci_c3} +@code{petrucci_c4} +@code{petrucci_c5} + +@tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "petrucci_c2" c +@end lilypond + +@item +@code{clefs-petrucci_f} @tab +petrucci style mensural F clef @tab +@code{petrucci_f} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "petrucci_f" c +@end lilypond + +@item +@code{clefs-petrucci_g} @tab +petrucci style mensural G clef @tab +@code{petrucci_g} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "petrucci_g" c +@end lilypond + +@item +@code{clefs-mensural_c} @tab +historic style mensural C clef @tab +@code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3}, +@code{mensural_c4} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "mensural_c2" c +@end lilypond + +@item +@code{clefs-mensural_f} @tab +historic style mensural F clef @tab +@code{mensural_f} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "mensural_f" c +@end lilypond + +@item +@code{clefs-mensural_g} @tab +historic style mensural G clef @tab +@code{mensural_g} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "mensural_g" c +@end lilypond + +@item +@code{clefs-vaticana_do} @tab +Editio Vaticana style do clef @tab +@code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3} @tab +@lilypond[relative,notime] + \override Staff.StaffSymbol #'line-count = #4 +\override Staff.TimeSignature #'transparent = ##t +\clef "vaticana_do2" c +@end lilypond + +@item +@code{clefs-vaticana_fa} @tab +Editio Vaticana style fa clef @tab +@code{vaticana_fa1}, @code{vaticana_fa2} @tab +@lilypond[relative,notime] + \override Staff.StaffSymbol #'line-count = #4 +\override Staff.TimeSignature #'transparent = ##t +\clef "vaticana_fa2" c +@end lilypond + +@item +@code{clefs-medicaea_do} @tab +Editio Medicaea style do clef @tab +@code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3} @tab +@lilypond[relative,notime] + \override Staff.StaffSymbol #'line-count = #4 +\override Staff.TimeSignature #'transparent = ##t +\clef "medicaea_do2" c +@end lilypond + +@item +@code{clefs-medicaea_fa} @tab +Editio Medicaea style fa clef @tab +@code{medicaea_fa1}, @code{medicaea_fa2} @tab +@lilypond[relative,notime] + \override Staff.StaffSymbol #'line-count = #4 +\override Staff.TimeSignature #'transparent = ##t +\clef "medicaea_fa2" c +@end lilypond + +@item +@code{clefs-hufnagel_do} @tab +historic style hufnagel do clef @tab +@code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3} @tab +@lilypond[relative,notime] + \override Staff.StaffSymbol #'line-count = #4 +\override Staff.TimeSignature #'transparent = ##t +\clef "hufnagel_do2" c +@end lilypond + +@item +@code{clefs-hufnagel_fa} @tab +historic style hufnagel fa clef @tab +@code{hufnagel_fa1}, @code{hufnagel_fa2} @tab +@lilypond[relative,notime] + \override Staff.StaffSymbol #'line-count = #4 +\override Staff.TimeSignature #'transparent = ##t +\clef "hufnagel_fa2" c +@end lilypond + +@item +@code{clefs-hufnagel_do_fa} @tab +historic style hufnagel combined do/fa clef @tab +@code{hufnagel_do_fa} @tab +@lilypond[relative,notime] +\override Staff.TimeSignature #'transparent = ##t +\clef "hufnagel_do_fa" c +@end lilypond + +@end multitable + +@c --- This should go somewhere else: --- +@c @item modern style percussion clef (glyph: @code{clefs-percussion}) +@c +@c Supported clefs: +@c @code{percussion} +@c +@c @lilypond{\override Staff.TimeSignature #'transparent = ##t \clef "percussion" c'} +@c +@c @item modern style tab clef (glyph: @code{clefs-tab}) +@c +@c Supported clefs: +@c @code{tab} +@c +@c @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #6 \override Staff.TimeSignature #'transparent = ##t \clef "tab" c'} + +@emph{Modern style} means ``as is typeset in contemporary editions of +transcribed mensural music''. + +@emph{Petrucci style} means ``inspired by printings published by the +famous engraver Petrucci (1466-1539)''. + +@emph{Historic style} means ``as was typeset or written in historic +editions (other than those of Petrucci)''. + +@emph{Editio XXX style} means ``as is/was printed in Editio XXX''. + +Petrucci used C clefs with differently balanced left-side vertical +beams, depending on which staff line it is printed. + +@seealso + +In this manual: for the percussion clef, see @ref{Percussion staves}. +For the @code{TAB} clef, see @ref{Tablatures}. + +Internals: for modern clefs, see @ref{Clef}. + +@refbugs + +The mensural g clef is temporarily mapped to the Petrucci g clef, +until a new mensural g clef will have been implemented. + + + +@node Ancient flags +@subsection Ancient flags + +@cindex flags + +@syntax + +Use the @code{flag-style} property of grob @internalsref{Stem} to +select ancient flags. Besides the @code{default} flag style, + only @code{mensural} style is supported: + +@lilypond[fragment,raggedright,verbatim] + \override Stem #'flag-style = #'mensural + \override Stem #'thickness = #1.0 + \override NoteHead #'style = #'mensural + \autoBeamOff + c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8 + c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32 +@end lilypond + +Note that the innermost flare of each mensural flag always is +vertically aligned with a staff line. If you do not like this +behavior, you can set the @code{adjust-if-on-staffline} property of +grob @internalsref{Stem} to @code{##f}. Then, the vertical position +of the end of each flare is different between notes on staff lines and +notes between staff lines: + +@lilypond[fragment,raggedright] + \override Stem #'flag-style = #'mensural + \override Stem #'thickness = #1.0 + \override Stem #'adjust-if-on-staffline = ##f + \override NoteHead #'style = #'mensural + \autoBeamOff + c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8 + c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32 +@end lilypond + +There is no particular flag style for neo-mensural notation. Hence, +when typesetting e.g. the incipit of a transcribed piece of mensural +music, the default flag style should be used. There are no flags in +Gregorian Chant notation. + + +@node Ancient time signatures +@subsection Ancient time signatures + +@cindex time signatures + +@syntax + +There is limited support for mensural time signatures. The +glyphs are hard-wired to particular time fractions. In other words, +to get a particular mensural signature glyph with the @code{\time n/m} +command, @code{n} and @code{m} have to be chosen according to the +following table: + +@lilypond +\score { + \notes { + \set Score.timing = ##f + \set Score.barAlways = ##t + s_\markup { "$\\backslash$time 4/4" } + ^\markup { " " \musicglyph #"timesig-neo_mensural4/4" } + s + s_\markup { "$\\backslash$time 2/2" } + ^\markup { " " \musicglyph #"timesig-neo_mensural2/2" } + s + s_\markup { "$\\backslash$time 6/4" } + ^\markup { " " \musicglyph #"timesig-neo_mensural6/4" } + s + s_\markup { "$\\backslash$time 6/8" } + ^\markup { " " \musicglyph #"timesig-neo_mensural6/8" } + \break + s_\markup { "$\\backslash$time 3/2" } + ^\markup { " " \musicglyph #"timesig-neo_mensural3/2" } + s + s_\markup { "$\\backslash$time 3/4" } + ^\markup { " " \musicglyph #"timesig-neo_mensural3/4" } + s + s_\markup { "$\\backslash$time 9/4" } + ^\markup { " " \musicglyph #"timesig-neo_mensural9/4" } + s + s_\markup { "$\\backslash$time 9/8" } + ^\markup { " " \musicglyph #"timesig-neo_mensural9/8" } + \break + s_\markup { "$\\backslash$time 4/8" } + ^\markup { " " \musicglyph #"timesig-neo_mensural4/8" } + s + s_\markup { "$\\backslash$time 2/4" } + ^\markup { " " \musicglyph #"timesig-neo_mensural2/4" } + \break + } + \paper { + indent = 0.0 + raggedright = ##t + \translator { + \StaffContext + \remove Staff_symbol_engraver + \remove Clef_engraver + \remove Time_signature_engraver + } + } +} +@end lilypond + +Use the @code{style} property of grob @internalsref{TimeSignature} to +select ancient time signatures. Supported styles are +@code{neo_mensural} and @code{mensural}. The above table uses the +@code{neo_mensural} style. This style is appropriate e.g. for the +incipit of transcriptions of mensural pieces. The @code{mensural} +style mimics the look of historical printings of the 16th century. + +@inputfileref{input/test,time.ly} gives an overview over all available +ancient and modern styles. + +@seealso + +Internals: @ref{Time signature} gives a general introduction into the use of time +signatures. + +@refbugs + +Mensural signature glyphs are mapped to time fractions in a +hard-wired way. This mapping is sensible, but still arbitrary: given +a mensural time signature, the time fraction represents a modern meter +that usually will be a good choice when transcribing a mensural piece +of music. For a particular piece of mensural music, however, the +mapping may be unsatisfactory. In particular, the mapping assumes a +fixed transcription of durations (e.g. brevis = half note in 2/2, +i.e. 4:1). Some glyphs (such as the alternate glyph for 6/8 meter) +are not at all accessible through the @code{\time} command. + +Mensural time signatures are supported typographically, but not yet +musically. The internal representation of durations is +based on a purely binary system; a ternary division such as 1 brevis = +3 semibrevis (tempus perfectum) or 1 semibrevis = 3 minima (cum +prolatione maiori) is not correctly handled: event times in ternary +modes will be badly computed, resulting e.g. in horizontally +misaligned note heads, and bar checks are likely to erroneously fail. + +The syntax and semantics of the @code{\time} command for mensural +music is subject to change. + +@node Custodes +@subsection Custodes + +@cindex custos +@cindex custodes + +A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a +symbol that appears at the end of a staff. 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. + +Custodes were frequently used in music notation until the 17th +century. Nowadays, they have survived only in a few particular forms +of musical notation such as contemporary editions of Gregorian chant +like the @emph{editio vaticana}. There are different custos glyphs +used in different flavors of notational style. + +@syntax + +For typesetting custodes, just put a @internalsref{Custos_engraver} into the +@internalsref{Staff} context when declaring the @code{\paper} block, +as shown in the following example: + +@example +\paper @{ + \translator @{ + \StaffContext + \consists Custos_engraver + Custos \override #'style = #'mensural + @} +@} +@end example + +The result looks like this: + +@lilypond +\score { + \notes { + a'1 + \override Staff.Custos #'style = #'mensural + \break + g' + } + \paper { + \translator { + \StaffContext + \consists Custos_engraver + } + linewidth = 4.0\cm + } +} +@end lilypond + +The custos glyph is selected by the @code{style} property. The styles +supported are @code{vaticana}, @code{medicaea}, @code{hufnagel} and +@code{mensural}. They are demonstrated in the following fragment: + +@lilypond +\score { + \notes { + \fatText + s + ^\markup { + \column < + "vaticana" + { " " \musicglyph #"custodes-vaticana-u0" } + > + \column < + "medicaea" + { " " \musicglyph #"custodes-medicaea-u0" } + > + \column < + "hufnagel" + { " " \musicglyph #"custodes-hufnagel-u0" } + > + \column < + "mensural" + { " " \musicglyph #"custodes-mensural-u0" } + > + } + } + \paper { + raggedright = ##t + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator{ + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \remove "Time_signature_engraver" + \remove "Staff_symbol_engraver" + minimumVerticalExtent = ##f + } + } +} +@end lilypond + +If the boolean property @code{adjust-if-on-staffline} is set to +@code{#t} (which it is by default), lily typesets slightly different +variants of the custos glyph, depending on whether the custos, is +typeset on or between staff lines. The glyph will +optically fit well into the staff, with the appendage on the right of +the custos always ending at the same vertical position between two +staff lines regardless of the pitch. If you set +@code{adjust-if-on-staffline} to @code{#f}, then +a compromise between both forms is used. + +Just like stems can be attached to note heads in two directions +@emph{up} and @emph{down}, each custos glyph is available with its +appendage pointing either up or down. If the pitch of a custos is +above a selectable position, the appendage will point downwards; if +the pitch is below this position, the appendage will point upwards. +Use property @code{neutral-position} to select this position. By +default, it is set to @code{0}, such that the neutral position is the +center of the staff. Use property @code{neutral-direction} to control +what happens if a custos is typeset on the neutral position itself. +By default, this property is set to @code{-1}, such that the appendage +will point downwards. If set to @code{1}, the appendage will point +upwards. Other values such as @code{0} are reserved for future +extensions and should not be used. + +@seealso + +Internals: @internalsref{Custos}. + +Examples: @inputfileref{input/regression,custos.ly}. + + +@node Divisiones +@subsection Divisiones + +@cindex divisio +@cindex divisiones +@cindex finalis + +A @emph{divisio} (plural: @emph{divisiones}; Latin word for +`division') is a staff context symbol that is used to structure +Gregorian music into phrases and sections. The musical meaning of +@emph{divisio minima}, @emph{divisio maior} and @emph{divisio maxima} +can be characterized as short, medium and long pause, somewhat like +@ref{Breath marks}. The @emph{finalis} sign not only marks the end of +a chant, but is also frequently used within a single +antiphonal/responsorial chant to mark the end of each section. + +@syntax + +To use divisiones, include the file @code{gregorian-init.ly}. It +contains definitions that you can apply by just inserting +@code{\divisioMinima}, @code{\divisioMaior}, @code{\divisioMaxima}, +and @code{\finalis} at proper places in the input. Some editions use +@emph{virgula} or @emph{caesura} instead of divisio minima. +Therefore, @code{gregorian-init.ly} also defines @code{\virgula} and +@code{\caesura}: + +@lilypondfile[]{divisiones.ly} + +@refcommands + +@cindex @code{\virgula} +@code{\virgula}, +@cindex @code{\caesura} +@code{\caesura}, +@cindex @code{\divisioMinima} +@code{\divisioMinima}, +@cindex @code{\divisioMaior} +@code{\divisioMaior}, +@cindex @code{\divisioMaxima} +@code{\divisioMaxima}, +@cindex @code{\finalis} +@code{\finalis}. + +@seealso + +In this manual: @ref{Breath marks}. + +Internals: @internalsref{BreathingSign}, @internalsref{BreathingSignEvent}. + +Examples: @inputfileref{input/test,divisiones.ly}. + +@node Ligatures +@subsection Ligatures + +@cindex Ligatures + +@c TODO: Should double check if I recalled things correctly when I wrote +@c down the following paragraph by heart. + +In musical terminology, a ligature is a coherent graphical symbol that +represents at least two distinct notes. Ligatures originally appeared +in the manuscripts of Gregorian chant notation roughly since the 9th +century as an allusion to the accent symbols of Greek lyric poetry to +denote ascending or descending sequences of notes. Both, the shape +and the exact meaning of ligatures changed tremendously during the +following centuries: In early notation, ligatures were used for +monophonic tunes (Gregorian chant) and very soon denoted also the way +of performance in the sense of articulation. With upcoming +multiphony, the need for a metric system arised, since multiple voices +of a piece have to be synchronized some way. New notation systems +were invented that used the manifold shapes of ligatures to now denote +rhythmical patterns (e.g. black mensural notation, mannered notation, +ars nova). With the invention of the metric system of the white +mensural notation, the need for ligatures to denote such patterns +disappeared. Nevertheless, ligatures were still in use in the +mensural system for a couple of decades until they finally disappeared +during the late 16th / early 17th century. Still, ligatures have +survived in contemporary editions of Gregorian chant such as the +Editio Vaticana from 1905/08. + +@syntax + +Syntactically, ligatures are simply enclosed by @code{\[} and +@code{\]}. Some ligature styles (such as Editio Vaticana) may need +additional input syntax specific for this particular type of ligature. +By default, the @internalsref{LigatureBracket} engraver just puts a +square bracket above the ligature: + +@lilypond[raggedright,verbatim] +\score { + \notes \transpose c c' { + \[ g c a f d' \] + a g f + \[ e f a g \] + } +} +@end lilypond + +To select a specific style of ligatures, a proper ligature engraver +has to be added to the @internalsref{Voice} context, as explained in +the following subsections. Only white mensural ligatures +are supported with certain limitations. Support for Editio Vaticana +will be added in the future. + +@menu +* White mensural ligatures:: +* Gregorian square neumes ligatures:: +@end menu + +@node White mensural ligatures +@subsubsection White mensural ligatures + +@cindex Mensural ligatures +@cindex White mensural ligatures + +There is limited support for white mensural ligatures. The +implementation is still experimental; it may output strange +warnings or even crash in some cases or produce weird results on more +complex ligatures. + +@syntax + +To engrave white mensural ligatures, in the paper block the +@internalsref{Mensural_ligature_engraver} has to be put into the +@internalsref{Voice} context, and remove the +@internalsref{Ligature_bracket_engraver}: + +@example + \paper @{ + \translator @{ + \VoiceContext + \remove Ligature_bracket_engraver + \consists Mensural_ligature_engraver + @} + @} +@end example + +There is no additional input language to describe the shape of a +white mensural ligature. The shape is rather determined solely from +the pitch and duration of the enclosed notes. While this approach may +take a new user a while to get accustomed, it has the great advantage +that the full musical information of the ligature is known internally. +This is not only required for correct MIDI output, but also allows for +automatic transcription of the ligatures. + +For example, + +@example + \set Score.timing = ##f + \set Score.defaultBarType = "empty" + \override NoteHead #'style = #'neo_mensural + \override Staff.TimeSignature #'style = #'neo_mensural + \clef "petrucci_g" + \[ g\longa c\breve a\breve f\breve d'\longa \] + s4 + \[ e1 f1 a\breve g\longa \] +@end example +@lilypond[raggedright] +\score { + \notes \transpose c c' { + \set Score.timing = ##f + \set Score.defaultBarType = "empty" + \override NoteHead #'style = #'neo_mensural + \override Staff.TimeSignature #'style = #'neo_mensural + \clef "petrucci_g" + \[ g\longa c\breve a\breve f\breve d'\longa \] + s4 + \[ e1 f1 a\breve g\longa \] + } + \paper { + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Mensural_ligature_engraver + } + } +} +@end lilypond + +Without replacing @internalsref{Ligature_bracket_engraver} with +@internalsref{Mensural_ligature_engraver}, the same music transcribes +to the following: + +@lilypond[raggedright] +\score { + \notes \transpose c c' { + \set Score.timing = ##f + \set Score.defaultBarType = "empty" + \override NoteHead #'style = #'neo_mensural + \override Staff.TimeSignature #'style = #'neo_mensural + \clef "petrucci_g" + \[ g\longa c\breve a\breve f\breve d'\longa \] + s4 + \[ e1 f1 a\breve g\longa \] + } +} +@end lilypond + + +@node Gregorian square neumes ligatures +@subsubsection Gregorian square neumes ligatures + +@cindex Square neumes ligatures +@cindex Gregorian square neumes ligatures + +Gregorian square neumes notation (following the style of the Editio +Vaticana) is under heavy development, but not yet really usable for +production purposes. Core ligatures can already be typeset, but +essential issues for serious typesetting are still under development, +such as (among others) horizontal alignment of multiple ligatures, +lyrics alignment and proper accidentals handling. Still, this section +gives a sneak preview of what Gregorian chant may look like once it +will work. + +The following table contains the extended neumes table of the 2nd +volume of the Antiphonale Romanum (@emph{Liber Hymnarius}), published +1983 by the monks of Solesmes. + +@multitable @columnfractions .4 .2 .2 .2 + +@item +@b{Neuma aut@*Neumarum Elementa} @tab +@b{Figurae@*Rectae} @tab +@b{Figurae@*Liquescentes Auctae} @tab +@b{Figurae@*Liquescentes Deminutae} + +@c TODO: \paper block is identical in all of the below examples. +@c Therefore, it should somehow be included rather than duplicated all +@c the time. --jr + +@c why not make identifiers in ly/engraver-init.ly? --hwn + +@c Because it's just used to typeset plain notes without +@c a staff for demonstration purposes rather than something +@c special of Gregorian chant notation. --jr + +@item +@code{1. Punctum} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.5\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Punctum + \[ b \] + \noBreak s^\markup {"a"} \noBreak + + % Punctum Inclinatum + \[ \inclinatum b \] + \noBreak s^\markup {"b"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=2.5\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Punctum Auctum Ascendens + \[ \auctum \ascendens b \] + \noBreak s^\markup {"c"} \noBreak + + % Punctum Auctum Descendens + \[ \auctum \descendens b \] + \noBreak s^\markup {"d"} \noBreak + + % Punctum Inclinatum Auctum + \[ \inclinatum \auctum b \] + \noBreak s^\markup {"e"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Punctum Inclinatum Parvum + \[ \inclinatum \deminutum b \] + \noBreak s^\markup {"f"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{2. Virga} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Virga + \[ \virga b \] + \noBreak s^\markup {"g"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@tab + +@item +@code{3. Apostropha vel Stropha} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Stropha + \[ \stropha b \] + \noBreak s^\markup {"h"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Stropha Aucta + \[ \stropha \auctum b \] + \noBreak s^\markup {"i"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab + +@item +@code{4. Oriscus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Oriscus + \[ \oriscus b \] + \noBreak s^\markup {"j"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@tab + +@item +@code{5. Clivis vel Flexa} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Clivis vel Flexa + \[ b \flexa g \] + s^\markup {"k"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=2.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Clivis Aucta Descendens + \[ b \flexa \auctum \descendens g \] + \noBreak s^\markup {"l"} \noBreak + + % Clivis Aucta Ascendens + \[ b \flexa \auctum \ascendens g \] + \noBreak s^\markup {"m"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Cephalicus + \[ b \flexa \deminutum g \] + s^\markup {"n"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{6. Podatus vel Pes} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Podatus vel Pes + \[ g \pes b \] + s^\markup {"o"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=2.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Pes Auctus Descendens + \[ g \pes \auctum \descendens b \] + \noBreak s^\markup {"p"} \noBreak + + % Pes Auctus Ascendens + \[ g \pes \auctum \ascendens b \] + \noBreak s^\markup {"q"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Epiphonus + \[ g \pes \deminutum b \] + s^\markup {"r"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{7. Pes Quassus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Pes Quassus + \[ \oriscus g \pes \virga b \] + s^\markup {"s"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Pes Quassus Auctus Descendens + \[ \oriscus g \pes \auctum \descendens b \] + s^\markup {"t"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab + +@item +@code{8. Quilisma Pes} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Quilisma Pes + \[ \quilisma g \pes b \] + s^\markup {"u"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Quilisma Pes Auctus Descendens + \[ \quilisma g \pes \auctum \descendens b \] + s^\markup {"v"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab + +@item +@code{9. Podatus Initio Debilis} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Pes Initio Debilis + \[ \deminutum g \pes b \] + s^\markup {"w"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Pes Auctus Descendens Initio Debilis + \[ \deminutum g \pes \auctum \descendens b \] + s^\markup {"x"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab + +@item +@code{10. Torculus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Torculus + \[ a \pes b \flexa g \] + s^\markup {"y"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Torculus Auctus Descendens + \[ a \pes b \flexa \auctum \descendens g \] + s^\markup {"z"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Torculus Deminutus + \[ a \pes b \flexa \deminutum g \] + s^\markup {"A"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{11. Torculus Initio Debilis} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Torculus Initio Debilis + \[ \deminutum a \pes b \flexa g \] + s^\markup {"B"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Torculus Auctus Descendens Initio Debilis + \[ \deminutum a \pes b \flexa \auctum \descendens g \] + s^\markup {"C"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Torculus Deminutus Initio Debilis + \[ \deminutum a \pes b \flexa \deminutum g \] + s^\markup {"D"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{12. Porrectus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Porrectus + \[ a \flexa g \pes b \] + s^\markup {"E"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Porrectus Auctus Descendens + \[ a \flexa g \pes \auctum \descendens b \] + s^\markup {"F"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Porrectus Deminutus + \[ a \flexa g \pes \deminutum b \] + s^\markup {"G"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{13. Climacus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Climacus + \[ \virga b \inclinatum a \inclinatum g \] + s^\markup {"H"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Climacus Auctus + \[ \virga b \inclinatum a \inclinatum \auctum g \] + s^\markup {"I"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Climacus Deminutus + \[ \virga b \inclinatum a \inclinatum \deminutum g \] + s^\markup {"J"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{14. Scandicus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Scandicus + \[ g \pes a \virga b \] + s^\markup {"K"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Scandicus Auctus Descendens + \[ g \pes a \pes \auctum \descendens b \] + s^\markup {"L"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Scandicus Deminutus + \[ g \pes a \pes \deminutum b \] + s^\markup {"M"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond + +@item +@code{15. Salicus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Salicus + \[ g \oriscus a \pes \virga b \] + s^\markup {"N"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Salicus Auctus Descendens + \[ g \oriscus a \pes \auctum \descendens b \] + s^\markup {"O"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab + +@item +@code{16. Trigonus} +@tab +@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] +\include "gregorian-init.ly" +\score { + \notes \transpose c c' { + % Trigonus + \[ \stropha b \stropha b \stropha a \] + s^\markup {"P"} + } + \paper { + interscoreline = 1 + \translator { + \ScoreContext + \remove "Bar_number_engraver" + } + \translator { + \StaffContext + \remove "Clef_engraver" + \remove "Key_engraver" + \override StaffSymbol #'transparent = ##t + \remove "Time_signature_engraver" + \remove "Bar_engraver" + minimumVerticalExtent = ##f + } + \translator { + \VoiceContext + \remove Ligature_bracket_engraver + \consists Vaticana_ligature_engraver + \override NoteHead #'style = #'vaticana_punctum + \override Stem #'transparent = ##t + } + } +} +@end lilypond +@tab +@tab + +@end multitable + +@syntax + +Unlike most other neumes notation systems, the input language for +neumes does not necessarily reflect directly the typographical +appearance, but is designed to solely focuse on musical meaning. For +example, @code{\[ a \pes b \flexa g \]} produces a Torculus consisting +of three Punctum heads, while @code{\[ a \flexa g \pes b \]} produces +a Porrectus with a curved flexa shape and only a single Punctum head. +There is no command to explicitly typeset the curved flexa shape; the +decision of when to typeset a curved flexa shape is purely taken from +the musical input. The idea of this approach is to separate the +musical aspects of the input from the notation style of the output. +This way, the same input can be reused to typeset the same music in a +different style of Gregorian chant notation such as Hufnagel (also +known as German gothic neumes) or Medicaea (kind of a very simple +forerunner of the Editio Vaticana). As soon as Hufnagel ligature +engraver and Medicaea ligature engraver will have been implemented, it +will be as simple as replacing the ligature engraver in the +@internalsref{Voice} context to get the desired notation style from +the same input. + +The following table shows the code fragments that produce the +ligatures in the above neumes table. The letter in the first column +in each line of the below table indicates to which ligature in the +above table it refers. The second column gives the name of the +ligature. The third column shows the code fragment that produces this +ligature, using @code{g}, @code{a} and @code{b} as example pitches. + +@multitable @columnfractions .1 .4 .5 + +@item +@b{#} @tab +@b{Name} @tab +@b{Input Language} + +@item +a @tab +Punctum @tab +@code{\[ b \]} + +@item +b @tab +Punctum Inclinatum @tab +@code{\[ \inclinatum b \]} + +@item +c @tab +Punctum Auctum Ascendens @tab +@code{\[ \auctum \ascendens b \]} + +@item +d @tab +Punctum Auctum Descendens @tab +@code{\[ \auctum \descendens b \]} + +@item +e @tab +Punctum Inclinatum Auctum @tab +@code{\[ \inclinatum \auctum b \]} + +@item +f @tab +Punctum Inclinatum Parvum @tab +@code{\[ \inclinatum \deminutum b \]} + +@item +g @tab +Virga @tab +@code{\[ \virga b \]} + +@item +h @tab +Stropha @tab +@code{\[ \stropha b \]} + +@item +i @tab +Stropha Aucta @tab +@code{\[ \stropha \auctum b \]} + +@item +j @tab +Oriscus @tab +@code{\[ \oriscus b \]} + +@item +k @tab +Clivis vel Flexa @tab +@code{\[ b \flexa g \]} + +@item +l @tab +Clivis Aucta Descendens @tab +@code{\[ b \flexa \auctum \descendens g \]} + +@item +m @tab +Clivis Aucta Ascendens @tab +@code{\[ b \flexa \auctum \ascendens g \]} + +@item +n @tab +Cephalicus @tab +@code{\[ b \flexa \deminutum g \]} + +@item +o @tab +Podatus vel Pes @tab +@code{\[ g \pes b \]} + +@item +p @tab +Pes Auctus Descendens @tab +@code{\[ g \pes \auctum \descendens b \]} + +@item +q @tab +Pes Auctus Ascendens @tab +@code{\[ g \pes \auctum \ascendens b \]} + +@item +r @tab +Epiphonus @tab +@code{\[ g \pes \deminutum b \]} + +@item +s @tab +Pes Quassus @tab +@code{\[ \oriscus g \pes \virga b \]} + +@item +t @tab +Pes Quassus Auctus Descendens @tab +@code{\[ \oriscus g \pes \auctum \descendens b \]} + +@item +u @tab +Quilisma Pes @tab +@code{\[ \quilisma g \pes b \]} + +@item +v @tab +Quilisma Pes Auctus Descendens @tab +@code{\[ \quilisma g \pes \auctum \descendens b \]} + +@item +w @tab +Pes Initio Debilis @tab +@code{\[ \deminutum g \pes b \]} + +@item +x @tab +Pes Auctus Descendens Initio Debilis @tab +@code{\[ \deminutum g \pes \auctum \descendens b \]} + +@item +y @tab +Torculus @tab +@code{\[ a \pes b \flexa g \]} + +@item +z @tab +Torculus Auctus Descendens @tab +@code{\[ a \pes b \flexa \auctum \descendens g \]} + +@item +A @tab +Torculus Deminutus @tab +@code{\[ a \pes b \flexa \deminutum g \]} + +@item +B @tab +Torculus Initio Debilis @tab +@code{\[ \deminutum a \pes b \flexa g \]} + +@item +C @tab +Torculus Auctus Descendens Initio Debilis @tab +@code{\[ \deminutum a \pes b \flexa \auctum \descendens g \]} + +@item +D @tab +Torculus Deminutus Initio Debilis @tab +@code{\[ \deminutum a \pes b \flexa \deminutum g \]} + +@item +E @tab +Porrectus @tab +@code{\[ a \flexa g \pes b \]} + +@item +F @tab +Porrectus Auctus Descendens @tab +@code{\[ a \flexa g \pes \auctum \descendens b \]} + +@item +G @tab +Porrectus Deminutus @tab +@code{\[ a \flexa g \pes \deminutum b \]} + +@item +H @tab +Climacus @tab +@code{\[ \virga b \inclinatum a \inclinatum g \]} + +@item +I @tab +Climacus Auctus @tab +@code{\[ \virga b \inclinatum a \inclinatum \auctum g \]} + +@item +J @tab +Climacus Deminutus @tab +@code{\[ \virga b \inclinatum a \inclinatum \deminutum g \]} + +@item +K @tab +Scandicus @tab +@code{\[ g \pes a \virga b \]} + +@item +L @tab +Scandicus Auctus Descendens @tab +@code{\[ g \pes a \pes \auctum \descendens b \]} + +@item +M @tab +Scandicus Deminutus @tab +@code{\[ g \pes a \pes \deminutum b \]} + +@item +N @tab +Salicus @tab +@code{\[ g \oriscus a \pes \virga b \]} + +@item +O @tab +Salicus Auctus Descendens @tab +@code{\[ g \oriscus a \pes \auctum \descendens b \]} + +@item +P @tab +Trigonus @tab +@code{\[ \stropha b \stropha b \stropha a \]} + +@end multitable + +@refcommands + +The following head prefixes are supported: + +@cindex @code{\virga} +@code{\virga}, +@cindex @code{\stropha} +@code{\stropha}, +@cindex @code{\inclinatum} +@code{\inclinatum}, +@cindex @code{\auctum} +@code{\auctum}, +@cindex @code{\descendens} +@code{\descendens}, +@cindex @code{\ascendens} +@code{\ascendens}, +@cindex @code{\oriscus} +@code{\oriscus}, +@cindex @code{\quilisma} +@code{\quilisma}, +@cindex @code{\deminutum} +@code{\deminutum}. + +Head prefixes can be accumulated, though restrictions apply. For +example, either @code{\descendens} or @code{\ascendens} can be applied +to a head, but not both to the same head. + +@cindex @code{\pes} +@cindex @code{\flexa} +Two adjacent heads can be tied together with the @code{\pes} and +@code{\flexa} infix commands for a rising and falling line of melody, +respectively. + +@refbugs + +Trigonus: apply equal spacing, regardless of pitch. + +@node Figured bass +@subsection Figured bass + +@cindex Basso continuo + +@c TODO: musicological blurb about FB + +@syntax + +LilyPond has limited support for figured bass: + +@lilypond[verbatim,fragment] +<< + \context Voice \notes { \clef bass dis4 c d ais} + \context FiguredBass + \figures { + < 6 >4 < 7 >8 < 6+ [_!] > + < 6 >4 <6 5 [3+] > + } + >> +@end lilypond + +The support for figured bass consists of two parts: there is an input +mode, introduced by @code{\figures}, where you can enter bass figures +as numbers, and there is a context called @internalsref{FiguredBass} that +takes care of making @internalsref{BassFigure} objects. + +In figures input mode, a group of bass figures is delimited by +@code{<} and @code{>}. The duration is entered after the @code{>>}: +@example + <4 6> +@end example +@lilypond[fragment] +\context FiguredBass +\figures { <4 6> } +@end lilypond + +Accidentals are added when you append @code{-}, @code{!} and @code{+} +to the numbers: + +@example + <4- 6+ 7!> +@end example +@lilypond[fragment] + \context FiguredBass + \figures { <4- 6+ 7!> } +@end lilypond + +Spaces or dashes may be inserted by using @code{_}. Brackets are +introduced with @code{[} and @code{]}: + +@example + < [4 6] 8 [_! 12]> +@end example +@lilypond[fragment] + \context FiguredBass +\figures { < [4 6] 8 [_! 12]> } +@end lilypond + +Although the support for figured bass may superficially resemble chord +support, it works much simpler. The @code{\figures} mode simply +stores the numbers , and @internalsref{FiguredBass} context prints +them as entered. There is no conversion to pitches, and no +realizations of the bass are played in the MIDI file. + +Internally, the code produces markup texts. You can use any of the +markup text properties to override formatting. For example, the +vertical spacing of the figures may be set with @code{baseline-skip}. + +@seealso + +Internals: @internalsref{BassFigureEvent} music, @internalsref{BassFigure} object, +and @internalsref{FiguredBass} context. + +@refbugs + +Slash notation for alterations is not supported. + + +@node Vaticana style contexts +@subsection Vaticana style contexts + +@cindex VaticanaVoiceContext +@cindex VaticanaStaffContext + +The predefined @code{VaticanaVoiceContext} and +@code{VaticanaStaffContext} can be used to easily engrave a piece of +Gregorian Chant in the style of the Editio Vaticana. These contexts +initialize all relevant context properties and grob properties to +proper values. With these contexts, you can immediately go ahead +entering the chant, as the following short excerpt demonstrates: + +@lilypond[raggedright,verbatim,noindent] +\include "gregorian-init.ly" +\score { +<< + \context VaticanaVoice = "cantus" { + \override Score.BarNumber #'transparent = ##t + \notes { + \[ c'\melisma c' \flexa a \] \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima + \[ f\melisma \pes a c' c' \pes d'\melismaEnd \] c' \divisioMinima \break + \[ c'\melisma c' \flexa a \] \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima + } + } + \lyricsto "cantus" \new Lyrics \lyrics { + San- ctus, San- ctus, San- ctus + } >> + +} +@end lilypond + + +@node Contemporary notation +@section Contemporary notation + +In the 20th century, composers have greatly expanded the musical +vocabulary. With this expansion, many innovations in musical notation +have been tried. The book by Stone (1980) gives a comprehensive +overview (see @ref{Literature list}). In general, the use of new, +innovative notation makes a piece harder to understand and perform and +its use should therefore be avoided if possible. For this reason, +support for contemporary notation in LilyPond is limited. + + +@menu +* Clusters:: +* Fermatas:: +@end menu + +@node Clusters +@subsection Clusters + +@cindex cluster + +In musical terminology, a @emph{cluster} denotes a range of +simultaneously sounding pitches that may change over time. The set of +available pitches to apply usually depends on the acoustic source. +Thus, in piano music, a cluster typically consists of a continuous range +of the semitones as provided by the piano's fixed set of a chromatic +scale. In choral music, each singer of the choir typically may sing an +arbitrary pitch within the cluster's range that is not bound to any +diatonic, chromatic or other scale. In electronic music, a cluster +(theoretically) may even cover a continuous range of pitches, thus +resulting in colored noise, such as pink noise. + +Clusters can be denoted in the context of ordinary staff notation by +engraving simple geometrical shapes that replace ordinary notation of +notes. Ordinary notes as musical events specify starting time and +duration of pitches; however, the duration of a note is expressed by the +shape of the note head rather than by the horizontal graphical extent of +the note symbol. In contrast, the shape of a cluster geometrically +describes the development of a range of pitches (vertical extent) over +time (horizontal extent). Still, the geometrical shape of a cluster +covers the area in which any single pitch contained in the cluster would +be notated as an ordinary note. From this point of view, it is +reasonable to specify a cluster as the envelope of a set of notes. + +@syntax + +A cluster is engraved as the envelope of a set of +cluster-notes. Cluster notes are created by applying the function +@code{notes-to-clusters} to a sequence of chords, e.g. +@c +@lilypond[relative=1,verbatim] + \apply #notes-to-clusters { } +@end lilypond + +The following example (from +@inputfileref{input/regression,cluster.ly}) shows what the result +looks like: + +@lilypondfile[]{cluster.ly} + +By default, @internalsref{Cluster_spanner_engraver} is in the +@internalsref{Voice} context. This allows putting ordinary notes and +clusters together in the same staff, even simultaneously. In such a +case no attempt is made to automatically avoid collisions between +ordinary notes and clusters. + +@seealso + +Internals: @internalsref{ClusterSpanner}, +@internalsref{ClusterSpannerBeacon}, +@internalsref{Cluster_spanner_engraver}, and +@internalsref{ClusterNoteEvent}. + +Examples: @inputfileref{input/regression,cluster.ly}. + +@refbugs + +Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed +accurately. Use @code{8 8} instead. + + + +@node Fermatas +@subsection Fermatas + +@cindex fermatas + + + +Contemporary music notation frequently uses special fermata symbols to +indicate fermatas of differing lengths. + +@syntax + +The following are supported + +@lilypond[raggedright] +\score { + << \addlyrics \notes { + b' + ^\shortfermata + _\shortfermata + r + b' + ^\fermata + _\fermata + + r + b' + ^\longfermata + _\longfermata + + r + b' + ^\verylongfermata + _\verylongfermata + r + } + \context Lyrics \lyrics { + "shortfermata" "fermata" "longfermata" "verylongfermata" + } >> +} +@end lilypond + +See @ref{Articulations} for general instructions how to apply scripts +such as fermatas to a @code{\notes@{@}} block. + + +@node Special notation +@section Special notation + +@menu +* Balloon help:: +* Easy Notation note heads:: +@end menu + +@node Balloon help +@subsection Balloon help + +Elements of notation can be marked and named with the help of a square +balloon. The primary purpose of this feature is to explain notation. + +The following example demonstrates its use. + +@lilypond[verbatim,fragment,raggedright,relative=1] + \context Voice + \applyoutput + #(add-balloon-text 'NoteHead "heads, or tails?" + '(1 . -3)) + c8 +@end lilypond + +@noindent +The function @code{add-balloon-text} takes the name of a grob, the +label to print and where to put the label relative to the object. In +the above example, the text ``heads or tails?'' ends 3 spaces below +the `balloon.' + +@cindex balloon +@cindex notation, explaining + +@seealso + +Internals: @internalsref{text-balloon-interface}. + +Examples: @inputfileref{input/regression,balloon.ly}. + +@node Easy Notation note heads +@subsection Easy Notation note heads + +@cindex easy notation +@cindex Hal Leonard + +The `easy play' note head includes a note name inside the head. It is +used in music aimed at beginners: + +@lilypond[raggedright,verbatim,staffsize=26] +\score { + \notes { c'2 e'4 f' | g'1 } + \paper { \translator { \EasyNotation } } +} +@end lilypond + +The @code{EasyNotation} variable overrides a @internalsref{Score} @c +context. To make the letters readable, it has to be printed in a +large font size. To print with a larger font, see @ref{Font Size}. + +@cindex Xdvi +@cindex ghostscript + +If you view the result with Xdvi, then staff lines may show through +the letters. Printing the PostScript file obtained does produce the +correct result. + + +@node Sound +@section Sound +@cindex Sound + +Entered music can also be converted to MIDI output. The performance +is good enough for proof-hearing the music for errors. + +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 volume vary linearly between +their two extremities. The fractions can be adjusted by +@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context. +For each type of MIDI instrument, a volume range can be defined. This +gives a basic equalizer control, which can enhance the quality of +the MIDI output remarkably. The equalizer can be controlled by +setting @code{instrumentEqualizer}. + +@refbugs + +Many musically interesting effects, such as swing, articulation, +slurring, etc., are not translated to MIDI. + +The MIDI output allocates a channel for each Staff, and one for global +settings. Hence, the MIDI file should not have more than 15 staves +(or 14 if you do not use drums). + + +@menu +* MIDI block:: +* MIDI instrument names:: +@end menu + + +@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, and + @item context definitions. +@end itemize + +Assignments in the @code{\midi} block are not allowed. + +A number followed by a period is interpreted as a real number, so +for setting the tempo for dotted notes, an extra space should be +inserted, for example: + +@example + \midi @{ \tempo 4 . = 120 @} +@end example + + +@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-init.ly}. + + +@node MIDI instrument names +@subsection MIDI instrument names + +@cindex instrument names +@cindex @code{Staff.midiInstrument} + +The MIDI instrument name is set by the @code{Staff.midiInstrument} +property. The instrument name should be chosen from the list in +@ref{MIDI instruments}. + +@refbugs + +If the selected string does not exactly match, then the default is +used, which is the Grand Piano. diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely new file mode 100644 index 0000000000..ff923a66c6 --- /dev/null +++ b/Documentation/user/programming-interface.itely @@ -0,0 +1,510 @@ +@node Interfaces for programmers +@appendix Interfaces for programmers + + + +@menu +* Programmer interfaces for input :: +* Markup programmer interface:: +* Contexts for programmers:: +@end menu + +@node Programmer interfaces for input +@appendixsec Programmer interfaces for input + +@menu +* Input variables and Scheme:: +* Internal music representation:: +* Manipulating music expressions:: +@end menu + +@node Input variables and Scheme +@appendixsubsec Input variables and Scheme + + +The input format supports the notion of variable: in the following +example, a music expression is assigned to a variable with the name +@code{traLaLa}. +@example + traLaLa = \notes @{ c'4 d'4 @} +@end example + +@noindent + +There is also a form of scoping: in the following example, the +@code{\paper} block also contains a @code{traLaLa} variable, which is +independent of the outer @code{\traLaLa}. +@example + traLaLa = \notes @{ c'4 d'4 @} + \paper @{ traLaLa = 1.0 @} +@end example +@c +In effect, each input file is a scope, and all @code{\header}, +@code{\midi} and @code{\paper} blocks are scopes nested inside that +toplevel scope. + +Both variables and scoping are implemented in the GUILE module system. +An anonymous Scheme module is attached to each scope. An assignment of +the form +@example + traLaLa = \notes @{ c'4 d'4 @} +@end example + +@noindent +is internally converted to a Scheme definition +@example + (define traLaLa @var{Scheme value of ``@code{\notes ... }''}) +@end example + +This means that input variables and Scheme variables may be freely +mixed. In the following example, a music fragment is stored in the +variable @code{traLaLa}, and duplicated using Scheme. The result is +imported in a @code{\score} by means of a second variable +@code{twice}: +@example + traLaLa = \notes @{ c'4 d'4 @} + + #(define newLa (map ly:music-deep-copy + (list traLaLa traLaLa))) + #(define twice + (make-sequential-music newLa)) + + \score @{ \twice @} +@end example + +In the above example, music expressions can be `exported' from the +input to the Scheme interpreter. The opposite is also possible. By +wrapping a Scheme value in the function @code{ly:export}, a Scheme +value is interpreted as if it were entered in LilyPond syntax: instead +of defining @code{\twice}, the example above could also have been +written as +@example + @dots{} + \score @{ #(ly:export (make-sequential-music newLa)) @} +@end example + + +@node Internal music representation +@appendixsubsec Internal music representation + +When a music expression is parsed, it is converted into a set of +Scheme music objects. The defining property of a music object is that +it takes up time. Time is a rational number that measures the length +of a piece of music, in whole notes. + +A music object has three kinds of types: +@itemize @bullet +@item + music name: Each music expression has a name, for example, a note +leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to +a @internalsref{SimultaneousMusic}. A list of all expressions +available is in the internals manual, under @internalsref{Music +expressions}. + +@item + `type' or interface: Each music name has several `types' or interface, + for example, a note is an @code{event}, but it is also a @code{note-event}, + a @code{rhythmic-event} and a @code{melodic-event}. + + All classes of music are listed in the internals manual, under + @internalsref{Music classes}. +@item +C++ object: Each music object is represented by a C++ object. For technical +reasons, different music objects may be represented by different C++ +object types. For example, a note is @code{Event} object, while +@code{\grace} creates a @code{Grace_music} object. + +We expect that distinctions between different C++ types will disappear +in the future. +@end itemize + +The actual information of a music expression is stored in properties. +For example, a @internalsref{NoteEvent} has @code{pitch} and +@code{duration} properties that store the pitch and duration of that +note. A list of all properties available is in the internals manual, +under @internalsref{Music properties}. + +A compound music expression is a music object that contains other +music objects in its properties. A list of objects can be stored in +the @code{elements} property of a music object, or a single `child' +music object in the @code{element} object. For example, +@internalsref{SequentialMusic} has its children in @code{elements}, +and @internalsref{GraceMusic} has its single argument in +@code{element}. The body of a repeat is in @code{element} property of +@internalsref{RepeatedMusic}, and the alternatives in @code{elements}. + +@node Manipulating music expressions +@appendixsubsec Manipulating music expressions + +Music objects and their properties can be accessed and manipulated +directly, through the @code{\apply} mechanism. +The syntax for @code{\apply} is +@example +\apply #@var{func} @var{music} +@end example + +@noindent +This means that the scheme function @var{func} is called with +@var{music} as its argument. The return value of @var{func} is the +result of the entire expression. @var{func} may read and write music +properties using the functions @code{ly:music-property} and +@code{ly:music-set-property!}. + +An example is a function that reverses the order of elements in +its argument: +@lilypond[verbatim,raggedright] + #(define (rev-music-1 m) + (ly:music-set-property! m 'elements (reverse + (ly:music-property m 'elements))) + m) + \score { \notes \apply #rev-music-1 { c4 d4 } } +@end lilypond + +The use of such a function is very limited. The effect of this +function is void when applied to an argument which is does not have +multiple children. The following function application has no effect: + +@example + \apply #rev-music-1 \grace @{ c4 d4 @} +@end example + +@noindent +In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no +@code{elements}, only a single @code{element}. Every generally +applicable function for @code{\apply} must -- like music expressions +themselves -- be recursive. + +The following example is such a recursive function: It first extracts +the @code{elements} of an expression, reverses them and puts them +back. Then it recurses, both on @code{elements} and @code{element} +children. +@example +#(define (reverse-music music) + (let* ((elements (ly:music-property music 'elements)) + (child (ly:music-property music 'element)) + (reversed (reverse elements))) + + ; set children + (ly:music-set-property! music 'elements reversed) + + ; recurse + (if (ly:music? child) (reverse-music child)) + (map reverse-music reversed) + + music)) +@end example + +A slightly more elaborate example is in +@inputfileref{input/test,reverse-music.ly}. + +Some of the input syntax is also implemented as recursive music +functions. For example, the syntax for polyphony +@example + <> +@end example + +@noindent +is actually implemented as a recursive function that replaces the +above by the internal equivalent of +@example + << \context Voice = "1" @{ \voiceOne a @} + \context Voice = "2" @{ \voiceTwo b @} >> +@end example + +Other applications of @code{\apply} are writing out repeats +automatically (@inputfileref{input/test,unfold-all-repeats.ly}), +saving keystrokes (@inputfileref{input/test,music-box.ly}) and +exporting +LilyPond input to other formats (@inputfileref{input/test,to-xml.ly}) + +@seealso + +@file{scm/music-functions.scm}, @file{scm/music-types.scm}, +@inputfileref{input/test,add-staccato.ly}, +@inputfileref{input/test,unfold-all-repeats.ly}, and +@inputfileref{input/test,music-box.ly}. + + + +@node Markup programmer interface +@appendixsec Markup programmer interface + + +@menu +* Markup construction in scheme:: +* Markup command definition:: +@end menu + +@node Markup construction in scheme +@appendixsubsec Markup construction in scheme + +@cindex defining markup commands + +The @code{markup} macro builds markup expressions in Scheme while +providing a LilyPond-like syntax. For example, +@example +(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world") + #:bigger #:line ("foo" "bar" "baz"))) +@end example + +@noindent +is equivalent to: +@example +\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @} + \bigger @{ foo bar baz @} > +@end example + +@noindent +This example exposes the main translation rules between regular +LilyPond markup syntax and scheme markup syntax, which are summed up +is this table: +@multitable @columnfractions .5 .5 +@item @b{LilyPond} @tab @b{Scheme} +@item @code{\command} @tab @code{#:command} +@item @code{\variable} @tab @code{variable} +@item @code{@{ ... @}} @tab @code{#:line ( ... )} +@item @code{\center-align < ... >} @tab @code{#:center ( ... )} +@item @code{string} @tab @code{"string"} +@item @code{#scheme-arg} @tab @code{scheme-arg} +@end multitable + +Besides, the whole scheme language is accessible inside the +@code{markup} macro: thus, one may use function calls inside +@code{markup} in order to manipulate character strings for +instance. This proves useful when defining new markup commands (see +@ref{Markup command definition}). + +@refbugs + +One can not feed the @code{#:line} (resp @code{#:center}, +@code{#:column}) command with a variable or the result of a function +call. Eg: +@lisp +(markup #:line (fun-that-returns-markups)) +@end lisp +is illegal. One should use the @code{make-line-markup} (resp +@code{make-center-markup}, @code{make-column-markup}) function +instead: +@lisp +(markup (make-line-markup (fun-that-returns-markups))) +@end lisp + +@node Markup command definition +@appendixsubsec Markup command definition + +New markup commands can be defined thanks to the @code{def-markup-command} scheme macro. +@lisp +(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...) + (@var{arg1-type?} @var{arg2-type?} ...) + ..command body..) + + @var{argi}: i@var{th} command argument + @var{argi-type?}: a type predicate for the i@var{th} argument + @var{paper}: the `paper' definition + @var{props}: a list of alists, containing all active properties. +@end lisp + +As a simple example, we show how to add a @code{\smallcaps} command, +which selects @TeX{}'s small caps font. Normally, we could select the +small caps font as follows: + +@verbatim + \markup { \override #'(font-shape . caps) Text-in-caps } +@end verbatim + +This selects the caps font by setting the @code{font-shape} property to +@code{#'caps} for interpreting @code{Text-in-caps}. + +To make the above available as @code{\smallcaps} command, we have to +define a function using @code{def-markup-command}. The command should +take a single argument, of markup type. Therefore, the start of the +definition should read +@example + (def-markup-command (smallcaps paper props argument) (markup?) +@end example + +@noindent + +What follows is the content of the command: we should interpret +the @code{argument} as a markup, i.e. + +@example + (interpret-markup paper @dots{} argument) +@end example + +@noindent +This interpretation should add @code{'(font-shape . caps)} to the active +properties, so we substitute the the following for the @dots{} in the +above example: + +@example + (cons (list '(font-shape . caps) ) props) +@end example + +@noindent +The variable @code{props} is a list of alists, and we prepend to it by +consing a list with the extra setting. + +However, suppose that we are using a font that does not have a +small-caps variant. In that case, we have to fake the small caps font, +by setting a string in upcase, with the first letter a little larger: + +@example +#(def-markup-command (smallcaps paper props str) (string?) + "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" + (interpret-markup paper props + (make-line-markup + (map (lambda (s) + (if (= (string-length s) 0) + s + (markup #:large (string-upcase (substring s 0 1)) + #:translate (cons -0.6 0) + #:tiny (string-upcase (substring s 1))))) + (string-split str #\Space))))) +@end example + +The @code{smallcaps} command first splits its string argument into +tokens separated by spaces (@code{(string-split str #\Space)}); for +each token, a markup is built with the first letter made large and +upcased (@code{#:large (string-upcase (substring s 0 1))}), and a +second markup built with the following letters made tiny and upcased +(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond +introduces a space between markups on a line, the second markup is +translated to the left (@code{#:translate (cons -0.6 0) ...}). Then, +the markups built for each token are put in a line +(@code{(make-line-markup ...)}). Finally, the resulting markup is +passed to the @code{interpret-markup} function, with the @code{paper} +and @code{props} arguments. + +Finally, suppose that we are typesetting a recitative in an opera, and +we would like to define a command that will show character names in a +custom manner. Names should be printed with small caps and translated a +bit to the left and top. We will define a @code{\character} command +that takes into account the needed translation, and uses the newly +defined @code{\smallcaps} command: + +@verbatim +#(def-markup-command (character paper props name) (string?) + "Print the character name in small caps, translated to the left and + top. Syntax: \\character #\"name\"" + (interpret-markup paper props + (markup "" #:translate (cons -4 2) #:smallcaps name))) +@end verbatim + +There is one complication that needs explanation: texts above and below +the staff are moved vertically to be at a certain distance (the +@code{padding} property) from the staff and the notes. To make sure +that this mechanism does not annihilate the vertical effect of our +@code{#:translate}, we add an empty string (@code{""}) before the +translated text. Now the @code{""} will be put above the notes, and the +@code{name} is moved in relation to that empty string. The net effect is +that the text is moved to the upper left. + +The final result is as follows: +@verbatim +\score { + \notes { \fatText + c''^\markup \character #"Cleopatra" + e'^\markup \character #"Giulio Cesare" + } +} +@end verbatim + +@lilypond[raggedright] +#(def-markup-command (smallcaps paper props str) (string?) + "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" + (interpret-markup paper props + (make-line-markup + (map (lambda (s) + (if (= (string-length s) 0) + s + (markup #:large (string-upcase (substring s 0 1)) + #:translate (cons -0.6 0) + #:tiny (string-upcase (substring s 1))))) + (string-split str #\Space))))) + +#(def-markup-command (character paper props name) (string?) + "Print the character name in small caps, translated to the left and + top. Syntax: \\character #\"name\"" + (interpret-markup paper props + (markup "" #:translate (cons -4 0) #:smallcaps name))) + +\score { + \notes { \fatText + c''^\markup \character #"Cleopatra" + e'^\markup \character #"Giulio Cesare" + } +} +@end lilypond + + + +@node Contexts for programmers +@appendixsec Contexts for programmers + + +@menu +* Context evaluation:: +* Applyoutput:: +@end menu + +@node Context evaluation +@appendixsubsec Context evaluation + +Contexts can be modified during interpretation with Scheme code. The +syntax for this is +@example + \applycontext @var{function} +@end example + +@var{function} should be a Scheme function taking a single argument, +being the context to apply it to. The following code will print the +current bar number on the standard output during the compile: + +@example + \applycontext + #(lambda (x) + (format #t "\nWe were called in barnumber ~a.\n" + (ly:context-property x 'currentBarNumber))) +@end example + + + +@node Applyoutput +@appendixsubsec Applyoutput + +The most versatile way of tuning an object is @code{\applyoutput}. Its +syntax is +@example +\applyoutput @var{proc} +@end example + +@noindent +where @var{proc} is a Scheme function, taking three arguments. + +When interpreted, the function @var{proc} is called for every layout +object found in the context, with the following arguments: +@itemize @bullet +@item the layout object itself, +@item the context where the layout object was created, and +@item the context where @code{\applyoutput} is processed. +@end itemize + + +In addition, the cause of the layout object, i.e. the music +expression or object that was responsible for creating it, is in the +object property @code{cause}. For example, for a note head, this is a +@internalsref{NoteHead} event, and for a @internalsref{Stem} object, +this is a @internalsref{NoteHead} object. + +Here is a simple example of @code{\applyoutput}; it blanks note-heads on the +center-line: +@example +(define (blanker grob grob-origin context) + (if (and (memq (ly:grob-property grob 'interfaces) + note-head-interface) + (eq? (ly:grob-property grob 'staff-position) 0)) + + (ly:grob-set-property! grob 'transparent #t))) +@end example + diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely deleted file mode 100644 index 10a03b6afa..0000000000 --- a/Documentation/user/refman.itely +++ /dev/null @@ -1,7572 +0,0 @@ -@c Note: -*-texinfo-*- -@c This file is part of lilypond.tely - -@c A menu is needed before every deeper *section nesting of @node's; run -@c M-x texinfo-all-menus-update -@c to automatically fill in these menus before saving changes -@c -@c FIXME: singular vs. plural: Beams/Beam - - -@node Notation manual -@chapter Notation manual - -This chapter describes all the different types of notation supported -by LilyPond. It is intended as a reference for users that are already -somewhat familiar with using LilyPond. - -@menu -* Note entry:: -* Easier music entry:: -* Staff notation:: -* Polyphony:: -* Beaming:: -* Accidentals:: -* Expressive marks:: -* Repeats:: -* Rhythmic music:: -* Piano music:: -* Vocal music:: -* Tablatures:: -* Chord names:: -* Orchestral music:: -* Ancient notation:: -* Contemporary notation:: -* Special notation:: -@end menu - -@c FIXME: Note entry vs Music entry at top level menu is confusing. - -@node Note entry -@section Note entry -@cindex Note entry - -The basic elements of any piece of music are the notes. This section -is about basic notation elements notes, rests and related constructs, -such as stems, tuplets and ties. - -@menu -* Notes:: -* Pitches:: -* Chromatic alterations:: -* Chords:: -* Rests:: -* Skips:: -* Durations:: -* Stems:: -* Ties:: -* Tuplets:: -@end menu - - -@node Notes -@subsection Notes - - -A note is printed by specifying its pitch and then its duration: -@footnote{Notes constitute the most basic elements of LilyPond input, -but they do not form valid input on their own without a @code{\score} -block. However, for the sake of brevity and simplicity we will -generally omit @code{\score} blocks and @code{\paper} declarations in -this manual.} - -@lilypond[fragment,verbatim] - cis'4 d'8 e'16 c'16 -@end lilypond - - -@node Pitches -@subsection Pitches - -@cindex Pitch names -@cindex Note specification -@cindex pitches -@cindex entering notes - -The most common syntax for pitch entry is used in @code{\chords} and -@code{\notes} mode. In Note and Chord mode, pitches may be designated -by names. The notes are specified by the letters @code{a} through -@code{g}, while the octave is formed with 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: - -@lilypond[fragment,verbatim] -\clef bass - a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c'' -@end lilypond - -@cindex note names, Dutch - -A sharp is formed by adding @code{-is} to the end of a pitch name and -a flat is formed by adding @code{-es}. Double sharps and double flats -are obtained by adding @code{-isis} or @code{-eses}. These -names are the Dutch note names. In Dutch, @code{aes} is contracted to -@code{as}, but both forms are accepted. Similarly, both -@code{es} and @code{ees} are accepted. - -Half-flats and half-sharps are formed by adding @code{-eh} and -@code{-ih}; the following is a series of Cs with increasing pitches: - -@cindex quarter tones -@cindex semi-flats, semi-sharps - -@lilypond[verbatim,relative=2] - ceses4 - ceseh - ces - ceh - c - cih - cis - cisih - cisis -@end lilypond - -There are predefined sets of note names for various other languages. -To use them, include the language specific init file. For -example: @code{\include "english.ly"}. The available language files -and the note names they define are: - -@anchor{note name} -@anchor{note names} -@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 - -x (double) -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 -espanol.ly do re mi fa sol la sib si -s -b - -@end example - -@cindex @code{'} -@cindex @code{,} - - - -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] - c' c'' es' g' as' gisis' ais' -@end lilypond - - -@refcommands - -Notes can be hidden and unhidden with the following commands: - -@cindex @code{\hideNotes} -@code{\hideNotes}, -@cindex @code{\unHideNotes} -@code{\unHideNotes}. - - -@seealso - -Internals: @internalsref{NoteEvent}, and @internalsref{NoteHead}. - -@node Chromatic alterations -@subsection Chromatic alterations - -Normally accidentals are printed automatically, but you may also -print them manually. 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: - -@lilypond[fragment,verbatim] - cis' cis' cis'! cis'? -@end lilypond - - -The automatic production of accidentals can be tuned in many -ways. For more information, refer to @ref{Accidentals}. - -@node Chords -@subsection Chords - -A chord is formed by a enclosing a set of pitches in @code{<} and -@code{>}. A chord may be followed by a duration, and a set of -articulations, just like simple notes. - - -@node Rests -@subsection Rests -@cindex Rests - - - - -Rests are entered like notes, with the note name @code{r}: - -@lilypond[raggedright,verbatim] -r1 r2 r4 r8 -@end lilypond - -Whole bar rests, centered in middle of the bar, -must be done with multi measure rests. They are discussed in -@ref{Multi measure rests}. - - -A rest's vertical position may be explicitly specified by entering a -note with the @code{\rest} keyword appended. This makes manual -formatting in polyphonic music easier. Rest collision testing will -leave these rests alone: - -@lilypond[raggedright,verbatim] -a'4\rest d'4\rest -@end lilypond - -@seealso - -Internals: @internalsref{RestEvent}, and @internalsref{Rest}. - - -@c FIXME: naming. -@node Skips -@subsection Skips -@cindex Skip -@cindex Invisible rest -@cindex Space note - -An invisible rest (also called a `skip') can be entered like a note -with note name `@code{s}' or with @code{\skip @var{duration}}: - -@lilypond[raggedright,verbatim] -a2 s4 a4 \skip 1 a4 -@end lilypond - -The @code{s} syntax is only available in note mode and chord mode. In -other situations, you should use the @code{\skip} command: - -@lilypond[raggedright,verbatim] -\score { - \new Staff << - { \time 4/8 \skip 2 \time 4/4 } - \notes\relative c'' { a2 a1 } - >> -} -@end lilypond - -The skip command is merely an empty musical placeholder. It does not -produce any output, not even transparent output. - -The @code{s} skip command does create @internalsref{Staff} and -@internalsref{Voice} when necessary, similar to note and rest -commands. For example, the following results in an empty staff. - -@lilypond[raggedright,verbatim] -\score { \notes { s4 } } -@end lilypond - -The same fragment using @code{\skip} results in an empty page. - -@seealso - -Internals: @internalsref{SkipEvent}, @internalsref{SkipMusic}. - - - -@node Durations -@subsection Durations - - -@cindex duration - - -In Note, Chord, and Lyrics mode, durations are designated by numbers -and dots: durations are entered as their reciprocal values. For example, -a quarter note is entered using a @code{4} (since it is a 1/4 note), while -a half note is entered using a @code{2} (since it is a 1/2 note). For notes -longer than a whole you must use variables: - -@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 - -@lilypond[noindent] -\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" - \override StaffSymbol #'transparent = ##t - \override TimeSignature #'transparent = ##t - \consists "Pitch_squash_engraver" - } - } -} -@end lilypond - - -If the duration is omitted then it is set to the previously entered -duration. The default for the first note is a quarter note. The duration -can be followed by dots (`@code{.}') in order to obtain dotted note -lengths: -@cindex @code{.} - -@lilypond[fragment,verbatim] - a' b' c''8 b' a'4 a'4. b'4.. c'8. -@end lilypond -@cindex @code{r} -@cindex @code{s} - -You can alter the length of duration by a fraction @var{N/M} -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. -In the following example, the first three notes take up exactly two -beats: -@lilypond[fragment,relative=2,verbatim] - \time 2/4 - a4*2/3 gis4*2/3 a4*2/3 - a4 -@end lilypond - - -@refcommands - -Dots are normally moved up to avoid staff lines, except in polyphonic -situations. The following commands may be used to force a particular -direction manually: - -@cindex @code{\dotsUp} -@code{\dotsUp}, -@cindex @code{\dotsDown} -@code{\dotsDown}, -@cindex @code{\dotsBoth} -@code{\dotsBoth}. - -@seealso - -Internals: @internalsref{Dots}, and @internalsref{DotColumn}. - -@node Stems -@subsection Stems - -Whenever a note is found, a @internalsref{Stem} object is created -automatically. For whole notes and rests, they are also created but -made invisible. - -@refcommands - -@cindex @code{\stemUp} -@code{\stemUp}, -@cindex @code{\stemDown} -@code{\stemDown}, -@cindex @code{\stemBoth} -@code{\stemBoth}. - - -@node Ties -@subsection Ties - -@cindex Tie -@cindex ties -@cindex @code{~} - -A tie connects two adjacent note heads of the same pitch. The tie in -effect extends the length of a note. Ties should not be confused with -slurs, which indicate articulation, or phrasing slurs, which indicate -musical phrasing. A tie is entered using the tilde symbol `@code{~}': - -@lilypond[fragment,verbatim] - e' ~ e' ~ -@end lilypond - -When a tie is applied to a chord, all note heads whose pitches match -are connected. When no note heads match, no ties will be created. - -In its meaning a tie is just a way of extending a note duration, similar -to the augmentation dot; in the following example there are two ways of -notating exactly the same concept: -@c -@lilypond[fragment,raggedright] -\time 3/4 c'2. c'2 ~ c'4 -@end lilypond -If you need to tie a lot of notes over bars, it may be easier to use automatic -note splitting (see @ref{Automatic note splitting}). - -@refcommands - - -@cindex @code{\tieUp} -@code{\tieUp}, -@cindex @code{\tieDown} -@code{\tieDown}, -@cindex @code{\tieBoth} -@code{\tieBoth}, -@cindex @code{\tieDotted} -@code{\tieDotted}, -@cindex @code{\tieSolid} -@code{\tieSolid}. - -@seealso - -In this manual: @ref{Automatic note splitting}. - -Internals: @internalsref{TieEvent}, @internalsref{Tie}. - -For tying only a subset of the note heads of a pair of chords, see -@inputfileref{input/regression,tie-chord-partial.ly}. - -@refbugs - - -Switching staves when a tie is active will not produce a slanted tie. - -Formatting of ties is a difficult subject. The results are often not -optimal. - - - -@node Tuplets -@subsection Tuplets - -@cindex tuplets -@cindex triplets -@cindex @code{\times} - -Tuplets are made out of a music expression by multiplying all durations -with a fraction: - -@cindex @code{\times} -@example - \times @var{fraction} @var{musicexpr} -@end example - -@noindent -The duration of @var{musicexpr} will be multiplied by the fraction. -The fraction's denominator will be printed over the notes, optionally -with a bracket. The most common tuplet is the triplet in which 3 -notes have the length of 2, so the notes are 2/3 of their written -length: - -@lilypond[fragment,verbatim] - g'4 \times 2/3 {c'4 c' c'} d'4 d'4 -@end lilypond - -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, saving lots of typing. In the next -example, there are two triplets shown, while @code{\times} was only -used once: - -@lilypond[fragment,relative,raggedright,verbatim] -\set tupletSpannerDuration = #(ly:make-moment 1 4) -\times 2/3 { c'8 c c c c c } -@end lilypond - -The format of the number is determined by the property -@code{tupletNumberFormatFunction}. The default prints only the -denominator, but if it is set to the Scheme function -@code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed -instead. - - -@cindex @code{tupletNumberFormatFunction} -@cindex tuplet formatting - - -@refcommands - -@cindex @code{\tupletUp} -@code{\tupletUp}, -@cindex @code{\tupletDown} -@code{\tupletDown}, -@cindex @code{\tupletBoth} -@code{\tupletBoth}. - -@seealso - -Internals: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}. - -Examples: @inputfileref{input/regression,tuplet-nest.ly}. - -@refbugs - -Nested tuplets are not formatted automatically. In this case, outer -tuplet brackets should be moved manually, which is demonstrated in -@inputfileref{input/regression,tuplet-nest.ly}. - - - -@node Easier music entry -@section Easier music entry -@cindex Music entry - -When entering music it is easy to introduce errors. This section deals -with tricks and features of the input language that were added solely -to help entering music, and find and correct mistakes. - -It is also possible to use external programs, for example GUI -interfaces, or MIDI transcription programs, to enter or edit -music. Refer to the website for more information. Finally, there are -tools make debugging easier, by linking the input file and the output -shown on screen. See @ref{Point and click} for more information. - - -@menu -* Relative octaves:: -* Octave check:: -* Bar check:: -* Skipping corrected music:: -* Automatic note splitting:: -@end menu - - - - -@node Relative octaves -@subsection Relative octaves -@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. The relative -octave mode prevents these errors: a single error puts the rest of the -piece off by one octave: - -@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}. - -Here is the relative mode shown in action: -@lilypond[fragment,raggedright,verbatim] - \relative c'' { - b c d c b c bes a - } -@end lilypond - -Octave changing marks are used for intervals greater than a fourth: -@lilypond[fragment,verbatim] - \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: - -@lilypond[fragment,verbatim] - \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}. - -@node Octave check -@subsection Octave check - - -Octave checks make octave errors easier to correct: a note may be -followed by @code{=}@var{quotes} which indicates what its absolute -octave should be. In the following example, -@example - \relative c'' @{ c='' b=' d,='' @} -@end example - -@noindent -@c take care with @code, adds confusing quotes. -the d will generate a warning, because a d'' is expected, but a d' is -found. In the output, the octave is corrected this and the following -notes. - - - -There is also a syntax that is separate from the notes. -@example - \octave @var{pitch} -@end example - -This checks that @var{pitch} (without octave) yields @var{pitch} (with -octave) in \relative mode. If not, a warning is printed, and the -octave is corrected, for example, the first check is passed -successfully. The second check fails with an error message. The -octave is adjusted so the following notes are in the correct octave -once again. -@example - \relative c' @{ - e - \octave a' - \octave b' - @} -@end example - - -The octave of a note following an octave check is determined with -respect to the note preceding it. In the next fragment, the last note -is a @code{a'}, above middle C. Hence, the @code{\octave} check may -be deleted without changing the meaning of the piece. - -@lilypond[verbatim,fragment] - \relative c' { - e - \octave b - a - } -@end lilypond - -@node Bar check -@subsection Bar check -@cindex Bar check - -@cindex bar check -@cindex @code{barCheckSynchronize} -@cindex @code{|} - -Bar checks help detect errors in the durations. A bar check is -entered using the bar symbol, `@code{|}'. Whenever it is encountered -during interpretation, it should fall on a measure boundary. If it -does not, a warning is printed. Depending on the value of -@code{barCheckSynchronize}, the beginning of the measure will be -relocated. - -In the next example, the second bar check will signal an error: -@example - \time 3/4 c2 e4 | g2 | -@end example - -Bar checks can also be used in lyrics, for example - -@example - \lyrics @{ - \time 2/4 - Twin -- kle | Twin -- kle - @} -@end example - - -@cindex skipTypesetting - -Failed bar checks are caused by entering incorrect -durations. Incorrect durations often completely garble up the score, -especially if it is polyphonic, so you should start correcting the -score by scanning for failed bar checks and incorrect durations. To -speed up this process, you can use @code{skipTypesetting}, described -in the next section. - -@node Skipping corrected music -@subsection 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. -This can be used to skip over the parts of a score that have already -been checked for errors: - -@lilypond[fragment,raggedright,verbatim] -\relative c'' { c8 d -\set Score.skipTypesetting = ##t - e f g a g c, f e d -\set Score.skipTypesetting = ##f -c d b bes a g c2 } -@end lilypond - -@node Automatic note splitting -@subsection Automatic note splitting - -Long notes can be converted automatically to tied notes. This is done -by replacing the @internalsref{Note_heads_engraver} by the -@internalsref{Completion_heads_engraver}. -In the following examples, notes crossing the bar line are split and tied. - - -@lilypond[noindent,verbatim,relative=1] -\new Voice \with { - \remove "Note_heads_engraver" - \consists "Completion_heads_engraver" -} { - c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 -} -@end lilypond - -This engraver splits all running notes at the bar line, and inserts -ties. One of its uses is to debug complex scores: if the measures are -not entirely filled, then the ties exactly show how much each measure -is off. - -@refbugs - -Not all durations (especially those containing tuplets) can be -represented exactly; the engraver will not insert tuplets. - -@seealso - -Examples: @inputfileref{input/regression,completion-heads.ly}. - -Internals: @internalsref{Completion_heads_engraver}. - - -@node Staff notation -@section Staff notation - -This section describes music notation that occurs on staff level, -such as keys, clefs and time signatures. - -@cindex Staff notation - -@menu -* Staff symbol:: -* Key signature:: -* Clef:: -* Ottava brackets:: -* Time signature:: -* Partial measures:: -* Unmetered music:: -* Bar lines:: -@end menu - -@node Staff symbol -@subsection Staff symbol - -@cindex adjusting staff symbol - -Notes, dynamic signs, etc. are grouped -with a set of horizontal lines, into a staff (plural `staves'). In our -system, these lines are drawn using a separate layout object called -staff symbol. - - -@cindex staff lines, setting number of -@cindex staff lines, setting thickness of -@cindex thickness of staff lines, setting -@cindex number of staff lines, setting - -@seealso - -Internals: @internalsref{StaffSymbol}. - -Examples: @inputfileref{input/test,staff-lines.ly}, -@inputfileref{input/test,staff-size.ly}. - -@refbugs - -If a staff is ended halfway a piece, the staff symbol may not end -exactly on the bar line. - - -@node Key signature -@subsection Key signature -@cindex Key signature - -@cindex @code{\key} - -The key signature indicates the scale in which a piece is played. It -is denoted by a set of alterations (flats or sharps) at the start of -the staff. - -@syntax - -Setting or changing the key signature is done with the @code{\key} -command: -@example - @code{\key} @var{pitch} @var{type} -@end example - -@cindex @code{\minor} -@cindex @code{\major} -@cindex @code{\minor} -@cindex @code{\ionian} -@cindex @code{\locrian} -@cindex @code{\aeolian} -@cindex @code{\mixolydian} -@cindex @code{\lydian} -@cindex @code{\phrygian} -@cindex @code{\dorian} - -Here, @var{type} should be @code{\major} or @code{\minor} to get -@var{pitch}-major or @var{pitch}-minor, respectively. -The 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 -@internalsref{Staff}.@code{keySignature}. Non-standard key signatures -can be specified by setting this property directly. - -Accidentals and key signatures often confuse new users, because -unaltered notes get natural signs depending on the key signature. The -tutorial explains why this is so in @ref{More about pitches}. - -@refbugs - -The ordering of a key cancellation is wrong when it is combined with -repeat bar lines. The cancellation is also printed after a line break. - -@seealso - -Internals: @internalsref{KeyChangeEvent}, and @internalsref{KeySignature}. - -@cindex @code{keySignature} - - -@node Clef -@subsection Clef -@cindex @code{\clef} - -The clef indicates which lines of the staff correspond to which -pitches. - -@syntax - -The clef can be set or changed with the @code{\clef} command: -@lilypond[fragment,verbatim] - \key f\major c''2 \clef alto g'2 -@end lilypond - -Supported clef-names include: -@c Moved standard clefs to the top /MB -@table @code -@cindex treble clef -@cindex violin clef -@item treble, violin, G, G2 -G clef on 2nd line -@item alto, C -@cindex alto clef - C clef on 3rd line -@item tenor -@cindex tenor clef - C clef on 4th line. -@item bass, F -@cindex bass clef - F clef on 4th line -@item french -@cindex french clef - G clef on 1st line, so-called French violin clef -@item soprano -@cindex soprano clef - C clef on 1st line -@item mezzosoprano -@cindex mezzosoprano clef - C clef on 2nd line -@item baritone -@cindex baritone clef - C clef on 5th line -@item varbaritone -@cindex varbaritone clef - F clef on 3rd line -@item subbass -@cindex subbass clef - F clef on 5th line -@item percussion - percussion clef -@end table - -By adding @code{_8} or @code{^8} to the clef name, the clef is -transposed one octave down or up, respectively, and @code{_15} and -@code{^15} transposes by two octaves. The argument @var{clefname} -must be enclosed in quotes when it contains underscores or digits. For -example, - - -@cindex choral tenor clef -@lilypond[verbatim,fragment,relative] - \clef "G_8" c4 -@end lilypond - -This command is equivalent to setting @code{clefGlyph}, -@code{clefPosition} (which controls the Y position of the clef), -@code{centralCPosition} and @code{clefOctavation}. A clef is printed -when any of these properties are changed. - -@seealso - -Internals: the object for this symbol is @internalsref{Clef}. - - - -@node Ottava brackets -@subsection Ottava brackets - -``Ottava'' brackets introduce an extra transposition of an octave for -the staff. They are created by invoking the function -@code{set-octavation}: - -@cindex ottava -@cindex 15ma -@cindex octavation - -@lilypond[verbatim,fragment] -\relative c''' { - a2 b - #(set-octavation 1) - a b - #(set-octavation 0) - a b } -@end lilypond - -The @code{set-octavation} function also takes -1 (for 8va bassa) and 2 -(for 15ma) as arguments. Internally the function sets the properties -@code{ottavation} (e.g. to @code{"8va"}) and -@code{centralCPosition}. For overriding the text of the bracket, set -@code{ottavation} after invoking @code{set-octavation}, i.e., - -@example - #(set-octavation 1) - \set Staff.ottavation = #"8" -@end example - -@seealso - -Internals: @internalsref{OttavaBracket}. - -Examples: @inputfileref{input/regression,ottava.ly}, -@inputfileref{input/regression,ottava-broken.ly}. - -@refbugs - -@code{set-octavation} will get confused when clef changes happen -during an octavation bracket. - -@node Time signature -@subsection Time signature -@cindex Time signature -@cindex meter -@cindex @code{\time} - -Time signature indicates the metrum of a piece: a regular pattern of -strong and weak beats. It is denoted by a fraction at the start of the -staff. - -@syntax - -The time signature is set or changed by the @code{\time} -command: -@lilypond[fragment,verbatim] - \time 2/4 c'2 \time 3/4 c'2. -@end lilypond - -The symbol that is printed can be customized with the @code{style} -property. Setting it to @code{#'()} uses fraction style for 4/4 and -2/2 time. There are many more options for its layout. See -@inputfileref{input/test,time.ly} for more examples. - - -This command sets the property @code{timeSignatureFraction}, -@code{beatLength} and @code{measureLength} in the @code{Timing} -context, which is normally aliased to @internalsref{Score}. The -property @code{measureLength} determines where bar lines should be -inserted, and how automatic beams should be generated. Changing the -value of @code{timeSignatureFraction} also causes the symbol to be -printed. - -More options are available through the Scheme function -@code{set-time-signature}. In combination with the -@internalsref{Measure_grouping_engraver}, it will create -@internalsref{MeasureGrouping} signs. Such signs ease reading -rhythmically complex modern music. In the following example, the 9/8 -measure is subdivided in 2, 2, 2 and 3. This is passed to -@code{set-time-signature} as the third argument @code{(2 2 2 3)}: - -@lilypond[verbatim] -\score { \notes \relative c'' { - #(set-time-signature 9 8 '(2 2 2 3)) - g8[ g] d[ d] g[ g] a8[( bes g]) | - #(set-time-signature 5 8 '(3 2)) - a4. g4 - } - \paper { - raggedright = ##t - \translator { \StaffContext - \consists "Measure_grouping_engraver" - }}} -@end lilypond - -@seealso - -Internals: @internalsref{TimeSignature}, and @internalsref{Timing_engraver}. - - -@refbugs - -Automatic beaming does not use measure grouping specified with -@code{set-time-signature}. - -@node Partial measures -@subsection Partial measures -@cindex Partial -@cindex anacrusis -@cindex partial measure -@cindex measure, partial -@cindex shorten measures -@cindex @code{\partial} - -Partial measures, for example in upsteps, are entered using the -@code{\partial} command: -@lilypond[fragment,verbatim,relative=1] -\partial 16*5 c16 cis d dis e | a2. c,4 | b2 -@end lilypond - -The syntax for this command is -@example - \partial @var{duration} -@end example -This is internally translated into -@example - \set Timing.measurePosition = -@var{length of duration} -@end example -@cindex @code{|} -The property @code{measurePosition} contains a rational number -indicating how much of the measure has passed at this point. - -@node Unmetered music -@subsection Unmetered music - -Bar lines and bar numbers are calculated automatically. For unmetered -music (e.g. cadenzas), this is not desirable. By setting -@code{Score.timing} to false, this automatic timing can be switched -off. - - -@refcommands - -@cindex @code{\cadenzaOn} -@code{\cadenzaOn}, -@cindex @code{\cadenzaOff} -@code{\cadenzaOff}. - -@node Bar lines -@subsection Bar lines -@cindex Bar lines - -@cindex @code{\bar} -@cindex measure lines -@cindex repeat bars - - -Bar lines delimit measures, but are also used to indicate repeats. -Normally, they are inserted automatically. Line breaks may only -happen on bar lines. - -@syntax - - Special types -of bar lines can be forced with the @code{\bar} command: -@c -@lilypond[relative=1,fragment,verbatim] - c4 \bar "|:" c4 -@end lilypond - -The following bar types are available: -@lilypond[fragment,relative,raggedright,verbatim] -c4 -\bar "|" c -\bar "" c -\bar "|:" c -\bar "||" c -\bar ":|" c -\bar ".|" c -\bar ".|." c -\bar ":|:" c -\bar "|." c -\bar ":" c -@end lilypond -For allowing line breaks, there is a special command, -@example - \bar "empty" -@end example -This will insert an invisible bar line, and allow line breaks at this -point. - -In scores with many staves, a @code{\bar} command in one staff is -automatically applied to all staves. The resulting bar lines are -connected between different staves of a @internalsref{StaffGroup}: -@c -@lilypond[fragment,verbatim] -<< \context StaffGroup << - \new Staff { e'4 d' - \bar "||" - f' e' } - \new Staff { \clef bass c4 g e g } >> -\new Staff { \clef bass c2 c2 } >> -@end lilypond - - -The command @code{\bar @var{bartype}} is a short cut for doing -@code{\set Score.whichBar = @var{bartype}} Whenever -@code{whichBar} is set to a string, a bar line of that type is -created. At the start of a measure it is set to -@code{defaultBarType}. The contents of @code{repeatCommands} are used -to override default measure bars. - -Property @code{whichBar} can also be set directly, using @code{\set} -or @code{\bar}. These settings take precedence over the automatic -@code{whichBar} settings. - -@cindex whichBar -@cindex repeatCommands -@cindex defaultBarType - -You are encouraged to use @code{\repeat} for repetitions. See -@ref{Repeats}. - - - -@seealso - -In this manual: @ref{Repeats}. - - -Internals: the bar line objects that are created at -@internalsref{Staff} level are called @internalsref{BarLine}, the bar -lines that span staves are @internalsref{SpanBar}s. - -@cindex bar lines at start of system -@cindex start of system - -The bar lines at the start of each system are -@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and -@internalsref{SystemStartBracket}. Only one of these types is created -in every context, and that type is determined by the property -@code{systemStartDelimiter}. - -Examples: @inputfileref{input/test,bar-lines.ly}, - -@node Polyphony -@section Polyphony -@cindex polyphony - -The easiest way to enter fragments with more than one voice on a staff -is to split chords using the separator @code{\\}. You can use it for -small, short-lived voices or for single chords: - -@lilypond[verbatim,fragment] -\context Staff \relative c'' { - c4 << { f d e } \\ { b c2 } >> - c4 << g' \\ b, \\ f' \\ d >> -} -@end lilypond - -The separator causes @internalsref{Voice} contexts@footnote{Polyphonic -voices are sometimes called "layers" other notation packages} -@cindex layers -to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In -each of these contexts, vertical direction of slurs, stems, etc. is set -appropriately. - -@cindex @code{\voiceOne} -@cindex @code{\voiceFour} - -This can also be done by instantiating @internalsref{Voice} contexts -by hand, and using @code{\voiceOne}, up to @code{\voiceFour} to assign -a stem directions and horizontal shift for each part: -@c - -@lilypond[raggedright,verbatim] -\relative c'' -\context Staff << \new Voice { \voiceOne cis2 b } - \new Voice { \voiceThree b4 ais ~ ais4 gis4 } - \new Voice { \voiceTwo fis4~ fis4 f ~ f } >> -@end lilypond - -@noindent -The command @code{\oneVoice} will revert back to the normal setting. -@cindex @code{\oneVoice} - - -Normally, note heads with a different number of dots are not merged, but -when the object property @code{merge-differently-dotted} is set in -the @internalsref{NoteCollision} object, they are merged: -@lilypond[verbatim,fragment,raggedright] -\relative c'' \context Voice << { - g8 g8 - \override Staff.NoteCollision - #'merge-differently-dotted = ##t - g8 g8 - } \\ { g8.[ f16] g8.[ f16] } - >> -@end lilypond - -Similarly, you can merge half note heads with eighth notes, by setting -@code{merge-differently-headed}: -@lilypond[fragment,relative=2,verbatim] -\context Voice << { - c8 c4. - \override Staff.NoteCollision - #'merge-differently-headed = ##t - c8 c4. } \\ { c2 c2 } >> -@end lilypond - -LilyPond also vertically shifts rests that are opposite of a stem: - - -@lilypond[raggedright,fragment,verbatim] -\context Voice << c''4 \\ r4 >> -@end lilypond - - -@refcommands - - - -@cindex @code{\oneVoice} -@code{\oneVoice}, -@cindex @code{\voiceOne} -@code{\voiceOne}, -@cindex @code{\voiceTwo} -@code{\voiceTwo}, -@cindex @code{\voiceThree} -@code{\voiceThree}, -@cindex @code{\voiceFour} -@code{\voiceFour}. - - -The following commands specify in what chords of the current voice -should be shifted: the outer voice has @code{\shiftOff}, and the inner -voices have @code{\shiftOn}, @code{\shiftOnn}, etc. - - -@cindex @code{\shiftOn} -@code{\shiftOn}, -@cindex @code{\shiftOnn} -@code{\shiftOnn}, -@cindex @code{\shiftOnnn} -@code{\shiftOnnn}, -@cindex @code{\shiftOff} -@code{\shiftOff}. - - - -@seealso - -Internals: the objects responsible for resolving collisions are -@internalsref{NoteCollision} and @internalsref{RestCollision}. - -Examples: See also example files -@inputfileref{input/regression,collision-dots.ly}, -@inputfileref{input/regression,collision-head-chords.ly}, -@inputfileref{input/regression,collision-heads.ly}, -@inputfileref{input/regression,collision-mesh.ly}, and -@inputfileref{input/regression,collisions.ly}. - - -@refbugs - -Resolving collisions is a intricate subject, and only a few situations -are handled. When LilyPond cannot cope, the @code{force-hshift} -property of the @internalsref{NoteColumn} object and pitched rests can -be used to override typesetting decisions. - -When using @code{merge-differently-headed} with an upstem 8th or a shorter -note, and a downstem half note, the 8th note gets the wrong offset. - -There is no support for clusters where the same note occurs with -different accidentals in the same chord. In this case, it is -recommended to use enharmonic transcription, or to use special cluster -notation (see @ref{Clusters}). - -@node Beaming -@section Beaming - -Beams are used to group short notes into chunks that are aligned with -the metrum. They are inserted automatically in most cases: - -@lilypond[fragment,verbatim,relative=2] -\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 -@end lilypond - -When these automatic decisions are not good enough, beaming can be -entered explicitly. It is also possible to define beaming patterns -that differ from the defaults. - -Individual notes may be marked with @code{\noBeam}, to prevent them -from being beamed: - -@lilypond[fragment,verbatim,relative=2] - \time 2/4 c8 c\noBeam c c -@end lilypond - - -@seealso - -Internals: @internalsref{Beam}. - - -@cindex Automatic beams -@menu -* Manual beams:: -* Setting automatic beam behavior:: -@end menu - -@node Manual beams -@subsection Manual beams -@cindex beams, manual -@cindex @code{]} -@cindex @code{[} - -In some cases it may be necessary to override the automatic beaming -algorithm. For example, the autobeamer will not put beams over rests -or bar lines. Such beams are specified by manually: the begin and end -point are marked with @code{[} and @code{]}: - -@lilypond[fragment,relative,verbatim] - \context Staff { - r4 r8[ g' a r8] r8 g[ | a] r8 - } -@end lilypond - -@cindex @code{stemLeftBeamCount} - -Normally, beaming patterns within a beam are determined automatically. -When this mechanism fouls up, the properties -@code{stemLeftBeamCount} and @code{stemRightBeamCount} can -be used to control the beam subdivision on a stem. If either property -is set, its value will be used only once, and then it is erased: - -@lilypond[fragment,relative,verbatim] - \context Staff { - f8[ r16 f g a] - f8[ r16 \set stemLeftBeamCount = #1 f g a] - } -@end lilypond -@cindex @code{stemRightBeamCount} - - -The property @code{subdivideBeams} can be set in order to subdivide -all 16th or shorter beams at beat positions, as defined by the -@code{beatLength} property. This accomplishes the same effect as -twiddling with @code{stemLeftBeamCount} and @code{stemRightBeamCount}, -but it take less typing: - - -@lilypond[relative=1,verbatim,noindent] - c16[ c c c c c c c] - \set subdivideBeams = ##t - c16[ c c c c c c c] - \set Score.beatLength = #(ly:make-moment 1 8) - c16[ c c c c c c c] -@end lilypond -@cindex subdivideBeams - -Kneed beams are inserted automatically, when a large gap is detected -between the note heads. This behavior can be tuned through the object -property @code{auto-knee-gap}. - -Normally, line breaks are forbidden when beams cross bar lines. This -behavior can be changed by setting @code{allowBeamBreak}. - -@cindex @code{allowBeamBreak} -@cindex beams and line breaks - -@cindex beams, kneed -@cindex kneed beams -@cindex auto-knee-gap - - - -@refbugs - -@cindex Frenched staves - -Automatically kneed beams cannot be used together with hidden staves. - - - - -@node Setting automatic beam behavior -@subsection Setting automatic beam behavior - -@cindex @code{autoBeamSettings} -@cindex @code{(end * * * *)} -@cindex @code{(begin * * * *)} -@cindex automatic beams, tuning -@cindex tuning automatic beaming - -@c [TODO: use \applycontext] - -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{autoBeamSettings}. The defaults for @code{autoBeamSettings} -are defined in @file{scm/auto-beam.scm}. - -The value of @code{autoBeamSettings} is changed with two functions: -@example - #(override-auto-beam-setting - '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b} - [@var{context}]) - #(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})) -@end example -Here, @var{be} is the symbol @code{begin} or @code{end}. It determines -whether the rule applies to begin or end-points. The quantity -@var{p}/@var{q} refers to the length of the beamed notes (and `@code{* -*}' designates notes of any length), @var{n}/@var{M} refers to a time -signature (wildcards `@code{* *}' may be entered to designate all time -signatures), @var{a}/@var{b} is a duration. By default, this command -changes settings for the current voice. It is also possible to adjust -settings at higher contexts, by adding a @var{context} argument. - -For example, if automatic beams should end on every quarter note, use -the following: -@example - #(override-auto-beam-setting '(end * * * *) 1 4) -@end example -Since the duration of a quarter note is 1/4 of a whole note, it is -entered as @code{(ly:make-moment 1 4)}. - -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 - #(override-auto-beam-setting '(end * * * *) 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). - -Rules can also be restricted to specific time signatures. A rule that -should only be applied in @var{N}/@var{M} time signature is formed by -replacing the second asterisks by @var{N} and @var{M}. For example, a -rule for 6/8 time exclusively looks like -@example - #(override-auto-beam-setting '(begin * * 6 8) @dots{}) -@end example - -If a rule should be to applied only to certain types of beams, use the -first 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), use @code{(end 1 32 * -*)}. - -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. - -@cindex automatic beam generation -@cindex autobeam -@cindex @code{autoBeaming} -@cindex lyrics - -For melodies that have lyrics, you may want to switch off -automatic beaming. This is done by setting @code{autoBeaming} to -@code{#f}. - -@refcommands - -@cindex @code{\autoBeamOff} -@code{\autoBeamOff}, -@cindex @code{\autoBeamOn} -@code{\autoBeamOn}. - - -@refbugs - -The rules for ending a beam depend on the shortest note in a beam. -So, while it is possible to have different ending rules for eight -beams and sixteenth beams, a beam that contains both eight and -sixteenth notes will use the rules for the sixteenth beam. - -In the example below, the autobeamer makes eight beams and sixteenth -end at 3 eights; the third beam can only be corrected by specifying -manual beaming. - -@lilypond[raggedright,fragment,relative,noverbatim] - #(override-auto-beam-setting '(end * * * *) 3 8) - % rather show case where it goes wrong - %\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4 - \time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4 -@end lilypond -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}. - -@node Accidentals -@section Accidentals -@cindex Accidentals - -This section describes how to change the way that accidentals are -inserted automatically before the running notes. - - -@menu -* Using the predefined accidental variables:: -* Customized accidental rules:: -@end menu - -@node Using the predefined accidental variables -@subsection Using the predefined accidental variables - - -Common rules for typesetting macros have been canned in a -function. This function is called as follows: - -@cindex @code{set-accidental-style} -@example - #(set-accidental-style 'modern 'Voice) -@end example - -The function takes two arguments: a symbol that denotes the style (in -the example, @code{modern}), and another symbol that denotes the -context name (in this example, @code{Staff}). If no context name is -supplied, @code{Staff} is the default. - -The following styles are supported: -@table @code -@item default - This is the default typesetting behavior. It should correspond - to 18th century common practice: Accidentals are - remembered to the end of the measure in which they occur and - only on their own octave. - -@item voice -@c - The normal behavior is to remember the accidentals on -Staff-level. This variable, however, typesets accidentals -individually for each voice. Apart from that, the rule is similar to -@code{code}. - - This leads to some weird and often unwanted results - because accidentals from one voice do not get canceled in other - voices: -@lilypond[raggedright,relative,fragment,verbatim] - \context Staff << - #(set-accidental-style 'voice) - << - { es g } \\ - { c, e } - >> >> -@end lilypond - Hence you should only use @code{voice} if the voices -are to be read solely by individual musicians. If the staff is to be -used by one musician (e.g. a conductor) then you use -@code{modern} or @code{modern-cautionary} -instead. - -@item modern -@cindex @code{modern} style accidentals - This rule corresponds to the common practice in the 20th - century. - This rule prints the same accidentals as @code{default}, but temporary - accidentals also are canceled in other octaves. Furthermore, - in the same octave, they also get canceled in the following - measure: - -@lilypond[raggedright,fragment,verbatim] - #(set-accidental-style 'modern) - cis' c'' cis'2 | c'' c' -@end lilypond - -@item @code{modern-cautionary} - @cindex @code{modern-cautionary} - This rule is similar to @code{modern}, but the - ``extra'' accidentals (the ones not typeset by - @code{default}) are typeset as cautionary accidentals. - They are printed in reduced size or with parentheses: -@lilypond[raggedright,fragment,verbatim] - #(set-accidental-style 'modern-cautionary) - cis' c'' cis'2 | c'' c' -@end lilypond - - @cindex @code{modern-voice} -@item modern-voice -is used for multivoice accidentals to be read both by musicians -playing one voice and musicians playing all voices. Accidentals are -typeset for each voice, but they @emph{are} canceled across voices in -the same @internalsref{Staff}. - - @cindex @code{modern-voice-cautionary} -@item modern-voice-cautionary -is the same as @code{modern-voice}, but with the extra -accidentals (the ones not typeset by @code{voice}) typeset -as cautionaries. Even though all accidentals typeset by -@code{default} @emph{are} typeset by this variable then -some of them are typeset as cautionaries. - -@item piano - @cindex @code{piano} accidentals - 20th century practice for piano notation. Very similar to - @code{modern} but accidentals also get canceled - across the staves in the same @internalsref{GrandStaff} or - @internalsref{PianoStaff}. - -@item piano-cautionary - @cindex @code{#(set-accidental-style 'piano-cautionary)} - As @code{#(set-accidental-style 'piano)' , str)} but with the extra accidentals - typeset as cautionaries. - -@item no-reset - @cindex @code{no-reset} accidental style - Same as @code{default} but with accidentals lasting - ``forever'' and not only until the next measure: -@lilypond[raggedright,fragment,verbatim,relative] - #(set-accidental-style 'no-reset) - c1 cis cis c -@end lilypond - -@item forget - This is sort of the opposite of @code{no-reset}: Accidentals - are not remembered at all---and hence all accidentals are - typeset relative to the key signature, regardless of what was - before in the music: - -@lilypond[raggedright,fragment,verbatim,relative] - #(set-accidental-style 'forget) - \key d\major c4 c cis cis d d dis dis -@end lilypond -@end table - -@node Customized accidental rules -@subsection Customized accidental rules - -For determining when to print an accidental, several different rules -are tried. The rule that gives the highest number of accidentals is -used. Each rule consists of -@table @var -@item context: - In which context is the rule applied. For example, if -@var{context} is @internalsref{Score} then all staves share -accidentals, and if @var{context} is @internalsref{Staff} then all -voices in the same staff share accidentals, but staves do not. - -@item octavation: - Whether the accidental changes all octaves or only the current - octave. Valid choices are - - @table @samp - @item same-octave: - This is the default algorithm. Accidentals are typeset if the note changes - the accidental of that note in that octave. Accidentals lasts to the end of the measure - and then as many measures as specified in the value. I.e. 1 means to the end - of next measure, -1 means to the end of previous measure (that is: no duration at all), etc. #t means forever. - @item any-octave: - Accidentals are typeset if the note is different from - the previous note on the same pitch in any octave. The value has same meaning as in - same-octave. - @end table - -@item laziness - - Over how many bar lines the accidental lasts. - If @var{laziness} is @code{-1} then the accidental is forget - immediately, and if @var{laziness} is @code{#t} then the accidental - lasts forever. -@end table - - -@seealso - -Internals: @internalsref{Accidental_engraver}, -@internalsref{Accidental}, and @internalsref{AccidentalPlacement}. - - -@refbugs - -Currently the simultaneous notes are considered to be entered in -sequential mode. This means that in a chord the accidentals are -typeset as if the notes in the chord happened once at a time - in the -order in which they appear in the input file. - -This is only a problem when there are simultaneous notes whose -accidentals depend on each other. The problem only occurs when using -non-default accidentals. In the default scheme, accidentals only -depend on other accidentals with the same pitch on the same staff, so -no conflicts possible. - -This example shows two examples of the same music giving different -accidentals depending on the order in which the notes occur in the -input file: - -@lilypond[raggedright,fragment,verbatim] -\set Staff.autoAccidentals = #'( Staff (any-octave . 0) ) -cis'4 r2 | cis'4 r2 -| r | r | -@end lilypond - -This problem can be solved by manually inserting @code{!} and @code{?} -for the problematic notes. - -@node Expressive marks -@section Expressive marks - - -@c todo: should change ordering -@c where to put text spanners, metronome marks, -@c fingering? - -@menu -* Slurs:: -* Phrasing slurs:: -* Breath marks:: -* Metronome marks:: -* Text spanners:: -* Analysis brackets:: -* Articulations:: -* Fingering instructions:: -* Text scripts:: -* Grace notes:: -* Glissando:: -* Dynamics:: -@end menu - -@node Slurs -@subsection Slurs -@cindex Slurs - -A slur indicates that notes are to be played bound or @emph{legato}. - -@syntax - -They are entered using parentheses: -@lilypond[relative=1,fragment,verbatim] - f( g)( a) a8 b( a4 g2 f4) - 2( 2) -@end lilypond - - -@c TODO: should explain that ^( and _( set directions -@c should set attachments with ^ and _ ? - -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 -object property @code{attachment} of @internalsref{Slur} in -@internalsref{Voice} context. Its value is a pair of symbols, specifying -the attachment type of the left and right end points: - -@lilypond[fragment,relative,verbatim] - \slurUp - \override Stem #'length = #5.5 - g'8(g g4) - \override Slur #'attachment = #'(stem . stem) - g8( g g4) -@end lilypond - -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: - -@lilypond[fragment,relative,verbatim] - \stemUp \slurUp - d32( d'4 d8..) - \override Slur #'attachment = #'(stem . stem) - d,32( d'4 d8..) -@end lilypond - -@refcommands - - -@cindex @code{\slurUp} -@code{\slurUp}, -@cindex @code{\slurDown} -@code{\slurDown}, -@cindex @code{\slurBoth} -@code{\slurBoth}, -@cindex @code{\slurDotted} -@code{\slurDotted}, -@cindex @code{\slurSolid} -@code{\slurSolid}. - -@seealso - -Internals: @seeinternals{Slur}, and @internalsref{SlurEvent}. - - -@refbugs - -Producing nice slurs is a difficult problem, and LilyPond currently -uses a simple, empiric method to produce slurs. In some cases, its -results are ugly. - - -@cindex Adjusting slurs - -@node Phrasing slurs -@subsection Phrasing slurs - -@cindex phrasing slurs -@cindex phrasing marks - -A phrasing slur (or phrasing mark) connects chords and is used to -indicate a musical sentence. It is started using @code{\(} and @code{\)} -respectively: - -@lilypond[fragment,verbatim,relative] - \time 6/4 c'\( d( e) f( e) d\) -@end lilypond - -Typographically, the phrasing slur behaves almost exactly like a -normal slur. However, they are treated as different objects. A -@code{\slurUp} will have no effect on a phrasing slur; instead, you -should use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and -@code{\phrasingSlurBoth}. - -The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurBoth} -will only affect normal slurs and not phrasing slurs. - -@refcommands - -@cindex @code{\phrasingSlurUp} -@code{\phrasingSlurUp}, -@cindex @code{\phrasingSlurDown} -@code{\phrasingSlurDown}, -@cindex @code{\phrasingSlurBoth} -@code{\phrasingSlurBoth}. - -@seealso - -Internals: see also @internalsref{PhrasingSlur}, and -@internalsref{PhrasingSlurEvent}. - -@refbugs - -Phrasing slurs have the same limitations in their formatting as normal -slurs. Putting phrasing slurs over rests leads to spurious warnings. - -@node Breath marks -@subsection Breath marks - -Breath marks are entered using @code{\breathe}: - - -@lilypond[fragment,relative,verbatim] -c'4 \breathe d4 -@end lilypond - -The glyph of the breath mark can be tweaked by overriding the -@code{text} property of the @code{BreathingSign} layout object with -any markup text. For example, -@lilypond[fragment,verbatim,relative] -c'4 -\override BreathingSign #'text - = #(make-musicglyph-markup "scripts-rvarcomma") -\breathe -d4 -@end lilypond - -@seealso - -Internals: @internalsref{BreathingSign}, -@internalsref{BreathingSignEvent}. - -Examples: @inputfileref{input/regression,breathing-sign.ly}. - - -@node Metronome marks -@subsection Metronome marks - -@cindex Tempo -@cindex beats per minute -@cindex metronome marking - -Metronome settings can be entered as follows: -@example - \tempo @var{duration} = @var{per-minute} -@end example - -In the MIDI output, they are interpreted as a tempo change, and in the -paper output, a metronome marking is printed: -@cindex @code{\tempo} -@lilypond[fragment,verbatim] - \tempo 8.=120 c''1 -@end lilypond - -@seealso - -Internals: @internalsref{MetronomeChangeEvent}. - - - -@node Text spanners -@subsection Text spanners -@cindex Text spanners - -Some performance indications, e.g. @i{rallentando} or @i{accelerando}, -are written as texts, and extended over many measures with dotted -lines. You can create such texts using text spanners: attach -@code{\startTextSpan} and @code{\stopTextSpan} to the -start and ending note of the spanner. - -The string to be printed, as well as the style, is set through object -properties: - -@lilypond[fragment,relative,verbatim] - \relative c' { c1 - \override TextSpanner #'direction = #-1 - \override TextSpanner #'edge-text = #'("rall " . "") - c2\startTextSpan b c\stopTextSpan a } -@end lilypond - - -@seealso - -Internals @internalsref{TextSpanEvent}, -@internalsref{TextSpanner}. - -Examples: @inputfileref{input/regression,text-spanner.ly}. - - -@node Analysis brackets -@subsection Analysis brackets -@cindex brackets -@cindex phrasing brackets -@cindex musicological analysis -@cindex note grouping bracket - -Brackets are used in musical analysis to indicate structure in musical -pieces. LilyPond supports a simple form of nested horizontal brackets. -To use this, add the @internalsref{Horizontal_bracket_engraver} to -@internalsref{Staff} context. A bracket is started with -@code{\startGroup} and closed with @code{\stopGroup}: - -@lilypond[raggedright,verbatim] -\score { \notes \relative c'' { - c4\startGroup\startGroup - c4\stopGroup - c4\startGroup - c4\stopGroup\stopGroup - } - \paper { \translator { - \StaffContext \consists "Horizontal_bracket_engraver" - }}} -@end lilypond - -@seealso - -Internals: @internalsref{HorizontalBracket}, -@internalsref{NoteGroupingEvent}. - -Examples: @inputfileref{input/regression,note-group-bracket.ly}. - - -@node Articulations -@subsection Articulations -@cindex Articulations - -@cindex articulations -@cindex scripts -@cindex ornaments - -A variety of symbols can appear above and below notes to indicate -different characteristics of the performance. They are added to a note -by adding a dash and the character signifying the -articulation. They are demonstrated here: - -@lilypondfile[]{script-abbreviations.ly} - -The meanings of these shorthands can be changed: see -@file{ly/script-init.ly} for examples. - - -The script is automatically placed, but if you need to force -directions, you can use @code{_} to force them down, or @code{^} to -put them up: -@lilypond[fragment,verbatim] - c''4^^ c''4_^ -@end lilypond - -Other symbols can be added using the syntax -@var{note}@code{\}@var{name}, e.g. @code{c4\fermata}. Again, they -can be forced up or down using @code{^} and @code{_}, -e.g. - -@lilypond[verbatim,fragment,relative=2] - c\fermata c^\fermata c_\fermata -@end lilypond - - - -@cindex accent -@cindex marcato -@cindex staccatissimo -@cindex fermata -@cindex stopped -@cindex staccato -@cindex portato -@cindex tenuto -@cindex upbow -@cindex downbow -@cindex foot marks -@cindex organ pedal marks -@cindex turn -@cindex open -@cindex flageolet -@cindex reverseturn -@cindex trill -@cindex prall -@cindex mordent -@cindex prallprall -@cindex prallmordent -@cindex prall, up -@cindex prall, down -@cindex mordent -@cindex thumb marking -@cindex segno -@cindex coda -@cindex varcoda - -@lilypondfile[]{script-chart.ly} - - -@refcommands - -@cindex @code{\scriptUp} -@code{\scriptUp}, -@cindex @code{\scriptDown} -@code{\scriptDown}, -@cindex @code{\scriptBoth} -@code{\scriptBoth}. - -@seealso - -Internals: @internalsref{ScriptEvent}, and @internalsref{Script}. - -@refbugs - -These note ornaments appear in the printed output but have no -effect on the MIDI rendering of the music. - - -@node Fingering instructions -@subsection Fingering instructions - -@cindex fingering - -Fingering instructions can be entered using -@example - @var{note}-@var{digit} -@end example -For finger changes, use markup texts: -@c -@lilypond[verbatim,raggedright,fragment] - c'4-1 c'4-2 c'4-3 c'4-4 - c'^\markup { \fontsize #-3 \number "2-3" } -@end lilypond - -@cindex finger change -@cindex scripts -@cindex superscript -@cindex subscript - -You can use the thumb-script to indicate that a note should be -played with the thumb (e.g. in cello music): - -@lilypond[verbatim,raggedright,fragment] - 8(_\thumb )_\thumb - (_\thumb )_\thumb -@end lilypond - -Fingerings for chords can also be added to individual notes -of the chord by adding them after the pitches: -@lilypond[verbatim,raggedright,fragment,relative=1] - < c-1 e-2 g-3 b-5 > 4 -@end lilypond - -@noindent -In this case, setting @code{fingeringOrientations} will put fingerings next -to note heads: - -@lilypond[verbatim,raggedright,fragment,relative=1] - \set fingeringOrientations = #'(left down) - 4 - \set fingeringOrientations = #'(up right down) - 4 -@end lilypond - -By using single note chords, fingering instructions can be put close -to note heads in monophonic music. - -@seealso - -Internals: @internalsref{FingerEvent}, and @internalsref{Fingering}. - -Examples: @inputfileref{input/regression,finger-chords.ly}. - -@node Text scripts -@subsection Text scripts -@cindex Text scripts - -@cindex text items, non-empty -@cindex non-empty texts - -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"}. By default, these indications do not influence the -note spacing, but by using the command @code{\fatText}, the widths -will be taken into account: -@c -@lilypond[fragment,raggedright,verbatim] \relative c' { -c4^"longtext" \fatText c4_"longlongtext" c4 } -@end lilypond - -It is possible to use @TeX{} commands in the strings, but this should -be avoided because the exact dimensions of the string can then no -longer be computed. - -@refcommands - -@cindex @code{\fatText} -@code{\fatText}, -@cindex @code{\emptyText} -@code{\emptyText}. - -@seealso - -In this manual: @ref{Text markup}. - -Internals: @internalsref{TextScriptEvent}, @internalsref{TextScript}. - - - - -@node Grace notes -@subsection Grace notes - - -@c should have blurb about accaciatura / appogiatura - -@cindex @code{\grace} -@cindex ornaments -@cindex grace notes - -Grace notes are ornaments that are written out. The most common ones -are acciaccatura, which should be played as very short. It is denoted -by a slurred small note with a slashed stem. The appoggiatura is a -grace note that takes a fixed fraction of the main note, is and -denoted as a slurred note in small print without a slash. -They are entered with the commands @code{\acciaccatura} and -@code{\appoggiatura}, as demonstrated in the following example: - - -@cindex appoggiatura -@cindex acciaccatura - -@lilypond[relative=2,verbatim,fragment] -b4 \acciaccatura d8 c4 \appoggiatura e8 d4 -\acciaccatura { g16[ f] } e4 -@end lilypond - -Both are special forms of the @code{\grace} command. By prefixing this -keyword to a music expression, a new one is formed, which will be -printed in a smaller font and takes up no logical time in a measure. -@lilypond[relative=2,verbatim,fragment] - c4 \grace c16 c4 - \grace { c16[ d16] } c2 c4 -@end lilypond - -@noindent -Unlike @code{\acciaccatura} and @code{\appoggiatura}, the -@code{\grace} command does not start a slur. - -Internally, timing for grace notes is done using a second, `grace' -time. Every point in time consists of two rational numbers: one -denotes the logical time, one denotes the grace timing. The above -example is shown here with timing tuples: - -@lilypond[raggedright] -<< - \relative c''{ - c4 \grace c16 c4 \grace { - c16[ d16] } c2 c4 - } - \new Lyrics \lyrics { - \markup { (0,0) } 4 - \grace { \markup { - ( \fraction 1 4 , \fraction -1 16 ) } 16 } - \markup { (\fraction 1 4 , 0 ) } 4 - \grace { - \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 - \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16 - } - \markup { ( \fraction 2 4 , 0 ) } - } >> -@end lilypond - - -The placement of grace notes is synchronized between different staves. -In the following example, there are two sixteenth graces notes for -every eighth grace note: - -@lilypond[relative=2,verbatim,fragment] -<< \new Staff { e4 \grace { c16[ d e f] } e4 } - \new Staff { c'4 \grace { g8[ b] } c4 } >> -@end lilypond - - - -If you want to end a note with a grace, then the standard trick -is to put the grace notes after a ``space note'', e.g. -@lilypond[fragment,verbatim,relative=2] -\context Voice { - << { d1^\trill ( } - { s2 \grace { c16[ d] } } >> - c4) -} -@end lilypond - -@noindent -By adjusting the duration of the skip note (here it is a half-note), -the space between the main-note and the grace is adjusted. - - -A @code{\grace} section will introduce special typesetting settings, -for example, to produce smaller type, and set directions. Hence, when -introducing layout tweaks, they should be inside the grace section, -for example, -@lilypond[fragment,verbatim,relative=1] -\new Voice { - \acciaccatura { - \override Stem #'direction = #-1 - f16-> - \revert Stem #'direction - } - g4 -} -@end lilypond - -@noindent -The overrides should also be reverted inside the grace section. - -If the layout of grace sections must be changed throughout the music, -then this can be accomplished through the function -@code{add-grace-property}. The following example -undefines the Stem direction grace section, so stems do not always -point up. - -@example - \new Staff @{ - #(add-grace-property "Voice" Stem direction '()) - @dots{} - @} -@end example - -@noindent -Another option is to change the variables @code{startGraceMusic}, -@code{stopGraceMusic}, @code{startAccacciaturaMusic}, -@code{stopAccacciaturaMusic}, @code{startAppoggiaturaMusic}, -@code{stopAppoggiaturaMusic}. More information is in the file -@file{ly/grace-init.ly}. - - -@seealso - -Internals: @internalsref{GraceMusic}. - -@refbugs - -A score that starts with an @code{\grace} section needs an explicit -@code{\context Voice} declaration, otherwise the main note and grace -note end up on different staves. - -Grace note synchronization can also lead to surprises. Staff notation, -such as key signatures, bar lines, etc. are also synchronized. Take -care when you mix staves with grace notes and staves without, for example, - -@lilypond[relative=2,verbatim,fragment] -<< \new Staff { e4 \bar "|:" \grace c16 d4 } - \new Staff { c4 \bar "|:" d4 } >> -@end lilypond - -Grace sections should only be used within sequential music -expressions. Nesting or juxtaposing grace sections is not supported, -and might produce crashes or other errors. - - -@node Glissando -@subsection Glissando -@cindex Glissando - -@cindex @code{\glissando} - -A glissando is a smooth change in pitch. It is denoted by a line or a -wavy line between two notes. - -@syntax - -A glissando line can be requested by attaching a @code{\glissando} to -a note: - -@lilypond[fragment,relative,verbatim] - c'\glissando c' -@end lilypond - -@seealso - -Internals: @internalsref{Glissando}, and @internalsref{GlissandoEvent}. - - -@refbugs - -Adding additional texts (such as @emph{gliss.}) is not supported. - - -@node Dynamics -@subsection Dynamics -@cindex Dynamics - - - -@cindex @code{\ppp} -@cindex @code{\pp} -@cindex @code{\p} -@cindex @code{\mp} -@cindex @code{\mf} -@cindex @code{\f} -@cindex @code{\ff} -@cindex @code{\fff} -@cindex @code{\ffff} -@cindex @code{\fp} -@cindex @code{\sf} -@cindex @code{\sff} -@cindex @code{\sp} -@cindex @code{\spp} -@cindex @code{\sfz} -@cindex @code{\rfz} - - -Absolute dynamic marks are specified using a command after a note: -@code{c4\ff}. The available dynamic marks are @code{\ppp}, -@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, -@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff}, -@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}: - -@lilypond[verbatim,raggedright,fragment,relative] - c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff - c2\sf c\rfz -@end lilypond - -@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{\<} and terminated with -@code{\!}. A decrescendo is started with @code{\>} and also terminated -with @code{\!}. Because these marks are bound to notes, if you must -use spacer notes if multiple marks during one note are needed: - -@lilypond[fragment,verbatim] - c''\< c''\! d''\decr e''\rced - << f''1 { s4 s4\< s4\! \> s4\! } >> -@end lilypond -This may give rise to very short hairpins. Use @code{minimum-length} -in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for -example: - -@example - \override Staff.Hairpin #'minimum-length = #5 -@end example - -You can also use a text saying @emph{cresc.} instead of hairpins. Here -is an example how to do it: - -@lilypond[fragment,relative=2,verbatim] - c4 \cresc c4 c c c \endcresc c4 -@end lilypond - -@cindex crescendo -@cindex decrescendo - -You can also supply your own texts: -@lilypond[fragment,relative,verbatim] - \context Voice { - \set crescendoText = \markup { \italic "cresc. poco" } - \set crescendoSpanner = #'dashed-line - a'2\< a a a\!\mf - } -@end lilypond - -@cindex diminuendo - - -@refcommands - -@cindex @code{\dynamicUp} -@code{\dynamicUp}, -@cindex @code{\dynamicDown} -@code{\dynamicDown}, -@cindex @code{\dynamicBoth} -@code{\dynamicBoth}. - -@cindex direction, of dynamics - -@seealso - -Internals: @internalsref{CrescendoEvent}, @internalsref{DecrescendoEvent}, and -@internalsref{AbsoluteDynamicEvent}. - -Dynamics are objects of @internalsref{DynamicText} and -@internalsref{Hairpin}. Vertical positioning of these symbols is -handled by the @internalsref{DynamicLineSpanner} object. - -If you want to adjust padding or vertical direction of the dynamics, you -must set properties for the @internalsref{DynamicLineSpanner} object. - - -@node Repeats -@section Repeats - - -@cindex repeats -@cindex @code{\repeat} - - -Repetition is a central concept in music, and multiple notations exist -for repetitions. In LilyPond, most of these notations can be captured -in a uniform syntax. One of the advantages is that they can be -rendered in MIDI accurately. - -The following types of repetition are supported: - -@table @code -@item unfold -Repeated music is fully written (played) out. Useful for MIDI -output, and entering repetitive music. - -@item volta -This is the normal notation: Repeats are not written out, but -alternative endings (volte) are printed, left to right. - -@ignore -@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 -@inputfileref{input,star-spangled-banner.ly}. -@end ignore - -@c tremolo, beamed -@item tremolo -Make tremolo beams. - -@item percent -Make beat or measure repeats. These look like percent signs. - -@end table - -@menu -* Repeat syntax:: -* Repeats and MIDI:: -* Manual repeat commands:: -* Tremolo repeats:: -* Tremolo subdivisions:: -* Measure repeats:: -@end menu - -@node Repeat syntax -@subsection Repeat syntax - -@syntax - -LilyPond has one syntactic construct for specifying different types of -repeats. The syntax is - -@example - \repeat @var{variant} @var{repeatcount} @var{repeatbody} -@end example - -If you have alternative endings, you may add -@cindex @code{\alternative} -@example - \alternative @code{@{} @var{alternative1} - @var{alternative2} - @var{alternative3} @dots{} @code{@}} -@end example -where each @var{alternative} is a music expression. If you do not -give enough alternatives for all of the repeats, then the first -alternative is assumed to be played more than once. - -Normal notation repeats are used like this: -@lilypond[fragment,verbatim,relative=1] - c1 - \repeat volta 2 { c4 d e f } - \repeat volta 2 { f e d c } -@end lilypond - -With alternative endings: -@lilypond[fragment,verbatim,relative=1] - c1 - \repeat volta 2 {c4 d e f} - \alternative { {d2 d} {f f,} } -@end lilypond - - -@lilypond[fragment,verbatim,relative=1] -\context Staff { - \partial 4 - \repeat volta 4 { e | c2 d2 | e2 f2 | } - \alternative { { g4 g g } { a | a a a a | b2. } } -} -@end lilypond - -@refbugs - -If you do a nested repeat like - -@example -\repeat @dots{} -\repeat @dots{} -\alternative -@end example - -@noindent -then it is ambiguous to which @code{\repeat} the @code{\alternative} -belongs. This ambiguity is resolved by always having the -@code{\alternative} belong to the inner @code{\repeat}. For clarity, -it is advisable to use braces in such situations. -@cindex ambiguity - -@node Repeats and MIDI -@subsection Repeats and MIDI - -@cindex expanding repeats - -For instructions on how to unfold repeats for MIDI output, see the -example file @inputfileref{input/test,unfold-all-repeats.ly}. - - -@refbugs - -Timing information is not remembered at the start of an alternative, -so after a repeat timing information must be reset by hand, for -example by setting @code{Score.measurePosition} or entering -@code{\partial}. Similarly, slurs or ties are also not repeated. - - -@node Manual repeat commands -@subsection Manual repeat commands - -@cindex @code{repeatCommands} - -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 @asis -@item the symbol @code{start-repeat}, - which prints a @code{|:} bar line, -@item the symbol @code{end-repeat}, - which prints a @code{:|} bar line, -@item the list @code{(volta @var{text})}, - which prints a volta bracket saying @var{text}: The text can be specified as -a text string or as a markup text, see @ref{Text markup}. Do not -forget to change the font, as the default number font does not contain -alphabetic characters. Or, -@item the list @code{(volta #f)}, which - stops a running volta bracket: -@end table - -@lilypond[verbatim,fragment,relative=2] - c4 - \set Score.repeatCommands = #'((volta "93") end-repeat) - c4 c4 - \set Score.repeatCommands = #'((volta #f)) - c4 c4 -@end lilypond - - -@seealso - -Internals: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic}, -@internalsref{VoltaRepeatedMusic}, -@internalsref{UnfoldedRepeatedMusic}, and -@internalsref{FoldedRepeatedMusic}. - -@node Tremolo repeats -@subsection Tremolo repeats -@cindex tremolo beams - -To place tremolo marks between notes, use @code{\repeat} with tremolo -style: -@lilypond[verbatim,raggedright] -\score { - \context Voice \notes\relative c' { - \repeat "tremolo" 8 { c16 d16 } - \repeat "tremolo" 4 { c16 d16 } - \repeat "tremolo" 2 { c16 d16 } - } -} -@end lilypond - -Tremolo marks can also be put on a single note. In this case, the -note should not be surrounded by braces. -@lilypond[verbatim,raggedright] - \repeat "tremolo" 4 c16 -@end lilypond - -A similar mechanism is the tremolo subdivision, described in -@ref{Tremolo subdivisions}. - -@seealso - -In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}. - -Internals: tremolo beams are @internalsref{Beam} objects. Single stem -tremolos are @internalsref{StemTremolo} objects. The music expression is -@internalsref{TremoloEvent}. - -Example files: @inputfileref{input/regression,chord-tremolo.ly}, -@inputfileref{input/regression,stem-tremolo.ly}. - -@node Tremolo subdivisions -@subsection Tremolo subdivisions -@cindex tremolo marks -@cindex @code{tremoloFlags} - -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{tremoloFlags}) is used: - -@lilypond[verbatim,fragment] - c'2:8 c':32 | c': c': | -@end lilypond - -@c [TODO : stok is te kort bij 32en] - -@refbugs - -Tremolos in this style do not carry over into the MIDI output. - -@seealso - -In this manual: @ref{Tremolo repeats}. - -Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}. - -@node Measure repeats -@subsection Measure repeats - -@cindex percent repeats -@cindex measure repeats - -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-like signs, -patterns that divide the measure length are replaced by slashes: - -@lilypond[verbatim,raggedright] - \context Voice { \repeat "percent" 4 { c'4 } - \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 } -} -@end lilypond - -@seealso - -Internals: @internalsref{RepeatSlash}, @internalsref{PercentRepeat}, -@internalsref{PercentRepeatedMusic}, and -@internalsref{DoublePercentRepeat}. - - - -@node Rhythmic music -@section Rhythmic music - - -@menu -* Showing melody rhythms:: -* Entering percussion:: -* Percussion staves:: -@end menu - - -@node Showing melody rhythms -@subsection Showing melody rhythms - -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 has a single line: - -@lilypond[fragment,relative,verbatim] - \context RhythmicStaff { - \time 4/4 - c4 e8 f g2 | r4 g r2 | g1:32 | r1 | - } -@end lilypond - -@seealso - -Internals: @internalsref{RhythmicStaff}. - -Examples: @inputfileref{input/regression,rhythmic-staff.ly}. - - -@node Entering percussion -@subsection Entering percussion - -@cindex percussion -@cindex drums - -@syntax - -Percussion notes may be entered in @code{\drums} mode, which is -similar to @code{notes}. Each piece of percussion has a full name and -an abbreviated name, and both be used in input files: - -@lilypond[raggedright] - \drums { hihat4 hh4 } -@end lilypond - -The complete list of drum names is in the init file -@file{ly/drumpitch-init.ly}. -@c TODO: properly document this. - -@seealso - -Internals: @internalsref{DrumNoteEvent}. - -@node Percussion staves -@subsection Percussion staves -@cindex percussion -@cindex drums - -A percussion part for more than one instrument typically uses a -multiline staff where each position in the staff refers to one piece -of percussion. - - -To typeset the music, the notes must be interpreted in a -@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts: - -@c -@lilypond[raggedright,verbatim] -up = \drums { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } -down = \drums { bassdrum4 snare8 bd r bd sn4 } -\score { - \new DrumStaff - << \new DrumVoice { \voiceOne \up } - \new DrumVoice { \voiceTwo \down } ->> } -@end lilypond - -The above example shows verbose polyphonic notation. The short -polyphonic notation, described in @ref{Polyphony}, can also be used if -the @internalsref{DrumVoices} are instantiated by hand first. For example, - -@lilypond[fragment] -\drums \new DrumStaff << - \context DrumVoice = "1" { s1 *2 } - \context DrumVoice = "2" { s1 *2 } - { - bd4 sn4 bd4 sn4 - << - { \repeat unfold 16 hh16 } - \\ - { bd4 sn4 bd4 sn4 } - >> - } ->> -@end lilypond - - -There are also other layout possibilities. To use these, set the -property @code{drumStyleTable} in context @internalsref{DrumVoice}. -The following variables have been predefined: - -@table @code -@item drums-style -is the default. It typesets a typical drum kit on a five-line staff - -@lilypond[noindent] -nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc - bd sn ss tomh tommh tomml toml tomfh tomfl } -mus = \drums { cymc cyms cymr hh | hhc hho hhho hhp | \break cb hc - bd sn ss tomh tommh tomml toml tomfh tomfl s16 } -\score { - << \new DrumStaff\with { - \remove Bar_engraver - \remove Time_signature_engraver - \override Stem #'transparent = ##t - \override Stem #'Y-extent-callback = ##f - minimumVerticalExtent = #'(-4.0 . 5.0) - } \mus - \context Lyrics \nam - >> - \paper { - %% need to do this, because of indented @itemize - linewidth= 9 \cm - \translator { \ScoreContext - \override BarNumber #'transparent =##T -}}} -@end lilypond - -The drum scheme supports six different toms. When there fewer toms, simply -select the toms that produce the desired result, i.e. to get toms on -the three middle lines you use @code{tommh}, @code{tomml} and -@code{tomfh}. - -@item timbales-style -to typeset timbales on a two line staff: - -@lilypond[raggedright] -nam = \lyrics { timh ssh timl ssl cb } -mus = \drums { timh ssh timl ssl cb s16 } -\score { - << - \context DrumStaff \with { - \remove Bar_engraver - \remove Time_signature_engraver - \override Stem #'transparent = ##t - \override Stem #'Y-extent-callback = ##f - \override StaffSymbol #'line-count = #2 - \override StaffSymbol #'staff-space = #2 - minimumVerticalExtent = #'(-3.0 . 4.0) - drumStyleTable = #timbales-style - } \mus - \context Lyrics \nam - >> -} -@end lilypond -@item congas-style -to typeset congas on a two line staff: - -@lilypond[raggedright] -nam = \lyrics { cgh cgho cghm ssh cgl cglo cglm ssl } -mus = \drums { cgh cgho cghm ssh cgl cglo cglm ssl s16 } -\score { - << - \context DrumStaff\with { - \remove Bar_engraver - \remove Time_signature_engraver - drumStyleTable = #congas-style - \override StaffSymbol #'line-count = #2 - - %% this sucks; it will lengthen stems. - \override StaffSymbol #'staff-space = #2 - \override Stem #'transparent = ##t - \override Stem #'Y-extent-callback = ##f - } \mus - \context Lyrics \nam - >> -} -@end lilypond -@item bongos-style -to typeset bongos on a two line staff: - -@lilypond[raggedright] -nam = \lyrics { boh boho bohm ssh bol bolo bolm ssl } -mus = \drums { boh boho bohm ssh bol bolo bolm ssl s16 } -\score { - << - \context DrumStaff\with { - \remove Bar_engraver - \remove Time_signature_engraver - \override StaffSymbol #'line-count = #2 - drumStyleTable = #bongos-style - - %% this sucks; it will lengthen stems. - \override StaffSymbol #'staff-space = #2 - \override Stem #'transparent = ##t - \override Stem #'Y-extent-callback = ##f - } \mus - \context Lyrics \nam - >> -} -@end lilypond - -@item percussion-style -to typeset all kinds of simple percussion on one line staves: -@lilypond[raggedright] -nam = \lyrics { tri trio trim gui guis guil cb cl tamb cab mar hc } -mus = \drums { tri trio trim gui guis guil cb cl tamb cab mar hc s16 } -\score { - << - \context DrumStaff\with{ - \remove Bar_engraver - drumStyleTable = #percussion-style - \override StaffSymbol #'line-count = #1 - \remove Time_signature_engraver - \override Stem #'transparent = ##t - \override Stem #'Y-extent-callback = ##f - } \mus - \context Lyrics \nam - >> -} -@end lilypond -@end table - -If you do not like any of the predefined lists you can define your own -list at the top of your file: - -@lilypond[raggedright,verbatim] -#(define mydrums '( - (bassdrum default #f -1) - (snare default #f 0) - (hihat cross #f 1) - (pedalhihat xcircle "stopped" 2) - (lowtom diamond #f 3) -)) -up = \drums { hh8 hh hh hh hhp4 hhp } -down = \drums { bd4 sn bd toml8 toml } -\score { - \new DrumStaff << - \set DrumStaff.drumStyleTable - = #(alist->hash-table mydrums) - \new DrumVoice { \voiceOne \up } - \new DrumVoice { \voiceTwo \down } - >> -} -@end lilypond - - -@seealso - -Init files: @file{ly/drumpitch-init.ly}. - -Internals: @internalsref{DrumStaff}, @internalsref{DrumVoice}. - -@refbugs - -Short polyphonic notation, @code{<< @dots{} \\ @dots{} >>}, does not -work for @internalsref{DrumVoices}. - -Because general MIDI does not contain rim shots, the sidestick is used -for this purpose instead. - -@node Piano music -@section Piano music - -Piano staves are two normal staves coupled with a brace. The staves -are largely independent, but sometimes voices can cross between the -two staves. The same notation is also used for harps and other key -instruments. The @internalsref{PianoStaff} is especially built to -handle this cross-staffing behavior. In this section we discuss the -@internalsref{PianoStaff} and some other pianistic peculiarities. - - -@menu -* Automatic staff changes:: -* Manual staff switches:: -* Pedals:: -* Arpeggio:: -* Staff switch lines:: -@end menu - -@refbugs - -There is no support for putting chords across staves. You can get -this result by increasing the length of the stem in the lower stave so -it reaches the stem in the upper stave, or vice versa. An example is -included with the distribution as -@inputfileref{input/test,stem-cross-staff.ly}. - -Dynamics are not centered, but kludges do exist. See -@inputfileref{input/template,piano-dynamics.ly}. - -@cindex cross staff stem -@cindex stem, cross staff - -The distance between the two staves is normally fixed across the -entire score. It is possible to tune this per system, but it does -require arcane command incantations. See -@inputfileref{input/test,piano-staff-distance.ly}. - - - - - - -@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 - \autochange \context Voice @{ @dots{}@var{music}@dots{} @} -@end example -The two staffs of the piano staff must be named @code{up} and -@code{down}. - -The autochanger switches on basis of pitch (middle C is the turning -point), and it looks ahead skipping over rests to switch in -advance. Here is a practical example: - -@lilypond[verbatim,raggedright] -\score { \notes \context PianoStaff << - \context Staff = "up" { - \autochange \new Voice \relative c' { - g4 a b c d r4 a g } } - \context Staff = "down" { - \clef bass - s1*2 -} >> } -@end lilypond - -@noindent -In this example, spacer rests are used to prevent the bottom staff from -terminating too soon. - - -@seealso - -In this manual: @ref{Manual staff switches}. - -Internals: @internalsref{AutoChangeMusic}. - - - -@refbugs - -The staff switches often do not end up in optimal places. For high -quality output, staff switches should be specified manually. - - - -@node Manual staff switches -@subsection Manual staff switches - -@cindex manual staff switches -@cindex staff switch, manual - -Voices can be switched between staves manually, using the following command: -@example - \change Staff = @var{staffname} @var{music} -@end example - -@noindent -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"}. - - - -@node Pedals -@subsection Pedals -@cindex Pedals - -Pianos have pedals that alter the way sound are produced. Generally, a -piano has three pedals, sustain, una corda, and sostenuto. - -@syntax - -Piano pedal instruction can be expressed by attaching -@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda}, -@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a -note or chord: - -@lilypond[fragment,verbatim] - c'4\sustainDown c'4\sustainUp -@end lilypond - -What is printed can be modified by setting @code{pedal@var{X}Strings}, -where @var{X} is one of the pedal types: @code{Sustain}, -@code{Sostenuto} or @code{UnaCorda}. Refer to the generated -documentation of @internalsref{SustainPedal} for more information. - -Pedals can also be indicated by a sequence of brackets, by setting the -@code{pedalSustainStyle} property to @code{bracket} objects: - -@lilypond[fragment,verbatim] - \set Staff.pedalSustainStyle = #'bracket - c''4\sustainDown d''4 e''4 - a'4\sustainUp\sustainDown - f'4 g'4 a'4\sustainUp -@end lilypond - -A third style of pedal notation is a mixture of text and brackets, -obtained by setting the @code{pedalSustainStyle} style property to -@code{mixed}: - -@lilypond[fragment,verbatim] - \set Staff.pedalSustainStyle = #'mixed -c''4\sustainDown d''4 e''4 -c'4\sustainUp\sustainDown - f'4 g'4 a'4\sustainUp -@end lilypond - -The default `*Ped.' style for sustain and damper pedals corresponds to -style @code{#'text}. The sostenuto pedal uses @code{mixed} style by -default. - -@lilypond[fragment,verbatim] -c''4\sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4\sostenutoUp -@end lilypond - -For fine-tuning of the appearance of a pedal bracket, the properties -@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of -@code{PianoPedalBracket} objects (see -@internalsref{PianoPedalBracket} in the Program reference) can be modified. For example, the -bracket may be extended to the end of the note head: - -@lilypond[fragment,verbatim] -\override Staff.PianoPedalBracket - #'shorten-pair = #'(0 . -1.0) -c''4\sostenutoDown d''4 e''4 c'4 -f'4 g'4 a'4\sostenutoUp -@end lilypond - -@node Arpeggio -@subsection Arpeggio -@cindex Arpeggio - -@cindex broken arpeggio -@cindex @code{\arpeggio} - -You can specify an arpeggio sign on a chord by attaching an -@code{\arpeggio} to a chord: - - -@lilypond[fragment,relative,verbatim] - \arpeggio -@end lilypond - -When an arpeggio crosses staves, you attach an arpeggio to the chords -in both staves, and set -@internalsref{PianoStaff}.@code{connectArpeggios}: - -@lilypond[fragment,relative,verbatim] - \context PianoStaff << - \set PianoStaff.connectArpeggios = ##t - \new Staff { \arpeggio } - \new Staff { \clef bass \arpeggio } - >> -@end lilypond - -The direction of the arpeggio is sometimes denoted by adding an -arrowhead to the wiggly line: - -@lilypond[fragment,relative,verbatim] - \context Voice { - \arpeggioUp - \arpeggio - \arpeggioDown - \arpeggio - } -@end lilypond - -A square bracket on the left indicates that the player should not -arpeggiate the chord: - -@lilypond[fragment,relative,verbatim] - \arpeggioBracket - \arpeggio -@end lilypond - -@refcommands - -@cindex @code{\arpeggio} -@code{\arpeggio}, -@cindex @code{\arpeggioUp} -@code{\arpeggioUp}, -@cindex @code{\arpeggioDown} -@code{\arpeggioUp}, -@cindex @code{\arpeggioBoth} -@code{\arpeggioBoth}, -@cindex @code{\arpeggioBracket} -@code{\arpeggioBracket}. - -@seealso - -Internals: @internalsref{ArpeggioEvent} music expressions lead to -@internalsref{Arpeggio} objects. Cross staff arpeggios are -@internalsref{PianoStaff}.@internalsref{Arpeggio}. - -@refbugs - -It is not possible to mix connected arpeggios and unconnected -arpeggios in one @internalsref{PianoStaff} at the same time. - -@node Staff switch lines -@subsection Staff switch lines - - -@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 << - \set PianoStaff.followVoice = ##t - \context Staff \context Voice { - c1 - \change Staff=two - b2 a - } - \context Staff=two { \clef bass \skip 1*2 } - >> -@end lilypond - -The associated object is @internalsref{VoiceFollower}. - -@refcommands - -@cindex @code{\showStaffSwitch} -@code{\showStaffSwitch}, -@cindex @code{\hideStaffSwitch} -@code{\hideStaffSwitch}. - - -@node Vocal music -@section Vocal music - -This section discusses how to enter and print lyrics. - -@menu -* Entering lyrics:: -* The Lyrics context:: -* More stanzas:: -* Ambitus:: -@end menu - -@node Entering lyrics -@subsection Entering lyrics - - -@cindex lyrics -@cindex @code{\lyrics} -@cindex punctuation - -Lyrics are entered in a special input mode. This mode is is introduced -by the keyword @code{\lyrics}. In this mode you can enter lyrics, with -punctuation and accents without any hassle. Syllables are entered like -notes, but with pitches replaced by text. For example, -@example - \lyrics @{ Twin-4 kle4 twin- kle litt- le star2 @} -@end example - -A word in Lyrics mode begins with: an alphabetic character, @code{_}, -@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A} -through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^}, -any 8-bit character with ASCII code over 127, or a two-character -combination of a backslash followed by one of @code{`}, @code{'}, -@code{"}, or @code{^}. - -Subsequent characters of a word can be any character that is not a digit -and not white space. One important consequence of this is that a word -can end with @code{@}}. The following example is usually a bug. The -syllable includes a @code{@}}, and hence the opening brace is not balanced: -@example - \lyrics @{ twinkle@} -@end example - -@cindex @code{\property}, in @code{\lyrics} -Similarly, a period following a alphabetic sequence, is included in -the resulting string. As a consequence, spaces must be inserted around -property commands: -@example - \override Score . LyricText #'font-shape = #'italic -@end example - -@cindex @code{_} -@cindex spaces, in lyrics -@cindex quotes, in lyrics - -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: - -@example - \lyrics @{ He said: "\"Let" my peo ple "go\"" @} -@end example - -@cindex hyphens -Hyphens can be entered as ordinary hyphens at the end of a syllable, i.e. -@example - soft- ware -@end example - -These will be attached to the end of the first syllable. - -Centered hyphens are entered using the special `@code{-}@code{-}' lyric -as a separate word between syllables. The hyphen will have variable -length depending on the space between the syllables and it will be -centered between the syllables. - -@cindex melisma -@cindex extender - -When a lyric is sung over many notes (this is called a melisma), this is -indicated with a horizontal line centered between a syllable and the -next one. Such a line is called an extender line, and it is entered as -@code{__}. - -@seealso - -Internals: @internalsref{LyricEvent}, @internalsref{HyphenEvent}, and -@internalsref{ExtenderEvent}. - -Examples: @inputfileref{input/test,lyric-hyphen-retain.ly}. - -@refbugs - -The definition of lyrics mode is too complex. - - - -@node The Lyrics context -@subsection The Lyrics context - -Lyrics are printed by interpreting them in a @internalsref{Lyrics} context: -@example - \context Lyrics \lyrics @dots{} -@end example - -@cindex automatic syllable durations -@cindex @code{\lyricsto} -@cindex lyrics and melodies - -This will place the lyrics according to the durations that were -entered. The lyrics can also be aligned under a given melody -automatically. In this case, it is no longer necessary to enter the -correct duration for each syllable. This is achieved by combining the -melody and the lyrics with the @code{\lyricsto} expression: -@example -\lyricsto @var{name} \new Lyrics @dots{} -@end example - -This aligns the lyrics to the -@c -notes of the @internalsref{Voice} context called @var{name}, which has -to exist. Therefore, normally the @code{Voice} is specified first, and -then the lyrics are specified with @code{\lyricsto}. - -For different or more complex orderings, the best way is to setup the -hierarchy of staves and lyrics first, e.g. -@example -\context ChoirStaff \notes << - \context Lyrics = sopranoLyrics @{ s1 @} - \context Voice = soprano @{ @emph{music} @} - \context Lyrics = tenorLyrics @{ s1 @} - \context Voice = tenor @{ @emph{music} @} ->> -@end example -and then combine the appropriate melodies and lyric lines: -@example - \lyricsto "soprano" \new Lyrics @emph{the lyrics} -@end example - -@noindent -The final input would resemble - -@example - << \context ChoirStaff \notes << @emph{setup the music} >> - \lyricsto "soprano" @emph{etc} - \lyricsto "alto" @emph{etc} - @emph{etc} - >> -@end example - - -The @code{\lyricsto} command detects melismata: it only puts one -syllable under a tied or slurred group of notes. If you want to force -an unslurred group of notes to be a melisma, then insert -@code{\melisma} after the first note of the group, and -@code{\melismaEnd} after the last one, e.g. - -@lilypond[relative=1,raggedright,fragment,verbatim] -<< \context Voice = "lala" { \time 3/4 - f4 g8 - \melisma - f e f - \melismaEnd - e2 } - \lyricsto "lala" \new Lyrics \lyrics { - la di __ daah - } >> -@end lilypond - -In addition, notes are considered a melisma if they are manually -beamed, and automatic beaming (see @ref{Setting automatic beam -behavior}) is switched off. The criteria for deciding melismata -can be tuned with the property @code{melismaBusyProperties}. See -@internalsref{Melisma_translator} for more information. - -When multiple stanzas are put on the same melody, it can happen that -two stanzas have melismata in different locations. This can be -remedied by switching off melismata for one -@internalsref{Lyrics}. This is achieved by setting -the @code{ignoreMelismata} property to @code{#t}. An example is shown -in @inputfileref{input/regression,lyric-combine-new.ly}. - -@cindex SATB -@cindex choral score - -A complete example of a SATB score setup is in the file -@inputfileref{input/template,satb.ly}. - - -@refcommands - -@code{\melisma}, @code{\melismaEnd} -@cindex @code{\melismaEnd} -@cindex @code{\melisma} - -@seealso - -Internals: Music expressions: @internalsref{LyricCombineMusic}, -Contexts: @internalsref{Lyrics}, @internalsref{Melisma_translator}. - -Examples: @inputfileref{input/template,satb.ly}, -@inputfileref{input/regression,lyric-combine-new.ly}. - -@refbugs - -Melismata are not detected automatically, and extender lines must be -inserted by hand. - - -For proper processing of extender lines, the -@internalsref{Lyrics} and @internalsref{Voice} should be -linked. This can be achieved either by using @code{\lyricsto} or by -setting corresponding names for both contexts. The latter is explained -in @ref{More stanzas}. - -@node More stanzas -@subsection More stanzas - -@cindex phrasing, in lyrics - - -The lyrics should be aligned with the note heads of the melody. To -achieve this, each line of lyrics should be marked to correspond with -the melodic line. This is done automatically when @code{\lyricsto}, -but it can also be done manually. - -To this end, give the @internalsref{Voice} context an identity: -@example -\context Voice = duet @{ - \time 3/4 - g2 e4 a2 f4 g2. @} -@end example - -Then set the @internalsref{Lyrics} contexts to names starting with -that identity followed by a dash. In the preceding example, the -@internalsref{Voice} identity is @code{duet}, so the identities of the -@internalsref{Lyrics}s are marked @code{duet-1} and @code{duet-2}: -@example - \context Lyrics = "duet-1" @{ - Hi, my name is bert. @} - \context Lyrics = "duet-2" @{ - Ooooo, ch\'e -- ri, je t'aime. @} -@end example - -The complete example is shown here: -@lilypond[raggedright,verbatim] -\score { - << \notes \relative c'' \context Voice = duet { \time 3/4 - g2 e4 a2 f4 g2. } - \lyrics << \lyricsto "duet" \new Lyrics { - \set stanza = "B." - \set vocNam = "Bert" - Hi, my name is bert. } - \lyricsto "duet" \new Lyrics { - \set stanza = "E." - \set vocNam = "Ernie" - Ooooo, ch\'e -- ri, je t'aime. - } - >> >> -} -@end lilypond - -@cindex stanza number -@cindex singer's names -@cindex name of singer - -Stanza numbers can be added by setting @code{stanza}, e.g. - -@example - \set stanza = "B." - @dots{} - \set stanza = "E." -@end example - -Notice how dots are surrounded with spaces in @code{\lyrics} mode, to -prevent @code{stanza} being interpreted as a single -string. - -This example also demonstrates how names of the singers can be added -using @code{vocalName} analogous to instrument annotations for staves. -A short version may be entered as @code{vocNam}. - -To make empty spaces in lyrics, use @code{\skip}. - - -@seealso - -Internals: Layout objects @internalsref{LyricText} and -@internalsref{VocalName}. Music expressions: -@internalsref{LyricEvent}. - -@refbugs - -@cindex ambiguity - -Input for lyrics introduces a syntactical ambiguity: - -@example -foo = bar -@end example - -@noindent -is interpreted as assigning a string identifier @code{\foo} such that -it contains @code{"bar"}. However, it could also be interpreted as -making or a music identifier @code{\foo} containing the syllable -`bar'. The force the latter interpretation, use -@example - foo = \lyrics bar4 -@end example - - -@node Ambitus -@subsection Ambitus -@cindex ambitus - -The term @emph{ambitus} (plural: ambituses) denotes a range of pitches -for a given voice in a part of music. It also may denote the pitch -range that a musical instrument is capable of playing. Most musical -instruments have their ambitus standardized (or at least there is -agreement upon the minimal ambitus of a particular type of -instrument), such that a composer or arranger of a piece of music can -easily meet the ambitus constraints of the targeted instrument. -However, the ambitus of the human voice depends on individual -physiological state, including education and training of the voice. -Therefore, a singer potentially has to check for each piece of music -if the ambitus of that piece meets his individual capabilities. This -is why the ambitus of a piece may be of particular value to vocal -performers. - -The ambitus is typically notated on a per-voice basis at the very -beginning of a piece, e.g. nearby the initial clef or time signature of -each staff. The range is graphically specified by two note heads, that -represent the minimum and maximum pitch. Some publishers use a textual -notation: they put the range in words in front of the corresponding -staff. LilyPond only supports the graphical ambitus notation. - -To apply, add the @internalsref{Ambitus_engraver} to the -@internalsref{Voice} context, i.e. - -@example - \paper @{ - \translator @{ - \VoiceContext - \consists Ambitus_engraver - @} - @} -@end example - -This results in the following output: - -@lilypond[raggedright] -upper = \notes \relative c { - \clef "treble" - \key c \minor - as'' c e2 bes f cis d4 e f2 g -} -lower = \notes \relative c { - \clef "treble" - \key e \major - e'4 b g a c es fis a cis b a g f e d2 -} -\score { - \context ChoirStaff { - << - \new Staff { \upper } - \new Staff { \lower } - >> - } - \paper { - \translator { - \StaffContext - \consists Ambitus_engraver - } - } -} -@end lilypond - -If you have multiple voices in a single staff, and you want a single -ambitus per staff rather than per each voice, then add the -@internalsref{Ambitus_engraver} to the @internalsref{Staff} context -rather than to the @internalsref{Voice} context. - -It is possible to tune individual ambituses for multiple voices on a -single staff, for example by erasing or shifting them horizontally. An -example is in @inputfileref{input/test,ambitus-mixed.ly}. - -@seealso - -Internals: @internalsref{Ambitus}. - -Examples: @inputfileref{input/regression,ambitus.ly}, -@inputfileref{input/test,ambitus-mixed.ly}. - -@refbugs - -There is no collision handling in the case of multiple per-voice -ambitus. - -@node Tablatures -@section Tablatures - -Tablature notation is used for notating music for plucked string -instruments. It notates pitches not by using note heads, but by -indicating on which string and fret a note must be played. LilyPond -offers limited support for tablature. - -@menu -* Tablatures basic:: -* Non-guitar tablatures:: -@end menu - -@node Tablatures basic -@subsection Tablatures basic -@cindex Tablatures basic - -The string number associated to a note is given as a backslash -followed by a number, e.g. @code{c4\3} for a C quarter on the third -string. By default, string 1 is the highest one, and the tuning -defaults to the standard guitar tuning (with 6 strings). The notes -are printed as tablature, by using @internalsref{TabStaff} and -@internalsref{TabVoice} contexts: - -@lilypond[fragment,verbatim] -\notes \context TabStaff { - a,4\5 c'\2 a\3 e'\1 - e\4 c'\2 a\3 e'\1 -} -@end lilypond - -@cindex minimumFret - -When no string is specified, the first string that does not give a -fret number less than @code{minimumFret} is selected. The default -value for @code{minimumFret} is 0: - - -@example -e8 fis gis a b cis' dis' e' -\set TabStaff.minimumFret = #8 -e8 fis gis a b cis' dis' e' -@end example -@lilypond[noindent] -frag = \notes { - \key e \major - e8 fis gis a b cis' dis' e' - \set TabStaff.minimumFret = #8 - e8 fis gis a b cis' dis' e' -} -\score { - \context StaffGroup << - \context Staff { \clef "G_8" \frag } - \context TabStaff { \frag } - >> -} -@end lilypond - -@seealso - -Internals: @internalsref{TabStaff}, @internalsref{TabVoice}, and -@internalsref{StringNumberEvent}. - -@refbugs - -Chords are not handled in a special way, and hence the automatic -string selector may easily select the same string to two notes in a -chord. - - -@node Non-guitar tablatures -@subsection Non-guitar tablatures -@cindex Non-guitar tablatures - -You can change the number of strings, by setting the number of lines -in the @internalsref{TabStaff}. - -You can change the tuning of the strings. A string tuning is given as -a Scheme list with one integer number for each string, the number -being the pitch (measured in semitones relative to middle C) of an -open string. The numbers specified for @code{stringTuning} are the -numbers of semitones to subtract or add, starting the specified pitch -by default middle C, in string order. Thus, the notes are e, a, d, and -g: - -@lilypond[fragment,verbatim] - \context TabStaff << - \set TabStaff.stringTunings = #'(-5 -10 -15 -20) - - \notes { - a,4 c' a e' e c' a e' - } - >> -@end lilypond - -It is possible to change the Scheme function to format the tablature -note text. The default is @code{fret-number-tablature-format}, which -uses the fret number. For instruments that do not use this notation, -you can create a special tablature formatting function. This function -takes three argument: string number, string tuning and note pitch. - -@refbugs - -No guitar special effects have been implemented. - - - -@node Chord names -@section Chord names -@cindex Chords - -LilyPond has support for both printing chord names. Chords may be -entered in musical chord notation, i.e. @code{< .. >}, but they can -also be entered by name. Internally, the chords are represented as a -set of pitches, so they can be transposed: - - -@lilypond[verbatim,raggedright] -twoWays = \notes \transpose c c' { - \chords { - c1 f:sus4 bes/f - } - - - - } - -\score { - << \context ChordNames \twoWays - \context Voice \twoWays >> } -@end lilypond - -This example also shows that the chord printing routines do not try to -be intelligent. The last chord (@code{f bes d}) is not interpreted as -an inversion. - - -@menu -* Chords mode:: -* Printing chord names:: -@end menu - - -@node Chords mode -@subsection Chords mode -@cindex Chords mode - -Chord mode is a mode where you can input sets of pitches using common -names. It is introduced by the keyword @code{\chords}. -In chords mode, a chord is entered by the root, which is entered -like a common pitch: -@lilypond[fragment,verbatim,relative=1] -\chords { es4. d8 c2 } -@end lilypond -@cindex chord entry -@cindex chord mode - -Other chords may be entered by suffixing a colon, and introducing a -modifier, and optionally, a number: -@c -@lilypond[fragment,verbatim] -\chords { e1:m e1:7 e1:m7 } -@end lilypond -The first number following the root is taken to be the `type' of the -chord, thirds are added to the root until it reaches the specified -number: -@lilypond[fragment,verbatim] - \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 } -@end lilypond - -@cindex root of chord -@cindex additions, in chords -@cindex removals, in chords - -More complex chords may also be constructed adding separate steps -to a chord. Additions are added after the number following -the colon, and are separated by dots: -@c -@lilypond[verbatim,fragment] - \chords { c:5.6 c:3.7.8 c:3.6.13 } -@end lilypond -Chord steps can be altered by suffixing a @code{-} or @code{+} sign -to the number: -@lilypond[verbatim,fragment] - \chords { c:7+ c:5+.3- c:3-.5-.7- } -@end lilypond -Removals are specified similarly, and are introduced by a caret. They -must come after the additions: -@lilypond[verbatim,fragment] - \chords { c^3 c:7^5 c:9^3.5 } -@end lilypond - -Modifiers can be used to change pitches. The following modifiers are -supported: -@table @code -@item m - is the minor chord. This modifier lowers the 3rd and (if present) the 7th step. -@item dim - is the diminished chord. This modifier lowers the 3rd, 5th and (if present) - the 7th step. -@item aug - is the augmented chord. This modifier raises the 5th step. -@item maj - is the major 7th chord. This modifier raises the 7th step if present. -@item sus - is the suspended 4th or 2nd. This modifier removes the 3rd -step. Append either @code{2} or @code{4} to add the 2nd or 4th step to -the chord. -@end table -Modifiers can be mixed with additions: -@lilypond[verbatim,fragment] - \chords { c:sus4 c:7sus4 c:dim7 c:m6 } -@end lilypond - -@cindex modifiers, in chords. -@cindex @code{aug} -@cindex @code{dim} -@cindex @code{maj} -@cindex @code{sus} -@cindex @code{m} - -Since an unaltered 11 does not sound good when combined with an -unaltered 13, the 11 is removed in this case (unless it is added -explicitly): -@c -@lilypond[fragment,verbatim] - \chords { c:13 c:13.11 c:m13 } -@end lilypond - -@cindex @code{/} - -An inversion (putting one pitch of the chord on the bottom), as well -as bass notes, can be specified by appending -@code{/}@var{pitch} to the chord: -@lilypond[fragment,verbatim] - \chords { c1 c/g c/f } -@end lilypond -@cindex @code{/+} - -A bass note can be added instead of transposed out of the chord, -by using @code{/+}@var{pitch}. - -@lilypond[fragment,verbatim] - \chords { c1 c/+g c/+f } -@end lilypond - -Chords is a mode similar to @code{\lyrics}, @code{\notes} etc. Most -of the commands continue to work, for example, @code{r} and -@code{\skip} can be used to insert rests and spaces, and property -commands may be used to change various settings. - - - -@refbugs - -Each step can only be present in a chord once. The following -simply produces the augmented chord, since @code{5+} is interpreted -last: -@cindex clusters -@lilypond[verbatim,fragment] - \chords { c:5.5-.5+ } -@end lilypond - - -@node Printing chord names -@subsection Printing chord names - -@cindex printing chord names -@cindex chord names -@cindex chords - -For displaying printed chord names, use the @internalsref{ChordNames} context. -The chords may be entered either using the notation -described above, or directly using @code{<} and @code{>}: - -@lilypond[verbatim,raggedright] -scheme = \notes { - \chords {a1 b c} -} -\score { - \notes<< - \context ChordNames \scheme - \context Staff \scheme - >> -} -@end lilypond - -You can make the chord changes stand out by setting -@internalsref{ChordNames}.@code{chordChanges} to true. This will only -display chord names when there is a change in the chords scheme and at -the start of a new line: - -@lilypond[verbatim,linewidth=9\cm] -scheme = \chords { - c1:m c:m \break c:m c:m d -} -\score { - \notes << - \context ChordNames { - \set chordChanges = ##t - \scheme } - \context Staff \transpose c c' \scheme - >> -} -@end lilypond - -The default chord name layout is a system for Jazz music, proposed by -Klaus Ignatzek (see @ref{Literature list}). It can be tuned through the -following properties: - -@table @code -@cindex chordNameExceptions -@item chordNameExceptions -This is a list that contains the chords that have special formatting. -For an example, see -@inputfileref{input/regression,chord-name-exceptions.ly}. -@cindex exceptions, chord names. - - -@cindex majorSevenSymbol -@item majorSevenSymbol -This property contains the markup object used for the 7th step, when -it is major. Predefined options are @code{whiteTriangleMarkup} and -@code{blackTriangleMarkup}. See -@inputfileref{input/regression,chord-name-major7.ly} for an example. - -@cindex chordNameSeparator -@item chordNameSeparator -Different parts of a chord name are normally separated by a -slash. By setting @code{chordNameSeparator}, you can specify other -separators, e.g. -@lilypond[fragment,verbatim] -\context ChordNames \chords { - c:7sus4 - \set chordNameSeparator - = \markup { \typewriter "|" } - c:7sus4 } -@end lilypond - -@cindex chordRootNamer -@item chordRootNamer -The root of a chord is usually printed as a letter with an optional -alteration. The transformation from pitch to letter is done by this -function. Special note names (for example, the German ``H'' for a -B-chord) can be produced by storing a new function in this property. - -The predefined variables @code{\germanChords}, -@code{\semiGermanChords} set these variables. - - -@cindex chordNoteNamer -@item chordNoteNamer -The default is to print single pitch, e.g. the bass note, using the -@code{chordRootNamer}. The @code{chordNoteNamer} property can be set -to a specialized function to change this behavior. For example, the -base can be printed in lower case. - -@end table - - -There are also two other chord name schemes implemented: an alternate -Jazz chord notation, and a systematic scheme called Banter chords. The -alternate jazz notation is also shown on the chart in @ref{Chord name -chart}. Turning on these styles is described in the input file -@inputfileref{input/test,chord-names-jazz.ly}. - -@cindex Banter -@cindex jazz chords -@cindex chords, jazz - - -@refcommands - -@cindex @code{\germanChords} -@code{\germanChords}, -@cindex @code{\semiGermanChords} -@code{\semiGermanChords}. - - - - -@seealso - -Examples: @inputfileref{input/regression,chord-name-major7.ly}, -@inputfileref{input/regression,chord-name-exceptions.ly}, -@inputfileref{input/test,chord-names-jazz.ly}, -@inputfileref{input/test,chord-names-german.ly}. - -Init files: @file{scm/chords-ignatzek.scm}, and @file{scm/chord-entry.scm}. - - -@refbugs - -Chord names are determined solely from the list of pitches. Chord -inversions are not identified, and neither are added bass notes. This -may result in strange chord names when chords are entered with the -@code{< .. >} syntax. - - - - -@node Orchestral music -@section Orchestral music - -@cindex Writing parts - -Orchestral music involves some special notation, both in the full -score and the individual parts. This section explains how to tackle -some common problems in orchestral music. - - - -@menu -* Multiple staff contexts:: -* Rehearsal marks:: -* Bar numbers:: -* Instrument names:: -* Transpose:: -* Instrument transpositions:: -* Multi measure rests:: -* Automatic part combining:: -* Hiding staves:: -* Different editions from one source:: -* Quoting other voices:: -@end menu - -@node Multiple staff contexts -@subsection Multiple staff contexts - -Polyphonic scores consist of many staves. These staves can be -constructed in three different ways: -@itemize @bullet -@item The group is started with a brace at the left. This is done with the -@internalsref{GrandStaff} context. -@item The group is started with a bracket. This is done with the -@internalsref{StaffGroup} context -@item The group is started with a vertical line. This is the default -for the score. -@end itemize - -@cindex Staff, multiple -@cindex bracket, vertical -@cindex brace, vertical -@cindex grand staff -@cindex staff group - - - - -@node Rehearsal marks -@subsection Rehearsal marks -@cindex Rehearsal marks -@cindex mark -@cindex @code{\mark} - -To print a rehearsal mark, use the @code{\mark} command: -@lilypond[fragment,verbatim] -\relative c'' { - c1 \mark \default - c1 \mark \default - c1 \mark #8 - c1 \mark \default - c1 \mark \default -} -@end lilypond - -@noindent -(The letter I is skipped in accordance with engraving traditions.) - -The mark is incremented automatically if you use @code{\mark -\default}, but you can also use an integer argument to set the mark -manually. The value to use is stored in the property -@code{rehearsalMark}. - -The style is defined by the property @code{markFormatter}. It is a -function taking the current mark (an integer) and the current context -as argument. It should return a markup object. In the following -example, @code{markFormatter} is set to a canned procedure. After a -few measures, it is set to function that produces a boxed number. - -@lilypond[verbatim,fragment,relative=1] - \set Score.markFormatter = #format-mark-numbers - c1 \mark \default - c1 \mark \default - \set Score.markFormatter - = #(lambda (mark context) - (make-bold-markup (make-box-markup (number->string mark)))) - c1 \mark \default - c1 \mark \default -@end lilypond - -The file @file{scm/translation-functions.scm} contains the definitions -of @code{format-mark-numbers} (the default format) and -@code{format-mark-letters}. They can be used as inspiration for other -formatting functions. - - -@cindex coda on bar line -@cindex segno on bar line -@cindex fermata on bar line -@cindex bar lines, symbols on - -The @code{\mark} command can also be used to put signs like coda, -segno and fermatas on a bar line. Use @code{\markup} to -to access the appropriate symbol: - -@lilypond[fragment,verbatim,relative=1] - c1 \mark \markup { \musicglyph #"scripts-ufermata" } - c1 -@end lilypond - -In this case, during line breaks, marks must also be printed at the -end of the line, and not at the beginning. Use the following to force -that behavior: -@example -\override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible -@end example - -@cindex fermatas -@cindex coda -@cindex segno -@cindex bar lines, putting symbols on - -@seealso - -Internals: @internalsref{MarkEvent}, @internalsref{RehearsalMark}. - -Init files: @file{scm/translation-functions.scm} contains the -definition of @code{format-mark-numbers} and -@code{format-mark-letters}. They can be used as inspiration for other -formatting functions. - -Examples: @inputfileref{input/regression,rehearsal-mark-letter.ly}, -@inputfileref{input/regression,rehearsal-mark-number.ly}. - - -@node Bar numbers -@subsection Bar numbers - - -@cindex bar numbers -@cindex measure numbers -@cindex currentBarNumber - -Bar numbers are printed by default at the start of the line. The -number itself is stored in the -@code{currentBarNumber} property, -which is normally updated automatically for every measure. - -Bar numbers can be typeset at regular intervals instead of at the -beginning of each line. This is illustrated in the following example, -whose source is available as -@inputfileref{input/test,bar-number-regular-interval.ly}: - -@lilypondfile[]{bar-number-regular-interval.ly} - - -@seealso - -Internals: @internalsref{BarNumber}. - -Examples: @inputfileref{input/test,bar-number-every-five-reset.ly}, -and @inputfileref{input/test,bar-number-regular-interval.ly}. - -@refbugs - -Bar numbers can collide with the @internalsref{StaffGroup} bracket, if -there is one at the top. To solve this, the -@code{padding} property of @internalsref{BarNumber} can be -used to position the number correctly. - -@node Instrument names -@subsection Instrument names - -In an orchestral score, instrument names are printed left side of the -staves. - -This can be achieved by setting @internalsref{Staff}.@code{instrument} -and @internalsref{Staff}.@code{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: - -@quotation -@lilypond[verbatim,raggedright] - \set Staff.instrument = "ploink " { c''4 } -@end lilypond -@end quotation - -You can also use markup texts to construct more complicated instrument -names: - -@quotation -@lilypond[fragment,verbatim,raggedright] - \notes { - \set Staff.instrument = \markup { - \column < "Clarinetti" - { "in B" - \smaller \flat - } - > - } - { c''1 } - } -@end lilypond -@end quotation - -@seealso - -Internals: @internalsref{InstrumentName}. - -@refbugs - -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} - -A music expression can be transposed with @code{\transpose}. The syntax -is -@example - \transpose @var{from} @var{to} @var{musicexpr} -@end example - -This means that @var{musicexpr} is transposed by the interval between -the pitches @var{from} and @var{to}: any note with pitch @code{from} -is changed to @code{to}. - - -For example, consider a piece written in the key of D major. If -this piece is a little too low for its performer, it can be -transposed up to E major with -@example - \transpose d e @dots{} -@end example - -Consider a part written for violin (a C instrument). If -this part is to be played on the A clarinet, the following -transposition will produce the appropriate part - -@example - \transpose a c @dots{} -@end example - -Since @var{from} and @var{to} are pitches, @code{\transpose} must be -inside a @code{\notes} section. @code{\transpose} distinguishes -between enharmonic pitches: both @code{\transpose c cis} or -@code{\transpose c des} will transpose up half a tone. The first -version will print sharps and the second version will print flats: - -@lilypond[raggedright,verbatim] -mus =\notes { \key d \major cis d fis g } -\score { \notes \context Staff { - \clef "F" \mus - \clef "G" - \transpose c g' \mus - \transpose c f' \mus -}} -@end lilypond - - -@seealso - -Internals: @internalsref{TransposedMusic}, and -@internalsref{UntransposableMusic}. - -@refbugs - -If you want to use both @code{\transpose} and @code{\relative}, then -you must put @code{\transpose} outside of @code{\relative}, since -@code{\relative} will have no effect music that appears inside a -@code{\transpose}. - -@node Instrument transpositions -@subsection Instrument transpositions - -The key of a transposing instrument can also be specified. This -applies to many wind instruments, for example, clarinets (B-flat, A and -E-flat), horn (F) and trumpet (B-flat, C, D and E-flat). - -@syntax - -The transposition is entered after the keyword @code{\transposition}: - -@example - \transposition bes %% B-flat clarinet -@end example - -This command sets the property @code{instrumentTuning}. The value of -this property is used for MIDI output and quotations. It does not -affect how notes are printed in the current staff. - -@cindex transposition, MIDI -@cindex transposition, instrument - - -@node Multi measure rests -@subsection Multi measure rests -@cindex multi measure rests -@cindex Rests, multi measure - -@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, empty measures will not -be expanded, and the appropriate number is added automatically: - -@lilypond[fragment,verbatim] - \time 4/4 r1 | R1 | R1*2 - \set Score.skipBars = ##t R1*17 R1*4 -@end lilypond - -The @code{1} in @code{R1} is similar to the duration notation used for -notes. Hence, for time signatures other than 4/4, you must enter other -durations. This can be done with augmentation dots or fractions: - -@lilypond[fragment,verbatim] - \set Score.skipBars = ##t - \time 3/4 - R2. | R2.*2 - \time 13/8 - R1*13/8 - R1*13/8*12 -@end lilypond - -An @code{R} spanning a single measure is printed as either a whole rest -or a breve, centered in the measure regardless of the time signature. - -@cindex text on multi-measure rest -@cindex script on multi-measure rest -@cindex fermata on multi-measure rest - -Texts can be added to multi-measure rests by using the -@var{note}-@code{markup} syntax (see @ref{Text markup}). In this case, the number is -replaced. If you need both texts and the number, you must add the -number by hand. A variable (@code{\fermataMarkup}) is provided for -adding fermatas: - - -@lilypond[verbatim,fragment] - \time 3/4 - R2._\markup { "Ad lib" } - R2.^\fermataMarkup -@end lilypond - -If you want to have a text on the left end of a multi-measure rest, -attach the text to a zero-length skip note, i.e. - -@example - s1*0^"Allegro" - R1*4 -@end example - - -@cindex whole rests for a full measure - -@seealso - -Internals: @internalsref{MultiMeasureRestEvent}, -@internalsref{MultiMeasureTextEvent}, -@internalsref{MultiMeasureRestMusicGroup}, and -@internalsref{MultiMeasureRest}. - -The layout object @internalsref{MultiMeasureRestNumber} is for the -default number, and @internalsref{MultiMeasureRestText} for user -specified texts. - -@refbugs - -It is not possible to use fingerings (e.g. @code{R1-4}) to put numbers -over multi-measure rests. - -@cindex condensing rests - -There is no way to automatically condense multiple rests into a single -multimeasure rest. Multi measure rests do not take part in rest -collisions. - -Be careful when entering multimeasure rests followed by whole -notes. The following will enter two notes lasting four measures each: -@example - R1*4 cis cis -@end example -When @code{skipBars} is set, then the result will look OK, but the -bar numbering will be off. - -@node Automatic part combining -@subsection Automatic part combining -@cindex automatic part combining -@cindex part combiner - - -Automatic part combining is used to merge two parts of music onto a -staff. It is aimed 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 are identified and can be marked. - -@syntax - -The syntax for part combining is - -@example - \partcombine @var{musicexpr1} @var{musicexpr2} -@end example - -The music expressions will be interpreted as @internalsref{Voice} contexts. - -The following example demonstrates the basic functionality of the part -combiner: putting parts on one staff, and setting stem directions and -polyphony: - -@lilypond[verbatim,raggedright,fragment,relative=1] - \new Staff \partcombine - { - g a( b) r - } - { - g r4 r f - } -@end lilypond - -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,raggedright,fragment,relative=1] - \new Staff << - \set Staff.soloADue = ##f - \partcombine - { - g a( b) r - } - { - g r4 r f - } >> -@end lilypond - -@seealso - -Internals: @internalsref{PartCombineMusic}, -@internalsref{SoloOneEvent}, and -@internalsref{SoloTwoEvent}, and -@internalsref{UnisonoEvent}. - -@refbugs - -In @code{soloADue} mode, when the two voices play the same notes on and -off, the part combiner may typeset @code{a2} more than once in a -measure. - -@code{\partcombine} can not be inside @code{\times}. - -Internally, the @code{\partcombine} interprets both arguments as -@code{Voice}s named @code{one} and @code{two}, and then decides when -the parts can be combined. Consequently, if the arguments switch to -differently named @internalsref{Voice} contexts, then the events in -those will be ignored. - -@node Hiding staves -@subsection Hiding staves - -@cindex Frenched scores -@cindex Hiding staves - -In orchestral scores, staff lines that only have rests are usually -removed. This saves some space. This style is called `French Score'. -For @internalsref{Lyrics}, -@internalsref{ChordNames} and @internalsref{FiguredBass}, this is -switched on by default. When these line of these contexts turn out -empty after the line-breaking process, they are removed. - -For normal staves, a specialized @internalsref{Staff} context is -available, which does the same: staves containing nothing (or only -multi measure rests) are removed. The context definition is stored in -@code{\RemoveEmptyStaffContext} variable. Observe how the second staff -in this example disappears in the second line: - - -@lilypond[verbatim] -\score { - \notes \relative c' << - \new Staff { e4 f g a \break c1 } - \new Staff { c4 d e f \break R1 } - >> - \paper { - linewidth = 6.\cm - \translator { \RemoveEmptyStaffContext } - } -} -@end lilypond - -The first page shows all staffs in full. If they should be removed -from the first page too, set @code{remove-first} to false -in @internalsref{RemoveEmptyVerticalGroup}. - -Another application is making ossia sections, i.e. alternative -melodies on a separate piece of staff, with help of a Frenched -staff. See @inputfileref{input/test,ossia.ly} for an example. - - -@node Different editions from one source -@subsection Different editions from one source - -The @code{\tag} command marks music expressions with a name. These -tagged expressions can be filtered out later. With this mechanism it -is possible to make different versions of the same music source. - -In the following example, we see two versions of a piece of music, one -for the full score, and one with cue notes for the instrumental part: - -@example - c1 - \relative c' << - \tag #'part << - R1 \\ - @{ - \set fontSize = #-1 - c4_"cue" f2 g4 @} - >> - \tag #'score R1 - >> - c1 -@end example - -The same can be applied to articulations, texts, etc.: they are -made by prepending -@example - -\tag #@var{your-tag} -@end example -to an articulation, for example, -@example - c1-\tag #'part ^4 -@end example - -This defines a note with a conditional fingering indication. - -By applying the @code{remove-tag} function, tagged expressions can be -filtered. For example, -@example -\simultaneous @{ - @var{the music} - \apply #(remove-tag 'score) @var{the music} - \apply #(remove-tag 'part) @var{the music} -@} -@end example -would yield - -@lilypondfile[]{tag-filter.ly} - -The argument of the @code{\tag} command should be a symbol, or a list -of symbols, for example, -@example - \tag #'(original-part transposed-part) @dots{} -@end example - -@seealso - -Examples: @inputfileref{input/regression,tag-filter.ly}. - - -@node Quoting other voices -@subsection Quoting other voices - -With quotations, fragments of other parts can be inserted into a part -directly. Before a part can be quoted, it must be marked especially as -quotable. This is done with code @code{\addquote} command. The -quotation may then be done with @code{\quote} - -@example - \addquote @var{name} @var{music} - \quote @var{name} @var{duration} -@end example - -@noindent - -Here, @var{name} is an identifying string. The @var{music} is any kind -of music. This is an example of @code{\addquote}: - -@verbatim -\addquote clarinet \notes\relative c' { - f4 fis g gis -} -@end verbatim - -During a part, a piece of music can be quoted with the @code{\quote} -command. - -@verbatim - \quote clarinet 2. -@end verbatim - -This would cite 3 quarter notes (a dotted half note) of the previously -added clarinet voice. - -Quotations take into account the transposition both source and target -instruments, if they are specified using the @code{\transposition} command. - -@lilypond[verbatim fragment] -\addquote clarinet \notes\relative c' { - \transposition bes - f4 fis g gis -} -\score { - \notes { - e'8 f'8 \quote clarinet 2 -} } -@end lilypond - -@refbugs - -Only the contents of the first @internalsref{Voice} occurring in an -@code{\addquote} command will be considered for quotation, so -@var{music} can not contain @code{\new} and @code{\context Voice} -statements that would switch to a different Voice. - - -@seealso - -In this manual: @ref{Instrument transpositions}. - -Examples: @inputfileref{input/regression,quote.ly} -@inputfileref{input/regression,quote-transposition.ly} - -Internals: @internalsref{QuoteMusic}. - - - - - -@node Ancient notation -@section Ancient notation - -@cindex Vaticana, Editio -@cindex Medicaea, Editio -@cindex hufnagel -@cindex Petrucci -@cindex mensural - -@c [TODO: write more comprehensive introduction on ancient notation] - -Support for ancient notation is still under heavy development. -Regardless of all of the current limitations (see the bugs section -below for details), it includes features for mensural -notation and Gregorian Chant notation. There is also limited support -for figured bass notation. - -Many graphical objects provide a @code{style} property, see -@ref{Ancient note heads}, @ref{Ancient accidentals}, @ref{Ancient -rests}, @ref{Ancient clefs}, @ref{Ancient flags} and @ref{Ancient time -signatures}. By manipulating such a grob property, the typographical -appearance of the affected graphical objects can be accommodated for a -specific notation flavor without need for introducing any new -notational concept. - - -Other aspects of ancient notation can not that easily be expressed as -in terms of just changing a style property of a graphical object. -Therefore, some notational concepts are introduced specifically for -ancient notation, see @ref{Custodes}, @ref{Divisiones}, -@ref{Ligatures}, and @ref{Figured bass}. - - -@menu -* Ancient note heads:: -* Ancient accidentals:: -* Ancient rests:: -* Ancient clefs:: -* Ancient flags:: -* Ancient time signatures:: -* Custodes:: -* Divisiones:: -* Ligatures:: -* Figured bass:: -* Vaticana style contexts:: -@end menu - -If this all is way too much of documentation for you, and you just -want to dive into typesetting without worrying too much about the -details on how to customize a context, then you may have a look at the -predefined contexts (see @ref{Vaticana style contexts}). Use them to -set up predefined style-specific voice and staff contexts, and -directly go ahead with the note entry. - -@refbugs - -Ligatures need special spacing that has not yet been implemented. As -a result, there is too much space between ligatures most of the time, -and line breaking often is unsatisfactory. Also, lyrics do not -correctly align with ligatures. - -Accidentals must not be printed within a ligature, but instead need to -be collected and printed in front of it. - -Augmentum dots within ligatures are not handled correctly. - - -@node Ancient note heads -@subsection Ancient note heads - -@cindex note heads - -@syntax - -For ancient notation, a note head style other than the @code{default} -style may be chosen. This is accomplished by setting the @code{style} -property of the NoteHead object to the desired value (@code{baroque}, -@code{neo_mensural} or @code{mensural}). The @code{baroque} style -differs from the @code{default} style only in using a square shape for -@code{\breve} note heads. The @code{neo_mensural} style differs from -the @code{baroque} style in that it uses rhomboidal heads for whole -notes and all smaller durations. Stems are centered on the note -heads. This style is in particular useful when transcribing mensural -music, e.g. for the incipit. The @code{mensural} style finally -produces note heads that mimic the look of note heads in historic -printings of the 16th century. - -The following example demonstrates the @code{neo_mensural} style: - -@lilypond[fragment,raggedright,verbatim] - \override NoteHead #'style = #'neo_mensural - a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 -@end lilypond - -When typesetting a piece in Gregorian Chant notation, a Gregorian -ligature engraver will automatically select the proper note heads, -such there is no need to explicitly set the note head style. Still, -the note head style can be set e.g. to @code{vaticana_punctum} to -produce punctum neumes. Similarly, a mensural ligature engraver is -used to automatically assemble mensural ligatures. See -@ref{Ligatures} for how ligature engravers work. - -@seealso - -In this manual: -@ref{Percussion staves} use note head styles of their own that are -frequently used in contemporary music notation. - -Examples: @inputfileref{input/regression,note-head-style.ly} gives an -overview over all available note head styles. - - -@node Ancient accidentals -@subsection Ancient accidentals - -@cindex accidentals - -@syntax - -Use the @code{style} property of grob @internalsref{Accidental} to -select ancient accidentals. Supported styles are -@code{mensural}, @code{vaticana}, @code{hufnagel} and @code{medicaea}. - -@lilypond[raggedright,staffsize=26] -\score { - \notes { - \fatText - s - ^\markup { - \column < - "vaticana" - { " " \musicglyph #"accidentals-vaticana-1" - " " \musicglyph #"accidentals-vaticana0" } - > - \column < - "medicaea" - { " " \musicglyph #"accidentals-medicaea-1" } - > - \column < - "hufnagel" - { " " \musicglyph #"accidentals-hufnagel-1" } - > - \column < - "mensural" - { " " \musicglyph #"accidentals-mensural-1" - " " \musicglyph #"accidentals-mensural1" } - > - } - } - \paper { - raggedright = ##t - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator{ - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \remove "Time_signature_engraver" - \remove "Staff_symbol_engraver" - minimumVerticalExtent = ##f - } - } -} -@end lilypond - -As shown, not all accidentals are supported by each style. When -trying to access an unsupported accidental, LilyPond will switch to a -different style, as demonstrated in -@inputfileref{input/test,ancient-accidentals.ly}. - -Similarly to local accidentals, the style of the key signature can be -controlled by the @code{style} property of the -@internalsref{KeySignature} grob. - -@seealso - -In this manual: @ref{Pitches}, @ref{Chromatic alterations} and -@ref{Accidentals} give a general introduction into the use of -accidentals. @ref{Key signature} gives a general introduction into -the use of key signatures. - -Internals: @internalsref{KeySignature}. - -Examples: @inputfileref{input/test,ancient-accidentals.ly}. - -@node Ancient rests -@subsection Ancient rests - -@cindex rests - -@syntax - -Use the @code{style} property of grob @internalsref{Rest} to select -ancient accidentals. Supported styles are @code{classical}, -@code{neo_mensural} and @code{mensural}. @code{classical} differs -from the @code{default} style only in that the quarter rest looks like -a horizontally mirrored 8th rest. The @code{neo_mensural} style suits -well for e.g. the incipit of a transcribed mensural piece of music. -The @code{mensural} style finally mimics the appearance of rests as -in historic prints of the 16th century. - -The following example demonstrates the @code{neo_mensural} style: - -@lilypond[fragment,raggedright,verbatim] - \override Rest #'style = #'neo_mensural - r\longa r\breve r1 r2 r4 r8 r16 -@end lilypond - -There are no 32th and 64th rests specifically for the mensural or -neo-mensural style. Instead, the rests from the default style will be -taken. See @inputfileref{input/test,rests.ly} for a chart of all -rests. - -There are no rests in Gregorian Chant notation; instead, it uses -@ref{Divisiones}. - -@seealso - -In this manual: @ref{Rests} gives a general introduction into the use of rests. - - -@node Ancient clefs -@subsection Ancient clefs - -@cindex clefs - -@syntax - -LilyPond supports a variety of clefs, many of them ancient. - -The following table shows all ancient clefs that are supported via the -@code{\clef} command. Some of the clefs use the same glyph, but -differ only with respect to the line they are printed on. In such -cases, a trailing number in the name is used to enumerate these clefs. -Still, you can manually force a clef glyph to be typeset on an -arbitrary line, as described in @ref{Clef}. The note printed to the -right side of each clef in the example column denotes the @code{c'} -with respect to that clef. - -@multitable @columnfractions .3 .3 .3 .1 - -@item -@b{Glyph Name} @tab -@b{Description} @tab -@b{Supported Clefs} @tab -@b{Example} - -@item -@code{clefs-neo_mensural_c} @tab -modern style mensural C clef @tab -@code{neo_mensural_c1}, @code{neo_mensural_c2}, -@code{neo_mensural_c3}, @code{neo_mensural_c4} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "neo_mensural_c2" c -@end lilypond - -@item -@code{clefs-petrucci_c1} -@code{clefs-petrucci_c2} -@code{clefs-petrucci_c3} -@code{clefs-petrucci_c4} -@code{clefs-petrucci_c5} - -@tab -petrucci style mensural C clefs, for use on different staff lines -(the examples shows the 2nd staff line C clef). - -@tab -@code{petrucci_c1} -@code{petrucci_c2} -@code{petrucci_c3} -@code{petrucci_c4} -@code{petrucci_c5} - -@tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "petrucci_c2" c -@end lilypond - -@item -@code{clefs-petrucci_f} @tab -petrucci style mensural F clef @tab -@code{petrucci_f} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "petrucci_f" c -@end lilypond - -@item -@code{clefs-petrucci_g} @tab -petrucci style mensural G clef @tab -@code{petrucci_g} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "petrucci_g" c -@end lilypond - -@item -@code{clefs-mensural_c} @tab -historic style mensural C clef @tab -@code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3}, -@code{mensural_c4} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "mensural_c2" c -@end lilypond - -@item -@code{clefs-mensural_f} @tab -historic style mensural F clef @tab -@code{mensural_f} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "mensural_f" c -@end lilypond - -@item -@code{clefs-mensural_g} @tab -historic style mensural G clef @tab -@code{mensural_g} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "mensural_g" c -@end lilypond - -@item -@code{clefs-vaticana_do} @tab -Editio Vaticana style do clef @tab -@code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3} @tab -@lilypond[relative,notime] - \override Staff.StaffSymbol #'line-count = #4 -\override Staff.TimeSignature #'transparent = ##t -\clef "vaticana_do2" c -@end lilypond - -@item -@code{clefs-vaticana_fa} @tab -Editio Vaticana style fa clef @tab -@code{vaticana_fa1}, @code{vaticana_fa2} @tab -@lilypond[relative,notime] - \override Staff.StaffSymbol #'line-count = #4 -\override Staff.TimeSignature #'transparent = ##t -\clef "vaticana_fa2" c -@end lilypond - -@item -@code{clefs-medicaea_do} @tab -Editio Medicaea style do clef @tab -@code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3} @tab -@lilypond[relative,notime] - \override Staff.StaffSymbol #'line-count = #4 -\override Staff.TimeSignature #'transparent = ##t -\clef "medicaea_do2" c -@end lilypond - -@item -@code{clefs-medicaea_fa} @tab -Editio Medicaea style fa clef @tab -@code{medicaea_fa1}, @code{medicaea_fa2} @tab -@lilypond[relative,notime] - \override Staff.StaffSymbol #'line-count = #4 -\override Staff.TimeSignature #'transparent = ##t -\clef "medicaea_fa2" c -@end lilypond - -@item -@code{clefs-hufnagel_do} @tab -historic style hufnagel do clef @tab -@code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3} @tab -@lilypond[relative,notime] - \override Staff.StaffSymbol #'line-count = #4 -\override Staff.TimeSignature #'transparent = ##t -\clef "hufnagel_do2" c -@end lilypond - -@item -@code{clefs-hufnagel_fa} @tab -historic style hufnagel fa clef @tab -@code{hufnagel_fa1}, @code{hufnagel_fa2} @tab -@lilypond[relative,notime] - \override Staff.StaffSymbol #'line-count = #4 -\override Staff.TimeSignature #'transparent = ##t -\clef "hufnagel_fa2" c -@end lilypond - -@item -@code{clefs-hufnagel_do_fa} @tab -historic style hufnagel combined do/fa clef @tab -@code{hufnagel_do_fa} @tab -@lilypond[relative,notime] -\override Staff.TimeSignature #'transparent = ##t -\clef "hufnagel_do_fa" c -@end lilypond - -@end multitable - -@c --- This should go somewhere else: --- -@c @item modern style percussion clef (glyph: @code{clefs-percussion}) -@c -@c Supported clefs: -@c @code{percussion} -@c -@c @lilypond{\override Staff.TimeSignature #'transparent = ##t \clef "percussion" c'} -@c -@c @item modern style tab clef (glyph: @code{clefs-tab}) -@c -@c Supported clefs: -@c @code{tab} -@c -@c @lilypond{\context Staff \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #6 \override Staff.TimeSignature #'transparent = ##t \clef "tab" c'} - -@emph{Modern style} means ``as is typeset in contemporary editions of -transcribed mensural music''. - -@emph{Petrucci style} means ``inspired by printings published by the -famous engraver Petrucci (1466-1539)''. - -@emph{Historic style} means ``as was typeset or written in historic -editions (other than those of Petrucci)''. - -@emph{Editio XXX style} means ``as is/was printed in Editio XXX''. - -Petrucci used C clefs with differently balanced left-side vertical -beams, depending on which staff line it is printed. - -@seealso - -In this manual: for the percussion clef, see @ref{Percussion staves}. -For the @code{TAB} clef, see @ref{Tablatures}. - -Internals: for modern clefs, see @ref{Clef}. - -@refbugs - -The mensural g clef is temporarily mapped to the Petrucci g clef, -until a new mensural g clef will have been implemented. - - - -@node Ancient flags -@subsection Ancient flags - -@cindex flags - -@syntax - -Use the @code{flag-style} property of grob @internalsref{Stem} to -select ancient flags. Besides the @code{default} flag style, - only @code{mensural} style is supported: - -@lilypond[fragment,raggedright,verbatim] - \override Stem #'flag-style = #'mensural - \override Stem #'thickness = #1.0 - \override NoteHead #'style = #'mensural - \autoBeamOff - c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8 - c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32 -@end lilypond - -Note that the innermost flare of each mensural flag always is -vertically aligned with a staff line. If you do not like this -behavior, you can set the @code{adjust-if-on-staffline} property of -grob @internalsref{Stem} to @code{##f}. Then, the vertical position -of the end of each flare is different between notes on staff lines and -notes between staff lines: - -@lilypond[fragment,raggedright] - \override Stem #'flag-style = #'mensural - \override Stem #'thickness = #1.0 - \override Stem #'adjust-if-on-staffline = ##f - \override NoteHead #'style = #'mensural - \autoBeamOff - c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8 - c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32 -@end lilypond - -There is no particular flag style for neo-mensural notation. Hence, -when typesetting e.g. the incipit of a transcribed piece of mensural -music, the default flag style should be used. There are no flags in -Gregorian Chant notation. - - -@node Ancient time signatures -@subsection Ancient time signatures - -@cindex time signatures - -@syntax - -There is limited support for mensural time signatures. The -glyphs are hard-wired to particular time fractions. In other words, -to get a particular mensural signature glyph with the @code{\time n/m} -command, @code{n} and @code{m} have to be chosen according to the -following table: - -@lilypond -\score { - \notes { - \set Score.timing = ##f - \set Score.barAlways = ##t - s_\markup { "$\\backslash$time 4/4" } - ^\markup { " " \musicglyph #"timesig-neo_mensural4/4" } - s - s_\markup { "$\\backslash$time 2/2" } - ^\markup { " " \musicglyph #"timesig-neo_mensural2/2" } - s - s_\markup { "$\\backslash$time 6/4" } - ^\markup { " " \musicglyph #"timesig-neo_mensural6/4" } - s - s_\markup { "$\\backslash$time 6/8" } - ^\markup { " " \musicglyph #"timesig-neo_mensural6/8" } - \break - s_\markup { "$\\backslash$time 3/2" } - ^\markup { " " \musicglyph #"timesig-neo_mensural3/2" } - s - s_\markup { "$\\backslash$time 3/4" } - ^\markup { " " \musicglyph #"timesig-neo_mensural3/4" } - s - s_\markup { "$\\backslash$time 9/4" } - ^\markup { " " \musicglyph #"timesig-neo_mensural9/4" } - s - s_\markup { "$\\backslash$time 9/8" } - ^\markup { " " \musicglyph #"timesig-neo_mensural9/8" } - \break - s_\markup { "$\\backslash$time 4/8" } - ^\markup { " " \musicglyph #"timesig-neo_mensural4/8" } - s - s_\markup { "$\\backslash$time 2/4" } - ^\markup { " " \musicglyph #"timesig-neo_mensural2/4" } - \break - } - \paper { - indent = 0.0 - raggedright = ##t - \translator { - \StaffContext - \remove Staff_symbol_engraver - \remove Clef_engraver - \remove Time_signature_engraver - } - } -} -@end lilypond - -Use the @code{style} property of grob @internalsref{TimeSignature} to -select ancient time signatures. Supported styles are -@code{neo_mensural} and @code{mensural}. The above table uses the -@code{neo_mensural} style. This style is appropriate e.g. for the -incipit of transcriptions of mensural pieces. The @code{mensural} -style mimics the look of historical printings of the 16th century. - -@inputfileref{input/test,time.ly} gives an overview over all available -ancient and modern styles. - -@seealso - -Internals: @ref{Time signature} gives a general introduction into the use of time -signatures. - -@refbugs - -Mensural signature glyphs are mapped to time fractions in a -hard-wired way. This mapping is sensible, but still arbitrary: given -a mensural time signature, the time fraction represents a modern meter -that usually will be a good choice when transcribing a mensural piece -of music. For a particular piece of mensural music, however, the -mapping may be unsatisfactory. In particular, the mapping assumes a -fixed transcription of durations (e.g. brevis = half note in 2/2, -i.e. 4:1). Some glyphs (such as the alternate glyph for 6/8 meter) -are not at all accessible through the @code{\time} command. - -Mensural time signatures are supported typographically, but not yet -musically. The internal representation of durations is -based on a purely binary system; a ternary division such as 1 brevis = -3 semibrevis (tempus perfectum) or 1 semibrevis = 3 minima (cum -prolatione maiori) is not correctly handled: event times in ternary -modes will be badly computed, resulting e.g. in horizontally -misaligned note heads, and bar checks are likely to erroneously fail. - -The syntax and semantics of the @code{\time} command for mensural -music is subject to change. - -@node Custodes -@subsection Custodes - -@cindex custos -@cindex custodes - -A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a -symbol that appears at the end of a staff. 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. - -Custodes were frequently used in music notation until the 17th -century. Nowadays, they have survived only in a few particular forms -of musical notation such as contemporary editions of Gregorian chant -like the @emph{editio vaticana}. There are different custos glyphs -used in different flavors of notational style. - -@syntax - -For typesetting custodes, just put a @internalsref{Custos_engraver} into the -@internalsref{Staff} context when declaring the @code{\paper} block, -as shown in the following example: - -@example -\paper @{ - \translator @{ - \StaffContext - \consists Custos_engraver - Custos \override #'style = #'mensural - @} -@} -@end example - -The result looks like this: - -@lilypond -\score { - \notes { - a'1 - \override Staff.Custos #'style = #'mensural - \break - g' - } - \paper { - \translator { - \StaffContext - \consists Custos_engraver - } - linewidth = 4.0\cm - } -} -@end lilypond - -The custos glyph is selected by the @code{style} property. The styles -supported are @code{vaticana}, @code{medicaea}, @code{hufnagel} and -@code{mensural}. They are demonstrated in the following fragment: - -@lilypond -\score { - \notes { - \fatText - s - ^\markup { - \column < - "vaticana" - { " " \musicglyph #"custodes-vaticana-u0" } - > - \column < - "medicaea" - { " " \musicglyph #"custodes-medicaea-u0" } - > - \column < - "hufnagel" - { " " \musicglyph #"custodes-hufnagel-u0" } - > - \column < - "mensural" - { " " \musicglyph #"custodes-mensural-u0" } - > - } - } - \paper { - raggedright = ##t - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator{ - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \remove "Time_signature_engraver" - \remove "Staff_symbol_engraver" - minimumVerticalExtent = ##f - } - } -} -@end lilypond - -If the boolean property @code{adjust-if-on-staffline} is set to -@code{#t} (which it is by default), lily typesets slightly different -variants of the custos glyph, depending on whether the custos, is -typeset on or between staff lines. The glyph will -optically fit well into the staff, with the appendage on the right of -the custos always ending at the same vertical position between two -staff lines regardless of the pitch. If you set -@code{adjust-if-on-staffline} to @code{#f}, then -a compromise between both forms is used. - -Just like stems can be attached to note heads in two directions -@emph{up} and @emph{down}, each custos glyph is available with its -appendage pointing either up or down. If the pitch of a custos is -above a selectable position, the appendage will point downwards; if -the pitch is below this position, the appendage will point upwards. -Use property @code{neutral-position} to select this position. By -default, it is set to @code{0}, such that the neutral position is the -center of the staff. Use property @code{neutral-direction} to control -what happens if a custos is typeset on the neutral position itself. -By default, this property is set to @code{-1}, such that the appendage -will point downwards. If set to @code{1}, the appendage will point -upwards. Other values such as @code{0} are reserved for future -extensions and should not be used. - -@seealso - -Internals: @internalsref{Custos}. - -Examples: @inputfileref{input/regression,custos.ly}. - - -@node Divisiones -@subsection Divisiones - -@cindex divisio -@cindex divisiones -@cindex finalis - -A @emph{divisio} (plural: @emph{divisiones}; Latin word for -`division') is a staff context symbol that is used to structure -Gregorian music into phrases and sections. The musical meaning of -@emph{divisio minima}, @emph{divisio maior} and @emph{divisio maxima} -can be characterized as short, medium and long pause, somewhat like -@ref{Breath marks}. The @emph{finalis} sign not only marks the end of -a chant, but is also frequently used within a single -antiphonal/responsorial chant to mark the end of each section. - -@syntax - -To use divisiones, include the file @code{gregorian-init.ly}. It -contains definitions that you can apply by just inserting -@code{\divisioMinima}, @code{\divisioMaior}, @code{\divisioMaxima}, -and @code{\finalis} at proper places in the input. Some editions use -@emph{virgula} or @emph{caesura} instead of divisio minima. -Therefore, @code{gregorian-init.ly} also defines @code{\virgula} and -@code{\caesura}: - -@lilypondfile[]{divisiones.ly} - -@refcommands - -@cindex @code{\virgula} -@code{\virgula}, -@cindex @code{\caesura} -@code{\caesura}, -@cindex @code{\divisioMinima} -@code{\divisioMinima}, -@cindex @code{\divisioMaior} -@code{\divisioMaior}, -@cindex @code{\divisioMaxima} -@code{\divisioMaxima}, -@cindex @code{\finalis} -@code{\finalis}. - -@seealso - -In this manual: @ref{Breath marks}. - -Internals: @internalsref{BreathingSign}, @internalsref{BreathingSignEvent}. - -Examples: @inputfileref{input/test,divisiones.ly}. - -@node Ligatures -@subsection Ligatures - -@cindex Ligatures - -@c TODO: Should double check if I recalled things correctly when I wrote -@c down the following paragraph by heart. - -In musical terminology, a ligature is a coherent graphical symbol that -represents at least two distinct notes. Ligatures originally appeared -in the manuscripts of Gregorian chant notation roughly since the 9th -century as an allusion to the accent symbols of Greek lyric poetry to -denote ascending or descending sequences of notes. Both, the shape -and the exact meaning of ligatures changed tremendously during the -following centuries: In early notation, ligatures were used for -monophonic tunes (Gregorian chant) and very soon denoted also the way -of performance in the sense of articulation. With upcoming -multiphony, the need for a metric system arised, since multiple voices -of a piece have to be synchronized some way. New notation systems -were invented that used the manifold shapes of ligatures to now denote -rhythmical patterns (e.g. black mensural notation, mannered notation, -ars nova). With the invention of the metric system of the white -mensural notation, the need for ligatures to denote such patterns -disappeared. Nevertheless, ligatures were still in use in the -mensural system for a couple of decades until they finally disappeared -during the late 16th / early 17th century. Still, ligatures have -survived in contemporary editions of Gregorian chant such as the -Editio Vaticana from 1905/08. - -@syntax - -Syntactically, ligatures are simply enclosed by @code{\[} and -@code{\]}. Some ligature styles (such as Editio Vaticana) may need -additional input syntax specific for this particular type of ligature. -By default, the @internalsref{LigatureBracket} engraver just puts a -square bracket above the ligature: - -@lilypond[raggedright,verbatim] -\score { - \notes \transpose c c' { - \[ g c a f d' \] - a g f - \[ e f a g \] - } -} -@end lilypond - -To select a specific style of ligatures, a proper ligature engraver -has to be added to the @internalsref{Voice} context, as explained in -the following subsections. Only white mensural ligatures -are supported with certain limitations. Support for Editio Vaticana -will be added in the future. - -@menu -* White mensural ligatures:: -* Gregorian square neumes ligatures:: -@end menu - -@node White mensural ligatures -@subsubsection White mensural ligatures - -@cindex Mensural ligatures -@cindex White mensural ligatures - -There is limited support for white mensural ligatures. The -implementation is still experimental; it may output strange -warnings or even crash in some cases or produce weird results on more -complex ligatures. - -@syntax - -To engrave white mensural ligatures, in the paper block the -@internalsref{Mensural_ligature_engraver} has to be put into the -@internalsref{Voice} context, and remove the -@internalsref{Ligature_bracket_engraver}: - -@example - \paper @{ - \translator @{ - \VoiceContext - \remove Ligature_bracket_engraver - \consists Mensural_ligature_engraver - @} - @} -@end example - -There is no additional input language to describe the shape of a -white mensural ligature. The shape is rather determined solely from -the pitch and duration of the enclosed notes. While this approach may -take a new user a while to get accustomed, it has the great advantage -that the full musical information of the ligature is known internally. -This is not only required for correct MIDI output, but also allows for -automatic transcription of the ligatures. - -For example, - -@example - \set Score.timing = ##f - \set Score.defaultBarType = "empty" - \override NoteHead #'style = #'neo_mensural - \override Staff.TimeSignature #'style = #'neo_mensural - \clef "petrucci_g" - \[ g\longa c\breve a\breve f\breve d'\longa \] - s4 - \[ e1 f1 a\breve g\longa \] -@end example -@lilypond[raggedright] -\score { - \notes \transpose c c' { - \set Score.timing = ##f - \set Score.defaultBarType = "empty" - \override NoteHead #'style = #'neo_mensural - \override Staff.TimeSignature #'style = #'neo_mensural - \clef "petrucci_g" - \[ g\longa c\breve a\breve f\breve d'\longa \] - s4 - \[ e1 f1 a\breve g\longa \] - } - \paper { - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Mensural_ligature_engraver - } - } -} -@end lilypond - -Without replacing @internalsref{Ligature_bracket_engraver} with -@internalsref{Mensural_ligature_engraver}, the same music transcribes -to the following: - -@lilypond[raggedright] -\score { - \notes \transpose c c' { - \set Score.timing = ##f - \set Score.defaultBarType = "empty" - \override NoteHead #'style = #'neo_mensural - \override Staff.TimeSignature #'style = #'neo_mensural - \clef "petrucci_g" - \[ g\longa c\breve a\breve f\breve d'\longa \] - s4 - \[ e1 f1 a\breve g\longa \] - } -} -@end lilypond - - -@node Gregorian square neumes ligatures -@subsubsection Gregorian square neumes ligatures - -@cindex Square neumes ligatures -@cindex Gregorian square neumes ligatures - -Gregorian square neumes notation (following the style of the Editio -Vaticana) is under heavy development, but not yet really usable for -production purposes. Core ligatures can already be typeset, but -essential issues for serious typesetting are still under development, -such as (among others) horizontal alignment of multiple ligatures, -lyrics alignment and proper accidentals handling. Still, this section -gives a sneak preview of what Gregorian chant may look like once it -will work. - -The following table contains the extended neumes table of the 2nd -volume of the Antiphonale Romanum (@emph{Liber Hymnarius}), published -1983 by the monks of Solesmes. - -@multitable @columnfractions .4 .2 .2 .2 - -@item -@b{Neuma aut@*Neumarum Elementa} @tab -@b{Figurae@*Rectae} @tab -@b{Figurae@*Liquescentes Auctae} @tab -@b{Figurae@*Liquescentes Deminutae} - -@c TODO: \paper block is identical in all of the below examples. -@c Therefore, it should somehow be included rather than duplicated all -@c the time. --jr - -@c why not make identifiers in ly/engraver-init.ly? --hwn - -@c Because it's just used to typeset plain notes without -@c a staff for demonstration purposes rather than something -@c special of Gregorian chant notation. --jr - -@item -@code{1. Punctum} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.5\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Punctum - \[ b \] - \noBreak s^\markup {"a"} \noBreak - - % Punctum Inclinatum - \[ \inclinatum b \] - \noBreak s^\markup {"b"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=2.5\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Punctum Auctum Ascendens - \[ \auctum \ascendens b \] - \noBreak s^\markup {"c"} \noBreak - - % Punctum Auctum Descendens - \[ \auctum \descendens b \] - \noBreak s^\markup {"d"} \noBreak - - % Punctum Inclinatum Auctum - \[ \inclinatum \auctum b \] - \noBreak s^\markup {"e"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Punctum Inclinatum Parvum - \[ \inclinatum \deminutum b \] - \noBreak s^\markup {"f"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{2. Virga} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Virga - \[ \virga b \] - \noBreak s^\markup {"g"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@tab - -@item -@code{3. Apostropha vel Stropha} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Stropha - \[ \stropha b \] - \noBreak s^\markup {"h"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Stropha Aucta - \[ \stropha \auctum b \] - \noBreak s^\markup {"i"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab - -@item -@code{4. Oriscus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Oriscus - \[ \oriscus b \] - \noBreak s^\markup {"j"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@tab - -@item -@code{5. Clivis vel Flexa} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Clivis vel Flexa - \[ b \flexa g \] - s^\markup {"k"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=2.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Clivis Aucta Descendens - \[ b \flexa \auctum \descendens g \] - \noBreak s^\markup {"l"} \noBreak - - % Clivis Aucta Ascendens - \[ b \flexa \auctum \ascendens g \] - \noBreak s^\markup {"m"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Cephalicus - \[ b \flexa \deminutum g \] - s^\markup {"n"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{6. Podatus vel Pes} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Podatus vel Pes - \[ g \pes b \] - s^\markup {"o"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=2.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Pes Auctus Descendens - \[ g \pes \auctum \descendens b \] - \noBreak s^\markup {"p"} \noBreak - - % Pes Auctus Ascendens - \[ g \pes \auctum \ascendens b \] - \noBreak s^\markup {"q"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Epiphonus - \[ g \pes \deminutum b \] - s^\markup {"r"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{7. Pes Quassus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Pes Quassus - \[ \oriscus g \pes \virga b \] - s^\markup {"s"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Pes Quassus Auctus Descendens - \[ \oriscus g \pes \auctum \descendens b \] - s^\markup {"t"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab - -@item -@code{8. Quilisma Pes} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Quilisma Pes - \[ \quilisma g \pes b \] - s^\markup {"u"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Quilisma Pes Auctus Descendens - \[ \quilisma g \pes \auctum \descendens b \] - s^\markup {"v"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab - -@item -@code{9. Podatus Initio Debilis} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Pes Initio Debilis - \[ \deminutum g \pes b \] - s^\markup {"w"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Pes Auctus Descendens Initio Debilis - \[ \deminutum g \pes \auctum \descendens b \] - s^\markup {"x"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab - -@item -@code{10. Torculus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Torculus - \[ a \pes b \flexa g \] - s^\markup {"y"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Torculus Auctus Descendens - \[ a \pes b \flexa \auctum \descendens g \] - s^\markup {"z"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Torculus Deminutus - \[ a \pes b \flexa \deminutum g \] - s^\markup {"A"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{11. Torculus Initio Debilis} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Torculus Initio Debilis - \[ \deminutum a \pes b \flexa g \] - s^\markup {"B"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Torculus Auctus Descendens Initio Debilis - \[ \deminutum a \pes b \flexa \auctum \descendens g \] - s^\markup {"C"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Torculus Deminutus Initio Debilis - \[ \deminutum a \pes b \flexa \deminutum g \] - s^\markup {"D"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{12. Porrectus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Porrectus - \[ a \flexa g \pes b \] - s^\markup {"E"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Porrectus Auctus Descendens - \[ a \flexa g \pes \auctum \descendens b \] - s^\markup {"F"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Porrectus Deminutus - \[ a \flexa g \pes \deminutum b \] - s^\markup {"G"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{13. Climacus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Climacus - \[ \virga b \inclinatum a \inclinatum g \] - s^\markup {"H"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Climacus Auctus - \[ \virga b \inclinatum a \inclinatum \auctum g \] - s^\markup {"I"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Climacus Deminutus - \[ \virga b \inclinatum a \inclinatum \deminutum g \] - s^\markup {"J"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{14. Scandicus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Scandicus - \[ g \pes a \virga b \] - s^\markup {"K"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Scandicus Auctus Descendens - \[ g \pes a \pes \auctum \descendens b \] - s^\markup {"L"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Scandicus Deminutus - \[ g \pes a \pes \deminutum b \] - s^\markup {"M"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond - -@item -@code{15. Salicus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Salicus - \[ g \oriscus a \pes \virga b \] - s^\markup {"N"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Salicus Auctus Descendens - \[ g \oriscus a \pes \auctum \descendens b \] - s^\markup {"O"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab - -@item -@code{16. Trigonus} -@tab -@lilypond[noindent,staffsize=26,nofragment,linewidth=1.0\cm] -\include "gregorian-init.ly" -\score { - \notes \transpose c c' { - % Trigonus - \[ \stropha b \stropha b \stropha a \] - s^\markup {"P"} - } - \paper { - interscoreline = 1 - \translator { - \ScoreContext - \remove "Bar_number_engraver" - } - \translator { - \StaffContext - \remove "Clef_engraver" - \remove "Key_engraver" - \override StaffSymbol #'transparent = ##t - \remove "Time_signature_engraver" - \remove "Bar_engraver" - minimumVerticalExtent = ##f - } - \translator { - \VoiceContext - \remove Ligature_bracket_engraver - \consists Vaticana_ligature_engraver - \override NoteHead #'style = #'vaticana_punctum - \override Stem #'transparent = ##t - } - } -} -@end lilypond -@tab -@tab - -@end multitable - -@syntax - -Unlike most other neumes notation systems, the input language for -neumes does not necessarily reflect directly the typographical -appearance, but is designed to solely focuse on musical meaning. For -example, @code{\[ a \pes b \flexa g \]} produces a Torculus consisting -of three Punctum heads, while @code{\[ a \flexa g \pes b \]} produces -a Porrectus with a curved flexa shape and only a single Punctum head. -There is no command to explicitly typeset the curved flexa shape; the -decision of when to typeset a curved flexa shape is purely taken from -the musical input. The idea of this approach is to separate the -musical aspects of the input from the notation style of the output. -This way, the same input can be reused to typeset the same music in a -different style of Gregorian chant notation such as Hufnagel (also -known as German gothic neumes) or Medicaea (kind of a very simple -forerunner of the Editio Vaticana). As soon as Hufnagel ligature -engraver and Medicaea ligature engraver will have been implemented, it -will be as simple as replacing the ligature engraver in the -@internalsref{Voice} context to get the desired notation style from -the same input. - -The following table shows the code fragments that produce the -ligatures in the above neumes table. The letter in the first column -in each line of the below table indicates to which ligature in the -above table it refers. The second column gives the name of the -ligature. The third column shows the code fragment that produces this -ligature, using @code{g}, @code{a} and @code{b} as example pitches. - -@multitable @columnfractions .1 .4 .5 - -@item -@b{#} @tab -@b{Name} @tab -@b{Input Language} - -@item -a @tab -Punctum @tab -@code{\[ b \]} - -@item -b @tab -Punctum Inclinatum @tab -@code{\[ \inclinatum b \]} - -@item -c @tab -Punctum Auctum Ascendens @tab -@code{\[ \auctum \ascendens b \]} - -@item -d @tab -Punctum Auctum Descendens @tab -@code{\[ \auctum \descendens b \]} - -@item -e @tab -Punctum Inclinatum Auctum @tab -@code{\[ \inclinatum \auctum b \]} - -@item -f @tab -Punctum Inclinatum Parvum @tab -@code{\[ \inclinatum \deminutum b \]} - -@item -g @tab -Virga @tab -@code{\[ \virga b \]} - -@item -h @tab -Stropha @tab -@code{\[ \stropha b \]} - -@item -i @tab -Stropha Aucta @tab -@code{\[ \stropha \auctum b \]} - -@item -j @tab -Oriscus @tab -@code{\[ \oriscus b \]} - -@item -k @tab -Clivis vel Flexa @tab -@code{\[ b \flexa g \]} - -@item -l @tab -Clivis Aucta Descendens @tab -@code{\[ b \flexa \auctum \descendens g \]} - -@item -m @tab -Clivis Aucta Ascendens @tab -@code{\[ b \flexa \auctum \ascendens g \]} - -@item -n @tab -Cephalicus @tab -@code{\[ b \flexa \deminutum g \]} - -@item -o @tab -Podatus vel Pes @tab -@code{\[ g \pes b \]} - -@item -p @tab -Pes Auctus Descendens @tab -@code{\[ g \pes \auctum \descendens b \]} - -@item -q @tab -Pes Auctus Ascendens @tab -@code{\[ g \pes \auctum \ascendens b \]} - -@item -r @tab -Epiphonus @tab -@code{\[ g \pes \deminutum b \]} - -@item -s @tab -Pes Quassus @tab -@code{\[ \oriscus g \pes \virga b \]} - -@item -t @tab -Pes Quassus Auctus Descendens @tab -@code{\[ \oriscus g \pes \auctum \descendens b \]} - -@item -u @tab -Quilisma Pes @tab -@code{\[ \quilisma g \pes b \]} - -@item -v @tab -Quilisma Pes Auctus Descendens @tab -@code{\[ \quilisma g \pes \auctum \descendens b \]} - -@item -w @tab -Pes Initio Debilis @tab -@code{\[ \deminutum g \pes b \]} - -@item -x @tab -Pes Auctus Descendens Initio Debilis @tab -@code{\[ \deminutum g \pes \auctum \descendens b \]} - -@item -y @tab -Torculus @tab -@code{\[ a \pes b \flexa g \]} - -@item -z @tab -Torculus Auctus Descendens @tab -@code{\[ a \pes b \flexa \auctum \descendens g \]} - -@item -A @tab -Torculus Deminutus @tab -@code{\[ a \pes b \flexa \deminutum g \]} - -@item -B @tab -Torculus Initio Debilis @tab -@code{\[ \deminutum a \pes b \flexa g \]} - -@item -C @tab -Torculus Auctus Descendens Initio Debilis @tab -@code{\[ \deminutum a \pes b \flexa \auctum \descendens g \]} - -@item -D @tab -Torculus Deminutus Initio Debilis @tab -@code{\[ \deminutum a \pes b \flexa \deminutum g \]} - -@item -E @tab -Porrectus @tab -@code{\[ a \flexa g \pes b \]} - -@item -F @tab -Porrectus Auctus Descendens @tab -@code{\[ a \flexa g \pes \auctum \descendens b \]} - -@item -G @tab -Porrectus Deminutus @tab -@code{\[ a \flexa g \pes \deminutum b \]} - -@item -H @tab -Climacus @tab -@code{\[ \virga b \inclinatum a \inclinatum g \]} - -@item -I @tab -Climacus Auctus @tab -@code{\[ \virga b \inclinatum a \inclinatum \auctum g \]} - -@item -J @tab -Climacus Deminutus @tab -@code{\[ \virga b \inclinatum a \inclinatum \deminutum g \]} - -@item -K @tab -Scandicus @tab -@code{\[ g \pes a \virga b \]} - -@item -L @tab -Scandicus Auctus Descendens @tab -@code{\[ g \pes a \pes \auctum \descendens b \]} - -@item -M @tab -Scandicus Deminutus @tab -@code{\[ g \pes a \pes \deminutum b \]} - -@item -N @tab -Salicus @tab -@code{\[ g \oriscus a \pes \virga b \]} - -@item -O @tab -Salicus Auctus Descendens @tab -@code{\[ g \oriscus a \pes \auctum \descendens b \]} - -@item -P @tab -Trigonus @tab -@code{\[ \stropha b \stropha b \stropha a \]} - -@end multitable - -@refcommands - -The following head prefixes are supported: - -@cindex @code{\virga} -@code{\virga}, -@cindex @code{\stropha} -@code{\stropha}, -@cindex @code{\inclinatum} -@code{\inclinatum}, -@cindex @code{\auctum} -@code{\auctum}, -@cindex @code{\descendens} -@code{\descendens}, -@cindex @code{\ascendens} -@code{\ascendens}, -@cindex @code{\oriscus} -@code{\oriscus}, -@cindex @code{\quilisma} -@code{\quilisma}, -@cindex @code{\deminutum} -@code{\deminutum}. - -Head prefixes can be accumulated, though restrictions apply. For -example, either @code{\descendens} or @code{\ascendens} can be applied -to a head, but not both to the same head. - -@cindex @code{\pes} -@cindex @code{\flexa} -Two adjacent heads can be tied together with the @code{\pes} and -@code{\flexa} infix commands for a rising and falling line of melody, -respectively. - -@refbugs - -Trigonus: apply equal spacing, regardless of pitch. - -@node Figured bass -@subsection Figured bass - -@cindex Basso continuo - -@c TODO: musicological blurb about FB - -@syntax - -LilyPond has limited support for figured bass: - -@lilypond[verbatim,fragment] -<< - \context Voice \notes { \clef bass dis4 c d ais} - \context FiguredBass - \figures { - < 6 >4 < 7 >8 < 6+ [_!] > - < 6 >4 <6 5 [3+] > - } - >> -@end lilypond - -The support for figured bass consists of two parts: there is an input -mode, introduced by @code{\figures}, where you can enter bass figures -as numbers, and there is a context called @internalsref{FiguredBass} that -takes care of making @internalsref{BassFigure} objects. - -In figures input mode, a group of bass figures is delimited by -@code{<} and @code{>}. The duration is entered after the @code{>>}: -@example - <4 6> -@end example -@lilypond[fragment] -\context FiguredBass -\figures { <4 6> } -@end lilypond - -Accidentals are added when you append @code{-}, @code{!} and @code{+} -to the numbers: - -@example - <4- 6+ 7!> -@end example -@lilypond[fragment] - \context FiguredBass - \figures { <4- 6+ 7!> } -@end lilypond - -Spaces or dashes may be inserted by using @code{_}. Brackets are -introduced with @code{[} and @code{]}: - -@example - < [4 6] 8 [_! 12]> -@end example -@lilypond[fragment] - \context FiguredBass -\figures { < [4 6] 8 [_! 12]> } -@end lilypond - -Although the support for figured bass may superficially resemble chord -support, it works much simpler. The @code{\figures} mode simply -stores the numbers , and @internalsref{FiguredBass} context prints -them as entered. There is no conversion to pitches, and no -realizations of the bass are played in the MIDI file. - -Internally, the code produces markup texts. You can use any of the -markup text properties to override formatting. For example, the -vertical spacing of the figures may be set with @code{baseline-skip}. - -@seealso - -Internals: @internalsref{BassFigureEvent} music, @internalsref{BassFigure} object, -and @internalsref{FiguredBass} context. - -@refbugs - -Slash notation for alterations is not supported. - - -@node Vaticana style contexts -@subsection Vaticana style contexts - -@cindex VaticanaVoiceContext -@cindex VaticanaStaffContext - -The predefined @code{VaticanaVoiceContext} and -@code{VaticanaStaffContext} can be used to easily engrave a piece of -Gregorian Chant in the style of the Editio Vaticana. These contexts -initialize all relevant context properties and grob properties to -proper values. With these contexts, you can immediately go ahead -entering the chant, as the following short excerpt demonstrates: - -@lilypond[raggedright,verbatim,noindent] -\include "gregorian-init.ly" -\score { -<< - \context VaticanaVoice = "cantus" { - \override Score.BarNumber #'transparent = ##t - \notes { - \[ c'\melisma c' \flexa a \] \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima - \[ f\melisma \pes a c' c' \pes d'\melismaEnd \] c' \divisioMinima \break - \[ c'\melisma c' \flexa a \] \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima - } - } - \lyricsto "cantus" \new Lyrics \lyrics { - San- ctus, San- ctus, San- ctus - } >> - -} -@end lilypond - -@node Contemporary notation -@section Contemporary notation - -In the 20th century, composers have greatly expanded the musical -vocabulary. With this expansion, many innovations in musical notation -have been tried. The book by Stone (1980) gives a comprehensive -overview (see @ref{Literature list}). In general, the use of new, -innovative notation makes a piece harder to understand and perform and -its use should therefore be avoided if possible. For this reason, -support for contemporary notation in LilyPond is limited. - - -@menu -* Clusters:: -* Fermatas:: -@end menu - -@node Clusters -@subsection Clusters - -@cindex cluster - -In musical terminology, a @emph{cluster} denotes a range of -simultaneously sounding pitches that may change over time. The set of -available pitches to apply usually depends on the acoustic source. -Thus, in piano music, a cluster typically consists of a continuous range -of the semitones as provided by the piano's fixed set of a chromatic -scale. In choral music, each singer of the choir typically may sing an -arbitrary pitch within the cluster's range that is not bound to any -diatonic, chromatic or other scale. In electronic music, a cluster -(theoretically) may even cover a continuous range of pitches, thus -resulting in colored noise, such as pink noise. - -Clusters can be denoted in the context of ordinary staff notation by -engraving simple geometrical shapes that replace ordinary notation of -notes. Ordinary notes as musical events specify starting time and -duration of pitches; however, the duration of a note is expressed by the -shape of the note head rather than by the horizontal graphical extent of -the note symbol. In contrast, the shape of a cluster geometrically -describes the development of a range of pitches (vertical extent) over -time (horizontal extent). Still, the geometrical shape of a cluster -covers the area in which any single pitch contained in the cluster would -be notated as an ordinary note. From this point of view, it is -reasonable to specify a cluster as the envelope of a set of notes. - -@syntax - -A cluster is engraved as the envelope of a set of -cluster-notes. Cluster notes are created by applying the function -@code{notes-to-clusters} to a sequence of chords, e.g. -@c -@lilypond[relative=1,verbatim] - \apply #notes-to-clusters { } -@end lilypond - -The following example (from -@inputfileref{input/regression,cluster.ly}) shows what the result -looks like: - -@lilypondfile[]{cluster.ly} - -By default, @internalsref{Cluster_spanner_engraver} is in the -@internalsref{Voice} context. This allows putting ordinary notes and -clusters together in the same staff, even simultaneously. In such a -case no attempt is made to automatically avoid collisions between -ordinary notes and clusters. - -@seealso - -Internals: @internalsref{ClusterSpanner}, -@internalsref{ClusterSpannerBeacon}, -@internalsref{Cluster_spanner_engraver}, and -@internalsref{ClusterNoteEvent}. - -Examples: @inputfileref{input/regression,cluster.ly}. - -@refbugs - -Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed -accurately. Use @code{8 8} instead. - - - -@node Fermatas -@subsection Fermatas - -@cindex fermatas - - - -Contemporary music notation frequently uses special fermata symbols to -indicate fermatas of differing lengths. - -@syntax - -The following are supported - -@lilypond[raggedright] -\score { - << \addlyrics \notes { - b' - ^\shortfermata - _\shortfermata - r - b' - ^\fermata - _\fermata - - r - b' - ^\longfermata - _\longfermata - - r - b' - ^\verylongfermata - _\verylongfermata - r - } - \context Lyrics \lyrics { - "shortfermata" "fermata" "longfermata" "verylongfermata" - } >> -} -@end lilypond - -See @ref{Articulations} for general instructions how to apply scripts -such as fermatas to a @code{\notes@{@}} block. - - -@node Special notation -@section Special notation - -@menu -* Balloon help:: -* Easy Notation note heads:: -@end menu - -@node Balloon help -@subsection Balloon help - -Elements of notation can be marked and named with the help of a square -balloon. The primary purpose of this feature is to explain notation. - -The following example demonstrates its use. - -@lilypond[verbatim,fragment,raggedright,relative=1] - \context Voice - \applyoutput - #(add-balloon-text 'NoteHead "heads, or tails?" - '(1 . -3)) - c8 -@end lilypond - -@noindent -The function @code{add-balloon-text} takes the name of a grob, the -label to print and where to put the label relative to the object. In -the above example, the text ``heads or tails?'' ends 3 spaces below -the `balloon.' - -@cindex balloon -@cindex notation, explaining - -@seealso - -Internals: @internalsref{text-balloon-interface}. - -Examples: @inputfileref{input/regression,balloon.ly}. - -@node Easy Notation note heads -@subsection Easy Notation note heads - -@cindex easy notation -@cindex Hal Leonard - -The `easy play' note head includes a note name inside the head. It is -used in music aimed at beginners: - -@lilypond[raggedright,verbatim,staffsize=26] -\score { - \notes { c'2 e'4 f' | g'1 } - \paper { \translator { \EasyNotation } } -} -@end lilypond - -The @code{EasyNotation} variable overrides a @internalsref{Score} @c -context. To make the letters readable, it has to be printed in a -large font size. To print with a larger font, see @ref{Font Size}. - -@cindex Xdvi -@cindex ghostscript - -If you view the result with Xdvi, then staff lines may show through -the letters. Printing the PostScript file obtained does produce the -correct result. - diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely deleted file mode 100644 index e0395c30af..0000000000 --- a/Documentation/user/running.itely +++ /dev/null @@ -1,1484 +0,0 @@ -@node Using LilyPond -@chapter Using LilyPond - -@menu -* Setting variables:: -* Fine tuning layout:: -* Tuning output:: -* Text markup:: -* Global layout:: -* Sound:: -@end menu - -@node Setting variables -@section Setting variables - -When the music is converted from notes to print it is interpreted -in left-to-right order. This is similar to what happens when we read -music. During this step context-sensitive information such as the -accidentals to print, and where bar lines must be placed, are stored in -variables. These variables are called @emph{context properties}. -The properties can also be manipulated from input files. Consider this input: -@example -\set Staff.autoBeaming = ##f -@end example - -@noindent -It sets the property named @code{autoBeaming} in the current staff at -this point in the music to @code{##f}, which means `false'. This -property controls whether beams are printed automatically: -@c -@lilypond[relative=1,fragment,verbatim] - c8 c c c - \set Staff.autoBeaming = ##f - c8 c c c -@end lilypond - -@noindent -LilyPond includes a built-in programming language, namely, a dialect -of Scheme. The argument to @code{\set}, @code{##f}, is an -expression in that language. The first hash-mark signals that a piece -of Scheme code follows. The second hash character is part of the -boolean value true (@code{#t}). Values of other types may be -entered as follows: -@itemize @bullet -@item a string, enclosed in double quotes, for example, -@example - \set Staff.instrument = #"French Horn" -@end example -@item a boolean: either @code{#t} or @code{#f}, for true and false -respectively, e.g. -@example - \set autoBeaming = ##f - \set Score.skipBars = ##t -@end example - -@item a number, such as -@example - \set Score.currentBarNumber = #20 -@end example - -@item a symbol, which is introduced by a quote character, as in -@example - \set Staff.crescendoSpanner = #'dashed-line -@end example - -@item a pair, which is also introduced by a quote character, like in -the following statements, which set properties to the pairs (-7.5, 6) -and (3, 4) respectively: - -@example - \set Staff.minimumVerticalExtent = #'(-7.5 . 6) - \set Staff.timeSignatureFraction = #'(3 . 4) -@end example - -@item a list, which is also introduced by a quote character. In the -following example, the @code{breakAlignOrder} property is set to a -list of symbols: -@example - \set Score.breakAlignOrder = - #'(left-edge time-signature key-signatures) -@end example - - -@end itemize - -There are many different properties. Not all of them are listed in -this manual. However, the program reference lists them all in the -section @internalsref{Context-properties}, and most properties are -demonstrated in one of the -@ifhtml -@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks} -@end ifhtml -@ifnothtml -tips-and-tricks -@end ifnothtml -examples. - - -@node Fine tuning layout -@section Fine tuning layout - -Sometimes it is necessary to change music layout by hand. When music -is formatted, layout objects are created for each symbol. For -example, every clef and every note head is represented by a layout -object. These layout objects also carry variables, which we call -@emph{layout properties}. By changing these variables from their -values, we can alter the look of a formatted score: - -@lilypond[verbatim,relative] - c4 - \override Stem #'thickness = #3.0 - c4 c4 c4 -@end lilypond - -@noindent -In the example shown here, the layout property @code{thickness} (a -symbol) is set to 3 in the @code{Stem} layout objects of the current -As a result, the notes following @code{\override} have thicker -stems. - -For the most part, a manual override is needed only on a case by -case basis and not for all subsequent instances of the altered -property. To accomplish this, simply prefix @code{\once} to the -@code{\override} statement and the override will apply only once, -immediately reverting to its default setting, i.e. - -@example - \once \override Stem #'thickness = #3.0 -@end example - -@lilypond[relative] - c4 - \once \override Stem #'thickness = #3.0 - c4 c4 c4 -@end lilypond - -@noindent -Some overrides are so common that predefined commands are provided as -a short cut. For example, @code{\slurUp} and @code{\stemDown}. These -commands are described in -@ifhtml -the -@end ifhtml -@ref{Notation manual}, under the sections for slurs and stems -respectively. - -The exact tuning possibilities for each type of layout object are -documented in the program reference of the respective -object. However, many layout objects share properties, which can be -used to apply generic tweaks. We mention a couple of these: - -@itemize @bullet -@item The @code{extra-offset} property, which -@cindex @code{extra-offset} -has a pair of numbers as value, moves around objects in the printout. -The first number controls left-right movement; a positive number will -move the object to the right. The second number controls up-down -movement; a positive number will move it higher. The units of these -offsets are staff-spaces. The @code{extra-offset} property is a -low-level feature: the formatting engine is completely oblivious to -these offsets. - -In the following example, the second fingering is moved a little to -the left, and 1.8 staff space downwards: - -@cindex setting object properties - -@lilypond[relative=1,verbatim] -\stemUp -f-5 -\once \override Fingering - #'extra-offset = #'(-0.3 . -1.8) -f-5 -@end lilypond - -@item -Setting the @code{transparent} property will cause an object to be printed -in `invisible ink': the object is not printed, but all its other -behavior is retained. The object still takes up space, it takes part in -collisions, and slurs, and ties and beams can be attached to it. - -@cindex transparent objects -@cindex removing objects -@cindex invisible objects -The following example demonstrates how to connect different voices -using ties. Normally, ties only connect two notes in the same -voice. By introducing a tie in a different voice, and blanking a stem -in that voice, the tie appears to cross voices: - -@lilypond[fragment,relative=1,verbatim] - c4 << { - \once \override Stem #'transparent = ##t - b8~ b8 - } \\ { - b[ g8] - } >> -@end lilypond - -@item -The @code{padding} property for objects with -@cindex @code{padding} -@code{side-position-interface} can be set to increase distance between -symbols that are printed above or below notes. We only give an -example; a more elaborate explanation is in @ref{Constructing a -tweak}: - -@lilypond[relative=1,verbatim] - c2\fermata - \override Script #'padding = #3 - b2\fermata -@end lilypond - -@end itemize - -More specific overrides are also possible. The notation manual -discusses in depth how to figure out these statements for yourself, in -@ref{Tuning output}. - - - - -@node Tuning output -@section Tuning output - -There are situations where default layout decisions are not -sufficient. In this section we discuss ways to override these -defaults. - -Formatting is internally done by manipulating so called objects -(graphic objects). Each object carries with it a set of properties -(object or layout properties) specific to that object. For example, a -stem object 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 one type of object, thus -affecting a whole set of objects. Second, you can select one specific -object, and set a layout property in that object. - -Do not confuse layout properties with translation -properties. Translation properties always use a mixed caps style -naming, and are manipulated using @code{\set} and @code{\unset}: -@example - \set Context.propertyName = @var{value} -@end example - -Layout properties are use Scheme style variable naming, i.e. lower -case words separated with dashes. They are symbols, and should always -be quoted using @code{#'}. For example, this could be an imaginary -layout property name: -@example - #'layout-property-name -@end example - -@seealso - -The introduction of the @ref{Technical manual} gives a more in-depth -treatment of the difference between translation and layout. - -@menu -* Tuning objects:: -* Constructing a tweak:: -* Applyoutput:: -* Font selection:: -@end menu - - - -@node Tuning objects -@subsection Tuning objects - -@cindex object description - -The definition of an object is a list of default object -properties. For example, the definition of the Stem object (available -in @file{scm/define-grobs.scm}), includes the following definitions -for @internalsref{Stem}: - -@example - (thickness . 1.3) - (beamed-lengths . (3.5 3.5 3.5 4.5 5.0)) - (Y-extent-callback . ,Stem::height) - @var{...} -@end example - - -Adding variables on top of this existing definition overrides the -system default, and alters the resulting appearance of the layout -object. - -@syntax - - -Changing a variable for only one object is commonly achieved with -@code{\once}: - -@example -\once \override @var{context}.@var{objectname} - @var{symbol} = @var{value} -@end example -Here @var{symbol} is a Scheme expression of symbol type, @var{context} -and @var{objectname} is a string and @var{value} is a Scheme expression. -This command applies a setting only during one moment in the score. - -In the following example, only one @internalsref{Stem} object is -changed from its original setting: - -@lilypond[verbatim,fragment,relative=1] - c4 - \once \override Voice.Stem #'thickness = #4 - c4 - c4 -@end lilypond -@cindex @code{\once} - -For changing more objects, the same command, without @code{\once} can -be used: -@example -\override @var{context}.@var{objectname} @var{symbol} = @var{value} -@end example -This command adds @code{@var{symbol} = @var{value}} to the definition -of @var{objectname} in the context @var{context}, and this definition -stays in place until it is removed. - -An existing definition may be removed by the following command: -@c -@example -\property @var{context}.@var{objectname} \revert @var{symbol} -@end example -@c - -Some examples: -@lilypond[verbatim] -c'4 \override Stem #'thickness = #4.0 -c'4 -c'4 \revert Stem #'thickness -c'4 -@end lilypond - -The following example gives exactly the same result as the previous -one (assuming the system default for stem thickness is 1.3): -@c -@lilypond[verbatim] - c'4 \override Stem #'thickness = #4.0 - c'4 - c'4 \override Stem #'thickness = #1.3 - c'4 -@end lilypond - -Reverting a setting which was not set in the first place has no -effect. - - -@seealso - -Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty}, -@internalsref{PropertySet}, @internalsref{All-backend-properties}, and -@internalsref{All-layout-objects}. - - -@refbugs - -The back-end is not very strict in type-checking object properties. -Cyclic references in Scheme values for properties can cause hangs -and/or crashes. - -@menu -* Constructing a tweak:: -* Applyoutput:: -* Font selection:: -* Text markup:: -@end menu - -@node Constructing a tweak -@subsection Constructing a tweak - - -@cindex internal documentation -@cindex finding graphical objects -@cindex graphical object descriptions -@cindex tweaking -@cindex @code{\override} -@cindex @code{\set} -@cindex internal documentation - - - -Three pieces of information are required to use @code{\override} and -@code{\set}: the name of the layout object, the context and the name -of the property. We demonstrate how to glean this information from -the notation manual and the generated documentation. - -The generated documentation is a set of HTML pages which should be -included if you installed a binary distribution, typically in -@file{/usr/share/doc/lilypond}. They are also available on the web: -go to the @uref{http://lilypond.org,LilyPond website}, click -``Documentation'', select the correct version, and click then -``Program reference.'' It is advisable to bookmark the local HTML -files. They will load faster than the ones on the web. If you use the -version from the web, you must check whether the documentation matches -the program version: it is generated from the definitions that the -program uses, and therefore it is strongly tied to the LilyPond -version. - - -@c [TODO: revise for new site.] - -Suppose we want to move the fingering indication in the fragment below: - -@lilypond[relative=2,verbatim] -c-2 -\stemUp -f -@end lilypond - -If you visit the documentation of @code{Fingering} (in @ref{Fingering -instructions}), you will notice that there is written: - -@quotation -@seealso - -Internals: @internalsref{FingerEvent} and @internalsref{Fingering}. - -@end quotation - -@separate - -@noindent -In other words, the fingerings once entered, are internally stored as -@code{FingerEvent} music objects. When printed, a @code{Fingering} -layout object is created for every @code{FingerEvent}. - -The Fingering object has a number of different functions, and each of -those is captured in an interface. The interfaces are listed under -@internalsref{Fingering} in the program reference. - - - -The @code{Fingering} object has a fixed size -(@internalsref{item-interface}), the symbol is a piece of text -(@internalsref{text-interface}), whose font can be set -(@internalsref{font-interface}). It is centered horizontally -(@internalsref{self-alignment-interface}), it is placed next to other -objects (@internalsref{side-position-interface}) vertically, and its -placement is coordinated with other scripts -(@internalsref{text-script-interface}). It also has the standard -@internalsref{grob-interface} (grob stands for Graphical object) -@cindex grob -@cindex graphical object -@cindex layout object -@cindex object, layout -with all the variables that come with -it. Finally, it denotes a fingering instruction, so it has -@internalsref{finger-interface}. - -For the vertical placement, we have to look under -@code{side-position-interface}: -@quotation -@code{side-position-interface} - - Position a victim object (this one) next to other objects (the - support). In this case, the property @code{direction} signifies where to put the - victim object relative to the support (left or right, up or down?) -@end quotation - -@cindex padding -@noindent -below this description, the variable @code{padding} is described as -@quotation -@table @code -@item padding - (dimension, in staff space) - - add this much extra space between objects that are next to each -other. Default value: @code{0.6} -@end table -@end quotation - -By increasing the value of @code{padding}, we can move away the -fingering. The following command inserts 3 staff spaces of white -between the note and the fingering: -@example -\once \override Fingering #'padding = #3 -@end example - -Inserting this command before the Fingering object is created, -i.e. before @code{c2}, yields the following result: - -@lilypond[relative=2,fragment,verbatim] -\once \override Fingering - #'padding = #3 -c-2 -\stemUp -f -@end lilypond - -The context name @code{Voice} in the example above can be determined -as follows. In the documentation for @internalsref{Fingering}, it says -@quotation -Fingering grobs are created by: @internalsref{Fingering_engraver} @c -@end quotation - -Clicking @code{Fingering_engraver} shows the documentation of -the module responsible for interpreting the fingering instructions and -translating them to a @code{Fingering} object. Such a module is called -an @emph{engraver}. The documentation of the @code{Fingering_engraver} -says -@example -Fingering_engraver is part of contexts: Voice -@end example -so tuning the settings for Fingering should be done with -@example - \override Fingering @dots{} -@end example - -Of course, the tweak may also done in a larger context than -@code{Voice}, for example, @internalsref{Staff} or -@internalsref{Score}. - -@seealso - -Internals: the program reference also contains alphabetical lists of -@internalsref{Contexts}, @internalsref{All-layout-objects} and -@internalsref{Music-expressions}, so you can also find which objects -to tweak by browsing the internals document. - - -@node Applyoutput -@subsection Applyoutput - -The most versatile way of tuning an object is @code{\applyoutput}. Its -syntax is -@example -\applyoutput @var{proc} -@end example - -@noindent -where @var{proc} is a Scheme function, taking three arguments. - -When interpreted, the function @var{proc} is called for every layout -object found in the context, with the following arguments: -@itemize @bullet -@item the layout object itself, -@item the context where the layout object was created, and -@item the context where @code{\applyoutput} is processed. -@end itemize - - -In addition, the cause of the layout object, i.e. the music -expression or object that was responsible for creating it, is in the -object property @code{cause}. For example, for a note head, this is a -@internalsref{NoteHead} event, and for a @internalsref{Stem} object, -this is a @internalsref{NoteHead} object. - -Here is a simple example of @code{\applyoutput}; it blanks note-heads on the -center-line: -@example -(define (blanker grob grob-origin context) - (if (and (memq (ly:grob-property grob 'interfaces) - note-head-interface) - (eq? (ly:grob-property grob 'staff-position) 0)) - - (ly:grob-set-property! grob 'transparent #t))) -@end example - - - -@node Font selection -@subsection Font selection - -The most common thing to change about the appearance of fonts is their -size. The font size of any context can be easily changed by setting -the @code{fontSize} property for that context. Its value is a number: -negative numbers make the font smaller, positive numbers larger. An -example is given below: -@c -@lilypond[fragment,relative=1,verbatim] - c4 c4 \set fontSize = #-1 - f4 g4 -@end lilypond -This command will set @code{font-size} (see below), and does -not change the size of variable symbols, such as beams or slurs. - -One of the uses of @code{fontSize} is to get smaller symbols for cue -notes. An elaborate example of those is in -@inputfileref{input/test,cue-notes.ly}. - -@cindex magnification -@cindex cue notes - -The font used for printing a object can be selected by setting -@code{font-name}, e.g. -@example - \override Staff.TimeSignature - #'font-name = #"cmr17" -@end example - -@noindent -Any font can be used, as long as it is available to @TeX{}. Possible -fonts include foreign fonts or fonts that do not belong to the -Computer Modern font family. The size of fonts selected in this way -can be changed with the @code{font-magnification} property. For -example, @code{2.0} blows up all letters by a factor 2 in both -directions. - -@cindex font size -@cindex font magnification - -Font selection for the standard fonts, @TeX{}'s Computer Modern fonts, -can also be adjusted with a more fine-grained mechanism. By setting -the object properties described below, you can select a different font; -all three mechanisms work for every object that supports -@code{font-interface}: - - -@table @code -@item font-family - is 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, including ancient -glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}. - -@item font-shape - is a symbol indicating the shape of the font, there are typically several - font shapes available for each font family. Choices are @code{italic}, - @code{caps} and @code{upright}. - -@item font-series -is a symbol indicating the series of the font. There are typically several -font series for each font family and shape. Choices are @code{medium} -and @code{bold}. - -@end table - -For any of these properties, the value @code{*} (i.e. the symbol -@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used -to override default setting, which are always present. For example: -@example - \override Lyrics .LyricText #'font-series = #'bold - \override Lyrics .LyricText #'font-family = #'typewriter - \override Lyrics .LyricText #'font-shape = #'* -@end example - -@cindex @code{font-style} - -The font size is set by modifying the @code{font-size} property. Its -value is a number indicating the size relative to the standard size. -Each step up is an increase of approximately 12% of the font size. Six -steps is exactly a factor two. The Scheme function @code{magstep} -converts a @code{font-size} number to a scaling factor. - -LilyPond has fonts in different design sizes: the music fonts for -smaller sizes are chubbier, while the text fonts are relatively wider. -Font size changes are achieved by scaling the design size that is -closest to the desired size. - -The @code{font-size} mechanism does not work for fonts selected -through @code{font-name}. These may be scaled with -@code{font-magnification}. - -@refcommands - -The following commands set @code{fontSize} for the current voice. - -@cindex @code{\tiny} -@code{\tiny}, -@cindex @code{\small} -@code{\small}, -@cindex @code{\normalsize} -@code{\normalsize}. - -@seealso - -Init files: @file{ly/declarations-init.ly} contains hints how new -fonts may be added to LilyPond. - -@refbugs - -There is no style sheet provided for other fonts besides the @TeX{} -Computer Modern family. - -@cindex font selection -@cindex font magnification -@cindex @code{font-interface} - - -@node Text markup -@section Text markup -@cindex text markup -@cindex markup text - - -@cindex typeset text - -LilyPond has an internal mechanism to typeset texts. You can access it -with the keyword @code{\markup}. Within markup mode, you can enter texts -similar to lyrics: simply enter them, surrounded by spaces: -@cindex markup - -@lilypond[verbatim,fragment,relative=1] - c1^\markup { hello } - c1_\markup { hi there } - c1^\markup { hi \bold there, is \italic anyone home? } -@end lilypond - -@cindex font switching - -The markup in the example demonstrates font switching commands. The -command @code{\bold} and @code{\italic} only apply to the first -following word; enclose a set of texts with braces to apply a command -to more words: -@example - \markup @{ \bold @{ hi there @} @} -@end example - -@noindent -For clarity, you can also do this for single arguments, e.g. - -@verbatim - \markup { is \italic { anyone } home } -@end verbatim - -@cindex font size, texts - - -In markup mode you can compose expressions, similar to mathematical -expressions, XML documents and music expressions. The braces group -notes into horizontal lines. Other types of lists also exist: you can -stack expressions grouped with @code{<}, and @code{>} vertically with -the command @code{\column}. Similarly, @code{\center-align} aligns -texts by their center lines: - -@lilypond[verbatim,fragment,relative=1] - c1^\markup { \column < a bbbb c > } - c1^\markup { \center-align < a bbbb c > } - c1^\markup { \line < a b c > } -@end lilypond - - -Markups can be stored in variables, and these variables -may be attached to notes, like -@verbatim -allegro = \markup { \bold \large { Allegro } } -\notes { a^\allegro b c d } -@end verbatim - - -Some objects have alignment procedures of their own, which cancel out -any effects of alignments applied to their markup arguments as a -whole. For example, the @internalsref{RehearsalMark} is horizontally -centered, so using @code{\mark \markup @{ \left-align .. @}} has no -effect. Similarly, whole texts over notes cannot be moved vertically -with @code{\raise}. For moving and aligning complete objects, grob -properties should be used. - - - -@seealso - -Init files: @file{scm/new-markup.scm}. - - -@refbugs - -Text layout is ultimately done by @TeX{}, which does kerning of -letters. LilyPond does not account for kerning, so texts will be -spaced slightly too wide. - -Syntax errors for markup mode are confusing. - -Markup texts cannot be used in the titling of the @code{\header} -field. Titles are made by La@TeX{}, so La@TeX{} commands should be used -for formatting. - - - -@menu -* Overview of text markup commands:: -* Markup construction in scheme:: -* Markup command definition:: -@end menu - -@node Overview of text markup commands -@subsection Overview of text markup commands - -@include markup-commands.tely - -@node Markup construction in scheme -@subsection Markup construction in scheme - -@cindex defining markup commands - -The @code{markup} macro builds markup expressions in Scheme while -providing a LilyPond-like syntax. For example, -@example -(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world") - #:bigger #:line ("foo" "bar" "baz"))) -@end example - -@noindent -is equivalent to: -@example -\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @} - \bigger @{ foo bar baz @} > -@end example - -@noindent -This example exposes the main translation rules between regular -LilyPond markup syntax and scheme markup syntax, which are summed up -is this table: -@multitable @columnfractions .5 .5 -@item @b{LilyPond} @tab @b{Scheme} -@item @code{\command} @tab @code{#:command} -@item @code{\variable} @tab @code{variable} -@item @code{@{ ... @}} @tab @code{#:line ( ... )} -@item @code{\center-align < ... >} @tab @code{#:center ( ... )} -@item @code{string} @tab @code{"string"} -@item @code{#scheme-arg} @tab @code{scheme-arg} -@end multitable - -Besides, the whole scheme language is accessible inside the -@code{markup} macro: thus, one may use function calls inside -@code{markup} in order to manipulate character strings for -instance. This proves useful when defining new markup commands (see -@ref{Markup command definition}). - -@refbugs - -One can not feed the @code{#:line} (resp @code{#:center}, -@code{#:column}) command with a variable or the result of a function -call. Eg: -@lisp -(markup #:line (fun-that-returns-markups)) -@end lisp -is illegal. One should use the @code{make-line-markup} (resp -@code{make-center-markup}, @code{make-column-markup}) function -instead: -@lisp -(markup (make-line-markup (fun-that-returns-markups))) -@end lisp - -@node Markup command definition -@subsection Markup command definition - -New markup commands can be defined thanks to the @code{def-markup-command} scheme macro. -@lisp -(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...) - (@var{arg1-type?} @var{arg2-type?} ...) - ..command body..) - - @var{argi}: i@var{th} command argument - @var{argi-type?}: a type predicate for the i@var{th} argument - @var{paper}: the `paper' definition - @var{props}: a list of alists, containing all active properties. -@end lisp - -As a simple example, we show how to add a @code{\smallcaps} command, -which selects @TeX{}'s small caps font. Normally, we could select the -small caps font as follows: - -@verbatim - \markup { \override #'(font-shape . caps) Text-in-caps } -@end verbatim - -This selects the caps font by setting the @code{font-shape} property to -@code{#'caps} for interpreting @code{Text-in-caps}. - -To make the above available as @code{\smallcaps} command, we have to -define a function using @code{def-markup-command}. The command should -take a single argument, of markup type. Therefore, the start of the -definition should read -@example - (def-markup-command (smallcaps paper props argument) (markup?) -@end example - -@noindent - -What follows is the content of the command: we should interpret -the @code{argument} as a markup, i.e. - -@example - (interpret-markup paper @dots{} argument) -@end example - -@noindent -This interpretation should add @code{'(font-shape . caps)} to the active -properties, so we substitute the the following for the @dots{} in the -above example: - -@example - (cons (list '(font-shape . caps) ) props) -@end example - -@noindent -The variable @code{props} is a list of alists, and we prepend to it by -consing a list with the extra setting. - -However, suppose that we are using a font that does not have a -small-caps variant. In that case, we have to fake the small caps font, -by setting a string in upcase, with the first letter a little larger: - -@example -#(def-markup-command (smallcaps paper props str) (string?) - "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" - (interpret-markup paper props - (make-line-markup - (map (lambda (s) - (if (= (string-length s) 0) - s - (markup #:large (string-upcase (substring s 0 1)) - #:translate (cons -0.6 0) - #:tiny (string-upcase (substring s 1))))) - (string-split str #\Space))))) -@end example - -The @code{smallcaps} command first splits its string argument into -tokens separated by spaces (@code{(string-split str #\Space)}); for -each token, a markup is built with the first letter made large and -upcased (@code{#:large (string-upcase (substring s 0 1))}), and a -second markup built with the following letters made tiny and upcased -(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond -introduces a space between markups on a line, the second markup is -translated to the left (@code{#:translate (cons -0.6 0) ...}). Then, -the markups built for each token are put in a line -(@code{(make-line-markup ...)}). Finally, the resulting markup is -passed to the @code{interpret-markup} function, with the @code{paper} -and @code{props} arguments. - -Finally, suppose that we are typesetting a recitative in an opera, and -we would like to define a command that will show character names in a -custom manner. Names should be printed with small caps and translated a -bit to the left and top. We will define a @code{\character} command -that takes into account the needed translation, and uses the newly -defined @code{\smallcaps} command: - -@verbatim -#(def-markup-command (character paper props name) (string?) - "Print the character name in small caps, translated to the left and - top. Syntax: \\character #\"name\"" - (interpret-markup paper props - (markup "" #:translate (cons -4 2) #:smallcaps name))) -@end verbatim - -There is one complication that needs explanation: texts above and below -the staff are moved vertically to be at a certain distance (the -@code{padding} property) from the staff and the notes. To make sure -that this mechanism does not annihilate the vertical effect of our -@code{#:translate}, we add an empty string (@code{""}) before the -translated text. Now the @code{""} will be put above the notes, and the -@code{name} is moved in relation to that empty string. The net effect is -that the text is moved to the upper left. - -The final result is as follows: -@verbatim -\score { - \notes { \fatText - c''^\markup \character #"Cleopatra" - e'^\markup \character #"Giulio Cesare" - } -} -@end verbatim - -@lilypond[raggedright] -#(def-markup-command (smallcaps paper props str) (string?) - "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" - (interpret-markup paper props - (make-line-markup - (map (lambda (s) - (if (= (string-length s) 0) - s - (markup #:large (string-upcase (substring s 0 1)) - #:translate (cons -0.6 0) - #:tiny (string-upcase (substring s 1))))) - (string-split str #\Space))))) - -#(def-markup-command (character paper props name) (string?) - "Print the character name in small caps, translated to the left and - top. Syntax: \\character #\"name\"" - (interpret-markup paper props - (markup "" #:translate (cons -4 0) #:smallcaps name))) - -\score { - \notes { \fatText - c''^\markup \character #"Cleopatra" - e'^\markup \character #"Giulio Cesare" - } -} -@end lilypond - - - -@node Global layout -@section Global layout - -The global layout determined by three factors: the page layout, the -line breaks and the spacing. These all influence each other. The -choice of spacing determines how densely each system of music is set, -which influences where line breaks breaks are chosen, and thus -ultimately how many pages a piece of music takes. This section -explains how to tune the algorithm for spacing. - -Globally spoken, this procedure happens in three steps: first, -flexible distances (``springs'') are chosen, based on durations. All -possible line breaking combination are tried, and the one with the -best results---a layout that has uniform density and requires as -little stretching or cramping as possible---is chosen. When the score -is processed by @TeX{}, each page is filled with systems, and page breaks -are chosen whenever the page gets full. - - - -@menu -* Vertical spacing:: -* Horizontal spacing:: -* Font Size:: -* Line breaking:: -* Page layout:: -@end menu - - -@node Vertical spacing -@subsection Vertical spacing - -@cindex vertical spacing -@cindex distance between staves -@cindex staff distance -@cindex between staves, distance -@cindex staffs per page -@cindex space between staves - -The height of each system is determined automatically by LilyPond, to -keep systems from bumping into each other, some minimum distances are -set. By changing these, you can put staves closer together, and thus -put more systems onto one page. - -Normally staves are stacked vertically. To make -staves maintain a distance, their vertical size is padded. This is -done with the property @code{minimumVerticalExtent}. It takes a pair -of numbers, so if you want to make it smaller from its, then you could -set -@example - \set Staff.minimumVerticalExtent = #'(-4 . 4) -@end example -This sets the vertical size of the current staff to 4 staff spaces on -either side of the center staff line. The argument of -@code{minimumVerticalExtent} is interpreted as an interval, where the -center line is the 0, so the first number is generally negative. The -staff can be made larger at the bottom by setting it to @code{(-6 -. 4)}. - -The piano staves are handled a little differently: to make cross-staff -beaming work correctly, it is necessary that the distance between staves -is fixed beforehand. This is also done with a -@internalsref{VerticalAlignment} object, created in -@internalsref{PianoStaff}. In this object the distance between the -staves is fixed by setting @code{forced-distance}. If you want to -override this, use a @code{\translator} block as follows: -@example - \paper @{ - \translator @{ - \PianoStaffContext - \override VerticalAlignment #'forced-distance = #9 - @} - @dots{} - @} -@end example -This would bring the staves together at a distance of 9 staff spaces, -measured from the center line of each staff. - -@seealso - -Internals: Vertical alignment of staves is handled by the -@internalsref{VerticalAlignment} object. - - - - -@node Horizontal spacing -@subsection Horizontal Spacing - -The spacing engine translates differences in durations into -stretchable distances (``springs'') of differing lengths. Longer -durations get more space, shorter durations get less. The shortest -durations get a fixed amount of space (which is controlled by -@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object). -The longer the duration, the more space it gets: doubling a -duration adds a fixed amount (this amount is controlled by -@code{spacing-increment}) of space to the note. - -For example, the following piece contains lots of half, quarter and -8th notes, the eighth note is followed by 1 note head width (NHW). -The quarter note is followed by 2 NHW, the half by 3 NHW, etc. -@lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8 -c8 c4 c4 c4 -@end lilypond - -Normally, @code{shortest-duration-space} is set to 1.2, which is the -width of a note head, and @code{shortest-duration-space} is set to -2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times -@code{shortest-duration-space}) of space. For normal notes, this space -is always counted from the left edge of the symbol, so the shortest -notes are generally followed by one NHW of space. - -If one would follow the above procedure exactly, then adding a single -32th note to a score that uses 8th and 16th notes, would widen up the -entire score a lot. The shortest note is no longer a 16th, but a 32nd, -thus adding 1 NHW to every note. To prevent this, the -shortest duration for spacing is not the shortest note in the score, -but the most commonly found shortest note. Notes that are even -shorter this are followed by a space that is proportional to their -duration relative to the common shortest note. So if we were to add -only a few 16th notes to the example above, they would be followed by -half a NHW: - -@lilypond[fragment,verbatim,relative=2] - c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4 -@end lilypond - -The most common shortest duration is determined as follows: in every -measure, the shortest duration is determined. The most common short -duration, is taken as the basis for the spacing, with the stipulation -that this shortest duration should always be equal to or shorter than -1/8th note. The shortest duration is printed when you run lilypond -with @code{--verbose}. These durations may also be customized. If you -set the @code{common-shortest-duration} in -@internalsref{SpacingSpanner}, then this sets the base duration for -spacing. The maximum duration for this base (normally 1/8th), is set -through @code{base-shortest-duration}. - -@cindex @code{common-shortest-duration} -@cindex @code{base-shortest-duration} -@cindex @code{stem-spacing-correction} -@cindex @code{spacing} - -In the introduction it was explained that stem directions influence -spacing. This is controlled with @code{stem-spacing-correction} -property in @internalsref{NoteSpacing}, which are generated for every -@internalsref{Voice} context. The @code{StaffSpacing} object -(generated at @internalsref{Staff} context) contains the same property -for controlling the stem/bar line spacing. The following example -shows these corrections, once with default settings, and once with -exaggerated corrections: - -@lilypond - \score { \notes { - c'4 e''4 e'4 b'4 | - b'4 e''4 b'4 e''4| - \override Staff.NoteSpacing #'stem-spacing-correction - = #1.5 - \override Staff.StaffSpacing #'stem-spacing-correction - = #1.5 - c'4 e''4 e'4 b'4 | - b'4 e''4 b'4 e''4| - } - \paper { raggedright = ##t } } -@end lilypond - -@cindex SpacingSpanner, overriding properties - -Properties of the @internalsref{SpacingSpanner} must be overridden -from the @code{\paper} block, since the @internalsref{SpacingSpanner} is -created before any property commands are interpreted. -@example -\paper @{ \translator @{ - \ScoreContext - SpacingSpanner \override #'spacing-increment = #3.0 -@} @} -@end example - - -@seealso - -Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, -@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and -@internalsref{SeparatingGroupSpanner}. - -@refbugs - -Spacing is determined on a score wide basis. If you have a score that -changes its character (measured in durations) halfway during the -score, the part containing the longer durations will be spaced too -widely. - -There is no convenient mechanism to manually override spacing. - - - -@node Font Size -@subsection Font size -@cindex font size, setting -@cindex staff size, setting -@cindex @code{paper} file - -The Feta font provides musical symbols at eight seven different -sizes. Each font is tuned for a different staff size: at smaller sizes -the font gets heavier, to match the relatively heavier staff lines. -The recommended font sizes are listed in the following table: - -@multitable @columnfractions .25 .25 .25 .25 - -@item @b{name} -@tab @b{staff height (pt)} -@tab @b{staff height (mm)} -@tab @b{use} - -@item feta11 -@tab 11.22 -@tab 3.9 -@tab pocket scores - -@item feta13 -@tab 12.60pt -@tab 4.4mm -@tab - -@item feta14 -@tab 14.14pt -@tab 5.0mm -@tab - -@item feta16 -@tab 15.87pt -@tab 5.6mm -@tab - -@item feta18 -@tab 17.82pt -@tab 6.3mm -@tab song books - -@item feta20 -@tab 17.82pt -@tab 7.0mm -@tab standard parts - -@item feta23 -@tab 22.45 pt -@tab 7.9mm -@tab - -@item feta20 -@tab 25.2 pt -@tab 8.9mm -@tab -@c modern rental material ? - -@end multitable - -These fonts are available in any sizes. The context property -@code{fontSize} and the layout property @code{staff-space} (in -@internalsref{StaffSymbol}) can be used to tune size for individual -staffs. The size of individual staffs are relative to the global size, -which can be set in the following manner: - -@example - #(set-global-staff-size 14) -@end example - -This sets the global default size to 14pt staff height, and scales all -fonts accordingly. - - - -@node Line breaking -@subsection Line breaking - -@cindex line breaks -@cindex breaking lines - -Line breaks are normally computed automatically. They are chosen such -that lines look neither cramped nor loose, and that consecutive lines -have similar density. - -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. 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 -point. - - -@cindex regular line breaks -@cindex four bar music. - -For line breaks at regular intervals use @code{\break} separated by -skips and repeated with @code{\repeat}: -@example -<< \repeat unfold 7 @{ - s1 \noBreak s1 \noBreak - s1 \noBreak s1 \break @} - @emph{the real music} ->> -@end example - -@noindent -This makes the following 28 measures (assuming 4/4 time) be broken every -4 measures, and only there. - -@refcommands - -@code{\break}, @code{\noBreak} -@cindex @code{\break} -@cindex @code{\noBreak} - -@seealso - -Internals: @internalsref{BreakEvent}. - - -@node Page layout -@subsection Page layout - -@cindex page breaks -@cindex breaking pages - -@cindex @code{indent} -@cindex @code{linewidth} - -The most basic settings influencing the spacing are @code{indent} and -@code{linewidth}. They are set in the @code{\paper} block. They -control the indentation of the first line of music, and the lengths of -the lines. - -If @code{raggedright} is set to true in the @code{\paper} -block, then the lines are justified at their natural length. This -useful for short fragments, and for checking how tight the natural -spacing is. - -@cindex page layout -@cindex vertical spacing - -The page layout process happens outside the LilyPond formatting -engine: variables controlling page layout are passed to the output, -and are further interpreted by @code{lilypond} wrapper program. It -responds to the following variables in the @code{\paper} block. The -variable @code{textheight} sets the total height of the music on each -page. The spacing between systems is controlled with -@code{interscoreline}, its default is 16pt. The distance between the -score lines will stretch in order to fill the full page -@code{interscorelinefill} is set to a positive number. In that case -@code{interscoreline} specifies the minimum spacing. - -@cindex @code{textheight} -@cindex @code{interscoreline} -@cindex @code{interscorelinefill} - -If the variable @code{lastpagefill} is defined, -@c fixme: this should only be done if lastpagefill= #t -systems are evenly distributed vertically on the last page. This -might produce ugly results in case there are not enough systems on the -last page. The @command{lilypond-book} command ignores -@code{lastpagefill}. See @ref{lilypond-book manual} for more -information. - -@cindex @code{lastpagefill} - -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. This -is done by setting the @code{between-systems-strings} on the -@internalsref{NonMusicalPaperColumn} where the system is broken. -An example is shown in @inputfileref{input/regression,between-systems.ly}. -The predefined command @code{\newpage} also does this. - -@cindex paper size -@cindex page size -@cindex @code{papersize} - -To change the paper size, use the following Scheme code: -@example - \paper@{ - #(set-paper-size "a4") - @} -@end example - - -@refcommands - -@cindex @code{\newpage} -@code{\newpage}. - - -@seealso - -In this manual: @ref{Invoking lilypond}. - -Examples: @inputfileref{input/regression,between-systems.ly}. - -Internals: @internalsref{NonMusicalPaperColumn}. - -@refbugs - -LilyPond has no concept of page layout, which makes it difficult to -reliably choose page breaks in longer pieces. - - - - -@node Sound -@section Sound -@cindex Sound - -Entered music can also be converted to MIDI output. The performance -is good enough for proof-hearing the music for errors. - -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 volume vary linearly between -their two extremities. The fractions can be adjusted by -@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context. -For each type of MIDI instrument, a volume range can be defined. This -gives a basic equalizer control, which can enhance the quality of -the MIDI output remarkably. The equalizer can be controlled by -setting @code{instrumentEqualizer}. - -@refbugs - -Many musically interesting effects, such as swing, articulation, -slurring, etc., are not translated to MIDI. - -Since slurs are not interpreted, @code{\lyricsto} and -@code{\addlyrics} sections will be interpreted wrongly. - -The MIDI output allocates a channel for each Staff, and one for global -settings. Hence, the MIDI file should not have more than 15 staves -(or 14 if you do not use drums). - - -@menu -* MIDI block:: -* MIDI instrument names:: -@end menu - - -@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, and - @item context definitions. -@end itemize - -Assignments in the @code{\midi} block are not allowed. - -A number followed by a period is interpreted as a real number, so -for setting the tempo for dotted notes, an extra space should be -inserted, for example: - -@example - \midi @{ \tempo 4 . = 120 @} -@end example - - -@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-init.ly}. - - -@node MIDI instrument names -@subsection MIDI instrument names - -@cindex instrument names -@cindex @code{Staff.midiInstrument} - -The MIDI instrument name is set by the @code{Staff.midiInstrument} -property. The instrument name should be chosen from the list in -@ref{MIDI instruments}. - -@refbugs - -If the selected string does not exactly match, then the default is -used, which is the Grand Piano. - diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 4a03f90ef9..0f47b487d0 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -808,8 +808,8 @@ braces at the end of an expression. For example, @end example -For more information on context see the Technical manual description -in @ref{Interpretation context}. +For more information on context see the description in +@ref{Interpretation context}. diff --git a/make/lilypond.redhat.spec.in b/make/lilypond.redhat.spec.in index 39e9e88827..503b362073 100644 --- a/make/lilypond.redhat.spec.in +++ b/make/lilypond.redhat.spec.in @@ -107,7 +107,7 @@ fi /sbin/install-info --delete %{_infodir}/music-glossary.info.gz %{_infodir}/dir %endif -# chkfontpath --remove=%{_datadir}/share/lilypond/@TOPLEVEL_VERSION@/fonts/type1/ +# chkfontpath --remove=%{_datadir}/share/lilypond/@TOPLEVEL_VERSION@/fonts/type1n/ %postun @@ -144,7 +144,7 @@ scrollkeeper-update %doc NEWS.txt %if %{info} -%{_infodir}/* +%{_infodir}/lilypond/ %endif %{_mandir}/man1/abc2ly.1.gz diff --git a/scm/define-markup-commands.scm b/scm/define-markup-commands.scm index d4b0a3f7f3..3b1e6d1183 100644 --- a/scm/define-markup-commands.scm +++ b/scm/define-markup-commands.scm @@ -263,7 +263,7 @@ letter 'A'." This raises @var{arg}, by the distance @var{amount}. A negative @var{amount} indicates lowering: @c -@lilypond[verbatim,fragment,relative=1,quote] +@lilypond[verbatim,fragment,relative=1] c1^\\markup { C \\small \\raise #1.0 \\bold { \"9/7+\" }} @end lilypond The argument to @code{\\raise} is the vertical displacement amount, diff --git a/scm/documentation-generate.scm b/scm/documentation-generate.scm index 6062aae507..8c47ee1021 100644 --- a/scm/documentation-generate.scm +++ b/scm/documentation-generate.scm @@ -28,55 +28,24 @@ )) (map ly:load load-files) - -;;(define no-copies #t) ; from 490 to 410K, but doesn't look nice yet -;; -;; Also, copies of interfaces use up lots more space, but that's -;; functional because the default property values of the interfaces -;; are described... -(define no-copies #f) - - - - - - - - - - - - ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(dump-node (all-scheme-functions-doc) - (open-output-file "scheme-functions.tely") - 2) +(display + (slot-ref (all-scheme-functions-doc) 'text) + (open-output-file "scheme-functions.tely")) (display (markup-doc-string) + (open-output-file "markup-commands.tely")) - (open-output-file "markup-commands.tely") - ) -(dump-node - (make - #:name "Layout property overview" - #:desc "All user serviceable layout properties" - #:text (backend-properties-doc-string all-user-grob-properties)) - - (open-output-file "layout-properties.tely") - 2) - -(dump-node - (make - #:name "Context property overview" - #:desc "All user serviceable context properties" - #:text (translation-properties-doc-string all-user-translation-properties)) - - (open-output-file "context-properties.tely") - 2) +(display + (backend-properties-doc-string all-user-grob-properties) + (open-output-file "layout-properties.tely") ) +(display + (translation-properties-doc-string all-user-translation-properties) + (open-output-file "context-properties.tely") ) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; diff --git a/scm/new-markup.scm b/scm/new-markup.scm index a4174f94e0..b3f3d6d046 100644 --- a/scm/new-markup.scm +++ b/scm/new-markup.scm @@ -214,6 +214,43 @@ eg (make-COMMAND-markup arg1 arg2 ...), and the rest expression." (values (cons 'list (compile-all-markup-args (car expr))) (cdr expr))) (else (values (car expr) (cdr expr))))) +;;;;;;;;;;;;;;; +;;; Debugging utilities: print markup expressions in a friendly fashion + +(use-modules (ice-9 format)) +(define (markup->string markup-expr) + "Return a string describing, in LilyPond syntax, the given markup expression." + (define (proc->command proc) + (let ((cmd-markup (symbol->string (procedure-name proc)))) + (substring cmd-markup 0 (- (string-length cmd-markup) + (string-length "-markup"))))) + (define (arg->string arg) + (cond ((and (pair? arg) (pair? (car arg))) ;; markup list + (format #f "~{ ~a~}" (map markup->string arg))) + ((pair? arg) ;; markup + (markup->string arg)) + ((string? arg) ;; scheme string argument + (format #f "#\"~a\"" arg)) + (else ;; other scheme arg + (format #f "#~a" arg)))) + (let ((cmd (car markup-expr)) + (args (cdr markup-expr))) + (cond ((eqv? cmd simple-markup) ;; a simple string + (format #f "\"~a\"" (car args))) + ((eqv? cmd line-markup) ;; { ... } + (format #f "{~a}" (arg->string (car args)))) + ((eqv? cmd center-align-markup) ;; \center < ... > + (format #f "\\center-align <~a>" (arg->string (car args)))) + ((eqv? cmd column-markup) ;; \column < ... > + (format #f "\\column <~a>" (arg->string (car args)))) + (else ;; \command ... + (format #f "\\~a~{ ~a~} " (proc->command cmd) (map arg->string args)))))) + +(define-public (display-markup markup-expr) + "Print a LilyPond-syntax equivalent for the given markup expression." + (display "\\markup ") + (display (markup->string markup-expr))) + ;;;;;;;;;;;;;;; ;;; Utilities for storing and accessing markup commands signature ;;; and keyword.