Issue 5164: Doc: Add usage of OpenType font feature

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

diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index 9529c6704bfb0d5999c0ae96b8e486d57411109f..15af95d1405ba6ff626fd31ee912f7581f559274 100644 (file)
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.19.22"
+@c \version "2.19.53"

 
 
 @node Pitches
 
 
 @node Pitches


@@ -87,7 +87,6 @@ octave.
 }
 @end lilypond
 
 }
 @end lilypond
 

-@funindex fixed

 @funindex \fixed
 Common octave marks can be entered just once on a reference pitch
 after @code{\fixed} placed before the music.  Pitches inside
 @funindex \fixed
 Common octave marks can be entered just once on a reference pitch
 after @code{\fixed} placed before the music.  Pitches inside


@@ -129,7 +128,6 @@ Snippets:
 @cindex relative octave specification
 @cindex octave specification, relative
 
 @cindex relative octave specification
 @cindex octave specification, relative
 

-@funindex relative

 @funindex \relative
 
 Absolute octave entry requires specifying the octave for every
 @funindex \relative
 
 Absolute octave entry requires specifying the octave for every


@@ -299,6 +297,24 @@ that each interval contains.
 }
 @end lilypond
 
 }
 @end lilypond
 

+In complex situations, it is sometimes useful to get back to a
+certain pitch regardless of what happened before. This can be
+done using @code{\resetRelativeOctave}:
+
+@lilypond[verbatim,quote]
+\relative {
+  <<
+    { c''2 d }
+    \\
+    { e,,2 f }
+  >>
+  \resetRelativeOctave c''
+  c2
+}
+@end lilypond
+
+@funindex \resetRelativeOctave
+

 
 @seealso
 Music Glossary:
 
 @seealso
 Music Glossary:


@@ -319,11 +335,8 @@ Internals Reference:
 @cindex transposition and relative octave entry
 
 @funindex \transpose
 @cindex transposition and relative octave entry
 
 @funindex \transpose

-@funindex transpose

 @funindex \chordmode
 @funindex \chordmode

-@funindex chordmode

 @funindex \relative
 @funindex \relative

-@funindex relative

 
 
 @node Accidentals
 
 
 @node Accidentals


@@ -461,7 +474,7 @@ Internals Reference:
 
 @knownissues
 There are no generally accepted standards for denoting
 
 @knownissues
 There are no generally accepted standards for denoting

-quarter-tone accidentals, so LilyPond's symbol does not conform to
+quarter-tone accidentals, so LilyPond's symbols do not conform to

 any standard.
 
 
 any standard.
 
 


@@ -523,7 +536,7 @@ In addition to note names, accidental suffixes may
 also vary depending on the language:
 
 @quotation
 also vary depending on the language:
 
 @quotation

-@multitable {@code{nederlands}} {-@code{s}/-@code{-sharp}} {-@code{ess}/-@code{es}} {-@code{ss}/-@code{x}/-@code{-sharpsharp}} {-@code{essess}/-@code{eses}}
+@multitable {@code{nederlands}} {-@code{s}/-@code{-sharp}} {-@code{f}/-@code{-flat}} {-@code{ss}/-@code{x}/-@code{-sharpsharp}} {-@code{ff}/-@code{-flatflat}}

 @headitem Language
   @tab sharp @tab flat @tab double sharp @tab double flat
 @item @code{nederlands}
 @headitem Language
   @tab sharp @tab flat @tab double sharp @tab double flat
 @item @code{nederlands}


@@ -645,7 +658,6 @@ This section discusses how to modify pitches.
 
 @funindex =
 @funindex \octaveCheck
 
 @funindex =
 @funindex \octaveCheck

-@funindex octaveCheck

 @funindex controlpitch
 
 In relative mode, it is easy to forget an octave changing mark.
 @funindex controlpitch
 
 In relative mode, it is easy to forget an octave changing mark.


@@ -720,7 +732,6 @@ Internals Reference:
 @cindex notes, transposition of
 
 @funindex \transpose
 @cindex notes, transposition of
 
 @funindex \transpose

