X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fuser%2Frefman.itely;h=8e3eae139c92cd638f73ee24cd2e2b6828c78f0f;hb=1753b1a73742a5b0893037116bb6f2febba277f3;hp=32f4edf3b91ebc26f63bdb799c1bcc55a8189747;hpb=145376509af3f2caf35122d257d24eb7edcb7092;p=lilypond.git

diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely
index 32f4edf3b9..8e3eae139c 100644
--- a/Documentation/user/refman.itely
+++ b/Documentation/user/refman.itely
@@ -10,6 +10,10 @@
 @node Notation manual
 @chapter Notation manual
 
+This chapter describes all the different types of notation supported
+by LilyPond. It is intended as a reference for users that are already
+somewhat familiar with using LilyPond.
+
 @menu
 * Note entry::                  
 * Easier music entry::          
@@ -18,8 +22,6 @@
 * Beaming::                     
 * Accidentals::                 
 * Expressive marks::            
-* Articulations::               
-* Fingering instructions::      
 * Repeats::                     
 * Rhythmic music::              
 * Piano music::                 
@@ -40,10 +42,9 @@
 @section Note entry
 @cindex Note entry
 
-This chapter describes all the different types of notation supported
-by LilyPond. It is intended as a reference for users that are already
-somewhat familiar with using LilyPond.
-
+The basic elements of any piece of music are the notes. This section
+is about basic notation elements notes, rests and related constructs,
+such as stems, tuplets and ties.
 
 @menu
 * Notes::                       
@@ -102,9 +103,27 @@ 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}.  These
 names are the Dutch note names.  In Dutch, @code{aes} is contracted to
-@code{as} in Dutch, but both forms are accepted. Similarly, both
+@code{as}, but both forms are accepted. Similarly, both
 @code{es} and @code{ees} are accepted.
 
+Half-flats and half-sharps are formed by adding @code{-eh} and
+@code{-ih}; the following is a series of Cs with increasing pitches:
+
+@cindex quarter tones
+@cindex semi-flats, semi-sharps
+
+@lilypond[verbatim,relative 2]
+  ceses4
+  ceseh
+  ces
+  ceh
+  c
+  cih
+  cis 
+  cisih
+  cisis
+@end lilypond  
+
 There are predefined sets of note names for various other languages.
 To use them,  include the language specific init file.  For
 example: @code{\include "english.ly"}.  The available language files
@@ -116,6 +135,7 @@ and the note names they define are:
                         Note Names               sharp       flat
 nederlands.ly  c   d   e   f   g   a   bes b   -is         -es
 english.ly     c   d   e   f   g   a   bf  b   -s/-sharp   -f/-flat
+                                               -x (double)
 deutsch.ly     c   d   e   f   g   a   b   h   -is         -es
 norsk.ly       c   d   e   f   g   a   b   h   -iss/-is    -ess/-es
 svenska.ly     c   d   e   f   g   a   b   h   -iss        -ess
@@ -140,17 +160,6 @@ octave; each @code{,} lowers the pitch by an octave:
 @end lilypond
 
 
-There is also a verbose syntax for pitch specification:
-
-@c TODO: junk this? 
-@cindex @code{\pitch}
-@example
-  \pitch @var{scmpitch}
-@end example
-
-
-where @var{scmpitch} is a Scheme object of the @code{Pitch} type.
-
 @refcommands
 
 Notes can be hidden and unhidden with the following commands:
@@ -164,6 +173,9 @@ Notes can be hidden and unhidden with the following commands:
 @seealso
 
 @noindent
+
+bla
+
 @internalsref{NoteEvent}, and @internalsref{NoteHead}.
 
 @node Chromatic alterations
@@ -247,7 +259,7 @@ other situations, you should use the @code{\skip} command:
 
 @lilypond[singleline,verbatim]
 \score {
-  \context Staff <<
+  \new Staff <<
     { \time 4/8 \skip 2 \time 4/4 } 
     \notes\relative c'' { a2 a1 }
   >>
@@ -268,7 +280,6 @@ produce any output, not even transparent output.
 
 
 @cindex duration
-@cindex @code{\duration}
 
 
 In Note, Chord, and Lyrics mode, durations are designated by numbers
@@ -331,13 +342,6 @@ beats:
    a4
 @end lilypond
 
-Durations can also be produced using the verbose syntax
-@code{\duration @var{Scheme object}}:
-@lilypond[verbatim,fragment]
- c'\duration #(ly:make-duration 4 1)
-@end lilypond
-
-
 
 @refcommands
 
@@ -363,10 +367,9 @@ In dense chords, dots can overlap.
 @node Stems
 @subsection Stems
 
-Whenever a note is found,  a
-@internalsref{Stem} object is created automatically. For whole notes
-and rests, stem objects are also created, but in those cases, the stem
-is invisible.
+Whenever a note is found, a @internalsref{Stem} object is created
+automatically. For whole notes and rests, they are also created but
+made invisible.
 
 @refcommands
 
@@ -432,11 +435,15 @@ ties created for a chord, see @inputfileref{input/test,tie-sparse.ly}.
 @refbugs
 
 Tieing only a subset of the note heads of a pair of chords is not
-supported in a simple way.  It can be achieved by moving the
+supported in a simple way.
+
+@ignore
+It can be achieved by moving the
 tie-engraver into the @internalsref{Thread} context and turning on and
 off ties per @internalsref{Thread}.
+@end ignore
 
-Switching staves when a tie is active, will not produce a slanted tie.
+Switching staves when a tie is active will not produce a slanted tie.
 
 Formatting of ties is a difficult subject. The results are often not
 optimal.
@@ -458,11 +465,12 @@ with a fraction:
   \times @var{fraction} @var{musicexpr}
 @end example
 
-The duration of @var{musicexpr} will be multiplied by the fraction. 
-In the sheet music, the fraction's denominator will be printed over
-the notes, optionally with a bracket.  The most common tuplet is the
-triplet in which 3 notes have the length of 2, so the notes are 2/3
-of their written length:
+@noindent
+The duration of @var{musicexpr} will be multiplied by the fraction.
+The fraction's denominator will be printed over the notes, optionally
+with a bracket.  The most common tuplet is the triplet in which 3
+notes have the length of 2, so the notes are 2/3 of their written
+length:
 
 @lilypond[fragment,verbatim,center]
   g'4 \times 2/3 {c'4 c' c'} d'4 d'4
@@ -546,10 +554,8 @@ correct result.
 @cindex Music entry
 
 When entering music it is easy to introduce errors. This section deals
-with tricks and features of the input language that help when entering
-music, and find and correct mistakes.  Some features of the input
-language ease entering music, but also have other applications. They
-are not described in this section.
+with tricks and features of the input language that were added solely
+to help entering music, and find and correct mistakes.
 
 It is also possible to use external programs, for example GUI
 interfaces, or MIDI transcription programs, to enter or edit
