X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fpitches.itely;h=4c41302c4f273657cdba7d58c4e7d03494c6ee6d;hb=fb6f94387f2431e59e84f5b79e523c56dfe59f7f;hp=20e56de28fed1e31e5b973031782fb53dcc4bb04;hpb=98c77cfcf941179ec011ca0e0ada02e35ccf4d0c;p=lilypond.git

diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index 20e56de28f..4c41302c4f 100644
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.15.20"
+@c \version "2.17.18"
 
 
 @node Pitches
@@ -87,6 +87,18 @@ octave.
 }
 @end lilypond
 
+@funindex absolute
+@funindex \absolute
+Music can be marked explicitly as being in absolute octave
+notation by preceding it with @code{\absolute}:
+
+@example
+\absolute @var{musicexpr}
+@end example
+
+will be interpreted in absolute octave entry mode regardless of
+the context it appears in.
+
 @seealso
 Music Glossary:
 @rglos{Pitch names}.
@@ -107,13 +119,13 @@ Snippets:
 @funindex relative
 @funindex \relative
 
-When octaves are specified in absolute mode it is easy to
-accidentally put a pitch in the wrong octave.  Relative octave
-mode reduces these errors since most of the time it is not
-necessary to indicate any octaves at all.  Furthermore, in
-absolute mode a single mistake may be difficult to spot, while in
-relative mode a single error puts the rest of the piece off by one
-octave.
+Absolute octave entry requires specifying the octave for every
+single note.  Relative octave entry, in contrast, specifies each
+octave in relation to the last note: changing one note's octave
+will affect all of the following notes.
+
+Relative note mode has to be entered explicitly using the
+@code{\relative} command:
 
 @example
 \relative @var{startpitch} @var{musicexpr}
@@ -143,8 +155,27 @@ octaves.
 @item
 The pitch of the first note is relative to
 @code{@var{startpitch}}.  @code{@var{startpitch}} is specified in
-absolute octave mode, and it is recommended that it be a octave of
-@code{c}.
+absolute octave mode.  Which choices are meaningful?
+
+@table @asis
+@item an octave of @code{c}
+Identifying middle C with @code{c'} is quite basic, so finding
+octaves of @code{c} tends to be straightforward.  If your music
+starts with @code{gis} above @code{c'''}, you'd write something
+like @code{\relative c''' @{ gis' @dots{} @}}
+
+@item an octave of the first note inside
+Writing @code{\relative gis''' @{ gis @dots{} @}} makes it easy to
+determine the absolute pitch of the first note inside.
+
+@item no explicit starting pitch
+This (namely writing @code{\relative @{ gis''' @dots{} @}}) can be
+viewed as a compact version of the previous option: the first note
+inside is written in absolute pitch itself.  This happens to be
+equivalent to choosing @code{f} as the reference pitch.
+@end table
+
+The documentation will usually employ the first option.
 @end itemize
 
 Here is the relative mode shown in action:
@@ -283,12 +314,6 @@ Internals Reference:
 @funindex \relative
 @funindex relative
 
-@c DEPRECATED
-If no @code{@var{startpitch}} is specified for @code{\relative},
-then@tie{}@code{c'} is assumed.  However, this is a deprecated
-option and may disappear in future versions, so its use is
-discouraged.
-
 
 @node Accidentals
 @unnumberedsubsubsec Accidentals
@@ -379,7 +404,7 @@ cis cis cis! cis? c c c! c?
 Accidentals on tied notes are only printed at the beginning of a
 new system:
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote,relative=2,ragged-right]
 cis1~ cis~
 \break
 cis
@@ -464,9 +489,9 @@ The available languages and the note names they define are:
   @tab c d e f g a b h
 @item @code{english}
   @tab c d e f g a bf b
-@item @code{espanol}
+@item @code{espanol} or @code{español}
   @tab do re mi fa sol la sib si
-@item @code{italiano}
+@item @code{italiano} or @code{français}
   @tab do re mi fa sol la sib si
 @item @code{norsk}
   @tab c d e f g a b h
@@ -497,9 +522,9 @@ also vary depending on the language:
 @item @code{english}
   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
     @tab -ff/-flatflat
-@item @code{espanol}
+@item @code{espanol} or @code{español}
   @tab -s @tab -b @tab -ss/-x @tab -bb
-@item @code{italiano}
+@item @code{italiano} or @code{français}
   @tab -d @tab -b @tab -dd @tab -bb
 @item @code{norsk}
   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
@@ -551,9 +576,9 @@ appear in this table do not provide special note names yet.
   @tab -ih @tab -eh @tab -isih @tab -eseh
 @item @code{english}
   @tab -qs @tab -qf @tab -tqs @tab -tqf
-@item @code{espanol}
+@item @code{espanol} or @code{español}
   @tab -cs @tab -cb @tab -tcs @tab -tcb
-@item @code{italiano}
+@item @code{italiano} or @code{français}
   @tab -sd @tab -sb @tab -dsd @tab -bsb
 @item @code{portugues}
   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
@@ -820,15 +845,16 @@ rather than e-triple-flat).
 @cindex operation, inversion
 @funindex \inversion
 
