X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpitches.itely;h=05d1bfc65101db6972fffbe33d4dd5c62ad79bba;hb=59b91873be1615ddbeb800632afad2b538686de9;hp=35ea806585be520de6c57f63ae2b88123602ca72;hpb=f643c5aab8d4567b1e54c88c14f46a42cccec334;p=lilypond.git

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index 35ea806585..05d1bfc651 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -1,4 +1,10 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
 
 
 @node Pitches
@@ -6,6 +12,9 @@
 
 This section discusses how to specify the pitch of notes.
 
+@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
+{pitches-headword.ly}
+
 @menu
 * Writing pitches::             
 * Changing multiple pitches::   
@@ -16,32 +25,41 @@ This section discusses how to specify the pitch of notes.
 @node Writing pitches
 @subsection Writing pitches
 
-Into text.
+Intro text.
 
 @menu
-* Normal pitches::              
+* Absolute octave entry::       
+* Relative octave entry::       
 * Accidentals::                 
-* Cautionary accidentals::      
-* Micro tones::                 
 * Note names in other languages::  
 @end menu
 
 
-@node Normal pitches
-@unnumberedsubsubsec Normal pitches
+@node Absolute octave entry
+@unnumberedsubsubsec Absolute octave entry
 
 @cindex Pitch names
 @cindex pitches
 
-A pitch name is specified using lowercase letters @code{a} through @code{g}.
-An ascending C-major scale is engraved with
+A pitch name is specified using lowercase letters @code{a} through
+@code{g}.  An ascending C-major scale is engraved with
 
 @lilypond[quote,fragment,verbatim,ragged-right]
 \clef bass
 c d e f g a b c'
 @end lilypond
 
-The note name @code{c} is engraved one octave below middle C.
+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 certain
+octave.  The note names @code{c} to @code{b} are engraved in the
+octave below middle C, as in the previous example.
 
 @lilypond[quote,fragment,verbatim,ragged-right]
 \clef treble
@@ -53,10 +71,11 @@ c1
 @funindex '
 @funindex ,
 
