X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpitches.itely;h=5813221d26dffde57763fb16c29c24ef87bc73e3;hb=83df07d0725ae6ef2004d32b5974a5465c9938d7;hp=fba0d95987a58a76c7ee2a1d3f957e9623f6a32d;hpb=b696bba38675d4b9ba88cc64e3111d3dec0fc506;p=lilypond.git

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index fba0d95987..5813221d26 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -43,8 +43,6 @@ This section discusses how to input pitches.
 @cindex pitch names
 @cindex pitches
 
-@c don't use @samp here because that might get confused with
-@c octave marks
 A pitch name is specified using lowercase letters@tie{}@code{a}
 through@tie{}@code{g}.  An ascending C-major scale is engraved
 with
@@ -54,17 +52,16 @@ with
 c d e f g a b c'
 @end lilypond
 
-There are two different ways to enter these note names with regard
-to octave placement: absolute and relative.  The relative mode
-will in most cases be the most convenient, but the absolute mode
-is more fundamental and will be presented first.
-
 @cindex absolute
 @cindex absolute octave specification
 
-In absolute mode, every note is placed explicitly in a specific
-octave.  The note names @code{c} to @code{b} are engraved in the
-octave below middle C, as in the previous example.
+There are two different ways to enter these note names with regard
+to octave placement: absolute and relative.  The relative mode
+will in most cases be the most convenient, but the absolute mode
+is more fundamental and will be presented first.  In absolute
+mode, every note is placed explicitly in a specific octave.  The
+note names @code{c} to @code{b} are engraved in the octave below
+middle C, as in the previous example.
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \clef treble
@@ -176,7 +173,8 @@ large intervals:
 
 If the preceding item is a chord, the first note of the chord is
 used as the reference point for the octave placement of a
-following note or chord:
+following note or chord.  Inside of chords the next note is always
+relative to the preceding one.
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \relative c' {
@@ -256,9 +254,9 @@ a2 aisis a aeses
 @end lilypond
 
 @noindent
-These are the Dutch note names.  In Dutch, @code{aes} is
-contracted to @code{as}, but both forms are accepted.  Similarly,
-both @code{es} and @code{ees} are accepted:
+The above notes are the Dutch note names.  In Dutch, @code{aes} is
+contracted to @code{as}, but both forms are accepted in LilyPond.
+Similarly, both @code{es} and @code{ees} are accepted:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a2 as e es
@@ -305,7 +303,7 @@ pitches
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \set Staff.extraNatural = ##f
-ceseh ceh cih cisih
+ceseh ces ceh c cih cis cisih
 @end lilypond
 
 Micro tones are also exported to the MIDI file.
@@ -313,16 +311,11 @@ Micro tones are also exported to the MIDI file.
 
 @commonprop
 