-A music expression can be inverted with:
+A music expression can be inverted and transposed in a single
+operation with:
 
 @example
-\inversion @var{from-pitch} @var{to-pitch} @var{musicexpr}
+\inversion @var{around-pitch} @var{to-pitch} @var{musicexpr}
 @end example
 
-The @code{@var{musicexpr}} is inverted interval-by-interval,
-and then transposed so that @code{@var{from-pitch}} is mapped
-to @code{@var{to-pitch}}.
+The @code{@var{musicexpr}} is inverted interval-by-interval around
+@code{@var{around-pitch}}, and then transposed so that
+@code{@var{around-pitch}} is mapped to @code{@var{to-pitch}}.
 
 @lilypond[verbatim,quote]
 music = \relative c' { c d e f }
@@ -839,6 +865,10 @@ 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
+@code{\relative} block.}
+
 @seealso
 Notation Reference:
 @ref{Modal transformations},
@@ -895,7 +925,7 @@ It may also be reversed to produce its @notation{retrograde}, see
 @warning{Any note that does not lie within the given scale will be
 left untransformed.}
 
-@subsubheading Modal transposition
+@subsubsubheading Modal transposition
 
 @cindex modal transposition
 @cindex transposition, modal
@@ -952,7 +982,7 @@ motif = \relative c' { c8 d e f g a b c }
 }
 @end lilypond
 
-@subsubheading Modal inversion
+@subsubsubheading Modal inversion
 
 @cindex modal inversion
 @cindex inversion, modal
@@ -1122,6 +1152,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
 
@@ -1146,6 +1178,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
@@ -1171,9 +1216,24 @@ Snippets:
 Internals Reference:
 @rinternals{Clef_engraver},
 @rinternals{Clef},
-@rinternals{OctavateEight},
+@rinternals{ClefModifier},
 @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.
+
+@lilypond[fragment,quote,relative=1]
+\new Staff \with {
+  \override ClefModifier.color = #red
+  \override Clef.color = #blue
+}
+
+\clef "treble_8" c4
+@end lilypond
+
 
 @node Key signature
 @unnumberedsubsubsec Key signature
@@ -1245,6 +1305,37 @@ f
 fis
 @end lilypond
 
+Additional modes can be defined, by listing the alterations
+for each scale step when the mode starts on C.
+
+@lilypond[verbatim,quote]
+freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
+    (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))
+
+\relative c' {
+  \key c \freygish c4 des e f
+  \bar "||" \key d \freygish d es fis g
+}
+@end lilypond
+
+Accidentals in the key signature may be printed in octaves other
+than their traditional positions, or in multiple octaves, by
+using the @code{flat-positions} and @code{sharp-positions}
+properties of @code{KeySignature}.  Entries in these properties
+specify the range of staff-positions where accidentals will be
+printed.  If a single position is specified in an entry, the
+accidentals are placed within the octave ending at that staff
+position.
+
+@lilypond[verbatim, quote,relative=0]
+\override Staff.KeySignature.flat-positions = #'((-5 . 5))
+\override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
+\clef bass \key es \major es g bes d
+\clef treble \bar "||" \key es \major es g bes d
+
+\override Staff.KeySignature.sharp-positions = #'(2)
+\bar "||" \key b \major b fis b2
+@end lilypond
 
 @snippets
 
