X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpitches.itely;h=e38bc880863b2c99646a3ce8cce4cc19eae67490;hb=3dd560c0c440c9e97730ca13f6d5abbb020bb02e;hp=c925afb184125fbc9913868d51c96578dfc4725a;hpb=682bdaa47443198aaee0df5c0f841469d71496c9;p=lilypond.git

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index c925afb184..e38bc88086 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -14,7 +14,7 @@
 {pitches-headword.ly}
 
 This section discusses how to specify the pitch of notes.  There
-are three steps to this process: input, modifying, and output.
+are three steps to this process: input, modification, and output.
 
 @menu
 * Writing pitches::             
@@ -114,8 +114,8 @@ interval is determined without considering accidentals.
 
 @item
 An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be added to
-respectively raise or lower a pitch by an extra octave, relatively to
-the pitch calculated without octave mark.
+respectively raise or lower a pitch by an extra octave, relative to
+the pitch calculated without an octave mark.
 
 @item
 Multiple octave changing marks can be used.  For example, @code{''}@tie{}and
@@ -162,7 +162,7 @@ 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.  Inside of chords the next note is always
+following note or chord.  Inside chords, the next note is always
 relative to the preceding one.
 
 @lilypond[verbatim,quote,ragged-right]
@@ -178,8 +178,8 @@ relative to the preceding one.
 
 As explained above, the octave of pitches is calculated only with
 the note names, regardless of any alterations.  Therefore, an
-E-double-sharp sharp following a B will be placed higher, while an
-F-double-flat would be placed lower.  In other words, a
+E-double-sharp following a B will be placed higher, while an
+F-double-flat will be placed lower.  In other words, a
 double-augmented fourth is considered a smaller interval than a
 double-diminished fifth, regardless of the number of semitones
 that each interval contains.
@@ -203,6 +203,10 @@ Notation Reference: @ref{Octave checks}.
 Snippets: @lsrdir{Pitches,Pitches}.
 
 
+@funindex \transpose
+@funindex \chordmode
+@funindex \relative
+
 @refbugs
 
 The relative conversion will not affect @code{\transpose},
@@ -221,6 +225,10 @@ discouraged.
 @node Accidentals
 @subsubsection Accidentals
 
+@cindex accidental
+@cindex key signature
+@cindex clef
+
 @warning{New users are sometimes confused about accidentals and
 key signatures.  In LilyPond, note names are the raw input; key
 signatures and clefs determine how this raw input is displayed.
@@ -230,13 +238,19 @@ see @rlearning{Accidentals and key signatures}.}
 
 @cindex note names, Dutch
 @cindex note names, default
-
-A @notation{sharp} pitch is made by adding @code{is} to the name,
-and a @notation{flat} pitch by adding @code{es}.  As you might
-expect, a @notation{double sharp} or @notation{double flat} is
-made by adding @code{isis} or @code{eses}.  This syntax is derived
-from Dutch note naming conventions.  To use other names for
-accidentals, see @ref{Note names in other languages}.
+@cindex sharp
+@cindex flat
+@cindex double sharp
+@cindex sharp, double
+@cindex double flat
+@cindex flat, double
+
+A @notation{sharp} pitch is made by adding @code{is} to the note name,
+and a @notation{flat} pitch by adding @code{es}.  As you might expect,
+a @notation{double sharp} or @notation{double flat} is made by adding
+@code{isis} or @code{eses}.  This syntax is derived from Dutch note
+naming conventions.  To use other names for accidentals, see
+@ref{Note names in other languages}.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 ais1 aes aisis aeses
@@ -284,8 +298,8 @@ natural signs.
 cis cis cis! cis? c c c! c?
 @end lilypond
 
-Accidentals are only printed on tied notes which begin a new
-system:
+Accidentals on tied notes are only printed at the beginning of a
+new system:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 cis1 ~ cis ~
@@ -302,7 +316,7 @@ cis
 @seealso
 
 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
-@rglos{double flat}, @rglos{Pitch names}.
+@rglos{double flat}, @rglos{Pitch names}, @rglos{quarter-tone}.
 
 Learning Manual: @rlearning{Accidentals and key signatures}.
 
@@ -316,8 +330,8 @@ Snippets: @lsrdir{Pitches,Pitches}.
 @refbugs
 
 There are no generally accepted standards for denoting
-three-quarter flats, so LilyPond's symbol does not conform to any
-standard.
+quarter-tone accidentals, so LilyPond's symbol does not conform to
+any standard.
 
 
 
@@ -325,12 +339,13 @@ standard.
 @subsubsection Note names in other languages
 
 There are predefined sets of note names for various other