-@funindex transpose

 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is


@@ -838,11 +849,8 @@ Internals Reference:
 @rinternals{TransposedMusic}.
 
 @funindex \transpose
 @rinternals{TransposedMusic}.
 
 @funindex \transpose

-@funindex transpose

 @funindex \chordmode
 @funindex \chordmode

-@funindex chordmode

 @funindex \relative
 @funindex \relative

-@funindex relative

 
 @knownissues
 The relative conversion will not affect @code{\transpose},
 
 @knownissues
 The relative conversion will not affect @code{\transpose},


@@ -851,7 +859,7 @@ 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
 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
+@q{enharmonically equivalent} pitch will be used instead (e.g., d-flat

 rather than e-triple-flat).
 
 
 rather than e-triple-flat).
 
 


@@ -900,7 +908,6 @@ Notation Reference:
 @cindex transformation, retrograde
 @cindex operation, retrograde
 @funindex \retrograde
 @cindex transformation, retrograde
 @cindex operation, retrograde
 @funindex \retrograde

-@funindex retrograde

 
 A music expression can be reversed to produce its retrograde:
 
 
 A music expression can be reversed to produce its retrograde:
 


@@ -914,9 +921,14 @@ music = \relative { c'8. ees16( fis8. a16 b8.) gis16 f8. d16 }
 @end lilypond
 
 @knownissues
 @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}.
+@code{\retrograde} is a rather simple tool.  Since many events are
+@q{mirrored} rather than exchanged, tweaks and directional
+modifiers for opening spanners need to be added at the matching
+closing spanners: @code{^(} needs to be ended by @code{^)}, every
+@code{\<} or @code{\cresc} needs to be ended by @code{\!} or
+@code{\endcr}, every @code{\>} or @code{\decr} needs to be ended
+by @code{\enddecr}.  Property-changing commands/overrides with a
+lasting effect will likely cause surprises.

 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:


@@ -948,7 +960,6 @@ left untransformed.}
 @cindex transposition, modal
 @cindex operation, transposition
 @funindex \modalTranspose
 @cindex transposition, modal
 @cindex operation, transposition
 @funindex \modalTranspose

-@funindex modalTranspose

 
 A motif can be transposed within a given scale with:
 
 
 A motif can be transposed within a given scale with:
 


