Rewrites for Staff; thanks Eyolf!

[lilypond.git] / Documentation / user / staff.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 Staff notation
@section Staff notation

Notes, dynamic signs, etc., are grouped
with a set of horizontal lines, called a staff (plural @q{staves}).  In
LilyPond, these lines are drawn using a separate layout object called
@code{staff symbol}.

Two or more staves can be grouped vertically in a
@internalsref{GrandStaff}, a @internalsref{StaffGroup}, or a
@internalsref{ChoirStaff}.

@c It seemed awkward to have the general definition of a stave in the
@c second section, since it is already used in the first. I have moved it
@c here.


@menu
* Displaying staves::           
* Writing parts::               
@end menu


@node Displaying staves
@subsection Displaying staves

@menu
* System start delimiters::     
* Staff symbol::                
* Hiding staves::               
@end menu

@node System start delimiters
@unnumberedsubsubsec System start delimiters

@cindex start of system
@cindex Staff, multiple
@cindex bracket, vertical
@cindex brace, vertical
@cindex grand staff
@cindex staff group
@cindex staff, choir

Many scores consist of more than one staff.  These staves can be
grouped in several different ways:

@c The fourth delimiter, SystemStartSquare, should also be mentioned, with a
@c reference to the relevant section, and a single line of code here showing
@c how to achieve it.
 
@itemize @bullet
@item
In a @internalsref{GrandStaff},
the group is started with a brace at the left, and bar lines are connected
between the staves. 
@c Arpeggios can run through several staves of a @code{GrandStaff}

@lilypond[verbatim,ragged-right,quote]
\new GrandStaff
\relative <<
  \new Staff { c1 c }
  \new Staff { c c }
>>
@end lilypond

@item
In a @internalsref{StaffGroup}, the barlines
will be drawn through all the staves, but the group is started with a
bracket.

@lilypond[verbatim,ragged-right,quote]
\new StaffGroup
\relative <<
  \new Staff { c1 c }
  \new Staff { c c }
>>
@end lilypond

@item
In a @internalsref{ChoirStaff}, the group is started with a bracket,
but bar lines are not connected. 

@lilypond[verbatim,ragged-right,quote]
\new ChoirStaff
\relative <<
  \new Staff { c1 c }
  \new Staff { c c }
>>
@end lilypond

@item
If no context is specified, the default properties for the score will
be used: the group is started with a vertical line, and the bar lines are
not connected.  

@lilypond[verbatim,ragged-right,quote]
\relative <<
  \new Staff { c1 c }
  \new Staff { c c }
>>
@end lilypond
@end itemize

In addition to these four staff group types, other groupings can
be produced by changing various properties. E.g., the
"Mensurstriche" layout common in Renaissance music, with barlines
running between but not through the staves, can be produced from a
@code{StaffGroup} or @code{GrandStaff} context if the barlines are
made transparent in the @code{Staff} itself, with the command
@code{\override Staff.BarLine #'transparent = ##t}

@seealso

The bar lines at the start of each system are
@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
@internalsref{SystemStartBracket}.  Only one of these types is created
in every context, and that type is determined by the property
@code{systemStartDelimiter}.


@commonprop
@c Is it possible to use other headings than this one? It's not very
@c informative... "Nesting braces and brackets" would be better, imho. 

System start delimiters may be deeply nested,

@lilypond[quote,ragged-right,verbatim]
\new StaffGroup
\relative <<
  \set StaffGroup.systemStartDelimiterHierarchy
    = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d)
  \new Staff { c1 }
  \new Staff { c1 }
  \new Staff { c1 }
  \new Staff { c1 }
  \new Staff { c1 }
>>
@end lilypond


@node Staff symbol
@unnumberedsubsubsec Staff symbol

@cindex adjusting staff symbol

The layout object which draws the lines of a staff is called @code{staff
symbol}.  The staff symbol may be tuned in the number, thickness and
distance of lines, using properties.  This is demonstrated in the example
files @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
@lsr{staff,changing-the-staff-size.ly}.

