Begin using 3-value @lsr macros.

[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
@unnumberedsubsubsec 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=1,verbatim]
c8
\set fontSize = #-4
c f
\set fontSize = #3
g
@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=1,verbatim]
c8
\override NoteHead #'font-size = #-4
c f
\override NoteHead #'font-size = #3
g
@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}.

Internals Reference: @internalsref{font-interface}.


@node Fingering instructions
@unnumberedsubsubsec Fingering instructions

@cindex fingering
@cindex finger change

Fingering instructions can be entered using

@example
@var{note}-@var{digit}
@end example

For finger changes, use markup texts

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

@cindex thumb-script


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

@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 >4
@end lilypond


@commonprop

You may exercise greater control over fingering chords by setting
@code{fingeringOrientations}

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

Using this feature, it is also possible to put fingering
instructions very close to note heads in monophonic music,

@lilypond[verbatim,ragged-right,quote,fragment]
\set fingeringOrientations = #'(right)
<es'-2>4
@end lilypond


@seealso

Snippets: @lsrdir{editorial}.

Internals Reference: @internalsref{Fingering}.

Examples: @c @lsr{expressive,fingering-chords.ly}



@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 d4
\hideNotes
e4 f4
\unHideNotes
g4 a
@end lilypond


@node Coloring objects
@unnumberedsubsubsec Coloring objects

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=1]
\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 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


TODO
you can get exact RGB colors by specifying

% black
\override Stem #'color = #(rgb-color 0 0 0)
% white
\override Stem #'color = #(rgb-color 1 1 1)
% dark blue
\override Stem #'color = #(rgb-color 0 0 0.5) 


@seealso

Appendix: @ref{List of colors}.


@refbugs
Not all x11 colors are distinguishable in a web browser.  For web
use normal colors are recommended.

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
@unnumberedsubsubsec Parentheses

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

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 -.
@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


@node Stems
@unnumberedsubsubsec Stems

Whenever a note is found, a @internalsref{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

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


@node Outside the staff
@subsection Outside the staff


@menu
* Balloon help::                
* Grid lines::                  
* Blank music sheet::           
* 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.

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

@noindent
There are two music functions, @code{balloonText} and
@code{balloonGrobText}.  The latter takes the name of the grob to
adorn, while the former 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

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


@node Grid lines
@unnumberedsubsubsec 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

Examples: @lsrdir{education}


@node Blank music sheet
@unnumberedsubsubsec Blank music sheet

@cindex Sheet music, empty
@cindex Staves, blank sheet

A blank music sheet can be produced also by using invisible notes,
and removing @code{Bar_number_engraver}.


@lilypond[quote,verbatim]
\layout{ indent = #0 }
emptymusic = {
  \repeat unfold 2 % Change this for more lines.
  { s1\break }
  \bar "|."
}
\new Score \with {
  \override TimeSignature #'transparent = ##t
% un-comment this line if desired
%  \override Clef #'transparent = ##t
  defaultBarType = #""
  \remove Bar_number_engraver
} <<

% modify these to get the staves you want
  \new Staff \emptymusic
  \new TabStaff \emptymusic
>>
@end lilypond


@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.  LilyPond supports a simple form of nested
horizontal brackets.  To use this, add the
@internalsref{Horizontal_bracket_engraver} to the
@internalsref{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

Internals Reference: @internalsref{HorizontalBracket}.