Merge remote branch 'origin/master' into release/unstable

[lilypond.git] / Documentation / notation / editorial.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.18.0"

@node Editorial annotations
@section Editorial annotations

@lilypondfile[quote]{editorial-headword.ly}

This section discusses the various ways to change the appearance of
notes and add analysis or educational emphasis.

@menu
* Inside the staff::
* Outside the staff::
@end menu


@node Inside the staff
@subsection Inside the staff

This section discusses how to add emphasis to elements that are
inside the staff.

@menu
* Selecting notation font size::
* Fingering instructions::
* Hidden notes::
* Coloring objects::
* Parentheses::
* Stems::
@end menu

@node Selecting notation font size
@unnumberedsubsubsec Selecting notation font size

@cindex font size (notation) scaling
@cindex font size (notation)
@cindex selecting font size (notation)
@cindex notation font size
@cindex note heads

@funindex fontSize
@funindex font-size
@funindex magnification->font-size
@funindex magstep
@funindex magnifyMusic
@funindex teeny
@funindex tiny
@funindex small
@funindex normalsize
@funindex large
@funindex huge
@funindex \magnifyMusic
@funindex \teeny
@funindex \tiny
@funindex \normalsize
@funindex \small
@funindex \large
@funindex \huge

@warning{@*
For font sizes of text, see @ref{Selecting font and font size}.@*
For staff size, see @ref{Setting the staff size}.@*
For cue notes, see @ref{Formatting cue notes}.@*
For ossia staves, see @ref{Ossia staves}.}

To change the size of the notation without changing the staff
size, specify a magnification factor with the @code{\magnifyMusic}
command:

@c Grieg Piano Concerto (mvt.1 cadenza)
@lilypond[verbatim,quote]
\new Staff <<
  \new Voice \relative {
    \voiceOne
    <e' e'>4 <f f'>8. <g g'>16 <f f'>8 <e e'>4 r8
  }
  \new Voice \relative {
    \voiceTwo
    \magnifyMusic 0.63 {
      \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
      r32 c'' a c a c a c r c a c a c a c
      r c a c a c a c a c a c a c a c
    }
  }
>>
@end lilypond

The @code{\override} in the example above is a bug workaround.
See the @qq{Known issues and warnings} at the end of this section.

If a normal sized note head is merged with a smaller one, the size
of the smaller note may need to be reset (with
@w{@samp{\once@tie{}\normalsize}}) so that the stems and
accidentals align properly:

@c Chopin Prelude op.28 no.8
@lilypond[verbatim,quote]
\new Staff <<
  \key fis \minor
  \mergeDifferentlyDottedOn
  \new Voice \relative {
    \voiceOne
    \magnifyMusic 0.63 {
      \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
      \once \normalsize cis'32( cis' gis b a fis \once \normalsize d d'
      \once \normalsize cis, cis' gis b a gis \once \normalsize fis fis'
      \once \normalsize fis, fis' ais, cis b gis \once \normalsize eis eis'
      \once \normalsize a, a' bis, d cis b \once \normalsize gis gis')
    }
  }
  \new Voice \relative {
    \voiceTwo
    cis'8. d16 cis8. fis16 fis8. eis16 a8. gis16
  }
>>
@end lilypond

The @code{\magnifyMusic} command is not intended for cue notes,
grace notes, or ossia staves---there are more appropriate methods
of entering each of those constructs.  Instead, it is useful when
the notation size changes in a single instrumental part on one
staff, and where grace notes are not appropriate, such as in
cadenza-like passages or in cases such as the above examples.
Setting the @code{\magnifyMusic} value to 0.63 duplicates the
dimensions of the @code{CueVoice} context.

@warning{The @code{@bs{}magnifyMusic} command should @i{not} be
used when also resizing the staff.  See @ref{Setting the staff
size}.}


@subsubsubheading Resizing individual layout objects

An individual layout object can be resized by using the
@code{\tweak} or @code{\override} commands to adjust its
@code{font-size} property:

@lilypond[quote,verbatim,relative=1]
% resize a note head
<f \tweak font-size -4 b e>-5
% resize a fingering
bes-\tweak font-size 0 -3
% resize an accidental
\once \override Accidental.font-size = -4 bes!-^
% resize an articulation
\once \override Script.font-size = 4 bes!-^
@end lilypond

