Merge branch 'release/unstable' into HEAD

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

diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index 78a222794d195e9ceae5c812971e5f6b2357a824..491e76f03c870d18f9f7ad664678242880779b88 100644 (file)
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.13.36"
+@c \version "2.15.20"
 
 
 @node Pitches
@@ -255,6 +255,9 @@ that each interval contains.
 }
 @end lilypond
 
+One consequence of these rules is that the first note inside
+@code{@w{\relative f}} music is interpreted just the same as
+if it was written in absolute pitch mode.
 
 @seealso
 Music Glossary:
@@ -389,10 +392,10 @@ cis
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle,ragged-right]
+@lilypondfile[verbatim,quote,texidoc,doctitle,ragged-right]
 {hiding-accidentals-on-tied-notes-at-the-start-of-a-new-system.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {preventing-extra-naturals-from-being-automatically-added.ly}
 
 @seealso
@@ -594,6 +597,8 @@ This section discusses how to modify pitches.
 @menu
 * Octave checks::
 * Transpose::
+* Inversion::
+* Retrograde::
 * Modal transformations::
 @end menu
 
@@ -782,15 +787,17 @@ see @ref{Instrument transpositions}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 
 
 @seealso
 Notation Reference:
-@ref{Relative octave entry},
+@ref{Instrument transpositions},
+@ref{Inversion},
 @ref{Modal transformations},
-@ref{Instrument transpositions}.
+@ref{Relative octave entry},
+@ref{Retrograde}.
 
 Snippets:
 @rlsr{Pitches}.
@@ -809,9 +816,79 @@ Internals Reference:
 @knownissues
 
 The relative conversion will not affect @code{\transpose},
-@code{\chordmode} or @code{\relative} sections in its argument.
-To use relative mode within transposed music, an additional
-@code{\relative} must be placed inside @code{\transpose}.
+@code{\chordmode} or @code{\relative} sections in its argument.  To use
+relative mode within transposed music, an additional @code{\relative}
+must be placed inside @code{\transpose}.
+
+Triple accidentals will not be printed if using @code{\transpose}. An
+@q{enharmonically equivalent} pitch will be used instead (e.g. d-flat
+rather than e-triple-flat).
+
+
+@node Inversion
+@unnumberedsubsubsec Inversion
+
+@cindex inversion
+@cindex operation, inversion
+@funindex \inversion
+
+A music expression can be inverted with:
+
+@example
+\inversion @var{from-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}}.
+
+@lilypond[verbatim,quote]
+music = \relative c' { c d e f }
+\new Staff {
+  \music
+  \inversion d' d' \music
+  \inversion d' ees' \music
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Modal transformations},
+@ref{Retrograde},
+@ref{Transpose}.
+
+
+@node Retrograde
+@unnumberedsubsubsec Retrograde
+
+@cindex retrograde transformation
+@cindex transformation, retrograde
+@cindex operation, retrograde
+@funindex \retrograde
+@funindex retrograde
+
+A music expression can be reversed to produce its retrograde:
+
+@lilypond[verbatim,quote]
+music = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }
+
+\new Staff {
+  \music
+  \retrograde \music
+}
+@end lilypond
+
+@knownissues
+Manual ties inside @code{\retrograde} will be broken and
+generate warnings.  Some ties can be generated automatically
+by enabling @ref{Automatic note splitting}.
+
+@seealso
+Notation Reference:
+@ref{Inversion},
+@ref{Modal transformations},
+@ref{Transpose}.
+
 
 @node Modal transformations
 @unnumberedsubsubsec Modal transformations
@@ -822,9 +899,10 @@ To use relative mode within transposed music, an additional
 
 In a musical composition that is based on a scale, a motif is
 frequently transformed in various ways.  It may be
-@notation{transposed} to start at different places in the scale, it
-may be @notation{inverted} around a pivot point in the scale, and/or
-it may be converted to its @notation{retrograde} (written backwards).
+@notation{transposed} to start at different places in the scale or
+it may be @notation{inverted} around a pivot point in the scale.
+It may also be reversed to produce its @notation{retrograde}, see
+@ref{Retrograde}.
 
 @warning{Any note that does not lie within the given scale will be
 left untransformed.}
@@ -890,7 +968,7 @@ motif = \relative c' { c8 d e f g a b c }
 
 @cindex modal inversion
 @cindex inversion, modal
-@cindex operation, inversion
+@cindex operation, modal inversion
 @funindex \modalInversion
 @funindex modalInversion
 
@@ -934,26 +1012,6 @@ motive = \relative c' { c c g' c, }
 }
 @end lilypond
 
-
-@subsubheading Retrograde transformation
-
-@cindex retrograde transformation
-@cindex transformation, retrograde
-@cindex operation, retrograde
-@funindex \retrograde
-@funindex retrograde
-
-A motif can be reversed to produce its retrograde:
-
-@lilypond[verbatim,quote]
-motif = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }
-
-\new Staff {
-  \motif
-  \retrograde \motif
-}
-@end lilypond
-
 The combined operation of inversion and retrograde produce the
 retrograde-inversion:
 