In addition, staves may be started and stopped at will.  This is done
with @code{\startStaff} and @code{\stopStaff}.

@lilypond[verbatim,relative=2,fragment]
b4 b
\override Staff.StaffSymbol #'line-count = 2
\stopStaff \startStaff
b b
\revert Staff.StaffSymbol #'line-count
\stopStaff \startStaff
b b
@end lilypond

In combination with Frenched staves, this may be used to typeset ossia
sections.  An example is shown here

@cindex ossia

@lilypondfile{ossia.ly}

@cindex staff lines, setting number of
@cindex staff lines, setting thickness of
@cindex thickness of staff lines, setting
@cindex number of staff lines, setting

@seealso

Program reference: @internalsref{StaffSymbol}.

Examples: @lsrdir{staff}


@node Hiding staves
@unnumberedsubsubsec Hiding staves

@cindex Frenched scores
@cindex Hiding staves

In orchestral scores, staff lines that only have rests are usually
removed; this saves some space.  This style is called @q{French
Score}.  For @internalsref{Lyrics}, @internalsref{ChordNames} and
@internalsref{FiguredBass}, this is switched on by default.  When
the lines of these contexts turn out empty after the line-breaking
process, they are removed.

For normal staves, a specialized @internalsref{Staff} context is
available, which does the same: staves containing nothing (or only
multi-measure rests) are removed.  The context definition is stored in
@code{\RemoveEmptyStaffContext} variable.  Observe how the second staff
in this example disappears in the second line

@lilypond[quote,ragged-right,verbatim]
\layout {
  \context { \RemoveEmptyStaffContext }
}

{
  \relative c' <<
    \new Staff { e4 f g a \break c1 }
    \new Staff { c4 d e f \break R1 }
  >>
}
@end lilypond

The first system shows all staves in full.  If empty staves should be
removed from the first system too, set @code{remove-first} to true in
@internalsref{VerticalAxisGroup}.

@example
\override Score.VerticalAxisGroup #'remove-first = ##t
@end example

To remove other types of contexts, use @code{\AncientRemoveEmptyStaffContext}
or @code{\RemoveEmptyRhythmicStaffContext}.

Another application is making ossia sections, i.e., alternative
melodies on a separate piece of staff, with help of a Frenched
staff.  



@node Writing parts
@subsection Writing parts

@menu
* Metronome marks::             
* Instrument names::            
* Quoting other voices::        
* Formatting cue notes::        
@end menu

@node Metronome marks
@unnumberedsubsubsec Metronome marks

@cindex Tempo
@cindex beats per minute
@cindex metronome marking

Metronome settings can be entered as follows
@example
\tempo @var{duration} = @var{per-minute}
@end example

In the MIDI output, they are interpreted as a tempo change.  In the
layout output, a metronome marking is printed
@funindex \tempo
@lilypond[quote,ragged-right,verbatim,fragment]
\tempo 8.=120 c''1
@end lilypond


@commonprop

To change the tempo in the MIDI output without printing anything, make
the metronome marking invisible
@example
\once \override Score.MetronomeMark #'transparent = ##t
@end example

To print other metronome markings, use these markup commands
@lilypond[quote,ragged-right,verbatim,relative,fragment]
c4^\markup {
  (
  \smaller \general-align #Y #DOWN \note #"16." #1
  =
  \smaller \general-align #Y #DOWN \note #"8" #1
  ) }
@end lilypond

@noindent
See @ref{Text markup}, for more details.


@seealso

Program reference: @internalsref{MetronomeMark}.


@refbugs

Collisions are not checked.  If you have notes above the top line of
the staff (or notes with articulations, slurs, text, etc), then the
metronome marking may be printed on top of musical symbols.  If this
occurs, increase the padding of the metronome mark to place it
further away from the staff.

@example
\override Score.MetronomeMark #'padding = #2.5
@end example


