[lilypond.git] / Documentation / user / educational.itely

@c -*- coding: utf-8; mode: texinfo; -*-

@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


@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