-In accordance with standard typesetting rules, a natural sign is
-printed before a sharp or flat if a previous accidental needs to
-be canceled.  To change this behavior, use
+@lilypondfile[quote,ragged-right,texidoc]{pitches/preventing-extra-naturals-from-being-automatically-added.ly}
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-ceses4 ces cis c
-\set Staff.extraNatural = ##f
-ceses4 ces cis c
-@end lilypond
+@lilypondfile[quote,ragged-right,texidoc]{pitches/dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
 
+@lilypondfile[quote,ragged-right,texidoc]{pitches/makam.ly}
 
 @seealso
 
@@ -417,13 +410,6 @@ Here the prefixes @q{semi-} and @q{sesqui-} mean @q{half} and
 special names have been defined yet.
 
 
-@c What about Turkish Maquam music and similar microtonal systems?
-@c
-@c Note that the term "three-quarter-sharp/-flat" used in
-@c lilypond's source code is actually misleading since the
-@c alteration is in fact one and a half of a regular sharp/flat.
-@c Whence the naming "sesqui-sharp/-flat" used below.
-
 @example
 @multitable @columnfractions .2 .6 .05 .05 .05 .05
 @headitem Language
@@ -562,6 +548,7 @@ Snippets: @lsrdir{pitches}.
 
 @cindex transpose
 @cindex transposition of pitches
+@cindex transposing instruments
 @funindex \transpose
 
 A music expression can be transposed with @code{\transpose}.  The
@@ -612,10 +599,10 @@ will remain on the same scale step, the second version will print
 flats on the scale step above.
 
 @lilypond[verbatim,quote,ragged-right]
-mus = { c d e f }
+mus = \relative c' { c d e f }
 \new Staff {
-  \transpose c cis { \relative c' \mus }
-  \transpose c des { \relative c' \mus }
+  \transpose c cis { \mus }
+  \transpose c des { \mus }
 }
 @end lilypond
 
@@ -640,10 +627,15 @@ musicInBflat = @{ e4 @dots{} @}
 \transpose f c @{ \transpose c bes \musicInBflat @}
 @end example
 
+@commonprop
+
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
+
+
 @seealso
 
-Snippets: @lsrdir{pitches}, @lsr{scheme,
-transpose-pitches-with-minimum-accidentals.ly}.
+Snippets: @lsrdir{pitches}.
 
 Internals reference: @internalsref{TransposedMusic}.
 
@@ -689,24 +681,17 @@ This section discusses how to alter the output of pitches.
 @cindex varbaritone clef
 @cindex subbass clef
 
-The clef is set with the @code{\clef} @var{clefname}
-command:
+The clef is set with the @code{\clef} @var{clefname} command:
 
-@lilypond[verbatim,quote,ragged-right,fragment]
-<<
-  \new Staff {
-    % treble clef by default
-    c'1^"middle C"
-  }
-  \new Staff {
-    \clef alto
-    c'1^"middle C"
-  }
-  \new Staff {
-    \clef bass
-    c'1^"middle C"
-  }
->>
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+\clef treble
+c2 c
+\clef alto
+c2 c
+\clef tenor
+c2 c
+\clef bass
+c2 c
 @end lilypond
 
 The clef can also be changed inside the staff:
@@ -778,84 +763,12 @@ For example,
 \clef "G_8" c4
 @end lilypond
 
-@commonprop
-
-When a clef change takes place at a line break the new clef symbol
-is printed at both the end of the previous line and the beginning
-of the new line by default.  If the warning clef at the end of the
-previous line in not required it can be suppressed by setting the
-@code{explicitClefVisibility} Staff property to the value
-@var{end-of-line-invisible}:  @code{\set
-Staff.explicitClefVisibility = #end-of-line-invisible} The default
-behaviour can be recovered with @code{\unset
-Staff.explicitClefVisibility}
-
-The command @code{\clef "treble_8"} is equivalent to setting
-@code{clefGlyph}, @code{clefPosition} (which controls the Y
-position of the clef), @code{middleCPosition} and
-@code{clefOctavation}.  A clef is printed when either the
-@code{clefGlyph}, @code{clefPosition} or @code{clefOctavation}
-properties are changed.  Note that changing the glyph, the
-position of the clef, or the octavation, does not in itself change
-the position of subsequent notes on the staff: the position of
-middle C must also be specified to do this.  The positional
-parameters are relative to the staff centre line, positive numbers
-displacing upwards, counting 1 for each line and space.  The
-clefOctavation value would normally be set to 7, -7, 15 or -15,
-but other values are not invalid.
-
-The following examples show the possibilities when setting these
-properties manually.  First some manual changes which preserve the
-standard relative positioning of clefs and notes:
 
-@lilypond[verbatim,quote,ragged-right]
-{
-  % The default treble clef
-  c'4
-  % The standard bass clef
-  \set Staff.clefGlyph = #"clefs.F"
-  \set Staff.clefPosition = #2
-  \set Staff.middleCPosition = #6
-  c'4
-  % The baritone clef
-  \set Staff.clefGlyph = #"clefs.C"
-  \set Staff.clefPosition = #4
-  \set Staff.middleCPosition = #4
-  c'4
-  % The standard choral tenor clef
-  \set Staff.clefGlyph = #"clefs.G"
-  \set Staff.clefPosition = #-2
-  \set Staff.clefOctavation = #-7
-  \set Staff.middleCPosition = #1
-  c'4
-  % A non-standard clef
-  \set Staff.clefPosition = #0
-  \set Staff.clefOctavation = #0
-  \set Staff.middleCPosition = #-4
-  c'4
-}
-@end lilypond
+@commonprop
 
-and some which do not:
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/clefs-commonly-tweaked-properties.ly}
 
-@lilypond[verbatim,quote,ragged-right]
-{
-  \set Staff.clefGlyph = #"clefs.F"
-  \set Staff.clefPosition = #2
-  c'4
-  \set Staff.clefGlyph = #"clefs.G"
-  c'4
-  \set Staff.clefGlyph = #"clefs.C"
-  c'4
-  \set Staff.clefOctavation = #7
-  c'4
-  \set Staff.clefOctavation = #0
-  \set Staff.clefPosition = #0
-  c'4
-  \set Staff.middleCPosition = #4
-  c'4
-}
-@end lilypond
 
 @seealso
 
@@ -918,49 +831,15 @@ fis
 
 @commonprop
 
-A natural sign is printed to cancel any previous accidentals.
-This may be altered:
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-\key d \major
-a b cis d
-\key g \minor
-a bes c d
-\set Staff.printKeyCancellation = ##f
-\key d \major
-a b cis d
-\key g \minor
-a bes c d
-@end lilypond
-
-The @code{\key} command sets the context property
-@code{Staff.keySignature}.  Non-standard key signatures can be
-specified by setting this property directly.  The format of this
-command is a list:
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 
-@example
-\set Staff.keySignature =
-  #'((@var{octave} . @var{step}) . @var{alter})
-@end example
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/non-traditional-key-signatures.ly}
 
-@noindent
-where, for each element in the list, @var{octave} specifies the
-octave (0 being the octave from middle C to the B above),
-@var{step} specifies the note within the octave (0 means C and 6
-means B), and @var{alter} is @code{,SHARP} @code{,FLAT}
-@code{,DOUBLE-SHARP} etc.  (Note the leading comma.)  Here is an
-example of a possible key signature for generating a whole-tone
-scale:
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
 
-@lilypond[verbatim,quote,ragged-right]
-\relative c' {
-  \new Staff {
-    \set Staff.keySignature =
-      #`(((0 .  3) . ,SHARP) ((0 . 5) . ,FLAT) ((0 . 6) . ,FLAT))
-    c d e fis aes bes c
-  }
-}
-@end lilypond
 
 @seealso
 
@@ -968,9 +847,7 @@ Music Glossary: @rglos{church mode}, @rglos{scordatura}.
 
 Learning Manual: @rlearning{Accidentals and key signatures}.
 
-Snippets: @lsrdir{pitches},
-FIXME link to snippet 248,
-FIXME link to a snippet about scordatura.
+Snippets: @lsrdir{pitches}.
 
 Internals reference: @internalsref{KeyCancellation},
 @internalsref{KeySignature}, @internalsref{Key_engraver}.
@@ -988,14 +865,12 @@ Internals reference: @internalsref{KeyCancellation},
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
 
-@lilypond[verbatim,quote,ragged-right,fragment]
-\relative c''' {
-  a2 b
-  #(set-octavation 1)
-  a b
-  #(set-octavation 0)
-  a b
-}
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a'2 b
+#(set-octavation 1)
+a b
+#(set-octavation 0)
+a b
 @end lilypond
 
 The @code{set-octavation} function also takes -1 (for 8va bassa),
@@ -1005,18 +880,16 @@ Internally the function sets the properties @code{ottavation}
 @code{middleCPosition}.  To override the text of the bracket, set
 @code{ottavation} after invoking @code{set-octavation}, i.e.,
 
-@lilypond[verbatim,quote,ragged-right]
-{
-  #(set-octavation 1)
-  \set Staff.ottavation = #"8"
-  c'''
-}
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+#(set-octavation 1)
+\set Staff.ottavation = #"8"
+c'
 @end lilypond
 
 
 @seealso
 
