Revert "DOC -- Index editorial, pitches, staff. Ralph Palmer's work"

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

diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index 9c6e40a36380f16da6615447a252300e7f5558fe..3791eacb71b6954ad5237a783ae82c64de57db8c 100644 (file)
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -6,16 +6,16 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.57"
+@c \version "2.11.64"

 
 @node Staff notation
 @section Staff notation
 
 @lilypondfile[quote]{staff-headword.ly}
 
 
 @node Staff notation
 @section Staff notation
 
 @lilypondfile[quote]{staff-headword.ly}
 

-This section explains how to influence the staff appearance, print
-scores with more than one staff, and how to apply specific
-performance marks to single staves.
+This section explains how to influence the appearance of staves,
+how to print scores with more than one staff, and how to add tempo
+indications and cue notes to staves.

 
 @menu
 * Displaying staves::
 
 @menu
 * Displaying staves::


@@ -28,13 +28,12 @@ performance marks to single staves.
 @subsection Displaying staves
 
 This section describes the different methods of creating and
 @subsection Displaying staves
 
 This section describes the different methods of creating and

-grouping staves, which are marked at the beginning of each line
-with either a bracket or a brace.
+grouping staves.

 
 @menu
 * Instantiating new staves::
 * Grouping staves::
 
 @menu
 * Instantiating new staves::
 * Grouping staves::

-* Deeper nested staff groups::
+* Nested staff groups::

 @end menu
 
 
 @end menu
 
 


@@ -63,9 +62,10 @@ The basic staff context is @code{Staff}:
 \new Staff { c4 d e f }
 @end lilypond
 
 \new Staff { c4 d e f }
 @end lilypond
 

-@code{DrumStaff} creates a five-line staff set up for a
-typical drum set.  It uses different names for each instrument.
-The instrument names are set using the @code{\drummode} command.
+The @code{DrumStaff} context creates a five-line staff set up for
+a typical drum set.  Each instrument is shown with a different
+symbol.  The instruments are entered in drum mode following a
+@code{\drummode} command, with each instrument specified by name.

 For details, see @ref{Percussion staves}.
 
 @lilypond[verbatim,quote]
 For details, see @ref{Percussion staves}.
 
 @lilypond[verbatim,quote]


@@ -74,14 +74,6 @@ For details, see @ref{Percussion staves}.
 }
 @end lilypond
 
 }
 @end lilypond
 

-@c FIXME: remove when mentioned in NR 2.8
-@code{GregorianTranscriptionStaff} creates a staff to notate
-modern Gregorian chant.  It does not show bar lines.
-
-@lilypond[verbatim,quote,relative=2]
-\new GregorianTranscriptionStaff { c4 d e f }
-@end lilypond
-

 @code{RhythmicStaff} creates a single-line staff that only
 displays the rhythmic values of the input.  Real durations are
 preserved. For details, see @ref{Showing melody rhythms}.
 @code{RhythmicStaff} creates a single-line staff that only
 displays the rhythmic values of the input.  Real durations are
 preserved. For details, see @ref{Showing melody rhythms}.


@@ -101,12 +93,18 @@ There are two staff contexts specific for the notation of ancient
 music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
 described in @ref{Pre-defined contexts}.
 
 music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
 described in @ref{Pre-defined contexts}.
 

+The @code{GregorianTranscriptionStaff} context creates a staff to
+notate modern Gregorian chant.  It does not show bar lines.
+
+@lilypond[verbatim,quote,relative=2]
+\new GregorianTranscriptionStaff { c4 d e f e d }
+@end lilypond
+

 New single staff contexts may be defined.  For details, see
 @ref{Defining new contexts}.
 
 
 @seealso
 New single staff contexts may be defined.  For details, see
 @ref{Defining new contexts}.
 
 
 @seealso

-

 Music Glossary:
 @rglos{staff},
 @rglos{staves}.
 Music Glossary:
 @rglos{staff},
 @rglos{staves}.


