Merge branch 'master' of git://git.sv.gnu.org/lilypond

[lilypond.git] / Documentation / user / 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.  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 @strong{text} font sizes, 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:
@lsrdir{Editorial,Editorial-annotations}.

Internals Reference:
@internalsref{fontSize},
@internalsref{font-size},
@internalsref{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

You can use the thumb-script (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:
@lsrdir{Editorial,Editorial-annotations}.

Internals Reference:
@internalsref{FingeringEvent},
@internalsref{fingering-event},
@internalsref{Fingering_engraver},
@internalsref{New_fingering_engraver},
@internalsref{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:
@lsrdir{Editorial,Editorial-annotations}.

Internals Reference:
@internalsref{Note_spacing_engraver},
@internalsref{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"
}
  
% black
\override Stem #'color = #(rgb-color 0 0 0)
gis8 a
% white
\override Stem #'color = #(rgb-color 1 1 1)
gis8 a
% dark blue
\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:
@lsrdir{Editorial,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:
@lsrdir{Editorial,Editorial-annotations}.

Internals Reference:
@internalsref{Parenthesis_engraver},
@internalsref{ParenthesesItem},
@internalsref{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:
@lsrdir{Editorial,Editorial-annotations}.

Internals Reference:
@internalsref{Stem_engraver},
@internalsref{Stem},
@internalsref{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.

@predefined

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

@seealso

Snippets:
@lsrdir{Editorial,Editorial-annotations}.

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


@node Grid lines
@unnumberedsubsubsec Grid lines

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

@lilypond[quote,verbatim,ragged-right]
\layout {
  \context {
    \Staff
    % set up grids
    \consists "Grid_point_engraver" 
    % set the grid interval to one quarter note
    gridInterval = #(ly:make-moment 1 4)
  }
  \context {
    \Score
    % by default this centers grid lines horizontally below
    % and to the left side of the note head, the grid lines
    % extending from the middle lines of each staff
    \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:
@lsrdir{Editorial,Editorial-annotations}.

Internals Reference:
@internalsref{Grid_line_span_engraver},
@internalsref{Grid_point_engraver},
@internalsref{GridLine},
@internalsref{GridPoint},
@internalsref{grid-line-interface},
@internalsref{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:
@lsrdir{Editorial,Editorial-annotations}.

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