@@ -1271,7 +1362,6 @@ Internals Reference:
 @rinternals{Key_performer},
 @rinternals{KeyCancellation},
 @rinternals{KeySignature},
-@rinternals{key-cancellation-interface},
 @rinternals{key-signature-interface}.
 
 
@@ -1310,6 +1400,9 @@ a2 b
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {ottava-text.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{adding-an-ottava-marking-to-a-single-voice.ly}
+
 @seealso
 Music Glossary:
 @rglos{octavation}.
@@ -1388,21 +1481,34 @@ playing in unison.
 @end lilypond
 
 The @code{\transposition} may be changed during a piece.  For
-example, a clarinetist may switch from an A clarinet to a B-flat
-clarinet.
-
-@lilypond[verbatim,quote,relative=2]
-\set Staff.instrumentName = #"Cl (A)"
-\key a \major
-\transposition a
-c d e f
-\textLengthOn
-s1*0^\markup { Switch to B\flat clarinet }
-R1
+example, a clarinetist may be required to switch from an A clarinet
+to a B-flat clarinet.
 
-\key bes \major
-\transposition bes
-c2 g
+@lilypond[verbatim,quote]
+flute = \relative c'' {
+  \key f \major
+  \cueDuring #"clarinet" #DOWN {
+    R1 _\markup\tiny "clarinet"
+    c4 f e d
+    R1 _\markup\tiny "clarinet"
+  }
+}
+clarinet = \relative c'' {
+  \key aes \major
+  \transposition a
+  aes4 bes c des
+  R1^\markup { muta in B\flat }
+  \key g \major
+  \transposition bes
+  d2 g,
+}
+\addQuote "clarinet" \clarinet
+<<
+  \new Staff \with { instrumentName = #"Flute" }
+    \flute
+  \new Staff \with { instrumentName = #"Cl (A)" }
+    \clarinet
+>>
 @end lilypond
 
 @seealso
@@ -1438,7 +1544,7 @@ accidental style to use.  This function is called as follows:
 
 @example
 \new Staff <<
-  \accidentalStyle "voice"
+  \accidentalStyle voice
   @{ @dots{} @}
 >>
 @end example
@@ -1451,7 +1557,7 @@ scope the style should be changed.  For example, to use the same
 style in all staves of the current @code{StaffGroup}, use:
 
 @example
-\accidentalStyle #'StaffGroup "voice"
+\accidentalStyle StaffGroup.voice
 @end example
 
 The following accidental styles are supported.  To demonstrate
@@ -1494,11 +1600,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "default"
+      \accidentalStyle default
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "default"
+      \accidentalStyle default
       \musicB
     }
   >>
@@ -1514,7 +1620,7 @@ both staves.
   <<
     \context Staff = "up" @{
       %%% change the next line as desired:
-      \accidentalStyle #'Score "default"
+      \accidentalStyle Score.default
       \musicA
     @}
     \context Staff = "down" @{
@@ -1577,11 +1683,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "default"
+      \accidentalStyle default
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "default"
+      \accidentalStyle default
       \musicB
     }
   >>
@@ -1650,11 +1756,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "voice"
+      \accidentalStyle voice
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "voice"
+      \accidentalStyle voice
       \musicB
     }
   >>
@@ -1716,11 +1822,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "modern"
+      \accidentalStyle modern
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "modern"
+      \accidentalStyle modern
       \musicB
     }
   >>
@@ -1780,11 +1886,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "modern-cautionary"
+      \accidentalStyle modern-cautionary
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "modern-cautionary"
+      \accidentalStyle modern-cautionary
       \musicB
     }
   >>
@@ -1847,11 +1953,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "modern-voice"
+      \accidentalStyle modern-voice
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "modern-voice"
+      \accidentalStyle modern-voice
       \musicB
     }
   >>
@@ -1908,11 +2014,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "modern-voice-cautionary"
+      \accidentalStyle modern-voice-cautionary
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "modern-voice-cautionary"
+      \accidentalStyle modern-voice-cautionary
       \musicB
     }
   >>