@@ -810,7 +816,7 @@ using @code{\override} or @code{\set}.  At the moment that
 @code{\property Staff} is interpreted, a @internalsref{Staff} context
 is made, and the @internalsref{StaffSymbol} is created before any
 @code{\override} is effective. Properties can be changed in a
-@code{\translator} definition, or by using @code{\outputproperty}.
+@code{\translator} definition, or by using @code{\applyoutput}.
 
 @refbugs
 
@@ -857,6 +863,10 @@ This command sets the context property
 @internalsref{Staff}.@code{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 keysignature.  The
+tutorial explains why this is so in @ref{More about pitches}.
+
 @refbugs
 
 The ordering of a key cancellation is wrong when it is combined with
@@ -922,7 +932,8 @@ G clef on 2nd line
 @end table
 
 By adding @code{_8} or @code{^8} to the clef name, the clef is
-transposed one octave down or up, respectively. Argument @var{clefname} 
+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,
 
@@ -964,9 +975,9 @@ the staff. They are created by invoking the function
 @end lilypond
 
 Internally the @code{set-octavation} function sets the properties
-@code{ottavation} (eg. to @code{"8va"}) and @code{centralCPosition}.
-
-@seealso
+@code{ottavation} (eg. to @code{"8va"}) and
+@code{centralCPosition}. The function also takes arguments -1 (for 8va
+bassa) and 2 (for 15ma).
 
 @internalsref{OttavaSpanner}.
 
@@ -1050,8 +1061,8 @@ Automatic beaming does not use measure grouping specified with
 
 Partial measures, for example in upsteps, are entered using the
 @code{\partial} command:
-@lilypond[fragment,verbatim]
-\partial 16*5  c'16 c4 |   a'2. ~ a'8. a'16 | g'1
+@lilypond[fragment,verbatim,relative 1]
+\partial 16*5  c16 cis d dis e |   a2. c,4 | b2
 @end lilypond
 
 The syntax for this command is 
@@ -1099,6 +1110,7 @@ happen on barlines.
 
  Special types
 of barlines can be forced with the @code{\bar} command:
+@c
 @lilypond[relative=1,fragment,verbatim]
    c4 \bar "|:" c4
 @end lilypond
@@ -1115,6 +1127,12 @@ c4
 \bar ".|." c
 \bar "|." 
 @end lilypond
+For allowing linebreaks, there is a special command,
+@example
+  \bar "empty"
+@end example 
+This will insert an invisible barline, and allow linebreaks at this
+point.
 
 In scores with many staves, a @code{\bar} command in one staff is
 automatically applied to all staves. The resulting bar lines are
@@ -1178,7 +1196,8 @@ small, short-lived voices or for single chords:
 
 @lilypond[verbatim,fragment]
 \context Staff \relative c'' {
- c4 << { f d e  } \\ { b c2 } >> c4 << g' \\ b, \\  f' \\ d >>
+  c4 << { f d e  } \\ { b c2 } >>
+  c4 << g' \\ b, \\  f' \\ d >>
 }
 @end lilypond
 
@@ -1675,12 +1694,9 @@ some of them are typeset as cautionaries.
 @node Customized accidental rules
 @subsection  Customized accidental rules
 
-This section must be considered gurus-only, and hence it must be
-sufficient with a short description of the system and a reference to
-the internal documentation.
-
-The algorithm tries several different rules, and uses the rule
-that gives the highest number of accidentals.  Each rule consists of
+For determining when to print an accidental, several different rules
+are tried.  The rule that gives the highest number of accidentals is
+used.  Each rule consists of
 @table @var
 @item context:
       In which context is the rule applied. For example, if
@@ -1758,6 +1774,11 @@ for the problematic notes.
 @node Expressive marks
 @section Expressive marks
 
+
+@c todo: should change ordering
+@c where to put text spanners, metronome marks,
+@c fingering?
+ 
 @menu
 * Slurs ::                      
 * Phrasing slurs::              
@@ -1765,6 +1786,12 @@ for the problematic notes.
 * Metronome marks::             
 * Text spanners::               
 * Analysis brackets::           
+* Articulations::               
+* Fingering instructions::      
+* Text scripts::                
+* Grace notes::                 
+* Glissando ::                  
+* Dynamics::                    
 @end menu
 
 @node Slurs 
@@ -1776,9 +1803,9 @@ A slur indicates that notes are to be played bound or @emph{legato}.
 @syntax
 
 They are entered using parentheses:
-@lilypond[fragment,verbatim,center]
-  f'( g')( a') a'8[ b'(] a'4 g'2 f'4)
-  <c' e'>2( <b d'>2)
+@lilypond[relative 1,fragment,verbatim,center]
+  f( g)( a) a8 b( a4 g2 f4)
+  <c e>2( <b d>2)
 @end lilypond
 
 
@@ -1892,11 +1919,12 @@ c'4 \breathe d4
 @end lilypond
 
 The glyph of the breath mark can be tweaked by overriding the
-@code{text} property of the @code{BreathingSign} layout object with the name of
-any glyph of @ref{The Feta font}.  For example,
+@code{text} property of the @code{BreathingSign} layout object with
+any markup text.   For example,
 @lilypond[fragment,verbatim,relative]
 c'4
-\property Voice.BreathingSign \override #'text = #"scripts-rvarcomma"
+\property Voice.BreathingSign \override #'text
+ = #(make-musicglyph-markup "scripts-rvarcomma")
 \breathe
 d4
 @end lilypond
@@ -1992,7 +2020,7 @@ To use this, add the @internalsref{Horizontal_bracket_engraver} to
 
 
 @node Articulations
-@section Articulations
+@subsection Articulations
 @cindex Articulations
 
 @cindex articulations
@@ -2075,12 +2103,12 @@ eg.
 
 @refbugs
 
-All of these note ornaments appear in the printed output but have no
+ These note ornaments appear in the printed output but have no
 effect on the MIDI rendering of the music.
 
 
 @node Fingering instructions
-@section Fingering instructions
+@subsection Fingering instructions
 
 @cindex fingering
 
@@ -2104,8 +2132,8 @@ You can use the thumb-script to indicate that a note should be
 played with your thumb (used in cello music):
 
 @lilypond[verbatim, singleline, fragment]
-      <a' a''-3>8(_\thumb[ <b' b''-3>)_\thumb
-      <c'' c'''-3>(_\thumb <d'' d'''-3>)_\thumb]
+      <a' a''-3>8(_\thumb <b' b''-3>)_\thumb
+      <c'' c'''-3>(_\thumb <d'' d'''-3>)_\thumb
 @end lilypond
 
 Fingerings for chords can also be added to individual notes