-Music Glossary: @c FIXME add link once it's in the glossary @c @rgloss{ottava}.
+Music Glossary: @rglos{ottava}.
 
 Snippets: @lsrdir{pitches}.
 
@@ -1115,8 +988,6 @@ to serve as a reminder that these parts are written in C.
 
 @seealso
 
-Music Glossary: @c FIXME add link once it's in the glossary @c @rgloss{instrument transposition}.
-
 Notation Reference: @ref{Quoting other voices}, @ref{Transpose}.
 
 Snippets: @lsrdir{pitches}.
@@ -1126,11 +997,12 @@ Snippets: @lsrdir{pitches}.
 @unnumberedsubsubsec Automatic accidentals
 @cindex automatic accidentals
 
-Common rules for typesetting accidentals have been placed in a
-function.  This function is called as follows
-
 @funindex set-accidental-style
 
+There are many different conventions on how to typeset accidentals. 
+LilyPond provides a function to specify which such accidental style to
+use.   This function is called as follows
+
 @example
 \new Staff <<
   #(set-accidental-style 'voice)
@@ -1138,18 +1010,15 @@ function.  This function is called as follows
 >>
 @end example
 
-@c TODO: check the context stuff below
-@c -does it *really* work?
-@c -the default contexts as specified in
-@c  scm/music-function.scm seem to be different -vv
-
-If no context name is supplied, the accidental style applies to
-the @code{Staff} by default.  Optionally, the function can take
-the context for which the style should be changed as a second
-argument:
+The accidental style applies to the current @code{Staff} by default
+(with the exception of the styles @code{piano} and
+@code{piano-cautionary}, see below.  
+Optionally, the function can take second argument which determines in
+which 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 'STYLE #('CONTEXT))
+#(set-accidental-style 'voice 'StaffGroup)
 @end example
 
 The following accidental styles are supported.  To demonstrate
