structure cleanup.
+2004-11-04 Werner Lemberg <wl@gnu.org>
+
+ * Documentation/user/*: A new round of layout fixes and document
+ structure cleanup.
+
2004-11-04 Heikki Junes <hjunes@cc.hut.fi>
* Documentation/user/lilypond.tely: changes 2.3.x to 2.5.x.
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.
@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
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
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.
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
@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.
@cindex Context, creating
@example
- \new @var{type} @var{music expression}
+\new @var{type} @var{music expression}
@end example
@noindent
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
@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
The third command for creating contexts is
@example
- \context @var{type} @var{music}
+\context @var{type} @var{music}
@end example
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
@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
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
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
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}.
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
}
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.
@cindex polymetric scores
-@lilypond[relative=1,raggedright,verbatim,fragment]
+@lilypond[quote,relative=1,raggedright,verbatim,fragment]
\new Score \with {
\remove "Timing_engraver"
} <<
@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
Here
@example
- \Staff
+\Staff
@end example
@noindent
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
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
@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
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"
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
@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}.
@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
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
@cindex setting object properties
-@lilypond[fragment,relative=1,verbatim]
+@lilypond[quote,fragment,relative=1,verbatim]
\stemUp
f-5
\once \override Fingering
@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
@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
a command like
@example
- \override Voice.Stem #'thickness = #3.0
+\override Voice.Stem #'thickness = #3.0
@end example
@noindent
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
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
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
@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}}
@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.
@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
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
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
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
@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
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}
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)
(set! (ly:grob-property grob 'font-size) size))))
\relative {
- c
- \applyoutput #(set-position-font-size -2 4)
- <c e g>
+ c
+ \applyoutput #(set-position-font-size -2 4)
+ <c e g>
}
@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
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
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.
@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.
@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
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
@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
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
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
@seealso
-Init files: @file{scm/@/new@/-markup@/.scm}.
+Init files: @file{scm/@/new@/-markup@/.scm}.
@refbugs
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
@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 { }
-@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 @{ @}}.
@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.
@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)}
@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.
@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
@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
@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
@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.
@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).
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
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}
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
@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.
@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
@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
@example
\book @{
\score @{
- @var{..}
+ @var{..}
@}
\score @{
- @var{..}
+ @var{..}
@}
@}
@end example
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
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.
@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.
@cindex @code{\pageBreak}
@code{\pageBreak}
-@cindex @code{\noPageBreak}
+@cindex @code{\noPageBreak}
@code{\noPageBreak}
@node Paper size
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
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.
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
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.
@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}
@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.
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
@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..
@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
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
@appendix Cheat sheet
-@multitable @columnfractions .35 .3 .35
+@multitable @columnfractions .35 .3 .35
@item @b{Syntax}
@tab @b{Description}
@tab time signature
@tab
@lilypond[fragment]
-\override Staff.Clef #'transparent = ##t
+\override Staff.Clef #'transparent = ##t
\time 3/4
s4_" "
\time 4/4
\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
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.
@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
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
@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
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,
@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
@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
@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
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
Similarly,
@example
- %%LY slyrics more words
+%%LY slyrics more words
@end example
will cause the text following the ``slyrics'' keyword to be inserted
@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
@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
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::
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
@lilypond[quote,verbatim,raggedright]
\version "2.3.22"
-melody = \relative c' {
+melody = \relative c' {
\clef treble
\key c \major
\time 4/4
>>
\layout{ }
- \midi { \tempo 4=60}
+ \midi { \tempo 4=60}
}
@end lilypond
@lilypond[quote,verbatim,raggedright]
\version "2.3.22"
-melody = \relative c' {
+melody = \relative c' {
\clef treble
\key c \major
\time 4/4
@lilypond[quote,verbatim,raggedright]
\version "2.3.22"
-melody = \relative c'' {
+melody = \relative c'' {
\clef treble
\key c \major
\time 4/4
a2 c
}
-dynamics = {
+dynamics = {
s2\fff\> s4
s\!\pp
}
-pedal = {
+pedal = {
s2\sustainDown s2\sustainUp
}
@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
\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
% ############ Horns ############
% ------ Trumpet ------
-trpt = \transpose c d \relative c'' {
+trpt = \transpose c d \relative c'' {
\Key
c1 c c
}
}
% ------ Trombone ------
-tbone = \relative c {
+tbone = \relative c {
\Key
c1 c c
}
% ############ Rhythm Section #############
% ------ Guitar ------
-gtr = \relative c'' {
+gtr = \relative c'' {
\Key
c1 \sl b4 b b b \nsl c1
}
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
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
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 } }
\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
\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.
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
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
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
@code{@{@tie{}@dots{}@tie{}@}}
@example
-@{ f4 <<c4 d4 e4>> @}
+@{ f4 <<c4 d4 e4>> @}
@end example
@lilypond[quote,relative=1,fragment]
@lilypond[quote,fragment,relative=2]
\new Voice { << g2 \\ { f4 <<c d e>> } >> }
@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
@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
@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::
@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
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}
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}
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' {
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
@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@}
\end@{lilypond@}
@end example
+@noindent
+or
+
@example
\lilypondfile[options,go,here]@{@var{filename}@}
@end example
\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
@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]@{<c' e' g'>@}
+\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
@end example
@noindent
produces
-@lilypond[fragment,staffsize=11]{<c' e' g'>}
+@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
-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
@@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
c' d' e' f' g'2 g'
@end lilypond
-Then the short version:
+The short version
@example
-@@lilypond[staffsize=11]@{<c' e' g'>@}
+@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
@end example
@noindent
produces
-@lilypond[fragment,staffsize=11]{ <c' e' g'> }
-
-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]{<c' e' g'>}
+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
Music is entered using
@example
-<lilypond relative=2 verbatim>
- \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+<lilypond fragment relative=2>
+ \key c \minor c4 es g2
</lilypond>
@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
-<lilypond relative=2 verbatim>
- \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
-</lilypond>
-@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{<lilypond ... />} syntax, e.g.
+For inline pictures, use @code{<lilypond ... />} syntax, where the options
+are separated by a colon from the music, for example
+
@example
-Some music in <lilypond a b c/> a line of text.
+Some music in <lilypond relative=2: a b c/> 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{<lilypondfile>} tag, for example,
@example
@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
\end@{lilypond@}
@end example
-
@item noindent
sets indentation of the first music system to zero. This option
affects LilyPond, not the text layout.
@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
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
@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}}
@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
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
@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
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
@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
* 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::
@macro seeinternals{NAME}
-internals document, @internalsref{\NAME\}
+internals document, @internalsref{\NAME\}
@end macro
@end iftex
@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
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
@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
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
\key d \major
\time 4/4
-%\override Score.TextScript #'font-style = #'large
+%\override Score.TextScript #'font-style = #'large
<d a fis>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
}
\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 "||"
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.
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}.
@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
@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
@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
\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
@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'' {
<g b d>1 s s
@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
% \override Staff.Custos #'neutral-position = #4
\override Staff.Custos #'neutral-direction = #-1
\override Staff.Custos #'style = #'hufnagel
- c'1 \break
+ c'1 \break
<d' a' f''>1
}
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 |
@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
@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 {
@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 {
@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 {
@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 {
@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
@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 {
@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 {
@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 {
@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 {
@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
}
@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 <des g,!> s s <cis g!> 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
@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
f1
}
\context Lyrics \lyrics {
-% \override Lyrics .LyricText #'self-alignment-X = #-1
+% \override Lyrics .LyricText #'self-alignment-X = #-1
"baritone "
"bass "
"sub-bass "
@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
@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'' {
@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
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 "
\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
@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'' {
<g g>1_"unisone " s
<g b>_"third " s
@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'' {
<g a>1_"second " s s
<g f'>_"seventh " s s
<g a'>_"ninth" s s
@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
@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 "
@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 "
@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 "||"
}
c4-. d-. e-. \bar "||"
}
\context Lyrics \lyrics {
-% \override Lyrics .LyricText #'font-style = #'large
+% \override Lyrics .LyricText #'font-style = #'large
a
b "" ""
c
@lilypond[fragment,notime,raggedright]
\set Score.automaticBars = ##f
\relative c'' {
- \override NoteHead #'style = #'mensural
+ \override NoteHead #'style = #'mensural
g\longa
}
@end lilypond
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}.
@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
@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
@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"
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 "||"
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 "||"
@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 "||"
}
}
@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 "||"
}
\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
}
>>
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
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
@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
@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 "||"
@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' {
}
\context Lyrics \lyrics {
<< { I II III IV V VI VII I }
- { T "" "" S D } >>
+ { T "" "" S D } >>
}
@end lilypond
@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
\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
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
@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
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,
@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
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]
@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 {
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
@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
@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.
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.,
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
@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,
@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]
@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
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}
@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
for example
@lilypond[quote,raggedright,fragment,verbatim]
-\context Voice << c''4 \\ r4 >>
+\context Voice << c''4 \\ r4 >>
@end lilypond
<d g>
} \\ {
<b f'>
- \once \override NoteColumn #'force-hshift = #1.7
+ \once \override NoteColumn #'force-hshift = #1.7
<b f'>
} >>
@end lilypond
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
@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
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.
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.
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
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
@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
\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
-@node Running trills
+@node Running trills
@subsection Running trills
Long running trills are made with @code{\startTrillSpan} and
@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]
<a_\thumb a'-3>8 <b_\thumb b'-3>
@lilypond[quote,raggedright]
<<
\relative c''{
- c4 \grace c16 c4 \grace {
+ c4 \grace c16 c4 \grace {
c16[ d16] } c2 c4
}
\new Lyrics \lyricmode {
\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
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
\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 } }
}
@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
@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
<<
@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}.
@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
@node The Lyrics context
-@subsection The Lyrics context
+@subsection The Lyrics context
Lyrics are printed by interpreting them in a @internalsref{Lyrics} context
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}
% one syllable too soon!
\set associatedVoice = alternative % applies to "ran"
Ty --
- ran --
+ ran --
no --
\set associatedVoice = lahlah % applies to "rus"
sau -- rus Rex
@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
@internalsref{AmbitusAccidental}.
-Examples: @inputfileref{input/@/regression,ambitus@/.ly}.
+Examples: @inputfileref{input/@/regression,ambitus@/.ly}.
@refbugs
* 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
@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
e16 fis gis a b4
@end example
@lilypond[quote,raggedright]
-frag = {
+frag = {
\key e \major
e16 fis gis a b4
\set TabStaff.minimumFret = #8
chord.
-@node Non-guitar tablatures, , Tablatures basic, Tablatures
+@node Non-guitar tablatures, , Tablatures basic, Tablatures
@subsection Non-guitar tablatures
@cindex Non-guitar tablatures
@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
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
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
@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 }
@lilypond[quote,verbatim,raggedright]
harmonies = {
- \chordmode {a1 b c} <d' f' a'> <e' g' b'>
+ \chordmode {a1 b c} <d' f' a'> <e' g' b'>
}
<<
\context ChordNames \harmonies
@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)
@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.
@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
}
}
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-);"
@example
\set squashedPosition = #0
-\override NoteHead #'style = #'slash
+\override NoteHead #'style = #'slash
@end example
@noindent
@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
@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
in the following example.
@lilypond[verbatim,raggedright,quote]
-cadenza = \relative c' {
+cadenza = \relative c' {
c4 d8 << { e f g } \\ { d4. } >>
g4 f2 g4 g
}
@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
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
The transposition is entered after the keyword @code{\transposition}
@example
-\transposition bes %% B-flat clarinet
+\transposition bes %% B-flat clarinet
@end example
@noindent
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
\transposition c'
...
@}
-saxophone = @{
+saxophone = @{
\transposition c'
...
@}
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
@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
@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
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.
@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
@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)))
}
\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
}
>>
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
@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.
@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.
@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
@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
@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
@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
@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
@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
\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
\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
\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
@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+] >
\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
@lilypond[verbatim,raggedright]
% create 2/4 + 5/8
-tsMarkup =\markup {
+tsMarkup =\markup {
\number {
\column < "2" "4" >
\musicglyph #"scripts-stopped"
\context{ \Staff \consists "Timing_engraver" }
}
-\relative c' <<
+\relative c' <<
\new Staff {
\time 3/4
c4 c c | c c c |
\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
}
}
@lilypond[quote,raggedright]
<<
- \oldaddlyrics {
+ \oldaddlyrics {
b'2
^\shortfermata
_\shortfermata
}
\context Lyrics \lyricmode {
\override LyricText #'font-family = #'typewriter
- "shortfermata" "fermata" "longfermata" "verylongfermata"
+ "shortfermata" "fermata" "longfermata" "verylongfermata"
}
>>
@end lilypond
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
@lilypond[quote,verbatim]
-emptymusic = {
+emptymusic = {
\repeat unfold 2 % Change this for more lines.
{ s1\break }
\bar "|."
@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.
@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
@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.
@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
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)
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.
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}.
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
@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},
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
@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
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}.
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
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
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.
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)
@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
+<<a \\ b>>
@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
@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
@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.
@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")))
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}
@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
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
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}.
@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?} ...)
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
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
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
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.
@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
@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}
@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
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
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
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
respectively,
@example
- #'(stem . head)
- #'(staff clef key-signature)
- #'((1) (2))
+#'(stem . head)
+#'(staff clef key-signature)
+#'((1) (2))
@end example
-
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'})
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
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.
of a horn/@/bassoon duo
@example
-hornNotes = \relative c @{
+hornNotes = \relative c @{
\time 2/4
r4 f8 a cis4 f e d
@}
projects / lilypond.git / commitdiff