@node Instrument names
@unnumberedsubsubsec Instrument names

In an orchestral score, instrument names are printed at the left side
of the staves.

This can be achieved by setting @internalsref{Staff}.@code{instrumentName}
and @internalsref{Staff}.@code{shortInstrumentName}, or
@internalsref{PianoStaff}.@code{instrumentName} and
@internalsref{PianoStaff}.@code{shortInstrumentName}.  This will
print text before
the start of the staff.  For the first staff, @code{instrumentName} is
used, for the following ones, @code{shortInstrumentName} is used.

@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
\set Staff.instrumentName = "Ploink "
\set Staff.shortInstrumentName = "Plk "
c1
\break
c''
@end lilypond

You can also use markup texts to construct more complicated instrument
names, for example

@lilypond[quote,fragment,verbatim,ragged-right]
\set Staff.instrumentName = \markup {
  \column { "Clarinetti"
            \line { "in B" \smaller \flat } } }
c''1
@end lilypond

If you wish to center the instrument names, you must center all of them

@lilypond[quote,verbatim,ragged-right]
{ <<
\new Staff {
  \set Staff.instrumentName = \markup {
    \center-align { "Clarinetti"
      \line { "in B" \smaller \flat } } }
  c''1
}
\new Staff {
  \set Staff.instrumentName = \markup{ \center-align { Vibraphone }}
  c''1
}
>>
}
@end lilypond

For longer instrument names, it may be useful to increase the
@code{indent} setting in the @code{\layout} block.

To center instrument names while leaving extra space to the right,

@lilypond[quote,verbatim,ragged-right]
\new StaffGroup \relative
<<
  \new Staff {
    \set Staff.instrumentName = \markup { \hcenter-in #10 "blabla" }
    c1 c1
  }
  \new Staff {
    \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" }
    c1 c1
  }
>>
@end lilypond

To add instrument names to other contexts (such as @code{GrandStaff},
@code{ChoirStaff}, or @code{StaffGroup}), the engraver must
be added to that context.

@example
\layout@{
  \context @{\GrandStaff \consists "Instrument_name_engraver"@}
@}
@end example

@noindent
More information about adding and removing engravers can
be found in @ref{Modifying context plug-ins}.

Instrument names may be changed in the middle of a piece,

@lilypond[quote,fragment,verbatim,ragged-right]
\set Staff.instrumentName = "First"
\set Staff.shortInstrumentName = "one"
c1 c c c \break
c1 c c c \break
\set Staff.instrumentName = "Second"
\set Staff.shortInstrumentName = "two"
c1 c c c \break
c1 c c c \break
@end lilypond


@seealso

Program reference: @internalsref{InstrumentName}.


@node Quoting other voices
@unnumberedsubsubsec Quoting other voices

@cindex cues

With quotations, fragments of other parts can be inserted into a part
directly.  Before a part can be quoted, it must be marked especially as
quotable.  This is done with the @code{\addQuote} command.

@example
\addQuote @var{name} @var{music}
@end example


@noindent
Here, @var{name} is an identifying string.  The @var{music} is any kind
of music.  Here is an example of @code{\addQuote}

@example
\addQuote clarinet \relative c' @{
  f4 fis g gis
@}
@end example

This command must be entered at toplevel, i.e., outside any music
blocks.

After calling @code{\addQuote}, the quotation may then be done with
@code{\quoteDuring} or @code{\cueDuring},

@example
\quoteDuring #@var{name} @var{music}
@end example

During a part, a piece of music can be quoted with the @code{\quoteDuring}
command.

@example
\quoteDuring #"clarinet" @{ s2. @}
@end example

This would cite three quarter notes (the duration of @code{s2.})  of
the previously added @code{clarinet} voice.


More precisely, it takes the current time-step of the part being
printed, and extracts the notes at the corresponding point of the
@code{\addQuote}d voice.  Therefore, the argument to @code{\addQuote}
should be the entire part of the voice to be quoted, including any
rests at the beginning.