@@ -236,11 +234,9 @@ New staff group contexts may be defined.  For details, see
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {mensurstriche-layout-bar-lines-between-the-staves.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {mensurstriche-layout-bar-lines-between-the-staves.ly}

-@c FIXME: move to NR 2.8.x when sectioning is ready

 
 
 @seealso
 
 
 @seealso

-

 Music Glossary:
 @rglos{brace},
 @rglos{bracket},
 Music Glossary:
 @rglos{brace},
 @rglos{bracket},


@@ -265,8 +261,8 @@ Internals Reference:
 @rinternals{SystemStartSquare}.
 
 
 @rinternals{SystemStartSquare}.
 
 

-@node Deeper nested staff groups
-@unnumberedsubsubsec Deeper nested staff groups
+@node Nested staff groups
+@unnumberedsubsubsec Nested staff groups

 
 @cindex staff, nested
 @cindex staves, nested
 
 @cindex staff, nested
 @cindex staves, nested


@@ -275,40 +271,24 @@ Internals Reference:
 @cindex nested staff brackets
 @cindex brackets, nesting of
 @cindex braces, nesting of
 @cindex nested staff brackets
 @cindex brackets, nesting of
 @cindex braces, nesting of

-@cindex inner staff group
-@cindex inner choir staff group

 
 

-Two additional staff-group contexts are available that can be
-nested within a @code{StaffGroup} or @code{ChoirStaff} context:
-@code{InnerStaffGroup} and @code{InnerChoirStaff}.  These contexts
-create a bracket next to the original bracket of their parent
-staff group.
-
-An @code{InnerStaffGroup} is treated similarly to a
-@code{StaffGroup}; bar lines are connected between each stave
-within the context:
+Staff-group contexts can be nested to arbitrary depths.  In this
+case, each child context creates a new bracket adjacent to the
+bracket of its parent group.

 
 @lilypond[verbatim,quote,relative=2]
 \new StaffGroup <<
   \new Staff { c2 c | c2 c }
 
 @lilypond[verbatim,quote,relative=2]
 \new StaffGroup <<
   \new Staff { c2 c | c2 c }

-  \new InnerStaffGroup <<
+  \new StaffGroup <<

     \new Staff { g2 g | g2 g }
     \new Staff { g2 g | g2 g }

-    \new Staff { e2 e | e2 e }
-  >>
->>
-@end lilypond
-
-Bar lines are @emph{not} connected between staves of an
-@code{InnerChoirStaff}, just like a @code{ChoirStaff}:
-
-@lilypond[verbatim,quote,relative=2]
-\new ChoirStaff <<
-  \new Staff { c2 c | c2 c }
-  \new InnerChoirStaff <<
-    \new Staff { g2 g | g2 g }
-    \new Staff { e2 e | e2 e }
+    \new StaffGroup \with {
+      systemStartDelimiter = #'SystemStartSquare
+    }
+    <<
+      \new Staff { e2 e | e2 e }
+      \new Staff { c2 c | c2 c }
+    >>

   >>
   >>

-  \new Staff { c1 | c1 }

 >>
 @end lilypond
 
 >>
 @end lilypond
 


@@ -323,7 +303,6 @@ New nested staff group contexts can be defined.  For details, see
 
 
 @seealso
 
 
 @seealso

-

 Notation Reference:
 @ref{Grouping staves},
 @ref{Instrument names},
 Notation Reference:
 @ref{Grouping staves},
 @ref{Instrument names},


@@ -333,9 +312,7 @@ Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
 @rlsr{Staff notation}.
 
 Internals Reference:

-@rinternals{InnerStaffGroup},

 @rinternals{StaffGroup},
 @rinternals{StaffGroup},

-@rinternals{InnerChoirStaff},

 @rinternals{ChoirStaff},
 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},
 @rinternals{ChoirStaff},
 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},


@@ -393,22 +370,6 @@ staff.  For an explanation, refer to the snippet section in
 { d4 d d d }
 @end lilypond
 
 { d4 d d d }
 @end lilypond
 