@@ -2129,13 +2157,6 @@ to note heads:
 @internalsref{FingerEvent}, and @internalsref{Fingering}.
 
 
-@menu
-* Text scripts::                
-* Grace notes::                 
-* Glissando ::                  
-* Dynamics::                    
-@end menu
-
 @node Text scripts
 @subsection Text scripts
 @cindex Text scripts
@@ -2186,16 +2207,18 @@ They are entered with the commands @code{\acciaccatura} and
 
 @lilypond[relative=2,verbatim,fragment]
 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
-\acciaccatura { g16 f } e4
+\acciaccatura { g16[ f] } e4
 @end lilypond
 
 Both are special forms of the @code{\grace} command. By prefixing this
 keyword to a music expression, a new one is formed, which will be
 printed in a smaller font and takes up no logical time in a measure.
 @lilypond[relative=2,verbatim,fragment]
-  c4 \grace c16 c4 \grace {
-  c16[ d16] } c2 c4
+  c4 \grace c16 c4
+  \grace { c16[ d16] } c2 c4
 @end lilypond
+
+@noindent
 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
 @code{\grace} command does not start a slur.
 
@@ -2208,7 +2231,7 @@ example is shown here with timing tuples:
 <<
   \relative c''{ 
   c4  \grace c16  c4  \grace {
-  c16[  d16] } c4
+  c16[  d16] } c2 c4
   }
   \new Lyrics \lyrics {
       \markup { (0,0)  } 4
@@ -2235,8 +2258,8 @@ every eighth grace note:
 
 
 
-If you want to end a note with a grace note, then the standard trick
-is to put the grace notes before a phantom ``space note'', e.g.
+If you want to end a note with a grace, then the standard trick
+is to put the grace notes after a ``space note'', e.g.
 @lilypond[fragment,verbatim, relative=2]
 \context Voice {
     << { d1^\trill ( }
@@ -2254,7 +2277,7 @@ A @code{\grace} section will introduce special typesetting settings,
 for example, to produce smaller type, and set directions. Hence, when
 introducing layout tweaks, they should be inside the grace section,
 for example,
-@lilypond[fragment,verbatim,relative 2]
+@lilypond[fragment,verbatim,relative 1]
 \new Voice {
     \acciaccatura {
       \property Voice.Stem \override #'direction = #-1
@@ -2264,6 +2287,8 @@ for example,
     g4
 }
 @end lilypond
+
+@noindent
 The overrides should also be reverted inside the grace section.
 
 If the layout of grace sections must be changed throughout the music,
@@ -2341,7 +2366,7 @@ a note:
 
 @refbugs
 
-Additional texts (such as @emph{gliss.}) is not supported.
+Adding additional texts (such as @emph{gliss.}) is not supported.
 
 
 @node Dynamics
@@ -2421,7 +2446,7 @@ You can also supply your own texts:
   \context Voice {
     \property Voice.crescendoText = \markup { \italic "cresc. poco" }
     \property Voice.crescendoSpanner = #'dashed-line
-    a'2\mf\< a a a\!
+    a'2\< a a a\!\mf
   }
 @end lilypond
 
@@ -2462,8 +2487,8 @@ must set properties for the @internalsref{DynamicLineSpanner} object.
 
 Repetition is a central concept in music, and multiple notations exist
 for repetitions. In LilyPond, most of these notations can be captured
-in a uniform syntax. One of the advantages is, all these repetitions
-can be rendered in MIDI accurately.
+in a uniform syntax. One of the advantages is that they can be
+rendered in MIDI accurately.
 
 The following types of repetition are supported:
 
@@ -2524,27 +2549,25 @@ give enough alternatives for all of the repeats, then the first
 alternative is assumed to be played more than once.
 
 Normal notation repeats are used like this:
-@lilypond[fragment,verbatim]
-  c'1
-  \repeat volta 2 { c'4 d' e' f' }
-  \repeat volta 2 { f' e' d' c' }
+@lilypond[fragment,verbatim,relative 1]
+  c1
+  \repeat volta 2 { c4 d e f }
+  \repeat volta 2 { f e d c }
 @end lilypond
 
 With alternative endings:
-@lilypond[fragment,verbatim]
-  c'1
-  \repeat volta 2 {c'4 d' e' f'} 
-  \alternative { {d'2 d'} {f' f} }
+@lilypond[fragment,verbatim,relative 1]
+  c1
+  \repeat volta 2 {c4 d e f} 
+  \alternative { {d2 d} {f f,} }
 @end lilypond
 
 
-@lilypond[fragment,verbatim]
+@lilypond[fragment,verbatim,relative 1]
 \context Staff {
-  \relative c' {
     \partial 4
     \repeat volta 4 { e | c2 d2 | e2 f2 | }
     \alternative { { g4 g g } { a | a a a a | b2. } }
-  }
 }
 @end lilypond
 
@@ -2605,12 +2628,12 @@ alphabetic characters. Or,
   stops a running volta bracket:
 @end table
 
-@lilypond[verbatim, fragment]
- c''4
+@lilypond[verbatim, fragment,relative 2]
+ c4
     \property Score.repeatCommands = #'((volta "93") end-repeat)
- c''4 c''4
+ c4 c4
     \property Score.repeatCommands = #'((volta #f))
- c''4 c''4
+ c4 c4
 @end lilypond
 
 
@@ -2756,7 +2779,7 @@ down = \notes { bassdrum4 snare8 bd r bd sn4 }
 
 @end lilypond
 In the above example the music was transformed using the list @code{'drums}.
-Currently the following lists are defined in @file{scm/drums.scm}:
+The following lists are defined in @file{scm/drums.scm}:
 @table @code
 @item 'drums
 to typeset a typical drum kit on a five-line staff:
@@ -3090,7 +3113,7 @@ terminating too soon.
 @refbugs
 
 The staff switches often do not end up in optimal places. For high
-quality output staff switches should be specified manually.
+quality output, staff switches should be specified manually.
 
  
 
@@ -3165,9 +3188,9 @@ c''4\sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4\sostenutoUp
 
 For fine-tuning of the appearance of a pedal bracket, the properties
 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
-@code{PianoPedalBracket} objects (, see the detailed documentation of
-@internalsref{PianoPedalBracket},) can be modified.  For example, the bracket
-may be extended to the end of the note head:
+@code{PianoPedalBracket} objects (see
+@internalsref{PianoPedalBracket} in the Program reference)  can be modified.  For example, the
+bracket may be extended to the end of the note head:
 
 @lilypond[fragment,verbatim]
 \property Staff.PianoPedalBracket \override
@@ -3237,7 +3260,7 @@ arpeggiate the chord. To draw these brackets, set the
 
 @seealso
 
-@internalsref{ArpeggioEvent} expression lead to
+@internalsref{ArpeggioEvent} music expressions lead to
 @internalsref{Arpeggio} objects.  Cross staff arpeggios are
 @internalsref{PianoStaff}.@internalsref{Arpeggio}.
 
@@ -3406,24 +3429,24 @@ more complex orderings, the best way is to setup the hierarchy of
 staves and lyrics first, e.g.
 @example
 \context ChoirStaff \notes <<
-  \new Lyrics @{ s1 @}
-  \new Staff @{ s1 @}
-  \new Lyrics @{ s1 @}
-  \new Staff @{ s1 @}
+  \context Lyrics = sopr @{ s1 @}
+  \context Staff = soprStaff @{ s1 @}
+  \context Lyrics = tenor @{ s1 @}
+  \context Staff = tenorStaff @{ s1 @}
 >>
 @end example
 and then combine the appropriate melodies and lyric lines:
 @example
   \addlyrics
-    \new Staff @emph{the music}
-    \new Lyrics @emph{the lyrics}
+    \context Staff = soprStaff  @emph{the music}
+    \context Lyrics = sopr @emph{the lyrics}
 @end example
 
 putting both together, you would get
 @example
 \context ChoirStaff \notes <<
-  \new Lyrics @dots{}
-  \new Staff @dots{}
+  \context Lyrics = @dots{}
+  \context Staff =  @dots{}
   \addlyrics @dots{}
 >>
 @end example
@@ -3534,38 +3557,40 @@ making or a music identifier @code{\foo} containing the syllable
 @subsection Ambitus
 @cindex ambitus
 
-The term @emph{ambitus} denotes a range of pitches for a given voice in
-a part of music.  It also may denote the pitch range that a musical
-instrument is capable of playing.  Most musical instruments have their
-ambitus standardized (or at least there is agreement upon the minimal
-ambitus of a particular type of instrument), such that a composer or
-arranger of a piece of music can easily meet the ambitus constraints of
-the targeted instrument.  However, the ambitus of the human voice
-depends on individual physiological state, including education and
-training of the voice.  Therefore, a singer potentially has to check for
-each piece of music if the ambitus of that piece meets his individual
-capabilities.  This is why the ambitus of a piece may be of particular
-value to vocal performers.
+The term @emph{ambitus} (plural: ambituses) denotes a range of pitches
+for a given voice in a part of music.  It also may denote the pitch
+range that a musical instrument is capable of playing.  Most musical
+instruments have their ambitus standardized (or at least there is
+agreement upon the minimal ambitus of a particular type of
+instrument), such that a composer or arranger of a piece of music can
+easily meet the ambitus constraints of the targeted instrument.
+However, the ambitus of the human voice depends on individual
+physiological state, including education and training of the voice.
+Therefore, a singer potentially has to check for each piece of music
+if the ambitus of that piece meets his individual capabilities.  This
+is why the ambitus of a piece may be of particular value to vocal
+performers.
 
 The ambitus is typically notated on a per-voice basis at the very
 beginning of a piece, e.g. nearby the initial clef or time signature of
 each staff.  The range is graphically specified by two noteheads, that
 represent the minimum and maximum pitch.  Some publishers use a textual
 notation: they put the range in words in front of the corresponding
-staff.  LilyPond currently only supports the graphical ambitus notation.
+staff.  LilyPond only supports the graphical ambitus notation.
 
 To apply, add the @internalsref{Ambitus_engraver} to the
 @internalsref{Voice} context, i.e.
 
 @example
-  \paper @{ \translator @{
+  \paper @{
+    \translator @{
       \VoiceContext
       \consists Ambitus_engraver
-    @} @}
+    @}
+  @}
 @end example
 
-For example,
-
+This results in the following output:
 @lilypond[singleline]
 upper = \notes \relative c {
   \clef "treble"
@@ -3586,17 +3611,31 @@ lower = \notes \relative c {
   }
   \paper {
     \translator {
-      \VoiceContext
+      \StaffContext
       \consists Ambitus_engraver
     }
   }
 }
 @end lilypond
 
+If you have multiple voices in a single staff, and you want a single
+ambitus per staff rather than per each voice, then add the
+@internalsref{Ambitus_engraver} to the @internalsref{Staff} context
+rather than to the @internalsref{Voice} context.
+
+It is possible to tune individual ambituses for multiple voices on a
+single staff, for example by erasing or shifting them horizontally. An
+example is in @inputfileref{input/test,ambitus-mixed.ly}
 
 @seealso
 
-@internalsref{Ambitus}, and @inputfileref{input/regression,ambitus.ly}.
+@internalsref{Ambitus}, @inputfileref{input/regression,ambitus.ly},
+@inputfileref{input/test,ambitus-mixed.ly}.
+
+@refbugs
+
+There is no collision handling in the case of multiple per-voice
+ambitus.
 
 @node Tablatures
 @section Tablatures
@@ -3673,7 +3712,7 @@ chord.
 You can change the number of strings, by setting the number of lines
 in the @internalsref{TabStaff} (the @code{line-count} property of
 @internalsref{TabStaff} can only be changed using
-@code{\outputproperty}, for more information, see @ref{Tuning
+@code{\applyoutput}, for more information, see @ref{Tuning
 objects}).
 
 You can change the tuning of the strings. A string tuning is given as
@@ -3687,8 +3726,8 @@ g:
 @lilypond[fragment,verbatim]
   \context TabStaff <<
 
-    \outputproperty #(make-type-checker 'staff-symbol-interface)
-                    #'line-count = #4
+    \applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface)
+                    'line-count 4)
     \property TabStaff.stringTunings =  #'(-5 -10 -15 -20)
     
     \notes {
@@ -3705,8 +3744,7 @@ takes three argument: string number, string tuning and note pitch.
 
 @refbugs
 
-Most of the guitar special effects such as bend have not been
-implemented yet.
+No guitar special effects have been implemented.
 
 
 
@@ -3825,8 +3863,9 @@ Modifiers can be mixed with additions:
 @cindex @code{m}
 
 Since an unaltered 11 does not sound good when combined with an
-unaltered 13, the 11 is removed in this case (, unless it is added
+unaltered 13, the 11 is removed in this case (unless it is added
 explicitly):
+@c
 @lilypond[fragment,verbatim]
   \chords { c:13 c:13.11 c:m13 }
 @end lilypond 
@@ -3909,7 +3948,7 @@ scheme = \chords {
 @end lilypond
 
 The default chord name layout is a system for Jazz music, proposed by
-Klaus Ignatzek (see @ref{Literature}).  It can be tuned through the
+Klaus Ignatzek (see @ref{Literature list}).  It can be tuned through the
 following properties:
 
 @table @code
@@ -3948,6 +3987,10 @@ alteration. The transformation from pitch to letter is done by this
 function.  Special note names (for example, the German ``H'' for a
 B-chord) can be produced by storing a new function in this property.
 
+The pre-defined variables @code{\germanChords},
+@code{\semiGermanChords} set these variables.
+
+
 @cindex chordNoteNamer
 @item chordNoteNamer
 The default is to print single pitch, e.g. the bass note, using the
@@ -3962,7 +4005,7 @@ There are also two other chord name schemes implemented: an alternate
 Jazz chord notation, and a systematic scheme called Banter chords. The
 alternate jazz notation is also shown on the chart in @ref{Chord name
 chart}.  Turning on these styles is described in the input file
-@inputfileref{input/test/,chord-names-jazz.ly}.
+@inputfileref{input/test,chord-names-jazz.ly}.
 
 @cindex Banter
 @cindex jazz chords
@@ -4142,13 +4185,16 @@ and @internalsref{Staff}.@code{instr}. This will print a string before
 the start of the staff. For the first start, @code{instrument} is
 used, for the next ones @code{instr} is used:
 
+@quotation
 @lilypond[verbatim,singleline]
   \property Staff.instrument = "ploink " { c''4 }  
 @end lilypond
+@end quotation
 
 You can also use markup texts to construct more complicated instrument
 names:
 
+@quotation
 @lilypond[fragment,verbatim,singleline]
   \notes {
     \property Staff.instrument = \markup {
@@ -4161,7 +4207,7 @@ names:
      { c''1 }
   }
 @end lilypond
-
+@end quotation
 
 @seealso
 
@@ -4225,11 +4271,11 @@ you must put @code{\transpose} outside of @code{\relative}, since
 @cindex @code{R}
 
 Multi measure rests are entered using `@code{R}'. It is specifically
-meant for full bar rests and for entering parts: the rest can expand to
-fill a score with rests, or it can be printed as a single multimeasure
-rest. This expansion is controlled by the property
-@code{Score.skipBars}. If this is set to true, Lily will not expand
-empty measures, and the appropriate number is added automatically:
+meant for full bar rests and for entering parts: the rest can expand
+to fill a score with rests, or it can be printed as a single
+multimeasure rest. This expansion is controlled by the property
+@code{Score.skipBars}. If this is set to true, empty measures will not
+be expanded, and the appropriate number is added automatically:
 
 @lilypond[fragment,verbatim]
  \time 4/4 r1 | R1 | R1*2
@@ -4294,13 +4340,13 @@ There is no way to automatically condense multiple rests into a single
 multimeasure rest. Multi measure rests do not take part in rest
 collisions.
 
-Be careful when entering multimeasure rests followed by whole notes,
+Be careful when entering multimeasure rests followed by whole
+notes. The following will enter two notes lasting four measures each:
 @example
  R1*4 cis cis 
 @end example
-will enter two notes lasting four measures each. When @code{skipBars}
-is set, then the result will look OK, but the bar numbering will be
-off.
+When @code{skipBars} is set, then the result will look OK, but the
+bar numbering will be off.
 
 @node Automatic part combining
 @subsection Automatic part combining
@@ -4433,10 +4479,9 @@ in this example disappears in the second line:
 }
 @end lilypond
 
-In orchestral scores, the first page usually shows all staffs in
-full. To prevent empty staffs from being discarded from the first
-page, set @code{remove-first} to false in
-@internalsref{RemoveEmptyVerticalGroup}.
+The first page shows all staffs in full. If they should be  removed
+from  the first page too, set @code{remove-first} to false
+in @internalsref{RemoveEmptyVerticalGroup}.
 
 @node Different editions from one source
 @subsection Different editions from one source
@@ -4451,13 +4496,13 @@ for the full score, and one with cue notes for the instrumental part:
 @example
     c1
     \relative c' <<
-	\tag #'part <<
-	  R1 \\
-	  @{
-	      \property Voice.fontSize = #-1
-	      c4_"cue" f2 g4 @} 
+        \tag #'part <<
+          R1 \\
+          @{
+              \property Voice.fontSize = #-1
+              c4_"cue" f2 g4 @} 
         >>
-	\tag #'score R1
+        \tag #'score R1
      >>
      c1
 @end example
@@ -4479,8 +4524,8 @@ filtered. For example,
 @example
 \simultaneous @{
         @var{the music}
-	\apply #(remove-tag 'score) @var{the music}
-	\apply #(remove-tag 'part) @var{the music}
+        \apply #(remove-tag 'score) @var{the music}
+        \apply #(remove-tag 'part) @var{the music}
 @}
 @end example
 would yield
@@ -4528,7 +4573,7 @@ output:
 
 Support for ancient notation is still under heavy development.
 Regardless of all of the current limitations (see the bugs section
-below for details), it currently includes features for mensural
+below for details), it includes features for mensural
 notation and Gregorian Chant notation.  There is also limited support
 for figured bass notation.
 
@@ -4579,7 +4624,7 @@ correctly align with ligatures.
 Accidentals must not be printed within a ligature, but instead need to
 be collected and printed in front of it.
 
-Augmentum dots within ligatures are currently not handled correctly.
+Augmentum dots within ligatures are  not handled correctly.
 
 
 @node Ancient note heads
@@ -4633,7 +4678,7 @@ frequently used in contemporary music notation.
 @syntax
 
 Use the @code{style} property of grob @internalsref{Accidental} to
-select ancient accidentals.  Currently supported styles are
+select ancient accidentals.   Supported styles are
 @code{mensural}, @code{vaticana}, @code{hufnagel} and @code{medicaea}.
 
 @lilypond[singleline,26pt]
@@ -4647,13 +4692,13 @@ select ancient accidentals.  Currently supported styles are
                 { " " \musicglyph #"accidentals-vaticana-1"
                   " " \musicglyph #"accidentals-vaticana0" }
             >
-	    \column <
+            \column <
                 "medicaea"
-		{ " " \musicglyph #"accidentals-medicaea-1" }
+                { " " \musicglyph #"accidentals-medicaea-1" }
             >
-	    \column <
+            \column <
                 "hufnagel"
-		{ " " \musicglyph #"accidentals-hufnagel-1" }
+                { " " \musicglyph #"accidentals-hufnagel-1" }
             >
             \column <
                 "mensural"
@@ -4663,7 +4708,7 @@ select ancient accidentals.  Currently supported styles are
         }
     }
     \paper {
-	raggedright = ##t 
+        raggedright = ##t 
         interscoreline = 1
         \translator {
             \ScoreContext
@@ -4706,7 +4751,7 @@ signatures.
 @syntax
 
 Use the @code{style} property of grob @internalsref{Rest} to select
-ancient accidentals.  Currently supported styles are @code{classical},
+ancient accidentals.   Supported styles are @code{classical},
 @code{neo_mensural} and @code{mensural}.  @code{classical} differs
 from the @code{default} style only in that the quarter rest looks like
 a horizontally mirrored 8th rest.  The @code{neo_mensural} style suits
@@ -4846,7 +4891,7 @@ Editio Vaticana style do clef @tab
 @code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3} @tab
 @lilypond[relative 0, notime]
 \context Staff
-\outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4
+\applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface) 'line-count 4)
 \property Staff.TimeSignature \set #'transparent = ##t
 \clef "vaticana_do2" c
 @end lilypond
@@ -4857,7 +4902,7 @@ Editio Vaticana style fa clef @tab
 @code{vaticana_fa1}, @code{vaticana_fa2} @tab
 @lilypond[relative 0, notime]
 \context Staff
-\outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4
+\applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface) 'line-count 4)
 \property Staff.TimeSignature \set #'transparent = ##t
 \clef "vaticana_fa2" c
 @end lilypond
@@ -4868,7 +4913,7 @@ Editio Medicaea style do clef @tab
 @code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3} @tab
 @lilypond[relative 0, notime]
 \context Staff
-\outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4
+\applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface) 'line-count 4)
 \property Staff.TimeSignature \set #'transparent = ##t
 \clef "medicaea_do2" c
 @end lilypond
@@ -4879,7 +4924,7 @@ Editio Medicaea style fa clef @tab
 @code{medicaea_fa1}, @code{medicaea_fa2} @tab
 @lilypond[relative 0, notime]
 \context Staff
-\outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4
+\applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface) 'line-count 4)
 \property Staff.TimeSignature \set #'transparent = ##t
 \clef "medicaea_fa2" c
 @end lilypond
@@ -4890,7 +4935,7 @@ historic style hufnagel do clef @tab
 @code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3} @tab
 @lilypond[relative 0, notime]
 \context Staff
-\outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4
+\applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface) 'line-count 4)
 \property Staff.TimeSignature \set #'transparent = ##t
 \clef "hufnagel_do2" c
 @end lilypond
@@ -4901,7 +4946,7 @@ historic style hufnagel fa clef @tab
 @code{hufnagel_fa1}, @code{hufnagel_fa2} @tab
 @lilypond[relative 0, notime]
 \context Staff
-\outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4
+\applyoutput #(outputproperty-compatibility (make-type-checker 'staff-symbol-interface) 'line-count 4)
 \property Staff.TimeSignature \set #'transparent = ##t
 \clef "hufnagel_fa2" c
 @end lilypond
@@ -4962,7 +5007,7 @@ For modern clefs, see @ref{Clef}.  For the percussion clef, see
 
 Use the @code{flag-style} property of grob @internalsref{Stem} to
 select ancient flags.  Besides the @code{default} flag style,
-currently only @code{mensural} style is supported:
+ only @code{mensural} style is supported:
 
 @lilypond[fragment,singleline,verbatim]
   \property Voice.Stem \set #'flag-style = #'mensural
@@ -5003,7 +5048,7 @@ Gregorian Chant notation.
 
 @syntax
 
-There is limited support for mensural time signatures.  Currently, the
+There is limited support for mensural time signatures.   The
 glyphs are hard-wired to particular time fractions.  In other words,
 to get a particular mensural signature glyph with the @code{\time n/m}
 command, @code{n} and @code{m} have to be chosen according to the
@@ -5012,10 +5057,10 @@ following table:
 @lilypond
 \score {
     \notes {
-	\property Score.timing = ##f
-	\property Score.barAlways = ##t
-	s_\markup { "$\\backslash$time 4/4" }
-	 ^\markup { "       " \musicglyph #"timesig-neo\_mensural4/4" }
+        \property Score.timing = ##f
+        \property Score.barAlways = ##t
+        s_\markup { "$\\backslash$time 4/4" }
+         ^\markup { "       " \musicglyph #"timesig-neo\_mensural4/4" }
 	s
 	s_\markup { "$\\backslash$time 2/2" }
 	 ^\markup { "       " \musicglyph #"timesig-neo\_mensural2/2" }
@@ -5059,7 +5104,7 @@ following table:
 @end lilypond
 
 Use the @code{style} property of grob @internalsref{TimeSignature} to
-select ancient time signatures.  Currently supported styles are
+select ancient time signatures.  Supported styles are
 @code{neo_mensural} and @code{mensural}.  The above table uses the
 @code{neo_mensural} style.  This style is appropriate e.g. for the
 incipit of transcriptions of mensural pieces.  The @code{mensural}
@@ -5075,7 +5120,7 @@ signatures.
 
 @refbugs
 
-Mensural signature glyphs are currently mapped to time fractions in a
+Mensural signature glyphs are  mapped to time fractions in a
 hard-wired way.  This mapping is sensible, but still arbitrary: given
 a mensural time signature, the time fraction represents a modern meter
 that usually will be a good choice when transcribing a mensural piece
@@ -5083,10 +5128,10 @@ of music.  For a particular piece of mensural music, however, the
 mapping may be unsatisfactory.  In particular, the mapping assumes a
 fixed transcription of durations (e.g. brevis = half note in 2/2,
 i.e. 4:1).  Some glyphs (such as the alternate glyph for 6/8 meter)
-are currently not at all accessible through the @code{\time} command.
+are  not at all accessible through the @code{\time} command.
 
 Mensural time signatures are supported typographically, but not yet
-musically.  The internal representation of durations is currently
+musically.  The internal representation of durations is 
 based on a purely binary system; a ternary division such as 1 brevis =
 3 semibrevis (tempus perfectum) or 1 semibrevis = 3 minima (cum
 prolatione maiori) is not correctly handled: event times in ternary
@@ -5314,16 +5359,16 @@ square bracket above the ligature:
 @lilypond[singleline,verbatim]
 \score {
     \notes \transpose c c' {
-	\[ g c a f d' \]
-	a g f
-	\[ e f a g \]
+        \[ g c a f d' \]
+        a g f
+        \[ e f a g \]
     }
 }
 @end lilypond
 
 To select a specific style of ligatures, a proper ligature engraver
 has to be added to the @internalsref{Voice} context, as explained in
-the following subsections.  Currently, only white mensural ligatures
+the following subsections.   Only white mensural ligatures
 are supported with certain limitations.  Support for Editio Vaticana
 will be added in the future.
 
@@ -5339,7 +5384,7 @@ will be added in the future.
 @cindex White mensural ligatures
 
 There is limited support for white mensural ligatures.  The
-implementation is still experimental; it currently may output strange
+implementation is still experimental; it may output strange
 warnings or even crash in some cases or produce weird results on more
 complex ligatures.
 
@@ -5352,11 +5397,11 @@ To engrave white mensural ligatures, in the paper block the
 
 @example
     \paper @{
-	\translator @{
-	    \VoiceContext
-	    \remove Ligature_bracket_engraver
-	    \consists Mensural_ligature_engraver
-	@}
+        \translator @{
+            \VoiceContext
+            \remove Ligature_bracket_engraver
+            \consists Mensural_ligature_engraver
+        @}
     @}
 @end example
 
@@ -5371,33 +5416,33 @@ automatic transcription of the ligatures.
 For example,
 
 @example
-	\property Score.timing = ##f
-	\property Score.defaultBarType = "empty"
-	\property Voice.NoteHead \set #'style = #'neo_mensural
-	\property Staff.TimeSignature \set #'style = #'neo_mensural
-	\clef "petrucci_g"
-	\[ g\longa c\breve a\breve f\breve d'\longa \]
-	s4
-	\[ e1 f1 a\breve g\longa \]
+        \property Score.timing = ##f
+        \property Score.defaultBarType = "empty"
+        \property Voice.NoteHead \set #'style = #'neo_mensural
+        \property Staff.TimeSignature \set #'style = #'neo_mensural
+        \clef "petrucci_g"
+        \[ g\longa c\breve a\breve f\breve d'\longa \]
+        s4
+        \[ e1 f1 a\breve g\longa \]
 @end example
 @lilypond[singleline]
 \score {
     \notes \transpose c c' {
-	\property Score.timing = ##f
-	\property Score.defaultBarType = "empty"
-	\property Voice.NoteHead \set #'style = #'neo_mensural
-	\property Staff.TimeSignature \set #'style = #'neo_mensural
-	\clef "petrucci_g"
-	\[ g\longa c\breve a\breve f\breve d'\longa \]
-	s4
-	\[ e1 f1 a\breve g\longa \]
+        \property Score.timing = ##f
+        \property Score.defaultBarType = "empty"
+        \property Voice.NoteHead \set #'style = #'neo_mensural
+        \property Staff.TimeSignature \set #'style = #'neo_mensural
+        \clef "petrucci_g"
+        \[ g\longa c\breve a\breve f\breve d'\longa \]
+        s4
+        \[ e1 f1 a\breve g\longa \]
     }
     \paper {
-	\translator {
-	    \VoiceContext
-	    \remove Ligature_bracket_engraver
-	    \consists Mensural_ligature_engraver
-	}
+        \translator {
+            \VoiceContext
+            \remove Ligature_bracket_engraver
+            \consists Mensural_ligature_engraver
+        }
     }
 }
 @end lilypond
@@ -5409,14 +5454,14 @@ to the following:
 @lilypond[singleline]
 \score {
     \notes \transpose c c' {
-	\property Score.timing = ##f
-	\property Score.defaultBarType = "empty"
-	\property Voice.NoteHead \set #'style = #'neo_mensural
-	\property Staff.TimeSignature \set #'style = #'neo_mensural
-	\clef "petrucci_g"
-	\[ g\longa c\breve a\breve f\breve d'\longa \]
-	s4
-	\[ e1 f1 a\breve g\longa \]
+        \property Score.timing = ##f
+        \property Score.defaultBarType = "empty"
+        \property Voice.NoteHead \set #'style = #'neo_mensural
+        \property Staff.TimeSignature \set #'style = #'neo_mensural
+        \clef "petrucci_g"
+        \[ g\longa c\breve a\breve f\breve d'\longa \]
+        s4
+        \[ e1 f1 a\breve g\longa \]
     }
 }
 @end lilypond
@@ -7112,7 +7157,7 @@ takes care of making @internalsref{BassFigure} objects.
 In figures input mode, a group of bass figures is delimited by
 @code{<} and @code{>}. The duration is entered after the @code{>>}:
 @example
-	<4 6>
+        <4 6>
 @end example
 @lilypond[fragment]
 \context FiguredBass
@@ -7134,7 +7179,7 @@ Spaces or dashes may be inserted by using @code{_}. Brackets are
 introduced with @code{[} and @code{]}:
 
 @example
-	< [4 6] 8 [_! 12]>
+        < [4 6] 8 [_! 12]>
 @end example
 @lilypond[fragment]
  \context FiguredBass
@@ -7197,11 +7242,11 @@ entering the chant, as the following short excerpt demonstrates:
 
 In the 20th century, composers have greatly expanded the musical
 vocabulary. With this expansion, many innovations in musical notation
-have been tried. For a comprehensive overview, refer to @cite{Stone
-1980} (see @ref{Literature}). In general, the use of new, innovative
-notation makes a piece harder to understand and perform and its use
-should therefore be avoided if possible.  For this reason, support for
-contemporary notation in LilyPond is limited.
+have been tried. The book by Stone (1980) gives a comprehensive
+overview (see @ref{Literature list}). In general, the use of new,
+innovative notation makes a piece harder to understand and perform and
+its use should therefore be avoided if possible.  For this reason,
+support for contemporary notation in LilyPond is limited.
 
 
 @menu
@@ -7354,7 +7399,6 @@ layout property name:
 * Tuning objects ::             
 * Constructing a tweak::        
 * Applyoutput::                 
-* Outputproperty::              
 * Font selection::              
 * Text markup::                 
 @end menu
@@ -7484,7 +7528,7 @@ then you can use
 @end example
 @end itemize
 
-For the digirati, the object description is an Scheme association
+ The object description is an Scheme association
 list. Since a Scheme list is a singly linked list, we can treat it as
 a stack, and @code{\override} and @code{\revert} are push and pop
 operations.  The association list is stored in a normal context
@@ -7493,8 +7537,9 @@ property, hence
  \property Voice.NoteHead  = #'() 
 @end example
 will effectively erase @internalsref{NoteHead}s from the current
-@internalsref{Voice}. However, this mechanism is not guaranteed to
-work, and may cause crashes or other anomalous behavior.
+@internalsref{Voice}. Typically, this will blank the object. However,
+this mechanism should not be used: it may cause crashes or other
+anomalous behavior.
 
 @seealso
 
@@ -7506,8 +7551,8 @@ work, and may cause crashes or other anomalous behavior.
 @refbugs
 
 The backend is not very strict in type-checking object properties.
-Cyclic references in @var{value} cause hangs and/or crashes.
-Similarly, reverting properties that are system defaults may also lead
+Cyclic references in Scheme values for properties cause hangs and/or
+crashes.  Reverting properties that are system defaults may also lead
 to crashes.
 
 @node Constructing a tweak
@@ -7533,13 +7578,13 @@ The generated documentation is a set of HTML pages which should be
 included if you installed a binary distribution, typically in
 @file{/usr/share/doc/lilypond}.  They are also available on the web:
 go to the @uref{http://lilypond.org,LilyPond website}, click
-``Documentation'', and then ``Program reference'' on the side bar. It
-is advisable to bookmark either the local HTML files if possible. They
-will load faster than the ones on the web.  If you use the version
-from the web, you must check whether the documentation matches the
-program version: the documentation is generated from the definitions
-that the program uses, and therefore it is strongly tied to the
-LilyPond version.
+``Documentation'', select the correct version, and click then
+``Program reference.'' It is advisable to bookmark the local HTML
+files. They will load faster than the ones on the web.  If you use the
+version from the web, you must check whether the documentation matches
+the program version: it is generated from the definitions that the
+program uses, and therefore it is strongly tied to the LilyPond
+version.
 
 
 @c  [TODO: revise for new site.]
@@ -7559,16 +7604,19 @@ instructions}), you will notice that there is written:
 @seealso
 
 @internalsref{FingerEvent} and @internalsref{Fingering}.
+
 @end quotation
 
+@separate
+
 @noindent
 In other words, the fingerings once entered, are internally stored as
 @code{FingerEvent} music objects. When printed, a @code{Fingering}
 layout object is created for every @code{FingerEvent}.
 
 The Fingering object has a number of different functions, and each of
-those is captured in an interface,  when we look up
-@internalsref{Fingering} in the generated documentation.
+those is captured in an interface. The interfaces are listed under
+@internalsref{Fingering} in the program reference.
 
 
 
@@ -7595,7 +7643,7 @@ For the vertical placement, we have to look under
 @code{side-position-interface}
 
   Position a victim object (this one) next to other objects (the
-  support).  In this case, the direction signifies where to put the
+  support).  In this case, the property @code{direction} signifies where to put the
   victim object relative to the support (left or right, up or down?)
 @end quotation
 
@@ -7653,7 +7701,9 @@ Of course, the tweak may also done in a larger context than
 @code{Voice}, for example, @internalsref{Staff} or
 @internalsref{Score}.
 
-The internals document also contains alphabetical lists of
+@seealso
+
+The program reference also contains alphabetical lists of
 @internalsref{Contexts}, @internalsref{All-layout-objects} and
 @internalsref{Music-expressions}, so you can also find which objects to
 tweak by browsing the internals document.
@@ -7669,48 +7719,34 @@ syntax is
 @end example
 
 @noindent
-where @var{proc} is a Scheme function, taking four arguments.
+where @var{proc} is a Scheme function, taking three arguments.
 
-When interpreted, the function @var{proc} is called for every layout object found
-in the context, with the following arguments:
+When interpreted, the function @var{proc} is called for every layout
+object found in the context, with the following arguments:
 @itemize @bullet
 @item the layout object itself,
 @item the context where the layout object was created, and
 @item the context where @code{\applyoutput} is processed.
 @end itemize
 
+
 In addition, the cause of the layout object, i.e.  the music
 expression or object that was responsible for creating it, is in the
 object property @code{cause}.  For example, for a note head, this is a
 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
 this is a @internalsref{NoteHead} object.
 
-
-@node Outputproperty
-@subsection Outputproperty
-
-@cindex @code{\outputproperty}
-
-Another way of tuning objects is the more arcane @code{\outputproperty}
-feature.  The syntax is as follows:
+Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
+center-line:
 @example
-\outputproperty @var{predicate} @var{symbol} = @var{value}
-@end example
-Here @code{predicate} is a Scheme function taking an object argument, and
-returning a boolean.  This statement is processed by the
-@code{Output_property_engraver}.  It instructs the engraver to feed all
-objects that it sees to @var{predicate}. Whenever the predicate returns
-true, the object property @var{symbol} will be set to @var{value}.
-
-You will need to combine this statement with @code{\context} to select
-the appropriate context to apply this to.
-@inputfileref{input/regression,output-property.ly} shows an example of
-the use of @code{\outputproperty}.
+(define (blanker grob grob-origin context)
+  (if (and (memq (ly:get-grob-property grob 'interfaces)
+                 note-head-interface)
+           (eq? (ly:get-grob-property grob 'staff-position) 0))
 
-@refbugs
+           (ly:set-grob-property! grob 'transparent #t)))
+@end example
 
-This command is slated for removal.  Please use the
-@code{\applyoutput} command, see @ref{Applyoutput}.
 
 
 @node Font selection
@@ -8063,9 +8099,8 @@ The global layout determined by three factors: the page layout, the
 line breaks and the spacing. These all influence each other. The
 choice of spacing determines how densely each system of music is set,
 which influences where line breaks breaks are chosen, and thus
-ultimately how many pages a piece of music takes. In this section, the
-algorithm for spacing music is explained, and how spacing can be
-tuned.
+ultimately how many pages a piece of music takes. This section
+explains how to tune the algorithm for spacing.
 
 Globally spoken, this procedure happens in three steps: first,
 flexible distances (``springs'') are chosen, based on durations. All
@@ -8109,7 +8144,7 @@ set
 @example
   \property Staff.minimumVerticalExtent = #'(-4 . 4)
 @end example
-This sets the vertical size of the current staff to 4 staff-space on
+This sets the vertical size of the current staff to 4 staff spaces on
 either side of the center staff line.  The argument of
 @code{minimumVerticalExtent} is interpreted as an interval, where the
 center line is the 0, so the first number is generally negative.  The
@@ -8168,10 +8203,10 @@ notes are generally followed by one NHW of space.
 If one would follow the above procedure exactly, then adding a single
 32th note to a score that uses 8th and 16th notes, would widen up the
 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
-thus adding 2 noteheads of space to every note. To prevent this, the
+thus adding 1 NHW to every note. To prevent this, the
 shortest duration for spacing is not the shortest note in the score,
 but the most commonly found shortest note.  Notes that are even
-shorter this are followed by a space that is proportonial to their
+shorter this are followed by a space that is proportional to their
 duration relative to the common shortest note.  So if we were to add
 only a few 16th notes to the example above, they would be followed by
 half a NHW:
@@ -8268,8 +8303,8 @@ of these files, the variables @code{paperEleven},
 are defined respectively.  The default @code{\paper} block is also
 set. These files should be imported at toplevel, i.e.
 @example
-	\include "paper26.ly"
-	\score @{  ... @}
+        \include "paper26.ly"
+        \score @{  ... @}
 @end example
 
 The default font size settings for each staff heights are generated
@@ -8478,17 +8513,13 @@ The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
 
 @cindex instrument names
 @cindex @code{Staff.midiInstrument}
-@cindex @code{Staff.instrument}
 
 The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property or, if that property is not set, the @code{Staff.instrument}
 property.  The instrument name should be chosen from the list in
 @ref{MIDI instruments}.
 
 @refbugs
 
-If the selected string does not exactly match, then LilyPond uses the
-default (Grand Piano). It is not possible to select an instrument by
-number.
-
+If the selected string does not exactly match, then the default is
+used, which is the Grand Piano.