Quotations take into account the transposition of both source and target
instruments, if they are specified using the @code{\transposition} command.

@lilypond[quote,ragged-right,verbatim]
\addQuote clarinet \relative c' {
  \transposition bes
  f4 fis g gis
}

{
  e'8 f'8 \quoteDuring #"clarinet" { s2 }
}
@end lilypond

The type of events that are present in cue notes can be trimmed with
the @code{quotedEventTypes} property.  The default value is
@code{(note-event rest-event)}, which means that only notes and
rests of the cued voice end up in the @code{\quoteDuring}.
Setting

@example
\set Staff.quotedEventTypes =
       #'(note-event articulation-event dynamic-event)
@end example

@noindent
will quote notes (but no rests), together with scripts and dynamics.

@refbugs

Only the contents of the first @internalsref{Voice} occurring in an
@code{\addQuote} command will be considered for quotation, so
@var{music} can not contain @code{\new} and @code{\context Voice}
statements that would switch to a different Voice.

Quoting grace notes is broken and can even cause LilyPond to crash.

Quoting nested triplets may result in poor notation.


@seealso

In this manual: @ref{Instrument transpositions}.

Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly}

Program reference: @internalsref{QuoteMusic}.


@node Formatting cue notes
@unnumberedsubsubsec Formatting cue notes

@cindex cues, formatting

The previous section deals with inserting notes from another voice.
There is a more advanced music function called @code{\cueDuring},
which makes formatting cue notes easier.

The syntax is

@example
  \cueDuring #@var{name} #@var{updown} @var{music}
@end example

This will insert notes from the part @var{name} into a
@internalsref{Voice} called @code{cue}.  This happens simultaneously
with @var{music}, which usually is a rest.  When the cue notes start,
the staff in effect becomes polyphonic for a moment.  The argument
@var{updown} determines whether the cue notes should be notated as a
first or second voice.


@lilypond[verbatim,ragged-right]
smaller = {
  \set fontSize = #-2
  \override Stem #'length-fraction = #0.8
  \override Beam #'thickness = #0.384
  \override Beam #'length-fraction = #0.8
}

\addQuote clarinet \relative {
  R1*20
  r2 r8 c' f f
}

\new Staff \relative  <<

  % setup a context for cue notes.
  \new Voice = "cue" { \smaller \skip 1*21 }

  \set Score.skipBars = ##t

  \new Voice {
    R1*20
    \cueDuring #"clarinet" #UP {
      R1
    }
    g4 g2.
  }
>>
@end lilypond


Here are a couple of hints for successful cue notes

@itemize @bullet
@item
Cue notes have smaller font sizes.
@item
 the cued part is marked with the instrument playing the cue.
@item
 when the original part takes over again, this should be marked with
 the name of the original instrument.

@c really?  Are you sure about that last point?  I'll check after 3.0 -gp

@c Yes, this is good practice.  Otherwise, the start of the original
@c part can only be seen from the font size.  This is not good enough
@c for sight-reading.  It is possilbe to use other
@c markers (e.g. a big close-bracket over the staff) to indicate the cue
@c   notes are
@c finished.
@c -hwn


Any other changes introduced by the cued part should also be
undone.  For example, if the cued instrument plays in a different clef,
the original clef should be stated once again.

@end itemize

The macro @code{\transposedCueDuring} is
useful to add cues to instruments which use a completely different
octave range (for example, having a cue of a piccolo flute within
a contra bassoon part).

@lilypond[verbatim,ragged-right,quote]
picc = \relative c''' {
  \clef "treble^8"
  R1 |
  c8 c c e g2 |
  a4 g g2 |
}
\addQuote "picc" { \picc }

cbsn = \relative c, {
  \clef "bass_8"
  c4 r g r
  \transposedCueDuring #"picc" #UP c,, { R1 } |
  c4 r g r |
}

<<
  \context Staff = "picc" \picc
  \context Staff = "cbsn" \cbsn
>>
@end lilypond