@@ -969,13 +1027,10 @@ motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
 
 @seealso
 Notation Reference:
+@ref{Inversion},
+@ref{Retrograde},
 @ref{Transpose}.
 
-@knownissues
-Manual ties inside @code{\retrograde} will be broken and
-generate warnings.  Some ties can be generated automatically
-by enabling @ref{Automatic note splitting}.
-
 
 @node Displaying pitches
 @subsection Displaying pitches
@@ -1105,20 +1160,22 @@ c2 c
 
 Some special purpose clefs are described in @ref{Mensural clefs},
 @ref{Gregorian clefs}, @ref{Default tablatures}, and @ref{Custom
-tablatures}.
+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}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {tweaking-clef-properties.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Mensural clefs},
 @ref{Gregorian clefs},
 @ref{Default tablatures},
-@ref{Custom tablatures}.
+@ref{Custom tablatures},
+@ref{Formatting cue notes}.
 
 Snippets:
 @rlsr{Pitches}.
@@ -1203,10 +1260,10 @@ fis
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {non-traditional-key-signatures.ly}
 
 
@@ -1263,7 +1320,7 @@ a2 b
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {ottava-text.ly}
 
 
@@ -1386,7 +1443,7 @@ Snippets:
 @cindex automatic accidentals
 @cindex default accidental style
 
-@funindex set-accidental-style
+@funindex \accidentalStyle
 @funindex voice
 @funindex default
 
@@ -1396,7 +1453,7 @@ accidental style to use.  This function is called as follows:
 
 @example
 \new Staff <<
-  #(set-accidental-style 'voice)
+  \accidentalStyle "voice"
   @{ @dots{} @}
 >>
 @end example
@@ -1409,7 +1466,7 @@ scope the style should be changed.  For example, to use the same
 style in all staves of the current @code{StaffGroup}, use:
 
 @example
-#(set-accidental-style 'voice 'StaffGroup)
+\accidentalStyle #'StaffGroup "voice"
 @end example
 
 The following accidental styles are supported.  To demonstrate
@@ -1420,7 +1477,7 @@ each style, we use the following example:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1452,11 +1509,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'default)
+      \accidentalStyle "default"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'default)
+      \accidentalStyle "default"
       \musicB
     }
   >>
@@ -1472,7 +1529,7 @@ both staves.
   <<
     \context Staff = "up" @{
       %%% change the next line as desired:
-      #(set-accidental-style 'default 'Score)
+      \accidentalStyle #'Score "default"
       \musicA
     @}
     \context Staff = "down" @{
@@ -1503,7 +1560,7 @@ last@tie{}@code{c}:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1535,11 +1592,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'default)
+      \accidentalStyle "default"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'default)
+      \accidentalStyle "default"
       \musicB
     }
   >>
@@ -1576,7 +1633,7 @@ individual musicians.  If the staff is to be used by one musician
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1608,11 +1665,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'voice)
+      \accidentalStyle "voice"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'voice)
+      \accidentalStyle "voice"
       \musicB
     }
   >>
@@ -1627,8 +1684,11 @@ musicB = {
 @funindex modern
 
 This rule corresponds to the common practice in the twentieth
-century.  It prints the same accidentals as @code{default}, with
-two exceptions that serve to avoid ambiguity: after temporary
+century.  It omits some extra natural signs, which were
+traditionally prefixed to a sharp following a double sharp,
+or a flat following a double flat.  The @code{modern} rule
+prints the same accidentals as @code{default}, with
+two additions that serve to avoid ambiguity: after temporary
 accidentals, cancellation marks are printed also in the following
 measure (for notes in the same octave) and, in the same measure,
 for notes in other octaves.  Hence the naturals before
@@ -1639,7 +1699,7 @@ the upper staff:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1671,11 +1731,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'modern)
+      \accidentalStyle "modern"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'modern)
+      \accidentalStyle "modern"
       \musicB
     }
   >>
@@ -1703,7 +1763,7 @@ defining the @code{cautionary-style} property of
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1735,11 +1795,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'modern-cautionary)
+      \accidentalStyle "modern-cautionary"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'modern-cautionary)
+      \accidentalStyle "modern-cautionary"
       \musicB
     }
   >>
@@ -1770,7 +1830,7 @@ accidental in a different voice in the previous measure:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1802,11 +1862,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'modern-voice)
+      \accidentalStyle "modern-voice"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'modern-voice)
+      \accidentalStyle "modern-voice"
       \musicB
     }
   >>
@@ -1831,7 +1891,7 @@ typeset as cautionaries.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1863,11 +1923,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'modern-voice-cautionary)
+      \accidentalStyle "modern-voice-cautionary"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'modern-voice-cautionary)
+      \accidentalStyle "modern-voice-cautionary"
       \musicB
     }
   >>