-The optional octave specification takes the form of a series of
-single quote (@samp{'}) characters or a series of comma
-(@samp{,}) characters.  Each @samp{'} raises the pitch by one
-octave; each @samp{,} lowers the pitch by an octave.
+If a note should be in another octave than this, an octave
+specification must be given.  It takes the form of a series of
+single quote (@samp{'}) or comma (@samp{,}) characters.  Each
+@samp{'} raises the pitch by one octave; each @samp{,} lowers the
+pitch by an octave.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 \clef treble
@@ -65,10 +84,126 @@ c' c'' e' g d'' d' d c
 c, c,, e, g d,, d, d c
 @end lilypond
 
-An alternate method may be used to declare which octave to
-engrave a pitch; this method does not require as many
-octave specifications (@code{'} and @code{,}).  See
-@ref{Relative octaves}.
+
+@node Relative octave entry
+@unnumberedsubsubsec Relative octaves entry
+
+@cindex Relative
+@cindex Relative octave specification
+@funindex \relative
+
+The absolute mode requires a lot of octave specifications, which
+not only becomes tedious but also easily leads to errors.
+Therefore, it is usually more convenient to let notes be entered
+relative to the previous note.  This is done with the relative
+mode.  
+
+@example
+\relative @var{startpitch} @var{musicexpr}
+@end example
+
+In relative mode, each note is assumed to be as close to the
+previous note as possible.  This means that the octave of notes
+that appear in @var{musicexpr} are calculated as follows:
+
+@itemize
+@item 
+The pitch of the first note is relative to @code{\relative
+@var{startpitch} }.  
+
+@item
+If no octave changing marks are used, the basic interval between a
+note and the one that precedes it is always taken to be a fourth
+or less.
+
+@item
+This distance is determined without regarding alterations or the
+actual sounding pitches; a @code{fisis} following a @code{ceses}
+will be put above the @code{ceses}.  In other words, a
+doubly-augmented fourth is considered a smaller interval than a
+diminished fifth, even though the doubly-augmented fourth spans
+seven semitones while the diminished fifth only spans six
+semitones.
+
+@item
+The octave changing marks @code{'} and @code{,} can be added to
+raise or lower the pitch by an extra octave from the basic
+interval.
+
+@item
+Multiple octave changing marks can be used.  @code{''} will raise
+the pitch by two octaves.
+
+@end itemize 
+
+Here is the relative mode shown in action:
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+\relative c'' {
+  b c d c b c bes a
+}
+@end lilypond
+
+Octave changing marks are used for intervals greater than a
+fourth:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c'' {
+  c g c f, c' a, e''
+}
+@end lilypond
+
+A note sequence without a single octave mark can nevertheless span
+large intervals:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c {
+  c f b e a d g
+}
+@end lilypond
+
+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:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' {
+  c <c e g>
+  <c' e g>
+  <c, e' g> c
+}
+@end lilypond
+
+The @var{startpitch} (after @code{\relative}) is a note name in
+absolute mode.  In principle it can be any note name, but common
+practice is to use @code{c} in various octave positions. 
+
+When octaves are specified as above by adding @code{'} and
+@code{,} to pitch names, it is easy to accidentally put a pitch in
+the wrong octave.  The relative octave mode prevents 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; in relative mode, a single error puts the rest
+of the piece off by one octave.
+
+@seealso
+
+Snippets: @lsrdir{pitch}
+
+
+@refbugs
+
+The relative conversion will not affect @code{\transpose},
+@code{\chordmode} or @code{\relative} sections in its argument.
+To use relative within transposed music, an additional
+@code{\relative} must be placed inside @code{\transpose}.
+
+@c DEPRECATED
+If no @var{startpitch} is specified for @code{\relative}, then
+@code{c'} is assumed.  However, this is a deprecated option and
+may disappear in future versions, so its use is discouraged.
+
+
 
 
 @node Accidentals
@@ -77,9 +212,16 @@ octave specifications (@code{'} and @code{,}).  See
 @cindex note names, Dutch
 @cindex note names, default
 
-A sharp is formed by adding @code{-is} to the end of a pitch name and
-a flat is formed by adding @code{-es}.  Double sharps and double flats
-are obtained by adding @code{-isis} or @code{-eses} to a note name.
+@c following paragraph changed to match Tutorial and Accidental
+@c and Key Signature pages.  
+
+A @rglos{sharp} pitch is made by adding @samp{is} to the name, and
+a @rglos{flat} pitch by adding @samp{es}.  As you might expect,
+a @rglos{double sharp} or @rglos{double flat} is made by adding
+@samp{isis} or @samp{eses}.  This syntax derived from note naming
+conventions in Nordic and Germanic languages, like German and
+Dutch.  To use other names for accidentals, see @ref{Note names
+in other languages}.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 a2 ais a aes
@@ -87,27 +229,28 @@ 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
+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:
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 a2 as e es
 @end lilypond
 
-A natural will cancel the effect of an accidental or key signature.
-However, naturals are not encoded into the note name syntax with a
-suffix; a natural pitch is shown as a simple note name
+A natural will cancel the effect of an accidental or key
+signature.  However, naturals are not encoded into the note name
+syntax with a suffix; a natural pitch is shown as a simple note
+name:
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 a4 aes a2
 @end lilypond
 
 The input @code{d e f} is interpreted as @q{print a D-natural,
-E-natural, and an F-natural,} regardless of the key
-signature.  For more information about the distinction between
-musical content and the presentation of that content, see
-@rlearning{Accidentals and key signatures}.
+E-natural, and an F-natural,} regardless of the key signature.
+For more information about the distinction between musical content
+and the presentation of that content, see @rlearning{Accidentals
+and key signatures}.
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative]
 \key d \major
@@ -116,28 +259,6 @@ d e fis g
 @end lilypond
 
 
-@commonprop
-
-In accordance with standard typesetting rules, a natural sign is printed
-before a sharp or flat if a previous accidental needs to be
-cancelled.  To change this behavior, use
-@code{\set Staff.extraNatural = ##f}
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-ceses4 ces cis c
-\set Staff.extraNatural = ##f
-ceses4 ces cis c
-@end lilypond
-
-
-@seealso
-
-Program reference: @internalsref{LedgerLineSpanner},
-@internalsref{NoteHead}.
-
-
-@node Cautionary accidentals
-@unnumberedsubsubsec Cautionary accidentals
 
 @cindex accidental, reminder
 @cindex accidental, cautionary
@@ -149,32 +270,23 @@ Program reference: @internalsref{LedgerLineSpanner},
 @funindex !
 
 Normally accidentals are printed automatically, but you may also
-print them manually.  A reminder accidental
-can be forced by adding an exclamation mark @code{!}
-after the pitch.  A cautionary accidental
-(i.e., an accidental within parentheses) can be obtained by adding the
-question mark @samp{?} after the pitch.  These extra accidentals
-can be used to produce natural signs, too.
+print them manually.  A reminder accidental can be forced by
+adding an exclamation mark @code{!} after the pitch.  A cautionary
+accidental (i.e., an accidental within parentheses) can be
+obtained by adding the question mark @samp{?} after the pitch.
+These extra accidentals can be used to produce natural signs, too.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 cis cis cis! cis? c c? c! c
 @end lilypond
 
 
-@seealso
-
-The automatic production of accidentals can be tuned in many
-ways.  For more information, see @ref{Automatic accidentals}.
-
-
-@node Micro tones
-@unnumberedsubsubsec Micro tones
-
 @cindex quarter tones
 @cindex semi-flats, semi-sharps
 
 Half-flats and half-sharps are formed by adding @code{-eh} and
-@code{-ih}; the following is a series of Cs with increasing pitches
+@code{-ih}; the following is a series of Cs with increasing
+pitches
 
 @lilypond[verbatim,ragged-right,quote,relative=2,fragment]
 \set Staff.extraNatural = ##f
@@ -184,6 +296,34 @@ ceseh ceh cih cisih
 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 cancelled.  To change this behavior, use @code{\set
+Staff.extraNatural = ##f}
+
+@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+ceses4 ces cis c
+\set Staff.extraNatural = ##f
+ceses4 ces cis c
+@end lilypond
+
+
+@seealso
+
+The automatic production of accidentals can be tuned in many ways
+concerning for how long an accidental is considered to last.  For
+more information, see @ref{Automatic accidentals}.
+
+For @emph{musica ficta}, editorial accidentals placed above the
+staff commonly used in editions of early music, see @ref{Musica
+ficta accidentals}.
+
+Program reference: @internalsref{LedgerLineSpanner},
+@internalsref{NoteHead}.
+
+
 @refbugs
 
 There are no generally accepted standards for denoting
@@ -191,154 +331,112 @@ three-quarter flats, so LilyPond's symbol does not conform to any
 standard.
 
 
+
 @node Note names in other languages
 @unnumberedsubsubsec 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
+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:
 
-@c  Should this be made into a multitable?
 @cindex note names, other languages
+
 @example
-                        Note Names               sharp       flat     double        double
-                                                                       sharp        flat
-
-nederlands.ly  c   d   e   f   g   a   bes b   -is         -es       -isis         -eses
-english.ly     c   d   e   f   g   a   bf  b   -s/-sharp   -f/-flat  -ss/-x/       -ff/
-                                                                     -sharpsharp   -flatflat
-deutsch.ly     c   d   e   f   g   a   b   h   -is         -es       -isis         -eses
-norsk.ly       c   d   e   f   g   a   b   h   -iss/-is    -ess/-es  -ississ/-isis -essess/-eses
-svenska.ly     c   d   e   f   g   a   b   h   -iss        -ess      -ississ       -essess
-italiano.ly    do  re  mi  fa  sol la  sib si  -d          -b        -dd           -bb
-catalan.ly     do  re  mi  fa  sol la  sib si  -d/-s       -b        -dd/-ss       -bb
-espanol.ly     do  re  mi  fa  sol la  sib si  -s          -b        -ss           -bb
+@multitable @columnfractions .2 .6 .05 .05 .05 .05
+@headitem Language
+  @tab Note names
+  @tab sharp @tab flat @tab double sharp @tab double flat
+@item netherlands.ly
+  @tab c d e f g a bes b
+  @tab -is @tab -es @tab -isis @tab -eses
+@item english.ly
+  @tab c d e f g a bf b 
+  @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
+    @tab -ff/-flatflat
+@item deutsch.ly
+  @tab c d e f g a b h 
+  @tab -is @tab -es @tab -isis @tab -eses
+@item norsk.ly
+  @tab c d e f g a b h 
+  @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
+    @tab -essess/-eses
+@item svenska.ly
+  @tab c d e f g a b h 
+  @tab -iss @tab -ess @tab -ississ @tab -essess
+@item italiano.ly
+  @tab do re mi fa sol la sib si 
+  @tab -d @tab -b @tab -dd @tab -bb
+@item catalan.ly
+  @tab do re mi fa sol la sib si 
+  @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
+@item espanol.ly
+  @tab do re mi fa sol la sib si 
+  @tab -s @tab -b @tab -ss @tab -bb
+@end multitable
 @end example
 
 @noindent
 Note that in Dutch, German, Norwegian, and Swedish, the flat
-alterations of @samp{a} like for example @code{aes} and @code{aeses}
-are usually contracted to @code{as} and @code{ases} (or more commonly
-@code{asas}). Sometimes only these contracted names are defined in the
-corresponding language files (this also applies to the suffixes for
-quartertones below).
+alterations of @samp{a} like for example @code{aes} and
+@code{aeses} are usually contracted to @code{as} and @code{ases}
+(or more commonly @code{asas}).  Sometimes only these contracted
+names are defined in the corresponding language files (this also
+applies to the suffixes for quartertones below).
 
 @noindent
 Some music uses microtones whose alterations are fractions of a
-@q{regular} sharp or flat. The note names for quartertones defined in
-the various language files are listed in the following table. Here the
-prefixes @q{semi-} and @q{sesqui-} mean @q{half} and @q{one and a
-half}, respectively. For Norwegian, Swedish, Catalan and Spanish no
-special names have been defined yet.
+@q{regular} sharp or flat.  The note names for quartertones
+defined in the various language files are listed in the following
+table.  Here the prefixes @q{semi-} and @q{sesqui-} mean @q{half}
+and @q{one and a half}, respectively.  For Norwegian, Swedish,
+Catalan and Spanish no 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 lilypond's source code 
 @c is actually misleading since the alteration is in fact one and a half
-@c of a regular sharp/flat. Whence the naming "sesqui-sharp/-flat" used below.
+@c of a regular sharp/flat.  Whence the naming "sesqui-sharp/-flat" used below.
 
 @example
-                        Note Names             semi-   semi-  sesqui-  sesqui-
-                                               sharp   flat    sharp    flat
-
-nederlands.ly  c   d   e   f   g   a   bes b   -ih     -eh    -isih    -eseh
-english.ly     c   d   e   f   g   a   bf  b   -qs     -qf    -tqs     -tqf
-deutsch.ly     c   d   e   f   g   a   b   h   -ih     -eh    -isih    -eseh
-norsk.ly       c   d   e   f   g   a   b   h   
-svenska.ly     c   d   e   f   g   a   b   h   
-italiano.ly    do  re  mi  fa  sol la  sib si  -sd     -sb    -dsd     -bsb
-catalan.ly     do  re  mi  fa  sol la  sib si  
-espanol.ly     do  re  mi  fa  sol la  sib si  
+@multitable @columnfractions .2 .6 .05 .05 .05 .05
+@headitem Language
+  @tab Note names
+  @tab semi- @tab semi- @tab sesqui- @tab sesqui-
+
+@item nederlands.ly
+  @tab c d e f g a bes b 
+  @tab -ih @tab -eh @tab -isih @tab -eseh
+@item english.ly
+  @tab c d e f g a bf b 
+  @tab -qs @tab -qf @tab -tqs @tab -tqf
+@item deutsch.ly
+  @tab c d e f g a b h 
+  @tab -ih @tab -eh @tab -isih @tab -eseh
+@c @item norsk.ly
+@c   @tab c d e f g a b h 
+@c @item svenska.ly
+@c   @tab c d e f g a b h 
+@item italiano.ly
+  @tab do re mi fa sol la sib si 
+  @tab -sd @tab -sb @tab -dsd @tab -bsb
+@c @item catalan.ly 
+@c   @tab do re mi fa sol la sib si 
+@c @item  espanol.ly 
+@c   @tab do re mi fa sol la sib si 
+@end multitable
 @end example
 
-
 @node Changing multiple pitches
 @subsection Changing multiple pitches
 
 @menu
-* Relative octaves::            
 * Octave check::                
 * Transpose::                   
 @end menu
 
-@node Relative octaves
-@unnumberedsubsubsec Relative octaves
-
-@cindex Relative
-@cindex Relative octave specification
-@funindex \relative
-
-Octaves are specified by adding @code{'} and @code{,} to pitch names.
-When you copy existing music, it is easy to accidentally put a pitch
-in the wrong octave and hard to find such an error.  The relative
-octave mode prevents these errors by making the mistakes much
-larger: a single error puts the rest of the piece off by one octave
-
-@example
-\relative @var{startpitch} @var{musicexpr}
-@end example
-
-@noindent
-or
-
-@example
-\relative @var{musicexpr}
-@end example
-
-@noindent
-@code{c'} is used as the default if no starting pitch is defined.
-
-The octave of notes that appear in @var{musicexpr} are calculated as
-follows: if no octave changing marks are used, the basic interval
-between this and the last note is always taken to be a fourth or
-less.  This distance is determined without regarding alterations; a
-@code{fisis} following a @code{ceses} will be put above the
-@code{ceses}.  In other words, a doubly-augmented fourth is considered
-a smaller interval than a diminished fifth, even though the
-doubly-augmented fourth spans seven semitones while the diminished
-fifth only spans six semitones.
-
-The octave changing marks @code{'} and @code{,} can be added to raise
-or lower the pitch by an extra octave.  Upon entering relative mode,
-an absolute starting pitch can be specified that will act as the
-predecessor of the first note of @var{musicexpr}.  If no starting pitch
-is specified, then middle C is used as a start.
-
-Here is the relative mode shown in action
-@lilypond[quote,fragment,ragged-right,verbatim]
-\relative c'' {
-  b c d c b c bes a
-}
-@end lilypond
-
-Octave changing marks are used for intervals greater than a fourth
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c'' {
-  c g c f, c' a, e''
-}
-@end lilypond
-
-If the preceding item is a chord, the first note of the chord is used
-to determine the first note of the next chord
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c' {
-  c <c e g>
-  <c' e g>
-  <c, e' g>
-}
-@end lilypond
-
-The pitch after @code{\relative} contains a note name.
-
-The relative conversion will not affect @code{\transpose},
-@code{\chordmode} or @code{\relative} sections in its argument.  To use
-relative within transposed music, an additional @code{\relative} must
-be placed inside @code{\transpose}.
-
-
 @node Octave check
 @unnumberedsubsubsec Octave check
 
@@ -353,29 +451,31 @@ octave should be.  In the following example,
 @end example
 
 @noindent
-the @code{d} will generate a warning, because a @code{d''} is expected
-(because @code{b'} to @code{d''} is only a third), but a @code{d'} is
-found.  In the output, the octave is corrected to be a @code{d''} and
-the next note is calculated relative to @code{d''} instead of @code{d'}.
+the @code{d} will generate a warning, because a @code{d''} is
+expected (because @code{b'} to @code{d''} is only a third), but a
+@code{d'} is found.  In the output, the octave is corrected to be
+a @code{d''} and the next note is calculated relative to
+@code{d''} instead of @code{d'}.
 
-There is also an octave check that produces no visible output.  The syntax
+There is also an octave check that produces no visible output.
+The syntax
 
 @example
 \octave @var{pitch}
 @end example
 
-This checks that @var{pitch} (without quotes) yields @var{pitch} (with
-quotes) in @code{\relative} mode compared to the note given in the
-@code{\relative} command.  If not, a warning is printed, and the
-octave is corrected.  The @var{pitch} is not printed as a note.
+This checks that @var{pitch} (without quotes) yields @var{pitch}
+(with quotes) in @code{\relative} mode compared to the note given
+in the @code{\relative} command.  If not, a warning is printed,
+and the octave is corrected.  The @var{pitch} is not printed as a
+note.
 
-In the example below, the first check passes without incident, since
-the @code{e} (in @code{relative} mode) is within a fifth of
-@code{a'}.  However,
-the second check produces a warning, since the @code{e} is not within
-a fifth of @code{b'}.  The warning message is printed, and the octave
-is adjusted so that the following notes are in the correct octave
-once again.
+In the example below, the first check passes without incident,
+since the @code{e} (in @code{relative} mode) is within a fifth of
+@code{a'}.  However, the second check produces a warning, since
+the @code{e} is not within a fifth of @code{b'}.  The warning
+message is printed, and the octave is adjusted so that the
+following notes are in the correct octave once again.
 
 @example
 \relative c' @{
@@ -387,10 +487,10 @@ once again.
 
 
 The octave of a note following an octave check is determined with
-respect to the note preceding it.  In the next fragment, the last note
-is an @code{a'}, above middle C.  That means that the @code{\octave}
-check passes successfully, so the check could be deleted without changing
-the output of the piece.
+respect to the note preceding it.  In the next fragment, the last
+note is an @code{a'}, above middle C.  That means that the
+@code{\octave} check passes successfully, so the check could be
+deleted without changing the output of the piece.
 
 @lilypond[quote,ragged-right,verbatim,fragment]
 \relative c' {
@@ -410,35 +510,34 @@ the output of the piece.
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
+
 @example
 \transpose @var{from} @var{to} @var{musicexpr}
 @end example
 
-This means that @var{musicexpr} is transposed by the interval between
-the pitches @var{from} and @var{to}: any note with pitch @code{from}
-is changed to @code{to}.
+This means that @var{musicexpr} is transposed by the interval
+between the pitches @var{from} and @var{to}: any note with pitch
+@code{from} is changed to @code{to} and any other note is
+transposed by the same interval.
+
+Consider a piece written in the key of D-major.  If this piece is
+a little too low for its performer, it can be transposed up to
+E-major with
 
-For example, consider a piece written in the key of D-major.  If
-this piece is a little too low for its performer, it can be
-transposed up to E-major with
 @example
 \transpose d e @dots{}
 @end example
 
-Consider a part written for violin (a C instrument).  If
-this part is to be played on the A clarinet (for which an
-A is notated as a C, and which sounds a minor third lower
-than notated), the following
-transposition will produce the appropriate part
+Consider a part written for violin (a C instrument).  If this part
+is to be played on the A clarinet (for which an A is notated as a
+C, and which sounds a minor third lower than notated), the
+following transposition will produce the appropriate part:
 
 @example
 \transpose a c @dots{}
 @end example
 
-@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 second
-version will print flats
+@code{\transpose} will also transpose key signatures:
 
 @lilypond[quote,ragged-right,verbatim]
 mus = { \key d \major cis d fis g }
@@ -450,19 +549,35 @@ mus = { \key d \major cis d fis g }
 }
 @end lilypond
 
+@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
+will remain on the same scale step, the second version will print
+flats on the scale step above.
+
+@lilypond[quote,ragged-right,verbatim]
+mus = { c d e f }
+\new Staff {
+  \transpose c cis { \relative c' \mus }
+  \transpose c des { \relative c' \mus }
+}
+@end lilypond
+
+
+
 @code{\transpose} may also be used to input written notes for a
-transposing instrument.  Pitches are normally entered into LilyPond
-in C (or @q{concert pitch}), but they may be entered in another
-key.  For example, when entering music for a B-flat trumpet which
-begins on concert D, one would write
+transposing instrument.  Pitches are normally entered into
+LilyPond in C (or @notation{concert pitch}), but they may be
+entered in another key.  For example, when entering music for a
+B-flat trumpet which begins on concert D, one would write
 
 @example
 \transpose c bes @{ e4 @dots{} @}
 @end example
 
-To print this music in B-flat again (i.e., producing a trumpet part,
-instead of a concert pitch conductor's score) you would wrap the
-existing music with another @code{transpose}
+To print this music in B-flat again (i.e., producing a trumpet
+part, instead of a concert pitch conductor's score) you would wrap
+the existing music with another @code{transpose}
 
 @example
 \transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
@@ -473,15 +588,16 @@ existing music with another @code{transpose}
 
 Program reference: @internalsref{TransposedMusic}.
 
-Example: @lsr{scheme,transpose-pitches-with-minimum-accidentals.ly}.
+Example:
+@lsr{scheme,transpose-pitches-with-minimum-accidentals.ly}.
 
 
 @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}.
+@code{\relative} will have no effect on music that appears inside
+a @code{\transpose}.
 
 
 @node Displaying pitches
@@ -499,13 +615,9 @@ you must put @code{\transpose} outside of @code{\relative}, since
 
 @funindex \clef
 
-The clef indicates which lines of the staff correspond to which
-pitches.  The clef is set with the @code{\clef} command
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-{ c''2 \clef alto g'2 }
-@end lilypond
-
+@cindex G clef
+@cindex C clef
+@cindex F clef
 @cindex treble clef
 @cindex violin clef
 @cindex alto clef
@@ -518,56 +630,154 @@ pitches.  The clef is set with the @code{\clef} command
 @cindex varbaritone clef
 @cindex subbass clef
 
+The clef is set with the @code{\clef} @var{clefname} 
+command:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+<<
+  \new Staff {
+    % treble clef by default
+    c'1^"middle C"
+  }
+  \new Staff {
+    \clef alto
+    c'1^"middle C"
+  }
+  \new Staff {
+    \clef bass
+    f1^"middle C"
+  }
+>>
+@end lilypond
+
+The clef can also be changed inside the staff:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new PianoStaff <<
+  \new Staff {
+    \time 2/4
+    \clef treble
+    r16
+    \clef bass
+    e g c' e' e g c'
+  }
+  \new Staff {
+    \clef bass
+    c,8 r \clef treble g''4
+  }
+>>
+@end lilypond
+
+These same clef symbols are used in different positions on
+the staff to change the range of notes shown by that staff.
+The treble (alto, bass) clef is always positioned to show
+the line on which a g' (c', f) note is printed.
+ 
 Supported clefs include
 
-@multitable @columnfractions .33 .66
+@multitable @columnfractions .4 .6
 @headitem Clef @tab Position
-@item @code{treble}, violin, G, G2 @tab
-G clef on 2nd line
+@item @code{treble, violin, G, G2} @tab
+G clef (g') on 2nd line
 @item @code{alto, C} @tab
-C clef on 3rd line
+C clef (c') on 3rd line
 @item @code{tenor} @tab
-C clef on 4th line.
+C clef (c') on 4th line.
 @item @code{bass, F} @tab
-F clef on 4th line
+F clef (f) on 4th line
 @item @code{french} @tab
-G clef on 1st line, so-called French violin clef
+G clef (g') on 1st line, so-called French violin clef
 @item @code{soprano} @tab
-C clef on 1st line
+C clef (c') on 1st line
 @item @code{mezzosoprano} @tab
-C clef on 2nd line
+C clef (c') on 2nd line
 @item @code{baritone} @tab
-C clef on 5th line
+C clef (c') on 5th line
 @item @code{varbaritone} @tab
-F clef on 3rd line
+F clef (f) on 3rd line
 @item @code{subbass} @tab
-F clef on 5th line
+F clef (f) on 5th line
 @item @code{percussion} @tab
 percussion clef
 @item @code{tab} @tab
 tablature clef
 @end multitable
 
+Further supported clefs are described under @ref{Ancient clefs}.
+
 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,
+must be enclosed in quotes when it contains underscores or digits.
+For example,
 
 @cindex choral tenor clef
+
 @lilypond[quote,ragged-right,verbatim,fragment,relative=1]
 \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 any of these properties are changed.  The following example shows
-possibilities when setting properties manually.
+@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[quote,ragged-right,verbatim]
+{
+  % 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
+
+and some which do not:
 
 @lilypond[quote,ragged-right,verbatim]
 {
@@ -583,33 +793,29 @@ possibilities when setting properties manually.
   \set Staff.clefOctavation = #0
   \set Staff.clefPosition = #0
   c'4
-  \clef "bass"
-  c'4
   \set Staff.middleCPosition = #4
   c'4
 }
 @end lilypond
 
-
 @seealso
 
-Manual: @ref{Grace notes}.
+User manual: @ref{Ancient clefs}.
 
 Program reference: @internalsref{Clef}.
 
-
 @node Key signature
 @unnumberedsubsubsec Key signature
 
 @cindex Key signature
 @funindex \key
 
-The key signature indicates the tonality in which a piece is played.  It
-is denoted by a set of alterations (flats or sharps) at the start of the
-staff.
+The key signature indicates the tonality in which a piece is
+played.  It is denoted by a set of alterations (flats or sharps)
+at the start of the staff.
 
 Setting or changing the key signature is done with the @code{\key}
-command
+command:
 
 @example
 @code{\key} @var{pitch} @var{type}
@@ -628,19 +834,20 @@ command
 @cindex church modes
 
 Here, @var{type} should be @code{\major} or @code{\minor} to get
-@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}.
-
-This command sets the context property
-@code{Staff.keySignature}.  Non-standard key signatures
-can be specified by setting this property directly.
-
-Accidentals and key signatures often confuse new users, because
-unaltered notes get natural signs depending on the key signature.  For
-more information, see @ref{Accidentals}, or @rlearning{Accidentals
-and key signatures}.
+@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}.  See @rglos{church mode}.
+
+@warning{The relationship between accidentals and key signatures can
+be confusing to new users who think of the note letters as scale
+steps and not as absolute pitches.  The note names that are
+entered in a music expression are the raw material; key signatures
+and clefs decide how this raw material is displayed.  Thus,
+unaltered notes may get natural signs depending on the key
+signature.  For more information, see @ref{Accidentals} and
+@rlearning{Accidentals and key signatures}.}
 
 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 \key g \major
@@ -648,14 +855,13 @@ f1
 fis
 @end lilypond
 
-
 @commonprop
 
-A natural sign is printed to cancel any previous accidentals.  This
-can be suppressed by setting the @code{Staff.printKeyCancellation}
-property.
+A natural sign is printed to cancel any previous accidentals.
+This can be suppressed by setting the
+@code{Staff.printKeyCancellation} property.
 
-@lilypond[quote,fragment,ragged-right,fragment,verbatim,relative=2]
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 \key d \major
 a b cis d
 \key g \minor
@@ -667,22 +873,49 @@ a b cis d
 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
+@code{\set Staff.keySignature} =
+#'((@var{octave} . @var{step}) . @var{alter})
+where @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 ,SHARP ,FLAT ,DOUBLE-SHARP etc. (Note the leading comma.)
+Here is an example of a possible key
+signature for generating a whole-tone scale:
+
+@lilypond[quote,ragged-right,verbatim]
+\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
 
+@c Link to snippet 248
+Another example of using @code{keySignature} can be found in
+@lsrdir{scordatura}
+
 Program reference: @internalsref{KeyCancellation},
-@internalsref{KeySignature}.
+@internalsref{KeySignature}, @internalsref{Key_engraver}
 
 
 @node Ottava brackets
 @unnumberedsubsubsec Ottava brackets
 
-@q{Ottava} brackets introduce an extra transposition of an octave for
-the staff.  They are created by invoking the function
+@q{Ottava} brackets introduce an extra transposition of an octave
+for the staff.  They are created by invoking the function
 @code{set-octavation}
 
 @cindex ottava
 @cindex 15ma
+@cindex 8va
+@cindex 8ve
 @cindex octavation
 
 @lilypond[quote,ragged-right,verbatim,fragment]
@@ -695,10 +928,11 @@ the staff.  They are created by invoking the function
 }
 @end lilypond
 
-The @code{set-octavation} function also takes -1 (for 8va bassa), 2@tie{}(for 15ma),
-and -2 (for 15ma bassa) as arguments.  Internally the function sets the properties
-@code{ottavation} (e.g., to @code{"8va"} or @code{"8vb"}) and
-@code{centralCPosition}.  For overriding the text of the bracket, set
+The @code{set-octavation} function also takes -1 (for 8va bassa),
+2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
+Internally the function sets the properties @code{ottavation}
+(e.g., to @code{"8va"} or @code{"8vb"}) and
+@code{middleCPosition}.  To override the text of the bracket, set
 @code{ottavation} after invoking @code{set-octavation}, i.e.,
 
 @lilypond[quote,ragged-right,verbatim]
@@ -727,27 +961,70 @@ during an octavation bracket.
 @cindex transposition, MIDI
 @cindex transposition, instrument
 
-The key of a transposing instrument can also be specified.  This
-applies to many wind instruments, for example, clarinets (B-flat, A, and
-E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).
+The key of a transposing instrument can be specified.  This
+applies to many wind instruments, for example, clarinets (B-flat,
+A, and E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).
 
-The transposition is entered after the keyword @code{\transposition}
+The transposition is entered with the command
+@code{\transposition} @var{pitch} where @var{pitch} specifies
+the key in which the instrument plays:
 
 @example
 \transposition bes   %% B-flat clarinet
 @end example
 
 @noindent
-This command sets the property @code{instrumentTransposition}.  The value of
-this property is used for MIDI output and quotations.  It does not
-affect how notes are printed in the current staff.  To change the printed
-output, see @ref{Transpose}.
+This command sets the property @code{instrumentTransposition}.
+The value of this property is used for MIDI output and quotations.
+MIDI output is transposed to play at concert pitch, and cue 
+notes and quotations are automatically transposed to the
+key of the instrument in which they are quoted.
+See @ref{Quoting other voices}.
+The value does not affect how notes are printed in the 
+current staff; to change the printed output, see @ref{Transpose}.
+
+The pitch to use for @code{\transposition} should correspond to
+the real sound heard when a @code{c'} written on the staff is
+played by the transposing instrument.  The command 
+@code{\transposition} @var{pitch} should be used when the music
+is entered from an orchestral part written for the instrument.
+For example, in
+classical horn parts, the tuning of the instrument is often
+changed during a piece.  Here are a few notes for a violin 
+and a B-flat clarinet where the parts have been entered 
+using the notes and key as they appear in each part or the 
+conductor's score:
 
-The pitch to use for @code{\transposition} should correspond to the
-real sound heard when a @code{c'} written on the staff is played by the
-transposing instrument.  For example, when entering a score in
-concert pitch, typically all voices are entered in C, so
-they should be entered as
+@lilypond[quote,ragged-right,verbatim]
+\score {
+  \new GrandStaff <<
+    \new Staff = "Violin I" {
+      \set Staff.instrumentName = "Vln"
+      \set Staff.midiInstrument="violin"
+      \key c \major
+      \transposition c
+      g'4( c''8) r c'' r c''4
+    }
+    \new Staff = "Clarinet" {
+      \set Staff.instrumentName = "Cl"
+      \set Staff.midiInstrument="clarinet"
+      \key d \major
+      \transposition bes
+      a'4( d''8) r d'' r d''4
+    }
+  >>
+  \layout { }
+  \midi { }
+}
+@end lilypond
+
+Without the @code{\transposition} command the midi output of this 
+would play the notes a tone apart; with it the notes are played
+correctly in unison.
+
+However, when entering the notes of
+a score in concert pitch, when all voices are entered in C,
+they may be prefaced by (the default) @code{\transposition c'}:
 
 @example
 clarinet = @{
@@ -760,20 +1037,9 @@ saxophone = @{
 @}
 @end example
 
-The command @code{\transposition} should be used when the music is
-entered from a (transposed) orchestral part.  For example, in
-classical horn parts, the tuning of the instrument is often changed
-during a piece.  When copying the notes from the part, use
-@code{\transposition}, e.g.,
-
-@example
-\transposition d'
-c'4^"in D"
-...
-\transposition g'
-c'4^"in G"
-...
-@end example
+@noindent
+to serve as a reminder
+that these parts are written in C.