The default @code{font-size} value for each layout object is
listed in the Internals Reference.  The @code{font-size} property
can only be set for layout objects that support the
@code{font-interface} layout interface.  If @code{font-size} is
not specified in the object's @q{Standard@tie{}settings} list, its
value is 0.  See @rinternals{All layout objects}.


@subsubsubheading Understanding the @code{fontSize} property

The @code{fontSize} context property adjusts the relative size of
all glyph-based notational elements in a context:

@lilypond[verbatim,quote,relative=2]
\time 3/4
d4---5 c8( b a g) |
\set fontSize = -6
e'4-- c!8-4( b a g) |
\set fontSize = 0
fis4---3 e8( d) fis4 |
g2.
@end lilypond

The @code{fontSize} value is a number indicating the size relative
to the standard size for the current staff height.  The default
@code{fontSize} is 0; adding 6 to any @code{fontSize} value
doubles the printed size of the glyphs, and subtracting 6 halves
the size.  Each step increases the size by approximately 12%.

The scheme function @code{magnification->font-size} is provided
for convenience since the logarithmic units of the
@code{font-size} property are not entirely intuitive.  For
example, to adjust the musical notation to 75% of the default
size, use:

@example
\set fontSize = #(magnification->font-size 0.75)
@end example

The scheme function @code{magstep} does the opposite: it converts
a @code{font-size} value into a magnification factor.

The @code{fontSize} property will only affect notational elements
that are drawn with glyphs, such as noteheads, accidentals,
scripts, etc.  It will not affect the size of the staff itself,
nor will it scale stems, beams, or horizontal spacing.  To scale
stems, beams, and horizontal spacing along with the notation size
(without changing the staff size), use the @code{\magnifyMusic}
command discussed above.  To scale everything, including the staff
size, see @ref{Setting the staff size}.

Whenever the @code{fontSize} @i{context property} is set, its
value is added to the value of the @code{font-size} @i{grob
property} for individual layout objects, before any glyphs are
printed.  This can cause confusion when setting individual
@code{font-size} properties while @code{fontSize} is already set:

@lilypond[verbatim,quote,relative=2]
% the default font-size for NoteHead is 0
% the default font-size for Fingering is -5
c4-3

\set fontSize = -3
% the effective font size for NoteHead is now -3
% the effective font size for Fingering is now -8
c4-3

\override Fingering.font-size = 0
% the effective font size for Fingering is now -3
c4-3
@end lilypond

The following shorthand commands are also available:

@multitable @columnfractions .2 .4 .4
@item @b{Command} @tab @b{Equivalent to} @tab @b{Relative size}
@item @code{\teeny}      @tab @code{\set fontSize = -3} @tab 71%
@item @code{\tiny}       @tab @code{\set fontSize = -2} @tab 79%
@item @code{\small}      @tab @code{\set fontSize = -1} @tab 89%
@item @code{\normalsize} @tab @code{\set fontSize = 0} @tab 100%
@item @code{\large}      @tab @code{\set fontSize = 1} @tab 112%
@item @code{\huge}       @tab @code{\set fontSize = 2} @tab 126%
@end multitable

@lilypond[verbatim,quote,relative=2]
\teeny
c4.-> d8---3
\tiny
c4.-> d8---3
\small
c4.-> d8---3
\normalsize
c4.-> d8---3
\large
c4.-> d8---3
\huge
c4.-> d8---3
@end lilypond


@cindex standard font size (notation)
@cindex font size (notation), standard

@funindex font-interface
@funindex font-size

Font size changes are achieved by scaling the design size that is
closest to the desired size.  The standard font size (for
@w{@code{font-size = 0}}) depends on the standard staff height.
For a 20pt staff, a 11pt font is selected.


@predefined
@code{\magnifyMusic},
@code{\teeny},
@code{\tiny},
@code{\small},
@code{\normalsize},
@code{\large},
@code{\huge}.
@endpredefined

@seealso
Notation Reference:
@ref{Selecting font and font size},
@ref{Setting the staff size},
@ref{Formatting cue notes},
@ref{Ossia staves}.

Installed Files:
@file{ly/music-functions-init.ly},
@file{ly/property-init.ly}.

Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{font-interface}.