@@ -1896,7 +1956,7 @@ This accidental style applies to the current @code{GrandStaff} or
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1928,7 +1988,7 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'piano)
+      \accidentalStyle "piano"
       \musicA
     }
     \context Staff = "down" {
@@ -1956,7 +2016,7 @@ typeset as cautionaries.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1988,7 +2048,7 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'piano-cautionary)
+      \accidentalStyle "piano-cautionary"
       \musicA
     }
     \context Staff = "down" {
@@ -2015,7 +2075,7 @@ if the note is immediately repeated.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2047,11 +2107,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'neo-modern)
+      \accidentalStyle "neo-modern"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'neo-modern)
+      \accidentalStyle "neo-modern"
       \musicB
     }
   >>
@@ -2072,7 +2132,7 @@ accidentals are printed as cautionary accidentals.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2104,11 +2164,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'neo-modern-cautionary)
+      \accidentalStyle "neo-modern-cautionary"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'neo-modern-cautionary)
+      \accidentalStyle "neo-modern-cautionary"
       \musicB
     }
   >>
@@ -2132,7 +2192,7 @@ but they are canceled across voices in the same @code{Staff}.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2164,11 +2224,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'neo-modern-voice)
+      \accidentalStyle "neo-modern-voice"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'neo-modern-voice)
+      \accidentalStyle "neo-modern-voice"
       \musicB
     }
   >>
@@ -2189,7 +2249,7 @@ accidentals are printed as cautionary accidentals.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2221,11 +2281,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'neo-modern-voice-cautionary)
+      \accidentalStyle "neo-modern-voice-cautionary"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'neo-modern-voice-cautionary)
+      \accidentalStyle "neo-modern-voice-cautionary"
       \musicB
     }
   >>
@@ -2249,7 +2309,7 @@ including natural signs.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2281,11 +2341,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'dodecaphonic)
+      \accidentalStyle "dodecaphonic"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'dodecaphonic)
+      \accidentalStyle "dodecaphonic"
       \musicB
     }
   >>
@@ -2310,7 +2370,7 @@ key signature, except if the note is immediately repeated.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2343,12 +2403,12 @@ musicB = {
   <<
     \context Staff = "up" {
       \key fis \minor
-      #(set-accidental-style 'teaching)
+      \accidentalStyle "teaching"
       \musicA
     }
     \context Staff = "down" {
       \key fis \minor
-      #(set-accidental-style 'teaching)
+      \accidentalStyle "teaching"
       \musicB
     }
   >>
@@ -2371,7 +2431,7 @@ This is the same as @code{default} but with accidentals lasting
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2403,11 +2463,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'no-reset)
+      \accidentalStyle "no-reset"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'no-reset)
+      \accidentalStyle "no-reset"
       \musicB
     }
   >>
@@ -2424,14 +2484,13 @@ musicB = {
 This is the opposite of @code{no-reset}: Accidentals are not
 remembered at all -- and hence all accidentals are typeset
 relative to the key signature, regardless of what came before in
-the music.  Unlike @code{dodecaphonic}, this rule never prints
-any naturals.
+the music.
 
 @lilypond[quote]
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2463,11 +2522,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      #(set-accidental-style 'forget)
+      \accidentalStyle "forget"
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'forget)
+      \accidentalStyle "forget"
       \musicB
     }
   >>
@@ -2475,12 +2534,6 @@ musicB = {
 @end lilypond
 @end table
 
-@snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
-
-
 @seealso
 Snippets:
 @rlsr{Pitches}.
@@ -2518,7 +2571,7 @@ not need a natural sign:
 
 @lilypond[quote]
 {
-  #(set-accidental-style 'modern)
+  \accidentalStyle "modern"
   \time 2/4
   \repeat volta 2 {
     c'2
@@ -2535,12 +2588,12 @@ the accidental style to @code{forget}:
 
 @lilypond[verbatim,quote]
 forget = #(define-music-function (parser location music) (ly:music?) #{
-  #(set-accidental-style 'forget)
+  \accidentalStyle "forget"
   $music
-  #(set-accidental-style 'modern)
+  \accidentalStyle "modern"
 #})
 {
-  #(set-accidental-style 'modern)
+  \accidentalStyle "modern"
   \time 2/4
   \repeat volta 2 {
     c'2
@@ -2587,13 +2640,13 @@ printed if they are not part of the key signature.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {adding-ambitus-per-voice.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {ambitus-with-multiple-voices.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {changing-the-ambitus-gap.ly}
 
 
@@ -2771,7 +2824,7 @@ font, see @ref{Setting the staff size}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {numbers-as-easy-note-heads.ly}
 
 
@@ -2891,7 +2944,7 @@ a2 b c d \break
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
 
 To see all note head styles, see @ref{Note head styles}.