@@ -1973,7 +2079,7 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "piano"
+      \accidentalStyle piano
       \musicA
     }
     \context Staff = "down" {
@@ -2033,7 +2139,7 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "piano-cautionary"
+      \accidentalStyle piano-cautionary
       \musicA
     }
     \context Staff = "down" {
@@ -2092,11 +2198,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "neo-modern"
+      \accidentalStyle neo-modern
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "neo-modern"
+      \accidentalStyle neo-modern
       \musicB
     }
   >>
@@ -2149,11 +2255,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "neo-modern-cautionary"
+      \accidentalStyle neo-modern-cautionary
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "neo-modern-cautionary"
+      \accidentalStyle neo-modern-cautionary
       \musicB
     }
   >>
@@ -2209,11 +2315,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "neo-modern-voice"
+      \accidentalStyle neo-modern-voice
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "neo-modern-voice"
+      \accidentalStyle neo-modern-voice
       \musicB
     }
   >>
@@ -2266,11 +2372,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "neo-modern-voice-cautionary"
+      \accidentalStyle neo-modern-voice-cautionary
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "neo-modern-voice-cautionary"
+      \accidentalStyle neo-modern-voice-cautionary
       \musicB
     }
   >>
@@ -2326,11 +2432,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "dodecaphonic"
+      \accidentalStyle dodecaphonic
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "dodecaphonic"
+      \accidentalStyle dodecaphonic
       \musicB
     }
   >>
@@ -2351,7 +2457,7 @@ Accidentals are printed like with @code{modern}, but cautionary
 accidentals are added for all sharp or flat tones specified by the
 key signature, except if the note is immediately repeated.
 
-@lilypond[quote]
+@lilypond[quote,staffsize=18]
 musicA = {
   <<
     \relative c' {
@@ -2388,12 +2494,12 @@ musicB = {
   <<
     \context Staff = "up" {
       \key fis \minor
-      \accidentalStyle "teaching"
+      \accidentalStyle teaching
       \musicA
     }
     \context Staff = "down" {
       \key fis \minor
-      \accidentalStyle "teaching"
+      \accidentalStyle teaching
       \musicB
     }
   >>
@@ -2448,11 +2554,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "no-reset"
+      \accidentalStyle no-reset
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "no-reset"
+      \accidentalStyle no-reset
       \musicB
     }
   >>
@@ -2507,11 +2613,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      \accidentalStyle "forget"
+      \accidentalStyle forget
       \musicA
     }
     \context Staff = "down" {
-      \accidentalStyle "forget"
+      \accidentalStyle forget
       \musicB
     }
   >>
@@ -2554,7 +2660,7 @@ not need a natural sign:
 
 @lilypond[quote]
 {
-  \accidentalStyle "modern"
+  \accidentalStyle modern
   \time 2/4
   \repeat volta 2 {
     c'2
@@ -2571,12 +2677,12 @@ the accidental style to @code{forget}:
 
 @lilypond[verbatim,quote]
 forget = #(define-music-function (parser location music) (ly:music?) #{
-  \accidentalStyle "forget"
-  $music
-  \accidentalStyle "modern"
+  \accidentalStyle forget
+  #music
+  \accidentalStyle modern
 #})
 {
-  \accidentalStyle "modern"
+  \accidentalStyle modern
   \time 2/4
   \repeat volta 2 {
     c'2
@@ -2691,13 +2797,13 @@ The appearance of note heads may be altered:
 
 @lilypond[verbatim,quote,relative=2]
 c4 b
-\override NoteHead #'style = #'cross
+\override NoteHead.style = #'cross
 c4 b
-\revert NoteHead #'style
+\revert NoteHead.style
 a b
-\override NoteHead #'style = #'harmonic
+\override NoteHead.style = #'harmonic
 a b
-\revert NoteHead #'style
+\revert NoteHead.style
 c4 d e f
 @end lilypond
 
@@ -2730,11 +2836,10 @@ As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
 @code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
 be used.  The term @notation{dead note} is commonly used by guitarists.
 
-There is also a shorthand for diamond shapes which can be used
-only inside chords:
+There is also a similar shorthand for diamond shapes:
 
 @lilypond[verbatim,quote,relative=2]
-<c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
+<c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
 @end lilypond
 
 @predefined