Clarify colors, issue 490.

[lilypond.git] / Documentation / user / educational.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 Educational use
@section Educational use

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


@node Note heads
@subsection Note heads

@menu
* Easy notation note heads::    
* Shape note heads::            
* Improvisation::               
* Special noteheads::           
@end menu

@node Easy notation note heads
@unnumberedsubsubsec Easy notation note heads

@cindex note heads, practice
@cindex note heads, easy notation
@cindex easy notation
@cindex Hal Leonard

The @q{easy play} note head includes a note name inside the head.
It is used in music for beginners

@lilypond[quote,ragged-right,verbatim,fragment,staffsize=26]
  \setEasyHeads
  c'2 e'4 f' | g'1
@end lilypond

The command @code{\setEasyHeads} overrides settings for the
@internalsref{NoteHead} object.  To make the letters readable, it
has to be printed in a large font size.  To print with a larger
font, see @ref{Setting the staff size}.

@refcommands

@funindex \setEasyHeads
@code{\setEasyHeads}


@node Shape note heads
@unnumberedsubsubsec Shape note heads

@cindex note heads, shape

In shape note head notation, the shape of the note head
corresponds to the harmonic function of a note in the scale.  This
notation was popular in the 19th century American song books.

Shape note heads can be produced by setting @code{\aikenHeads} or
@code{\sacredHarpHeads}, depending on the style desired.

@lilypond[verbatim,relative=1,fragment]
  \aikenHeads
  c8 d4 e8 a2 g1
  \sacredHarpHeads
  c8 d4. e8 a2 g1
@end lilypond

Shapes are determined on the step in the scale, where the base of
the scale is determined by  the @code{\key} command

@funindex \key
@funindex shapeNoteStyles
@funindex \aikenHeads
@funindex \sacredHarpHeads

Shape note heads are implemented through the
@code{shapeNoteStyles} property.  Its value is a vector of
symbols.  The k-th element indicates the style to use for the k-th
step of the scale.  Arbitrary combinations are possible, e.g.

@lilypond[verbatim,relative=1,fragment]
\set shapeNoteStyles =
  ##(cross triangle fa #f mensural xcircle diamond)
c8 d4. e8 a2 g1
@end lilypond


@node Improvisation
@unnumberedsubsubsec Improvisation

Improvisation is sometimes denoted with slashed note heads.  Such
note heads can be created by adding a
@internalsref{Pitch_squash_engraver} to the @internalsref{Voice}
context.  Then, the following command

@example
\set squashedPosition = #0
\override NoteHead #'style = #'slash
@end example

@noindent
switches on the slashes.

There are shortcuts @code{\improvisationOn} (and an accompanying
@code{\improvisationOff}) for this command sequence.  They are
used in the following example

@lilypond[verbatim,ragged-right,quote]
\new Voice \with {
  \consists Pitch_squash_engraver
} \transpose c c' {
  e8 e g a a16(bes)(a8) g \improvisationOn
  e8
  ~e2~e8 f4 fis8
  ~fis2 \improvisationOff a16(bes) a8 g e
}
@end lilypond


@node Special noteheads
@unnumberedsubsubsec Special noteheads

@cindex note heads, special

Different noteheads are used by various instruments for various
meanings -- crosses are used for @q{parlato} with vocalists,
stopped notes on guitar; diamonds are used for harmonics on string
instruments, etc.  There is a shorthand (@code{\harmonic}) for
diamond shapes; the other notehead styles are produced by tweaking
the property

@lilypond[ragged-right,relative=1,fragment,verbatim,quote]
c4 d
\override NoteHead #'style = #'cross
e f
\revert NoteHead #'style
e d <c f\harmonic> <d a'\harmonic>
@end lilypond

@noindent
To see all notehead styles, please see @ref{Note head styles}.


@seealso

Program reference: @internalsref{NoteHead}.



@node Inside the staff
@subsection Inside the staff


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

@node Selecting notation font size
@unnumberedsubsubsec Selecting notation 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.

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

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
@internalsref{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}.


@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

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

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

Program reference: @internalsref{Fingering}.

Examples: @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, even for single notes

@example
< \parenthesize NOTE>
@end example


@node Ambitus
@unnumberedsubsubsec Ambitus
@cindex ambitus

The term @emph{ambitus} denotes a range of pitches for a given
voice in a part of music.  It may also denote the pitch range that
a musical instrument is capable of playing.  Ambits are printed on
vocal parts, so performers can easily determine it meets their
capabilities.

Ambits are denoted at the beginning of a piece near the initial
clef.  The range is graphically specified by two note heads that
represent the minimum and maximum pitch.  To print such ambits,
add the @internalsref{Ambitus_engraver} to the
@internalsref{Voice} context, for example,

@example
\layout @{
  \context @{
    \Voice
    \consists Ambitus_engraver
  @}
@}
@end example

This results in the following output

@lilypond[quote,ragged-right]
\layout {
  \context {
    \Staff
    \consists Ambitus_engraver
  }
}

\relative \new Staff {
  as'' c e2 cis,2
}
@end lilypond

If you have multiple voices in a single staff and you want a
single ambitus per staff rather than per each voice, add the
@internalsref{Ambitus_engraver} to the @internalsref{Staff}
context rather than to the @internalsref{Voice} context.  Here is
an example,

@lilypond[verbatim,ragged-right,quote]
\new Staff \with {
  \consists "Ambitus_engraver"
}
<<
  \new Voice \with {
    \remove "Ambitus_engraver"
  } \relative c'' {
    \override Ambitus #'X-offset = #-1.0
    \voiceOne
    c4 a d e f2
  }
  \new Voice \with {
    \remove "Ambitus_engraver"
  } \relative c' {
    \voiceTwo
    es4 f g as b2
  }
>>
@end lilypond

@noindent
This example uses one advanced feature,

@example
\override Ambitus #'X-offset = #-1.0
@end example

@noindent
This code moves the ambitus to the left.  The same effect could
have been achieved with @code{extra-offset}, but then the
formatting system would not reserve space for the moved object.

@seealso

Program reference: @internalsref{Ambitus},
@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
@internalsref{AmbitusAccidental}.

Examples:
@lsr{vocal,ambitus@/.ly}.

@refbugs

There is no collision handling in the case of multiple per-voice
ambitus.


@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 in the middle 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::           
@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" }
  <c-\balloonText #'(-2 . -2) \markup { Hello }  >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

Program 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 noteheads
  \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