@@ -1191,18 +1060,37 @@ musicB = {
   <<
     \context Staff = "up" {
       %%% change the next line as desired:
-      %#(set-accidental-style 'default)
+      #(set-accidental-style 'default)
       \musicA
     }
     \context Staff = "down" {
       %%% change the next line as desired:
-      %#(set-accidental-style 'default)
+      #(set-accidental-style 'default)
       \musicB
     }
   >>
 }
 @end lilypond
 
+Note that the last lines of this example can be replaced by the
+followin, as long as the same accidental style should be used in both
+staves. 
+@example
+\new PianoStaff @{
+  <<
+    \context Staff = "up" @{
+      %%% change the next line as desired:
+      #(set-accidental-style 'default 'Score)
+      \musicA
+    @}
+    \context Staff = "down" @{
+      \musicB
+    @}
+  >>
+@}
+@end example
+
+
 @c don't use verbatim in this table.
 @table @code
 @item default
@@ -1248,11 +1136,11 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      %#(set-accidental-style 'default)
+      #(set-accidental-style 'default)
       \musicA
     }
     \context Staff = "down" {
-      %#(set-accidental-style 'default)
+      #(set-accidental-style 'default)
       \musicB
     }
   >>
@@ -1442,7 +1330,7 @@ musicB = {
 This rule is used for multivoice accidentals to be read both by
 musicians playing one voice and musicians playing all voices.
 Accidentals are typeset for each voice, but they @emph{are}
-canceled across voices in the same @internalsref{Staff}.  Hence,
+canceled across voices in the same @code{Staff}.  Hence,
 the@tie{}@code{a} in the last measure is canceled because the
 previous cancellation was in a different voice, and
 the@tie{}@code{d} in the lower staff is canceled because of the
@@ -1557,25 +1445,10 @@ This rule reflects twentieth-century practice for piano notation.
 Its behavior is very similar to @code{modern} style, but here
 accidentals also get canceled across the staves in the same
 GrandStaff or PianoStaff, hence all the cancellations of the final
-notes.
-
-This accidental style takes place in a GrandStaff context.
-However, you have to explicitly set it for @emph{each} individual
-Staff of the GrandStaff:
-
+notes. 
 
-@example
-\new GrandStaff @{ <<
-  \new Staff = "up" @{ <<
-    #(set-accidental-style 'piano)
-    @{ @dots{} @}
-  >> @}
-  \new Staff = "down" @{ <<
-    #(set-accidental-style 'piano)
-    @{ @dots{} @}
-  >> @}
->> @}
-@end example
+This accidental style applies to the current @code{GrandStaff} or
+@code{PianoStaff} by default.
 
 @lilypond[quote,ragged-right]
 musicA = {
@@ -1616,7 +1489,6 @@ musicB = {
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'piano)
       \musicB
     }
   >>
@@ -1668,7 +1540,6 @@ musicB = {
       \musicA
     }
     \context Staff = "down" {
-      #(set-accidental-style 'piano-cautionary)
       \musicB
     }
   >>
@@ -1817,71 +1688,40 @@ determine if it matches their capabilities.
 
 Ambits are denoted at the beginning of a piece near the initial
 clef.  The range is graphically specified by two note heads that
-represent the minimum and maximum pitch.  To print such ambits,
-add the @code{Ambitus_engraver} to the @code{Voice} context, for
-example:
+represent the minimum and maximum pitch.  Accidentals are only
+printed if they are not part of the key signature.
 
 @lilypond[verbatim,quote,ragged-right]
 \layout {
   \context {
-    \Staff
+    \Voice
     \consists Ambitus_engraver
   }
 }
 
-\relative \new Staff {
-  as'' c e2 cis,2
+\relative c'' {
+  aes c e2 cis,2
 }
 @end lilypond
 
-If you have multiple voices in a single staff and you want a
-single ambitus per staff rather than per voice, add the
-@code{Ambitus_engraver} to the @code{Staff} context rather than to
-the @code{Voice} context:
 
-@lilypond[verbatim,quote,ragged-right]
-\new Staff \with {
-  \consists "Ambitus_engraver"
-}
-<<
-  \new Voice \with {
-    \remove "Ambitus_engraver"
-  } \relative c'' {
-    \override Ambitus #'X-offset = #-1.0
-    \voiceOne
-    c4 a d e f2
-  }
-  \new Voice \with {
-    \remove "Ambitus_engraver"
-  } \relative c' {
-    \voiceTwo
-    es4 f g as b2
-  }
->>
-@end lilypond
+@commonprop
 
-@noindent
-This example uses one advanced feature,
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/adding-ambiti-per-voice.ly}
 
-@example
-\override Ambitus #'X-offset = #-1.0
-@end example
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/ambiti-multiple-voices.ly}
 