-languages.  To use them, include the language specific init file.
-For example, add @code{\include "english.ly"} to the top of the
-input file.  The available language files and the note names they
-define are:
+languages.  To use them, include the language-specific init file.
+For example, to use English notes names, add @code{\include
+"english.ly"} to the top of the input file.  The available
+language files and the note names they define are:
 
 @cindex note names, other languages
+@cindex pitch names, other languages
 
 @smallexample
 @multitable {nederlands.ly} {do re mi fa sol la sib si} {-iss/-is} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
@@ -375,18 +390,30 @@ define are:
 @end multitable
 @end smallexample
 
+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.  This also applies to
+@code{aeses}@tie{}/@tie{}@code{ases} and
+@code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
+contracted names are defined in the corresponding language files.
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a2 as e es a ases e eses
+@end lilypond
+
+
 Some music uses microtones whose alterations are fractions of a
-@q{normal} sharp or flat.  The note names for quartertones defined
-in the various language files are listed in the following table.
-Here the prefixes @notation{semi-} and @notation{sesqui-} mean
-@q{half} and @q{one and a half}, respectively.  For the other
+@q{normal} sharp or flat.  The note names for quarter-tones
+defined in the various language files are listed in the following
+table.  Here the prefixes @notation{semi-} and @notation{sesqui-}
+mean @q{half} and @q{one and a half}, respectively.  For the other
 languages, no special names have been defined yet.
 
 @smallexample
 @multitable {nederlands.ly} {do re mi fa sol la sib si} {-iss/-is} {-ess/-es} {-ississ/-isis} {-ississ/-isis}
 @headitem Language
   @tab Note names
-  @tab semi- @tab semi- @tab sesqui- @tab sesqui-
+  @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 
 @item nederlands.ly
   @tab c d e f g a bes b
@@ -406,17 +433,6 @@ languages, no special names have been defined yet.
 @end multitable
 @end smallexample
 
-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.  This also applies to
-@code{aeses}@tie{}/@tie{}@code{ases} and
-@code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
-contracted names are defined in the corresponding language files.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-a2 as e es a ases e eses
-@end lilypond
-
 
 @seealso
 
@@ -461,14 +477,13 @@ the octave correction.
 }
 @end lilypond
 