@c The two issues mentioned below:
@c http://code.google.com/p/lilypond/issues/detail?id=3987
@c http://code.google.com/p/lilypond/issues/detail?id=3990
@knownissues
There are currently two bugs that are preventing proper horizontal
spacing when using @code{\magnifyMusic}.  There is only one
available workaround, and it is not guaranteed to work in every
case.  In the example below, replace the @var{mag} variable with
your own value.  You may also try removing one or both of the
@code{\newSpacingSection} commands, and/or the @code{\override}
and @code{\revert} commands:

@example
\magnifyMusic @var{mag} @{
  \newSpacingSection
  \override Score.SpacingSpanner.spacing-increment = #(* 1.2 @var{mag})
  @var{[music]}
  \newSpacingSection
  \revert Score.SpacingSpanner.spacing-increment
@}
@end example


@node Fingering instructions
@unnumberedsubsubsec Fingering instructions

@cindex fingering
@cindex finger change

@funindex \finger
@funindex finger

Fingering instructions can be entered using
@samp{@var{note}-@var{digit}}:

@lilypond[verbatim,quote,relative=2]
c4-1 d-2 f-4 e-3
@end lilypond

Markup texts or strings may be used for finger changes.

@lilypond[verbatim,quote,relative=2]
c4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\finger "2 - 3"
@end lilypond

@cindex thumb-script

@funindex \thumb
@funindex thumb

A thumb-script can be added (e.g. cello music) to indicate
that a note should be played with the thumb.

@lilypond[verbatim,quote,relative=2]
<a_\thumb a'-3>2 <b_\thumb b'-3>
@end lilypond

@cindex fingering chords
@cindex fingering instructions for chords
@cindex chords, fingering

Fingerings for chords can also be added to individual notes by
adding them after the pitches.

@lilypond[verbatim,quote,relative=2]
<c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
@end lilypond

Fingering instructions may be manually placed above or below the
staff, see @ref{Direction and placement}.