-@noindent
-This code moves the ambitus to the left.  The same effect could
-have been achieved with @code{extra-offset}, but then the
-formatting system would not reserve space for the moved object.
 
 @seealso
 
 Snippets: @lsrdir{pitches}.
-@c FIXME: lsr stuff.
-@c @lsr{vocal,ambitus@/.ly}.
 
 Internals reference: @internalsref{Ambitus},
 @internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
 @internalsref{AmbitusAccidental}, @internalsref{Ambitus_engraver},
-@internalsref{Staff} and @internalsref{Voice}.
+@internalsref{Staff}, @internalsref{Voice}.
 
 
 @refbugs
@@ -1952,7 +1792,7 @@ Shape note heads can be produced by setting @code{\aikenHeads} or
 \aikenHeads
 c8 d4 e8 a2 g1
 \sacredHarpHeads
-c,8 d4. e8 a2 g1
+c,8 d4 e8 a2 g1
 @end lilypond
 
 Shapes are typeset according to the step in the scale, where
@@ -1971,9 +1811,15 @@ step of the scale.  Arbitrary combinations are possible, e.g.:
 @lilypond[verbatim,fragment,relative=1]
 \set shapeNoteStyles =
   ##(cross triangle fa #f mensural xcircle diamond)
-c8 d4. e8 a2 g1
+c8 d4 e8 a2 g1
 @end lilypond
 
+@commonprop
+
+@lilypondfile[quote,ragged-right,texidoc]
+{pitches/applying-noteheads-styles-depending-on-the-step-of-the-scale.ly}
+
+
 @seealso
 
 Snippets: @lsrdir{pitches}.