Adds documentation for optional octavation clef syntax

This documents the new feature made available with commit
74b4c9351b01381f0dc1d6d4688dcd845fc59720

(see Issue 2933)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index f6702bfdde23ba3542e10a6fdeafe36570d5c436..f0d11f45e862e1482715b49798eb459c0485be4f 100644 (file)
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -61,6 +61,15 @@ which scares away people.
 
 @end ignore
 
+@item
+The @code{\clef} command supports optional octavation:
+@lilypond[verbatim,quote,relative=1]
+\clef "treble_(8)"
+c2 c
+\clef "bass^[15]"
+c2 c
+@end lilypond
+
 @item
 The LilyPond syntax of dot-separated words @code{Voice.Accidental}
 has been made interchangeable with @code{#'(Voice Accidental)}, a

diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index bdfc34a7dfc442a1d2b88c4fa1477f985750eb92..58982672577932fbec7f3bc20e1022885cf73d87 100644 (file)
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -841,7 +841,7 @@ music = \relative c' { c d e f }
 @end lilypond
 
 @warning{Motifs to be inverted should be expressed in absolute form
-or be first converted to absolute form by enclosing them in a 
+or be first converted to absolute form by enclosing them in a
 @code{\relative} block.}
 
 @seealso
@@ -1127,6 +1127,8 @@ c2 c
 @cindex transposing clef
 @cindex clef, transposing
 @cindex octave transposition
+@cindex optional octave transposition
+@cindex octave transposition, optional
 @cindex choral tenor clef
 @cindex tenor clef, choral
 
@@ -1151,6 +1153,19 @@ c2 c
 c2 c
 @end lilypond
 
+Optional octavation can be obtained by enclosing the numeric
+argument in parentheses or brackets:
+
+@lilypond[verbatim,quote,relative=1]
+\clef "treble_(8)"
+c2 c
+\clef "bass^[15]"
+c2 c
+@end lilypond
+
+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