@end html
This document describes GNU LilyPond and its input format. The last
-revision of this document was made for LilyPond 1.6.2. It assumes
+revision of this document was made for LilyPond 1.7.10. It assumes
that you already know a little bit about LilyPond input (how to
make an input file, how to create sheet music from that input file,
etc). New users are encouraged to study the tutorial before reading
* Repeats::
* Rhythmic music::
* Piano music::
+* Vocal music::
* Tablatures::
* Chords::
* Writing parts::
-* Ancient notation ::
+* Ancient notation::
+* Contemporary notation::
* Tuning output::
* Global layout::
* Sound::
@end quotation
@end itemize
-Another option is to enter the music using your favorite MIDI
-sequencer, and then import it using midi2ly. midi2ly is described in
-@ref{Invoking midi2ly}.
+Another option is to enter the music using your favorite
+sequencer/notation editor, and then export it as MIDI or MusicXML.
+You can then import it in lilypond by using either midi2ly or
+@cindex midi2ly
+xml2ly. midi2ly is described in @ref{Invoking midi2ly}. @code{xml2ly}
+@cindex xml2ly
+is a tool to convert from the MusicXML music representation format
+(@uref{http://www.musicxml.org}) to LilyPond format. @code{xml2ly} is
+described at @uref{http://www.nongnu.org/xml2ly/}.
@c . {Relative}
@item \pianoCautionaries
@cindex @code{\pianoCautionaries}
As @code{\pianoAccidentals} but with the extra accidentals
- typeset as cationaries.
+ typeset as cautionaries.
@item \noResetKey
@cindex @code{\noResetKey}
@item 'end-repeat
Print a :| bar line
@item (volta . @var{text})
- Print a volta bracket saying @var{text} (the text can be specified
- as a text string or as a markup text, see @ref{Text markup}).
-@item (volta . #f)
+ Print a volta bracket saying @var{text}. The text can be specified as
+a text string or as a markup text, see @ref{Text markup}. Do not
+forget to change the font, as the default number font does not contain
+alphabetic characters.
+@item (volta . #f)
Stop a running volta bracket
@end table
The associated object is @internalsref{VoiceFollower}.
+@node Vocal music
+@section Vocal music
+
+For a discussion of how to put lyrics into a score, see section
+@code{Printing lyrics} in the tutorial.
+
+[TODO: Move lyrics section from tutorial to here?]
+
+See also the sections on @ref{Slurs} and @ref{Breath marks}.
+
+[TODO: Move slurs / breath marks section to here?]
+
+[TODO: Write subsection upon usage of ChoirStaff.]
+
+@menu
+* Ambitus::
+@end menu
+
+@node Ambitus
+@subsection Ambitus
+@cindex ambitus
+
+The term @emph{ambitus} denotes a range of pitches for a given voice in
+a part of music. It also may denote the pitch range that a musical
+instrument is capable of playing. Most musical instruments have their
+ambitus standardized (or at least there is agreement upon the minimal
+ambitus of a particular type of instrument), such that a composer or
+arranger of a piece of music can easily meet the ambitus constraints of
+the targeted instrument. However, the ambitus of the human voice
+depends on individual physiological state, including education and
+training of the voice. Therefore, a singer potentially has to check for
+each piece of music if the ambitus of that piece meets his individual
+capabilities. This is why the ambitus of a piece may be of particular
+value to vocal performers.
+
+The ambitus is typically notated on a per-voice basis at the very
+beginning of a piece, e.g. nearby the initial clef or time signature of
+each staff. The range is graphically specified by two noteheads, that
+represent the minimum and maximum pitch. Some publishers use a textual
+notation: they put the range in words in front of the corresponding
+staff. Lilypond currently only supports the graphical ambitus notation.
+
+To apply, simply add the @internalsref{Ambitus_engraver} to the
+@internalsref{Voice} context, as shown in the below example:
+
+@lilypond[singleline,verbatim]
+upper = \notes \relative c {
+ \clef "treble"
+ \key c \minor
+ as'' c e2 bes f cis d4 e f2 g
+}
+lower = \notes \relative c {
+ \clef "treble"
+ \key e \major
+ e'4 b g a c es fis a cis b a g f e d2
+}
+\score {
+ \context ChoirStaff {
+ <
+ \context Staff = one { \upper }
+ \context Staff = three { \lower }
+ >
+ }
+ \paper {
+ \translator {
+ \VoiceContext
+ \consists Ambitus_engraver
+ }
+ }
+}
+@end lilypond
+
+The shape of the note heads to use can be changed via the
+@code{note-head-style} property, which holds the glyph name of the note
+head (see also @ref{Ancient note heads}). The vertical line between the
+upper and lower head can be switched on or off via the @code{join-heads}
+property. Example:
+
+@example
+\translator @{
+ \VoiceContext
+ \consists Ambitus_engraver
+ Ambitus \set #'note-head-style = #'noteheads-2mensural
+ Ambitus \set #'join-heads = ##f
+@}
+@end example
+
+By default, the ambitus grob is put before the clef. You can control
+this behaviour through the @code{breakAlignOrder} property of the score
+context by redefining the order, e.g. with the following addition to the
+paper block:
+
+@example
+\translator @{
+ \ScoreContext
+ breakAlignOrder = #'(
+ instrument-name
+ left-edge
+ span-bar
+ breathing-sign
+ clef
+ ambitus
+ key-signature
+ staff-bar
+ time-signature
+ custos
+ )
+@}
+@end example
+
@node Tablatures
@section Tablatures
@cindex Chords mode
Chord mode is a mode where you can input sets of pitches using common
-names. It is introduced by the keyword @code{\chords}. It is similar
-to note mode, but words are also looked up in a chord modifier table
-(containing @code{maj}, @code{dim}, etc). Dashes and carets are used
-to indicate chord additions and subtractions, so articulation scripts
-can not be entered in Chord mode.
+names. It is introduced by the keyword @code{\chords}.
+In chords mode, a chord is entered by the root, which is entered
+like a common pitch, for example,
+@lilypond[fragment,verbatim]
+ es4. d8 c2
+@end lilypond
+is the notation for an E-flat major chord.
-Throughout these examples, chords have been shifted around the staff
-using @code{\transpose}.
+@cindex chord entry
+@cindex chord mode
+Other chords may be entered
+by suffixing a colon, and introducing a modifier, and optionally, a
+number, for example
@lilypond[fragment,verbatim]
-\transpose c c' {
- \chords {
- c1 c:3- c:7 c:8
- c:9 c:9-.5+.7+ c:3-.5-
- }
-}
+\chords { e1:m e1:7 e1:m7 }
+@end lilypond
+The first number following the root is taken to be the `type' of the
+chord, thirds are added to the root until it reaches the specified
+number, for example.
+@lilypond[fragment,verbatim]
+ \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }
+@end lilypond
+
+@cindex root of chord
+@cindex additions, in chords
+@cindex removals, in chords
+
+More complex chords may also be constructed adding separate steps
+to a chord. Additions are added after the number following
+the colon, and are separated by dots. For example
+@c
+@lilypond[verbatim,fragment]
+ \chords { c:5.6 c:3.7.8 c:3.6.13 }
+@end lilypond
+Chord steps can be altered by suffixing a @code{-} or @code{+} sign
+to the number, for example:
+@lilypond[verbatim,fragment]
+ \chords { c:7+ c:5+.3- c:3-.5-.7- }
+@end lilypond
+Removals are specified similarly, and are introduced by a caret. They
+must come after the additions.
+@lilypond[verbatim,fragment]
+ \chords { c^3 c:7^5 c:9^3.5 }
@end lilypond
+Modifiers can be used to change pitches. The following modifiers are
+supported
+@table @code
+@item m
+ Minor chord. Lowers the 3rd and (if present) the 7th step.
+@item dim
+ Diminished chord. Lowers the 3rd, 5th and (if present) the 7th step
+@item aug
+ Augmented chord. Raises the 5th step.
+@item maj
+ Major 7th chord. Raises the 7th step, if present.
+@item sus
+ Suspended 4th or 2nd. This modifier removes the 3rd step. Append
+ either @code{2} or @code{4} to add the 2nd or 4th step to the chord.
+@end table
+Modifiers can be mixed with additions.
+@lilypond[verbatim,fragment]
+ \chords { c:sus4 c:7sus4 c:dim7 c:m6 }
+@end lilypond
+
+@cindex modifiers, in chords.
@cindex @code{aug}
@cindex @code{dim}
@cindex @code{maj}
@cindex @code{sus}
+@cindex @code{m}
-The second type of modifier that may appear after the @code{:} is a
-named modifier. Named modifiers are listed in the file
-@file{chord-modifiers.ly}. The available modifiers are @code{m} and
-@code{min} which lower the 3rd half a step, `@code{aug}' which
-raises the 5th, `@code{dim}' which lowers the 5th,
-`@code{maj}' which adds a raised 7th, and `@code{sus}'
-which replaces the 5th with a 4th.
-
+Since the unaltered 11 does sound well when combined with the
+unaltered 3, the 11 is removed in this case, unless it is added
+explicitly). For example,
@lilypond[fragment,verbatim]
-\transpose c c' {
- \chords {
- c1:m c:min7 c:maj c:aug c:dim c:sus
- }
-}
-@end lilypond
-
-
-Chord subtractions are used to eliminate notes from a chord. The
-notes to be subtracted are listed after a @code{^} character,
-separated by dots.
-
-@lilypond[fragment,verbatim,center]
- \transpose c c' {
- \chords {
- c1^3 c:7^5.3 c:8^7
- }
- }
+ \chords { c:13 c:13.11 c:m13 }
@end lilypond
-@cindex @code{/}
-Chord inversions can be specified by appending `@code{/}' and the name
-of a single note to a chord. In a chord inversion, the inverted note is
-transposed down until it is the lowest note in the chord. If the note
-is not in the chord, a warning will be printed.
+@cindex @code{/}
+An inversion (putting one pitch of the chord on the bottom), as well
+as bass notes, can be specified by appending
+@code{/}@var{pitch} to the chord.
@lilypond[fragment,verbatim,center]
- \transpose c c'' {
- \chords {
- c1 c/e c/g c:7/e
- }
- }
-
+ \chords { c1 c/g c/f }
@end lilypond
@cindex @code{/+}
-
-Bass notes can be added by `@code{/+}' and
-the name of a single note to a chord. This has the effect of
-adding the specified note to the chord, lowered by an octave,
-so it becomes the lowest note in the chord.
+If you do not want to remove the bass note from the chord, but rather
+add the note, then you can use @code{/+}@var{pitch}.
@lilypond[fragment,verbatim,center]
- \transpose c c'' {
- \chords {
- c1 c/+c c/+g c:7/+b
- }
- }
-
+ \chords { c1 c/+g c/+f }
@end lilypond
-The formal syntax for named chords is as follows:
-@example
- @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
-@end example
-@var{tonic} should be the tonic note of the chord, and @var{duration} is
-the chord duration in the usual notation. There are two kinds of
-modifiers. One type is formed by @emph{chord additions}. Additions are
-obtained by listing intervals separated by dots. An interval is written
-by its number with an optional @code{+} or @code{-} to indicate raising
-or lowering by half a step. Chord additions have two effects: they adds
-the specified interval and all lower odd numbered intervals to the
-chord, and they may lower or raise the specified interval.
+@refbugs
+
+Each step can only be present in a chord once. The following
+simply produces the augmented chord, since @code{5+} is interpreted
+last.
+@cindex clusters
+@lilypond[verbatim,fragment]
+ \chords { c:5.5-.5+ }
+@end lilypond
+
+In chord mode, dashes and carets are used to indicate chord additions
+and subtractions, so articulation scripts can not be entered.
-@refbugs
-Implementation details are gory. For example @code{c:4} not only adds
-a fourth, but also removes the third.
@c . {Printing named chords}
}
@end lilypond
+The default chord name layout is a system for Jazz music, proposed by
+Klaus Ignatzek (See @ref{Literature}).
-By default, a chord name system proposed by Harald Banter (See
-@ref{Literature}) is used. The system is very regular and predictable.
-Typical American style chord names may be selected by setting the
-@code{style} property of the @code{ChordNames.ChordName} object to
-@code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
-
-Routines that determine the names to be printed are written in Scheme,
-and may be customized by the user. The code can be found in
-@file{scm/chord-name.scm}. Here's an example showing the differences in
-chord name styles:
-
-@c too long?
-@c maybe just junk verbatim option?
-@lilypond[verbatim,singleline,noquote]
-scheme = \chords {
- c1 c:5^3 c:4^3 c:5+
- c:m7+ c:m5-.7
- c:5-.7 c:5+.7
- c:9^7
-}
-
-\score {
- \notes <
- \context ChordNames = banter \scheme
- \context ChordNames = american {
- \property ChordNames.ChordName \override
- #'style = #'american \scheme }
- \context ChordNames = jazz {
- \property ChordNames.ChordName \override
- #'style = #'jazz \scheme }
- \context Staff \transpose c c' \scheme
- >
-}
-@end lilypond
+[TODO: add description for banter other jazz.]
@node Writing parts
fermata. This can be corrected by the following property setting
@example
\property Score.RehearsalMark \override
- #'visibility-lambda = #begin-of-line-invisible
+ #'break-visibility = #begin-of-line-invisible
@end example
@cindex fermatas
the MIDI file.
+@c . {Contemporary notation}
+@node Contemporary notation
+@section Contemporary notation
+
+@menu
+* Clusters::
+@end menu
+
+@node Clusters
+@subsection Clusters
+
+@cindex cluster
+
+In musical terminology, a @emph{cluster} denotes a range of
+simultaneously sounding pitches that may change over time. The set of
+available pitches to apply usually depends on the accoustic source.
+Thus, in piano music, a cluster typically consists of a continous range
+of the semitones as provided by the piano's fixed set of a chromatic
+scale. In choral music, each singer of the choir typically may sing an
+arbitrary pitch within the cluster's range that is not bound to any
+diatonic, chromatic or other scale. In electronic music, a cluster
+(theoretically) may even cover a continuous range of pitches, thus
+resulting in coloured noise, such as pink noise.
+
+Clusters can be notated in the context of ordinary staff notation by
+engraving simple geometrical shapes that replace ordinary notation of
+notes. Ordinary notes as musical events specify starting time and
+duration of pitches; however, the duration of a note is expressed by the
+shape of the note head rather than by the horizontal graphical extent of
+the note symbol. In contrast, the shape of a cluster geometrically
+describes the development of a range of pitches (vertical extent) over
+time (horizontal extent). Still, the geometrical shape of a cluster
+covers the area in wich any single pitch contained in the cluster would
+be notated as an ordinary note. From this point of view, it is
+reasonable to specify a cluster as the envelope of a set of notes. This
+is exactly how to construct a cluster with lilypond.
+
+@lilypond[singleline,verbatim]
+\score {
+ \context PianoStaff <
+ \context Voice = voiceI { % same as voiceII, but with ordinary notes
+ \notes \relative c' {
+ c4 f4
+ a4 <e4 d'4> | \break
+ < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 |
+ c4 a4 f4 g4 a4
+ }
+ }
+ \context Voice = voiceII { % same as voiceI, but with cluster notation
+ \notes \relative c' {
+
+ % hide notes, accidentals, etc.
+ \property Thread.NoteHead \set #'transparent = ##t
+ \property Voice.Stem \set #'transparent = ##t
+ \property Voice.Beam \set #'transparent = ##t
+ \property Staff.Accidental \set #'transparent = ##t
+
+ \property Voice.Cluster \set #'padding = #0.01
+ \property Voice.Cluster \set #'shape = #'ramp
+
+ c4 f4
+ \startCluster
+ a4 <e4 d'4> | \break
+ < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 |
+ c4 \stopCluster a4 f4 g4 a4
+ }
+ }
+ >
+}
+@end lilypond
+
+Note that the second voice differs from the first one only by the
+additional keywords @code{\startCluster} and @code{\stopCluster} and the
+fact that notes, accidentals, etc. are hidden. A future version of
+lilypond may automatically hide notes, accidentals, etc. within the
+scope of clusters.
+
+Also note that a music expression like @code{< @{ g8 e8 @} a4 >} is
+illegal; in such a case, you can instead use the expression @code{< g8
+a8 > < e8 a8 >}.
+
+By default, cluster engraver is in the voice context. This allows
+putting ordinary notes and clusters together in the same staff, even
+simultaneously. However, in such a case no attempt is made to
+automatically avoid collisions between ordinary notes and clusters.
+
+The geometrical shape can be further controlled with grob properties
+@code{padding} and @code{shape}. @code{padding} adds to the vertical
+extent of the shape (top and bottom) and is expressed in units of
+staffspace. Since the pitch range of a single pitch is infinitely
+small, if padding is set to @code{0.0}, this possibly results in an
+invisible shape, if you,for example, say @code{ \startCluster c d e
+\endCluster}. The default value for @code{padding} therefore is
+@code{0.25}, such that a single pitch roughly shows the same height as a
+note head. Property @code{shape} controls how the overall shape of the
+cluster is constructed from the set of notes. Currently supported
+values are @code{leftsided-stairs}, @code{rightsided-stairs},
+@code{centered-stairs}, and @code{ramp}.
+
@c . {Tuning output}
@node Tuning output
@section Tuning output
Relative size is not linked to any real size.
There is no style sheet provided for other fonts besides the @TeX{}
-family, and the style sheet can not be modified easiyl.
+family, and the style sheet can not be modified easily.
@cindex font selection
@cindex font magnification
that the command only apply to the first following word; enclose a set
of texts with braces to apply a command to more words.
@example
- \markup { \bold { hi there } }
+ \markup @{ \bold @{ hi there @} @}
@end example
For clarity, you can also do this for single arguments, e.g.
@example
- \markup { is \italic { anyone } home }
+ \markup @{ is \italic @{ anyone @} home @}
@end example
@cindex font size, texts
@item \small
@item \large
@item \huge
-@end \itemize
+@end table
+
You can also make letter larger or smaller relative to their neighbors,
with the commands @code{\larger} and @code{\smaller}.
@cindex smaller
@cindex \hspace
This produces a invisible object taking horizontal space.
@example
-\markup { A \hspace #2.0 B }
+\markup @{ A \hspace #2.0 B @}
@end example
will put extra space between A and B. Note that lilypond
inserts space before and after @code{\hspace}.
@cindex \fontsize
This sets the relative font size, eg.
@example
-A \fontsize #2 { B C } D
+A \fontsize #2 @{ B C @} D
@end example
This will enlarge the B and the C by two steps.
@cindex \translate
This translates an object. It's first argument is a cons of numbers
@example
-A \translate #(cons 2 -3) { B C } D
+A \translate #(cons 2 -3) @{ B C @} D
@end example
This moves `B C' 2 spaces to the right, and 3 down.
This sets the font magnification for the its argument. In the following
example, the middle A will be 10% larger.
@example
-A \magnify #1.1 { A } A
+A \magnify #1.1 @{ A @} A
@end example
@end example
@end table
-
In markup mode you can compose expressions, similar to mathematical
expressions, XML documents and music expressions. The braces group
notes into horizontal lines. Other types of lists also exist: you can
stack expressions grouped with @code{<<}, and @code{>>} vertically with
-the command @code{\column}. The @code{@{} and @code{@}} produce
-@code{\line} commands:
+the command @code{\column}.
@lilypond[verbatim,fragment,relative=1]
c1^\markup { \column << a b c >> }
c1^\markup { \line << a b c >> }
@end lilypond
-The markup mechanism is very flexible and extensible. Refer to
-@file{scm/new-markup.scm} for more information.
+The markup mechanism is very flexible and extensible. Refer to
+@file{scm/new-markup.scm} for more information on extending the markup
+mode.
@cindex metronome mark
marking:
@lilypond[verbatim]
-eigthStem = \markup \combine
+eighthStem = \markup \combine
\musicglyph #"flags-stem"
\translate #'(0.0 . 3.5) \musicglyph #"flags-u3"
eighthNote = \markup
\override #'(word-space . 0.0)
{ \musicglyph #"noteheads-2"
- \translate #'(-0.05 . 0.1) \eigthStem }
+ \translate #'(-0.05 . 0.1) \eighthStem }
\score {
\notes\relative c'' {
a1^\markup { \magnify #0.9 \eighthNote " = 64" }
}
}
+@end lilypond
+
@refbugs
-LilyPond account for kerning in its text formatting engine, so it spaces
-texts slightly too wide.
+@cindex kerning
+
+LilyPond does not account for kerning in its text formatting, so it
+spaces texts slightly too wide.
Syntax errors for markup mode are confusing.
projects / lilypond.git / blobdiff