+2006-05-07 Graham Percival <gpermus@gmail.com>
+
+ * Documentation/user/ all: backport everything from 2.9 docs.
+
+ * Documentation/user/ README.txt, working.itely, tweaks.itely:
+ new files, backported from 2.9.
+
2006-05-04 Graham Percival <gpermus@gmail.com>
* Documentation/user/baer-flat-bw.png: backport remove alpha
# todo: add latex.
DVI_FILES = $(TELY_FILES:%.tely=$(outdir)/%.dvi)
-EXTRA_DIST_FILES= $(LATEX_FILES) $(IMAGES)
+EXTRA_DIST_FILES= $(LATEX_FILES) $(IMAGES) README.txt
IMAGES=$(call src-wildcard,*.png)
OUT_EPS_IMAGES=$(IMAGES:%.png=$(outdir)/%.eps)
* The above three suggestions refer to the formal Notation Manual
(chapters 5 and up). In the Tutorial, Example templates, and
- Putting it all together, you may write more colloquially
+ Putting it all together, you may write more colloquially.
* The use of the word `illegal' is inappropriate in most cases. Say
`invalid' instead.
this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
all such characters appear in all output formats.
-%%%%%
-
-
+* Lines should be less than 80 characters long.
* Orchestral music::
* Contemporary notation::
* Educational use::
-* Automatic notation::
@end menu
@commonprop
-Checking to make sure that text scripts and lyrics are within the margins is a relatively large computational task. To speed up processing, lilypond does not perform such calculations by default; to enable it, use
+Checking to make sure that text scripts and lyrics are within the margins is
+a relatively large computational task. To speed up processing, lilypond does
+not perform such calculations by default; to enable it, use
@example
\override Score.PaperColumn #'keep-inside-line = ##t
@lilypond[quote,verbatim,fragment,relative=1]
c1^\markup { hello }
c1_\markup { hi there }
-c1^\markup { hi \bold there, is \italic anyone home? }
-c1_\markup { "\special #characters" }
+c1^\markup { hi \bold there, is \italic {anyone home?} }
+c1_\markup { "\special {weird} #characters" }
@end lilypond
@noindent
@end lilypond
The file @file{scm/@/translation@/-functions@/.scm} contains the definitions
-of @code{format-mark-numbers} (the default format), @code{format-mark-box-numbers},
+of @code{format-mark-numbers} (the default format),
+@code{format-mark-box-numbers},
@code{format-mark-letters} and @code{format-mark-box-letters}.
These can be used as inspiration for other formatting functions.
used to move the instrument names to the left, in such situations.
@example
-\override Score.InstrumentName #'space-alist = #'((left-edge extra-space . 2.0))
+\override Score.InstrumentName #'space-alist =
+ #'((left-edge extra-space . 2.0))
@end example
@c Yes, this is good practice. Otherwise, the start of the original
@c part can only be seen from the font size. This is not good enough
@c for sight-reading. It is possilbe to use other
-@c markers (e.g. a big close-bracket over the staff) to indicate the cue notes are
+@c markers (e.g. a big close-bracket over the staff) to indicate the cue
+@c notes are
@c finished.
@c -hwn
@noindent
As the example illustrates, @code{ly:make-moment n m} constructs a
-duration of n/m of a whole note. For example, @code{ly:make-moment 1 8} is an eighth
+duration of n/m of a whole note. For example, @code{ly:make-moment 1 8} is
+an eighth
note duration and @code{ly:make-moment 7 16} is the duration of
seven sixteenths notes.
* Easy Notation note heads::
* Analysis brackets::
* Coloring objects::
+* Parentheses::
@end menu
@node Balloon help
named normal color.
-@node Automatic notation
-@section Automatic notation
+@node Parentheses
+@subsection Parentheses
-This section describes how to change the way that accidentals and
-beams are automatically displayed.
+@cindex ghost notes
+@cindex notes, ghost
+@cindex notes, parenthesized
-FIXME: this might get moved into Changing Defaults. Please send
-opinions to lilypond-devel. Thanks! :)
+Objects may be parenthesized by prefixing @code{\parenthesize} to the music
+event,
-@menu
-* Automatic accidentals::
-* Setting automatic beam behavior::
-@end menu
-
-@node Automatic accidentals
-@subsection Automatic accidentals
-@cindex Automatic accidentals
-
-Common rules for typesetting accidentals have been placed in a
-function. This function is called as follows
-
-@cindex @code{set-accidental-style}
-@example
-#(set-accidental-style 'STYLE #('CONTEXT#))
-@end example
-
-The function can take two arguments: the name of the accidental style,
-and an optional argument that denotes the context that should be
-changed. If no context name is supplied, @code{Staff} is the default,
-but you may wish to apply the accidental style to a single @code{Voice}
-instead.
-
-The following accidental styles are supported
-@table @code
-@item default
-This is the default typesetting behavior. It corresponds
-to 18th century common practice: Accidentals are
-remembered to the end of the measure in which they occur and
-only on their own octave.
-
-@item voice
-The normal behavior is to remember the accidentals on
-Staff-level. This variable, however, typesets accidentals
-individually for each voice. Apart from that, the rule is similar to
-@code{default}.
-
-As a result, accidentals from one voice do not get canceled in other
-voices, which is often an unwanted result
-
-@lilypond[quote,ragged-right,relative=1,fragment,verbatim]
-\new Staff <<
- #(set-accidental-style 'voice)
- <<
- { es g } \\
- { c, e }
->> >>
-@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
-@code{modern} or @code{modern-cautionary}
-should be used instead.
-
-@item modern
-@cindex @code{modern} style accidentals
-This rule corresponds to the common practice in the 20th century. This rule
-prints the same accidentals as @code{default}, but temporary
-accidentals also are canceled in other octaves. Furthermore,
-in the same octave, they also get canceled in the following
-measure
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-#(set-accidental-style 'modern)
-cis' c'' cis'2 | c'' c'
-@end lilypond
-
-@item @code{modern-cautionary}
-@cindex @code{modern-cautionary}
-This rule is similar to @code{modern}, but the ``extra'' accidentals
-(the ones not typeset by @code{default}) are typeset as cautionary
-accidentals. They are printed in reduced size or with parentheses
-@lilypond[quote,ragged-right,fragment,verbatim]
-#(set-accidental-style 'modern-cautionary)
-cis' c'' cis'2 | c'' c'
-@end lilypond
-
-@cindex @code{modern-voice}
-@item modern-voice
-This rule is used for multivoice accidentals to be read both by musicians
-playing one voice and musicians playing all voices. Accidentals are
-typeset for each voice, but they @emph{are} canceled across voices in
-the same @internalsref{Staff}.
-
-@cindex @code{modern-voice-cautionary}
-@item modern-voice-cautionary
-This rule is the same as @code{modern-voice}, but with the extra
-accidentals (the ones not typeset by @code{voice}) typeset
-as cautionaries. Even though all accidentals typeset by
-@code{default} @emph{are} typeset by this variable,
-some of them are typeset as cautionaries.
-
-@item piano
-@cindex @code{piano} accidentals
-This rule reflects 20th century practice for piano notation. Very similar to
-@code{modern} but accidentals also get canceled
-across the staves in the same @internalsref{GrandStaff} or
-@internalsref{PianoStaff}.
-
-@item piano-cautionary
-@cindex @code{#(set-accidental-style 'piano-cautionary)}
-Same as @code{#(set-accidental-style 'piano)} but with the extra
-accidentals typeset as cautionaries.
-
-@item no-reset
-@cindex @code{no-reset} accidental style
-This is the same as @code{default} but with accidentals lasting
-``forever'' and not only until the next measure
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-#(set-accidental-style 'no-reset)
-c1 cis cis c
-@end lilypond
-
-@item forget
-This is sort of the opposite of @code{no-reset}: Accidentals
-are not remembered at all---and hence all accidentals are
-typeset relative to the key signature, regardless of what was
-before in the music
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-#(set-accidental-style 'forget)
-\key d\major c4 c cis cis d d dis dis
-@end lilypond
-@end table
-
-
-@seealso
-
-Program reference: @internalsref{Accidental_engraver},
-@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
-
-
-@refbugs
-
-Simultaneous notes are considered to be entered in sequential
-mode. This means that in a chord the accidentals are typeset as if the
-notes in the chord happened once at a time - in the order in which
-they appear in the input file.
-
-This is 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
-problematic notes.
-
-
-@node Setting automatic beam behavior
-@subsection Setting automatic beam behavior
-
-@cindex @code{autoBeamSettings}
-@cindex @code{(end * * * *)}
-@cindex @code{(begin * * * *)}
-@cindex automatic beams, tuning
-@cindex tuning automatic beaming
-
-@c [TODO: use \applyContext]
-
-In normal time signatures, automatic beams can start on any note but can
-only end in a few positions within the measure: beams can end on a beat,
-or at durations specified by the properties in
-@code{autoBeamSettings}. The properties in @code{autoBeamSettings}
-consist of a list of rules for where beams can begin and end. The
-default @code{autoBeamSettings} rules are defined in
-@file{scm/@/auto@/-beam@/.scm}.
-
-In order to add a rule to the list, use
-@example
-#(override-auto-beam-setting '(be p q n m) a b [context])
-@end example
-
-@itemize @bullet
-
-@item @code{be} is either "begin" or "end".
-
-@item @code{p/q} is the duration of the note for which you want
-to add a rule. A beam is considered to have the duration of its
-shortest note. Set @code{p} and @code{q} to @code{'*'} to
-have this apply to any beam.
-
-@item @code{n/m} is the time signature to which
-this rule should apply. Set @code{n} and @code{m} to @code{'*'}
-to have this apply in any time signature.
-
-@item @code{a/b} is the position in the bar at which the beam should begin/end.
-
-@item @code{context} is optional, and it specifies the context at which
-the change should be made. The default is @code{'Voice}.
-@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to
-@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.
-
-@end itemize
-
-For example, if automatic beams should always end on the first quarter
-note, use
-
-@example
-#(override-auto-beam-setting '(end * * * *) 1 4)
-@end example
-
-You can force the beam settings to only take effect on beams whose shortest
-note is a certain duration
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\time 2/4
-#(override-auto-beam-setting '(end 1 16 * *) 1 16)
-a16 a a a a a a a |
-a32 a a a a16 a a a a a |
-#(override-auto-beam-setting '(end 1 32 * *) 1 16)
-a32 a a a a16 a a a a a |
-@end lilypond
-
-You can force the beam settings to only take effect in certain time
-signatures
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\time 5/8
-#(override-auto-beam-setting '(end * * 5 8) 2 8)
-c8 c d d d
-\time 4/4
-e8 e f f e e d d
-\time 5/8
-c8 c d d d
-@end lilypond
-
-You can also remove a previously set beam-ending rule by using
-
-@example
-#(revert-auto-beam-setting '(be p q n m) a b [context])
-@end example
-
-@noindent
-be, p, q, n, m, a, b and context are the same as above. Note that the
-default rules are specified in @file{scm/@/auto@/-beam@/.scm},
-so you can revert rules that you did not explicitly create.
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\time 4/4
-a16 a a a a a a a a a a a a a a a
-#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
-a16 a a a a a a a a a a a a a a a
-@end lilypond
-
-The rule in a revert-auto-beam-setting statement must exactly match the
-original rule. That is, no wildcard expansion is taken into account.
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\time 1/4
-#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
-a16 a a a
-#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
-a a a a
-#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
-a a a a
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+<
+ c
+ \parenthesize d
+ g
+>4-\parenthesize -.
@end lilypond
-@c TODO: old material -- not covered by above stuff, I think.
-If automatic beams should end on every quarter in 5/4 time, specify
-all endings
-@example
-#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
-#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
-#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
-#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
-@dots{}
-@end example
-
-The same syntax can be used to specify beam starting points. In this
-example, automatic beams can only end on a dotted quarter note
-@example
-#(override-auto-beam-setting '(end * * * *) 3 8)
-#(override-auto-beam-setting '(end * * * *) 1 2)
-#(override-auto-beam-setting '(end * * * *) 7 8)
-@end example
-In 4/4 time signature, this means that automatic beams could end only on
-3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
-3/8, has passed within the measure).
-
-@cindex automatic beam generation
-@cindex autobeam
-@cindex @code{autoBeaming}
-@cindex lyrics
-
-If beams are used to indicate melismata in songs, then automatic
-beaming should be switched off with @code{\autoBeamOff}.
-
-
-@refcommands
-
-@cindex @code{\autoBeamOff}
-@code{\autoBeamOff},
-@cindex @code{\autoBeamOn}
-@code{\autoBeamOn}.
-
-
-@refbugs
-
-If a score ends while an automatic beam has not been ended and is
-still accepting notes, this last beam will not be typeset at all. The
-same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
->>}. If a polyphonic voice ends while an automatic beam is still
-accepting notes, it is not typeset.
-
-
-
@seealso
-Program reference: @internalsref{KeyCancellation}, @internalsref{KeySignature}.
+Program reference: @internalsref{KeyCancellation},
+@internalsref{KeySignature}.
@node Time signature
}
@end lilypond
+
@seealso
-Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_translator}.
+Program reference: @internalsref{TimeSignature}, and
+@internalsref{Timing_translator}.
+
+Examples: @inputfileref{input/@/test,compound@/-time@/.ly}.
@refbugs
Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
@inputfileref{input/@/test@/,ossia.ly},
-@inputfileref{input/@/test,staff@/-size@/.ly}.
+@inputfileref{input/@/test,staff@/-size@/.ly},
+@inputfileref{input/@/regression,staff@/-line@/-positions@/.ly}.
@subsection Dynamics
@cindex Dynamics
+@cindex @code{\pppp}
@cindex @code{\ppp}
@cindex @code{\pp}
@cindex @code{\p}
@cindex @code{\rfz}
Absolute dynamic marks are specified using a command after a note
-@code{c4\ff}. The available dynamic marks are @code{\ppp},
+@code{c4\ff}. The available dynamic marks are @code{\ppppp},
+@code{\pppp}, @code{\ppp},
@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
-@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
+@code{\fff}, @code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff},
@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
A hairpin starts at the left edge of the beginning note and ends on the
right edge of the ending note.
+In some situations the @code{\espressivo} articulation mark may
+be suitable to indicate a crescendo and decrescendo on the one note,
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+c2 b4 a g1\espressivo
+@end lilypond
+
This may give rise to very short hairpins. Use @code{minimum-length}
in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
example
into or out of a @code{<< \\ >>} construct. Conversely, parallel voices
from separate @code{<< \\ >>} constructs on the same staff are the the
same voice. Here is the same example, with different noteheads for each
-voice. Note that the change to the note-head style in the main voice does not affect
+voice. Note that the change to the note-head style in the main voice does
+not affect
the inside of the @code{<< \\ >>} constructs. Also, the change to the second
voice in the first @code{<< \\ >>} construct is effective in the second
@code{<< \\ >>}, and the voice is tied across the two constructs.
@item volta
Repeats are not written out, but alternative endings (volte) are
printed, left to right with brackets. This is the standard notation
-for repeats with alternatives. These are not played in MIDI output by default.
+for repeats with alternatives. These are not played in MIDI output by
+default.
@ignore
@item fold
on the @code{countPercentRepeats} property,
@lilypond[relative=2,fragment,quote,verbatim,ragged-right]
+\new Voice {
\set countPercentRepeats = ##t
-\new Voice
\repeat "percent" 4 { c1 }
+}
@end lilypond
The controls available for tuning are described in a separate
document, the
@iftex
-Program reference
+Program reference manual.
@end iftex
@ifnottex
@ref{Top,Program reference,,lilypond-internals}.
@end ifnottex
-manual. That manual
+That manual
lists all different variables, functions and options available in
LilyPond. It is written as a HTML document, which is available
-@uref{http://@/lilypond@/.org/@/doc/@/v2.7/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/v2.8/@/Documentation/@/user/@/
+lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
-There are three areas where the default settings may be changed:
+There are four areas where the default settings may be changed:
@itemize @bullet
+@item
+Automatic notation: changing the automatic creation of notation
+elements. For example, changing the beaming rules.
+
@item
Output: changing the appearance of individual
objects. For example, changing stem directions or the location of
@item
Global layout: changing the appearance of the spacing, line
-breaks, and page dimensions.
+breaks, and page dimensions. These modifications are discussed
+in @ref{Global issues}.
@end itemize
-Then there are separate systems for typesetting text (like
-@emph{ritardando}) and selecting different fonts. This chapter also
-discusses these.
-
Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure. Overriding layout decisions in effect accesses the
program internals, which requires Scheme input. Scheme elements are
@menu
+* Automatic notation::
* Interpretation contexts::
* The \override command::
@end menu
+@node Automatic notation
+@section Automatic notation
+
+This section describes how to change the way that accidentals and
+beams are automatically displayed.
+
+@menu
+* Automatic accidentals::
+* Setting automatic beam behavior::
+@end menu
+
+@node Automatic accidentals
+@subsection Automatic accidentals
+@cindex Automatic accidentals
+
+Common rules for typesetting accidentals have been placed in a
+function. This function is called as follows
+
+@cindex @code{set-accidental-style}
+@example
+#(set-accidental-style 'STYLE #('CONTEXT#))
+@end example
+
+The function can take two arguments: the name of the accidental style,
+and an optional argument that denotes the context that should be
+changed. If no context name is supplied, @code{Staff} is the default,
+but you may wish to apply the accidental style to a single @code{Voice}
+instead.
+
+The following accidental styles are supported
+@table @code
+@item default
+This is the default typesetting behavior. It corresponds
+to 18th century common practice: Accidentals are
+remembered to the end of the measure in which they occur and
+only on their own octave.
+
+@item voice
+The normal behavior is to remember the accidentals on
+Staff-level. This variable, however, typesets accidentals
+individually for each voice. Apart from that, the rule is similar to
+@code{default}.
+
+As a result, accidentals from one voice do not get canceled in other
+voices, which is often an unwanted result
+
+@lilypond[quote,ragged-right,relative=1,fragment,verbatim]
+\new Staff <<
+ #(set-accidental-style 'voice)
+ <<
+ { es g } \\
+ { c, e }
+>> >>
+@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
+@code{modern} or @code{modern-cautionary}
+should be used instead.
+
+@item modern
+@cindex @code{modern} style accidentals
+This rule corresponds to the common practice in the 20th century. This rule
+prints the same accidentals as @code{default}, but temporary
+accidentals also are canceled in other octaves. Furthermore,
+in the same octave, they also get canceled in the following
+measure
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+#(set-accidental-style 'modern)
+cis' c'' cis'2 | c'' c'
+@end lilypond
+
+@item @code{modern-cautionary}
+@cindex @code{modern-cautionary}
+This rule is similar to @code{modern}, but the ``extra'' accidentals
+(the ones not typeset by @code{default}) are typeset as cautionary
+accidentals. They are printed in reduced size or with parentheses
+@lilypond[quote,ragged-right,fragment,verbatim]
+#(set-accidental-style 'modern-cautionary)
+cis' c'' cis'2 | c'' c'
+@end lilypond
+
+@cindex @code{modern-voice}
+@item modern-voice
+This rule is used for multivoice accidentals to be read both by musicians
+playing one voice and musicians playing all voices. Accidentals are
+typeset for each voice, but they @emph{are} canceled across voices in
+the same @internalsref{Staff}.
+
+@cindex @code{modern-voice-cautionary}
+@item modern-voice-cautionary
+This rule is the same as @code{modern-voice}, but with the extra
+accidentals (the ones not typeset by @code{voice}) typeset
+as cautionaries. Even though all accidentals typeset by
+@code{default} @emph{are} typeset by this variable,
+some of them are typeset as cautionaries.
+
+@item piano
+@cindex @code{piano} accidentals
+This rule reflects 20th century practice for piano notation. Very similar to
+@code{modern} but accidentals also get canceled
+across the staves in the same @internalsref{GrandStaff} or
+@internalsref{PianoStaff}.
+
+@item piano-cautionary
+@cindex @code{#(set-accidental-style 'piano-cautionary)}
+Same as @code{#(set-accidental-style 'piano)} but with the extra
+accidentals typeset as cautionaries.
+
+@item no-reset
+@cindex @code{no-reset} accidental style
+This is the same as @code{default} but with accidentals lasting
+``forever'' and not only until the next measure
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+#(set-accidental-style 'no-reset)
+c1 cis cis c
+@end lilypond
+
+@item forget
+This is sort of the opposite of @code{no-reset}: Accidentals
+are not remembered at all---and hence all accidentals are
+typeset relative to the key signature, regardless of what was
+before in the music
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+#(set-accidental-style 'forget)
+\key d\major c4 c cis cis d d dis dis
+@end lilypond
+@end table
+
+
+@seealso
+
+Program reference: @internalsref{Accidental_engraver},
+@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
+
+
+@refbugs
+
+Simultaneous notes are considered to be entered in sequential
+mode. This means that in a chord the accidentals are typeset as if the
+notes in the chord happen one at a time, in the order in which
+they appear in the input file. This is a problem when accidentals
+in a chord depend on each other,
+which does not happen for the default accidental style. The problem
+can be solved by manually inserting @code{!} and @code{?} for the
+problematic notes.
+
+
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+
+@cindex @code{autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
+
+@c [TODO: use \applyContext]
+
+In normal time signatures, automatic beams can start on any note but can
+only end in a few positions within the measure: beams can end on a beat,
+or at durations specified by the properties in
+@code{autoBeamSettings}. The properties in @code{autoBeamSettings}
+consist of a list of rules for where beams can begin and end. The
+default @code{autoBeamSettings} rules are defined in
+@file{scm/@/auto@/-beam@/.scm}.
+
+In order to add a rule to the list, use
+@example
+#(override-auto-beam-setting '(be p q n m) a b [context])
+@end example
+
+@itemize @bullet
+
+@item @code{be} is either "begin" or "end".
+
+@item @code{p/q} is the duration of the note for which you want
+to add a rule. A beam is considered to have the duration of its
+shortest note. Set @code{p} and @code{q} to @code{'*'} to
+have this apply to any beam.
+
+@item @code{n/m} is the time signature to which
+this rule should apply. Set @code{n} and @code{m} to @code{'*'}
+to have this apply in any time signature.
+
+@item @code{a/b} is the position in the bar at which the beam should
+begin/end.
+
+@item @code{context} is optional, and it specifies the context at which
+the change should be made. The default is @code{'Voice}.
+@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to
+@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.
+
+@end itemize
+
+For example, if automatic beams should always end on the first quarter
+note, use
+
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4)
+@end example
+
+You can force the beam settings to only take effect on beams whose shortest
+note is a certain duration
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 2/4
+#(override-auto-beam-setting '(end 1 16 * *) 1 16)
+a16 a a a a a a a |
+a32 a a a a16 a a a a a |
+#(override-auto-beam-setting '(end 1 32 * *) 1 16)
+a32 a a a a16 a a a a a |
+@end lilypond
+
+You can force the beam settings to only take effect in certain time
+signatures
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 5/8
+#(override-auto-beam-setting '(end * * 5 8) 2 8)
+c8 c d d d
+\time 4/4
+e8 e f f e e d d
+\time 5/8
+c8 c d d d
+@end lilypond
+
+You can also remove a previously set beam-ending rule by using
+
+@example
+#(revert-auto-beam-setting '(be p q n m) a b [context])
+@end example
+
+@noindent
+be, p, q, n, m, a, b and context are the same as above. Note that the
+default rules are specified in @file{scm/@/auto@/-beam@/.scm},
+so you can revert rules that you did not explicitly create.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 4/4
+a16 a a a a a a a a a a a a a a a
+#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
+a16 a a a a a a a a a a a a a a a
+@end lilypond
+
+The rule in a revert-auto-beam-setting statement must exactly match the
+original rule. That is, no wildcard expansion is taken into account.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 1/4
+#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
+a16 a a a
+#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
+a a a a
+#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
+a a a a
+@end lilypond
+
+
+
+@c TODO: old material -- not covered by above stuff, I think.
+If automatic beams should end on every quarter in 5/4 time, specify
+all endings
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
+#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
+@dots{}
+@end example
+
+The same syntax can be used to specify beam starting points. In this
+example, automatic beams can only end on a dotted quarter note
+@example
+#(override-auto-beam-setting '(end * * * *) 3 8)
+#(override-auto-beam-setting '(end * * * *) 1 2)
+#(override-auto-beam-setting '(end * * * *) 7 8)
+@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8, has passed within the measure).
+
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{autoBeaming}
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off with @code{\autoBeamOff}.
+
+
+@refcommands
+
+@cindex @code{\autoBeamOff}
+@code{\autoBeamOff},
+@cindex @code{\autoBeamOn}
+@code{\autoBeamOn}.
+
+
+@refbugs
+
+If a score ends while an automatic beam has not been ended and is
+still accepting notes, this last beam will not be typeset at all. The
+same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
+>>}. If a polyphonic voice ends while an automatic beam is still
+accepting notes, it is not typeset.
+
+
@node Interpretation contexts
@section Interpretation contexts
When music is printed, a lot of notational elements must be added to the
-input, which is often bare bones. For example, compare the input and
-output of the following example:
+input. For example, compare the input and output of the following example:
@lilypond[quote,verbatim,relative=2,fragment]
cis4 cis2. g4
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,
-the input, the program remembers where measure boundaries are, and what
-pitches need explicit accidentals. This information can be presented on
+order, similar to reading a score from left to right. While reading
+the input, the program remembers where measure boundaries are, and which
+pitches require explicit accidentals. This information can be presented on
several levels. For example, the effect of an accidental is limited
to a single staff, while a bar line must be synchronized across the
entire score.
Within LilyPond, these rules and bits of information are grouped in
-so-called Contexts. Examples of context are @context{Voice},
+@emph{Contexts}. Some examples of contexts are @context{Voice},
@context{Staff}, and @context{Score}. They are hierarchical, for
-example, a @context{Staff} can contain many @context{Voice}s, and a
+example: a @context{Staff} can contain many @context{Voice}s, and a
@context{Score} can contain many @context{Staff} contexts.
Each context has the responsibility for enforcing some notation rules,
creating some notation objects and maintaining the associated
-properties. So, the synchronization of bar lines is handled at
-@context{Score} context. The @context{Voice} may introduce an
+properties. For example, the @context{Voice} context may introduce an
accidental and then the @context{Staff} context maintains the rule to
-show or suppress the accidental for the remainder of the measure.
+show or suppress the accidental for the remainder of the measure. The
+synchronization of bar lines is handled at @context{Score} context.
+
+However, in some music we may not want the bar lines to be
+synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
+such cases, we must modify the default settings of the @context{Score}
+and @context{Staff} contexts.
-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
+For very simple scores, contexts are created implicitly, and you need
+not be aware of them. For larger pieces, such as anything with more
+than one staff, 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
@node Creating contexts
@subsection Creating contexts
-For scores with only one voice and one staff, correct contexts are
+For scores with only one voice and one staff, contexts are
created automatically. For more complex scores, it is necessary to
create them by hand. There are three commands that do this.
+@itemize @bullet
+
+@item
The easiest command is @code{\new}, and it also the quickest to type.
It is prepended to a music expression, for example
@code{\new Staff}.
@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
-<< \new Staff { c4 c }
- \new Staff { d4 d }
+<<
+ \new Staff { c4 c }
+ \new Staff { d4 d }
>>
@end lilypond
-@cindex @code{\context}
+The @code{\new} command may also give a name to the context,
+
+@example
+\new @var{type} = @var{id} @var{music}
+@end example
+However, this user specified name is only used if there is no other
+context already earlier with the same name.
+
+@cindex @code{\context}
+\item
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 explicit name. The
syntax is
@example
@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, a new
+context with the specified name 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
@noindent
-Another possibility is funneling two different music expressions into
-one context. In the following example, articulations and notes are
-entered separately,
+Another possible use of named contexts is funneling two different
+music expressions into one context. In the following example,
+articulations and notes are entered separately,
@example
music = @{ c4 c4 @}
They are combined by sending both to the same @context{Voice} context,
@example
-<< \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
+<<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
>>
@end example
@lilypond[quote,ragged-right]
@cindex creating contexts
+@item
The third command for creating contexts is
@example
\context @var{type} @var{music}
\context Staff \applyOutput #@var{function}
@end example
+@end itemize
+
@node Changing context properties on the fly
@subsection Changing context properties on the fly
@code{Clef_engraver} from a @code{Staff} context,
@lilypond[quote,relative=1,verbatim,fragment]
-<< \new Staff {
+<<
+ \new Staff {
f2 g
}
\new Staff \with {
In the second staff 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. This method also influences the spacing, which may or
+may not be desirable. A more
sophisticated method of blanking objects is shown in @ref{Common tweaks}.
The next example shows a practical application. Bar lines and time
@menu
-* Common tweaks::
* Constructing a tweak::
* Navigating the program reference::
* Layout interfaces::
-@node Common tweaks
-@subsection Common tweaks
-
-@c Should we point at ly/property-init.ly ? -gp
-Some overrides are so common that predefined commands are provided as
-short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@c @ref{Notation manual},
-Notation manual
-@c FIXME
-under the sections for slurs and stems
-respectively.
-
-The exact tuning possibilities for each type of layout object are
-documented in the program reference of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a few of these:
-
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves objects around in the printout.
-The first number controls left-right movement; a positive number will
-move the object to the right. The second number controls up-down
-movement; a positive number will move it higher. The units of these
-offsets are staff-spaces. The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
-
-In the following example, the second fingering is moved a little to
-the left, and 1.8 staff space downwards:
-
-@cindex setting object properties
-
-@lilypond[quote,fragment,relative=1,verbatim]
-\stemUp
-f-5
-\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
-
-@item
-Setting the @code{transparent} property will cause an object to be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes up space, it takes part in
-collisions, and slurs, ties, and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing 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[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[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 the distance between
-symbols that are printed above or below notes. We provide two
-examples; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c2\fermata
-\override Script #'padding = #3
-b2\fermata
-@end lilypond
-
-@lilypond[quote,fragment,relative=1,verbatim]
-% This will not work, see below:
-\override MetronomeMark #'padding = #3
-\tempo 4=120
-c1
-% This works:
-\override Score.MetronomeMark #'padding = #3
-\tempo 4=80
-d1
-@end lilypond
-
-Note in the second example how important it is to figure out what
-context handles a certain object. Since the @code{MetronomeMark} object
-is handled in the Score context, property changes in the @code{Voice}
-context will not be noticed.
-
-@end itemize
-
-Some tweakable options are called ``subproperties'' and reside inside
-properties. To tweak those, use
-
-@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
-@end example
-
-@cindex Tweaks, distances
-@cindex Distances
-
-Distances in LilyPond are measured in staff-spaces, while most
-thickness properties are measured in line-thickness. Some
-properties are different; for example, the thickness of beams
-is measured in staff-spaces. For more information, see the
-relevant portion of the program reference.
-
-More specific overrides are also possible. The next section
-discusses in depth how to figure out these statements for yourself.
-
-
@node Constructing a tweak
@subsection Constructing a tweak
@item a sensible value: here @code{3.0}
@end itemize
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
@cindex internal documentation
@cindex finding graphical objects
@node Objects connected to the input
@subsection Objects connected to the input
+@cindex @code{\tweak}
+
In some cases, it is possible to take a short-cut for tuning graphical
objects. For objects that result directly from a piece of the input,
you can use the @code{\tweak} function, for example
by note heads, not by music events) or clefs (these are not caused by
music inputs, but rather by the change of a property value).
-In a similar vein, objects may be parenthesized by prefixing
-@code{\parenthesize} to the music event,
-
-@lilypond[relative=2,fragment,verbatim,ragged-right]
-<
- c
- \parenthesize d
- g
->4-\parenthesize -.
-@end lilypond
-
-
-
@node Difficult tweaks
@subsection Difficult tweaks
@node Invoking musicxml2ly
@section Invoking @code{musicxml2ly}
-@uref{http://@/www.@/recordarde@/.com/xml/,MusicXML} is an XML dialect
+@uref{http://@/www.@/recordarde@/.com/xml@/.html,MusicXML} is an XML dialect
for representing music notation.
@command{musicxml2ly} extracts the notes from part-wise MusicXML
@item
@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor.
@item
-@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime monophonic MIDI to LilyPond converter.
+@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
+monophonic MIDI to LilyPond converter.
@item
-@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an Emacs major mode.
+@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
+Emacs major mode.
@item
@uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, which imports
@uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
@c -*- coding: utf-8; mode: texinfo; -*-
@node Example templates
-@chapter Example templates
+@appendix Example templates
This section of the manual contains templates with the LilyPond score
already set up for you. Just add notes, run LilyPond, and enjoy
@node Single staff
-@section Single staff
-@subsection Notes only
+@appendixsec Single staff
+@appendixsubsec Notes only
The first example gives you a staff with notes, suitable for a solo
instrument or a melodic fragment. Cut and paste this into a file,
}
@end lilypond
-@subsection Notes and lyrics
+@appendixsubsec Notes and lyrics
The next example demonstrates a simple melody with lyrics. Cut and
paste, add notes, then words for the lyrics. This example turns off
}
@end lilypond
-@subsection Notes and chords
+@appendixsubsec Notes and chords
Want to prepare a lead sheet with a melody and chords? Look no further!
}
@end lilypond
-@subsection Notes, lyrics, and chords.
+@appendixsubsec Notes, lyrics, and chords.
This template allows you to prepare a song with melody, words, and chords.
@end lilypond
@node Piano templates
-@section Piano templates
-@subsection Solo piano
+@appendixsec Piano templates
+@appendixsubsec Solo piano
Here is a simple piano staff.
}
@end lilypond
-@subsection Piano and melody with lyrics
+@appendixsubsec Piano and melody with lyrics
Here is a typical song format: one staff with the melody and lyrics, with
piano accompaniment underneath.
@end lilypond
-@subsection Piano centered lyrics
+@appendixsubsec Piano centered lyrics
Instead of having a full staff for the melody and lyrics, you can place
the lyrics between the piano staff (and omit the separate melody staff).
@end lilypond
-@subsection Piano centered dynamics
+@appendixsubsec Piano centered dynamics
Many piano scores have the dynamics centered between the two
staffs. This requires a bit of tweaking to implement, but
@node String quartet
-@section String quartet
-@subsection String quartet
+@appendixsec String quartet
+@appendixsubsec String quartet
This template demonstrates a string quartet. It also uses a @code{\global}
section for time and key signatures.
}
@end lilypond
-@subsection String quartet parts
+@appendixsubsec String quartet parts
The previous example produces a nice string quartet, but what if you
needed to print parts? This template demonstrates how to use the
@node Vocal ensembles
-@section Vocal ensembles
+@appendixsec Vocal ensembles
-@subsection SATB vocal score
+@appendixsubsec SATB vocal score
Here is a standard four-part SATB vocal score. With larger ensembles,
it's often useful to include a section which is included in all
@end lilypond
-@subsection SATB vocal score and automatic piano reduction
+@appendixsubsec SATB vocal score and automatic piano reduction
This template adds an automatic piano reduction to the SATB vocal
score. This demonstrates one of the strengths of LilyPond -- you
@c bad node name to avoid node name confict
@node Ancient notation templates
-@section Ancient notation templates
+@appendixsec Ancient notation templates
-@subsection Transcription of mensural music
+@appendixsubsec Transcription of mensural music
When transcribing mensural music, an incipit at the beginning of the
piece is useful to indicate the original key and tempo. While today
@end lilypond
-@subsection Gregorian transcription template
+@appendixsubsec Gregorian transcription template
-This example demonstrates how to do modern transcriptions of Gregorian
+This example demonstrates how to do modern transcription of Gregorian
music. Gregorian music has no measure, no stems; it uses only half and
-quarter notes, and two types of barlines, a short one indicating a rest,
-and a second one indicating a breath mark.
+quarter noteheads, and special marks, indicating rests of different length.
@lilypond[quote,verbatim,ragged-right]
\include "gregorian-init.ly"
@node Jazz combo
-@section Jazz combo
+@appendixsec Jazz combo
This is a much more complicated template, for a jazz ensemble. Note that all
instruments are notated in @code{\key c \major}. This refers to the key in
composer = "Me"
meter = "moderato"
piece = "Swing"
- tagline = "LilyPond example file by Amelie Zapf,
- Berlin 07/07/2003"
+ tagline = \markup {
+ \column {
+ "LilyPond example file by Amelie Zapf,"
+ "Berlin 07/07/2003"
+ }
+ }
texidoc = "Jazz tune for combo
(horns, guitar, piano, bass, drums)."
}
\global
\set Staff.instrument = #"Trumpet"
\clef treble
- \new Staff <<
+ <<
\trpt
>>
}
\global
\set Staff.instrument = #"Alto Sax"
\clef treble
- \new Staff <<
+ <<
\alto
>>
}
\global
\set Staff.instrument = #"Bari Sax"
\clef treble
- \new Staff <<
+ <<
\bari
>>
}
\global
\set Staff.instrument = #"Trombone"
\clef bass
- \new Staff <<
+ <<
\tbone
>>
}
\global
\set Staff.instrument = #"Guitar"
\clef treble
- \new Staff <<
+ <<
\gtr
>>
}
\clef treble
\global
\set Staff.midiInstrument = "acoustic grand"
- \new Staff <<
+ <<
\new Voice = "one" \rhUpper
\new Voice = "two" \rhLower
>>
\clef bass
\global
\set Staff.midiInstrument = "acoustic grand"
- \new Staff <<
+ <<
\new Voice = "one" \lhUpper
\new Voice = "two" \lhLower
>>
}
piano = {
- \new PianoStaff <<
+ <<
\set PianoStaff.instrument = #"Piano"
\new Staff = "upper" \PianoRH
\new Staff = "lower" \PianoLH
\global
\set Staff.instrument = #"Bass"
\clef bass
- \new Staff <<
+ <<
\Bass
>>
}
@node Lilypond-book templates
-@section Lilypond-book templates
+@appendixsec Lilypond-book templates
These templates are for use with @code{lilypond-book}. If you're not familiar
with this program, please refer to @ref{LilyPond-book}.
-@subsection LaTeX
+@appendixsubsec LaTeX
You can include LilyPond fragments in a LaTeX document.
\end@{document@}
@end example
-@subsection Texinfo
+@appendixsubsec Texinfo
You can include LilyPond fragments in Texinfo; in fact, this entire manual
is written in Texinfo.
current working directory are available to \include, but a file of the same
name in LilyPond's installation takes precedence. Files are
available to \include from directories in the search path specified as an
-option when invoking @code{lilypond --include=DIR} which adds DIR to the search
-path.
+option when invoking @code{lilypond --include=DIR} which adds DIR to the
+search path.
The @code{\include} statement can use full path information, but with the Unix
convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
\book {
\header {
dedication = "dedicated to me"
- title = \markup \center-align { "Title first line" "Title second line, longer" }
+ title = \markup \center-align { "Title first line" "Title second line,
+longer" }
subtitle = "the subtitle,"
- subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version))
+ subsubtitle = #(string-append "subsubtitle LilyPond version "
+(lilypond-version))
poet = "Poet"
composer = \markup \center-align { "composer" \small "(1847-1973)" }
texttranslator = "Text Translator"
- meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" }
- arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
+ meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
+"r" }
+ arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
+#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
instrument = \markup \bold \italic "instrument"
piece = "Piece"
}
@refbugs
-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
+The @code{breakbefore=##t} header requires that there is a @code{piece}
+header as well. It may be used as a normal header, or left blank
+(@code{=""}) as in the example above, but it must be present.
@}
@end example
-The first command sets the size of all pages. The second command sets the size
+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{\book}, then the paper size will only
@c let's wait for a some comments before writing more.
-The vertical spacing on a page can also be changed for each system individually.
+The vertical spacing on a page can also be changed for each system
+individually.
Some examples are found in the example file
@inputfileref{input/regression/,page-spacing.ly}.
@refbugs
-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
+The @code{breakbefore=##t} header requires that there is a @code{piece}
+header as well. It may be used as a normal header, or left blank
+(@code{=""}) as in the example above, but it must be present.
@node Vocal music
@section Vocal music
-There are three different issues when printing vocal music
+Since LilyPond input files are text, there are two issues to
+consider when working with vocal music:
@itemize @bullet
@item
input@tie{}@code{d} should be interpreted as a one letter syllable, not the
note@tie{}D.
-@item
-Song texts must be printed as text, not as notes.
-
@item
Song texts must be aligned with the notes of their melody.
@end itemize
-The simplest solution for printing music uses the @code{\addlyrics}
-function to solve all these problems at once. However, these
-three functions can be controlled separately, which is necessary
-for complex vocal music.
-
+There are a few different ways to define lyrics; the simplest
+way is to use the @code{\addlyrics} function.
@menu
* Setting simple songs::
* Entering lyrics::
* Hyphens and extenders::
* The Lyrics context::
-* Flexibility in alignment::
-* More stanzas::
+* Melismata::
+* Another way of entering lyrics::
+* Flexibility in placement::
+* Spacing lyrics::
+* More about stanzas::
* Ambitus::
* Other vocal issues::
@end menu
@commonprop
-Checking to make sure that text scripts and lyrics are within the margins is a relatively large computational task. To speed up processing, lilypond does not perform such calculations by default; to enable it, use
+Checking to make sure that text scripts and lyrics are within the margins is
+a relatively large computational task. To speed up processing, lilypond does
+not perform such calculations by default; to enable it, use
@example
\override Score.PaperColumn #'keep-inside-line = ##t
\addlyrics { joue le jeu }
@end lilypond
-Sometimes it is appropriate to have one stanza set
-to the music, and the rest added in verse form at
-the end of the piece. This can be accomplished by adding
-the extra verses into a @code{\markup} section outside
-of the main score block. Notice that there are two
-different ways to force linebreaks when using
-@code{\markup}.
-
-@lilypond[ragged-right,verbatim,quote]
-melody = \relative c' {
-e d c d | e e e e |
-d d e d | c1 |
-}
-
-text = \lyricmode {
-\set stanza = "1." Ma- ry had a lit- tle lamb,
-its fleece was white as snow.
-}
-
-\book{
- \score{ <<
- \new Voice = "one" { \melody }
- \new Lyrics \lyricsto "one" \text
- >>
- \layout { }
- }
- \markup { \column{
- \line{ Verse 2. }
- \line{ All the children laughed and played }
- \line{ To see a lamb at school. }
- }
- }
- \markup{
- \wordwrap-string #"
- Verse 3.
-
- Mary took it home again,
-
- It was against the rule."
- }
-}
-@end lilypond
-
-
-@c TODO - this isn't such a great place for this note, but I can't
-@c find a better place without rearranging a lot of lyric stuff.
-@c It's yet another thing to look at post-3.0.
-
-The @code{\addlyrics} command is actually just a convienient way
-to write a more complicated LilyPond structure that sets up the
-lyrics. You should use @code{\addlyrics} unless you need to do
-fancy things, in which case you should investigate
-@code{\lyricsto} or @code{\lyricmode}.
-
-@example
-@{ MUSIC @}
-\addlyrics @{ LYRICS @}
-@end example
-
-@noindent
-is the same as
-
-@example
-\new Voice = "blah" @{ music @}
-\new Lyrics \lyricsto "blah" @{ LYRICS @}
-@end example
-
-@refbugs
+The command @code{\addlyrics} cannot handle polyphony settings. For these
+cases you should use @code{\lyricsto} and @code{\lyricmode}.
-@code{\addlyrics} cannot handle polyphony.
@node Entering lyrics
the lyrics to a melody or other voice of music, using @code{\addlyrics}
or @code{\lyricsto}. For more details see @ref{The Lyrics context}.
-A word lyrics mode begins with an alphabetic character, and ends with
+A word or syllable of lyrics begins with an alphabetic character, and ends
+with
any space or digit. The following characters can be any character
that is not a digit or white space. One important consequence of this
is that a word can end with @code{@}}. The following example is
-usually a mistake in the input file. The syllable includes a @code{@}}, so the
+usually a mistake in the input file. The syllable includes a @code{@}}, so
+the
opening brace is not balanced
@example
\lyricmode @{ twinkle@}
@cindex spaces, in lyrics
@cindex quotes, in lyrics
-Any @code{_} character that appears in an unquoted word is converted
-to a space. This provides a mechanism for introducing spaces into words
-without using quotes.
+In order to assign more than one syllable to a single note, you must
+surround them with quotes or use a @code{_} character between the syllables.
+
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+\time 3/4
+\relative { c2 e4 g2 e4 }
+\addlyrics { gran- de_a- mi- go }
+\addlyrics { pu- "ro y ho-" nes- to }
+@end lilypond
To enter lyrics with characters from non-English languages, or with
non-ascii characters (such as the heart symbol or slanted quotes),
\lyricmode @{ He said: “Let my peo ple go”. @}
@end example
+To use normal quotes in lyrics, add a backslash before the
+quotes. For example,
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
+\addlyrics { "\"I" am so lone- "ly\"" said she }
+@end lilypond
+
The full definition of a word start in Lyrics mode is somewhat more
complex.
@code{"}, or @code{^}.
-
@seealso
Program reference: @internalsref{LyricText}, @internalsref{LyricSpace}.
-@refbugs
-The definition of lyrics mode is too complex.
@node Hyphens and extenders
@subsection Hyphens and extenders
@node The Lyrics context
@subsection The Lyrics context
+Lyrics are printed by interpreting them in the context caleld
+@internalsref{Lyrics}.
-Lyrics are printed by interpreting them in a @internalsref{Lyrics} context
@example
\new Lyrics \lyricmode @dots{}
@end example
automatically. In this case, it is no longer necessary to enter the
correct duration for each syllable. This is achieved by combining the
melody and the lyrics with the @code{\lyricsto} expression
+
@example
\new Lyrics \lyricsto @var{name} @dots{}
@end example
@code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
@code{\lyricmode} keyword may be omitted.
+The following example uses different commands for entering lyrics.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+ \new Voice = "one" \relative c'' {
+ \autoBeamOff
+ \time 2/4
+ c4 b8. a16 g4. f8 e4 d c2
+ }
+ \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
+ \new Lyrics \lyricmode { Joy to the earth! the Sav -- our reigns. }
+ \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
+>>
+@end lilypond
+
+The second stanza is not properly aligned because the durations
+were not specified. A solution for that would be to use @code{\lyricsto}.
+
+
+
+
+
+
+To define indentifiers containing lyrics, the function @code{lyricmode}
+must be used.
+
+@example
+verseOne = \lyricmode @{ Joy to the world the Lord is come @}
+\score @{
+ <<
+ \new Voice = "one" \relative c'' @{
+ \autoBeamOff
+ \time 2/4
+ c4 b8. a16 g4. f8 e4 d c2
+ @}
+ \addlyrics @{ \verseOne @}
+ >>
+@}
+@end example
+
+The @code{\addlyrics} command is actually just a convenient way
+to write a more complicated LilyPond structure that sets up the
+lyrics.
+
+@example
+@{ MUSIC @}
+\addlyrics @{ LYRICS @}
+@end example
+
+@noindent
+is the same as
+
+@example
+\new Voice = "blah" @{ music @}
+\new Lyrics \lyricsto "blah" @{ LYRICS @}
+@end example
+
For different or more complex orderings, the best way is to setup the
hierarchy of staves and lyrics first, e.g.,
@example
\new ChoirStaff <<
- \new Lyrics = "sopranoLyrics" @{ s1 @}
\new Voice = "soprano" @{ @emph{music} @}
+ \new Lyrics = "sopranoLyrics" @{ s1 @}
\new Lyrics = "tenorLyrics" @{ s1 @}
\new Voice = "tenor" @{ @emph{music} @}
>>
@end example
+
and then combine the appropriate melodies and lyric lines
+
@example
\context Lyrics = sopranoLyrics \lyricsto "soprano"
@emph{the lyrics}
>>
@end example
+@seealso
+
+Program reference: @internalsref{LyricCombineMusic},
+@internalsref{Lyrics}.
+
+
+@node Melismata
+@subsection Melismata
The @code{\lyricsto} command detects melismata: it only puts one
syllable under a tied or slurred group of notes. If you want to force
beamed, and automatic beaming (see @ref{Setting automatic beam
behavior}) is switched off.
-@ignore
+@cindex SATB
+@cindex choral score
-@c nonformation:
+A complete example of a SATB score setup is in section
+@ref{Vocal ensembles}.
-The criteria for deciding melismata can
-be tuned with the property @code{melismaBusyProperties}. See
-@internalsref{Melisma_translator} in the program reference for more
-information.
-@end ignore
+@refcommands
+
+@code{\melisma}, @code{\melismaEnd}
+@cindex @code{\melismaEnd}
+@cindex @code{\melisma}
+
+@seealso
+
+Program reference: @internalsref{Melisma_translator}.
+
+
+@inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}.
+
+@refbugs
+
+Melismata are not detected automatically, and extender lines must be
+inserted by hand.
+
+
+@node Another way of entering lyrics
+@subsection Another way of entering lyrics
Lyrics can also be entered without @code{\lyricsto}. In this case the
duration of each syllable must be entered explicitly, for example,
} >>
@end lilypond
-@cindex SATB
-@cindex choral score
-
-A complete example of a SATB score setup is in section
-@ref{Vocal ensembles}.
-
-
-@refcommands
-
-@code{\melisma}, @code{\melismaEnd}
-@cindex @code{\melismaEnd}
-@cindex @code{\melisma}
-
-@seealso
-
-Program reference: @internalsref{LyricCombineMusic},
-@internalsref{Lyrics}, @internalsref{Melisma_translator}.
-
-
-@inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}.
-@c TODO: make separate section for melismata
-
-@refbugs
-
-Melismata are not detected automatically, and extender lines must be
-inserted by hand.
-
@c TODO: document \new Staff << Voice \lyricsto >> bug
-@node Flexibility in alignment
-@subsection Flexibility in alignment
+@node Flexibility in placement
+@subsection Flexibility in placement
Often, different stanzas of one song are put to one melody in slightly
differing ways. Such variations can still be captured with
@code{\lyricsto}.
+@menu
+* Lyrics to multiple notes of a melisma::
+* Divisi lyrics::
+* Switching the melody associated with a lyrics line::
+* Specifying melismata within the lyrics::
+@end menu
+
+@node Lyrics to multiple notes of a melisma
@subsubsection Lyrics to multiple notes of a melisma
voice ignore the melisma. This is done by setting
@code{ignoreMelismata} in the Lyrics context.
-There has one tricky aspect. The setting for @code{ignoreMelismata}
+There is one tricky aspect: the setting for @code{ignoreMelismata}
must be set one syllable @emph{before} the non-melismatic syllable
in the text, as shown here,
@end lilypond
-@subsection Switching the melody associated with a lyrics line
+@node Divisi lyrics
+@subsubsection Divisi lyrics
+
+You can display alternate (or divisi) lyrics by naming voice
+contexts and attaching lyrics to those specific contexts.
+
+@lilypond[verbatim,ragged-right,quote]
+\score{ <<
+ \new Voice = "melody" {
+ \relative c' {
+ c4
+ <<
+ { \voiceOne c8 e }
+ \new Voice = "splitpart" { \voiceTwo c4 }
+ >>
+ \oneVoice c4 c | c
+ }
+ }
+ \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
+ \new Lyrics \lyricsto "splitpart" { will }
+>> }
+@end lilypond
+
+
+You can use this trick to display different lyrics for a repeated
+section.
+
+@lilypond[verbatim,ragged-right,quote]
+\score{ <<
+ \new Voice = "melody" \relative c' {
+ c2 e | g e | c1 |
+ \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
+ a2 b | c1}
+ \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
+ do mi sol mi do
+ la si do }
+ \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
+ do re mi fa sol }
+ \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
+ dodo rere mimi fafa solsol }
+>>
+}
+@end lilypond
+
+@node Switching the melody associated with a lyrics line
+@subsubsection Switching the melody associated with a lyrics line
More complex variations in text underlay are possible. It is possible
to switch the melody for a line of lyrics during the text. This is
@code{lahlah} to @code{associatedVoice}.
-
-@subsection Specifying melismata within the lyrics
+@node Specifying melismata within the lyrics
+@subsubsection Specifying melismata within the lyrics
It is also possible to define melismata entirely in the lyrics. This
can be done by entering @code{_} for every note that is part of the
{ Ky -- _ _ ri __ _ _ _ e }
@end lilypond
-@subsubsection Spacing lyrics
+
+@node Spacing lyrics
+@subsection Spacing lyrics
@cindex Spacing lyrics
@cindex Lyrics, increasing space between
}
@end lilypond
-To make this change for all lyrics in the score, set the property in the layout.
+To make this change for all lyrics in the score, set the property in the
+layout.
@lilypond[relative,verbatim,quote,ragged-right]
\score {
@end lilypond
-@node More stanzas
-@subsection More stanzas
+@node More about stanzas
+@subsection More about stanzas
@cindex phrasing, in lyrics
These numbers are put just before the start of first syllable.
+Sometimes it is appropriate to have one stanza set
+to the music, and the rest added in verse form at
+the end of the piece. This can be accomplished by adding
+the extra verses into a @code{\markup} section outside
+of the main score block. Notice that there are two
+different ways to force linebreaks when using
+@code{\markup}.
+
+@lilypond[ragged-right,verbatim,quote]
+melody = \relative c' {
+e d c d | e e e e |
+d d e d | c1 |
+}
+
+text = \lyricmode {
+\set stanza = "1." Ma- ry had a lit- tle lamb,
+its fleece was white as snow.
+}
+
+\book{
+ \score{ <<
+ \new Voice = "one" { \melody }
+ \new Lyrics \lyricsto "one" \text
+ >>
+ \layout { }
+ }
+ \markup { \column{
+ \line{ Verse 2. }
+ \line{ All the children laughed and played }
+ \line{ To see a lamb at school. }
+ }
+ }
+ \markup{
+ \wordwrap-string #"
+ Verse 3.
+
+ Mary took it home again,
+
+ It was against the rule."
+ }
+}
+@end lilypond
+
+
Names of singers can also be added. They are printed at the start of
the line, just like instrument names. They are created by setting
@code{vocalName}. A short version may be entered as @code{vocNam}.
}
@end lilypond
-You can display alternate (or divisi) lyrics by naming voice
-contexts and attaching lyrics to those specific contexts.
-
-@lilypond[verbatim,ragged-right,quote]
-\score{ <<
- \new Voice = "melody" {
- \relative c' {
- c4
- <<
- { \voiceOne c8 e }
- \new Voice = "splitpart" { \voiceTwo c4 }
- >>
- \oneVoice c4 c | c
- }
- }
- \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
- \new Lyrics \lyricsto "splitpart" { will }
->> }
-@end lilypond
-
-
-You can use this trick to display different lyrics for a repeated
-section.
-
-@lilypond[verbatim,ragged-right,quote]
-\score{ <<
- \new Voice = "melody" \relative c' {
- c2 e | g e | c1 |
- \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
- a2 b | c1}
- \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
- do mi sol mi do
- la si do }
- \new Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
- do re mi fa sol }
- \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
- dodo rere mimi fafa solsol }
->>
-}
-@end lilypond
-
@seealso
-Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber}, @internalsref{VocalName}.
+Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber},
+@internalsref{VocalName}.
* String number indications::
* Tablatures basic::
* Non-guitar tablatures::
+* Banjo tablatures::
* Fret diagrams::
* Other guitar issues::
@end menu
>>
@end lilypond
+
+@commonprop
+
+To print tablatures with stems down and horizontal beams,
+initialize the @code{TabStaff} with this code:
+
+@example
+\stemDown
+\override Beam #'damping = #100000
+@end example
+
@seealso
Program reference: @internalsref{TabStaff}, @internalsref{TabVoice}.
@subsection Non-guitar tablatures
@cindex Non-guitar tablatures
-You can change the number of strings, by setting the number of lines
-in the @internalsref{TabStaff}.
-
You can change the tuning of the strings. A string tuning is given as
a Scheme list with one integer number for each string, the number
being the pitch (measured in semitones relative to middle C) of an
open string. The numbers specified for @code{stringTuning} are the
numbers of semitones to subtract or add, starting the specified pitch
-by default middle C, in string order. In the next example,
+by default middle C, in string order. LilyPond automatically calculates
+the number of strings by looking at @code{stringTuning}.
+
+In the next example,
@code{stringTunings} is set for the pitches e, a, d, and g
@lilypond[quote,ragged-right,fragment,verbatim]
>>
@end lilypond
+LilyPond comes with predefined string tunings for banjo, mandolin, guitar
+and bass guitar.
+
+@example
+\set TabStaff.stringTunings = #bass-tuning
+@end example
+
+The default string tuning is @code{guitar-tuning} (the standard EADGBE
+tuning).
+Some other predefined tunings are @code{guitar-open-g-tuning},
+@code{mandolin-tuning} and @code{banjo-open-g-tuning}.
+
+@seealso
+
+The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
+tunings.
+Program reference: @internalsref{Tab_note_heads_engraver}.
+
@refbugs
No guitar special effects have been implemented.
+
+
+@node Banjo tablatures
+@subsection Banjo tablatures
+@cindex Banjo tablatures
+
+LilyPond has basic support for five stringed banjo. When making tablatures
+for five stringed banjo, use the banjo tablature format function to get
+correct
+fret numbers for the fifth string:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new TabStaff <<
+ \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
+ \set TabStaff.stringTunings = #banjo-open-g-tuning
+ {
+ \stemDown
+ g8 d' g'\5 a b g e d' |
+ g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
+ g4
+ }
+>>
+@end lilypond
+
+A number of common tunings for banjo are predefined in LilyPond:
+@code{banjo-c-tuning} (gCGBD), @code{banjo-modal-tuning} (gDGCD),
+@code{banjo-open-d-tuning} (aDF#AD) and @code{banjo-open-dm-tuning}
+(aDFAD).
+
+These tunings may be converted to four string banjo tunings using the
+@code{four-string-banjo} function:
+
+@example
+\set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)
+@end example
+
@seealso
-Program reference: @internalsref{Tab_note_heads_engraver}.
+The file @file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.
@node Fret diagrams
@seealso
-In this manual: @ref{Rests} gives a general introduction into the use of rests.
+In this manual: @ref{Rests} gives a general introduction into the use of
+rests.
@node Ancient clefs
{
\set Score.timing = ##f
\set Score.barAlways = ##t
- s_\markup { "\\time 4/4" }^\markup { " " \musicglyph #"timesig.neomensural44" }
+ s_\markup { "\\time 4/4" }^\markup { " " \musicglyph
+#"timesig.neomensural44" }
s
- s_\markup { "\\time 2/2" }^\markup { " " \musicglyph #"timesig.neomensural22" }
+ s_\markup { "\\time 2/2" }^\markup { " " \musicglyph
+#"timesig.neomensural22" }
s
- s_\markup { "\\time 6/4" }^\markup { " " \musicglyph #"timesig.neomensural64" }
+ s_\markup { "\\time 6/4" }^\markup { " " \musicglyph
+#"timesig.neomensural64" }
s
- s_\markup { "\\time 6/8" }^\markup { " " \musicglyph #"timesig.neomensural68" }
+ s_\markup { "\\time 6/8" }^\markup { " " \musicglyph
+#"timesig.neomensural68" }
\break
- s_\markup { "\\time 3/2" }^\markup { " " \musicglyph #"timesig.neomensural32" }
+ s_\markup { "\\time 3/2" }^\markup { " " \musicglyph
+#"timesig.neomensural32" }
s
- s_\markup { "\\time 3/4" }^\markup { " " \musicglyph #"timesig.neomensural34" }
+ s_\markup { "\\time 3/4" }^\markup { " " \musicglyph
+#"timesig.neomensural34" }
s
- s_\markup { "\\time 9/4" }^\markup { " " \musicglyph #"timesig.neomensural94" }
+ s_\markup { "\\time 9/4" }^\markup { " " \musicglyph
+#"timesig.neomensural94" }
s
- s_\markup { "\\time 9/8" }^\markup { " " \musicglyph #"timesig.neomensural98" }
+ s_\markup { "\\time 9/8" }^\markup { " " \musicglyph
+#"timesig.neomensural98" }
\break
- s_\markup { "\\time 4/8" }^\markup { " " \musicglyph #"timesig.neomensural48" }
+ s_\markup { "\\time 4/8" }^\markup { " " \musicglyph
+#"timesig.neomensural48" }
s
- s_\markup { "\\time 2/4" }^\markup { " " \musicglyph #"timesig.neomensural24" }
+ s_\markup { "\\time 2/4" }^\markup { " " \musicglyph
+#"timesig.neomensural24" }
}
@end lilypond
@code{\[ \stropha b \stropha b \stropha a \]}
@end multitable
+The ligatures listed above mainly serve as a limited, but still
+representative pool of Gregorian ligature examples. Virtually, within
+the ligature delimiters @code{\[} and @code{\]}, any number of heads
+may be accumulated to form a single ligature, and head prefixes like
+@code{\pes}, @code{\flexa}, @code{\virga}, @code{\inclinatum},
+etc. may be mixed in as desired. The use of the set of rules that
+underlies the construction of the ligatures in the above table is
+accordingly extrapolated. This way, infinitely many different
+ligatures can be created.
+
+@c TODO: create a regression or tips & tricks example document with
+@c even more Gregorian ligatures, and add a link to this document
+@c here.
+
@refcommands
The following head prefixes are supported
@cindex @code{\quilisma}
@code{\quilisma},
@cindex @code{\deminutum}
-@code{\deminutum}.
+@code{\deminutum},
+@cindex @code{\cavum}
+@code{\cavum},
+@cindex @code{\linea}
+@code{\linea}.
Head prefixes can be accumulated, though restrictions apply. For
example, either @code{\descendens} or @code{\ascendens} can be applied
@end example
Accidentals and plus signs can appear before or after the numbers,
-depending on the @code{figuredBassAlterationDirection} and @code{figuredBassPlusDirection}
+depending on the @code{figuredBassAlterationDirection} and
+@code{figuredBassPlusDirection}
properties
@lilypond
@end ifnotinfo
@ifinfo
@c workaround for makeinfo-4.6: line breaks and multi-column cookies
-@image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png} @image{lily-flat-bw,,,png}
+@image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png}
+@image{lily-flat-bw,,,png}
@end ifinfo
@item @tab
eye deceives us a little; not only does it notice the distance between
note heads, it also takes into account the distance between
consecutive stems. As a result, the notes of an up-stem/@/down-stem
-combination should be put farther apart, and the notes of a down-stem/@/up-stem
+combination should be put farther apart, and the notes of a
+down-stem/@/up-stem
combination should be put closer together, all depending on the
combined vertical positions of the notes. The first two measures are
printed with this correction, the last two measures without. The notes
users should start here.
@item
-@emph{@ref{Example templates}}
-provides templates of LilyPond pieces. Just cut and paste a
-template into a file, add notes, and you're done!
-
-@item
-@emph{@ref{Putting it all together}}
+@emph{@ref{Working on LilyPond projects}}
demonstrates practical uses of LilyPond.
@item
@emph{@ref{Literature list}}
contains a set of useful reference books for those who wish to know
more on notation and engraving.
+
+@item
+@emph{@ref{Example templates}}
+provides templates of LilyPond pieces. Just cut and paste a
+template into a file, add notes, and you're done!
+
@end itemize
+
Once you are an experienced user, you can use the manual as reference:
there is an extensive index@footnote{If you are looking for something,
and you cannot find it in the manual, that is considered a bug. In
@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+
@node Running LilyPond
@chapter Running LilyPond
@menu
* Invoking lilypond::
* Notes for the MacOS X app::
-* Error messages::
* Updating files with convert-ly::
* Reporting bugs::
+* Error messages::
* Editor support::
+* Point and click::
@end menu
@node Invoking lilypond
not to change any system defaults from within Scheme.}
-@section Command line options
+@subsection Command line options
The following options are supported:
@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
+@cindex point and click, command line
+
@example
-dno-point-and-click
@end example
-dpoint-and-click='#f'
@end example
-@cindex point and click
+Another notable option is
-Setting the @code{help} option will print a summary of the options
+@example
+-dpaper-size=\"letter\"
+@end example
+
+@noindent
+Note that the string must be enclosed in escaped quotes ( @code{\"} ).
+
+Setting the @code{-dhelp} option will print a summary of the options
available, and exit.
@item -h,--help
@end table
-@section Environment variables
+@subsection Environment variables
@cindex LANG
Note that @var{path/to} will generally be @code{/Applications/}.
-@node Error messages
-@section Error messages
-
-@cindex error messages
-Different error messages can appear while compiling a file:
-
-@table @emph
-@cindex warning
-
-@item Warning
-Something looks suspect. If you are requesting something out of the
-ordinary then you will understand the message, and can ignore it.
-However, warnings usually indicate that something is wrong with the
-input file.
-
-@item Error
-Something is definitely wrong. The current processing step (parsing,
-interpreting, or formatting) will be finished, but the next step will
-be skipped.
-
-@cindex error
-@cindex fatal error
-@item Fatal error
-Something is definitely wrong, and LilyPond cannot continue. This
-happens rarely. The most usual cause is misinstalled fonts.
-
-@cindex trace, Scheme
-@cindex call trace
-@cindex Scheme error
-@item Scheme error
-Errors that occur while executing Scheme code are caught by the Scheme
-interpreter. If running with the verbose option (@code{-V} or
-@code{--verbose}) then a call trace of the offending
-function call is printed.
-
-@cindex Programming error
-@item Programming error
-There was some internal inconsistency. These error messages are
-intended to help the programmers and debuggers. Usually, they can be
-ignored. Sometimes, they come in such big quantities that they obscure
-other output. In this case, file a bug-report.
-
-@item Aborted (core dumped)
-This signals a serious programming error that caused the program to
-crash. Such errors are considered critical. If you stumble on one,
-send a bug-report.
-
-
-@end table
-
-@cindex errors, message format
-If warnings and errors can
-be linked to some part of the input file, then error messages have the
-following form
-
-@example
-@var{filename}:@var{lineno}:@var{columnno}: @var{message}
-@var{offending input line}
-@end example
-
-A line-break is inserted in the offending line to indicate the column
-where the error was found. For example,
-
-@example
-test.ly:2:19: error: not a duration: 5:
- @{ c'4 e'5
- g' @}
-@end example
-
-These locations are LilyPond's best guess about where the warning or
-error occurred, but (by their very nature) warnings and errors occur
-when something unexpected happens. If you can't see an error in the
-indicated line of your input file, try checking one or two lines
-above the indicated position.
-
-
@node Updating files with convert-ly
@section Updating with @command{convert-ly}
Copy and paste from CVS, last updated
Aug 18, 2005
-http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
+http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/
+convert-ly.txt?rev=HEAD&content-type=text/plain
@end ignore
@verbatim
-There are a few things that the convert-ly cannot handle. Here's a list of limitations
+There are a few things that the convert-ly cannot handle. Here's a list of
+limitations
that the community has complained about.
-This bug report structure has been chosen because convert-ly has a structure that doesn't
-allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
+This bug report structure has been chosen because convert-ly has a structure
+that doesn't
+allow to smoothly implement all needed changes. Thus this is just a wishlist,
+placed
here for reference.
1.6->2.0:
- Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
+ Doesn't always convert figured bass correctly, specifically things like {<
+>}. Mats' comment on working around this:
To be able to run convert-ly
on it, I first replaced all occurencies of '{<' to some dummy like '{#'
and similarly I replaced '>}' with '&}'. After the conversion, I could
then change back from '{ #' to '{ <' and from '& }' to '> }'.
Doesn't convert all text markup correctly. In the old markup syntax,
- it was possible to group a number of markup commands together within parentheses, e.g.
+ it was possible to group a number of markup commands together within
+parentheses, e.g.
-#'((bold italic) "string")
This will incorrectly be converted into
-\markup{{\bold italic} "string"}
-\markup{\bold \italic "string"}
2.0->2.2:
Doesn't handle \partcombine
- Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
+stanzas.
2.0->2.4:
\magnify isn't changed to \fontsize.
- \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
- \rced => \!
- \rc => \!
2.2->2.4:
- \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
+ \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
+converted.
2.4.2->2.5.9
\markup{ \center-align <{ ... }> } should be converted to:
\markup{ \center-align {\line { ... }} }
It seems that placement of accidentals is broken. In the
following example, the accidental touches the note head.
-Using Mac OSX 10.3.7, fink package lilypond-devel
+Using Mac OSX 10.3.7, lilypond 2.7.32
\version "2.7.32"
\layout { ragged-right = ##t }
}
@end lilypond
+@node Error messages
+@section Error messages
+
+@cindex error messages
+Different error messages can appear while compiling a file:
+
+@table @emph
+@cindex warning
+
+@item Warning
+Something looks suspect. If you are requesting something out of the
+ordinary then you will understand the message, and can ignore it.
+However, warnings usually indicate that something is wrong with the
+input file.
+
+@item Error
+Something is definitely wrong. The current processing step (parsing,
+interpreting, or formatting) will be finished, but the next step will
+be skipped.
+
+@cindex error
+@cindex fatal error
+@item Fatal error
+Something is definitely wrong, and LilyPond cannot continue. This
+happens rarely. The most usual cause is misinstalled fonts.
+
+@cindex trace, Scheme
+@cindex call trace
+@cindex Scheme error
+@item Scheme error
+Errors that occur while executing Scheme code are caught by the Scheme
+interpreter. If running with the verbose option (@code{-V} or
+@code{--verbose}) then a call trace of the offending
+function call is printed.
+
+@cindex Programming error
+@item Programming error
+There was some internal inconsistency. These error messages are
+intended to help the programmers and debuggers. Usually, they can be
+ignored. Sometimes, they come in such big quantities that they obscure
+other output. In this case, file a bug-report.
+
+@item Aborted (core dumped)
+This signals a serious programming error that caused the program to
+crash. Such errors are considered critical. If you stumble on one,
+send a bug-report.
+
+
+@end table
+
+@cindex errors, message format
+If warnings and errors can
+be linked to some part of the input file, then error messages have the
+following form
+
+@example
+@var{filename}:@var{lineno}:@var{columnno}: @var{message}
+@var{offending input line}
+@end example
+
+A line-break is inserted in the offending line to indicate the column
+where the error was found. For example,
+
+@example
+test.ly:2:19: error: not a duration: 5:
+ @{ c'4 e'5
+ g' @}
+@end example
+
+These locations are LilyPond's best guess about where the warning or
+error occurred, but (by their very nature) warnings and errors occur
+when something unexpected happens. If you can't see an error in the
+indicated line of your input file, try checking one or two lines
+above the indicated position.
+
+
@node Editor support
@section Editor support
of a symbol in the graphical output. See @ref{Point and click}.
+@node Point and click
+@section Point and click
+@cindex point and click
+
+
+Point and click lets you find notes in the input by clicking on them
+in the PDF viewer. This makes it easier to find input that causes
+some error in the sheet music.
+
+When this functionality is active, LilyPond adds hyperlinks to the PDF
+file. These hyperlinks are sent to the web-browser, which opens a
+text-editor with the cursor in the right place.
+
+To make this chain work, you should configure your PDF viewer to
+follow hyperlinks using the @file{lilypond-invoke-editor} script
+supplied with LilyPond.
+
+For Xpdf on Unix, the following should be present in
+@file{xpdfrc}@footnote{On unix, this file is found either in
+@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
+
+@example
+urlCommand "lilypond-invoke-editor %s"
+@end example
+
+The program @file{lilypond-invoke-editor} is a small helper
+program. It will invoke an editor for the special @code{textedit}
+URIs, and run a web browser for others. It tests the environment
+variable @code{EDITOR} for the following patterns,
+
+@table @code
+@item emacs
+ this will invoke
+@example
+emacsclient --no-wait +@var{line}:@var{column} @var{file}
+@end example
+@item vim
+ this will invoke
+@example
+gvim --remote +:@var{line}:norm@var{char} @var{file}
+@end example
+
+@item nedit
+this will invoke
+@example
+ nc -noask +@var{line} @var{file}'
+@end example
+@end table
+
+The environment variable @code{LYEDITOR} is used to override this. It
+contains the command line to start the editor, where @code{%(file)s},
+@code{%(column)s}, @code{%(line)s} is replaced with the file, column
+and line respectively. The setting
+
+@example
+emacsclient --no-wait +%(line)s:%(column)s %(file)s
+@end example
+
+@noindent
+for @code{LYEDITOR} is equivalent to the standard emacsclient
+invocation.
+
+
+@cindex file size, output
+
+The point and click links enlarge the output files significantly. For
+reducing the size of PDF and PS files, point and click may be switched
+off by issuing
+
+@example
+#(ly:set-option 'point-and-click #f)
+@end example
+
+@noindent
+in a @file{.ly} file. Alternately, you may pass this as an command-line
+option
+
+@example
+lilypond -dno-point-and-click file.ly
+@end example
@dircategory GNU music project
@direntry
-@ignore
-(I think)
-Current version of the manual: 2.8.0
-****** Please update this whenever you run convert-ly on the docs.
-
-convert-ly --from=... --to=... --no-version *.itely
-
-%%%%%
-
-Distributions will want to install lilypond.info in postinstall, doing:
-
- install-info --info-dir=/usr/share/info out/lilypond.info
-
-%%%%%
-
- * Prepend GNU for dir, must be unique.
-
- * Do not list the `lilypond' node at toplevel, so that `info lilypond'
- goes to Top.
-
- * List all commands in direntry.
-
-@c * lilypond: (lilypond/lilypond)Running LilyPond. Invoking the
-@c LilyPond program.
-
-@end ignore
* LilyPond: (lilypond/lilypond). The GNU music typesetter.
* abc2ly: (lilypond/lilypond)Invoking abc2ly. Importing ABC.
* convert-ly: (lilypond/lilypond)Invoking convert-ly. Older LilyPond versions.
@end direntry
+@c don't remove this comment.
@ignore
@omfcreator Han-Wen Nienhuys, Jan Nieuwenhuizen and Graham Percival
@omfdescription User manual of the LilyPond music engraving system
@omflanguage English
@end ignore
-@c don't remove this comment.
-
-@ignore
-
-HINTS FOR STYLE
-
-* Do not forget to create @cindex entries for new sections of text.
-
-* Try not to use punctuation between an introductory sentence and
- display material (music, example code).
-
-* Do not refer to LilyPond in the text. The reader knows what the
- manual is about. If you do, capitalization is LilyPond.
-
-* If you explicitly refer to `lilypond', the program (or any other
- command to be executed), say `@command{lilypond}'.
-
-* Do not explicitly refer to the reader/user. There is no one else
- besides the reader and the writer.
-
-* Do not use abbreviations (don't, won't, etc.). If you do, use a
- comma after it:
-
- blabla blabla, i.e., blabla blabla
-
-* Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'').
-
-* The above three suggestions refer to the formal Notation Manual
- (chapters 5 and up). In the Tutorial, Example templates, and
- Putting it all together, you may write more colloquially
-
-* The use of the word `illegal' is inappropriate in most cases. Say
- `invalid' instead.
-
-* Avoid long stretches of input code. Noone is going to read them in
- print. Instead refer to an example input file (@inputfileref), these
- are clickable in HTML.
-
-* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
-
-* Colon usage
-
- 0. Do not use a colon to introduce examples, sentences just continue
-
- in the display material.
-
- 1. To introduce lists
- 2. When beginning a quote: "So, he said,..."
- This usage is rarer. Americans often just use a comma.
- 3. When adding a defining example at the end of a sentence.
-
-* To produce good looking texinfo output (for both TTY and DVI) some
- additional formatting rules should be followed.
-
- . Do not use tabs. They expand to nothing in DVI output.
-
- . Do not use spaces at the beginning of a line (except in @example
- or @verbatim environments), and do not use more than a single space
- between words. `makeinfo' copies the input lines verbatim without
- removing those spaces.
-
- . Variables or numbers which consist of a single character (probably
- followed by a punctuation mark) should be tied properly, either to
- the previous or the next word. Example:
-
- The variable@tie{}@var{a} ...
-
- . To get consistent indentation in the DVI output it is better to avoid
- the @verbatim environment. Use the @example environment instead if
- possible, but without extraneous indentation. For example, this
-
- @example
- foo {
- bar
- }
- @end example
-
- should be replaced with
-
- @example
- foo {
- bar
- }
- @end example
-
- where `@example' starts the line (without leading spaces).
-
- . Use the `quote' option in @lilypond commands if possible.
-
- . Do not compress the input vertically; this is, do not use
-
- Beginning of logical unit
- @example
- ...
- @end example
- continuation of logical unit
-
- but
-
- Beginning of logical unit
-
- @example
- ...
- @end example
-
- @noindent
- continuation of logical unit
-
- This makes it easier to not forget `@noindent'.
-
- . Non-ASCII characters which are in utf-8 should be directly used;
- this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
- all such characters appear in all output formats.
-
-@end ignore
@ifhtml
-This document is also available in @uref{source/Documentation/user/lilypond.pdf,PDF}.
+This document is also available as a
+@uref{source/Documentation/user/lilypond.pdf,PDF}.
@end ifhtml
@documentlanguage en
@documentencoding utf-8
+@c FIXME: Index has two alphabetically sorted lists @code vs plain?
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@vskip 20pt
-@c Not yet debugged or reported. This crashes gs-8.01:
-@c compiling gs-8.01 right now... -- jcn
@lilypond[ragged-right]
\score {
- \context Lyrics {
- \override Score.RehearsalMark #'self-alignment-X = #LEFT
- \override Score.RehearsalMark #'font-size = #-2
- \mark #(ly:export (string-append
- "(For LilyPond version " (lilypond-version) ")"))
- s2
- }
- \layout {
- indent = 0.0\pt
- ragged-right = ##t
- }
+ \context Lyrics {
+ \override Score.RehearsalMark #'self-alignment-X = #LEFT
+ \override Score.RehearsalMark #'font-size = #-2
+ \mark #(ly:export (string-append
+ "(For LilyPond version " (lilypond-version) ")"))
+ s2
+ }
+ \layout {
+ indent = 0.0\pt
+ }
}
@end lilypond
@cindex web site
@cindex URL
-A further source of information is the website, which can be found at
+More information can be found at
@uref{http://@/www@/.lilypond@/.org/}. The website contains on-line copies
of this and other documentation.
@include dedication.itely
@menu
+Learning Manual
+
* Preface:: Preface.
* Introduction:: What, Why, How.
* Tutorial:: A tutorial introduction.
-* Example templates:: Larger examples.
-* Putting it all together:: Demonstrates real-life LilyPond usage.
-* Running LilyPond:: Operation.
+* Putting it all together:: More explanation about LilyPond concepts.
+* Working on LilyPond projects:: Discusses real-life usage.
+* Tweaking output:: Introduction to modifying output.
+
+Notation Reference
+
* Basic notation:: Standard musical notation.
-* Instrument-specific notation:: Notation that is only used for some
- instruments.
+* Instrument-specific notation:: Specialized notation.
* Advanced notation:: Less frequently used notation.
* Changing defaults:: Tuning output.
* Global issues:: What LilyPond produces.
+* Interfaces for programmers:: Expert usage.
+
+Technical Details
-* Interfaces for programmers::
+* Running LilyPond:: Operation.
* LilyPond-book:: Integrating text and music.
* Converting from other formats:: Converting to lilypond source format.
-* Literature list::
-* Scheme tutorial::
-* Notation manual details::
-* Point and click::
-* Cheat sheet::
-* GNU Free Documentation License:: FDL.
+
+Appendices
+
+* Literature list:: Reference works about music notation.
+* Scheme tutorial:: Programming inside LilyPond.
+* Notation manual tables:: Tables and charts.
+* Example templates:: Ready-made templates.
+* Cheat sheet:: Summary of LilyPond syntax.
+* GNU Free Documentation License:: License of this document.
* LilyPond index::
@end menu
@end ifnottex
@include preface.itely
@include introduction.itely
@include tutorial.itely
-@include examples.itely
@include putting.itely
-@include invoking.itely
+@include working.itely
+@include tweaks.itely
+
@include basic-notation.itely
@include instrument-notation.itely
@include advanced-notation.itely
@include changing-defaults.itely
@include global.itely
-
@include programming-interface.itely
+
+@include invoking.itely
@include lilypond-book.itely
@include converters.itely
-@c FIXME: Index has two alphabetically sorted lists @code vs plain?
@include literature.itely
@include scheme-tutorial.itely
@include notation-appendices.itely
-@include point-and-click.itely
+@include examples.itely
@include cheatsheet.itely
@include fdl.itexi
@end direntry
@ifhtml
-This document is also available in @uref{source/Documentation/user/music-glossary.pdf,PDF}
+This document is also available in
+@uref{source/Documentation/user/music-glossary.pdf,PDF}
and as @uref{source/Documentation/user/music-glossary.html,one big page}.
@end ifhtml
NL: cent,
DK: cent,
S: cent,
-FI: sentti, puolisävelaskeleen sadasosa tasavireisessä viritysjärjestelmässä.
+FI: sentti, puolisävelaskeleen sadasosa tasavireisessä
+viritysjärjestelmässä.
Logarithmic unit of measurement. 1@tie{}cent is 1/1200 of an octave (1/100
of an equally tempered @aref{semitone}).
S: ackord,
FI: sointu.
-Three or more tones sounding simultaneously. In traditional European music the
-base chord is a @emph{triad} consisting of 2@w{ }thirds. @emph{Major} (major +
+Three or more tones sounding simultaneously. In traditional European music
+the
+base chord is a @emph{triad} consisting of 2@w{ }thirds. @emph{Major} (major
++
minor @aref{third}) as well as @emph{minor} (minor + major third)
chords may be extended with more thirds. Four-tone @emph{seventh chords}
and five-tone @emph{ninth} major chords are most often used as dominants
\context Voice \relative c'' {
<g e c >1 < a f d > < b g e >
<c a f > < d b g > < e c a > < f d b > }
-\context Lyrics \lyrics { T Sp Dp S D Tp \markup{ D\translate #(cons -2 0) {"|"} } }
+\context Lyrics \lyrics {
+ T Sp Dp S D Tp \markup{ D\translate #(cons -2 0) {"|"} } }
@end lilypond
@node G
S: intervall,
FI: intervalli, kahden sävelen korkeusero.
-Difference in pitch between two notes. Intervals may be perfect, minor, major,
+Difference in pitch between two notes. Intervals may be perfect, minor,
+major,
diminished, or augmented. The augmented fourth and the diminished fifth are
identical (@aref{enharmonic}) and are called @emph{tritonus}
because they consist of three @aref{whole tone}s. The addition
FI: nuotin aika-arvo.
Note values (durations) are measured as fractions, normally 1/2, of the next
-higher note value. The longest duration normally used is called @emph{brevis},
+higher note value. The longest duration normally used is called
+@emph{brevis},
but sometimes (mostly in pre-baroque music) the double length note value
@emph{longa} is used.
>>
@end lilypond
-Other frequently used ornaments are the @emph{turn}, the @emph{mordent}, and the
+Other frequently used ornaments are the @emph{turn}, the @emph{mordent}, and
+the
@emph{prall} (inverted mordent).
@lilypond[fragment,line-width=13.0\cm]
NL: syntonische komma,
DK: syntonisk komma,
S: syntoniskt komma,
-FI: syntoninen komma, terssien taajuusero luonnollisessa ja Pytagorisessa viritysjärjestelmässä.
+FI: syntoninen komma, terssien taajuusero luonnollisessa ja Pytagorisessa
+viritysjärjestelmässä.
Difference between the natural third and the third obtained by Pythagorean
tuning (@aref{Pythagorean comma}), equal to 22@w{ }cents.
FI: viritysavain.
A two-pronged piece of steel used to indicate absolute pitch. Tuning forks
-give the international pitch for the tone @emph{a} (440 vibrations per second).
+give the international pitch for the tone @emph{a} (440 vibrations per
+second).
@node turn
@section turn
@item
-@item @strong{c-sharp} @tab do diesis @tab do diesis @tab ut dièse @tab Cis @tab cis @tab
+@item @strong{c-sharp} @tab do diesis @tab do diesis @tab ut dièse @tab
+Cis @tab cis @tab
cis @tab cis @tab cis
@item
-@item @strong{d-flat} @tab re bemolle @tab re bemolle @tab ré bémol @tab Des @tab des @tab
+@item @strong{d-flat} @tab re bemolle @tab re bemolle @tab ré bémol @tab
+Des @tab des @tab
des @tab des @tab des
@item
@item
-@item @strong{g} @tab sol @tab sol @tab sol @tab G @tab g @tab g @tab g @tab g
+@item @strong{g} @tab sol @tab sol @tab sol @tab G @tab g @tab g @tab g
+@tab g
@item
-@item @strong{a-flat} @tab la bemol @tab la bemolle @tab la bémol @tab As @tab as @tab as
+@item @strong{a-flat} @tab la bemol @tab la bemolle @tab la bémol @tab As
+@tab as @tab as
@tab as @tab as
@item
@item
-@item @strong{a-sharp} @tab la sostenido @tab la diesis @tab la dièse @tab Ais @tab ais @tab
+@item @strong{a-sharp} @tab la sostenido @tab la diesis @tab la dièse @tab
+Ais @tab ais @tab
ais @tab ais @tab ais
@item
-@item @strong{b-flat} @tab si bemol @tab si bemolle @tab si bémol @tab B @tab bes @tab b
+@item @strong{b-flat} @tab si bemol @tab si bemolle @tab si bémol @tab B
+@tab bes @tab b
@tab b @tab b
@item
@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
-@node Notation manual details
-@appendix Notation manual details
+@node Notation manual tables
+@appendix Notation manual tables
@menu
* Chord name chart::
@node Putting it all together
@chapter Putting it all together
-This section explains how to use the rest of the documentation and
-how to solve common problems.
+This chapter discusses general LilyPond concepts and how to
+create @code{\score} blocks.
+
@menu
-* Suggestions for writing LilyPond files::
* Extending the templates::
-* Fixing overlapping notation::
* How LilyPond files work::
* Score is a single musical expression::
-* Troubleshooting (taking it all apart)::
@end menu
-@node Suggestions for writing LilyPond files
-@section Suggestions for writing LilyPond files
-
-Now you're ready to begin writing larger LilyPond files -- not just the
-little examples in the tutorial, but whole pieces. But how should you
-go about doing it?
-
-The best answer is ``however you want to do it.'' As long as LilyPond
-can understand your files and produces the output that you want, it
-doesn't matter what your files look like. That said, sometimes we
-make mistakes when writing files. If LilyPond can't understand your
-files, or produces output that you don't like, how do you fix the
-problem?
-
-Here are a few suggestions that can help you to avoid or fix
-problems:
-
-@itemize @bullet
-@item Include @code{\version} numbers in every file. Note that all
-templates contain a @code{\version "2.7.32"} string. We
-highly recommend that you always include the @code{\version}, no matter
-how small your file is. Speaking from personal experience, it's
-quite frustrating to try to remember which version of LilyPond you were
-using a few years ago. @code{convert-ly} requires you to declare
-which version of LilyPond you used.
-
-@item Include checks: See @ref{Bar check} and @ref{Octave check}. If you
-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
-very complex music, every bar.
-
-@item One bar per line of text. If there is anything complicated, either in the music
-itself or in the output you desire, it's often good to write only one bar
-per line. Saving screen space by cramming eight bars per line just isn't
-worth it if you have to `debug' your files.
-
-@item Comment your files, with either bar numbers (every so often) or
-references to musical themes (``second theme in violins'', ``fourth
-variation''). You may not need it when you're writing the piece for
-the first time, but if you want to go back and change something two
-or three years later, you won't know how your file is structured if you
-didn't comment the file.
-
-@item Indent your braces. A lot of problems are caused by an imbalance
-in the number of @code{@{} and @code{@}}.
-
-@end itemize
-
-If you are entering music from an existing score (i.e. typesetting a
-piece of existing sheet music),
-
-@itemize @bullet
-
-@item Enter one manuscript (the physical copy) system at a time (but still
-only one bar per line of text), and
-check each system when you finish it. You may use the
-@code{showLastLength} command to speed up processing -- see
-@ref{Skipping corrected music}.
-
-@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
-in the input file whenever the manuscript has a line break. This
-makes it much easier to compare the LilyPond music to the original
-music. When you are finished proofreading your score, you may
-define @code{mBreak = @{ @}} to remove all those line breaks. This
-will allow LilyPond to place line breaks wherever it feels are
-best.
-
-@end itemize
-
-
@node Extending the templates
@section Extending the templates
@code{\layout} or @code{\midi}.
If we simply cut and paste the @code{melody} section, we would end up with
-two @code{melody} sections. So let's rename them. We'll call the one
-for the soprano @code{sopranoMusic}, and the one for the cello can be
-called @code{celloMusic}. While we're doing this, let's rename @code{text}
+two @code{melody} sections. So let's rename them. We'll call the section
+for the soprano @code{sopranoMusic} and the section for the cello
+@code{celloMusic}. While we're doing this, let's rename @code{text}
to be @code{sopranoLyrics}. Remember to rename both instances of all
these names -- both the initial definition (the
@code{melody = relative c' @{ } part) and the name's use (in the
@noindent
underneath the soprano stuff. We also need to add @code{<<} and
@code{>>} around the music -- that tells LilyPond that there's
-more than one thing (in this case staff) happening at once. The
+more than one thing (in this case, @code{Staff}) happening at once. The
@code{\score} looks like this now
@example
-@node Fixing overlapping notation
-@section Fixing overlapping notation
-
-This may come as a surprise, but LilyPond isn't perfect. Some notation
-elements can overlap. This is unfortunate, but (in most cases) is easily
-solved.
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-@cindex padding
-
-The easiest solution is to increase the distance between the object
-(in this case text, but it could easily be fingerings or dynamics
-instead) and the note. In LilyPond, this is called the
-@code{padding} property; it is measured in staff spaces. For most
-objects, this value is around 1.0 or less (it varies with each
-object). We want to increase it, so let's try 1.5
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\once \override TextScript #'padding = #1.5
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-That looks better, but it isn't quite big enough. After experimenting
-with a few values, we think 2.3 is the best number in this case. However,
-this number is merely the result of experimentation and my personal
-taste in notation. Try the above example with 2.3... but also try higher
-(and lower) numbers. Which do you think looks the best?
-
-@cindex extra-offset
-
-Another solution gives us complete control over placing the object -- we
-can move it horizontally or vertically. This is done with the
-@code{extra-offset} property. It is slightly more complicated and can
-cause other problems. When we move objects with @code{extra-offset},
-the movement is done after LilyPond has placed all other objects. This means
-that the result can overlap with other objects.
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-With @code{extra-offset}, the first number controls the horizontal
-movement (left is negative); the second number controls the vertical
-movement (up is positive). After a bit of experimenting, we decided
-that these values look good
-
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-@noindent
-Again, these numbers are simply the result of a few experiments and
-looking at the output. You might prefer the text to be slightly higher,
-or to the left, or whatever. Try it and look at the result!
-
-
-@seealso
-
-This manual: @ref{The \override command}, @ref{Common tweaks}.
-
-
@node How LilyPond files work
@section How LilyPond files work
@end example
@noindent
-Most people put some of those commands outside the
+Some people put some of those commands outside the
@code{\score} block -- for example, @code{\header} is
-almost always placed above the @code{\score}. That's
-just another shorthand.
+often placed above the @code{\score}. That's just
+another shorthand that LilyPond accepts.
Another great shorthand is the ability to define
variables. All the templates use this
@code{\melody}. There's nothing special about the
names -- it could be @code{melody}, @code{global},
@code{pianorighthand}, or @code{foofoobarbaz}. You
-can use whatever variable names you want.
+can use whatever variable names you want. For
+more details, see
+@ref{Saving typing with identifiers and functions}.
For a complete definition
of the input format, see @ref{File structure}.
that there @emph{is} no mystery. This line explains it
all:
-@example
-A @code{\score} must begin with a single music expression.
-@end example
+@quotation
+@emph{A @code{\score} must begin with a single music expression.}
+@end quotation
@noindent
You may find it useful to review
text editor!
-@node Troubleshooting (taking it all apart)
-@section Troubleshooting (taking it all apart)
-
-Sooner or later, you will write a file that LilyPond cannot
-compile. The messages that LilyPond gives may help
-you find the error, but in many cases you need to do some
-investigation to determine the source of the problem.
-
-The most powerful tools for this purpose are the
-single line comment (indicated by @code{%}) and the block
-comment (indicated by @code{%@{ ... %@}}). If you don't
-know where a problem is, start commenting out huge portions
-of your input file. After you comment out a section, try
-compiling the file again. If it works, then the problem
-must exist in the portion you just commented. If it doesn't
-work, then keep on commenting out material until you have
-something that works.
-
-In an extreme case, you might end up with only
-
-@example
-\score @{
- <<
- % \melody
- % \harmony
- % \bass
- >>
- \layout@{@}
-@}
-@end example
-
-@noindent
-(in other words, a file without any music)
-
-If that happens, don't give up. Uncomment a bit -- say,
-the bass part -- and see if it works. If it doesn't work,
-then comment out all of the bass music (but leave
-@code{\bass} in the @code{\score} uncommented.
-
-@example
-bass = \relative c' @{
-%@{
- c4 c c c
- d d d d
-%@}
-@}
-@end example
-
-Now start slowly uncommenting more and more of the
-@code{bass} part until you find the problem line.
-
* More staves::
* Adding articulation marks to notes::
* Combining notes into chords::
-* Advanced rhythmic commands::
+* Advanced rhythmic commands::
* Commenting input files::
* Printing lyrics::
* A lead sheet::
* Piano staves::
* Organizing larger pieces::
* An orchestral part::
+* After the tutorial::
@end menu
@section Organizing larger pieces
When all of the elements discussed earlier are combined to produce
-larger files, the @code{\score} blocks get a lot bigger, because the
-music expressions are longer, and, in the case of polyphonic pieces,
+larger files, the @code{\score} blocks get a lot bigger because the
+music expressions are longer, and, in the case of polyphonic music,
more deeply nested. Such large expressions can become unwieldy.
By using variables, also known as identifiers, it is possible to break
{ \seufzer \seufzer }
@end lilypond
-The name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes. The assignment should be outside of
+The name of an identifier should have alphabetic characters only: no
+numbers, underscores, or dashes. The assignment should be outside of
running music.
It is possible to use variables for many other types of objects in the
In ensemble pieces, one of the voices often does not play for many
measures. This is denoted by a special rest, the multi-measure
rest. It is entered with a capital @samp{R} followed by a duration
-(1@tie{}for a whole note, 2@tie{}for a half note, etc.). By multiplying the
+(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
+etc.). By multiplying the
duration, longer rests can be constructed. For example, this rest
takes 3@tie{}measures in 2/4 time
@ref{Changing context properties on the fly}.
-@ignore
+@node After the tutorial
+@section After the tutorial
-* longer example
+After finishing the tutorial, you should probably try writing a
+piece or two. Start with one of the @ref{Example templates} and
+add notes. If you need any notation that was not covered in the
+tutorial, look at the Notation Reference, starting with
+@ref{Basic notation}. If you want to write for an instrument
+ensemble which is not covered in the @ref{Example templates},
+take a look at @ref{Extending the templates}.
-* discuss expectations (?)
+Once you have written a few short pieces, read the rest of
+the Learning Manual (chapters 3-5). There's nothing wrong
+with reading them now, of course! However, the rest of the
+Learning Manual assumes that you are familiar with
+LilyPond input. You may wish to skim these chapters right
+now, and come back to them after you have more experience.
-* conclude tutorial
-* overview of chapters?
-
-@end ignore
projects / lilypond.git / commitdiff