* Vocal music::
* Tablatures::
* Chord names::
-* Writing parts::
+* Orchestral music::
* Ancient notation ::
* Contemporary notation::
* Tuning output::
* Rests::
* Skips::
* Durations::
+* Stems::
* Ties::
* Tuplets::
* Easy Notation note heads ::
\pitch @var{scmpitch}
@end example
+
where @var{scmpitch} is a Scheme object of the @code{Pitch} type.
+@refcommands
+
+Dots are normally moved up to avoid staff lines, except in polyphonic
+situations. The following commands may be used to force a particular
+direction manually.
+
+@refcommand dotsUp
+@refcommand dotsDown
+@refcommand dotsBoth
+
+Notes can be hidden and unhidden with the following commands.
+
+@refcommand hideNotes
+@refcommand unHideNotes
+
@seealso
<<f, c'' d e f>>4.
@end lilypond
+@node Stems
+@subsection Stems
+
+Whenever a note is found, a
+@internalsref{Stem} object is created automatically. For whole notes
+and rests, stem objects are also created, but in those cases, the stem
+is invisible.
+
+@refcommands
+
+@refcommand stemUp
+@refcommand stemDown
+@refcommand stemBoth
+
@node Ties
@subsection Ties
If you need to tie notes over bars, it may be easier to use automatic
note splitting (See @ref{Automatic note splitting}).
+@refcommands
+
+
+@refcommand tieUp
+@refcommand tieDown
+@refcommand tieBoth
+@refcommand tieDotted
+@refcommand tieSolid
@seealso
@cindex @code{tupletNumberFormatFunction}
@cindex tuplet formatting
+
+@refcommands
+
+@refcommand tupletUp
+@refcommand tupletDown
+@refcommand tupletBoth
+
@seealso
@seeinternals{TupletBracket}, @seeinternals{TimeScaledMusic}.
Notes, dynamic signs, etc. are grouped
with a set of horizontal lines, into a staff (plural `staves'). In our
-system, these lines are drawn using a separate graphical object called
+system, these lines are drawn using a separate layout object called
staff symbol.
This object is created whenever a @internalsref{Staff} context is
@node Key signature
@subsection Key signature
-@cindex Key
+@cindex Key signature
@cindex @code{\key}
@code{Score.timing} to false, this automatic timing can be switched
off.
+
+@refcommands
+
+@refcommand cadenzaOn
+@refcommand cadenzaOff
+
@node Bar lines
@subsection Bar lines
@cindex Bar lines
when the object property @code{merge-differently-dotted} is set in
the @internalsref{NoteCollision} object, they are:
@lilypond[verbatim,fragment,singleline]
-\relative c' \context Voice < {
+\relative c'' \context Voice < {
g8 g8
\property Staff.NoteCollision \override
#'merge-differently-dotted = ##t
LilyPond also vertically shifts rests that are opposite of a stem.
+
@lilypond[singleline,fragment,verbatim]
\context Voice < c''4 \\ r4 >
@end lilypond
+
+@refcommands
+
+
+
+@refcommand oneVoice
+@refcommand voiceOne
+@refcommand voiceTwo
+@refcommand voiceThree
+@refcommand voiceFour
+
+The following commands specify in what chords of the current voice
+should be shifted: the outer voice has @code{\shiftOff}, and the inner
+voices have @code{\shiftOn}, @code{\shiftOnn}, etc.
+
+
+@refcommand shiftOn
+@refcommand shiftOnn
+@refcommand shiftOnnn
+@refcommand shiftOff
+
+
+
@seealso
The objects responsible for resolving collisions are
c16-[ c c c c c c c-]
\property Voice.subdivideBeams = ##t
c16-[ c c c c c c c-]
- c32-[ c c c c c c c c c c c c c c c-]
\property Score.beatLength = #(ly:make-moment 1 8)
- c32-[ c c c c c c c c c c c c c c c-]
+ c16-[ c c c c c c c-]
@end lilypond
@cindex subdivideBeams
@cindex automatic beams, tuning
@cindex tuning automatic beaming
-[TODO: use \applycontext]
+@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,
automatic beaming. This is done by setting @code{Voice.autoBeaming} to
@code{#f}.
+@refcommands
+
+@refcommand autoBeamOff
+@refcommand autoBeamOn
+
@refbugs
@end table
+@refcommands
+
+@refcommand defaultAccidentals
+@refcommand voiceAccidentals
+@refcommand modernAccidentals
+@refcommand modernCautionaries
+@refcommand modernVoiceAccidentals
+@refcommand modernVoiceCautionaries
+@refcommand pianoAccidentals
+@refcommand pianoCautionaries
+@refcommand noResetKey
+@refcommand forgetAccidentals
+
@seealso
@internalsref{Accidental_engraver}, @internalsref{Accidental},
d,32-( d'4 d8..-)
@end lilypond
+@refcommands
+
+
+@refcommand slurUp
+@refcommand slurDown
+@refcommand slurBoth
+@refcommand slurDotted
+@refcommand slurSolid
+
@seealso
@seeinternals{Slur}, @internalsref{SlurEvent}.
The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurBoth}
will only affect normal slurs and not phrasing slurs.
+@refcommands
+
+@refcommand phrasingSlurUp
+@refcommand phrasingSlurDown
+@refcommand phrasingSlurBoth
+
@seealso
See also @internalsref{PhrasingSlur},
@end lilypond
The glyph of the breath mark can be tweaked by overriding the
-@code{text} property of the @code{BreathingSign} grob with the name of
+@code{text} property of the @code{BreathingSign} layout object with the name of
any glyph of @ref{The Feta font}. For example,
@lilypond[fragment,verbatim,relative]
c'4
@lilypondfile[notexidoc]{script-chart.ly}
+
+@refcommands
+
+@refcommand scriptUp
+@refcommand scriptDown
+@refcommand scriptBoth
+
@seealso
@internalsref{ScriptEvent}, @internalsref{Script}.
@node Grace notes
@subsection Grace notes
-
-
@cindex @code{\grace}
@cindex ornaments
@cindex grace notes
)c4
}
@end lilypond
+By adjusting the duration of the skip note (here it is a half-note),
+the space between the main-note and the grace is adjusted.
A @code{\grace} section has some default values, and LilyPond will
use those default values unless you specify otherwise inside the
Grace notes cannot be used in the smallest size (@file{paper11.ly}).
+A score that starts with an @code{\grace} section needs an explicit
+@code{\context Voice} declaration, otherwise the main note and grace
+note end up on different staffs.
+
Grace note synchronization can also lead to surprises. Staff notation,
such as key signatures, barlines, etc. are also synchronized. Take
care when you mix staves with grace notes and staves without.
@cindex diminuendo
+
+@refcommands
+
+@refcommand dynamicUp
+@refcommand dynamicDown
+@refcommand dynamicBoth
+
+@cindex direction, of dynamics
+
@seealso
@internalsref{CrescendoEvent}, @internalsref{DecrescendoEvent},
If you want to adjust padding or vertical direction of the dynamics,
you must set properties for the @internalsref{DynamicLineSpanner}
-object. Predefined variables to set the vertical direction are
-@code{\dynamicUp} and @code{\dynamicDown}.
-
-@cindex direction, of dynamics
-@cindex @code{\dynamicDown}
-@cindex @code{\dynamicUp}
+object.
@node Repeats
@refbugs
- If you do a nested repeat like
+If you do a nested repeat like
@example
\repeat @dots{}
list at the top of your file:
@lilypond[singleline, verbatim]
-#(define mydrums `(
+#(set-drum-kit 'mydrums `(
(bassdrum default #f ,(ly:make-pitch -1 2 0))
(snare default #f ,(ly:make-pitch 0 1 0))
(hihat cross #f ,(ly:make-pitch 0 5 0))
<<c' e g c>>-\arpeggio
@end lilypond
+@refcommands
+
+@refcommand arpeggioBracket
+@refcommand arpeggio
@refbugs
The associated object is @internalsref{VoiceFollower}.
+@refcommands
+
+@refcommand showStaffSwitch
+@refcommand hideStaffSwitch
+
@node Vocal music
@section Vocal music
@end table
+
+There are also two other chord name schemes implemented: an alternate
+Jazz chord notation, and a systematic scheme called Banter chords. The
+alternate jazz notation is also shown on the chart in @ref{Chord name
+chart}. Turning on these styles is described in the input file
+@inputfileref{input/test/,chord-names-jazz.ly}.
+
+@cindex Banter
+@cindex jazz chords
+@cindex chords, jazz
+
+
+@refcommands
+
+@refcommand germanChords
+@refcommand semiGermanChords
+
+
+
+
@seealso
@inputfileref{input/regression,chord-name-major7.ly},
@inputfileref{input/regression,chord-name-exceptions.ly},
+@inputfileref{input/test,chord-names-jazz.ly},
@inputfileref{input/test,chord-names-german.ly},
@file{scm/chords-ignatzek.scm}, @file{scm/chord-entry.scm}
-@node Writing parts
-@section Writing parts
+@node Orchestral music
+@section Orchestral music
+
+@cindex Writing parts
Orchestral music involves some special notation, both in the full
score and the individual parts. This section explains how to tackle
@menu
+* Multiple staff contexts::
* Rehearsal marks::
* Bar numbers::
* Instrument names::
* Sound output for transposing instruments::
@end menu
+@node Multiple staff contexts
+@subsection Multiple staff contexts
+
+Polyphonic scores consist of many staffs. These staffs can be
+constructed in three different ways:
+@itemize @bullet
+@item The group is started with a brace at the left. This is done with the
+@internalsref{GrandStaff} context.
+@item The group is started with a bracket. This is done with the
+@internalsref{StaffGroup} context
+@item The group is started with a vertical line. This is the default
+for the score.
+@end itemize
+
+@cindex Staff, multiple
+@cindex bracket, vertical
+@cindex brace, vertical
+@cindex grand staff
+@cindex staff group
+
+
+
@node Rehearsal marks
@subsection Rehearsal marks
@cindex fermata on multi-measure rest
Texts can be added to multi-measure rests by using the
-@var{note}-@code{markup} syntax (see @ref{Text markup}) . In this case, the number is
+@var{note}-@code{markup} syntax (see @ref{Text markup}). In this case, the number is
replaced. If you need both texts and the number, you must add the
number by hand. A variable (@code{\fermataMarkup}) is provided for
adding fermatas.
@internalsref{MultiMeasureRestMusicGroup},
@internalsref{MultiMeasureRest},
-The graphical object @internalsref{MultiMeasureRestNumber} is for the
+The layout object @internalsref{MultiMeasureRestNumber} is for the
default number, and @internalsref{MultiMeasureRestText} for user
specified texts.
>
@end lilypond
-The part combiner is slated to be rewritten [TODO: explain why] .
+The part combiner is slated to be rewritten [TODO: explain why].
@cindex @code{Thread_devnull_engraver}
@cindex @code{Voice_engraver}
@tab
@item
-@code{16. Trigomus}
+@code{16. Trigonus}
@tab
@lilypond[noindent, 26pt, nofragment, linewidth=1.0cm]
\include "gregorian-init.ly"
@refbugs
-Use special heads for lower/upper head of Pes only when heads are
-stacked.
-
Scandicus Deminutus: Punctum Auctum Ascendens overlaps with
Semivocalis head; this looks awful.
@seealso
-@internalsref{BassFigureEvent} music, @internalsref{BassFigure} grob,
+@internalsref{BassFigureEvent} music, @internalsref{BassFigure} object,
@internalsref{FiguredBass} context
@refbugs
@syntax
-A cluster is engraved as the envelope of a set of notes. The starting
-note is marked with @code{\startCluster}, and the ending note with
-@code{\stopCluster}, e.g.,
-
-@example
- c4-\startCluster
- ...
- f4-\stopCluster
-@end example
+A cluster is engraved as the envelope of a set of
+cluster-notes. Cluster notes are created by applying the function
+@code{notes-to-clusters} to a sequence of chords, eg.
+@c
+@lilypond[relative 2]
+ \apply #notes-to-clusters { << c e >> <<b f'>> }
+@end lilypond
The following example (from
@inputfileref{input/regression,cluster.ly}) shows what the result
@seealso
-@internalsref{Cluster}, @inputfileref{input/regression,cluster.ly},
-@internalsref{Cluster_engraver}, @internalsref{ClusterEvent}.
+@internalsref{ClusterSpanner}, @internalsref{ClusterSpannerBeacon},
+@inputfileref{input/regression,cluster.ly},
+@internalsref{Cluster_engraver}, @internalsref{ClusterNoteEvent}.
@refbugs
-When a cluster is active, note heads must be switched off manually using
-@code{\hideNotes}.
-
Music expressions like @code{< @{ g8 e8 @} a4 >} are not printed
accurately. Use @code{<<g a>>8 <<e a>>8} instead.
@menu
* Tuning objects ::
+* Constructing a tweak::
* Applyoutput::
* Outputproperty::
* Font selection::
* Text markup::
@end menu
+
+
@node Tuning objects
@subsection Tuning objects
The definition of an object is actually a list of default object
properties. For example, the definition of the Stem object (available
-in @file{scm/grob-description.scm}), includes the following definitions for
+in @file{scm/define-grobs.scm}), includes the following definitions for
@internalsref{Stem}
@example
By adding variables on top of these existing definitions, the system
-defaults is overriden, and the appearance of a graphical objects is
+default is overridden, and the appearance of a layout objects is
altered.
@syntax
@code{\once}:
@example
-\once \property @var{context}.@var{grobname}
+\once \property @var{context}.@var{objectname}
\override @var{symbol} = @var{value}
@end example
Here @var{symbol} is a Scheme expression of symbol type, @var{context}
-and @var{grobname} is a string and @var{value} is a Scheme expression.
+and @var{objectname} is a string and @var{value} is a Scheme expression.
This command applies a setting only during one moment in the score.
In the following example, only one @internalsref{Stem} object is
For changing more objects, the same command, without @code{\once} can
be used.
@example
-\property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
+\property @var{context}.@var{objectname} \override @var{symbol} = @var{value}
@end example
This command adds @code{@var{symbol} = @var{value}} to the definition
-of @var{grobname} in the context @var{context}, and this definition
+of @var{objectname} in the context @var{context}, and this definition
stays in place until it is removed.
An existing definition may be removed by the following command
@c
@example
-\property @var{context}.@var{grobname} \revert @var{symbol}
+\property @var{context}.@var{objectname} \revert @var{symbol}
@end example
@c
All @code{\override} and @code{\revert} commands should be balanced.
and is often more convenient to use
@example
-\property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
+\property @var{context}.@var{objectname} \set @var{symbol} = @var{value}
@end example
Some examples:
@internalsref{OverrideProperty}, @internalsref{RevertProperty},
@internalsref{PropertySet}, @internalsref{backend properties},
-@internalsref{All Graphical Objects}.
+@internalsref{All layout objects}.
@refbugs
Similarly, reverting properties that are system defaults may also lead
to crashes.
+@node Constructing a tweak
+@subsection Constructing a tweak
+
+
+@cindex internal documentation
+@cindex finding graphical objects
+@cindex graphical object descriptions
+@cindex tweaking
+@cindex @code{\override}
+@cindex @code{\set}
+@cindex internal documentation
+
+
+
+Using @code{\override} and @code{\set}, requires three pieces of
+information: the name of the layout object, the context and the name
+of the property. We demonstrate how to glean this information from
+the notation manual and the generated documentation.
+
+The generated documentation is a set of HTML pages which should be
+included if you installed a binary distribution, typically in
+@file{/usr/share/doc/lilypond}. They are also available on the web:
+go to the @uref{LilyPond website,http://lilypond.org}, click
+``Documentation: Index'' on the side bar, look in the ``Information
+for users'' section, and click on ``Documentation of internals.'' It
+is advisable to bookmark either the local HTML files if possilbe. They
+will load faster than the ones on the web. If you use the version
+from the web, you must check whether the documentation matches the
+program version: the documentation is generated from the definitions
+that the program uses, and therefore it is strongly tied to the
+LilyPond version.
+
+
+@c [TODO: revise for new site.]
+
+Suppose we want to move the fingering indication in the fragment below
+
+@lilypond[relative=2]
+c-2
+\stemUp
+f
+@end lilypond
+
+If you visit the documentation of @code{Fingering} (in @ref{Fingering
+instructions}), you will notice that it says
+
+@quotation
+@seealso
+
+@internalsref{FingerEvent} and @internalsref{Fingering}.
+@end quotation
+
+This implies that the fingerings, once entered, are internally stored
+as @code{FingerEvent} music objects. When printed, a @code{Fingering}
+layout object is created for every @code{FingerEvent}.
+
+@ifhtml
+When we follow the link of @internalsref{Fingering},
+@end ifhtml
+@ifnothtml
+When we look up @internalsref{Fingering} in the generated
+documentation,
+@end ifnothtml
+we see a list of interfaces. The Fingering object has a number of
+different functions, and each of those is captured in an interface.
+
+The @code{Fingering} object has a fixed size
+(@internalsref{item-interface}), the symbol is a piece of text
+(@internalsref{text-interface}), whose font can be set
+(@internalsref{font-interface}). It is centered horizontally
+(@internalsref{self-alignment-interface}), it is placed next to other
+objects (@internalsref{side-position-interface}) vertically, and its
+placement is coordinated with other scripts
+(@internalsref{text-script-interface}). It also has the standard
+@internalsref{grob-interface} (grob stands for Graphical object)
+@cindex grob
+@cindex graphical object
+@cindex layout object
+@cindex object, layout
+with all the variables that come with
+it. Finally, it denotes a fingering instruction, so it has
+@internalsref{finger-interface}.
+
+For the vertical placement, we have to look under
+@code{side-position-interface}.
+@quotation
+ side-position-interface
+
+ Position a victim object (this one) next to other objects (the
+ support). In this case, the direction signifies where to put the
+ victim object relative to the support (left or right, up or down?)
+@end quotation
+below this description, the variable @code{padding} is described as
+@quotation
+@table @code
+@item padding
+ (dimension, in staff space)
+
+ add this much extra space between objects that are next to each
+other. Default value: @code{0.6}
+@end table
+@end quotation
+
+By increasing the value of @code{padding}, we can move away the
+fingering. The following command inserts 3 staff spaces of white
+between the note and the fingering
+@example
+\once \property Voice.Fingering \set #'padding = #3
+@end example
+
+Before the object is created, we get
+@lilypond[relative=2,fragment]
+\once \property Voice.Fingering
+ \set #'padding = #3
+c-2
+\stemUp
+f
+@end lilypond
+
+The context name @code{Voice} in the example above can be determined
+as follows. In the documentation for @internalsref{Fingering}, it says
+@quotation
+Fingering grobs are created by: @internalsref{Fingering_engraver}
+@end quotation
+
+Clicking @code{Fingering_engraver} shows the documentation of
+the module responsible for interpreting the fingering instructions and
+translating them to a @code{Fingering} object. Such a module is called
+an @emph{engraver}. The documentation of the @code{Fingering_engraver}
+says
+@example
+Fingering_engraver is part of contexts: Voice and TabVoice
+@end example
+so tuning the settings for Fingering should be done using either
+@example
+ \property Voice.Fingering \set @dots{}
+@end example
+or
+@example
+ \property TabVoice.Fingering \set @dots{}
+@end example
+
+Since the @code{TabVoice} is only used for tab notation, we see that
+the first guess @code{Voice} was indeed correct.
+
+Of course, the tweak may also done in a larger context than
+@code{Voice}, for example, @internalsref{Staff} or
+@internalsref{Score}.
+
+The internals document also contains alphabetical lists of
+@internalsref{All contexts}, @internalsref{All layout objects} and
+@internalsref{All music types}, so you can also find which objects to
+tweak by browsing the internals document.
+
@node Applyoutput
@subsection Applyoutput
@end example
where @var{proc} is a Scheme function, taking four arguments.
-When interpreted, the function @var{proc} is called for every grob found
+When interpreted, the function @var{proc} is called for every layout object found
in the context, with the following arguments:
@itemize @bullet
-@item the grob itself
-@item the context where the grob was created
+@item the layout object itself
+@item the context where the layout object was created
@item the context where @code{\applyoutput} is processed.
@end itemize
-In addition, the cause of the grob, i.e. the music expression or object
-that was responsible for creating the object, is in the object property
-@code{cause}. For example, for a note head, this is a
+In addition, the cause of the layout object, i.e. the music
+expression or object that was responsible for creating it, is in the
+object property @code{cause}. For example, for a note head, this is a
@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
this is a @internalsref{NoteHead} object.
@cindex @code{font-style}
+@refcommands
+
+The following commands set @code{fontSize} for the current voice.
+@refcommand tiny
+@refcommand small
+@refcommand normalsize
@refbugs
This produces a single character, e.g. @code{\char #65} produces the
letter 'A'.
+@item \note
+@cindex \note @var{log} @var{dots} @var{dir}
+
+This produces a note with a stem pointing in @var{dir} direction, with
+duration log @var{log} and @var{dots} augmentation dots.
+
@item \hspace #@var{amount}
@cindex \hspace
This produces a invisible object taking horizontal space.
This overrides a formatting property for its argument. The argument
should be a key/value pair, e.g.
@example
-m \override #'(font-family . math) m m
+ m \override #'(font-family . math) m m
@end example
@end table
@cindex SpacingSpanner, overriding properties
-Properties of the @internalsref{SpacingSpanner} must be overriden
+Properties of the @internalsref{SpacingSpanner} must be overridden
from the @code{\paper} block, since the @internalsref{SpacingSpanner}
is created before any @code{\property} statements are interpreted.
@example
is done by setting the @code{between-systems-strings} on the
@internalsref{NonMusicalPaperColumn} where the system is broken.
An example is shown in @inputfileref{input/regression,between-systems.ly}.
+The predefined command @code{\newpage} also does this.
@cindex paper size
@cindex page size
Lilypond and @code{ly2dvi})
+@refcommands
+
+@refcommand newpage
+
+
@seealso
@ref{Invoking ly2dvi},
projects / lilypond.git / blobdiff