Doc: NR Pitches.itely - Clef - updated snippets and text

[lilypond.git] / Documentation / notation / pitches.itely

diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index b5cc66246d5856e4f609528fb5aa964d587bc704..60fb0cc443d1763bedcaefd13ad1aaa08a56cf8a 100644 (file)
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -1104,8 +1104,16 @@ This section discusses how to alter the output of pitches.
 @funindex \clef
 @funindex clef
 
-The clef may be altered.  Middle C is shown in every example.  The
-following clef names can (but do not need to) be enclosed in quotes.
+Without any explicit command, the default clef for LilyPond is the
+treble (or @emph{G}) clef.
+
+@lilypond[verbatim,quote,relative=1,ragged-right]
+c2 c
+@end lilypond
+
+However, the clef can be changed by using the @code{\clef} command and
+an appropriate clef name.  @emph{Middle C} is shown in each of the
+following examples.
 
 @lilypond[verbatim,quote,relative=1]
 \clef treble
@@ -1118,36 +1126,17 @@ c2 c
 c2 c
 @end lilypond
 
-Other clefs include:
+For the full range of possible clef names see @ref{Clef styles}.
 
-@lilypond[verbatim,quote,relative=1]
-\clef french
-c2 c
-\clef soprano
-c2 c
-\clef mezzosoprano
-c2 c
-\clef baritone
-c2 c
-
-\break
+Specialized clefs, such as those used in @emph{Ancient} music, are
+described in @ref{Mensural clefs} and @ref{Gregorian clefs}.  Music that
+requires tablature clefs is discussed in @ref{Default tablatures} and
+@ref{Custom tablatures}.
 
-\clef varbaritone
-c2 c
-\clef subbass
-c2 c
-\clef percussion
-c2 c
-
-\break
-
-\clef G   % synonym for treble
-c2 c
-\clef F   % synonym for bass
-c2 c
-\clef C   % synonym for alto
-c2 c
-@end lilypond
+@cindex Cue clefs
+@cindex Clefs with cue notes
+For mixing clefs when using cue notes, see the @code{\cueClef} and
+@code{\cueDuringWithClef} commands in @ref{Formatting cue notes}.
 
 @cindex transposing clef
 @cindex clef, transposing
@@ -1191,14 +1180,60 @@ c2 c
 The pitches are displayed as if the numeric argument were
 given without parentheses/brackets.
 
-Some special purpose clefs are described in @ref{Mensural clefs},
-@ref{Gregorian clefs}, @ref{Default tablatures}, and @ref{Custom
-tablatures}.  For mixing different clefs when using cue notes within a
-score, see the @code{\cueClef} and @code{\cueDuringWithClef} functions
-in @ref{Formatting cue notes}.
+By default, a clef change taking place at a line break will cause
+the new clef symbol to be printed at the end of the previous line,
+as a @emph{warning} clef, as well as the beginning of the next.
+This @emph{warning} clef can be suppressed.
 
-@snippets
+@lilypond[verbatim,quote,relative=1]
+\clef treble { c2 c } \break
+\clef bass { c2 c } \break
+\clef alto
+  \set Staff.explicitClefVisibility = #end-of-line-invisible
+  { c2 c } \break
+  \unset Staff.explicitClefVisibility
+\clef bass { c2 c } \break
+@end lilypond
+
+By default, a clef that has previously been printed will not be
+re-printed if the same @code{\clef} command is issued again and
+will be ignored.  The the command
+@code{\set Staff.forceClef = ##t} changes this behaviour.
+
+@lilypond[verbatim,quote,relative=1]
+  \clef treble
+  c1
+  \clef treble
+  c1
+  \set Staff.forceClef = ##t
+  c1
+  \clef treble
+  c1
+@end lilypond
 
+When there is a manual clef change, the glyph of the changed clef
+will be smaller than normal.  This behaviour can be overridden.
+
+@lilypond[verbatim,quote,relative=1]
+  \clef "treble"
+  c1
+  \clef "bass"
+  c1
+  \clef "treble"
+  c1
+  \override Staff.Clef.full-size-change = ##t
+  \clef "bass"
+  c1
+  \clef "treble"
+  c1
+  \revert Staff.Clef.full-size-change
+  \clef "bass"
+  c1
+  \clef "treble"
+  c1
+@end lilypond
+
+@snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {tweaking-clef-properties.ly}
 
@@ -1210,6 +1245,9 @@ Notation Reference:
 @ref{Custom tablatures},
 @ref{Formatting cue notes}.
 
+Installed Files:
+@file{scm/parser-clef.scm}.
+
 Snippets:
 @rlsr{Pitches}.
 
@@ -1220,10 +1258,10 @@ Internals Reference:
 @rinternals{clef-interface}.
 
 @knownissues
-Ottavation numbers attached to clefs are treated as separate grobs.  So
-any @code{\override} done to the @var{Clef} will also need to be
-applied, as a separate @code{\override}, to the @var{ClefModifier}
-grob.
+Ottavation numbers attached to clefs are treated as separate
+grobs.  So any @code{\override} done to the @var{Clef} will also
+need to be applied, as a separate @code{\override}, to the
+@var{ClefModifier} grob.
 
 @lilypond[fragment,quote,verbatim,relative=1]
 \new Staff \with {
@@ -1345,6 +1383,7 @@ position.
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {non-traditional-key-signatures.ly}
 
+
 @seealso
 Music Glossary:
 @rglos{church mode},
@@ -1403,6 +1442,9 @@ a2 b
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {adding-an-ottava-marking-to-a-single-voice.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{modifying-the-ottava-spanner-slope.ly}
+
 @seealso
 Music Glossary:
 @rglos{octavation}.
@@ -2452,7 +2494,7 @@ musicB = {
 
 Like with the dodecaphonic accidental style @emph{every} note
 gets an accidental sign by default, but accidentals are
-suppressed for pitches immediately repeated within one voice.
+suppressed for pitches immediately repeated within the same staff.
 
 @lilypond[quote]
 musicA = {