-The octave of pitches may also be checked with the
-@code{\octave}@tie{}@var{controlpitch} command.
-@var{controlpitch} is specified in absolute mode.  This checks
-that the interval between the previous note and the
-@var{controlpitch} is within a fourth (i.e. the normal calculation
-of relative mode).  If this check fails, a warning is printed, but
-the previous note is not changed.  Future notes are relative to
-the @var{controlpitch}.
+The octave of notes may also be checked with the
+@code{\octave}@tie{}@var{controlpitch} command.  @var{controlpitch} is
+specified in absolute mode.  This checks that the interval between the
+previous note and the @var{controlpitch} is within a fourth (i.e. the
+normal calculation of relative mode).  If this check fails, a warning
+is printed, but the previous note is not changed.  Future notes are
+relative to the @var{controlpitch}.
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \relative c'' {
@@ -479,7 +494,7 @@ the @var{controlpitch}.
 @end lilypond
 
 Compare the two bars below.  The first and third @code{\octave}
-check fail, but the second ones passes without fail.
+check fail, but the second one does not fail.
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \relative c'' {
@@ -505,6 +520,7 @@ Snippets: @lsrdir{Pitches,Pitches}.
 @subsubsection Transpose
 
 @cindex transpose
+@cindex transposition
 @cindex transposition of pitches
 @funindex \transpose
 
@@ -519,7 +535,8 @@ syntax is
 This means that @var{musicexpr} is transposed by the interval
 between the pitches @var{frompitch} and @var{topitch}: any note
 with pitch @var{frompitch} is changed to @var{topitch} and any
-other note is transposed by the same interval.
+other note is transposed by the same interval.  Both pitches are
+entered in absolute mode.
 
 Consider a piece written in the key of D-major.  It can be
 transposed up to E-major; note that the key signature is
@@ -555,7 +572,7 @@ key signature will be printed.
 
 @code{\transpose} distinguishes between enharmonic pitches: both
 @code{\transpose c cis} or @code{\transpose c des} will transpose
-up half a tone.  The first version will print sharps and the notes
+up a semitone.  The first version will print sharps and the notes
 will remain on the same scale step, the second version will print
 flats on the scale step above.
 
@@ -575,8 +592,8 @@ show how to enter pitches in C (or @notation{concert pitch}) and
 typeset them for a transposing instrument, but the opposite is
 also possible if you for example have a set of instrumental parts
 and want to print a conductor's score.  For example, when entering
-music for a B-flat trumpet which begins on a notated E (concert
-D), one would write:
+music for a B-flat trumpet that begins on a notated E (concert D),
+one would write:
 
 @example
 musicInBflat = @{ e4 @dots{} @}
@@ -611,12 +628,17 @@ Snippets: @lsrdir{Pitches,Pitches}.
 
 Internals Reference: @internalsref{TransposedMusic}.
 
+@funindex \transpose
+@funindex \chordmode
+@funindex \relative
+
 @refbugs
 
-If you want to use both @code{\transpose} and @code{\relative},
-you must put @code{\transpose} outside of @code{\relative}, since
-@code{\relative} will have no effect on music that appears inside
-a @code{\transpose}.
+
+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}.
 
 
 @node Displaying pitches
@@ -638,7 +660,6 @@ This section discusses how to alter the output of pitches.
 @subsubsection Clef
 
 @funindex \clef
-
 @cindex G clef
 @cindex C clef
 @cindex F clef
@@ -653,8 +674,26 @@ This section discusses how to alter the output of pitches.
 @cindex baritone clef
 @cindex varbaritone clef
 @cindex subbass clef
-
-The clef is set with the @code{\clef} @var{clefname} command:
+@cindex clef
+@cindex ancient clef
+@cindex clef, ancient
+@cindex clef, G
+@cindex clef, C
+@cindex clef, F
+@cindex clef, treble
+@cindex clef, violin 
+@cindex clef, alto 
+@cindex clef, tenor
+@cindex clef, bass 
+@cindex clef, french 
+@cindex clef, soprano 
+@cindex clef, mezzosoprano 
+@cindex clef, baritone 
+@cindex clef, varbaritone 
+@cindex subbass clef, subbass 
+
+The clef is set with the @code{\clef} @var{clefname} command.
+Middle C is shown in every example.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \clef treble
@@ -667,49 +706,48 @@ c2 c
 c2 c
 @end lilypond
 
-Supported clefs include:
-
-@multitable @columnfractions .4 .6
-@headitem Clef @tab Position
-@item @code{treble, violin, G, G2} @tab
-G clef, g' is on 2nd line
-@item @code{alto, C} @tab
-C clef, c' is on 3rd line
-@item @code{tenor} @tab
-C clef, c' is on 4th line
-@item @code{bass, F} @tab
-F clef, f is on 4th line
-@item @code{french} @tab
-G clef, g' is on 1st line, so-called French violin clef
-@item @code{soprano} @tab
-C clef, c' is on 1st line
-@item @code{mezzosoprano} @tab
-C clef, c' is on 2nd line
-@item @code{baritone} @tab
-C clef, c' is on 5th line
-@item @code{varbaritone} @tab
-F clef, f is on 3rd line
-@item @code{subbass} @tab
-F clef, f is on 5th line
-@item @code{percussion} @tab
-percussion clef
-@item @code{tab} @tab
-tablature clef
-@end multitable
+Other clefs include:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+\clef french
+c2 c
+\clef soprano
+c2 c
+\clef mezzosoprano
+c2 c
+\clef baritone
+c2 c
+
+\break
+
+\clef varbaritone
+c2 c
+\clef subbass
+c2 c
+\clef percussion
+c2 c
+\clef tab
+c2 c
+@end lilypond
 
 Further supported clefs are described under @ref{Ancient clefs}.
 
+@cindex transposing clefs
+@cindex clef, transposing
+@cindex octave transposition
+
 By adding @code{_8} or @code{^8} to the clef name, the clef is
 transposed one octave down or up, respectively, and @code{_15} and
 @code{^15} transposes by two octaves.  The argument @var{clefname}
 must be enclosed in quotes when it contains underscores or digits.
-For example,
 
 @cindex choral tenor clef
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-\clef "treble_8" c1
-\clef "bass^15" c1
+\clef "treble_8"
+c2 c
+\clef "bass^15"
+c2 c
 @end lilypond
 
 
@@ -750,7 +788,6 @@ is done with the @code{\key} command:
 \key @var{pitch} @var{mode}
 @end example
 
-@funindex \minor
 @funindex \major
 @funindex \minor
 @funindex \ionian
@@ -761,13 +798,14 @@ is done with the @code{\key} command:
 @funindex \phrygian
 @funindex \dorian
 @cindex church modes
+@cindex modes
 
 Here, @var{mode} should be @code{\major} or @code{\minor} to get a
 key signature of @var{pitch}-major or @var{pitch}-minor,
 respectively.  You may also use the standard mode names, also
-called @q{church modes}: @code{\ionian}, @code{\locrian},
-@code{\aeolian}, @code{\mixolydian}, @code{\lydian},
-@code{\phrygian}, and @code{\dorian}.
+called @q{church modes}: @code{\ionian}, @code{\dorian},
+@code{\phrygian}, @code{\lydian}, @code{\mixolydian},
+@code{\aeolian}, and @code{\locrian}.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \key g \major
@@ -830,7 +868,7 @@ The @code{set-octavation} function also takes -1 (for 8va bassa),
 
 @seealso
 
-Music Glossary: @rglos{ottava}.
+Music Glossary: @rglos{octavation}.
 
 Snippets: @lsrdir{Pitches,Pitches}.
 
@@ -843,6 +881,9 @@ Internals Reference: @internalsref{OttavaBracket}.
 
 @cindex transposition, MIDI
 @cindex transposition, instrument
+@cindex transposing instrument
+@cindex MIDI
+@funindex \transposition
 
 When typesetting scores that involve transposing instruments, some
 parts can be typeset in a different pitch than the
@@ -859,7 +900,7 @@ other voices}.
 The pitch to use for @code{\transposition} should correspond to
 the real sound heard when a@tie{}@code{c'} written on the staff is
 played by the transposing instrument.  This pitch is entered in
-absolute mode, so an instrument which produces a real sound which
+absolute mode, so an instrument that produces a real sound which
 is one tone higher than the printed music should use
 @code{\transposition d'}.  @code{\transposition} should
 @emph{only} be used if the pitches are @emph{not} being entered in
@@ -917,8 +958,7 @@ c2 g
 
 @seealso
 
-Music Glossary: @rglos{concert pitch},
-@rglos{transposing instrument}.
+Music Glossary: @rglos{concert pitch}, @rglos{transposing instrument}.
 
 Notation Reference: @ref{Quoting other voices}, @ref{Transpose}.
 
@@ -927,12 +967,17 @@ Snippets: @lsrdir{Pitches,Pitches}.
 
 @node Automatic accidentals
 @subsubsection Automatic accidentals
-@cindex automatic accidentals
 
+@cindex automatic accidentals
+@cindex accidentals, automatic
+@cindex accidentals
+@cindex accidental style
+@cindex default accidental style
+@cindex accidental style, default
 @funindex set-accidental-style
 
 There are many different conventions on how to typeset
-accidentals.  LilyPond provides a function to specify which such
+accidentals.  LilyPond provides a function to specify which
 accidental style to use.  This function is called as follows
 
 @example
@@ -945,7 +990,7 @@ accidental style to use.  This function is called as follows
 The accidental style applies to the current @code{Staff} by
 default (with the exception of the styles @code{piano} and
 @code{piano-cautionary}, which are explained below).  Optionally,
-the function can take a second argument which determines in which
+the function can take a second argument that 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
 
@@ -1142,11 +1187,13 @@ musicB = {
 @end lilypond
 
 @item modern
+@cindex accidentals, modern style
+@cindex modern style accidentals
 @funindex modern style accidentals
 
 This rule corresponds to the common practice in the twentieth
 century.  It prints the same accidentals as @code{default}, with
-two exceptions which serve to avoid ambiguity: after temporary
+two exceptions 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
@@ -1200,6 +1247,11 @@ musicB = {
 @end lilypond
 
 @item modern-cautionary
+@cindex accidentals, modern cautionary style
+@cindex modern style accidentals
+@cindex modern style cautionary accidentals
+@cindex modern accidental style
+@cindex modern cautionary accidental style
 @funindex modern-cautionary
 
 This rule is similar to @code{modern}, but the @q{extra}
@@ -1257,6 +1309,10 @@ musicB = {
 @end lilypond
 
 @item modern-voice
+@cindex accidentals, multivoice
+@cindex accidentals, modern
+@cindex modern accidentals
+@cindex multivoice accidentals
 @funindex modern-voice
 
 This rule is used for multivoice accidentals to be read both by
@@ -1625,7 +1681,7 @@ 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.  Accidentals are only
+represent the lowest and highest pitches.  Accidentals are only
 printed if they are not part of the key signature.
 
 @lilypond[verbatim,quote,ragged-right]
@@ -1698,7 +1754,7 @@ e d <c f\harmonic> <d a'\harmonic>
 @end lilypond
 
 @noindent
-To see all note head styles, please see @ref{Note head styles}.
+To see all note head styles, see @ref{Note head styles}.
 
 
 @seealso