From fcfc36d5bef8efa35d3004c706816ce70ece9196 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Thu, 4 Nov 2004 22:14:10 +0000 Subject: [PATCH] * Documentation/user/*: A new round of layout fixes and document structure cleanup. --- ChangeLog | 5 + Documentation/user/changing-defaults.itely | 1196 +++++++++-------- Documentation/user/cheatsheet.itely | 6 +- Documentation/user/converters.itely | 193 +-- Documentation/user/examples.itely | 46 +- Documentation/user/introduction.itely | 42 +- Documentation/user/lilypond-book.itely | 242 ++-- Documentation/user/lilypond.tely | 10 +- Documentation/user/macros.itexi | 2 +- Documentation/user/music-glossary.tely | 238 ++-- Documentation/user/notation.itely | 200 +-- Documentation/user/point-and-click.itely | 52 +- .../user/programming-interface.itely | 434 +++--- Documentation/user/scheme-tutorial.itely | 149 +- Documentation/user/tutorial.itely | 8 +- 15 files changed, 1448 insertions(+), 1375 deletions(-) diff --git a/ChangeLog b/ChangeLog index ff6e79126b..12289c3da0 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2004-11-04 Werner Lemberg + + * Documentation/user/*: A new round of layout fixes and document + structure cleanup. + 2004-11-04 Heikki Junes * Documentation/user/lilypond.tely: changes 2.3.x to 2.5.x. diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 8d9693e1c2..ce6081725f 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -4,10 +4,10 @@ The purpose of LilyPond's design is to provide the finest output -quality as a default. Nevertheless, it may happen that you need to +quality as a default. Nevertheless, it may happen that you need to change this default layout. The layout is controlled through a large number of proverbial ``knobs and switches.'' This chapter does not -list each and every knob. Rather, it outlines what groups of controls +list each and every knob. Rather, it outlines what groups of controls are available and explains how to lookup which knob to use for a certain effect. @@ -15,28 +15,31 @@ certain effect. @cindex Program reference The controls available for tuning are described in a separate -document, the @internalsref{Program reference} manual. That manual +document, the @internalsref{Program reference} manual. That manual lists all different variables, functions and options available in -LilyPond. It is written as a HTML document, which is available +LilyPond. It is written as a HTML document, which is available @uref{http://@/lilypond@/.org/@/doc/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line}, but is also included with the LilyPond documentation package. There are three areas where the default settings may be changed: @itemize @bullet -@item Output: changing the appearance of individual - objects. For example, changing stem directions, or the location of - subscripts. +@item +Output: changing the appearance of individual +objects. For example, changing stem directions, or the location of +subscripts. -@item Context: changing aspects of the translation from music events to - notation. For example, giving each staff a separate time signature. +@item +Context: changing aspects of the translation from music events to +notation. For example, giving each staff a separate time signature. -@item Global layout: changing the appearance of the spacing, line - breaks and page dimensions. +@item +Global layout: changing the appearance of the spacing, line +breaks and page dimensions. @end itemize Then, there are separate systems for typesetting text (like -@emph{ritardando}) and selecting different fonts. This chapter also +@emph{ritardando}) and selecting different fonts. This chapter also discusses these. Internally, LilyPond uses Scheme (a LISP dialect) to provide @@ -64,14 +67,14 @@ When music is printed, a lot of notation elements must be added to the input, which is often bare bones. For example, compare the input and output of the following example: -@lilypond[verbatim,relative=2,fragment] - cis4 cis2. g4 +@lilypond[quote,verbatim,relative=2,fragment] +cis4 cis2. g4 @end lilypond The input is rather sparse, but in the output, bar lines, accidentals, -clef, and time signature are added. LilyPond @emph{interprets} the -input. During this step, the musical information is inspected in time -order, similar to reading a score from left to right. While reading, +clef, and time signature are added. LilyPond @emph{interprets} the +input. During this step, the musical information is inspected in time +order, similar to reading a score from left to right. While reading, the program remembers where measure boundaries are, and what pitches need explicit accidentals. This information can be presented on several levels. For example, the effect of an accidental is limited @@ -79,7 +82,7 @@ to a single stave, while a bar line must be synchronized across the entire score. Within LilyPond, these rules and bits of information are grouped in -so-called Contexts. Examples of context are @context{Voice}, +so-called Contexts. Examples of context are @context{Voice}, @context{Staff}, and @context{Score}. They are hierarchical, for example, a @context{Staff} can contain many @context{Voice}s, and a @context{Score} can contain many @context{Staff} contexts. @@ -92,7 +95,7 @@ accidentals and then the @context{Staff} context maintains the rule to show or suppress the accidental for the remainder of the measure. For simple scores, contexts are created implicitly, and you need not -be aware of them. For larger pieces, such as piano music, they must be +be aware of them. For larger pieces, such as piano music, they must be created explicitly to make sure that you get as many staves as you need, and that they are in the correct order. For typesetting pieces with specialized notation, it can be useful to modify existing or @@ -124,7 +127,7 @@ Translation @arrow{} Context. @subsection Creating contexts For scores with only one voice and one staff, correct contexts are -created automatically. For more complex scores, it is necessary to +created automatically. For more complex scores, it is necessary to create them by hand. There are three commands which do this. The easiest command is @code{\new}, and it also the quickest to type. @@ -135,7 +138,7 @@ It is prepended to a music expression, for example @cindex Context, creating @example - \new @var{type} @var{music expression} +\new @var{type} @var{music expression} @end example @noindent @@ -144,32 +147,32 @@ where @var{type} is a context name (like @code{Staff} or interpreting @var{music expression} with that. A practical application of @code{\new} is a score with many -staves. Each part that should be on its own staff, is preceded with +staves. Each part that should be on its own staff, is preceded with @code{\new Staff}. -@lilypond[verbatim,relative=2,raggedright,fragment] - << \new Staff { c4 c } - \new Staff { d4 d } - >> +@lilypond[quote,verbatim,relative=2,raggedright,fragment] +<< \new Staff { c4 c } + \new Staff { d4 d } +>> @end lilypond @cindex @code{\context} Like @code{\new}, the @code{\context} command also directs a music -expression to a context object, but gives the context an extra name. The +expression to a context object, but gives the context an extra name. The syntax is @example - \context @var{type} = @var{id} @var{music} +\context @var{type} = @var{id} @var{music} @end example This form will search for an existing context of type @var{type} -called @var{id}. If that context does not exist yet, it is created. -This is useful if the context is referred to later on. For example, when +called @var{id}. If that context does not exist yet, it is created. +This is useful if the context is referred to later on. For example, when setting lyrics the melody is in a named context @example - \context Voice = "@b{tenor}" @var{music} +\context Voice = "@b{tenor}" @var{music} @end example @noindent @@ -182,27 +185,28 @@ so the texts can be properly aligned to its notes, @noindent Another possibility is funneling two different music expressions into -one context. In the following example, articulations and notes are +one context. In the following example, articulations and notes are entered separately, -@verbatim -music = { c4 c4 } -arts = { s4-. s4-> } -@end verbatim +@example +music = @{ c4 c4 @} +arts = @{ s4-. s4-> @} +@end example They are combined by sending both to the same @context{Voice} context, -@verbatim - << \new Staff \context Voice = "A" \music - \context Voice = "A" \arts - >> -@end verbatim -@lilypond[raggedright] -music = { c4 c4 } -arts = { s4-. s4-> } - \relative c'' << \new Staff \context Voice = "A" \music - \context Voice = "A" \arts - >> +@example +<< \new Staff \context Voice = "A" \music + \context Voice = "A" \arts +>> +@end example +@lilypond[quote,raggedright] +music = { c4 c4 } +arts = { s4-. s4-> } +\relative c'' << + \new Staff \context Voice = "A" \music + \context Voice = "A" \arts +>> @end lilypond With this mechanism, it is possible to define an Urtext (original @@ -214,7 +218,7 @@ same notes. The third command for creating contexts is @example - \context @var{type} @var{music} +\context @var{type} @var{music} @end example @@ -223,20 +227,20 @@ This is similar to @code{\context} with @code{= @var{id}}, but matches any context of type @var{type}, regardless of its given name. This variant is used with music expressions that can be interpreted at -several levels. For example, the @code{\applyoutput} command (see -@ref{Running a function on all layout objects}). Without an explicit +several levels. For example, the @code{\applyoutput} command (see +@ref{Running a function on all layout objects}). Without an explicit @code{\context}, it is usually is applied to @context{Voice} @example - \applyoutput #@var{function} % apply to Voice +\applyoutput #@var{function} % apply to Voice @end example To have it interpreted at the @context{Score} or @context{Staff} level use these forms @example - \context Score \applyoutput #@var{function} - \context Staff \applyoutput #@var{function} +\context Score \applyoutput #@var{function} +\context Staff \applyoutput #@var{function} @end example @@ -248,32 +252,32 @@ these forms @cindex changing properties Each context can have different @emph{properties}, variables contained -in that context. They can be changed during the interpretation step. +in that context. They can be changed during the interpretation step. This is achieved by inserting the @code{\set} command in the music, -@quotation - @code{\set } @var{context}@code{.}@var{prop}@code{ = #}@var{value} -@end quotation +@example +\set @var{context}.@var{prop} = #@var{value} +@end example For example, -@lilypond[verbatim,relative=2,fragment] - R1*2 - \set Score.skipBars = ##t - R1*2 +@lilypond[quote,verbatim,relative=2,fragment] +R1*2 +\set Score.skipBars = ##t +R1*2 @end lilypond -This command skips measures that have no notes. The result is that -multi rests are condensed. The value assigned is a Scheme object. In +This command skips measures that have no notes. The result is that +multi rests are condensed. The value assigned is a Scheme object. In this case, it is @code{#t}, the boolean True value. If the @var{context} argument is left out, then the current bottom-most context (typically @context{ChordNames}, @context{Voice}, or @context{Lyrics}) is used. In this example, -@lilypond[verbatim,relative=2,fragment] - c8 c c c - \set autoBeaming = ##f - c8 c c c +@lilypond[quote,verbatim,relative=2,fragment] +c8 c c c +\set autoBeaming = ##f +c8 c c c @end lilypond @noindent @@ -282,48 +286,48 @@ beaming is switched off in the current @internalsref{Voice}. Contexts are hierarchical, so if a bigger context was specified, for example @context{Staff}, then the change would also apply to all -@context{Voice}s in the current stave. The change is applied +@context{Voice}s in the current stave. The change is applied `on-the-fly', during the music, so that the setting only affects the second group of eighth notes. @cindex @code{\unset} There is also an @code{\unset} command, -@quotation - @code{\unset }@var{context}@code{.}@var{prop} -@end quotation +@example +\unset @var{context}.@var{prop} +@end example @noindent -which removes the definition of @var{prop}. This command removes +which removes the definition of @var{prop}. This command removes the definition only if it is set in @var{context}, so @example - \set Staff.autoBeaming = ##f +\set Staff.autoBeaming = ##f @end example @noindent -introduces a property setting at @code{Staff} level. The setting also -applies to the current @code{Voice}. However, +introduces a property setting at @code{Staff} level. The setting also +applies to the current @code{Voice}. However, @example - \unset Voice.autoBeaming +\unset Voice.autoBeaming @end example @noindent -does not have any effect. To cancel this setting, the @code{\unset} -must be specified on the same level as the original @code{\set}. In +does not have any effect. To cancel this setting, the @code{\unset} +must be specified on the same level as the original @code{\set}. In other words, undoing the effect of @code{Staff.autoBeaming = ##f} requires @example - \unset Staff.autoBeaming +\unset Staff.autoBeaming @end example Like @code{\set}, the @var{context} argument does not have to be specified for a bottom context, so the two statements @example - \set Voice.autoBeaming = ##t - \set autoBeaming = ##t +\set Voice.autoBeaming = ##t +\set autoBeaming = ##t @end example @noindent @@ -334,11 +338,11 @@ are equivalent. Settings that should only apply to a single time-step can be entered with @code{\once}, for example in -@lilypond[verbatim,relative=2,fragment] - c4 - \once \set fontSize = #4.7 - c4 - c4 +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\once \set fontSize = #4.7 +c4 +c4 @end lilypond the property @code{fontSize} is unset automatically after the second @@ -359,7 +363,7 @@ Translation @arrow{} Tunable context properties. Notation contexts (like Score and Staff) not only store properties, they also contain plug-ins, called ``engravers'' that create notation -elements. For example, the Voice context contains a +elements. For example, the Voice context contains a @code{Note_head_engraver} and the Staff context contains a @code{Key_signature_engraver}. @@ -380,26 +384,27 @@ Program reference @arrow Translation @arrow{} Context. lists the engravers used for that context. -It can be useful to shuffle around these plug-ins. This is done by +It can be useful to shuffle around these plug-ins. This is done by starting a new context, with @code{\new} or @code{\context}, and modifying it like this, @example - \new @var{context} \with @{ - \consists @dots{} - \consists @dots{} - \remove @dots{} - \remove @dots{} - @emph{etc.} - @} - @var{..music..} +\new @var{context} \with @{ + \consists @dots{} + \consists @dots{} + \remove @dots{} + \remove @dots{} + @emph{etc.} +@} +@emph{..music..} @end example -where the @dots{} should be the name of an engraver. Here is a simple +@noindent +where the @dots{} should be the name of an engraver. Here is a simple example which removes @code{Time_signature_engraver} and @code{Clef_engraver} from a @code{Staff} context, -@lilypond[relative=1, verbatim,fragment] +@lilypond[quote,relative=1,verbatim,fragment] << \new Staff { f2 g } @@ -414,14 +419,14 @@ example which removes @code{Time_signature_engraver} and In the second stave there are no time signature or clef symbols. This is a rather crude method of making objects disappear since it will affect -the entire staff. The spacing is adversely influenced too. A more +the entire staff. The spacing is adversely influenced too. A more sophisticated methods of blanking objects is shown in @ref{Common tweaks}. The next example shows a practical application. Bar lines and time signatures are normally synchronized across the score. This is done -by the @code{Timing_engraver}. This plug-in keeps an administration of -time signature, location within the measure, etc. By moving the +by the @code{Timing_engraver}. This plug-in keeps an administration of +time signature, location within the measure, etc. By moving the @code{Timing_engraver} engraver from @code{Score} to @code{Staff} context, we can have a score where each staff has its own time signature. @@ -429,7 +434,7 @@ signature. @cindex polymetric scores -@lilypond[relative=1,raggedright,verbatim,fragment] +@lilypond[quote,relative=1,raggedright,verbatim,fragment] \new Score \with { \remove "Timing_engraver" } << @@ -453,84 +458,84 @@ signature. @subsection Layout tunings within contexts Each context is responsible for creating certain types of graphical -objects. The settings used for printing these objects are also stored by -context. By changing these settings, the appearance of objects can be +objects. The settings used for printing these objects are also stored by +context. By changing these settings, the appearance of objects can be altered. The syntax for this is @example - \override @var{context}.@var{name}@code{ #'}@var{property} = #@var{value} +\override @var{context}.@var{name} #'@var{property} = #@var{value} @end example Here @var{name} is the name of a graphical object, like @code{Stem} or @code{NoteHead}, and @var{property} is an internal variable of the -formatting system (`grob property' or `layout property'). The latter is a -symbol, so it must be quoted. The subsection @ref{Constructing a +formatting system (`grob property' or `layout property'). The latter is a +symbol, so it must be quoted. The subsection @ref{Constructing a tweak} explains what to fill in for @var{name}, @var{property}, and -@var{value}. Here we only discuss functionality of this command. +@var{value}. Here we only discuss functionality of this command. The command @verbatim - \override Staff.Stem #'thickness = #4.0 +\override Staff.Stem #'thickness = #4.0 @end verbatim @noindent makes stems thicker (the default is 1.3, with staff line thickness as a -unit). Since the command specifies @context{Staff} as context, it only -applies to the current staff. Other staves will keep their normal +unit). Since the command specifies @context{Staff} as context, it only +applies to the current staff. Other staves will keep their normal appearance. Here we see the command in action: -@lilypond[verbatim,relative=2,fragment] - c4 - \override Staff.Stem #'thickness = #4.0 - c4 - c4 - c4 +@lilypond[quote,verbatim,relative=2,fragment] +c4 +\override Staff.Stem #'thickness = #4.0 +c4 +c4 +c4 @end lilypond The @code{\override} command changes the definition of the @code{Stem} -within the current @context{Staff}. After the command is interpreted +within the current @context{Staff}. After the command is interpreted all stems are thickened. Analogous to @code{\set}, the @var{context} argument may be left out, causing it to default to @context{Voice}, and adding @code{\once} applies the change during one timestep only -@lilypond[fragment,verbatim,relative=2] - c4 - \once \override Stem #'thickness = #4.0 - c4 - c4 +@lilypond[quote,fragment,verbatim,relative=2] +c4 +\once \override Stem #'thickness = #4.0 +c4 +c4 @end lilypond The @code{\override} must be done before the object is -started. Therefore, when altering @emph{Spanner} objects, like slurs or +started. Therefore, when altering @emph{Spanner} objects, like slurs or beams, the @code{\override} command must be executed at the moment when -the object is created. In this example, +the object is created. In this example, -@lilypond[fragment,verbatim,relative=2] - \override Slur #'thickness = #3.0 - c8[( c - \override Beam #'thickness = #0.6 - c8 c]) +@lilypond[quote,fragment,verbatim,relative=2] +\override Slur #'thickness = #3.0 +c8[( c +\override Beam #'thickness = #0.6 +c8 c]) @end lilypond @noindent -the slur is fatter but the beam is not. This is because the command for -@code{Beam} comes after the Beam is started. Therefore it has no effect. +the slur is fatter but the beam is not. This is because the command for +@code{Beam} comes after the Beam is started. Therefore it has no effect. Analogous to @code{\unset}, the @code{\revert} command for a context undoes a @code{\override} command; like with @code{\unset}, it only -affects settings that were made in the same context. In other words, the +affects settings that were made in the same context. In other words, the @code{\revert} in the next example does not do anything. -@verbatim - \override Voice.Stem #'thickness = #4.0 - \revert Staff.Stem #'thickness -@end verbatim +@example +\override Voice.Stem #'thickness = #4.0 +\revert Staff.Stem #'thickness +@end example @@ -572,7 +577,7 @@ from the music, in the @code{\layout} block, Here @example - \Staff +\Staff @end example @noindent @@ -581,9 +586,9 @@ identifier @code{\Staff}. The statements @example - \set fontSize = #-2 - \override Stem #'thickness = #4.0 - \remove "Time_signature_engraver" +\set fontSize = #-2 +\override Stem #'thickness = #4.0 +\remove "Time_signature_engraver" @end example @noindent @@ -621,30 +626,29 @@ contexts. The next example shows how to build a different type of @context{Voice} context from scratch. It will be similar to -@code{Voice}, but print centered slash noteheads only. It can be used +@code{Voice}, but print centered slash noteheads only. It can be used to indicate improvisation in Jazz pieces, -@lilypond[raggedright] - \layout { \context { - \name ImproVoice - \type "Engraver_group_engraver" - \consists "Note_heads_engraver" - \consists "Text_engraver" - \consists Pitch_squash_engraver - squashedPosition = #0 - \override NoteHead #'style = #'slash - \override Stem #'transparent = ##t - \alias Voice - } - \context { \Staff - \accepts "ImproVoice" - }} - +@lilypond[quote,raggedright] +\layout { \context { + \name ImproVoice + \type "Engraver_group_engraver" + \consists "Note_heads_engraver" + \consists "Text_engraver" + \consists Pitch_squash_engraver + squashedPosition = #0 + \override NoteHead #'style = #'slash + \override Stem #'transparent = ##t + \alias Voice +} +\context { \Staff + \accepts "ImproVoice" +}} \relative c'' { - a4 d8 bes8 \new ImproVoice { c4^"ad lib" c - c4 c^"undress" c_"while playing :)" c } - a1 + a4 d8 bes8 \new ImproVoice { c4^"ad lib" c + c4 c^"undress" c_"while playing :)" c } + a1 } @end lilypond @@ -653,56 +657,56 @@ These settings are again done within a @code{\context} block inside a @code{\layout} block, @example - \layout @{ - \context @{ - @dots{} - @} +\layout @{ + \context @{ + @dots{} @} +@} @end example In the following discussion, the example input shown should go on the @dots{} in the previous fragment. -First, name the context gets a name. Instead of @context{Voice} it +First, name the context gets a name. Instead of @context{Voice} it will be called @context{ImproVoice}, -@verbatim - \name ImproVoice -@end verbatim +@example +\name ImproVoice +@end example Since it is similar to the @context{Voice}, we want commands that work -on (existing) @context{Voice}s to remain working. This is achieved by +on (existing) @context{Voice}s to remain working. This is achieved by giving the new context an alias @context{Voice}, -@verbatim - \alias Voice -@end verbatim +@example +\alias Voice +@end example The context will print notes, and instructive texts -@verbatim - \consists Note_heads_engraver - \consists Text_engraver -@end verbatim +@example +\consists Note_heads_engraver +\consists Text_engraver +@end example but only on the center line, -@verbatim - \consists Pitch_squash_engraver - squashedPosition = #0 -@end verbatim +@example +\consists Pitch_squash_engraver +squashedPosition = #0 +@end example The @internalsref{Pitch_squash_engraver} modifies note heads (created by @internalsref{Note_heads_engraver}) and sets their vertical -position to the value of @code{squashedPosition}, in this case -@code{0}, the center line. +position to the value of @code{squashedPosition}, in this case@tie{}@code{0}, +the center line. -The notes look like a slash, without a stem, +The notes look like a slash, without a stem, -@verbatim - \override NoteHead #'style = #'slash - \override Stem #'transparent = ##t -@end verbatim +@example +\override NoteHead #'style = #'slash +\override Stem #'transparent = ##t +@end example All these plug-ins have to cooperate, and this is achieved with a @@ -710,48 +714,48 @@ special plug-in, which must be marked with the keyword @code{\type}. This should always be @internalsref{Engraver_group_engraver}, @example - \type "Engraver_group_engraver" +\type "Engraver_group_engraver" @end example Putting together, we get -@verbatim - \context { - \name ImproVoice - \type "Engraver_group_engraver" - \consists "Note_heads_engraver" - \consists "Text_engraver" - \consists Pitch_squash_engraver - squashedPosition = #0 - \override NoteHead #'style = #'slash - \override Stem #'transparent = ##t - \alias Voice - } -@end verbatim +@example +\context @{ + \name ImproVoice + \type "Engraver_group_engraver" + \consists "Note_heads_engraver" + \consists "Text_engraver" + \consists Pitch_squash_engraver + squashedPosition = #0 + \override NoteHead #'style = #'slash + \override Stem #'transparent = ##t + \alias Voice +@} +@end example -Contexts form hierarchies. We want to hang the @context{ImproVoice} -under @context{Staff}, just like normal @code{Voice}s. Therefore, we +Contexts form hierarchies. We want to hang the @context{ImproVoice} +under @context{Staff}, just like normal @code{Voice}s. Therefore, we modify the @code{Staff} definition with the @code{\accepts} command,@footnote{The opposite of @code{\accepts} is @code{\denies}, -which is sometimes when reusing existing context definitions. } +which is sometimes needed when reusing existing context definitions.} -@verbatim - \context { - \Staff - \accepts ImproVoice - } -@end verbatim +@example +\context @{ + \Staff + \accepts ImproVoice +@} +@end example Putting both into a @code{\layout} block, like @example - \layout @{ - \context @{ - \name ImproVoice - @dots{} - @} +\layout @{ + \context @{ + \name ImproVoice + @dots{} + @} \context @{ \Staff \accepts "ImproVoice" @@ -761,17 +765,17 @@ Putting both into a @code{\layout} block, like Then the output at the start of this subsection can be entered as -@verbatim -\relative c'' { - a4 d8 bes8 - \new ImproVoice { - c4^"ad lib" c - c4 c^"undress" - c c_"while playing :)" - } - a1 -} -@end verbatim +@example +\relative c'' @{ + a4 d8 bes8 + \new ImproVoice @{ + c4^"ad lib" c + c4 c^"undress" + c c_"while playing :)" + @} + a1 +@} +@end example @@ -780,10 +784,10 @@ Then the output at the start of this subsection can be entered as @section The \override command In the previous section, we have already touched on a command that -changes layout details, the @code{\override} command. In this section, +changes layout details, the @code{\override} command. In this section, we will look at in more detail how to use the command in practice. First, we will give a a few versatile commands, which are sufficient -for many situations. The next section will discuss general use of +for many situations. The next section will discuss general use of @code{\override}. @@ -802,7 +806,7 @@ for many situations. The next section will discuss general use of @subsection Common tweaks Some overrides are so common that predefined commands are provided as -a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These +a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These commands are described in @ifhtml the @@ -812,7 +816,7 @@ 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 +object. However, many layout objects share properties, which can be used to apply generic tweaks. We mention a few of these: @itemize @bullet @@ -831,7 +835,7 @@ the left, and 1.8 staff space downwards: @cindex setting object properties -@lilypond[fragment,relative=1,verbatim] +@lilypond[quote,fragment,relative=1,verbatim] \stemUp f-5 \once \override Fingering @@ -842,7 +846,7 @@ f-5 @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 +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 @@ -850,42 +854,42 @@ collisions, and slurs, and ties and beams can be attached to it. @cindex hiding 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, - -@lilypond[fragment,relative=2] - << { - b8~ b8\noBeam - } \\ { - b[ g8] - } >> +using ties. Normally, ties only connect two notes in the same +voice. By introducing a tie in a different voice, + +@lilypond[quote,fragment,relative=2] +<< { + b8~ b8\noBeam +} \\ { + b[ g8] +} >> @end lilypond @noindent and blanking the first up-stem in that voice, the tie appears to cross voices: -@lilypond[fragment,relative=2,verbatim] - << { - \once \override Stem #'transparent = ##t - b8~ b8\noBeam - } \\ { - b[ g8] - } >> +@lilypond[quote,fragment,relative=2,verbatim] +<< { + \once \override Stem #'transparent = ##t + b8~ b8\noBeam +} \\ { + 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 +symbols that are printed above or below notes. We only give an example; a more elaborate explanation is in @ref{Constructing a tweak}: -@lilypond[fragment,relative=1,verbatim] - c2\fermata - \override Script #'padding = #3 - b2\fermata +@lilypond[quote,fragment,relative=1,verbatim] +c2\fermata +\override Script #'padding = #3 +b2\fermata @end lilypond @end itemize @@ -901,7 +905,7 @@ The general procedure of changing output, that is, entering a command like @example - \override Voice.Stem #'thickness = #3.0 +\override Voice.Stem #'thickness = #3.0 @end example @noindent @@ -932,7 +936,7 @@ and the program reference. Suppose we want to move the fingering indication in the fragment below: -@lilypond[fragment,relative=2,verbatim] +@lilypond[quote,fragment,relative=2,verbatim] c-2 \stemUp f @@ -953,12 +957,12 @@ Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}. This fragment points to two parts of the program reference: a page on @code{FingerEvent} and on @code{Fingering}. -The page on @code{FingerEvent} describes the properties of the music -expression for the input @code{-2}. The page contains many links +The page on @code{FingerEvent} describes the properties of the music +expression for the input @code{-2}. The page contains many links forward. For example, it says @quotation - Accepted by: @internalsref{Fingering_engraver}, +Accepted by: @internalsref{Fingering_engraver}, @end quotation @noindent @@ -966,7 +970,7 @@ That link brings us to the documentation for the Engraver, the plug-in, which says @quotation - This engraver creates the following layout objects: @internalsref{Fingering}. +This engraver creates the following layout objects: @internalsref{Fingering}. @end quotation In other words, once the @code{FingerEvent}s are interpreted, the @@ -975,20 +979,21 @@ The @code{Fingering_engraver} is also listed to create @internalsref{Fingering} objects, - Lo and behold, that is also the +Lo and behold, that is also the second bit of information listed under @b{See also} in the Notation -manual. By clicking around in the program reference, we can follow the +manual. By clicking around in the program reference, we can follow the flow of information within the program, either forward (like we did here), or backwards, following links like this: @itemize @bullet @item @internalsref{Fingering}: - @internalsref{Fingering} objects are created by: - @b{@internalsref{Fingering_engraver}} +@internalsref{Fingering} objects are created by: +@b{@internalsref{Fingering_engraver}} @item @internalsref{Fingering_engraver}: Music types accepted: @b{@internalsref{fingering-event}} + @item @internalsref{fingering-event}: Music event type @code{fingering-event} is in Music expressions named @b{@internalsref{FingerEvent}} @@ -1005,7 +1010,7 @@ contains a chapter on @ifnothtml @code{Music definitions} @end ifnothtml -on @internalsref{Translation}, and the @internalsref{Backend}. Every +on @internalsref{Translation}, and the @internalsref{Backend}. Every chapter lists all the definitions used, and all properties that may be tuned. @@ -1017,8 +1022,8 @@ tuned. @cindex layout interface The HTML page which we found in the previous section, describes the -layout object called @internalsref{Fingering}. Such an object is a -symbol within the score. It has properties, which store numbers (like +layout object called @internalsref{Fingering}. Such an object is a +symbol within the score. It has properties, which store numbers (like thicknesses and directions), but also pointers to related objects. A layout object is also called @emph{grob}, @cindex grob @@ -1026,34 +1031,42 @@ which is short for Graphical Object. The page for @code{Fingering} lists the definitions for the -@code{Fingering} object. For example, the page says +@code{Fingering} object. For example, the page says @quotation - @code{padding} (dimension, in staff space): +@code{padding} (dimension, in staff space): - @code{0.6} +@code{0.6} @end quotation +@noindent which means that the number will be kept at a distance of at least 0.6 of the note head. Each layout object may have several functions as a notational or -typographical element. For example, the Fingering object +typographical element. For example, the Fingering object has the following aspects @itemize @bullet -@item Its size is independent of the horizontal spacing, unlike slurs or beams. +@item +Its size is independent of the horizontal spacing, unlike slurs or beams. + +@item +It is a piece of text. Granted, it is usually a very short text. + +@item +That piece of text is typeset with a font, unlike slurs or beams. -@item It is a piece of text. Granted, it is usually a very short text. +@item +Horizontally, the center of the symbol should be aligned to the +center of the notehead. -@item That piece of text is typeset with a font, unlike slurs or beams. -@item Horizontally, the center of the symbol should be aligned to the -center of the notehead -@item Vertically, the symbol is placed next to the note and the staff. +@item +Vertically, the symbol is placed next to the note and the staff. -@item The - vertical position is also coordinated with other super and subscript +@item +The vertical position is also coordinated with other super and subscript symbols. @end itemize @@ -1075,26 +1088,25 @@ them are not user-serviceable (``Internal properties''), but others are. We have been talking of `the' @code{Fingering} object, but actually it -does not amount to much. The initialization file +does not amount to much. The initialization file @file{scm/@/define@/-grobs@/.scm} shows the soul of the `object', -@verbatim - (Fingering - . ( - (print-function . ,Text_interface::print) - (padding . 0.6) - (staff-padding . 0.6) - (self-alignment-X . 0) - (self-alignment-Y . 0) - (script-priority . 100) - (font-encoding . number) - (font-size . -5) - (meta . ((interfaces . (finger-interface font-interface - text-script-interface text-interface - side-position-interface self-alignment-interface - item-interface)))) - )) -@end verbatim +@example +(Fingering + . ((print-function . ,Text_interface::print) + (padding . 0.6) + (staff-padding . 0.6) + (self-alignment-X . 0) + (self-alignment-Y . 0) + (script-priority . 100) + (font-encoding . number) + (font-size . -5) + (meta . ((interfaces . (finger-interface font-interface + text-script-interface text-interface + side-position-interface + self-alignment-interface + item-interface)))))) +@end example @noindent As you can see, the @code{Fingering} object is nothing more than a @@ -1107,35 +1119,35 @@ is directly generated from this definition. Recall that we wanted to change the position of the @b{2} in -@lilypond[fragment,relative=2,verbatim] +@lilypond[quote,fragment,relative=2,verbatim] c-2 \stemUp f @end lilypond Since the @b{2} is vertically positioned next to its note, we have to -meddle with the interface associated with this positioning. This is -done using @code{side-position-interface}. The page for this interface +meddle with the interface associated with this positioning. This is +done using @code{side-position-interface}. The page for this interface says @quotation @code{side-position-interface} - Position a victim object (this one) next to other objects (the - support). The property @code{direction} signifies where to put the - victim object relative to the support (left or right, up or down?) +Position a victim object (this one) next to other objects (the +support). 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) +(dimension, in staff space) - Add this much extra space between objects that are next to each - other. +Add this much extra space between objects that are next to each other. @end table @end quotation @@ -1147,9 +1159,9 @@ between the note and the fingering: @end example Inserting this command before the Fingering object is created, -i.e. before @code{c2}, yields the following result: +i.e., before @code{c2}, yields the following result: -@lilypond[relative=2,fragment,verbatim] +@lilypond[quote,relative=2,fragment,verbatim] \once \override Voice.Fingering #'padding = #3 c-2 \stemUp @@ -1162,15 +1174,15 @@ fact can also be deduced from the program reference, for the page for the @internalsref{Fingering_engraver} plug-in says @quotation - Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}} +Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}} @end quotation @node Difficult tweaks @subsection Difficult tweaks -There are two classes of difficult adjustments. First, when there are +There are two classes of difficult adjustments. First, when there are several of the same objects at one point, and you want to adjust only -one. For example, if you want to change only one note head in a chord. +one. For example, if you want to change only one note head in a chord. In this case, the @code{\applyoutput} function must be used. The next example defines a Scheme function @code{set-position-font-size} @@ -1178,13 +1190,12 @@ that sets the @code{font-size} property, but only on objects that have @internalsref{note-head-interface} and are at the right Y-position. -@lilypond[verbatim] +@lilypond[quote,verbatim] #(define ((set-position-font-size pos size) grob origin current) (let* ((interfaces (ly:grob-property grob 'interfaces)) (position (ly:grob-property grob 'staff-position))) - (if (and - + (if (and ; is this a note head? (memq 'note-head-interface interfaces) @@ -1195,33 +1206,33 @@ right Y-position. (set! (ly:grob-property grob 'font-size) size)))) \relative { - c - \applyoutput #(set-position-font-size -2 4) - + c + \applyoutput #(set-position-font-size -2 4) + } @end lilypond @noindent -A similar technique can be used for accidentals. In that case, the +A similar technique can be used for accidentals. In that case, the function should check for @code{accidental-interface}. Another difficult adjustment is the appearance of spanner objects, -such as slur and tie. Initially, only one of these objects is created, -and they can be adjust with the normal mechanism. However, in some -cases the spanners cross line breaks. If this happens, these objects +such as slur and tie. Initially, only one of these objects is created, +and they can be adjust with the normal mechanism. However, in some +cases the spanners cross line breaks. If this happens, these objects are cloned. A separate object is created for every system that it is -in. These are clones of the original object and inherit all +in. These are clones of the original object and inherit all properties, including @code{\override}s. In other words, an @code{\override} always affects all pieces of a -broken spanner. To change only one part of a spanner at a line break, -it is necessary to hook into the formatting process. The +broken spanner. To change only one part of a spanner at a line break, +it is necessary to hook into the formatting process. The @code{after-line-breaking-callback} property contains the Scheme procedure that is called after line breaks have been determined, and layout objects have been split over different systems. In the following example, we define a procedure -@code{my-callback}. This procedure +@code{my-callback}. This procedure @itemize @bullet @item @@ -1238,33 +1249,31 @@ This procedure is installed into @internalsref{Tie}, so the last part of broken tie is translated up. -@lilypond[verbatim,raggedright] +@lilypond[quote,verbatim,raggedright] #(define (my-callback grob) (let* ( + ; have we been split? + (orig (ly:grob-original grob)) - ; have we been split? - (orig (ly:grob-original grob)) + ; if yes, get the split pieces (our siblings) + (siblings (if (ly:grob? orig) + (ly:spanner-broken-into orig) '() ))) - ; if yes, get the split pieces (our siblings) - (siblings (if (ly:grob? orig) (ly:spanner-broken-into orig) '() ))) - - - (if (and (>= (length siblings) 2) + (if (and (>= (length siblings) 2) (eq? (car (last-pair siblings)) grob)) - (ly:grob-set-property! grob 'extra-offset '(-2 . 5)) - ))) + (ly:grob-set-property! grob 'extra-offset '(-2 . 5))))) \relative c'' { - \override Tie #'after-line-breaking-callback = - #my-callback - c1 ~ \break c2 ~ c + \override Tie #'after-line-breaking-callback = + #my-callback + c1 ~ \break c2 ~ c } @end lilypond - +@noindent When applying this trick, the new @code{after-line-breaking-callback} should also call the old @code{after-line-breaking-callback}, if there -is one. For example, if using this with @code{Slur}, +is one. For example, if using this with @code{Slur}, @code{Slur::after_line_breaking} should also be called. @node Fonts @@ -1284,14 +1293,15 @@ is one. For example, if using this with @code{Slur}, The easiest method of setting the font size of any context, is by setting the @code{fontSize} property. -@lilypond[fragment,relative=1,verbatim] - c8 - \set fontSize = #-4 - c f - \set fontSize = #3 - g +@lilypond[quote,fragment,relative=1,verbatim] +c8 +\set fontSize = #-4 +c f +\set fontSize = #3 +g @end lilypond +@noindent It does not change the size of variable symbols, such as beams or slurs. @@ -1299,28 +1309,28 @@ Internally, the @code{fontSize} context property will cause @code{font-size} property to be set in all layout objects. The value of @code{font-size} is a number indicating the size relative to the standard size for the current staff height. 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 +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[fragment,relative=1,verbatim] - c8 - \override NoteHead #'font-size = #-4 - c f - \override NoteHead #'font-size = #3 - g +@lilypond[quote,fragment,relative=1,verbatim] +c8 +\override NoteHead #'font-size = #-4 +c f +\override NoteHead #'font-size = #3 +g @end lilypond -LilyPond has fonts in different design sizes. The music fonts for +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 standard font size (for -@code{font-size} equals 0), depends on the standard staff height. For +closest to the desired size. The standard font size (for +@code{font-size} equals 0), depends on the standard staff height. For a 20 pt staff, a 10pt font is selected. The @code{font-size} mechanism does not work for fonts selected -through @code{font-name}. These may be scaled with -@code{font-magnification}. The @code{font-size} property can only be +through @code{font-name}. These may be scaled with +@code{font-magnification}. The @code{font-size} property can only be set on layout objects that use fonts; these are the ones supporting @internalsref{font-interface} layout interface. @@ -1358,25 +1368,24 @@ fonts. @itemize @bullet @item @code{font-encoding} -is a symbol that sets layout of the glyphs. Choices include @code{ec} +is a symbol that sets layout of the glyphs. Choices include @code{ec} for @TeX{} EC font encoding, @code{fetaBraces} (for piano staff braces), @code{fetaMusic} (the standard music font, including ancient glyphs), @code{fetaDynamic} (for dynamic signs) and @code{fetaNumber} for the number font. - @item @code{font-family} - is a symbol indicating the general class of the typeface. Supported are +is a symbol indicating the general class of the typeface. Supported are @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}. @item @code{font-shape} - is a symbol indicating the shape of the font, there are typically -several font shapes available for each font family. Choices are +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 @code{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} +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 itemize @@ -1387,12 +1396,12 @@ sheet. The font used for printing a object can be selected by setting @code{font-name}, e.g. @example - \override Staff.TimeSignature - #'font-name = #"cmr17" +\override Staff.TimeSignature + #'font-name = #"cmr17" @end example @noindent -Any font can be used, as long as it is available to @TeX{}. Possible +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 @@ -1420,14 +1429,14 @@ fonts may be added to LilyPond. @cindex typeset text The internal mechanism to typeset texts is accessed with the keyword -@code{\markup}. Within markup mode, you can enter texts similar to -lyrics. They are simply entered, while commands use the backslash @code{\}. +@code{\markup}. Within markup mode, you can enter texts similar to +lyrics. They are simply entered, while commands use the backslash @code{\}. @cindex markup -@lilypond[verbatim,fragment,relative=1] - c1^\markup { hello } - c1_\markup { hi there } - c1^\markup { hi \bold there, is \italic anyone home? } +@lilypond[quote,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 @@ -1437,39 +1446,39 @@ command @code{\bold} and @code{\italic} apply to the first following word only; enclose a set of texts with braces to apply a command to more words: @example - \markup @{ \bold @{ hi there @} @} +\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 +@example +\markup @{ is \italic @{ anyone @} home @} +@end example @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 +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 +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 > } +@lilypond[quote,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 } } - { a^\allegro b c d } -@end verbatim +@example +allegro = \markup @{ \bold \large @{ Allegro @} @} + @{ a^\allegro b c d @} +@end example Some objects have alignment procedures of their own, which cancel out @@ -1480,10 +1489,10 @@ effect. Similarly, for moving whole texts over notes with @code{\raise}, use the following trick: -@lilypond[verbatim] +@lilypond[quote,verbatim] { c'^\markup { \raise #0.5 not-raised } - c'^\markup { "" \raise #0.5 raised } + c'^\markup { "" \raise #0.5 raised } } @end lilypond @@ -1497,7 +1506,7 @@ objects can be moved with layout properties such as @code{padding} and @seealso -Init files: @file{scm/@/new@/-markup@/.scm}. +Init files: @file{scm/@/new@/-markup@/.scm}. @refbugs @@ -1522,45 +1531,46 @@ Texts can be entered in different encodings. The encoding of the file can be set with @code{\encoding}. @example - \encoding "latin1" +\encoding "latin1" @end example -This command may be placed anywhere in the input file. The current +This command may be placed anywhere in the input file. The current encoding is passed as an extra argument to @code{\markup} commands, and is passed similarly to lyric syllables. If no @code{\encoding} has been specified, then the encoding is taken from the @code{\layout} block (or @code{\paper}, if @code{\layout} -does not specify encoding). The variable @code{inputencoding} may be -set to a string or symbol specifying the encoding, e.g. +does not specify encoding). The variable @code{inputencoding} may be +set to a string or symbol specifying the encoding, e.g. -@verbatim - \layout { - inputencoding = "latin1" - } -@end verbatim +@example +\layout @{ + inputencoding = "latin1" +@} +@end example -Normal strings, are unaffected by @code{\encoding}. This means that -the following will usually not produce ba@ss{}tuba in the title. +Normal strings, are unaffected by @code{\encoding}. This means that +the following will usually not produce `Baßtuba' in the title. -@verbatim - \header { - title = "Grazing cow" - instrument = "Baßtuba" - } -@end verbatim +@example +\header @{ + title = "Grazing cow" + instrument = "Baßtuba" +@} +@end example +@noindent Rather, you should say -@verbatim - instrument = \markup { Baßtuba } -@end verbatim +@example +instrument = \markup @{ Baßtuba @} +@end example @noindent or set @code{inputencoding} in the @code{\paper} block. -There is a special encoding, called @code{TeX}. This encoding does not -reencode text for the font used. Rather, it tries to guess the width -of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX} +There is a special encoding, called @code{TeX}. This encoding does not +reencode text for the font used. Rather, it tries to guess the width +of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX} are passed to the output back-end verbatim. @cindex encoding @@ -1573,12 +1583,12 @@ are passed to the output back-end verbatim. @subsection Nested scores It is possible to nest music inside markups, by adding a @code{\score} -block to markup expression. Such a score must contain a @code{\layout} +block to markup expression. Such a score must contain a @code{\layout} block. -@lilypond[verbatim,raggedright] +@lilypond[quote,verbatim,raggedright] \relative { - c4 d^\markup { + c4 d^\markup { \score { \relative { c4 d e f } \layout { } @@ -1590,7 +1600,7 @@ block. -@node Overview of text markup commands +@node Overview of text markup commands @subsection Overview of text markup commands The following commands can all be used inside @code{\markup @{ @}}. @@ -1602,13 +1612,13 @@ The following commands can all be used inside @code{\markup @{ @}}. @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 +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 are chosen, and thus ultimately how many pages a piece of music takes. Globally spoken, this procedure happens in three steps: first, -flexible distances (``springs'') are chosen, based on durations. All +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. @@ -1641,12 +1651,13 @@ titles. @cindex staff size, setting @cindex @code{layout} file -The Feta font provides musical symbols at eight different -sizes. Each font is tuned for a different staff size: at a smaller size +The Feta font provides musical symbols at eight different +sizes. Each font is tuned for a different staff size: at a smaller size the font becomes heavier, to match the relatively heavier staff lines. The recommended font sizes are listed in the following table: -@multitable @columnfractions .25 .25 .25 .25 +@quotation +@multitable @columnfractions .15 .2 .22 .2 @item @b{font name} @tab @b{staff height (pt)} @@ -1692,20 +1703,22 @@ The recommended font sizes are listed in the following table: @tab 25.2 @tab 8.9 @tab -@c modern rental material ? +@c modern rental material? @end multitable +@end quotation -These fonts are available in any sizes. The context property +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 -staves. The size of individual staves are relative to the global size, -which can be set in the following manner: +staves. The size of individual staves are relative to the global size, +which can be set in the following manner: @example - #(set-global-staff-size 14) +#(set-global-staff-size 14) @end example +@noindent This sets the global default size to 14pt staff height, and scales all fonts accordingly. @@ -1720,7 +1733,7 @@ This manual: @ref{Selecting font sizes}. @subsection Vertical spacing of piano staves The distance between staves of a @internalsref{PianoStaff} cannot be -computed during formatting. Rather, to make cross-staff beaming work +computed during formatting. Rather, to make cross-staff beaming work correctly, that distance has to be fixed beforehand. The distance of staves in a @code{PianoStaff} is set with the @@ -1729,18 +1742,20 @@ The distance of staves in a @code{PianoStaff} is set with the @internalsref{PianoStaff}. It can be adjusted as follows -@verbatim -\new PianoStaff \with { - \override VerticalAlignment #'forced-distance = #7 -} { +@example +\new PianoStaff \with @{ + \override VerticalAlignment #'forced-distance = #7 +@} @{ ... -} -@end verbatim +@} +@end example + +@noindent This would bring the staves together at a distance of 7 staff spaces, measured from the center line of each staff. The difference is demonstrated in the following example, -@lilypond[verbatim] +@lilypond[quote,verbatim] \relative << \new PianoStaff \with { \override VerticalAlignment #'forced-distance = #7 @@ -1771,18 +1786,21 @@ The difference is demonstrated in the following example, @cindex staves per page @cindex space between staves -The height of each system is determined automatically. To prevent +The height of each system is determined automatically. To prevent 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 +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 default, then you could set + @example - \set Staff.minimumVerticalExtent = #'(-4 . 4) +\set Staff.minimumVerticalExtent = #'(-4 . 4) @end example + +@noindent 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 @@ -1800,7 +1818,7 @@ Internals: Vertical alignment of staves is handled by the @code{minimumVerticalExtent} is syntactic sugar for setting @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the -current context. It can only be changed score wide. +current context. It can only be changed score wide. @@ -1808,7 +1826,7 @@ current context. It can only be changed score wide. @subsection Horizontal Spacing The spacing engine translates differences in durations into -stretchable distances (``springs'') of differring lengths. Longer +stretchable distances (``springs'') of differring 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). @@ -1819,7 +1837,8 @@ duration adds a fixed amount (this amount is controlled by 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] + +@lilypond[quote,fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4 @end lilypond @@ -1828,28 +1847,28 @@ Normally, @code{spacing-increment} is set to 1.2 staff space, which is approximately the width of a note head, and @code{shortest-duration-space} is set to 2.0, meaning that the shortest note gets 2.4 staff space (2.0 times the -@code{spacing-increment}) of horizontal space. This space is counted +@code{spacing-increment}) of horizontal space. This space is 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 +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 rather the one which occurs most frequently. The most common shortest duration is determined as follows: in every -measure, the shortest duration is determined. The most common short +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 +1/8th note. The shortest duration is printed when you run @code{lilypond} with the @code{--verbose} option. -These durations may also be customized. If you set the +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 +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} @@ -1862,29 +1881,29 @@ 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 +@lilypond[quote,fragment,verbatim,relative=2] +c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4 @end lilypond In the introduction (see @ref{Engraving}), it was explained that stem -directions influence spacing. This is controlled with the +directions influence spacing. This is controlled with the @code{stem-spacing-correction} property in the -@internalsref{NoteSpacing}, object. These are generated for every -@internalsref{Voice} context. The @code{StaffSpacing} object +@internalsref{NoteSpacing}, object. These 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 +for controlling the stem/bar line spacing. The following example shows these corrections, once with default settings, and once with exaggerated corrections: -@lilypond[raggedright] +@lilypond[quote,raggedright] { - 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| + 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| } @end lilypond @@ -1897,7 +1916,7 @@ Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, @refbugs -Spacing is determined on a score wide basis. If you have a score that +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. @@ -1951,31 +1970,31 @@ paragraph, the last line simply takes its natural length. @cindex line breaks @cindex breaking lines -Line breaks are normally computed automatically. They are chosen such +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 +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 +""}. 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 +For line breaks at regular intervals use @code{\break} separated by skips and repeated with @code{\repeat}: @example -<< \repeat unfold 7 @{ +<< \repeat unfold 7 @{ s1 \noBreak s1 \noBreak - s1 \noBreak s1 \break @} + s1 \noBreak s1 \break @} @emph{the real music} >> -@end example +@end example @noindent This makes the following 28 measures (assuming 4/4 time) be broken every @@ -2001,14 +2020,14 @@ Internals: @internalsref{BreakEvent}. @cindex composer @cindex Engraved by LilyPond -A document may contains multiple pieces of music. Examples of these +A document may contains multiple pieces of music. Examples of these are an etude book, or an orchestral part with multiple movements. Each movement is entered with a @code{\score} block, @example - \score @{ - @var{..music..} - @} +\score @{ + @var{..music..} +@} @end example The movements are combined together to @@ -2017,10 +2036,10 @@ The movements are combined together to @example \book @{ \score @{ - @var{..} + @var{..} @} \score @{ - @var{..} + @var{..} @} @} @end example @@ -2062,32 +2081,42 @@ The contents of the titles are taken from the @code{\header} blocks. The header block for a book supports the following @table @code @item title - The title of the music. Centered on top of the first page. +The title of the music. Centered on top of the first page. + @item subtitle - Subtitle, centered below the title. +Subtitle, centered below the title. + @item subsubtitle - Subsubtitle, centered below the subtitle. +Subsubtitle, centered below the subtitle. + @item poet - Name of the poet, left flushed below the subtitle. +Name of the poet, left flushed below the subtitle. + @item composer - Name of the composer, right flushed below the subtitle. +Name of the composer, right flushed below the subtitle. + @item meter - Meter string, left flushed below the poet. +Meter string, left flushed below the poet. + @item opus - Name of the opus, right flushed below the composer. +Name of the opus, right flushed below the composer. + @item arranger - Name of the arranger, right flushed below the opus. +Name of the arranger, right flushed below the opus. + @item instrument - Name of the instrument, centered below the arranger. +Name of the instrument, centered below the arranger. + @item dedication - To whom the piece is dedicated. +To whom the piece is dedicated. + @item piece - Name of the piece, left flushed below the instrument. +Name of the piece, left flushed below the instrument. @end table This is a demonstration of the fields available, -@lilypond[verbatim,linewidth=11.0\cm] +@lilypond[quote,verbatim,linewidth=11.0\cm] \paper { linewidth = 11.0\cm vsize = 10.0\cm @@ -2127,17 +2156,17 @@ This is a demonstration of the fields available, Different fonts may be selected for each element, by using a @code{\markup}, e.g. -@verbatim - \header { - title = \markup { \italic { The italic title } } - } -@end verbatim +@example +\header @{ + title = \markup @{ \italic @{ The italic title @} @} +@} +@end example A more advanced option is to change the Scheme functions @code{make-book-title} and @code{make-score-title} functions, defined -in the @code{\paper} of the @code{\book} block. These functions +in the @code{\paper} of the @code{\book} block. These functions create a block of titling, given the information in the -@code{\header}. The init file @file{ly/@/titling@/.scm} shows how the +@code{\header}. The init file @file{ly/@/titling@/.scm} shows how the default format is created, and it may be used as a template for different styles. @@ -2155,9 +2184,9 @@ different styles. @subsection Page breaking The default page breaking may be overriden by inserting -@code{\pageBreak} or @code{\noPageBreak} commands. These commands are -analogous to @code{\break} and @code{\noBreak}. They should be -inserted with a bar line. These commands force and forbid a page-break +@code{\pageBreak} or @code{\noPageBreak} commands. These commands are +analogous to @code{\break} and @code{\noBreak}. They should be +inserted with a bar line. These commands force and forbid a page-break from happening. Of course, the @code{\pageBreak} command also forces a line break. @@ -2168,7 +2197,7 @@ Page breaks are computed by the @code{page-breaking} function in the @cindex @code{\pageBreak} @code{\pageBreak} -@cindex @code{\noPageBreak} +@cindex @code{\noPageBreak} @code{\noPageBreak} @node Paper size @@ -2180,25 +2209,16 @@ Page breaks are computed by the @code{page-breaking} function in the To change the paper size, there are two equal commands, @example - #(set-default-paper-size "a4") - \paper@{ - #(set-paper-size "a4") - @} +#(set-default-paper-size "a4") +\paper @{ + #(set-paper-size "a4") +@} @end example The first command sets the size of all pages. The second command sets the size of the pages that the @code{\paper} block applies to -- if the @code{\paper} block is at the top of the file, then it will apply to all pages. If the @code{\paper} block is inside a @code{\score}, then the paper size will only apply to that score. -The following paper sizes are supported. - -@table @code -@item a6 -@item a5 -@item a4 -@item a3 -@item legal -@item letter -@item tabloid -@end table +The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4}, +@code{a3}, @code{legal}, @code{letter}, @code{tabloid}. @cindex orientation @cindex landscape @@ -2223,46 +2243,57 @@ LilyPond will do page layout, setting margins and adding headers and footers to each page. The default layout responds to the following settings in the -@code{\paper} block +@code{\paper} block. @cindex \paper +@quotation @table @code @item firstpagenumber - The value of the page number of the first page. Default is 1. +The value of the page number of the first page. Default is@tie{}1. + @item printfirstpagenumber - If set to true will print the page number in the first page. Default is - false. +If set to true will print the page number in the first page. Default is +false. + @item hsize - The width of the page +The width of the page. + @item vsize - The height of the page +The height of the page. + @item topmargin - Margin between header and top of the page +Margin between header and top of the page. + @item bottommargin - Margin between footer and bottom of the page +Margin between footer and bottom of the page. + @item leftmargin - Margin between the left side of the page and the beginning of the music +Margin between the left side of the page and the beginning of the music. + @item linewidth - The length of the systems +The length of the systems. + @item headsep - Distance between top-most music system and the page header +Distance between top-most music system and the page header. + @item footsep - Distance between bottom-most music system and the page footer +Distance between bottom-most music system and the page footer. + @item raggedbottom - If set to true, systems will not be spread across the page. +If set to true, systems will not be spread across the page. - This should be set false for pieces that have only two or three +This should be set false for pieces that have only two or three systems per page, for example orchestral scores. @item raggedlastbottom - If set to false, systems will be spread to fill the last page. +If set to false, systems will be spread to fill the last page. - Pieces that amply fill two pages or more should have this set to +Pieces that amply fill two pages or more should have this set to true. @item betweensystemspace - This dimensions determines the distance between systems. It is the +This dimensions determines the distance between systems. It is the ideal distance between the center of the bottom staff of one system, and the center of the top staff of the next system. @@ -2278,34 +2309,39 @@ Increasing this will put systems whose bounding boxes almost touch farther apart. @item aftertitlespace -Amount of space between title and the first system +Amount of space between title and the first system. + @item beforetitlespace -Amount of space between last system of the previous piece and the -title of the next +Amount of space between last system of the previous piece and the +title of the next. + @item betweentitlespace -Amount of space between consecutive titles (eg. the title of the +Amount of space between consecutive titles (e.g., the title of the book and the title of piece). @end table +@end quotation + +Example: @example - \paper@{ - hsize = 2\cm - topmargin = 3\cm - bottommargin = 3\cm - raggedlastbottom = ##t - @} +\paper@{ + hsize = 2\cm + topmargin = 3\cm + bottommargin = 3\cm + raggedlastbottom = ##t +@} @end example -You can also define these values in scheme. In that case @code{mm}, +You can also define these values in scheme. In that case @code{mm}, @code{in}, @code{pt} and @code{cm} are variables defined in -@file{paper-defaults.ly} with values in millimeters. That's why the +@file{paper-defaults.ly} with values in millimeters. That's why the value has to be multiplied in the example above. @example - \paper@{ - #(define bottommargin (* 2 cm)) - @} +\paper @{ + #(define bottommargin (* 2 cm)) +@} @end example @cindex copyright @@ -2313,25 +2349,27 @@ value has to be multiplied in the example above. The default footer is empty, except for the first page, where it the @code{copyright} field from @code{\header} is inserted, and the last -page, where @code{tagline} from @code{\header} is added. The default +page, where @code{tagline} from @code{\header} is added. The default tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely printed parts are good PR for us, so please leave the tagline if you can.} The header and footer are created by the functions @code{make-footer} -and @code{make-header}, defined in @code{\paper}. The default +and @code{make-header}, defined in @code{\paper}. The default implementations are in @file{scm/@/page@/-layout@/.scm}. The following settings influence the header and footer layout. +@quotation @table @code @item printpagenumber this boolean controls whether a pagenumber is printed. @end table +@end quotation The page layout itself is done by two functions in the @code{\paper}, @code{page-music-height} and -@code{page-make-stencil}. The former tells the line-breaking algorithm +@code{page-make-stencil}. The former tells the line-breaking algorithm how much space can be spent on a page, the latter creates the actual page given the system to put on it. @@ -2343,7 +2381,7 @@ Examples: @inputfileref{input/@/test,page@/-breaks@/.ly} @refbugs The option rightmargin is defined but doesn't set the right margin -yet. The value for the right margin has to be defined adjusting the +yet. The value for the right margin has to be defined adjusting the values of the leftmargin and linewidth. The default page header puts the page number and the @code{instrument} @@ -2355,16 +2393,16 @@ field from the @code{\header} block on a line. @section File structure The bigger part of this manual is concerned with entering various -forms of music in LilyPond. However, many music expressions are not +forms of music in LilyPond. However, many music expressions are not valid input on their own, for example, a @code{.ly} file containing only a note @example - c'4 +c'4 @end example @noindent -will result in a parsing error. Instead, music should be inside other -expressions, which may be put in a file by themselves. Such +will result in a parsing error. Instead, music should be inside other +expressions, which may be put in a file by themselves. Such expressions are called toplevel expressions. This section enumerates them all. @@ -2372,18 +2410,22 @@ A @code{.ly} file contains any number of toplevel expressions, where a toplevel expressions is one of the following @itemize @bullet -@item An output definition, such as @code{\paper}, @code{\midi} -and @code{\layout}. Such a definition at toplevel changes the default +@item +An output definition, such as @code{\paper}, @code{\midi} +and @code{\layout}. Such a definition at toplevel changes the default settings for the block entered. -@item An @code{\header} block. This sets the global header block. This +@item +A @code{\header} block. This sets the global header block. This is the block containing the definitions for book-wide settings, like composer, title, etc. -@item An @code{\addquote} statement. See @ref{Quoting other voices} +@item +An @code{\addquote} statement. See @ref{Quoting other voices} for more information. -@item A @code{\score} block. This score will be collected with other +@item +A @code{\score} block. This score will be collected with other toplevel scores, and combined as a single @code{\book}. This behavior can be changed by setting the variable @@ -2392,7 +2434,7 @@ defined in the init file @file{scm/@/lily@/.scm}. @item A @code{\book} block logically combines multiple movements -(ie. multiple @code{\score} blocks) into one document. A number of +(i.e., multiple @code{\score} blocks) into one document. A number of @code{\scores} creates a single output file, where all movement are concatenated.. @@ -2400,10 +2442,9 @@ This behavior can be changed by setting the variable @code{toplevel-book-handler} at toplevel. The default handler is defined in the init file @file{scm/@/lily@/.scm}. - @item A compound music expression, such as @example - @{ c'4 d' e'2 @} +@{ c'4 d' e'2 @} @end example This will add the piece in a @code{\score}, and formats it into a @@ -2411,25 +2452,26 @@ single book together with all other toplevel @code{\score}s and music expressions. This behavior can be changed by setting the variable -@code{toplevel-music-handler} at toplevel. The default handler is +@code{toplevel-music-handler} at toplevel. The default handler is defined in the init file @file{scm/@/lily@/.scm}. @end itemize The following example shows three things which may be entered at toplevel -@verbatim - \layout { - % movements are non-justified by default - raggedright = ##t - } - - \header { - title = "Do-re-mi" - } + +@example +\layout @{ + % movements are non-justified by default + raggedright = ##t +@} + +\header @{ + title = "Do-re-mi" +@} - { c'4 d' e2 } -@end verbatim +@{ c'4 d' e2 @} +@end example At any point in a file, any of the following lexical instructions can diff --git a/Documentation/user/cheatsheet.itely b/Documentation/user/cheatsheet.itely index 6f9d9a0908..20ea1bb5bf 100644 --- a/Documentation/user/cheatsheet.itely +++ b/Documentation/user/cheatsheet.itely @@ -6,7 +6,7 @@ @appendix Cheat sheet -@multitable @columnfractions .35 .3 .35 +@multitable @columnfractions .35 .3 .35 @item @b{Syntax} @tab @b{Description} @@ -57,7 +57,7 @@ s4_" " @tab time signature @tab @lilypond[fragment] -\override Staff.Clef #'transparent = ##t +\override Staff.Clef #'transparent = ##t \time 3/4 s4_" " \time 4/4 @@ -128,7 +128,7 @@ c( d e) \set Score.timing = ##f \override Staff.TimeSignature #'break-visibility = #all-invisible \set Staff.autoBeaming = ##f -c\( c( d) e\) +c\( c( d) e\) @end lilypond diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index bd1e01ae0e..03dd377b20 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -6,7 +6,7 @@ Music can be entered also by importing it from other formats. This chapter documents the tools included in the distribution to do so. There are other tools that produce LilyPond input, for example GUI -sequencers and XML converters. Refer to the +sequencers and XML converters. Refer to the @uref{http://@/lilypond@/.org,website} for more details. @@ -22,12 +22,12 @@ sequencers and XML converters. Refer to the @node Invoking convert-ly -@section Invoking convert-ly +@section Invoking @command{convert-ly} The syntax is regularly changed to simplify it or improve it in -different ways. A side effect of this, is that LilyPond often is not -compatible with older files. To remedy this, the program convert-ly -can be used to deal with most of the syntax changes. +different ways. A side effect of this, is that LilyPond often is not +compatible with older files. To remedy this, the program +@command{convert-ly} can be used to deal with most of the syntax changes. It uses @code{\version} statements in the file to detect the old version number. For example, to upgrade all LilyPond files in the @@ -35,12 +35,13 @@ current directory and its subdirectories, enter the following on the command line. @example - convert-ly -e `find . -name '*.ly' -print` +convert-ly -e `find . -name '*.ly' -print` @end example -The program is invoked as follows: +In general, the program is invoked as follows: + @example - convert-ly [@var{option}]@dots{} @var{file}@dots{} +convert-ly [@var{option}]@dots{} @var{file}@dots{} @end example @@ -48,38 +49,46 @@ The following options can be given: @table @code @item -e,--edit - Do an inline edit of the input file. Overrides @code{--output}. +Do an inline edit of the input file. Overrides @code{--output}. + @item -f,--from=@var{from-patchlevel} - Set the level to convert from. If this is not set, convert-ly will - guess this, on the basis of @code{\version} strings in the file. +Set the level to convert from. If this is not set, @command{convert-ly} +will guess this, on the basis of @code{\version} strings in the file. + @item -o,--output=@var{file} - Set the output file to write. +Set the output file to write. + @item -n,--no-version - Normally, convert-ly adds a @code{\version} indicator - to the output. Specifying this option suppresses this. +Normally, @command{convert-ly} adds a @code{\version} indicator +to the output. Specifying this option suppresses this. + @item -s, --show-rules - Show all known conversions and exit. +Show all known conversions and exit. + @item --to=@var{to-patchlevel} - Set the goal version of the conversion. It defaults to the latest - available version. +Set the goal version of the conversion. It defaults to the latest +available version. + @item -h, --help - Print usage help. +Print usage help. @end table -convert-ly always converts up to the last syntax change handled by -it. This means that the @code{\version} number left in the file is -usually lower than the version of convert-ly itself. +@command{convert-ly} always converts up to the last syntax change handled by +it. This means that the @code{\version} number left in the file is +usually lower than the version of @command{convert-ly} itself. @refbugs -Not all language changes are handled. Only one output option can be specified. +Not all language changes are handled. Only one output option can be +specified. @node Invoking midi2ly -@section Invoking midi2ly +@section Invoking @command{midi2ly} @cindex MIDI -Midi2ly translates a Type 1 MIDI file to a LilyPond source file. +@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source +file. MIDI (Music Instrument Digital Interface) is a standard for digital instruments: it specifies cabling, a serial protocol and a file @@ -88,17 +97,17 @@ exporting music from other programs, so this capability may come in useful when importing files from a program that has convertor for a direct format. -Midi2ly will convert tracks into @internalsref{Staff} and +@command{midi2ly} converts tracks into @internalsref{Staff} and channels into @internalsref{Voice} contexts. Relative mode is used for pitches, durations are only written when necessary. It is possible to record a MIDI file using a digital keyboard, and -then convert it to @file{.ly}. However, human players are not +then convert it to @file{.ly}. However, human players are not rhythmically exact enough to make a MIDI to LY conversion trivial. -When invoked with quantizing (@code{-s} and @code{-d} options) midi2ly -tries to compensate for these timing errors, but is not very good at -this. It is therefore not recommended to use midi2ly for -human-generated midi files. +When invoked with quantizing (@code{-s} and @code{-d} options) +@command{midi2ly} tries to compensate for these timing errors, but is not +very good at this. It is therefore not recommended to use @command{midi2ly} +for human-generated midi files. It is invoked from the command-line as follows, @@ -107,46 +116,58 @@ midi2ly [@var{option}]@dots{} @var{midi-file} @end example -The following options are supported by midi2ly. +The following options are supported by @command{midi2ly}. @table @code @item -a, --absolute-pitches - Print absolute pitches. +Print absolute pitches. + @item -d, --duration-quant=@var{DUR} - Quantize note durations on @var{DUR}. +Quantize note durations on @var{DUR}. + @item -e, --explicit-durations - Print explicit durations. +Print explicit durations. + @item -h,--help - Show summary of usage. +Show summary of usage. + @item -k, --key=@var{acc}[:@var{minor}] - Set default key. @var{acc} > 0 sets number of sharps; @var{acc} < 0 - sets number of flats. A minor key is indicated by ":1". +Set default key. @math{@var{acc} > 0} sets number of sharps; +@math{@var{acc} < 0} sets number of flats. A minor key is indicated by +":1". + @item -o, --output=@var{file} - Write output to @var{file}. +Write output to @var{file}. + @item -s, --start-quant=@var{DUR} - Quantize note starts on DUR. +Quantize note starts on DUR. + @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN} - Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}. +Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}. + @item -V, --verbose - Be verbose. +Be verbose. + @item -v, --version - Print version number. +Print version number. + @item -w, --warranty - Show warranty and copyright. +Show warranty and copyright. + @item -x, --text-lyrics - Treat every text as a lyric. +Treat every text as a lyric. @end table @refbugs -Overlapping notes in an arpeggio will not be correctly rendered. The +Overlapping notes in an arpeggio will not be correctly rendered. The first note will be read and the others will be ignored. Set them all to a single duration and add phrase markings or pedal indicators. @node Invoking etf2ly -@section Invoking etf2ly +@section Invoking @command{etf2ly} @cindex ETF @cindex enigma @@ -154,21 +175,23 @@ to a single duration and add phrase markings or pedal indicators. @cindex Coda Technology ETF (Enigma Transport Format) is a format used by Coda Music -Technology's Finale product. etf2ly will convert part of an ETF +Technology's Finale product. @command{etf2ly} will convert part of an ETF file to a ready-to-use LilyPond file. It is invoked from the command-line as follows. + @example - etf2ly [@var{option}]@dots{} @var{etf-file} +etf2ly [@var{option}]@dots{} @var{etf-file} @end example -The following options are supported by etf2ly: +The following options are supported by @command{etf2ly}: + @table @code -@item -h,--help +@item -h,--help this help -@item -o,--output=FILE +@item -o,--output=FILE set output filename to FILE -@item -v,--version +@item -v,--version version information @end table @@ -176,32 +199,34 @@ version information @refbugs The list of articulation scripts is incomplete. Empty measures -confuse etf2ly. Sequences of grace notes are ended improperly. +confuse @command{etf2ly}. Sequences of grace notes are ended improperly. @node Invoking abc2ly -@section Invoking abc2ly +@section Invoking @code{abc2ly} @cindex ABC ABC is a fairly simple ASCII based format. It is described at the ABC site: + @quotation @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}. @end quotation -abc2ly translates from ABC to LilyPond. It is invoked as follows: + +@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows: @example - abc2ly [@var{option}]@dots{} @var{abc-file} +abc2ly [@var{option}]@dots{} @var{abc-file} @end example -The following options are supported by abc2ly: +The following options are supported by @command{abc2ly}: @table @code -@item -h,--help +@item -h,--help this help -@item -o,--output=@var{file} +@item -o,--output=@var{file} set output filename to @var{file}. -@item -v,--version +@item -v,--version print version information. @end table @@ -209,7 +234,7 @@ There is a rudimentary facility for adding LilyPond code to the ABC source file. If you say: @example - %%LY voices \set autoBeaming = ##f +%%LY voices \set autoBeaming = ##f @end example This will cause the text following the keyword ``voices'' to be inserted @@ -218,7 +243,7 @@ into the current voice of the LilyPond output file. Similarly, @example - %%LY slyrics more words +%%LY slyrics more words @end example will cause the text following the ``slyrics'' keyword to be inserted @@ -227,49 +252,50 @@ into the current line of lyrics. @refbugs -The ABC standard is not very ``standard''. For extended features -(e.g. polyphonic music) different conventions exist. +The ABC standard is not very ``standard''. For extended features +(e.g., polyphonic music) different conventions exist. Multiple tunes in one file cannot be converted. -ABC synchronizes words and notes at the beginning of a line; abc2ly does -not. +ABC synchronizes words and notes at the beginning of a line; +@command{abc2ly} does not. -abc2ly ignores the ABC beaming. +@command{abc2ly} ignores the ABC beaming. @node Invoking mup2ly -@section Invoking mup2ly +@section Invoking @command{mup2ly} Mup (Music Publisher) is a shareware music notation program by Arkkra -Enterprises. Mup2ly will convert part of a Mup file to LilyPond -format. It is invoked as follows: +Enterprises. @command{mup2ly} will convert part of a Mup file to LilyPond +format. It is invoked as follows: @cindex Music Publisher @cindex Mup @cindex Arkkra It is invoked from the command-line as follows. + @example - mup2ly [@var{option}]@dots{} @var{mup-file} +mup2ly [@var{option}]@dots{} @var{mup-file} @end example -The following options are supported by mup2ly: +The following options are supported by @command{mup2ly}: @table @code -@item -d,--debug +@item -d,--debug show what constructs are not converted, but skipped. @item -D, --define=@var{name}[=@code{exp}] define macro @var{name} with opt expansion @code{exp} -@item -E,--pre-process +@item -E,--pre-process only run the pre-processor -@item -h,--help +@item -h,--help print help -@item -o,--output=@var{file} +@item -o,--output=@var{file} write output to @var{file} -@item -v,--version +@item -v,--version version information -@item -w,--warranty +@item -w,--warranty print warranty and copyright. @end table @@ -284,17 +310,20 @@ converted. @section Other formats LilyPond itself does not come with support for other formats, but -there are also external tools that generate LilyPond files. +there are some external tools that generate LilyPond files also. These tools include -@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}. @itemize @bullet -@item @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports +@item +@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}. +@item +@uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports @uref{http://@/www@/.musicxml@/.com/,MusicXML} @item @uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit} which imports MusicXML -@item @uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden}, +@item +@uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden}, which imports MIDI @end itemize diff --git a/Documentation/user/examples.itely b/Documentation/user/examples.itely index 97d3aead40..e2568446af 100644 --- a/Documentation/user/examples.itely +++ b/Documentation/user/examples.itely @@ -6,7 +6,7 @@ This section of the manual contains templates with the LilyPond score already set up for you. Just add notes, run LilyPond, and enjoy beautiful printed scores! -@c bad node name for ancient notation to avoid confict +@c bad node name for ancient notation to avoid confict @menu * Suggestions for writing LilyPond files:: * Single staff:: @@ -47,7 +47,7 @@ quite frustrating to try to remember which version of LilyPond you were using a few years ago. @code{convert-ly} requires you to declare which version of LilyPond you used. -@item Include checks: See @ref{Bar check} and @ref{Octave check}. If you +@item Include checks: See @ref{Bar check} and @ref{Octave check}. If you include checks every so often, then if you make a mistake, you can pinpoint it quicker. How often is ``every so often''? It depends on the complexity of the music. For very simple music, perhaps just once or twice. For @@ -133,7 +133,7 @@ Want to prepare a lead sheet with a melody and chords? Look no further! @lilypond[quote,verbatim,raggedright] \version "2.3.22" -melody = \relative c' { +melody = \relative c' { \clef treble \key c \major \time 4/4 @@ -156,7 +156,7 @@ harmonies = \chordmode { >> \layout{ } - \midi { \tempo 4=60} + \midi { \tempo 4=60} } @end lilypond @@ -166,7 +166,7 @@ This template allows you to prepare a song with melody, words, and chords. @lilypond[quote,verbatim,raggedright] \version "2.3.22" -melody = \relative c' { +melody = \relative c' { \clef treble \key c \major \time 4/4 @@ -241,7 +241,7 @@ piano accompaniment underneath. @lilypond[quote,verbatim,raggedright] \version "2.3.22" -melody = \relative c'' { +melody = \relative c'' { \clef treble \key c \major \time 4/4 @@ -361,12 +361,12 @@ lower = \relative c { a2 c } -dynamics = { +dynamics = { s2\fff\> s4 s\!\pp } -pedal = { +pedal = { s2\sustainDown s2\sustainUp } @@ -562,7 +562,7 @@ bassWords = \lyricmode { @end lilypond -@c bad node name to avoid node name confict +@c bad node name to avoid node name confict @node Ancient notation templates @section Ancient notation templates @@ -614,7 +614,7 @@ global = { \skip 1*5 - % last bar contains a brevis (i.e. spans 2 bars); + % last bar contains a brevis (i.e., spans 2 bars); % therefore do not draw this particular bar \cadenzaOn \skip 1*2 @@ -862,7 +862,7 @@ Key = { \key c \major } % ############ Horns ############ % ------ Trumpet ------ -trpt = \transpose c d \relative c'' { +trpt = \transpose c d \relative c'' { \Key c1 c c } @@ -913,7 +913,7 @@ barisax = { } % ------ Trombone ------ -tbone = \relative c { +tbone = \relative c { \Key c1 c c } @@ -932,7 +932,7 @@ trombone = { % ############ Rhythm Section ############# % ------ Guitar ------ -gtr = \relative c'' { +gtr = \relative c'' { \Key c1 \sl b4 b b b \nsl c1 } @@ -1075,7 +1075,7 @@ drumContents = { This template displays all available headers. Some of them are only used in the Mutopia project; they don't affect the printed output at -all. They are used if you want the piece to be listed with different +all. They are used if you want the piece to be listed with different information in the Mutopia database than you wish to have printed on the music. For example, Mutopia lists the composer of the famous D major violin concerto as TchaikovskyPI, whereas perhaps you wish to print @@ -1137,14 +1137,14 @@ quarter notes, and two types of barlines, a short one indicating a rest, and a second one indicating a breath mark. @lilypond[quote,verbatim,raggedright] -barOne = { \once \override Staff.BarLine #'bar-size = #2 +barOne = { \once \override Staff.BarLine #'bar-size = #2 \bar "|" } -barTwo = { \once \override Staff.BarLine #'extra-offset = #'(0 . 2) - \once \override Staff.BarLine #'bar-size = #2 +barTwo = { \once \override Staff.BarLine #'extra-offset = #'(0 . 2) + \once \override Staff.BarLine #'bar-size = #2 \bar "|" } chant = \relative c' { \set Score.timing = ##f - \override Staff.Stem #'transparent = ##t + \override Staff.Stem #'transparent = ##t f4 a2 \barTwo g4 a2 f2 \barOne @@ -1173,15 +1173,15 @@ grip = { \grace { g32[ b g ] } } thrd = { \grace { g32[ d' c'] } } birl = { \grace { g32[ a g] } } gstd = { \grace { g'32[ d' g] } } -fgg = { \grace { f32[ g'32] } } +fgg = { \grace { f32[ g'32] } } dblb = { \grace { g'32[ b d'] } } dblc = { \grace { g'32[ c' d'] } } dble = { \grace { g'32[ e' f'] } } dblf = { \grace { g'32[ f' g'] } } dblg = { \grace { g'32[ f'] } } dbla = { \grace { a'32[ g'] } } -lgg = { \grace { g32 } } -lag = { \grace { a32 } } +lgg = { \grace { g32 } } +lag = { \grace { a32 } } cg = { \grace { c'32 } } eg = { \grace { e'32 } } gg = { \grace { g'32 } } @@ -1211,7 +1211,7 @@ gcdg = { \grace { g'32[ c' d'] } } \dblg g'4 a'8 \gg a'4. | \thrd d'4.( d'4) \eg a8 | \time 9/8 - \dble e'4 \lag e'8 \gg e'16[ d'8. e'8] \gg f'4 g'8 | + \dble e'4 \lag e'8 \gg e'16[ d'8. e'8] \gg f'4 g'8 | \break \time 6/8 @@ -1221,7 +1221,7 @@ gcdg = { \grace { g'32[ c' d'] } } \thrd d'4.( d'4) f'8 | \break - \dblg g'4 e'8( e'8) \dblf f'8.[ e'16] | + \dblg g'4 e'8( e'8) \dblf f'8.[ e'16] | \thrd d'4.( d'4) \cg d'8 | \gg c'4 e'8 \thrd d'4.( | d'4.) \gdcg d'4. diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 108340284c..99cb884078 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -53,7 +53,7 @@ rounded look. Our flat symbol is designed after, among others, this one. It is rounded, and its weight harmonizes with the thickness of our staff lines, which are also much thicker than Henle's lines. -@multitable @columnfractions .05 .3 .3 .3 .05 +@multitable @columnfractions .05 .3 .3 .3 .05 @item @tab @ifnotinfo @iftex @@ -268,27 +268,27 @@ appearance of objects. In the following example, the rule which note head objects use to produce their symbol is changed during the music fragment. -@c FIXME: this example has errors: +@c FIXME: this example has errors: @c programming error: Grob `NoteHead' has no interface for property `text' @c Continuing; crossing fingers @lilypond[quote,raggedright] #(define (mc-squared grob orig current) (let ((interfaces (ly:grob-property grob 'interfaces)) - (pos (ly:grob-property grob 'staff-position))) + (pos (ly:grob-property grob 'staff-position))) (if (and (memq 'note-head-interface interfaces) - (memq pos '(-2 -3 -5))) - (begin - (ly:grob-set-property! grob 'print-function brew-new-markup-stencil) - (ly:grob-set-property! grob 'font-family 'roman) - (ly:grob-set-property! - grob 'text - (make-raise-markup - -0.5 - (case pos - ((-5) (make-simple-markup "m")) - ((-3) (make-simple-markup "c ")) - ((-2) (make-smaller-markup (make-bold-markup "2"))) - (else (make-simple-markup "bla"))))))))) + (memq pos '(-2 -3 -5))) + (begin + (ly:grob-set-property! grob 'print-function brew-new-markup-stencil) + (ly:grob-set-property! grob 'font-family 'roman) + (ly:grob-set-property! + grob 'text + (make-raise-markup + -0.5 + (case pos + ((-5) (make-simple-markup "m")) + ((-3) (make-simple-markup "c ")) + ((-2) (make-smaller-markup (make-bold-markup "2"))) + (else (make-simple-markup "bla"))))))))) \new Voice \relative c' { \stemUp @@ -484,7 +484,7 @@ group called `Voice context,' while the engravers for key, accidental, bar, etc., go into a group called `Staff context.' In the case of polyphony, a single Staff context contains more than one Voice context. Similarly, more Staff contexts can be put into a single Score -context. The Score context is the top level notation context. +context. The Score context is the top level notation context. @seealso @@ -556,7 +556,7 @@ This expression is put in sequence by enclosing it in curly braces @code{@{@tie{}@dots{}@tie{}@}} @example -@{ f4 <> @} +@{ f4 <> @} @end example @lilypond[quote,relative=1,fragment] @@ -575,7 +575,7 @@ again with another simultaneous expression (a half note) using <<, @lilypond[quote,fragment,relative=2] \new Voice { << g2 \\ { f4 <> } >> } @end lilypond - + Such recursive structures can be specified neatly and formally in a context-free grammar. The parsing code is also generated from this grammar. In other words, the syntax of LilyPond is clearly and @@ -608,9 +608,9 @@ By adding chord names and lyrics we obtain a lead sheet. @lilypond[quote,raggedright] << - \chords { c2 c f2 c } + \chords { c2 c f2 c } \new Staff \relative c' { \time 2/4 c4 c g'4 g a4 a g2 } - \new Lyrics \lyricmode { twin4 kle twin kle lit tle star2 } + \new Lyrics \lyricmode { twin4 kle twin kle lit tle star2 } >> @end lilypond diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index a544ad1a68..b89b773f1d 100644 --- a/Documentation/user/lilypond-book.itely +++ b/Documentation/user/lilypond-book.itely @@ -13,30 +13,27 @@ TODO: cleanup @end ignore -@node Integrating text and music + +@node Integrating text and music @chapter Integrating text and music If you want to add pictures of music to a document, you can simply do it the way you would do with other types of pictures. The pictures -are created separately, yielding PostScript pictures or PNG images, +are created separately, yielding PostScript output or PNG images, and those are included into a La@TeX{} or HTML document. -@command{lilypond-book} provides a way to automate this process: this -program extracts snippets of music from your document, runs LilyPond -on them, and outputs the document with pictures substituted for the -music. The line width and font size definitions for the music are -adjusted to match the layout of your document. - -This procedure may be applied to La@TeX{}, @code{html} or Texinfo -documents. - - +@command{lilypond-book} provides a way to automate this process: This +program extracts snippets of music from your document, runs +@command{lilypond} on them, and outputs the document with pictures +substituted for the music. The line width and font size definitions for +the music are adjusted to match the layout of your document. +This procedure may be applied to La@TeX{}, HTML or Texinfo documents. @menu * An example of a musicological document:: -* Integrating Texinfo and music:: * Integrating LaTeX and music:: +* Integrating Texinfo and music:: * Integrating HTML and music:: * Music fragment options:: * Invoking lilypond-book:: @@ -44,10 +41,8 @@ documents. @end menu - - @node An example of a musicological document -@section An example of a musicological document +@section An example of a musicological document @cindex musicology @cindex La@TeX{}, music in @@ -57,22 +52,23 @@ Some texts contain music examples. These texts are musicological treatises, songbooks or manuals like this. Such texts can be made by hand, simply by importing a PostScript figure into the word processor. However, there is an automated procedure to reduce the amount of work -involved HTML, La@TeX{}, and Texinfo documents. +involved in HTML, La@TeX{}, and Texinfo documents. A script called @code{lilypond-book} will extract the music fragments, format them, and put back the resulting notation. Here we show a -small example for use with La@TeX{}. The example also contains explanatory text, so we will -not comment on it further +small example for use with La@TeX{}. The example also contains +explanatory text, so we will not comment on it further. +@quotation @verbatim \documentclass[a4paper]{article} \begin{document} -Documents for lilypond-book may freely mix music and text. For -example, +Documents for @command{lilypond-book} may freely mix music and text. +For example, \begin{lilypond} -\relative { +\relative c' { c2 g'2 \times 2/3 { f8 e d } c'2 g4 } \end{lilypond} @@ -83,24 +79,25 @@ Options are put in brackets. c'4 f16 \end{lilypond} -Larger examples can be put in a separate file, and introduced with +Larger examples can be put into a separate file, and introduced with \verb+\lilypondfile+. \lilypondfile[quote,noindent]{screech-boink.ly} \end{document} @end verbatim +@end quotation Under Unix, you can view the results as follows @example cd input/tutorial mkdir -p out/ -lilypond-book --output=out/ lilybook.tex -@emph{lilypond-book (GNU LilyPond) 2.3.11} -@emph{Reading `input/tutorial/lilybook.tex'} +lilypond-book --output=out lilybook.tex +@emph{lilypond-book (GNU LilyPond) 2.5.0} +@emph{Reading lilybook.tex...} @emph{..lots of stuff deleted..} -@emph{Compiling `out//lilybook.tex'} +@emph{Compiling out/lilybook.tex...} cd out latex lilybook @emph{lots of stuff deleted} @@ -115,20 +112,19 @@ dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook ps2pdf lilybook.ps @end example -Running lilypond-book and running latex creates a lot of temporary -files, which would clutter up the working directory. To remedy this, -use the @code{--output=@var{dir}} option. It will create the files in -a separate subdirectory @file{dir}. +Running @command{lilypond-book} and @command{latex} creates a lot of +temporary files, which would clutter up the working directory. To remedy +this, use the @code{--output=@var{dir}} option. It will create the files +in a separate subdirectory @file{dir}. -Finally the result of the La@TeX{} example shown above.@footnote{ This -tutorial is processed with Texinfo, so the example is as well. This -gives slightly different results in layout.} This finishes the -tutorial section. +Finally the result of the La@TeX{} example shown above.@footnote{This +tutorial is processed with Texinfo, so the example gives slightly +different results in layout.} This finishes the tutorial section. @page -Documents for lilypond-book may freely mix music and text. For -example, +Documents for @command{lilypond-book} may freely mix music and text. +For example, @lilypond \relative c' { @@ -142,11 +138,12 @@ Options are put in brackets. c'4 f16 @end lilypond -Larger examples can be put in a separate file, and introduced with +Larger examples can be put into a separate file, and introduced with @code{\lilypondfile}. @lilypondfile[quote,noindent]{screech-boink.ly} +@page @cindex texinfo @cindex latex @@ -156,20 +153,18 @@ Larger examples can be put in a separate file, and introduced with @cindex documents, adding music to -@c @TeX{} in node name seems to barf @node Integrating LaTeX and music -@section Integrating LaTeX and music +@section Integrating La@TeX{} and music -La@TeX{} is the de facto standard for publishing layouts in the exact -sciences. It is built on top of the @TeX{} typesetting engine, so it -provides the best typography available anywhere. +La@TeX{} is the de-facto standard for publishing layouts in the exact +sciences. It is built on top of the @TeX{} typesetting engine, providing +the best typography available anywhere. -For more information about La@TeX{} -@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so -Short Introduction to La@TeX{}} provides a introduction to using +See @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/, +The not so Short Introduction to La@TeX{}} for an overview on how to use La@TeX{}. -For La@TeX{}, music is entered using +Music is entered using @example \begin[options,go,here]@{lilypond@} @@ -177,6 +172,9 @@ For La@TeX{}, music is entered using \end@{lilypond@} @end example +@noindent +or + @example \lilypondfile[options,go,here]@{@var{filename}@} @end example @@ -188,14 +186,13 @@ or \lilypond@{ YOUR LILYPOND CODE @} @end example -Running lilypond-book yields a file that can be processed with -La@TeX{}. - +Running @command{lilypond-book} yields a file that can be further processed +with La@TeX{}. -We show some examples here: +We show some examples here. The lilypond environment @example -\begin[staffsize=26]@{lilypond@} +\begin[quote,fragment,staffsize=26]@{lilypond@} c' d' e' f' g'2 g'2 \end@{lilypond@} @end example @@ -203,84 +200,77 @@ We show some examples here: @noindent produces -@lilypond[fragment,staffsize=26] +@lilypond[quote,fragment,staffsize=26] c' d' e' f' g'2 g'2 @end lilypond -Then the short version: +The short version @example -\lilypond[staffsize=11]@{@} +\lilypond[quote,fragment,staffsize=11]@{@} @end example @noindent produces -@lilypond[fragment,staffsize=11]{} +@lilypond[quote,fragment,staffsize=11]{} -The linewidth of the music will be adjust by examining the commands in -the document preamble, the part of the document before -@code{\begin@{document@}}. The @command{lilypond-book} command sends -these to La@TeX{} to find out how wide the text is. The line width -for the music fragments is then adjusted to the text width. - -After @code{\begin@{document@}}, the column changing commands -@code{\onecolumn}, @code{\twocolumn} commands -@ignore -and the -@code{multicols} environment from the multicol package -@end ignore -are also interpreted. +The default linewidth of the music will be adjusted by examining the +commands in the document preamble, the part of the document before +@code{\begin@{document@}}. The @command{lilypond-book} command sends +these to La@TeX{} to find out how wide the text is. The line width +for the music fragments is then adjusted to the text width. Note that +this heuristic algorithm can fail easily; in such cases it is necessary +to use the @code{linewidth} music fragment option. @cindex titling and lilypond-book @cindex @code{\header} in La@TeX{} documents - -The music will be surrounded by @code{\preLilyPondExample} and -@code{\postLilyPondExample}, which are defined to be empty by default. +Each snippet calls @code{\preLilyPondExample} before and +@code{\postLilyPondExample} after the music if those macros have been +defined by the user. @cindex outline fonts @cindex type1 fonts @cindex dvips @cindex invoking dvips -For printing the La@TeX{} document, you will need to use dvips. For -producing PostScript with scalable fonts, add the following options to -the dvips command line: +For printing the La@TeX{} document you need a DVI to PostScript translator +like @command{dvips}. For producing PostScript with scalable fonts, add +the following options to the @command{dvips} command line: + @example - -Ppdf -u+lilypond.map -u+ec-mftrace.map +-Ppdf -u+lilypond.map -u+ec-mftrace.map @end example @noindent -PDF can then be produced with @code{ps2pdf}. +PDF can then be produced with a PostScript to PDF translator like +@code{ps2pdf} (which is part of GhostScript). @cindex international characters @cindex latin1 LilyPond does not use the La@TeX{} font handling scheme for lyrics and text -markups, so if you use characters in your lilypond-book +markups; it uses the EC font family and + + + so if you use characters in your @command{lilypond-book} documents that are not included in the standard US-ASCII character set, include @code{\usepackage[latin1]@{inputenc@}} in the file -header but do not include @code{\usepackage[T1]@{fontenc@}}. Character +header but do not include @code{\usepackage[T1]@{fontenc@}}. Character sets other than latin1 are not supported directly but may be handled by explicitly specifying the @code{font-name} property in LilyPond and -using the corresponding La@TeX{} packages. Please consult the mailing list +using the corresponding La@TeX{} packages. Please consult the mailing list for more details. - - @node Integrating Texinfo and music @section Integrating Texinfo and music Texinfo is the standard format for documentation at the GNU -project. An example of a texinfo document is this manual. The HTML, +project. An example of a texinfo document is this manual. The HTML, PDF and Info versions of the manual are made from the document. -When run on a lilypond-book, produces a @file{.texi} file containing -@code{@@image} tags for HTML and info. For the printed edition, the -raw @TeX{} output of LilyPond is included into the main document. - In the input file, music is specified like @example @@ -291,11 +281,15 @@ In the input file, music is specified like @@lilypondfile[options,go,here]@{@var{filename}@} @end example -When lilypond-book is run on it, this results in a texinfo file. We -show two simple examples here. First a complete block: +When @command{lilypond-book} is run on it, this results in a texinfo file +(with extension @file{.texi}) containing @code{@@image} tags for HTML and +info. For the printed edition, the raw @TeX{} output of LilyPond is +included into the main document. + +We show two simple examples here. A lilypond environment @example -@@lilypond[staffsize=26] +@@lilypond[fragment] c' d' e' f' g'2 g' @@end lilypond @end example @@ -307,22 +301,20 @@ produces c' d' e' f' g'2 g' @end lilypond -Then the short version: +The short version @example -@@lilypond[staffsize=11]@{@} +@@lilypond[fragment,staffsize=11]@{@} @end example @noindent produces -@lilypond[fragment,staffsize=11]{ } - -When producing texinfo, lilypond-book also generates bitmaps of the -music, so you can make a HTML document with embedded music. - - +@lilypond[fragment,staffsize=11]{} +When producing texinfo, @command{lilypond-book} also generates bitmaps of +the music (in PNG format), so you can make an HTML document with embedded +music. @node Integrating HTML and music @@ -331,32 +323,27 @@ music, so you can make a HTML document with embedded music. Music is entered using @example - - \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 + + \key c \minor c4 es g2 @end example @noindent -of which lilypond-book will produce a HTML with appropriate image tags for the -music fragments: - -@c why the second example? -gp -@example - - \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 - -@end example +of which @command{lilypond-book} will produce a HTML with appropriate image +tags for the music fragments: @lilypond[fragment,relative=2] - \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 + \key c \minor c4 es g2 @end lilypond -For inline pictures, use @code{} syntax, e.g. +For inline pictures, use @code{} syntax, where the options +are separated by a colon from the music, for example + @example -Some music in a line of text. +Some music in a line of text. @end example -@c FIXME: check if this feature is coming soon; if not, @ignore this stuff. +@c FIXME: check if this feature is coming soon; if not, @ignore this stuff. A special feature not (yet) available in other output formats, is the @code{} tag, for example, @example @@ -364,18 +351,19 @@ A special feature not (yet) available in other output formats, is the @end example This runs @file{trip.ly} through @code{lilypond} (see also @ref{Invoking lilypond}), and substitutes a preview image in the -output. The image links to a separate HTML file, so clicking it will +output. The image links to a separate HTML file, so clicking it will take the viewer to a menu, with links to images, midi and printouts. @cindex titling in THML @cindex preview image @cindex thumbnail + @node Music fragment options @section Music fragment options -The commands for lilypond-book have room to specify one or more of the -following options: +The commands for @command{lilypond-book} have room to specify one or more +of the following options: @table @code @item verbatim @@ -427,7 +415,6 @@ For example \end@{lilypond@} @end example - @item noindent sets indentation of the first music system to zero. This option affects LilyPond, not the text layout. @@ -459,8 +446,7 @@ starting note, where the default @code{1} is middle C. @node Invoking lilypond-book -@section Invoking lilypond-book - +@section Invoking @command{lilypond-book} Running @command{lilypond-book} generates lots of small files that LilyPond will process. To avoid all that garbage in the source @@ -472,8 +458,8 @@ lilypond-book --output=out yourfile.lytex cd out @end example -This will produce a .tex or .texi file. To produce a pdf from the -.tex file, you should do +This will produce a @file{.tex} or @file{.texi} file. To produce pdf +output from the @file{.tex} file, you should do @example latex yourfile.tex @@ -489,12 +475,12 @@ procedures for texinfo. @table @code @item @option{-f @var{format}}, @option{--format=@var{format}} Specify the document type to process: @code{html}, @code{latex} or -@code{texi} (the default). @command{lilypond-book} figures this +@code{texi} (the default). @command{lilypond-book} figures this out automatically. The @code{texi} document type produces a texinfo file with music fragments in the DVI output only. For getting images in the HTML -version, the format +version, the format @code{texi-html} must be used. @item @option{-F @var{filter}}, @option{--filter=@var{filter}} @@ -529,8 +515,6 @@ For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}. Texinfo input will be written to a file with extension @file{.texi}. - - @refbugs The Texinfo command @code{pagesize} is not interpreted. Almost all @@ -551,12 +535,8 @@ You can use any filename extension, but if you do not use the recommended extension, you may need to manually specify what output format you want. See @ref{Invoking lilypond-book} for details. -@code{lilypond-book} automatically selects the output format based -on the filename. For example, running @code{lilypond-book myfile.lytex} -will make @code{lilypond-book} produce latex output. If the file -was merely @code{myfile}, then @code{lilypond-book} would not know -which output format to produce (unless you specified it with -@code{-f=latex}. +@code{Lilypond-book} automatically selects the output format based +on the filename. @table @code diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index 92e9c8d3c5..24e4577456 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -31,7 +31,7 @@ Distributions will want to install lilypond.info in postinstall, doing: @ignore @omfcreator Han-Wen Nienhuys and Jan Nieuwenhuizen -@omfdescription User manual of the LilyPond music engraving system +@omfdescription User manual of the LilyPond music engraving system @omftype user manual @omfcategory Applications|Publishing @omflanguage English @@ -64,7 +64,7 @@ besides the reader and the writer. print. Instead refer to an example input file (@inputfileref), these are clickable in HTML. -* Abbrevs in caps, e.g. HTML, DVI, MIDI, etc. +* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc. * Colon usage 0. Do not use a colon to introduce examples, sentences just continue @@ -119,8 +119,8 @@ Copyright @copyright{} 1999--2004 by the authors @lilypond[raggedright] \score { \context Lyrics { - \override Score.RehearsalMark #'self-alignment-X = #LEFT - \override Score.RehearsalMark #'font-size = #-2 + \override Score.RehearsalMark #'self-alignment-X = #LEFT + \override Score.RehearsalMark #'font-size = #-2 \mark #(ly:export (string-append "(For LilyPond version " (lilypond-version) ")")) s2 @@ -178,7 +178,7 @@ of this and other documentation. * Sound:: Producing MIDI output * Changing defaults:: Tuning output. * Interfaces for programmers:: -* Running LilyPond:: Operation. +* Running LilyPond:: Operation. * Converting from other formats:: Converting to lilypond source format. * Integrating text and music:: Integrating text and music with lilypond-book. * Literature list:: diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi index d340e9c476..0bd9ea43f7 100644 --- a/Documentation/user/macros.itexi +++ b/Documentation/user/macros.itexi @@ -139,7 +139,7 @@ @macro seeinternals{NAME} -internals document, @internalsref{\NAME\} +internals document, @internalsref{\NAME\} @end macro @end iftex diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely index f5aa352257..90296c0352 100644 --- a/Documentation/user/music-glossary.tely +++ b/Documentation/user/music-glossary.tely @@ -28,7 +28,7 @@ PostScript} and @uref{music-glossary.pdf,PDF}. @author Adrian Mariano @c Italian glossary @author Heikki Junes @c Finnish glossary -@c Fixes by Jean-Pierre Coulon and `Dirk' +@c Fixes by Jean-Pierre Coulon and `Dirk' Copyright @copyright{} 1999--2004 by the authors @@ -205,7 +205,7 @@ DK: l S: tillfälligt förtecken, FI: tilapäinen etumerkki. -@c F: altération accidentelle, D: Vorzeichen, Versetzungszeichen, +@c F: altération accidentelle, D: Vorzeichen, Versetzungszeichen, @c Akzidenz, NL: toevallig teken, I: accidento. A sharp raises a tone by a @aref{semitone}, a double sharp raises it @@ -215,13 +215,13 @@ accidental. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override TextScript #'font-style = #'large +%\override TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c'' { gis1 gisis ges geses g! } \context Lyrics \lyrics { - \override Lyrics .LyricText #'self-alignment-X = #-1 + \override Lyrics .LyricText #'self-alignment-X = #-1 sharp "db. sharp" flat "db. flat" natural } @end lilypond @@ -249,9 +249,9 @@ S: adagio, FI: adagio, hitaasti. It.@: comfortable, easy. -1. Slow tempo, slower -- especially in even meter -- than +1.@tie{}Slow tempo, slower -- especially in even meter -- than @aref{andante} and faster than @aref{largo}. -2. A movement in slow tempo, especially the second (slow) movement of +2.@tie{}A movement in slow tempo, especially the second (slow) movement of @aref{sonata}s, symphonies, etc. @aitem{allegro}@c @@ -359,14 +359,14 @@ the duration of the long a.@: is proportional to that of the main note. \key d \major \time 4/4 -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large 4_"notation" r - { \override Stem #'flag-style = #'() + { \override Stem #'flag-style = #'() \grace g16 \revert Stem #'flag-style } fis8 e16 fis - { \override Stem #'flag-style = #'() + { \override Stem #'flag-style = #'() \grace a16 \revert Stem #'flag-style } @@ -384,7 +384,7 @@ An appoggiatura may have more notes preceding the main note. \relative c'' { \key as \major \time 2/4 -% \override Score.TextScript #'font-style = #'large +% \override Score.TextScript #'font-style = #'large \grace { bes16 } as8_"notation" as16 bes as8 g | \grace { as16[( bes] } < c as >4-) \grace { as16[( bes] } < c as >4-) \bar "||" @@ -458,8 +458,8 @@ DK: h S: handskrift, FI: käsinkirjoitettu nuotti. -1. A manuscript in the composer's own hand. -2. Music prepared for photoreproduction by freehand drawing, +1.@tie{}A manuscript in the composer's own hand. +2.@tie{} Music prepared for photoreproduction by freehand drawing, with the aid of a straightedge ruler and T-square only, which attempts to emulate engraving. This required more skill than did engraving. @@ -540,8 +540,8 @@ DK: bas, S: bas, FI: basso, matala miesääni. -1. The lowest of men's voices. -2. Sometimes, especially in jazz music, used as +1.@tie{}The lowest of men's voices. +2.@tie{}Sometimes, especially in jazz music, used as an abbreviation for double bass. @aref{strings}. @@ -559,7 +559,7 @@ The number of beams determine the note value of the connected notes. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override TextScript #'font-style = #'large +%\override TextScript #'font-style = #'large \relative c'' { g8_"1/8"[ g g g] s16 g16_"1/16"[ g g g] s16 @@ -608,7 +608,7 @@ orchestral or choral score. @lilypond[fragment,raggedright] \context GrandStaff << - \relative c''\context Staff = SA { \clef treble g4 e c2 } + \relative c''\context Staff = SA { \clef treble g4 e c2 } \relative c \context Staff = SB { \clef bass c1 \bar "|." } >> @end lilypond @@ -687,8 +687,8 @@ lines. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -\override Score.Clef #'full-size-change = ##t -%\override Score.LyricText #'font-style = #'large +\override Score.Clef #'full-size-change = ##t +%\override Score.LyricText #'font-style = #'large \oldaddlyrics \context Staff \relative c' { \clef soprano c1 s s @@ -698,7 +698,7 @@ lines. \clef baritone c s s } \context Lyrics \lyrics { - \override Lyrics .LyricText #'self-alignment-X = #-1 + \override Lyrics .LyricText #'self-alignment-X = #-1 "Soprano " "Mezzosoprano " "Alto " "Tenor " Baritone } @end lilypond @@ -781,7 +781,7 @@ chords are denoted open chords @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override TextScript #'font-style = #'large +%\override TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c'' { 1 s s @@ -1052,7 +1052,7 @@ abbreviation ``cresc.''. @lilypond[fragment,raggedright] \key g \major \time 4/4 -\relative c'' { g4 \< a b c | d1\! \bar "|." } +\relative c'' { g4 \< a b c | d1\! \bar "|." } @end lilypond @aitem{cue-notes}@c @@ -1087,7 +1087,7 @@ of the 20th century % \override Staff.Custos #'neutral-position = #4 \override Staff.Custos #'neutral-direction = #-1 \override Staff.Custos #'style = #'hufnagel - c'1 \break + c'1 \break 1 } @@ -1138,8 +1138,8 @@ Abbreviated ``d.s.''. Repetition, not from the beginning, but from another place frequently near the beginning marked by a sign: @lilypond[fragment,raggedright] -%\override TextScript #'font-style = #'large -\override TextScript #'font-shape = #'italic +%\override TextScript #'font-style = #'large +\override TextScript #'font-shape = #'italic \key g \major \time 4/4 \relative c'' { d1 | @@ -1165,7 +1165,7 @@ or the abbreviation ``decresc.''. @lilypond[fragment,raggedright] \relative c'' { \key g \major \time 4/4 - d4 \> c b a | g1 \! \bar "|." + d4 \> c b a | g1 \! \bar "|." } @end lilypond @@ -1200,12 +1200,12 @@ music but also to some extent in newer jazz music. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c' { c1 d - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 e^"~~ S" f g a b^"~~ S" c } \context Lyrics \lyrics { @@ -1215,12 +1215,12 @@ music but also to some extent in newer jazz music. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c' { d1 - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 e^"~~ S" f g a b^"~~ S" c d } \context Lyrics \lyrics { @@ -1230,11 +1230,11 @@ music but also to some extent in newer jazz music. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c' { - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 e1^"~~ S" f g a b^"~~ S" c d e } \context Lyrics \lyrics { @@ -1244,12 +1244,12 @@ music but also to some extent in newer jazz music. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c' { f1 g a - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 b^"~~ S" c d e^"~~ S" f } \context Lyrics \lyrics { @@ -1259,12 +1259,12 @@ music but also to some extent in newer jazz music. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c'' { g1 a - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 b^"~~ S" c d e^"~~ S" f g } \context Lyrics \lyrics { Mixolydian @@ -1273,12 +1273,12 @@ music but also to some extent in newer jazz music. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c'' { a1 - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 b^"~~ S" c d e^"~~ S" f g a } \context Lyrics \lyrics { @@ -1293,12 +1293,12 @@ harmonic minor scale type an augmented second (A) occurs between the 6th and @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c' { c1 d - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 e^"~~ S" f g a b^"~~ S" c } \context Lyrics \lyrics { @@ -1308,12 +1308,12 @@ harmonic minor scale type an augmented second (A) occurs between the 6th and @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c'' { a1 - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 b^"~~ S" c d e^"~~ S" f g a } \context Lyrics \lyrics { @@ -1323,12 +1323,12 @@ harmonic minor scale type an augmented second (A) occurs between the 6th and @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c'' { a1 - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 b^"~~ S" c d e^"~~ S" f!^"~~ A" gis^"~~ S" a } \context Lyrics \lyrics { @@ -1338,12 +1338,12 @@ harmonic minor scale type an augmented second (A) occurs between the 6th and @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \relative c'' { a1 - \override TextScript #'padding = #-4 + \override TextScript #'padding = #-4 b^"~~ S" c d e fis gis^"~~ S" a g! f!^"~~ S" e d c^"~~ S" b a } @@ -1660,13 +1660,13 @@ but equal pitch. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c'' { gis1 s s as s s s s s s } \context Lyrics \lyrics { - \override Lyrics .LyricText #'self-alignment-X = #-1 + \override Lyrics .LyricText #'self-alignment-X = #-1 "g sharp " "a flat " "dim fifth " "augm fourth" } @end lilypond @@ -1727,8 +1727,8 @@ symbol indicates playing an octave lower (for example on double bass @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -\override Staff.Clef #'full-size-change = ##t -%\override Score.LyricText #'font-style = #'large +\override Staff.Clef #'full-size-change = ##t +%\override Score.LyricText #'font-style = #'large \oldaddlyrics \relative c { \clef varbaritone @@ -1743,7 +1743,7 @@ symbol indicates playing an octave lower (for example on double bass f1 } \context Lyrics \lyrics { -% \override Lyrics .LyricText #'self-alignment-X = #-1 +% \override Lyrics .LyricText #'self-alignment-X = #-1 "baritone " "bass " "sub-bass " @@ -1816,7 +1816,7 @@ less than a quarter note. The number of flags determines the @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c'' { g8_"1/8" s8 g16_"1/16" s8 @@ -1895,8 +1895,8 @@ variants of the base chords. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \encoding "TeX" \context Voice \relative c'' { @@ -1933,8 +1933,8 @@ scores are notated like that). @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -\override Staff.Clef #'full-size-change = ##t -%\override Score.LyricText #'font-style = #'large +\override Staff.Clef #'full-size-change = ##t +%\override Score.LyricText #'font-style = #'large \oldaddlyrics \relative c'' { \clef french @@ -1947,7 +1947,7 @@ scores are notated like that). g s s } \context Lyrics \lyrics { - \override Lyrics .LyricText #'self-alignment-X = #-1 + \override Lyrics .LyricText #'self-alignment-X = #-1 "french violin clef " "violin clef " "octaved up " @@ -2053,7 +2053,7 @@ section. @aref{functional harmony}. \partial 4 < c g e >4 | < c a f > < b g d > < c g e >2 } -% %\override Score.LyricText #'font-style = #'large +% %\override Score.LyricText #'font-style = #'large \oldaddlyrics \context Staff = SB \relative c { \clef bass @@ -2083,7 +2083,7 @@ Consonances: @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \context Voice \relative c'' { 1_"unisone " s _"third " s @@ -2099,8 +2099,8 @@ Dissonances: @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large -\context Voice \relative c'' { +%\override Score.TextScript #'font-style = #'large +\context Voice \relative c'' { 1_"second " s s _"seventh " s s _"ninth" s s @@ -2140,8 +2140,8 @@ of such two forms an octave. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \context Voice \relative c'' { < g g >1 s @@ -2161,18 +2161,18 @@ of such two forms an octave. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c'' { < g c >1^"perfect" s - < g cis >^"augm" s - < g d' >^"perfect" s + < g cis >^"augm" s + < g d' >^"perfect" s < g des' > ^"dimin" s - < gis es' >^"dimin" s - < g! es' >^"minor" s - < g e'! >^"major" s - < g eis' >^"augm" s + < gis es' >^"dimin" s + < g! es' >^"minor" s + < g e'! >^"major" s + < g eis' >^"augm" s } \context Lyrics \lyrics { "fourth " "fourth " "fifth " "fifth " @@ -2182,18 +2182,18 @@ of such two forms an octave. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large -%\override Score.TextScript #'font-style = #'large +%\override Score.LyricText #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \oldaddlyrics \context Staff \relative c'' { - < gis f'! >1^"dimin" s - < g! f'! >^"minor" s - < g fis' >^"major" s + < gis f'! >1^"dimin" s + < g! f'! >^"minor" s + < g fis' >^"major" s < g g' > s - < g as' >^"minor" s - < g a'! >^"major" s - < g bes' >^"minor" s - < g b'! >^"major" s + < g as' >^"minor" s + < g a'! >^"major" s + < g bes' >^"minor" s + < g b'! >^"major" s } \context Lyrics \lyrics { "seventh " "seventh " "seventh " "octave " @@ -2215,9 +2215,9 @@ The difference between an interval and an octave. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \context Staff \relative c'' { - < g a >1_"second " s s < g' a, >_"seventh " s s \bar "||" + < g a >1_"second " s s < g' a, >_"seventh " s s \bar "||" < g, b >_"third " s s < g' b, >_"sixth " s s \bar "||" < g, c >_"fourth " s s < g' c, >_"fifth " s s \bar "||" } @@ -2330,7 +2330,7 @@ unlike (b) @emph{leggiero} or @emph{non-legato}, (c) @emph{portato}, and c4-. d-. e-. \bar "||" } \context Lyrics \lyrics { -% \override Lyrics .LyricText #'font-style = #'large +% \override Lyrics .LyricText #'font-style = #'large a b "" "" c @@ -2404,7 +2404,7 @@ Note value: double length of @aref{breve}. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f \relative c'' { - \override NoteHead #'style = #'mensural + \override NoteHead #'style = #'mensural g\longa } @end lilypond @@ -2482,8 +2482,8 @@ DK: mediant, S: mediant, FI: keskisävel. -1. The third @b{scale degree}. -2. A @aref{chord} having its base tone +1.@tie{}The third @b{scale degree}. +2.@tie{}A @aref{chord} having its base tone a third from that of another chord. For example, the tonic chord may be replaced by its lower mediant (variant tonic). @aref{functional harmony}, @aref{relative key}. @@ -2593,7 +2593,7 @@ First C below the 440 Hz A. @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -\override Staff.Clef #'full-size-change = ##t +\override Staff.Clef #'full-size-change = ##t \relative c' { \clef bass c1 s \clef alto c s @@ -2802,10 +2802,10 @@ but sometimes (mostly in pre baroque music) the double length note value @emph{longa} is used. @lilypond[fragment,notime,linewidth=13.0\cm] -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \set Score.automaticBars = ##f \relative c'' { - \override NoteHead #'style = #'mensural + \override NoteHead #'style = #'mensural a\longa_"longa" a\breve_"breve" \revert NoteHead #'style a1_"1/1" a2_"1/2" a4_"1/4" s16 a8_"1/8" s16 @@ -2813,7 +2813,7 @@ but sometimes (mostly in pre baroque music) the double length note value @end lilypond @lilypond[fragment,notime,linewidth=13.0\cm] -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \set Score.automaticBars = ##f \relative c'' { r\longa_"longa" r\breve_"breve" @@ -2825,7 +2825,7 @@ An augmentation dot after a note multiplies the duration by one and a half. Another dot adds yet a fourth of the duration. @lilypond[fragment,linewidth=13.0\cm] -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c'' { \time 4/4 g4._"pointed" g8 g2 | g4 ~ g8 g g2 \bar "||" @@ -2838,7 +2838,7 @@ Subdivisions by@w{ }2 (@emph{tuplets}) or@w{ }4 (@emph{quadruplets}) of dotted notes are also frequently used. @lilypond[fragment,linewidth=13.0\cm] -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c'' { \time 4/4 \times 2/3 {g8_"triplets" g g} g4 g8 g g4 \bar "||" @@ -2890,9 +2890,9 @@ the upper note is played first. @lilypond[fragment,linewidth=13.0\cm] << \context Staff = sa { -% \override Score.TextScript #'font-style = #'large +% \override Score.TextScript #'font-style = #'large \relative c'' { - c2._"pre-1850" b4\trill | c1 \bar "||" + c2._"pre-1850" b4\trill | c1 \bar "||" c2._"post-1850" b4\trill | c1 \bar "||" } } @@ -2909,7 +2909,7 @@ Other frequently used ornaments are the @emph{turn}, the @emph{mordent}, and the @lilypond[fragment,linewidth=13.0\cm] << \context Staff = sa { -% \override Score.TextScript #'font-style = #'large +% \override Score.TextScript #'font-style = #'large \relative c'' { a4_"turn" b\turn c2 \bar "||" g4_"mordent" a b\mordent a \bar "||" @@ -2918,7 +2918,7 @@ Other frequently used ornaments are the @emph{turn}, the @emph{mordent}, and the } \relative c'' { a4 c16[ b a b] c2 - g4 a b16-[ a b8] a4 + g4 a b16-[ a b8] a4 e'4 e32[ d e d ~ d8] c2 } >> @@ -2950,8 +2950,8 @@ DK: stemme, S: stämma, FI: stemma, instrumenttiosuus. -1. In instrumental or choral music the music for the single instrument -or voice. 2. in contrapuntal music @aref{counterpoint} the single +1.@tie{}In instrumental or choral music the music for the single instrument +or voice. 2.@tie{}in contrapuntal music @aref{counterpoint} the single melodic line of the contrapunctal web. @aitem{percussion}@c @@ -3068,7 +3068,7 @@ DK: presto, S: presto, FI: presto, hyvin nopeasti. -Very quick, i.e., quicker than @aref{allegro}; @emph{prestissimo} +Very quick, i.e., quicker than @aref{allegro}; @emph{prestissimo} denotes the highest possible degree of speed. @aitem{Pythagorean comma}@c @@ -3164,7 +3164,7 @@ with the same @aref{key signature}. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c' { \key es \major es1_"e flat major" f g as bes c d es @@ -3174,7 +3174,7 @@ with the same @aref{key signature}. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c' { \key es \major c1_"c minor" d es f g a! b! c \bar "||" @@ -3285,7 +3285,7 @@ sub@-do@-mi@-nant (S) and V = dominant (D). @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.automaticBars = ##f -%\override Score.LyricText #'font-style = #'large +%\override Score.LyricText #'font-style = #'large %\set minVerticalAlign = #8 \oldaddlyrics \context Staff \relative c' { @@ -3293,7 +3293,7 @@ sub@-do@-mi@-nant (S) and V = dominant (D). } \context Lyrics \lyrics { << { I II III IV V VI VII I } - { T "" "" S D } >> + { T "" "" S D } >> } @end lilypond @@ -3583,7 +3583,7 @@ whole note. @aref{beam}. @lilypond[fragment,notime,linewidth=13.0\cm] \set Score.autoBeaming = ##f \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c'' { g2_"1/2" g' s16 g,4_"1/4" g' s16 @@ -3713,7 +3713,7 @@ the underlaying (normal) pulse and the actual (abnormal) rhythm. \relative c' { \partial 4 d8 dis | - e c'4 e,8 c'4 e,8 c' ( | c2) + e c'4 e,8 c'4 e,8 c' ( | c2) } @end lilypond @@ -3867,9 +3867,9 @@ with figures designating the chief @aref{interval}s and es8 c d bes c as bes16 as g f | es4 } \context Lyrics \lyrics { - \override Lyrics .VerticalAlign #'threshold = #'(6 . 12) + \override Lyrics .VerticalAlign #'threshold = #'(6 . 12) << { "" "6" "" "4" "" "6" "" "" "6" "4" } - { "" "" "" "2" "" "" "" "" "" "2" } >> + { "" "" "" "2" "" "" "" "" "" "2" } >> } >> @end lilypond @@ -3995,7 +3995,7 @@ a @aref{chord}, usually in the distance of a third @lilypond[fragment,notime,raggedright] \set Score.automaticBars = ##f -%\override Score.TextScript #'font-style = #'large +%\override Score.TextScript #'font-style = #'large \relative c' { e2:32_"a" f:32 [ e8:16 f:16 g:16 a:16 ] s4 @@ -4133,10 +4133,10 @@ DK: stemme, S: stämma, FI: ääni, lauluääni. -1. Human voices: @aref{soprano}, @aref{mezzo-soprano}, +1.@tie{}Human voices: @aref{soprano}, @aref{mezzo-soprano}, @aref{contralto}, @aref{tenor}, @aref{baritone}, @aref{bass}. -2. A melodic layer or part of a polyphonic composition. +2.@tie{}A melodic layer or part of a polyphonic composition. @aitem{weak beat}@c ES: tiempo débil, diff --git a/Documentation/user/notation.itely b/Documentation/user/notation.itely index 74b141709f..1894bb43af 100644 --- a/Documentation/user/notation.itely +++ b/Documentation/user/notation.itely @@ -108,7 +108,7 @@ cisis @end lilypond There are predefined sets of note names for various other languages. -To use them, include the language specific init file. For +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 @@ -168,7 +168,7 @@ 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 +(i.e., an accidental within parentheses) can be obtained by adding the question mark `@code{?}' after the pitch. @lilypond[quote,raggedright,fragment,verbatim] @@ -322,11 +322,11 @@ r1 r2 r4 r8 r16 r32 r64 r64 @lilypond[quote] \score { \relative c'' { - a\breve*1/2 \autoBeamOff + a\breve*1/2 \autoBeamOff a1 a2 a4 a8 a16 a32 a64 a64 \bar "empty" \break - r\longa*1/4 r\breve *1/2 + r\longa*1/4 r\breve *1/2 r1 r2 r4 r8 r16 r32 r64 r64 } \layout { @@ -402,7 +402,7 @@ b16*4 c4 This manual: @ref{Tuplets} -@c TODO: I'm not certain that Stems belong here in the manual. -gp +@c TODO: I'm not certain that Stems belong here in the manual. -gp @node Stems @subsection Stems @@ -666,7 +666,7 @@ be placed inside @code{\transpose}. @subsection Octave check -Octave checks make octave errors easier to correct: a note may be +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 @@ -856,7 +856,7 @@ such as key signatures, clefs and time signatures. @cindex adjusting staff symbol -Notes, dynamic signs, etc. are grouped +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. @@ -1050,7 +1050,7 @@ the staff. They are created by invoking the function 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{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., @@ -1167,7 +1167,7 @@ Automatic beaming does not use the measure grouping specified with Partial measures, for example in upsteps, are entered using the @code{\partial} command @lilypond[quote,raggedright,fragment,verbatim,relative=2] -\partial 16*5 c16 cis d dis e | a2. c,4 | b2 +\partial 16*5 c16 cis d dis e | a2. c,4 | b2 @end lilypond The syntax for this command is @@ -1204,7 +1204,7 @@ the @code{\partial} should follow the grace notes @cindex @code{\bar} Bar lines and bar numbers are calculated automatically. For unmetered -music (e.g. cadenzas), this is not desirable. By setting +music (cadenzas, for example), this is not desirable. By setting @code{Score.timing} to false, this automatic timing can be switched off. Empty bar lines, @@ -1353,7 +1353,7 @@ c4 c1 @node Controlling formatting of prefatory matter @subsection Controlling formatting of prefatory matter -TODO Somebody needs to explain this example, but I don't know what +TODO: Somebody needs to explain this example, but I don't know what they're trying to do, so it won't be me. -gp @lilypond[quote,verbatim] @@ -1409,8 +1409,8 @@ small, short-lived voices or for single chords @lilypond[quote,raggedright,verbatim,fragment] \context Staff \relative c'' { - c4 << { f d e } \\ { b c2 } >> - c4 << g' \\ b, \\ f' \\ d >> + c4 << { f d e } \\ { b c2 } >> + c4 << g' \\ b, \\ f' \\ d >> } @end lilypond @@ -1418,7 +1418,7 @@ The separator causes @internalsref{Voice} contexts@footnote{Polyphonic voices are sometimes called ``layers'' in 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 +each of these contexts, vertical direction of slurs, stems, etc., is set appropriately. @cindex @code{\voiceOne} @@ -1432,9 +1432,9 @@ a stem directions and horizontal shift for each part @lilypond[quote,raggedright,verbatim] \relative c'' \context Staff << - \new Voice { \voiceOne cis2 b } + \new Voice { \voiceOne cis2 b } \new Voice { \voiceThree b4 ais ~ ais4 gis4 } - \new Voice { \voiceTwo fis4~ fis4 f ~ f } >> + \new Voice { \voiceTwo fis4~ fis4 f ~ f } >> @end lilypond @noindent @@ -1468,7 +1468,7 @@ LilyPond also vertically shifts rests that are opposite of a stem, for example @lilypond[quote,raggedright,fragment,verbatim] -\context Voice << c''4 \\ r4 >> +\context Voice << c''4 \\ r4 >> @end lilypond @@ -1514,7 +1514,7 @@ be used to override typesetting decisions. } \\ { - \once \override NoteColumn #'force-hshift = #1.7 + \once \override NoteColumn #'force-hshift = #1.7 } >> @end lilypond @@ -1568,7 +1568,7 @@ grouped. LilyPond inserts beams automatically @lilypond[quote,raggedright,fragment,verbatim,relative=2] -\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 +\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 @@ -1794,9 +1794,9 @@ down. However, this behaviour can be altered with the @lilypond[quote,raggedright,relative=2,fragment,verbatim] { b8[ b] - \override Beam #'neutral-direction = #-1 + \override Beam #'neutral-direction = #-1 b[ b] - \override Beam #'neutral-direction = #1 + \override Beam #'neutral-direction = #1 b[ b] } @end lilypond @@ -1858,7 +1858,7 @@ voices, which is often an unwanted result The @code{voice} option should be used 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 +used by one musician (e.g., a conductor) then @code{modern} or @code{modern-cautionary} should be used instead. @@ -1949,7 +1949,7 @@ they appear in the input file. This is a problem when accidentals in a chord depend on each other, which does not happen for the default accidental style. The problem -can be solved by manually inserting @code{!} and @code{?} for the +can be solved by manually inserting @code{!} and @code{?} for the problematic notes. @@ -2006,7 +2006,7 @@ directions. By adding @code{_} or @code{^} before the opening parentheses, the direction is also set. For example, @lilypond[relative=2,raggedright,quote,verbatim,fragment] -c4_( c) c^( c) +c4_( c) c^( c) @end lilypond Some composers write two slurs when they want legato chords. This can @@ -2048,7 +2048,7 @@ indicate a musical sentence. It is written using @code{\(} and @code{\)} respectively @lilypond[quote,raggedright,fragment,verbatim,relative=1] -\time 6/4 c'\( d( e) f( e) d\) +\time 6/4 c'\( d( e) f( e) d\) @end lilypond Typographically, the phrasing slur behaves almost exactly like a @@ -2176,7 +2176,7 @@ Program reference: @internalsref{TextScriptEvent}, @internalsref{TextScript}. @subsection Text spanners @cindex Text spanners -Some performance indications, e.g. @i{rallentando} or @i{accelerando}, +Some performance indications, e.g., @i{rallentando} or @i{accelerando}, are written as text and are extended over many measures with dotted lines. Such texts are created using text spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to the first and last @@ -2323,7 +2323,7 @@ they are entered decides which one comes first. \once \override TextScript #'script-priority = #-100 a4^\prall^\markup { \sharp } -\once \override Script #'script-priority = #-100 +\once \override Script #'script-priority = #-100 a4^\prall^\markup { \sharp } @end lilypond @@ -2341,7 +2341,7 @@ MIDI rendering of the music. -@node Running trills +@node Running trills @subsection Running trills Long running trills are made with @code{\startTrillSpan} and @@ -2389,7 +2389,7 @@ c^\markup { \finger "2-3" } @cindex subscript You can use the thumb-script to indicate that a note should be -played with the thumb (e.g. in cello music) +played with the thumb (e.g., in cello music) @lilypond[quote,verbatim,raggedright,fragment,relative=2] 8 @@ -2478,7 +2478,7 @@ example is shown here with timing tuples @lilypond[quote,raggedright] << \relative c''{ - c4 \grace c16 c4 \grace { + c4 \grace c16 c4 \grace { c16[ d16] } c2 c4 } \new Lyrics \lyricmode { @@ -2486,7 +2486,7 @@ example is shown here with timing tuples \markup { (0,0) } 4 \grace { \markup { - ( \fraction 1 4 , \fraction -1 16 ) } 16 } + ( \fraction 1 4 , \fraction -1 16 ) } 16 } \markup { (\fraction 1 4 , 0 ) } 4 \grace { \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16 @@ -2574,19 +2574,19 @@ A score that starts with a @code{\grace} section needs an explicit 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 +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[quote,raggedright,relative=2,verbatim,fragment] << \new Staff { e4 \bar "|:" \grace c16 d4 } - \new Staff { c4 \bar "|:" d4 } >> + \new Staff { c4 \bar "|:" d4 } >> @end lilypond @noindent This can be remedied by inserting grace skips, for the above example @example -\new Staff @{ c4 \bar "|:" \grace s16 d4 @} +\new Staff @{ c4 \bar "|:" \grace s16 d4 @} @end example Grace sections should only be used within sequential music @@ -2832,7 +2832,7 @@ bracket only lasts one measure, which is a duration of 3/4. \time 3/4 c c c \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4) - \repeat "volta" 5 { d d d } + \repeat "volta" 5 { d d d } \alternative { { e e e f f f } { g g g } } } @@ -3034,7 +3034,7 @@ patterns that divide the measure length are replaced by slashes @lilypond[quote,verbatim,raggedright] \new Voice \relative c' { - \repeat "percent" 4 { c4 } + \repeat "percent" 4 { c4 } \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 } } @end lilypond @@ -3136,8 +3136,8 @@ the @internalsref{DrumVoices} are instantiated by hand first. For example, @lilypond[quote,raggedright,fragment,verbatim] \new DrumStaff << - \context DrumVoice = "1" { s1 *2 } - \context DrumVoice = "2" { s1 *2 } + \context DrumVoice = "1" { s1 *2 } + \context DrumVoice = "2" { s1 *2 } \drummode { bd4 sn4 bd4 sn4 << @@ -3186,7 +3186,7 @@ mus = \drummode { @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 +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}. @@ -3444,10 +3444,10 @@ usually the setup for a score will start with a setup of the staves, @example << \context Staff = up @{ - \skip 1 * 10 %@emph{ keep staff alive} + \skip 1 * 10 % @emph{keep staff alive} @} \context Staff = down @{ - \skip 1 * 10 %@emph{idem} + \skip 1 * 10 % @emph{idem} @} >> @end example @@ -3855,7 +3855,7 @@ Examples: @inputfileref{input/@/test,lyric@/-hyphen@/-retain@/.ly}. @node The Lyrics context -@subsection The Lyrics context +@subsection The Lyrics context Lyrics are printed by interpreting them in a @internalsref{Lyrics} context @@ -3904,7 +3904,7 @@ and then combine the appropriate melodies and lyric lines The final input would resemble @example -<<\context ChoirStaff << @emph{setup the music} >> +<<\context ChoirStaff << @emph{setup the music} >> \lyricsto "soprano" @emph{etc} \lyricsto "alto" @emph{etc} @emph{etc} @@ -4102,7 +4102,7 @@ done by setting the @code{associatedVoice} property. In the example % one syllable too soon! \set associatedVoice = alternative % applies to "ran" Ty -- - ran -- + ran -- no -- \set associatedVoice = lahlah % applies to "rus" sau -- rus Rex @@ -4284,7 +4284,7 @@ Program reference: @internalsref{Ambitus}, @internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead}, @internalsref{AmbitusAccidental}. -Examples: @inputfileref{input/@/regression,ambitus@/.ly}. +Examples: @inputfileref{input/@/regression,ambitus@/.ly}. @refbugs @@ -4301,7 +4301,7 @@ include extra information for other instruments in the future. * Harmonic notes:: @end menu -@node Harmonic notes, , Other instrument specific notation, Other instrument specific notation +@node Harmonic notes, , Other instrument specific notation, Other instrument specific notation @subsection Harmonic notes @cindex artificial harmonics @@ -4337,7 +4337,7 @@ offers limited support for tablature. @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 +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 @@ -4364,7 +4364,7 @@ e16 fis gis a b4 e16 fis gis a b4 @end example @lilypond[quote,raggedright] -frag = { +frag = { \key e \major e16 fis gis a b4 \set TabStaff.minimumFret = #8 @@ -4388,7 +4388,7 @@ string selector may easily select the same string to two notes in a chord. -@node Non-guitar tablatures, , Tablatures basic, Tablatures +@node Non-guitar tablatures, , Tablatures basic, Tablatures @subsection Non-guitar tablatures @cindex Non-guitar tablatures @@ -4439,7 +4439,7 @@ This section discusses issues that arise when writing popular music. @cindex Chords LilyPond has support for printing chord names. Chords may be entered -in musical chord notation, i.e. @code{< .. >}, but they can also be +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 @@ -4492,7 +4492,7 @@ Other chords may be entered by suffixing a colon and introducing a modifier (which may include a number if desired) @c @lilypond[quote,fragment,verbatim] -\chordmode { e1:m e1:7 e1:m7 } +\chordmode { 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 @@ -4515,7 +4515,7 @@ the colon, and are separated by dots Chord steps can be altered by suffixing a @code{-} or @code{+} sign to the number @lilypond[quote,verbatim,fragment] -\chordmode { c:7+ c:5+.3- c:3-.5-.7- } +\chordmode { 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 @@ -4577,7 +4577,7 @@ as bass notes, can be specified by appending @cindex @code{/+} A bass note can be added instead of transposed out of the chord, -by using @code{/+}@var{pitch}. +by using @code{/+}@var{pitch}. @lilypond[quote,raggedright,fragment,verbatim] \chordmode { c1 c/+g c/+f } @@ -4614,7 +4614,7 @@ described above, or directly using @code{<} and @code{>} @lilypond[quote,verbatim,raggedright] harmonies = { - \chordmode {a1 b c} + \chordmode {a1 b c} } << \context ChordNames \harmonies @@ -4675,7 +4675,7 @@ The exceptions list should be encoded as @end example To get this information into @code{chordNameExceptions} takes a little -manoeuvring. The following code transforms @code{chExceptionMusic} +manoeuvring. The following code transforms @code{chExceptionMusic} (which is a sequential music) into a list of exceptions. @example (sequential-music-to-chord-exceptions chExceptionMusic #t) @@ -4724,7 +4724,7 @@ B-chord) can be produced by storing a new function in this property. @cindex @code{chordNoteNamer} @item chordNoteNamer -The default is to print single pitch, e.g. the bass note, using the +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. @@ -4783,7 +4783,7 @@ may result in strange chord names when chords are entered with the @cindex fret diagrams @cindex chord diagrams -Fret diagrams can be added to music as a markup to the desired note. The +Fret diagrams can be added to music as a markup to the desired note. The markup contains information about the desired fret diagram, as shown in the following example @@ -4800,7 +4800,7 @@ following example } } fis' fis' fis' - c' ^\markup \override #'(dot-radius . 0.35) { + c' ^\markup \override #'(dot-radius . 0.35) { \override #'(finger-code . in-dot) { \override #'(dot-color . white) { \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);" @@ -4837,7 +4837,7 @@ following command @example \set squashedPosition = #0 -\override NoteHead #'style = #'slash +\override NoteHead #'style = #'slash @end example @noindent @@ -4863,7 +4863,7 @@ the following example @node Orchestral music @section Orchestral music -@cindex Writing parts +@cindex Writing parts Orchestral music involves some special notation, both in the full score and the individual parts. This section explains how to tackle @@ -4888,7 +4888,7 @@ some common problems in orchestral music. @end menu @node System start delimiters -@subsection System start delimiters +@subsection System start delimiters Polyphonic scores consist of many staves. These staves can be constructed in three different ways @@ -4960,7 +4960,7 @@ long as the piece. The use of @code{mmrest-of-length} is demonstrated in the following example. @lilypond[verbatim,raggedright,quote] -cadenza = \relative c' { +cadenza = \relative c' { c4 d8 << { e f g } \\ { d4. } >> g4 f2 g4 g } @@ -4995,8 +4995,8 @@ c1 \mark \default @end lilypond @noindent -(The letter I is skipped in accordance with engraving traditions.) -@c umm, is the manual the right place for feature requests? :) -gp +(The letter@tie{}`I' is skipped in accordance with engraving traditions.) +@c umm, is the manual the right place for feature requests? :) -gp @c FIXME - should make that tunable. The mark is incremented automatically if you use @code{\mark @@ -5174,7 +5174,7 @@ 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 +For example, consider a piece written in the key of D@tie{}major. If this piece is a little too low for its performer, it can be transposed up to E major with @example @@ -5227,7 +5227,7 @@ E-flat), horn (F) and trumpet (B-flat, C, D and E-flat). The transposition is entered after the keyword @code{\transposition} @example -\transposition bes %% B-flat clarinet +\transposition bes %% B-flat clarinet @end example @noindent @@ -5236,7 +5236,7 @@ this property is used for MIDI output and quotations. It does not affect how notes are printed in the current staff. The pitch to use for @code{\transposition} should correspond to the -transposition of the notes. For example, when entering a score in +transposition of the notes. For example, when entering a score in concert pitch, typically all voices are entered in C, so they should be entered as @@ -5245,7 +5245,7 @@ clarinet = @{ \transposition c' ... @} -saxophone = @{ +saxophone = @{ \transposition c' ... @} @@ -5254,7 +5254,7 @@ saxophone = @{ The command @code{\transposition} should be used when the music is entered from a (transposed) orchestral part. For example, in classical horn parts, the tuning of the instrument is often changed -during a piece. When copying the notes from the part, use +during a piece. When copying the notes from the part, use @code{\transposition}, e.g. @example @@ -5288,7 +5288,7 @@ be expanded, and the appropriate number is added automatically @lilypond[quote,raggedright,fragment,verbatim] \time 4/4 r1 | R1 | R1*2 -\set Score.skipBars = ##t R1*17 R1*4 +\set Score.skipBars = ##t R1*17 R1*4 @end lilypond The @code{1} in @code{R1} is similar to the duration notation used for @@ -5361,7 +5361,7 @@ specified texts. @refbugs -It is not possible to use fingerings (e.g. @code{R1-4}) to put numbers +It is not possible to use fingerings (e.g., @code{R1-4}) to put numbers over multi-measure rests. @cindex condensing rests @@ -5503,7 +5503,7 @@ The first system shows all staves in full. If empty staves should be removed from the first system too, set @code{remove-first} to false in @internalsref{RemoveEmptyVerticalGroup}. -Another application is making ossia sections, i.e. alternative +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. @@ -5638,7 +5638,7 @@ instruments, if they are specified using the @code{\transposition} command. @end lilypond The type of events that are present in cue notes can be trimmed with -the @code{quotedEventTypes} property. The default value is +the @code{quotedEventTypes} property. The default value is @code{(note-event rest-event)}, which means that only notes of and rests of the cued voice end up in the @code{\quote}. Setting @@ -5682,9 +5682,9 @@ Here is an example of formatted cue notes @lilypond[raggedright,verbatim] smaller = { \set fontSize = #-2 - \override Stem #'length = #5.5 - \override Beam #'thickness = #0.384 - \override Beam #'space-function = + \override Stem #'length = #5.5 + \override Beam #'thickness = #0.384 + \override Beam #'space-function = #(lambda (beam mult) (* 0.8 (Beam::space_function beam mult))) } @@ -5693,14 +5693,14 @@ smaller = { \set Score.skipBars = ##t R1*21 << { - \once \override Staff.MultiMeasureRest #'staff-position = #-6 + \once \override Staff.MultiMeasureRest #'staff-position = #-6 R1 } \new Voice { s2 \clef tenor \smaller - r8^"Bsn." c'8 f'8[ f'8] + r8^"Bsn." c'8 f'8[ f'8] \clef treble } >> @@ -5724,11 +5724,11 @@ clef should be restored after the cue section. This minimizes confusion for the reader, @item When the original part starts, this should be marked with the name of -the instrument, in this case ``Horn.'' Of course, the cue part is +the instrument, in this case ``Horn.'' Of course, the cue part is marked with the instrument playing the cue. @end itemize -@c really? Are you sure about that last point? I'll check after 3.0 -gp +@c really? Are you sure about that last point? I'll check after 3.0 -gp @node Ancient notation @@ -5843,7 +5843,7 @@ note heads. The @code{neomensural} 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 +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. @@ -5950,7 +5950,7 @@ ancient accidentals. Supported styles are @code{classical}, @code{neomensural} 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{neomensural} style suits -well for e.g. the incipit of a transcribed mensural piece of music. +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. @@ -6075,7 +6075,7 @@ Editio Vaticana style do clef @code{vaticana-do3} @tab @lilypond[fragment,relative=1,notime] - \override Staff.StaffSymbol #'line-count = #4 + \override Staff.StaffSymbol #'line-count = #4 \clef "vaticana-do2" c @end lilypond @@ -6085,7 +6085,7 @@ Editio Vaticana style fa clef @code{vaticana-fa1}, @code{vaticana-fa2} @tab @lilypond[fragment,relative=1,notime] - \override Staff.StaffSymbol #'line-count = #4 + \override Staff.StaffSymbol #'line-count = #4 \clef "vaticana-fa2" c @end lilypond @@ -6096,7 +6096,7 @@ Editio Medicaea style do clef @code{medicaea-do3} @tab @lilypond[fragment,relative=1,notime] - \override Staff.StaffSymbol #'line-count = #4 + \override Staff.StaffSymbol #'line-count = #4 \clef "medicaea-do2" c @end lilypond @@ -6106,7 +6106,7 @@ Editio Medicaea style fa clef @code{medicaea-fa1}, @code{medicaea-fa2} @tab @lilypond[fragment,relative=1,notime] - \override Staff.StaffSymbol #'line-count = #4 + \override Staff.StaffSymbol #'line-count = #4 \clef "medicaea-fa2" c @end lilypond @@ -6117,7 +6117,7 @@ historic style hufnagel do clef @code{hufnagel-do3} @tab @lilypond[fragment,relative=1,notime] - \override Staff.StaffSymbol #'line-count = #4 + \override Staff.StaffSymbol #'line-count = #4 \clef "hufnagel-do2" c @end lilypond @@ -6127,7 +6127,7 @@ historic style hufnagel fa clef @code{hufnagel-fa1}, @code{hufnagel-fa2} @tab @lilypond[fragment,relative=1,notime] - \override Staff.StaffSymbol #'line-count = #4 + \override Staff.StaffSymbol #'line-count = #4 \clef "hufnagel-fa2" c @end lilypond @@ -6563,7 +6563,7 @@ For example, \set Score.timing = ##f \set Score.defaultBarType = "empty" \override NoteHead #'style = #'neomensural -\override Staff.TimeSignature #'style = #'neomensural +\override Staff.TimeSignature #'style = #'neomensural \clef "petrucci-g" \[ g\longa c\breve a\breve f\breve d'\longa \] s4 @@ -6575,7 +6575,7 @@ s4 \set Score.timing = ##f \set Score.defaultBarType = "empty" \override NoteHead #'style = #'neomensural - \override Staff.TimeSignature #'style = #'neomensural + \override Staff.TimeSignature #'style = #'neomensural \clef "petrucci-g" \[ g\longa c\breve a\breve f\breve d'\longa \] s4 @@ -6600,7 +6600,7 @@ to the following \set Score.timing = ##f \set Score.defaultBarType = "empty" \override NoteHead #'style = #'neomensural - \override Staff.TimeSignature #'style = #'neomensural + \override Staff.TimeSignature #'style = #'neomensural \clef "petrucci-g" \[ g\longa c\breve a\breve f\breve d'\longa \] s4 @@ -7601,7 +7601,7 @@ LilyPond has limited support for figured bass @lilypond[quote,raggedright,verbatim,fragment] << - \context Voice { \clef bass dis4 c d ais } + \context Voice { \clef bass dis4 c d ais } \context FiguredBass \figuremode { < 6 >4 < 7 >8 < 6+ [_!] > < 6 >4 <6 5 [3+] > @@ -7624,7 +7624,7 @@ In figures input mode, a group of bass figures is delimited by \figuremode { <4 6> } @end lilypond -Accidentals are added when you append @code{-}, @code{!} and @code{+} +Accidentals are added when you append @code{-}, @code{!} and @code{+} to the numbers @example @@ -7695,7 +7695,7 @@ created with a markup text. This markup text is inserted in the @lilypond[verbatim,raggedright] % create 2/4 + 5/8 -tsMarkup =\markup { +tsMarkup =\markup { \number { \column < "2" "4" > \musicglyph #"scripts-stopped" @@ -7747,7 +7747,7 @@ Now, each staff has its own time signature. \context{ \Staff \consists "Timing_engraver" } } -\relative c' << +\relative c' << \new Staff { \time 3/4 c4 c c | c c c | @@ -7797,7 +7797,7 @@ multiplied by 3/5, so that 3/5 * 10/8 = 3/4. \set Staff.timeSignatureFraction = #'(10 . 8) \compressmusic #'(3 . 5) { \repeat unfold 2 { c8[ c c] } - \repeat unfold 2 { c8[ c] } + \repeat unfold 2 { c8[ c] } | c4. c4. \times 2/3 { c8 c c } c4 } } @@ -7864,7 +7864,7 @@ of differing lengths. The following fermatas are supported @lilypond[quote,raggedright] << - \oldaddlyrics { + \oldaddlyrics { b'2 ^\shortfermata _\shortfermata @@ -7887,7 +7887,7 @@ of differing lengths. The following fermatas are supported } \context Lyrics \lyricmode { \override LyricText #'font-family = #'typewriter - "shortfermata" "fermata" "longfermata" "verylongfermata" + "shortfermata" "fermata" "longfermata" "verylongfermata" } >> @end lilypond @@ -7901,7 +7901,7 @@ such as fermatas to notes. Feathered beams are not supported natively, but they can be faked by forcing two beams to overlap. Here is an example, -@c don't change relative setting witout changing positions! +@c don't change relative setting witout changing positions! @lilypond[raggedright,relative=1,fragment,verbatim] \new Staff << \new Voice @@ -7976,7 +7976,7 @@ removing @code{Bar_number_engraver}. @lilypond[quote,verbatim] -emptymusic = { +emptymusic = { \repeat unfold 2 % Change this for more lines. { s1\break } \bar "|." diff --git a/Documentation/user/point-and-click.itely b/Documentation/user/point-and-click.itely index 0275dc00b8..e6872bbce8 100644 --- a/Documentation/user/point-and-click.itely +++ b/Documentation/user/point-and-click.itely @@ -6,10 +6,11 @@ @cindex specials, source Point and click lets you find notes in the input by clicking on them in -the Xdvi window. This makes it easier to find input that causes some +the Xdvi window. This makes it easier to find input that causes some error in the sheet music. To use it, you need the following software: + @itemize @bullet @item a dvi viewer that supports src specials. @@ -23,8 +24,8 @@ It is available from @uref{ftp://@/ftp@/.math@/.berkeley@/.edu/@/pub/@/Software/@/TeX/@/xdvi@/.tar@/.gz, ftp@/.math@/.berkeley@/.edu}. - Most @TeX{} distributions ship with xdvik, which is always a few -versions behind the official Xdvi. To find out which Xdvi you are +Most @TeX{} distributions ship with @command{xdvik}, which is always a few +versions behind the official Xdvi. To find out which Xdvi you are running, try @code{xdvi -version} or @code{xdvi.bin -version}. @item an editor with a client/@/server interface (or a lightweight GUI @@ -33,8 +34,9 @@ editor): @cindex editor -@itemize @bullet -@item Emacs. Emacs is an extensible text-editor. It is available from +@itemize @minus +@item +Emacs. Emacs is an extensible text editor. It is available from @uref{http://@/www@/.gnu@/.org/@/software/@/emacs/}. You need version 21 to use column location. @@ -46,24 +48,28 @@ to use column location. @cindex lilypond-mode for Emacs @cindex syntax coloring -@item XEmacs. XEmacs is very similar to Emacs. +@item +XEmacs. XEmacs is very similar to Emacs. @cindex XEmacs -@item NEdit. NEdit runs under Windows, and Unix. +@item +NEdit. NEdit runs under Windows and Unix. It is available from @uref{http://@/www@/.nedit@/.org}. @cindex NEdit -@item GVim. GVim is a GUI variant of VIM, the popular VI +@item +GVim. GVim is a GUI variant of VIM, the popular VI clone. It is available from @uref{http://@/www@/.vim@/.org}. @cindex GVim @cindex Vim -@item jEdit. jEdit is an editor written in Java with extensive plug-in -support. The LilyPond plugin for jEdit comes with an DVI +@item +jEdit. jEdit is an editor written in Java with extensive plug-in +support. The LilyPond plugin for jEdit comes with an DVI viewer, which is preconfigured for point-and-click. @cindex jEdit @@ -73,25 +79,26 @@ viewer, which is preconfigured for point-and-click. Xdvi must be configured to find the @TeX{} fonts and music -fonts. Refer to the Xdvi documentation for more information. +fonts. Refer to the Xdvi documentation for more information. -To use point-and-click, add one of these lines to the top of your .ly +To use point-and-click, add one of these lines to the top of your @file{.ly} file: + @example #(ly:set-point-and-click 'line) @end example @cindex line-location -When viewing, Control-Mousebutton 1 will take you to the originating -spot in the @file{.ly} file. Control-Mousebutton 2 will show all +When viewing, Control-Mousebutton@tie{}1 will take you to the originating +spot in the @file{.ly} file. Control-Mousebutton@tie{}2 will show all clickable boxes. If you correct large files with point-and-click, be sure to start -correcting at the end of the file. When you start at the top, and +correcting at the end of the file. When you start at the top, and insert one line, all following locations will be off by a line. @cindex Emacs -For using point-and-click with Emacs, add the following +For using point-and-click with Emacs, add the following In your Emacs startup file (usually @file{~/@/.emacs}): @example (server-start) @@ -102,8 +109,9 @@ Make sure that the environment variable @var{XEDITOR} is set to emacsclient --no-wait +%l %f @end example @cindex @var{XEDITOR} -If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in -your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}. +If you use XEmacs instead of Emacs, insert @code{(gnuserve-start)} in +your @file{.emacs} file, and set @code{XEDITOR} to +@code{gnuclient -q +%l %f}. For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or use this argument with Xdvi's @code{-editor} option. @@ -113,14 +121,14 @@ For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or use this argument with Xdvi's @code{-editor} option. If can also make your editor jump to the exact location of the note -you clicked. This is only supported on Emacs and VIM. Users of Emacs version -20 must apply the patch @file{emacsclient.patch}. Users of version 21 +you clicked. This is only supported on Emacs and VIM. Users of Emacs version +20 must apply the patch @file{emacsclient.patch}. Users of version 21 must apply @file{server.el.patch} (version 21.2 and earlier). At the -top of the @code{ly} file, replace the @code{set-point-and-click} line +top of the @code{.ly} file, replace the @code{set-point-and-click} line with the following line: @example #(ly:set-point-and-click 'line-column) @end example @cindex line-column-location and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim -users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}. +users can set @code{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}. diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index fc91a4db3f..c54e1bb0fa 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -29,7 +29,7 @@ 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 = @{ c'4 d'4 @} +traLaLa = @{ c'4 d'4 @} @end example @noindent @@ -38,8 +38,8 @@ There is also a form of scoping: in the following example, the @code{\layout} block also contains a @code{traLaLa} variable, which is independent of the outer @code{\traLaLa}. @example - traLaLa = @{ c'4 d'4 @} - \layout @{ traLaLa = 1.0 @} +traLaLa = @{ c'4 d'4 @} +\layout @{ traLaLa = 1.0 @} @end example @c In effect, each input file is a scope, and all @code{\header}, @@ -47,43 +47,43 @@ In effect, each input file is a scope, and all @code{\header}, 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 +An anonymous Scheme module is attached to each scope. An assignment of the form @example - traLaLa = @{ c'4 d'4 @} +traLaLa = @{ c'4 d'4 @} @end example @noindent is internally converted to a Scheme definition @example - (define traLaLa @var{Scheme value of ``@code{... }''}) +(define traLaLa @var{Scheme value of ``@code{... }''}) @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 +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 = @{ c'4 d'4 @} +traLaLa = @{ c'4 d'4 @} - #(define newLa (map ly:music-deep-copy - (list traLaLa traLaLa))) - #(define twice - (make-sequential-music newLa)) +#(define newLa (map ly:music-deep-copy + (list traLaLa traLaLa))) +#(define twice + (make-sequential-music newLa)) - @{ \twice @} +@{ \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 +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{} - @{ #(ly:export (make-sequential-music newLa)) @} +@dots{} +@{ #(ly:export (make-sequential-music newLa)) @} @end example @refbugs @@ -95,31 +95,31 @@ Mixing Scheme and LilyPond identifiers is not possible with the @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 +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 +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 +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 +`type' or interface: Each music name has several `types' or interfaces, 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}. +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 +@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} +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 @@ -133,12 +133,12 @@ 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 +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, +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 stored in the @code{element} +@code{element}. The body of a repeat is stored in the @code{element} property of @internalsref{RepeatedMusic}, and the alternatives in @code{elements}. @@ -153,12 +153,12 @@ The syntax of composite music expressions, like follows the general form of @example - \@code{keyword} @var{non-music-arguments} @var{music-arguments} +\@code{keyword} @var{non-music-arguments} @var{music-arguments} @end example -Such syntax can also be defined as user code. To do this, it is -necessary to create a @emph{music function}. This is a specially marked -Scheme function. For example, the music function @code{\applymusic} applies +Such syntax can also be defined as user code. To do this, it is +necessary to create a @emph{music function}. This is a specially marked +Scheme function. For example, the music function @code{\applymusic} applies a user-defined function to a music expression. Its syntax is @example @@ -168,35 +168,35 @@ a user-defined function to a music expression. Its syntax is A music function is created with @code{ly:make-music-function}, @example - (ly:make-music-function +(ly:make-music-function @end example @code{\applymusic} takes a Scheme function and a Music expression as -argument. This is encoded in its first argument, +argument. This is encoded in its first argument, @example - (list procedure? ly:music?) +(list procedure? ly:music?) @end example The function itself takes another argument, an Input location -object. That object is used to provide error messages with file names +object. That object is used to provide error messages with file names and line numbers. The definition is the second argument of -@code{ly:make-music-function}. The body is function simply calls the +@code{ly:make-music-function}. The body is function simply calls the function @example - (lambda (where func music) - (func music)) +(lambda (where func music) + (func music)) @end example -The above Scheme code only defines the functionality. The tag +The above Scheme code only defines the functionality. The tag @code{\applymusic} is selected by defining @example - applymusic = #(ly:make-music-function - (list procedure? ly:music?) - (lambda (location func music) - (func music))) +applymusic = #(ly:make-music-function + (list procedure? ly:music?) + (lambda (location func music) + (func music))) @end example A @code{def-music-function} macro is introduced on top of @@ -204,9 +204,9 @@ A @code{def-music-function} macro is introduced on top of functions: @example - applymusic = #(def-music-function (location func music) - (procedure? ly:music?) - (func music)) +applymusic = #(def-music-function (location func music) + (procedure? ly:music?) + (func music)) @end example Examples of the use of @code{\applymusic} are in the next section. @@ -233,31 +233,32 @@ properties using the functions @code{ly:music-property} and 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) - \applymusic #rev-music-1 { c4 d4 } +@lilypond[quote,verbatim,raggedright] +#(define (rev-music-1 m) + (ly:music-set-property! m 'elements + (reverse (ly:music-property m 'elements))) + m) + +\applymusic #rev-music-1 { c'4 d'4 } @end lilypond -The use of such a function is very limited. The effect of this +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 - \applymusic #rev-music-1 \grace @{ c4 d4 @} +\applymusic #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 +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{\applymusic} 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} +back. Then it recurses, both on @code{elements} and @code{element} children. @example #(define (reverse-music music) @@ -279,17 +280,17 @@ 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 +functions. For example, the syntax for polyphony @example - <> +<> @end example @noindent -is actually implemented as a recursive function that replaces the +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 @} >> +<< \context Voice = "1" @{ \voiceOne a @} + \context Voice = "2" @{ \voiceTwo b @} >> @end example Other applications of @code{\applymusic} are writing out repeats @@ -301,8 +302,8 @@ exporting LilyPond input to other formats @cindex internal storage @cindex @code{\displayMusic} When writing a music function, it is often instructive to inspect how -a music expression is stored internally. This can be done with the -music function @code{\displayMusic} +a music expression is stored internally. This can be done with the +music function @code{\displayMusic}. @seealso @@ -316,105 +317,103 @@ music function @code{\displayMusic} @subsection Using LilyPond syntax inside Scheme Creating music expressions in Scheme can be tedious, as they are -heavily nested and the resulting Scheme code is large. For some +heavily nested and the resulting Scheme code is large. For some simple tasks, this can be avoided, using LilyPond usual syntax inside Scheme, with the dedicated @code{#@{ ... #@}} syntax. The following two expressions give equivalent music expressions: @example - mynotes = @{ \override Stem #'thickness = #4 - @{ c'8 d' @} @} +mynotes = @{ \override Stem #'thickness = #4 + @{ c'8 d' @} @} - #(define mynotes #@{ \override Stem #'thickness = #4 - @{ c'8 d' @} #@}) +#(define mynotes #@{ \override Stem #'thickness = #4 + @{ c'8 d' @} #@}) @end example The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{ -... @}} block, which is parsed. The resulting music expression, a +... @}} block, which is parsed. The resulting music expression, a @code{SequentialMusic} music object, is then returned and usable in Scheme. Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}} expressions with the @code{$} character (@code{$$} can be used to -produce a single $ character). This makes the creation of simple -functions straightforward. In the following example, a function +produce a single $ character). This makes the creation of simple +functions straightforward. In the following example, a function setting the TextScript's padding is defined: -@lilypond[verbatim,raggedright] - #(use-modules (ice-9 optargs)) - #(define* (textpad padding #:optional once?) - (ly:export ; this is necessary for using the expression - ; directly inside a block - (if once? - #{ \once \override TextScript #'padding = #$padding #} - #{ \override TextScript #'padding = #$padding #}))) - - { - c'^"1" - #(textpad 3.0 #t) % only once - c'^"2" - c'^"3" - #(textpad 5.0) - c'^"4" - c'^"5" - - } +@lilypond[quote,verbatim,raggedright] +#(use-modules (ice-9 optargs)) +#(define* (textpad padding #:optional once?) + (ly:export ; this is necessary for using the expression + ; directly inside a block + (if once? + #{ \once \override TextScript #'padding = #$padding #} + #{ \override TextScript #'padding = #$padding #}))) + + { + c'^"1" + #(textpad 3.0 #t) % only once + c'^"2" + c'^"3" + #(textpad 5.0) + c'^"4" + c'^"5" + } @end lilypond Here, the variable @code{padding} is a number; music expression variables may also be used in a similar fashion, as in the following example: -@lilypond[verbatim,raggedright] - #(define (with-padding padding) - (lambda (music) - #{ \override TextScript #'padding = #$padding - $music - \revert TextScript #'padding #})) - - { - c'^"1" - \applymusic #(with-padding 3) - { c'^"2" c'^"3"} - c'^"4" - } +@lilypond[quote,verbatim,raggedright] +#(define (with-padding padding) + (lambda (music) + #{ \override TextScript #'padding = #$padding + $music + \revert TextScript #'padding #})) + +{ + c'^"1" + \applymusic #(with-padding 3) { c'^"2" c'^"3" } + c'^"4" +} @end lilypond The function created by @code{(with-padding 3)} adds @code{\override} and @code{\revert} statements around the music given as an argument, and returns -this new expression. Thus, this example is equivalent to: +this new expression. Thus, this example is equivalent to: @example - @{ - c'^"1" - @{ \override TextScript #'padding = #3 - @{ c'^"2" c'^"3"@} - \revert TextScript #'padding - @} - c'^"4" - @} +@{ + c'^"1" + @{ \override TextScript #'padding = #3 + @{ c'^"2" c'^"3"@} + \revert TextScript #'padding + @} + c'^"4" +@} @end example This function may also be defined as a music function: -@lilypond[verbatim,raggedright] - withPadding = #(def-music-function (location padding music) (number? ly:music?) - #{ \override TextScript #'padding = #$padding - $music - \revert TextScript #'padding #}) - - { - c'^"1" - \withPadding #3 - { c'^"2" c'^"3"} - c'^"4" - } +@lilypond[quote,verbatim,raggedright] +withPadding = + #(def-music-function (location padding music) (number? ly:music?) + #{ \override TextScript #'padding = #$padding + $music + \revert TextScript #'padding #}) + +{ + c'^"1" + \withPadding #3 { c'^"2" c'^"3"} + c'^"4" +} @end lilypond @node Markup programmer interface @section Markup programmer interface -Markups implemented as special Scheme functions. When applied with as +Markups implemented as special Scheme functions. When applied with as arguments an output definition (@code{\layout} or @code{\paper}), and a list of properties and other arguments, produce a Stencil object. @@ -431,7 +430,7 @@ object. @cindex defining markup commands The @code{markup} macro builds markup expressions in Scheme while -providing a LilyPond-like syntax. For example, +providing a LilyPond-like syntax. For example, @example (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world") #:bigger #:line ("foo" "bar" "baz"))) @@ -448,7 +447,9 @@ is equivalent to: 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 + +@quotation +@multitable @columnfractions .3 .3 @item @b{LilyPond} @tab @b{Scheme} @item @code{\command} @tab @code{#:command} @item @code{\variable} @tab @code{variable} @@ -457,22 +458,26 @@ is this table: @item @code{string} @tab @code{"string"} @item @code{#scheme-arg} @tab @code{scheme-arg} @end multitable +@end quotation 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 +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. E.g.: +call. Example: + @lisp (markup #:line (fun-that-returns-markups)) @end lisp -is illegal. One should use the @code{make-line-markup} (resp + +@noindent +is invalid. One should use the @code{make-line-markup} (resp @code{make-center-markup}, @code{make-column-markup}) function instead, @lisp @@ -485,15 +490,15 @@ instead, In a markup like @example - \raise #0.5 "foo" +\raise #0.5 "foo" @end example @noindent @code{\raise} is actually represented by the @code{raise-markup} -function. The markup expression is stored as +function. The markup expression is stored as @example - (list raise-markup 0.5 (list simple-markup 'latin1 "foo")) +(list raise-markup 0.5 (list simple-markup 'latin1 "foo")) @end example @noindent @@ -504,15 +509,15 @@ When the markup is converted to printable objects (Stencils), the raise markup is called as @example - (apply raise-markup - @var{\layout object} - @var{list of property alists} - 0.5 - @var{the "foo" markup}) +(apply raise-markup + @var{\layout object} + @var{list of property alists} + 0.5 + @var{the "foo" markup}) @end example The @code{raise-markup} first creates the stencil for the @code{foo} -string, and then it raises that Stencil by 0.5 staff space. This is a +string, and then it raises that Stencil by 0.5 staff space. This is a rather simple example; more complex examples are in the rest of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}. @@ -520,7 +525,7 @@ section, and in @file{scm/@/define@/-markup@/-commands@/.scm}. @subsection Markup command definition New markup commands can be defined -with the @code{def-markup-command} scheme macro. +with the @code{def-markup-command} scheme macro. @lisp (def-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...) (@var{arg1-type?} @var{arg2-type?} ...) @@ -544,19 +549,19 @@ 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 +@example +\markup @{ \override #'(font-shape . caps) Text-in-caps @} +@end example 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 +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 layout props argument) (markup?) +(def-markup-command (smallcaps layout props argument) (markup?) @end example @noindent @@ -565,16 +570,16 @@ What follows is the content of the command: we should interpret the @code{argument} as a markup, i.e. @example - (interpret-markup layout @dots{} argument) +(interpret-markup layout @dots{} argument) @end example @noindent This interpretation should add @code{'(font-shape . caps)} to the active -properties, so we substitute the following for the @dots{} in the +properties, so we substitute the following for the @dots{} in the above example: @example - (cons (list '(font-shape . caps) ) props) +(cons (list '(font-shape . caps) ) props) @end example @noindent @@ -584,78 +589,78 @@ consing a list with the extra setting. 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 +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 +@example #(def-markup-command (character layout props name) (string?) - "Print the character name in small caps, translated to the left and - top. Syntax: \\character #\"name\"" - (interpret-markup layout props - (markup "" #:translate (cons -4 2) #:smallcaps name))) -@end verbatim + "Print the character name in small caps, translated to the left and + top. Syntax: \\character #\"name\"" + (interpret-markup layout props + (markup "" #:translate (cons -3 1) #:smallcaps name))) +@end example 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 +@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 +@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 - { \fatText - c''^\markup \character #"Cleopatra" - e'^\markup \character #"Giulio Cesare" - } -@end verbatim - -@lilypond[raggedright] +@example +@{ + c''^\markup \character #"Cleopatra" + e'^\markup \character #"Giulio Cesare" +@} +@end example + +@lilypond[quote,raggedright] #(def-markup-command (smallcaps layout props str) (string?) - "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" - (interpret-markup layout 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))))) + "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" + (interpret-markup layout 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 layout props name) (string?) - "Print the character name in small caps, translated to the left and - top. Syntax: \\character #\"name\"" - (interpret-markup layout props - (markup "" #:translate (cons -4 0) #:smallcaps name))) - - { \fatText - c''^\markup \character #"Cleopatra" - e'^\markup \character #"Giulio Cesare" - } + "Print the character name in small caps, translated to the left and + top. Syntax: \\character #\"name\"" + (interpret-markup layout props + (markup "" #:translate (cons -3 1) #:smallcaps name))) + +{ + c''^\markup \character #"Cleopatra" c'' c'' c'' + e'^\markup \character #"Giulio Cesare" e' e' e' +} @end lilypond We have used the @code{caps} font shape, but suppose that our font -that does not have a small-caps variant. In that case, we have to fake +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 layout props str) (string?) - "Print the string argument in small caps." - (interpret-markup layout 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))))) + "Print the string argument in small caps." + (interpret-markup layout 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 @@ -663,11 +668,11 @@ 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 +(@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, +translated to the left (@code{#:translate (cons -0.6 0) ...}). Then, the markups built for each token are put in a line by -@code{(make-line-markup ...)}. Finally, the resulting markup is passed +@code{(make-line-markup ...)}. Finally, the resulting markup is passed to the @code{interpret-markup} function, with the @code{layout} and @code{props} arguments. @@ -688,21 +693,21 @@ to the @code{interpret-markup} function, with the @code{layout} and @cindex calling code during interpreting @cindex @code{\applycontext} -Contexts can be modified during interpretation with Scheme code. The +Contexts can be modified during interpretation with Scheme code. The syntax for this is @example - \applycontext @var{function} +\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 +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))) +\applycontext + #(lambda (x) + (format #t "\nWe were called in barnumber ~a.\n" + (ly:context-property x 'currentBarNumber))) @end example @@ -715,7 +720,7 @@ current bar number on the standard output during the compile: @cindex @code{\applyoutput} -The most versatile way of tuning an object is @code{\applyoutput}. Its +The most versatile way of tuning an object is @code{\applyoutput}. Its syntax is @example \applyoutput @var{proc} @@ -744,10 +749,9 @@ 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)) - - (set! (ly:grob-property grob 'transparent) #t))) + (if (and (memq (ly:grob-property grob 'interfaces) + note-head-interface) + (eq? (ly:grob-property grob 'staff-position) 0)) + (set! (ly:grob-property grob 'transparent) #t))) @end example diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely index 2534ef2633..2248c57956 100644 --- a/Documentation/user/scheme-tutorial.itely +++ b/Documentation/user/scheme-tutorial.itely @@ -13,95 +13,100 @@ LilyPond uses the Scheme programming language, both as part of the input syntax, and as internal mechanism to glue together modules of -the program. This section is a very brief overview of entering data in +the program. This section is a very brief overview of entering data in Scheme.@footnote{If you want to know more about Scheme, see @uref{http://@/www@/.schemers@/.org}.} The most basic thing of a language is data: numbers, character -strings, lists, etc. Here is a list of data types that are relevant to +strings, lists, etc. Here is a list of data types that are relevant to LilyPond input. @table @asis @item Booleans - Boolean values are True or False. The Scheme for True is @code{#t} - and False is @code{#f}. +Boolean values are True or False. The Scheme for True is @code{#t} +and False is @code{#f}. @cindex @code{##t} @cindex @code{##f} + @item Numbers - Numbers are entered in the standard fashion, - @code{1} is the (integer) number one, while @code{-1.5} is a - floating point number (a non-integer number). +Numbers are entered in the standard fashion, +@code{1} is the (integer) number one, while @code{-1.5} is a +floating point number (a non-integer number). + @item Strings - Strings are enclosed in double quotes, - @example - "this is a string" - @end example - - Strings may span several lines - @example - "this - is - a string" - @end example - - Quotation marks and newlines can also be added with so-called escape - sequences. The string @code{a said "b"} is entered as - @example - "a said \"b\"" - @end example - - Newlines and backslashes are escaped with @code{\n} and @code{\\} +Strings are enclosed in double quotes, + +@example +"this is a string" +@end example + +Strings may span several lines + +@example +"this +is +a string" +@end example + +Quotation marks and newlines can also be added with so-called escape +sequences. The string @code{a said "b"} is entered as + +@example +"a said \"b\"" +@end example + +Newlines and backslashes are escaped with @code{\n} and @code{\\} respectively. @end table In a music file, snippets of Scheme code are introduced with the hash -mark @code{#}. So, the previous examples translated in LilyPond are +mark @code{#}. So, the previous examples translated in LilyPond are @example - ##t ##f - #1 #-1.5 - #"this is a string" - #"this - is - a string" +##t ##f +#1 #-1.5 +#"this is a string" +#"this +is +a string" @end example For the rest of this section, we will assume that the data is entered in a music file, so we add @code{#}s everywhere. -Scheme can be used to do calculations. It uses @emph{prefix} -syntax. Adding 1 and 2 is written as @code{(+ 1 2)} rather than the -traditional 1+2. +Scheme can be used to do calculations. It uses @emph{prefix} +syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the +traditional @math{1+2}. @lisp - #(+ 1 2) - @result{} #3 +#(+ 1 2) + @result{} #3 @end lisp The arrow @result{} shows that the result of evaluating @code{(+ 1 2)} -is @code{3}. Calculations may be nested; the result of a function may +is@tie{}@code{3}. Calculations may be nested; the result of a function may be used for another calculation. @lisp - #(+ 1 (* 3 4)) - @result{} #(+ 1 12) - @result{} #13 +#(+ 1 (* 3 4)) + @result{} #(+ 1 12) + @result{} #13 @end lisp These calculations are examples of evaluations; an expression like -@code{(* 3 4)} is replaced by its value @code{12}. A similar thing -happens with variables. After defining a variable +@code{(* 3 4)} is replaced by its value @code{12}. A similar thing +happens with variables. After defining a variable @example - twelve = #12 +twelve = #12 @end example @noindent variables can also be used in expressions, here @example - twentyFour = #(* 2 twelve) +twentyFour = #(* 2 twelve) @end example @noindent @@ -109,21 +114,21 @@ the number 24 is stored in the variable @code{twentyFour}. The same assignment can be done in completely in Scheme as well, @example - #(define twentyFour (* twelve)) +#(define twentyFour (* twelve)) @end example The @emph{name} of a variable is also an expression, similar to a -number or a string. It is entered as +number or a string. It is entered as @example - #'twentyFour +#'twentyFour @end example @cindex @code{#'symbol} @cindex quoting in Scheme The quote mark @code{'} prevents Scheme interpreter from substituting -@code{24} for the @code{twentyFour}. Instead, we get the name +@code{24} for the @code{twentyFour}. Instead, we get the name @code{twentyFour}. This syntax will be used very frequently, since many of the layout @@ -131,55 +136,56 @@ tweaks involve assigning (Scheme) values to internal variables, for example @example - \override Stem #'thickness = #2.6 +\override Stem #'thickness = #2.6 @end example -This instruction adjusts the appearance of stems. The value @code{2.6} +This instruction adjusts the appearance of stems. The value @code{2.6} is put into a the @code{thickness} variable of a @code{Stem} -object. This makes stems almost twice as thick as their normal size. +object. This makes stems almost twice as thick as their normal size. To distinguish between variables defined in input files (like @code{twentyFour} in the example above) and variables of internal objects, we will call the latter ``properties'' and the former -``identifiers.'' So, the stem object has a @code{thickness} property, +``identifiers.'' So, the stem object has a @code{thickness} property, while @code{twentyFour} is an identifier. @cindex properties vs. identifiers @cindex identifiers vs. properties Two-dimensional offsets (X and Y coordinates) as well as object sizes -(intervals with a left and right point) are entered as @code{pairs}. A +(intervals with a left and right point) are entered as @code{pairs}. A pair@footnote{In Scheme terminology, the pair is called @code{cons}, -and its two elements are called @code{car} and @code{cdr} respectively.} is entered -as @code{(first . second)} and, like symbols, they must be quoted, +and its two elements are called @code{car} and @code{cdr} respectively.} +is entered as @code{(first . second)} and, like symbols, they must be quoted, @example - \override TextScript #'extra-offset = #'(1 . 2) +\override TextScript #'extra-offset = #'(1 . 2) @end example This assigns the pair (1, 2) to the @code{extra-offset} property of the -TextScript object. This moves the object 1 staff space to the right, +TextScript object. This moves the object 1 staff space to the right, and 2 spaces up. The two elements of a pair may be arbitrary values, for example @example - #'(1 . 2) - #'(#t . #f) - #'("blah-blah" . 3.14159265) +#'(1 . 2) +#'(#t . #f) +#'("blah-blah" . 3.14159265) @end example A list is entered by enclosing its elements in parentheses, and adding -a quote. For example, +a quote. For example, + @example - #'(1 2 3) - #'(1 2 "string" #f) +#'(1 2 3) +#'(1 2 "string" #f) @end example We have been using lists all along. A calculation, like @code{(+ 1 2)} is also a list (containing the symbol @code{+} and the numbers 1 -and 2). Normally lists are interpreted as calculations, and the Scheme -interpreter substitutes the outcome of the calculation. To enter a -list, we stop evaluation. This is done by quoting the list with a +and@tie{}2). Normally lists are interpreted as calculations, and the +Scheme interpreter substitutes the outcome of the calculation. To enter a +list, we stop evaluation. This is done by quoting the list with a quote @code{'} symbol. So, for calculations do not use a quote. Inside a quoted list or pair, there is no need to quote anymore. The @@ -187,8 +193,7 @@ following is a pair of symbols, a list of symbols and a list of lists respectively, @example - #'(stem . head) - #'(staff clef key-signature) - #'((1) (2)) +#'(stem . head) +#'(staff clef key-signature) +#'((1) (2)) @end example - diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 5285d6baa8..929e30b509 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -484,7 +484,7 @@ down To use relative mode, add @code{\relative} before the piece of music. The first note is taken relative to the middle C @c no , for this sentence -(i.e. @code{c'}) +(i.e., @code{c'}) @@ -885,7 +885,7 @@ see @ref{Partial measures}. A comment is a remark for the human reader of the music input; it is ignored while parsing, so it has no effect on the printed output. There are two types of comments. The percent symbol @samp{%} -introduces a line comment; after @code{%} the rest of the line is +introduces a line comment; after @code{%} the rest of the line is ignored. A block comments marks a whole section of music input. Anything that is enclosed in @code{%@{} and @code{%@}} is ignored. The following fragment shows possible uses for comments @@ -1031,7 +1031,7 @@ following example shows a few common modifiers For lead sheets, chords are not printed on staves, but as names on a line of themselves. This is achieved by using @code{\chords} instead -of @code{\chordmode}. This uses the same syntax as @code{\chordmode}, +of @code{\chordmode}. This uses the same syntax as @code{\chordmode}, but renders the notes in a @code{ChordNames} context, with the following result. @@ -1247,7 +1247,7 @@ suppose that the file @file{horn-music.ly} contains the following part of a horn/@/bassoon duo @example -hornNotes = \relative c @{ +hornNotes = \relative c @{ \time 2/4 r4 f8 a cis4 f e d @} -- 2.39.5