@@ -1005,7 +1016,6 @@ motif = \relative { c'8 d e f g a b c }
 @cindex inversion, modal
 @cindex operation, modal inversion
 @funindex \modalInversion
 @cindex inversion, modal
 @cindex operation, modal inversion
 @funindex \modalInversion

-@funindex modalInversion

 
 A motif can be inverted within a given scale around a given pivot
 note and transposed in a single operation with:
 
 A motif can be inverted within a given scale around a given pivot
 note and transposed in a single operation with:


@@ -1119,7 +1129,6 @@ This section discusses how to alter the output of pitches.
 
 
 @funindex \clef
 
 
 @funindex \clef

-@funindex clef

 
 Without any explicit command, the default clef for LilyPond is the
 treble (or @emph{G}) clef.
 
 Without any explicit command, the default clef for LilyPond is the
 treble (or @emph{G}) clef.


@@ -1228,6 +1237,13 @@ will be ignored.  The command
   c'1
 @end lilypond
 
   c'1
 @end lilypond
 

+@noindent
+To be more precise, it is not the @code{\clef} command itself that
+prints a clef.  Instead, it sets or changes a property of the
+@code{Clef_engraver}, which then decides by its own whether to
+display a clef or not in the current staff.  The @code{forceClef}
+property overrides this decision locally to re-print a clef once.
+

 When there is a manual clef change, the glyph of the changed clef
 will be smaller than normal.  This behaviour can be overridden.
 
 When there is a manual clef change, the glyph of the changed clef
 will be smaller than normal.  This behaviour can be overridden.
 


@@ -1296,7 +1312,6 @@ need to be applied, as a separate @code{\override}, to the
 @cindex key signature
 
 @funindex \key
 @cindex key signature
 
 @funindex \key

-@funindex key

 
 @c duplicated in Key signature and Accidentals
 @warning{New users are sometimes confused about accidentals and
 
 @c duplicated in Key signature and Accidentals
 @warning{New users are sometimes confused about accidentals and


@@ -1315,23 +1330,14 @@ at the start of the staff.  The key signature may be altered:
 @end example
 
 @funindex \major
 @end example
 
 @funindex \major

-@funindex major

 @funindex \minor
 @funindex \minor

-@funindex minor

 @funindex \ionian
 @funindex \ionian

-@funindex ionian

 @funindex \locrian
 @funindex \locrian

-@funindex locrian

 @funindex \aeolian
 @funindex \aeolian

-@funindex aeolian

 @funindex \mixolydian
 @funindex \mixolydian

-@funindex mixolydian

 @funindex \lydian
 @funindex \lydian

-@funindex lydian

 @funindex \phrygian
 @funindex \phrygian

-@funindex phrygian

 @funindex \dorian
 @funindex \dorian

-@funindex dorian

 
 @cindex church modes
 @cindex modes
 
 @cindex church modes
 @cindex modes


@@ -1434,7 +1440,6 @@ Internals Reference:
 
 @funindex set-octavation
 @funindex \ottava
 
 @funindex set-octavation
 @funindex \ottava

-@funindex ottava

 
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
 
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:


@@ -1489,7 +1494,6 @@ Internals Reference:
 @cindex MIDI transposition
 
 @funindex \transposition
 @cindex MIDI transposition
 
 @funindex \transposition

-@funindex transposition

 
 When typesetting scores that involve transposing instruments, some
 parts can be typeset in a different pitch than the
 
 When typesetting scores that involve transposing instruments, some
 parts can be typeset in a different pitch than the


@@ -1519,26 +1523,24 @@ playing in unison.
 
 @lilypond[verbatim,quote]
 \new GrandStaff <<
 
 @lilypond[verbatim,quote]
 \new GrandStaff <<

-  \new Staff = "violin" {
-    \relative c'' {
-      \set Staff.instrumentName = #"Vln"
-      \set Staff.midiInstrument = #"violin"
-      % not strictly necessary, but a good reminder
-      \transposition c'
-
-      \key c \major
-      g4( c8) r c r c4
-    }
+  \new Staff = "violin" \with {
+    instrumentName = #"Vln"
+    midiInstrument = #"violin"

   }
   }

-  \new Staff = "clarinet" {
-    \relative c'' {
-      \set Staff.instrumentName = \markup { Cl (B\flat) }
-      \set Staff.midiInstrument = #"clarinet"
-      \transposition bes
-
-      \key d \major
-      a4( d8) r d r d4
-    }
+  \relative c'' {
+    % not strictly necessary, but a good reminder
+    \transposition c'
+    \key c \major
+    g4( c8) r c r c4
+  }
+  \new Staff = "clarinet" \with {
+    instrumentName = \markup { Cl (B\flat) }
+    midiInstrument = #"clarinet"
+  }
+  \relative c'' {
+    \transposition bes
+    \key d \major
+    a4( d8) r d r d4

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -2211,6 +2213,129 @@ musicB = {
 @end lilypond
 
 
 @end lilypond
 
 

+@item choral
+
+@cindex accidental style, choral
+@cindex accidentals, choral
+@cindex choral accidental style
+@cindex choral accidentals
+
+@funindex choral
+
+This rule is a combination of the @code{modern-voice} and the @code{piano}
+style. It shows all accidentals required for singers that only follow their
+own voice, as well as additional accidentals for readers that follow all
+voices of an entire @code{ChoirStaff} simultaneously.
+
+This accidental style applies to the current @code{ChoirStaff} by default.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
+      \change Staff = up
+      cis' cis
+      \change Staff = down
+      <fis, a> <fis a>]
+      \showStaffSwitch
+      \change Staff = up
+      dis'4 |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new ChoirStaff {
+  <<
+    \context Staff = "up" {
+      \accidentalStyle choral
+      \musicA
+    }
+    \context Staff = "down" {
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+@item choral-cautionary
+
+@cindex accidentals, choral cautionary
+@cindex cautionary accidentals, choral
+@cindex choral cautionary accidentals
+@cindex accidental style, choral cautionary
+@cindex cautionary accidental style, choral
+@cindex choral cautionary accidental style
+
+@funindex choral-cautionary
+
+This is the same as @code{choral} but with the extra accidentals
+typeset as cautionaries.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
+      \change Staff = up
+      cis' cis
+      \change Staff = down
+      <fis, a> <fis a>]
+      \showStaffSwitch
+      \change Staff = up
+      dis'4 |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new ChoirStaff {
+  <<
+    \context Staff = "up" {
+      \accidentalStyle choral-cautionary
+      \musicA
+    }
+    \context Staff = "down" {
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+

 @item neo-modern
 
 @cindex neo-modern accidental style
 @item neo-modern
 
 @cindex neo-modern accidental style


@@ -3070,9 +3195,7 @@ Internals Reference:
 @cindex note heads, easy play
 
 @funindex \easyHeadsOn
 @cindex note heads, easy play
 
 @funindex \easyHeadsOn

-@funindex easyHeadsOn

 @funindex \easyHeadsOff
 @funindex \easyHeadsOff

-@funindex easyHeadsOff

 
 The @q{easy play} note head includes a note name inside the head.
 It is used in music for beginners.  To make the letters readable,
 
 The @q{easy play} note head includes a note name inside the head.
 It is used in music for beginners.  To make the letters readable,


@@ -3137,15 +3260,10 @@ Internals Reference:
 @cindex note heads, Walker
 
 @funindex \aikenHeads
 @cindex note heads, Walker
 
 @funindex \aikenHeads

-@funindex aikenHeads

 @funindex \sacredHarpHeads
 @funindex \sacredHarpHeads

-@funindex sacredHarpHeads

 @funindex \southernHarmonyHeads
 @funindex \southernHarmonyHeads

-@funindex southernHarmonyHeads

 @funindex \funkHeads
 @funindex \funkHeads

-@funindex funkHeads

 @funindex \walkerHeads
 @funindex \walkerHeads

-@funindex walkerHeads

 
 In shape note head notation, the shape of the note head
 corresponds to the harmonic function of a note in the scale.  This
 
 In shape note head notation, the shape of the note head
 corresponds to the harmonic function of a note in the scale.  This


@@ -3169,17 +3287,11 @@ Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
 @end lilypond
 
 @funindex \key
 @end lilypond
 
 @funindex \key

-@funindex key

 @funindex \aikenHeadsMinor
 @funindex \aikenHeadsMinor

-@funindex aikenHeadsMinor

 @funindex \sacredHarpHeadsMinor
 @funindex \sacredHarpHeadsMinor

-@funindex sacredHarpHeadsMinor

 @funindex \southernHarmonyHeadsMinor
 @funindex \southernHarmonyHeadsMinor

-@funindex southernHarmonyHeadsMinor

 @funindex \funkHeadsMinor
 @funindex \funkHeadsMinor

-@funindex funkHeadsMinor

 @funindex \walkerHeadsMinor
 @funindex \walkerHeadsMinor

-@funindex walkerHeadsMinor

 
 Shapes are typeset according to the step in the scale, where the base
 of the scale is determined by the @code{\key} command.  When writing
 
 Shapes are typeset according to the step in the scale, where the base
 of the scale is determined by the @code{\key} command.  When writing


@@ -3249,9 +3361,7 @@ Internals Reference:
 @cindex note heads, slashed
 
 @funindex \improvisationOn
 @cindex note heads, slashed
 
 @funindex \improvisationOn

-@funindex improvisationOn

 @funindex \improvisationOff
 @funindex \improvisationOff

-@funindex improvisationOff

 
 Improvisation is sometimes denoted with slashed note heads, where
 the performer may choose any pitch but should play the specified
 
 Improvisation is sometimes denoted with slashed note heads, where
 the performer may choose any pitch but should play the specified