Update from Jay.

[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

@node Editorial annotations
@section Editorial annotations

@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
{editorial-headword.ly}

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


@node Inside the staff
@subsection Inside the staff


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

@node Selecting notation font size
@subsubsection Selecting notation font size

@cindex font size
@cindex font size, selecting
@cindex selecting font size

The easiest method of setting the font size of any context is by
setting the @code{fontSize} property.

@lilypond[quote,fragment,relative=2,verbatim,ragged-right]
c4
\set fontSize = #-4
c f
\set fontSize = #3
g8 a
@end lilypond

@noindent
It does not change the size of variable symbols, such as beams or
slurs.

@cindex font size scaling

Internally, the @code{fontSize} context property will cause 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 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]
c4
\override NoteHead #'font-size = #-4
c f
\override NoteHead #'font-size = #3
g8 a
@end lilypond

@cindex standard font size
@cindex font size, 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} equals 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.

@refcommands

The following commands set @code{fontSize} for the current voice:

@funindex \tiny
@code{\tiny},
@funindex \small
@code{\small},
@funindex \normalsize
@code{\normalsize}.

@seealso

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

Internals Reference: @internalsref{font-interface}.


@node Fingering instructions
@subsubsection 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

Use markup texts 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>8 <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


@commonprop

@code{fingeringOrientations} are used to control where the fingering
numbers are placed.

@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
\set fingeringOrientations = #'(left)
<c-1 e-3 a-5 > 4
\set fingeringOrientations = #'(down)
<c-1 e-3 a-5 > 
\set fingeringOrientations = #'(right)
<c-1 e-3 a-5 > 
\set fingeringOrientations = #'(up)
<c-1 e-3 a-5 > 
\set fingeringOrientations = #'(left down)
<c-1 e-3 a-5 > 2
\set fingeringOrientations = #'(up right down)
<c-1 e-3 a-5 >
@end lilypond

@seealso

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

Internals Reference: @internalsref{Fingering}.


@node Hidden notes
@subsubsection 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 d4
\hideNotes
e4 f4
\unHideNotes
g4 a
\hideNotes 
b
\unHideNotes
c
@end lilypond

@seealso

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


@node Coloring objects
@subsubsection 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.  You may use the color
names 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 x11-color.  The function takes one argument
that can be a symbol

@example
\override Beam #'color = #(x11-color 'MediumTurquoise)
@end example

or a string

@example
\override Beam #'color = #(x11-color "MediumTurquoise")
@end example

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

@example
\override Beam #'color = #(x11-color "medium turquoise")
@end example

If x11-color cannot make sense of the parameter then the color
returned defaults to black.  It should be obvious from the final
score that something is wrong.

This example illustrates the use of x11-color.  Notice that the
stem color remains black after being set to (x11-color 'Boggle),
which is deliberate nonsense.

@lilypond[quote,ragged-right,verbatim]
{
  \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
  \set Staff.instrumentName = \markup {
    \with-color #(x11-color 'navy) "Clarinet"
  }
  \time 2/4
  gis''8 a''
  \override Beam #'color = #(x11-color "medium turquoise")
  gis'' a''
  \override NoteHead #'color = #(x11-color "LimeGreen")
  gis'' a''
  \override Stem #'color = #(x11-color 'Boggle)
  gis'' a''
}
@end lilypond

You can get exact RGB colors by specifying the rgb-color number.

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

  %black
  \override Stem #'color = #(rgb-color 0 0 0)
  c4
  % white
  \override Stem #'color = #(rgb-color 1 1 1)
  d
  % dark blue
  \override Stem #'color = #(rgb-color 0 0 0.5) 
  e
}
@end lilypond

@seealso

Notation Reference: @ref{List of colors}, @ref{Objects connected to
the input}.

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

@refbugs
Not all x11 colors are distinguishable in a web browser i.e. a web browser might not display a difference between 'LimeGreen and 'ForestGreen.  For web use normal colors are recommended. (#blue, #green, #red) TODOgp

An x11 color is not necessarily exactly the same shade as a
similarly named normal color.

Notes in a chord cannot be colored with @code{\override}; use
@code{\tweak} instead.  See @ref{Objects connected to the input},
for details.


@node Parentheses
@subsubsection Parentheses

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

Objects may be parenthesized by prefixing @code{\parenthesize} to
the music event,

@lilypond[relative=2,fragment,verbatim,ragged-right]
<
  c
  \parenthesize d
  g
>4-\parenthesize -.
d g 
< c
\parenthesize fis
>
@end lilypond

This only functions inside chords, to parenthesize a single note it 
must be enclosed with @code{<>} as if it is a chord.

@example
< \parenthesize NOTE>
@end example

@lilypond[relative=2,fragment,verbatim,ragged-right]
c4
<\parenthesize d>
g
<\parenthesize d>
@end lilypond

@seealso

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


@node Stems
@subsubsection 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.

@refcommands

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


@commonprop

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

To change the direction of stems on the center line of the staff, use

@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
a4 b c b
\override Stem #'neutral-direction = #up
a4 b c b
\override Stem #'neutral-direction = #down
a4 b c b
@end lilypond

@seealso

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


@node Outside the staff
@subsection Outside the staff


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

@node Balloon help
@subsubsection 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.

The following example demonstrates its use.

@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
\new Voice \with { \consists "Balloon_engraver" }
{
  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
  <f-\balloonText #'(-2 . -2) \markup { "I'm a note head" }  >8
}
@end lilypond

There are two music functions, @code{balloonGrobText} and
@code{balloonText}; the former takes the name of the grob to adorn,
while the latter may be used as an articulation on a note.  The other
arguments are the offset and the text of the label.

@cindex balloon
@cindex notation, explaining

@seealso

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

Internals Reference: @internalsref{text-balloon-interface}.


@node Grid lines
@subsubsection Grid lines

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

@lilypond[ragged-right,quote,verbatim]
\layout {
  \context {
    \Staff
    \consists "Grid_point_engraver" %% sets of grid
    gridInterval = #(ly:make-moment 1 4)
  }
}

\new Score \with {
  \consists "Grid_line_span_engraver"
  %% centers grid lines  horizontally below note heads
  \override NoteColumn #'X-offset = #-0.5
}

\new ChoirStaff <<
  \new Staff {
    \stemUp
    \relative {
      c'4. d8 e8 f g4
    }
  }
  \new Staff {
    %% centers grid lines  vertically
    \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
    \stemDown
    \clef bass
    \relative c {
      c4  g'  f  e
    }
  }
>>
@end lilypond

@seealso

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




@node Analysis brackets
@subsubsection 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.  LilyPond supports a simple form of nested horizontal
brackets.  To use this, add the @code{Horizontal_bracket_engraver} to
the @code{Staff} context.  A bracket is started with
@code{\startGroup} and closed with @code{\stopGroup}.

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

@seealso

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

Internals Reference: @internalsref{HorizontalBracket},
@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}.