-The vertical position of staff lines and the number of staff lines
-can be defined at the same time.  As the following example shows,
-note positions are not influenced by the staff line positions.
-
-@warning{The @code{'line-positions} property overrides the
-@code{'line-count} property.  The number of staff lines is
-implicitly defined by the number of elements in the list of values
-for @code{'line-positions}.}
-
-@lilypond[verbatim,quote,relative=1]
-\new Staff \with {
-  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
-}
-{ a4 e' f b | d1 }
-@end lilypond
-

 Staff line thickness can be modified.  The thickness of ledger
 lines and stems are also affected, since they depend on staff line
 thickness.
 Staff line thickness can be modified.  The thickness of ledger
 lines and stems are also affected, since they depend on staff line
 thickness.


@@ -421,7 +382,9 @@ thickness.
 @end lilypond
 
 Ledger line thickness can be set independently of staff line
 @end lilypond
 
 Ledger line thickness can be set independently of staff line

-thickness.
+thickness.  In the example the two numbers are factors multiplying
+the staff line thickness and the staff line spacing.  The two
+contributions are added to give the ledger line thickness.

 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {


@@ -440,19 +403,8 @@ affects the spacing of ledger lines as well.
 { a4 b c d }
 @end lilypond
 
 { a4 b c d }
 @end lilypond
 

-The width of a staff can be modified.  The unit is one staff
-space.  The spacing of objects inside the staff is not affected by
-this setting.
-
-@lilypond[verbatim,quote,relative=1]
-\new Staff \with {
-  \override StaffSymbol #'width = #23
-}
-{ a4 e' f b | d1 }
-@end lilypond
-

 Further details about the properties of @code{StaffSymbol} can be
 Further details about the properties of @code{StaffSymbol} can be

-found here: @rinternals{staff-symbol-interface}.
+found in @rinternals{staff-symbol-interface}.

 
 @funindex \startStaff
 @funindex \stopStaff
 
 @funindex \startStaff
 @funindex \stopStaff


@@ -488,9 +440,9 @@ e4 d c2
 
 
 @predefined
 
 
 @predefined

-

 @code{\startStaff},
 @code{\stopStaff}.
 @code{\startStaff},
 @code{\stopStaff}.

+@endpredefined

 
 
 @snippets
 
 
 @snippets


@@ -500,7 +452,6 @@ e4 d c2
 
 
 @seealso
 
 
 @seealso

-

 Music Glossary:
 @rglos{line},
 @rglos{ledger line},
 Music Glossary:
 @rglos{line},
 @rglos{ledger line},


@@ -548,7 +499,7 @@ staff in the appropriate location:
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-However, the above example is usually not the desired result.  To
+However, the above example is not what is usually desired.  To

 create ossia staves that are above the original staff, have no
 time signature or clef, and have a smaller font size, tweaks must
 be used.  The Learning Manual describes a specific technique to
 create ossia staves that are above the original staff, have no
 time signature or clef, and have a smaller font size, tweaks must
 be used.  The Learning Manual describes a specific technique to


@@ -591,7 +542,7 @@ example.
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"

-    \remove "Clef_engraver"
+    \override Clef #'transparent = ##t

     fontSize = #-3
     \override StaffSymbol #'staff-space = #(magstep -3)
     \override StaffSymbol #'thickness = #(magstep -3)
     fontSize = #-3
     \override StaffSymbol #'staff-space = #(magstep -3)
     \override StaffSymbol #'thickness = #(magstep -3)


@@ -631,7 +582,7 @@ more information about @code{\RemoveEmptyStaffContext}, see
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"

-    \remove "Clef_engraver"
+    \override Clef #'transparent = ##t

     fontSize = #-3
     \override StaffSymbol #'staff-space = #(magstep -3)
     \override StaffSymbol #'thickness = #(magstep -3)
     fontSize = #-3
     \override StaffSymbol #'staff-space = #(magstep -3)
     \override StaffSymbol #'thickness = #(magstep -3)


@@ -667,7 +618,6 @@ more information about @code{\RemoveEmptyStaffContext}, see
 
 
 @seealso
 
 
 @seealso

-

 Music Glossary:
 @rglos{ossia},
 @rglos{staff},
 Music Glossary:
 @rglos{ossia},
 @rglos{staff},


@@ -717,8 +667,9 @@ block.  In orchestral scores, this style is known as @q{Frenched
 Score}.  By default, this command hides and removes all empty
 staves in a score except for those in the first system.
 
 Score}.  By default, this command hides and removes all empty
 staves in a score except for those in the first system.
 

-@warning{An empty staff may only include multi-measure rests,
-skips, spacer rests, or a combination of these elements.}
+@warning{A staff is considered empty when it contains only
+multi-measure rests, skips, spacer rests, or a combination of these
+elements.}

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


@@ -759,10 +710,10 @@ hide empty staves in ancient music contexts.  Similarly,
 
 
 @predefined
 
 
 @predefined

-

 @code{\RemoveEmptyStaffContext},
 @code{\AncientRemoveEmptyStaffContext},
 @code{\RemoveEmptyRhythmicStaffContext}.
 @code{\RemoveEmptyStaffContext},
 @code{\AncientRemoveEmptyStaffContext},
 @code{\RemoveEmptyRhythmicStaffContext}.

+@endpredefined

 
 
 @snippets
 
 
 @snippets


@@ -772,7 +723,6 @@ hide empty staves in ancient music contexts.  Similarly,
 
 
 @seealso
 
 
 @seealso

-

 Music Glossary:
 @rglos{Frenched staff}.
 
 Music Glossary:
 @rglos{Frenched staff}.
 


@@ -877,31 +827,16 @@ d4 g e c
 
 @c perhaps also an example of how to move it horizontally?
 
 
 @c perhaps also an example of how to move it horizontally?
 

-@c TODO add snippet to LSR -pm
-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
-
-@c TODO add snippet to LSR -pm
-To print other metronome markings, use these markup commands
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-tempo-without-a-metronome-mark.ly}

 
 

-@lilypond[verbatim,quote,relative=1]
-c4^\markup {
-  (
-  \smaller \general-align #Y #DOWN \note #"16." #1
-  =
-  \smaller \general-align #Y #DOWN \note #"8" #1
-  ) }
-@end lilypond
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-metronome-marks-in-markup-mode.ly}

 
 For more details, see @ref{Formatting text}.
 
 
 @seealso
 
 For more details, see @ref{Formatting text}.
 
 
 @seealso

-

 Music Glossary:
 @rglos{metronome},
 @rglos{metronomic indication},
 Music Glossary:
 @rglos{metronome},
 @rglos{metronomic indication},


@@ -955,7 +890,7 @@ instrument names and short instrument names are centered by
 default.  To center multi-line instrument names,
 @code{\center-column} must be used:
 
 default.  To center multi-line instrument names,
 @code{\center-column} must be used:
 

-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote,indent=1.5\cm,relative=2]

 <<
   \new Staff {
     \set Staff.instrumentName = "Flute"
 <<
   \new Staff {
     \set Staff.instrumentName = "Flute"


@@ -963,7 +898,7 @@ default.  To center multi-line instrument names,
   }
   \new Staff {
     \set Staff.instrumentName = \markup \center-column {
   }
   \new Staff {
     \set Staff.instrumentName = \markup \center-column {

-      Clarinetti
+      Clarinet

       \line { "in B" \smaller \flat }
     }
     c4 b c2
       \line { "in B" \smaller \flat }
     }
     c4 b c2


@@ -977,17 +912,17 @@ default.  To center multi-line instrument names,
 However, if the instrument names are longer, the instrument names
 in a staff group may not be centered unless the @code{indent} and
 @code{short-indent} settings are increased.  For details about
 However, if the instrument names are longer, the instrument names
 in a staff group may not be centered unless the @code{indent} and
 @code{short-indent} settings are increased.  For details about

-these settings, see @ref{Page formatting}.
+these settings, see @ref{Horizontal dimensions}.

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

-  indent = 2.5\cm
+  indent = 3.0\cm

   short-indent = 1.5\cm
 }
 
 \relative c'' <<
   \new Staff {
   short-indent = 1.5\cm
 }
 
 \relative c'' <<
   \new Staff {

-    \set Staff.instrumentName = "Flute"
+    \set Staff.instrumentName = "Alto Flute in G"

     \set Staff.shortInstrumentName = "Fl."
     f2 g4 f \break
     g4 f g2
     \set Staff.shortInstrumentName = "Fl."
     f2 g4 f \break
     g4 f g2


@@ -1029,10 +964,10 @@ If an instrument @emph{switch} is needed,
 @code{\instrumentSwitch} to create a detailed list of the
 necessary changes for the switch.  The
 @code{\addInstrumentDefinition} command has two arguments: an
 @code{\instrumentSwitch} to create a detailed list of the
 necessary changes for the switch.  The
 @code{\addInstrumentDefinition} command has two arguments: an

-identifying string, and an alist of context properties and values
-to be used for the instrument.  It must be placed in the toplevel
-scope.  @code{\instrumentSwitch} is used in the music expression
-to declare the instrument switch:
+identifying string, and an association list of context properties
+and values to be used for the instrument.  It must be placed in
+the toplevel scope.  @code{\instrumentSwitch} is used in the music
+expression to declare the instrument switch:

 
 @lilypond[verbatim,quote,ragged-right]
 \addInstrumentDefinition #"contrabassoon"
 
 @lilypond[verbatim,quote,ragged-right]
 \addInstrumentDefinition #"contrabassoon"


@@ -1060,9 +995,8 @@ to declare the instrument switch:
 
 
 @seealso
 
 
 @seealso

-

 Notation Reference:
 Notation Reference:

-@ref{Page formatting},
+@ref{Horizontal dimensions},

 @ref{Modifying context plug-ins}.
 
 Snippets:
 @ref{Modifying context plug-ins}.
 
 Snippets:


@@ -1082,11 +1016,15 @@ Internals Reference:
 @cindex fragments
 @cindex cue notes
 
 @cindex fragments
 @cindex cue notes
 

-Fragments of other parts can be inserted directly into a music
-expression; this is called @emph{quotation}.  Before a part can be
-quoted, the @code{\addQuote} command must be used to initialize
-the quoted fragment.  This command must be used in the toplevel
-scope.  The first argument is an identifying string, and the
+It is very common for one voice to double some of the music from
+another voice.  For example, the first and second violins may play the
+same notes during a passage of music.  In LilyPond this is accomplished
+by letting one voice @emph{quote} the other voice without having to
+re-enter it.
+
+Before a part can be quoted, the @code{\addQuote} command must be used
+to initialize the quoted fragment.  This command must be used in the
+toplevel scope.  The first argument is an identifying string, and the

 second is a music expression:
 
 @example
 second is a music expression:
 
 @example


@@ -1096,10 +1034,12 @@ flute = \relative c'' @{
 \addQuote "flute" @{ \flute @}
 @end example
 
 \addQuote "flute" @{ \flute @}
 @end example
 

-The @code{\quoteDuring} command is used to indicate when the
-quotation should take place.  The corresponding measures from the
-quotation are inserted into the music expression.  The syntax is
-similar to @code{\addQuote}:
+The @code{\quoteDuring} command is used to indicate the point where the
+quotation begins.  It is followed by two arguments: the name of the
+quoted voice, as defined with @code{\addQuote}, and a music expression
+that indicates the duration of the quote, usually spacer rests or
+multi-measure rests.  The corresponding music from the quoted voice is
+inserted into the music expression:

 
 @lilypond[verbatim,quote]
 flute = \relative c'' {
 
 @lilypond[verbatim,quote]
 flute = \relative c'' {


@@ -1148,35 +1088,23 @@ It is possible to tag quotations with unique names in order to
 process them in different ways.  For details about this procedure,
 see @ref{Using tags}.
 
 process them in different ways.  For details about this procedure,
 see @ref{Using tags}.
 

-@c add to snippets, possibly.  It might already be there.  -pm
-@c
-@c The type of events that are present in the quoted music can be
-@c trimmed with the @code{quotedEventTypes} property.  The default
-@c value is @code{(note-event rest-event)}, which means that only
-@c notes and rests of the quoted voice end up in the
-@c @code{\quoteDuring}.  Setting
-@c
-@c @example
-@c \set Staff.quotedEventTypes =
-@c        #'(note-event articulation-event dynamic-event)
-@c @end example
-@c
-@c @noindent
-@c will quote notes (but no rests), together with scripts and
-@c dynamics.
-

 
 @snippets
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {quoting-another-voice-with-transposition.ly}
 
 
 @snippets
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {quoting-another-voice-with-transposition.ly}
 

+@cindex note-event
+@cindex articulation-event
+@cindex dynamic-event
+@cindex rest-event
+@funindex quotedEventTypes
+

 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {quoting-another-voice.ly}
 
 
 @seealso
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {quoting-another-voice.ly}
 
 
 @seealso

-

 Notation Reference:
 @ref{Instrument transpositions},
 @ref{Using tags}.
 Notation Reference:
 @ref{Instrument transpositions},
 @ref{Using tags}.


@@ -1221,7 +1149,7 @@ The previous section explains how to create quotations.  The
 notes into a part.  The syntax is as follows:
 
 @example
 notes into a part.  The syntax is as follows:
 
 @example

-  \cueDuring #@var{partname} #@var{voice} @var{music}
+\cueDuring #@var{partname} #@var{voice} @var{music}

 @end example
 
 This command copies the corresponding measures from @var{partname}
 @end example
 
 This command copies the corresponding measures from @var{partname}


@@ -1257,7 +1185,7 @@ The name of the cued instrument can be printed by setting the
 oboe = \relative c''' {
   g4 r8 e16 f e4 d
 }
 oboe = \relative c''' {
   g4 r8 e16 f e4 d
 }

-\addQuote oboe { \oboe }
+\addQuote "oboe" { \oboe }

 
 \new Staff \relative c'' <<
   \new CueVoice \with {
 
 \new Staff \relative c'' <<
   \new CueVoice \with {


@@ -1285,7 +1213,7 @@ from a part but may be restored at a later time.
 flute = \relative c''' {
   r2 cis2 r2 dis2
 }
 flute = \relative c''' {
   r2 cis2 r2 dis2
 }

-\addQuote flute { \flute }
+\addQuote "flute" { \flute }

 
 \new Voice \relative c'' {
   \killCues {
 
 \new Voice \relative c'' {
   \killCues {


@@ -1330,7 +1258,6 @@ see @ref{Using tags}.
 
 
 @seealso
 
 
 @seealso

-

 Notation Reference:
 @ref{Instrument transpositions},
 @ref{Instrument names},
 Notation Reference:
 @ref{Instrument transpositions},
 @ref{Instrument names},