@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.  See TRANSLATION for details.
@end ignore

@c \version "2.11.38"

@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)
@cindex selecting font size (notation)

The font size of notation elements may be altered.  It does not
change the size of variable symbols, such as beams or slurs.

@warning{For font sizes of text, see
@ref{Common markup commands}.}

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

@cindex font size (notation) scaling

Internally, this sets the @code{fontSize} property.  This in turn
causes the @code{font-size} property to be set in all layout
objects.  The value of @code{font-size} is a number indicating the
size relative to the standard size for the current staff height.
Each step up is an increase of approximately 12% of the font size.
Six steps is exactly a factor of two.  The Scheme function
@code{magstep} converts a @code{font-size} number to a scaling
factor.  The @code{font-size} property can also be set directly,
so that only certain layout objects are affected.

@lilypond[quote,fragment,relative=2,verbatim,ragged-right]
\set fontSize = #3
c4.-> d8---3
\override NoteHead #'font-size = #-4
c4.-> d8---3
\override Script #'font-size = #2
c4.-> d8---3
\override Stem #'font-size = #-5
c4.-> d8---3
@end lilypond

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

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

The @code{font-size} property can only be set on layout objects
that use fonts.  These are the ones supporting the
@code{font-interface} layout interface.

@predefined

@funindex \teeny
@code{\teeny},
@funindex \tiny
@code{\tiny},
@funindex \small
@code{\small},
@funindex \normalsize
@code{\normalsize},
@funindex \large
@code{\large},
@funindex \huge
@code{\huge}.

@seealso

Snippets:
@rlsr{Editorial annotations}.

Internals Reference:
@rinternals{fontSize},
@rinternals{font-size},
@rinternals{font-interface}.


@node Fingering instructions
@unnumberedsubsubsec Fingering instructions

@cindex fingering
@cindex finger change

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

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

Markup texts may be used for finger changes. 

@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
@end lilypond

@cindex thumb-script

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

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

@cindex fingering chords
@cindex chords, fingering

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

@lilypond[quote,verbatim,ragged-right,fragment,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{Controlling direction and placement}.

@snippets

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


@seealso

Notation Reference:
@ref{Controlling 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
@funindex \hideNotes
@funindex \unHideNotes

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

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

Notation objects which are attached to invisible notes are still
visible.

@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
c4( d)
\hideNotes
e4(\p f)--
@end lilypond


@predefined

@funindex \hideNotes
@funindex \unHideNotes
@code{\hideNotes}, @code{\unHideNotes}

@seealso

Snippets:
@rlsr{Editorial annotations}.

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


@node Coloring objects
@unnumberedsubsubsec Coloring objects

@cindex colored objects
@cindex colors
@cindex coloring objects
@cindex colored notes
@cindex coloring notes
@cindex notes, colored

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

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

@cindex x11-color

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 @var{'FooBar} or a
string in the form @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[quote,ragged-right,verbatim,fragment,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

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

@lilypond[quote,ragged-right,verbatim,fragment,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{Objects connected to
the input}.

Snippets:
@rlsr{Editorial annotations}.

@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 colored with @code{\override}; use
@code{\tweak} instead, see @ref{Objects connected to the input}.


@node Parentheses
@unnumberedsubsubsec Parentheses

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

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[quote,relative=2,fragment,verbatim,ragged-right]
c2 \parenthesize d
c2 \parenthesize <c e g>
c2 <c \parenthesize e g>
@end lilypond

Non-note objects may be parenthesized as well.

@lilypond[quote,relative=2,fragment,verbatim,ragged-right]
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

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

@predefined

@funindex \stemUp
@code{\stemUp},
@funindex \stemDown
@code{\stemDown},
@funindex \stemNeutral
@code{\stemNeutral}.


@snippets

@cindex stem, direction
@cindex stem, up
@cindex stem, down
@cindex stem, neutral

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

@seealso
Notation Reference:
@ref{Controlling 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

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[quote,verbatim,fragment,ragged-right,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

@cindex balloon
@cindex notation, explaining

There are two music functions, @code{balloonGrobText} and
@code{balloonText};  the former is used like @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 normally influences note spacing, but this can be
altered:

@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
\new Voice \with { \consists "Balloon_engraver" }
{
  \balloonLengthOff
  \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

@funindex balloonLengthOn
@funindex balloonLengthOff
@code{\balloonLengthOn}, @code{\balloonLengthOff}

@seealso

Snippets:
@rlsr{Editorial annotations}.

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


@node Grid lines
@unnumberedsubsubsec Grid lines

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[quote,verbatim,ragged-right]
\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,lilyquote,ragged-right,texidoc]
{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 phrasing brackets
@cindex musicological analysis
@cindex note grouping bracket

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

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

Analysis brackets may be nested.

@lilypond[quote,verbatim,ragged-right]
\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}.