@snippets

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{controlling-the-placement-of-chord-fingerings.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{allowing-fingerings-to-be-printed-inside-the-staff.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{avoiding-collisions-with-chord-fingerings.ly}

@seealso
Notation Reference:
@ref{Direction and placement}.

Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{FingeringEvent},
@rinternals{fingering-event},
@rinternals{Fingering_engraver},
@rinternals{New_fingering_engraver},
@rinternals{Fingering}.


@node Hidden notes
@unnumberedsubsubsec Hidden notes

@cindex hidden notes
@cindex invisible notes
@cindex transparent notes
@cindex notes, hidden
@cindex notes, invisible
@cindex notes, transparent

@funindex \hideNotes
@funindex hideNotes
@funindex \unHideNotes
@funindex unHideNotes

Hidden (or invisible or transparent) notes can be useful in
preparing theory or composition exercises.

@lilypond[verbatim,quote,relative=2]
c4 d
\hideNotes
e4 f
\unHideNotes
g a
\hideNotes
b
\unHideNotes
c
@end lilypond

Note heads, stems, and flags, and rests are invisible.  Beams
are invisible if they start on a hidden note.  Objects that are
attached to invisible notes are still visible.

@lilypond[verbatim,quote,relative=2]
e8(\p f g a)--
\hideNotes
e8(\p f g a)--
@end lilypond


@predefined
@code{\hideNotes},
@code{\unHideNotes}.
@endpredefined

@seealso
Learning Manual:
@rlearning{Visibility and color of objects}.

Notation Reference:
@ref{Invisible rests},
@ref{Visibility of objects},
@ref{Hiding staves}.

Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{Note_spacing_engraver},
@rinternals{NoteSpacing}.


@node Coloring objects
@unnumberedsubsubsec Coloring objects

@cindex colored objects
@cindex objects, colored
@cindex colors
@cindex coloring objects
@cindex colored notes
@cindex coloring notes
@cindex notes, colored
@cindex x11 color
@cindex x11-color
@cindex with-color

@funindex color
@funindex \with-color
@funindex with-color
@funindex x11-color

Individual objects may be assigned colors.  Valid color names
are listed in the @ref{List of colors}.

@lilypond[verbatim,quote,relative=2]
\override NoteHead.color = #red
c4 c
\override NoteHead.color = #(x11-color 'LimeGreen)
d
\override Stem.color = #blue
e
@end lilypond


The full range of colors defined for X11 can be accessed by using
the Scheme function @code{x11-color}.  The function takes one
argument; this can be a symbol in the form @code{'@var{FooBar}} or
a string in the form @code{"@var{FooBar}"}.  The first form is
quicker to write and is more efficient.  However, using the second
form it is possible to access X11 colors by the multi-word form of
its name.

If @code{x11-color} cannot make sense of the parameter then the
color returned defaults to black.

@lilypond[verbatim,quote,relative=2]
\override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
\set Staff.instrumentName = \markup {
  \with-color #(x11-color 'navy) "Clarinet"
}

gis8 a
\override Beam.color = #(x11-color "medium turquoise")
gis a
\override Accidental.color = #(x11-color 'DarkRed)
gis a
\override NoteHead.color = #(x11-color "LimeGreen")
gis a
% this is deliberate nonsense; note that the stems remain black
\override Stem.color = #(x11-color 'Boggle)
b2 cis
@end lilypond

@cindex rgb-color
@cindex color, rgb
@cindex rgb color

@funindex rgb-color

Exact RGB colors can be specified using the Scheme function
@code{rgb-color}.

@lilypond[verbatim,quote,relative=2]
\override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
\set Staff.instrumentName = \markup {
  \with-color #(x11-color 'navy) "Clarinet"
}

\override Stem.color = #(rgb-color 0 0 0)
gis8 a
\override Stem.color = #(rgb-color 1 1 1)
gis8 a
\override Stem.color = #(rgb-color 0 0 0.5)
gis4 a
@end lilypond

@seealso
Notation Reference:
@ref{List of colors}, @ref{The
tweak command}.

Snippets:
@rlsr{Editorial annotations}.

@cindex x11 color
@cindex colored notes in chords
@cindex notes, colored in chords
@cindex color in chords

@funindex x11-color

@knownissues
An X11 color is not necessarily exactly the same shade as a
similarly named normal color.

Not all X11 colors are distinguishable in a web browser, i.e.,
a web browser might not display a difference between @code{LimeGreen}
and @code{ForestGreen}.  For web use normal colors are recommended
(i.e., @code{blue}, @code{green}, @code{red}).

Notes in a chord cannot be separately colored with
@code{\override}; use @code{\tweak} or the equivalent
@code{\single\override} before the respective note instead, see
@ref{The tweak command}.


@node Parentheses
@unnumberedsubsubsec Parentheses

@cindex ghost notes
@cindex notes, ghost
@cindex notes, parenthesized
@cindex parentheses
@cindex brackets

@funindex \parenthesize
@funindex parenthesize

Objects may be parenthesized by prefixing @code{\parenthesize} to
the music event.  When prefixed to a chord, it parenthesizes every
note.  Individual notes inside a chord may also be parenthesized.

@lilypond[verbatim,quote,relative=2]
c2 \parenthesize d
c2 \parenthesize <c e g>
c2 <c \parenthesize e g>
@end lilypond

Non-note objects may be parenthesized as well.  For articulations,
a hyphen is needed before the @code{\parenthesize} command.

@lilypond[verbatim,quote,relative=2]
c2-\parenthesize -. d
c2 \parenthesize r
@end lilypond

@seealso
Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{Parenthesis_engraver},
@rinternals{ParenthesesItem},
@rinternals{parentheses-interface}.

@knownissues
Parenthesizing a chord prints parentheses around each individual
note, instead of a single large parenthesis around the entire
chord.


@node Stems
@unnumberedsubsubsec Stems

@cindex stem
@cindex stem, invisible
@cindex invisible stem

@funindex \stemUp
@funindex stemUp
@funindex \stemDown
@funindex stemDown
@funindex \stemNeutral
@funindex stemNeutral
@cindex stem, direction
@cindex stem, up
@cindex stem, down
@cindex stem, neutral

Whenever a note is found, a @code{Stem} object is created
automatically.  For whole notes and rests, they are also created but
made invisible.

Stems may be manually placed to point up or down; see
@ref{Direction and placement}.


@predefined
@code{\stemUp},
@code{\stemDown},
@code{\stemNeutral}.
@endpredefined


@snippets

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{default-direction-of-stems-on-the-center-line-of-the-staff.ly}

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}

@seealso
Notation Reference:
@ref{Direction and placement}.

Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{Stem_engraver},
@rinternals{Stem},
@rinternals{stem-interface}.


@node Outside the staff
@subsection Outside the staff

This section discusses how to add emphasis to elements in the staff
from outside of the staff.

@menu
* Balloon help::
* Grid lines::
* Analysis brackets::
@end menu

@node Balloon help
@unnumberedsubsubsec Balloon help

@cindex balloon
@cindex notation, explaining
@cindex balloon help
@cindex help, balloon

@funindex \balloonGrobText
@funindex \balloonText
@funindex Balloon_engraver
@funindex balloonGrobText
@funindex balloonText
@funindex \balloonLengthOn
@funindex balloonLengthOn
@funindex \balloonLengthOff
@funindex balloonLengthOff

Elements of notation can be marked and named with the help of a
square balloon.  The primary purpose of this feature is to explain
notation.

@lilypond[verbatim,quote,relative=2]
\new Voice \with { \consists "Balloon_engraver" }
{
  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
  a8
  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
  r
  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}
@end lilypond


There are two music functions, @code{balloonGrobText} and
@code{balloonText};  the former is used like
@w{@code{\once \override}} to attach text to any grob, and the
latter is used like @code{\tweak}, typically within chords, to
attach text to an individual note.

Balloon text does not influence note spacing, but this can be altered:

@lilypond[verbatim,quote,relative=2]
\new Voice \with { \consists "Balloon_engraver" }
{
  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
  a8
  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
  r
  \balloonLengthOn
  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}
@end lilypond

@predefined
@code{\balloonLengthOn},
@code{\balloonLengthOff}.
@endpredefined

@seealso
Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{Balloon_engraver},
@rinternals{BalloonTextItem},
@rinternals{balloon-interface}.


@node Grid lines
@unnumberedsubsubsec Grid lines

@cindex grid lines
@cindex lines, grid
@cindex vertical lines between staves
@cindex lines, vertical between staves

@funindex Grid_point_engraver
@funindex Grid_line_span_engraver
@funindex gridInterval

Vertical lines can be drawn between staves synchronized with the
notes.

The @code{Grid_point_engraver} must be used to create the end
points of the lines, while the @code{Grid_line_span_engraver} must
be used to actually draw the lines.  By default this centers grid
lines horizontally below and to the left side of each note head.
Grid lines extend from the middle lines of each staff.  The
@code{gridInterval} must specify the duration between the grid
lines.

@lilypond[verbatim,quote]
\layout {
  \context {
    \Staff
    \consists "Grid_point_engraver"
    gridInterval = #(ly:make-moment 1/4)
  }
  \context {
    \Score
    \consists "Grid_line_span_engraver"
  }
}

\score {
  \new ChoirStaff <<
    \new Staff \relative c'' {
      \stemUp
      c4. d8 e8 f g4
    }
    \new Staff \relative c {
      \clef bass
      \stemDown
      c4 g' f e
    }
  >>
}
@end lilypond

@snippets

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{grid-lines--changing-their-appearance.ly}

@seealso
Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{Grid_line_span_engraver},
@rinternals{Grid_point_engraver},
@rinternals{GridLine},
@rinternals{GridPoint},
@rinternals{grid-line-interface},
@rinternals{grid-point-interface}.


@node Analysis brackets
@unnumberedsubsubsec Analysis brackets

@cindex brackets
@cindex bracket, phrasing
@cindex phrasing bracket
@cindex musicological analysis
@cindex analysis, musicological
@cindex note grouping bracket
@cindex horizontal bracket
@cindex bracket, horizontal

@funindex Horizontal_bracket_engraver
@funindex \startGroup
@funindex startGroup
@funindex \stopGroup
@funindex stopGroup

Brackets are used in musical analysis to indicate structure in musical
pieces.  Simple horizontal brackets are supported.

@lilypond[verbatim,quote]
\layout {
  \context {
    \Voice
    \consists "Horizontal_bracket_engraver"
  }
}
\relative c'' {
  c2\startGroup
  d\stopGroup
}
@end lilypond

Analysis brackets may be nested.

@lilypond[verbatim,quote]
\layout {
  \context {
    \Voice
    \consists "Horizontal_bracket_engraver"
  }
}
\relative c'' {
  c4\startGroup\startGroup
  d4\stopGroup
  e4\startGroup
  d4\stopGroup\stopGroup
}
@end lilypond

@seealso
Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{Horizontal_bracket_engraver},
@rinternals{HorizontalBracket},
@rinternals{horizontal-bracket-interface},
@rinternals{Staff}.