X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frefman.itely;h=a46c14eaee71902342c24871da184d523d87db5f;hb=b76d0173a49e115b77120d673f5aa6169f4875aa;hp=00c006f2f57d9ed35db64fa4c5f290cac3feef84;hpb=87932dcb8ec24b069bbce8edbb76f5258ca4ff1b;p=lilypond.git

diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely
index 00c006f2f5..a46c14eaee 100644
--- a/Documentation/user/refman.itely
+++ b/Documentation/user/refman.itely
@@ -19,7 +19,7 @@
 @chapter Reference Manual
 
 This document describes GNU LilyPond and its input format. The last
-revision of this document was for LilyPond 1.3.138.
+revision of this document was for LilyPond 1.3.141.
 
 
 @menu
@@ -41,6 +41,7 @@ revision of this document was for LilyPond 1.3.138.
 * Page layout::                 
 * Sound::                       
 * Music entry::                 
+* Skipping corrected music::    
 * Interpretation context::      
 * Syntactic details::           
 * Lexical details::             
@@ -60,7 +61,7 @@ by `music compiler' or `music to notation compiler'.
 
 LilyPond is linked to GUILE, GNU's Scheme library for extension. The
 Scheme library provides the glue that holds together the low-level
-routines and separate modules general, which are C++
+routines and separate modules general, which are C++.
 
 When lilypond is run to typeset sheet music, the following happens:
 @itemize @bullet
@@ -133,7 +134,7 @@ The verbose syntax for pitch specification is
 @example
   \pitch @var{scmpitch}
 @end example
-9
+
 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
 
 In Note and Chord mode, pitches may be designated by names.  The default
@@ -347,10 +348,10 @@ warning message will appear and no ties will be created.
 @end lilypond
 
 If you dislike the amount of ties created for a chord, you set
-@code{Thread.sparseTies} to true, resulting in  a smaller number of
+@code{Voice.sparseTies} to true, resulting in  a smaller number of
 ties:
 @lilypond[fragment,verbatim,center]
-  \property Thread.sparseTies = ##t
+  \property Voice.sparseTies = ##t
   <c' e' g'> ~ <c' e' g'>
 @end lilypond
 
@@ -429,7 +430,7 @@ Rests are entered like notes, with note name `@code{r}'.
 
 Skips the amount of time specified by @var{duration}.  If no other music
 is played, a gap will be left for the skipped time with no notes
-printed.  The short hand is only available in Note and Chord mode.
+printed.  The shorthand is only available in Note and Chord mode.
 
 
 
@@ -463,7 +464,9 @@ numbers in this mode.
 
 @menu
 * Key signature::               
+* Clef::                        
 * Time signature::              
+* Unmetered music::             
 * Bar lines::                   
 @end menu
 
@@ -505,13 +508,14 @@ This command sets context property @code{Staff.keySignature}.
 @cindex @code{keySignature}
 
 @c .  {Clef}
-@subsection Clef changes
+@node Clef
+@subsection Clef
 @cindex @code{\clef}
 @example
   \clef @var{clefname} @code{;}
 @end example
 
-Short-cut for
+Shortcut for
 
 @example
   \property Staff.clefGlyph = @var{glyph associated with clefname} 
@@ -578,7 +582,7 @@ The time signature is changed by the @code{\time} command. Syntax:
 @example
   \time @var{numerator}@code{/}@var{denominator} @code{;}
 @end example
-Internally, this is a short-cut for doing
+Internally, this is a shortcut for doing
 @example
      \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
 @end example
@@ -600,13 +604,34 @@ Partial measures are entered using the @code{\partial} command:
   \partial @var{duration} @code{;}
 @end example
 
-Internally,  this is a short cut for 
+Internally,  this is a shortcut for 
 
 @example
   \property Score.measurePosition = -@var{length of duration}
 @end example
 @cindex @code{|}
 
+
+@node Unmetered music
+@subsection Unmetered music
+
+Bar lines and bar numbers are calculated automatically. For unmetered
+music (e.g. cadenzas), this is not desirable. The property
+@code{Score.timing} can be used to switch off this automatic timing
+
+@lilypond[fragment,relative,singleline,verbatim]
+c'2.
+\property Score.timing = ##f
+c4 c4 c4  
+\property Score.timing = ##t
+c4 c4 c4 
+@end lilypond
+
+The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used to
+achieve the same effect.
+
+
+
 @c .   {Bar lines}
 @node Bar lines
 @subsection Bar lines
@@ -620,7 +645,7 @@ Internally,  this is a short cut for
   \bar @var{bartype};
 @end example
 
-This is a short-cut for doing
+This is a shortcut for doing
 @example
   \property Score.whichBar = @var{bartype} 
 @end example
@@ -650,69 +675,77 @@ settings.
 @c .   {Polyphony}
 @node Polyphony
 @section Polyphony
-@cindex Polyphony
+@cindex polyphony
 
-[TODO: collisions, rest-collisinos, voiceX identifiers, how to
-which  contexts to instantiate.  some small examples? ]
+Polyphonic parts, i.e. parts with more than one voice on a staff can be
+typeset with LilyPond.   To use this, instantiate a separate Voice
+context for each part, and assign a stem direction to each part. 
+@lilypond[fragment,verbatim]
+\context Staff
+< \context Voice = VA { \stemUp b'4 a' g' f' e' }
+  \context Voice = VB { \stemDown g'4 g' g' g' g' } >
+@end lilypond
 
+When there are more than two voices on a staff, you must also indicate
+which voice should moved horizontally in case of a collision. This can
+be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
+@code{\shiftOnn}, etc. (which sets grob property @code{horizontal-shift}
+in @code{NoteColumn}).
+
+@lilypond[fragment, verbatim]
+  \context Staff \notes\relative c''<
+       \context Voice=one {
+       \shiftOff \stemUp e4
+       }
+       \context Voice=two {
+	  \shiftOn \stemUp cis
+       }
+       \context Voice=three {
+         \shiftOnn \stemUp ais
+       }
+       \context Voice=four {
+	  \shiftOnnn \stemUp fis-2
+       }
+  >
+@end lilypond
 
-@table @code
-@cindex @code{\shiftOff}  
-  @item @code{\shiftOff}
-    Disable horizontal shifting of note heads that collide. 
-
-@cindex @code{\shiftOn}  
-  @item @code{\shiftOn}
-    Enable note heads that collide with other note heads to be
-    shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
-set different shift values.
-
-@cindex @code{\stemBoth} 
-  @item @code{\stemBoth}
-    Allow stems and beams to point either upwards or
-    downwards, decided automatically by LilyPond.
-
-@cindex @code{\stemDown}  
-  @item @code{\stemDown}
-    Force stems and beams to point down.
-
-@cindex @code{\stemUp}  
-  @item @code{\stemUp}
-    Force stems and beams to point up.
-@end table
+The most convenient way is to use the identifiers @code{\voiceOne}
+through @code{\voiceFour}, which also set slur and tie directions in the
+correct manner.
 
-@cindex @code{\slurBoth}
-@cindex @code{\slurDown} 
-@cindex @code{\slurUp}
-Similarly, for slurs use
-@code{\slurBoth}, 
-@code{\slurDown}, 
-@code{\slurUp}.
-@cindex @code{\slurBoth}
-@cindex @code{\slurDown} 
-@cindex @code{\slurUp}
-Aand for ties use
-@code{\tieBoth}, 
-@code{\tieDown}, 
-@code{\tieUp}.
-
-@cindex @code{\voiceOne}
-@cindex @code{\voiceTwo}
-@cindex @code{\voiceThree}
-@cindex @code{\voiceFour}
-@cindex @code{\oneVoice}
-@cindex @code{\shiftOn}
-@cindex @code{\shiftOff}
-
-If two voices sharing one staff have the same stem directions, their
-note heads may collide.  You can shift the note heads of one voice by
-setting @code{\shiftOn}.  This can be undone by setting
-@code{\shiftOff}.
-
-For simple polyphonic music, shorthands are available that combine
-directions and shift settings: @code{\voiceOne}, @code{\voiceTwo},
-@code{\voiceThree}, @code{\voiceFour} and @code{\oneVoice}.
+@lilypond[singleline, verbatim]
+\relative c''
+\context Staff < \context Voice = VA { \voiceOne cis2 b  }
+  \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } 
+  \context Voice = VC { \voiceTwo fis4~  fis4 f ~ f  } >
+@end lilypond
+
+
+LilyPond also vertically shifts rests that are opposite of a stem. 
+
+@lilypond[singleline,verbatim]
+\context Staff <
+\context Voice {  \stemUp c''4  }
+\context Voice =VB { r4 }
+>
+@end lilypond
+
+Note head collisions (horizontal shifting of note heads) are handled by
+the @code{NoteCollision} grob. @code{RestCollision} handles vertical
+shifting of rests.
 
+@cindex @code{NoteCollision}
+@cindex @code{RestCollision}
+
+
+@refbugs
+
+Resolving collisions is a very intricate subject, and LilyPond only
+handles a few situations. When it can not cope, you are advised to use
+@code{force-hshift} of the NoteColumn grob and @code{staff-position} of
+the Rest grob to override typesetting decisions.
+
+[TODO: doc merge-differently-dotted]
 
 @node Beaming
 @section Beaming
@@ -787,9 +820,11 @@ note they contain. For a beam ending rule that only applies to beams
 with 32nd notes (and no shorter notes), you would use @code{(end * * 1
 32)}.
 
-[say something about irregular meters. eg 5/8 = 2+3/8, 3+2/8] 
+@c not true
+@c Automatic beams can not be put on the last note in a score.
 
-Automatic beams can not be put on the last note in a score.
+If a score ends while an automatic beam has not been ended and is still
+accepting notes, this last beam will not be typeset at all.
 
 @cindex automatic beam generation
 @cindex autobeam
@@ -799,6 +834,22 @@ Automatic beaming is on by default, but it can switched off by setting
 @code{Voice.noAutoBeaming} to true.  You you may find this necessary for
 a melody that goes with lyrics.
 
+@refbugs
+
+It is not possible to specify beaming parameters for beams with mixed
+durations, that differ from the beaming parameters of all separate
+durations, ie, you'll have to specify manual beams to get:
+@lilypond[fragment,singleline,relative]
+  \property Voice.autoBeamSettings
+  \override #'(end * * * *) = #(make-moment 3 8)
+  \time 12/8; c'8 c c c16 c c c c c [c c c c] c8 c c4
+@end lilypond
+
+It is not possible to specify beaming parameters that act differently in
+different parts of a measure, eg, in irregular meters such as @code{5/8}
+that breaks down to @code{2/8 +3/8} or @code{3/8 + 2/8}, automatic beams
+won't act according to the broken down parts @code{2/8} and @code{3/8}.
+
 @c .    {Manual beams}
 @cindex Automatic beams
 @subsection Manual beams
@@ -811,7 +862,6 @@ beaming algorithm.  For example, the auto beamer will not beam over
 rests or bar lines, so if you want that, specify the begin and end point
 manually using @code{[} and @code{]}:
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \context Staff {
     r4 [r8 g'' a r8] r8 [g | a] r8
@@ -832,7 +882,6 @@ control the number of beams through the properties
     [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
   }
 @end lilypond
-@end quotation
 @cindex @code{stemRightBeamCount}
 
 The beam symbol can be tweaked through @code{Voice.Beam}'s
@@ -841,24 +890,20 @@ in staff-spaces.
 
 Set @code{height} to zero, to get horizontal beams:
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \property Voice.Beam \set #'direction = #1
   \property Voice.Beam \set #'height = #0
   [a''8 e' d c]
 @end lilypond
-@end quotation
 
 Here's how you'd specify a weird looking beam that instead of being
 horizontal, falls two staff spaces:
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \property Voice.Beam \set #'staff-position = #2
   \property Voice.Beam \set #'height = #-2
   [c'8 c] 
 @end lilypond
-@end quotation
 @cindex @code{default-neutral-direction}
 
 @node Expressive marks
@@ -892,7 +937,6 @@ stem end.  If you want to override this layout you can do this through
 Maybe reinclude other slur features and move back to tricks?  Esp. the
 second example, how to fix, can be very helpful.
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \property Voice.Slur \set #'direction = #1
   \property Voice.Stem \set #'length = #5.5
@@ -900,13 +944,11 @@ second example, how to fix, can be very helpful.
   \property Voice.Slur \set #'attachment = #'(stem . stem)
   g8(g)g4
 @end lilypond
-@end quotation
 
 If a slur would strike through a stem or beam, the slur will be moved
 away upward or downward. If this happens, attaching the slur to the
 stems might look better:
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \property Voice.Stem \set #'direction = #1
   \property Voice.Slur \set #'direction = #1
@@ -914,7 +956,6 @@ stems might look better:
   \property Voice.Slur \set #'attachment = #'(stem . stem)
   d,32( d'4 )d8..
 @end lilypond
-@end quotation
 
 
 Similarly, the curvature of a slur is adjusted to stay clear of note
@@ -1035,6 +1076,8 @@ An application---or rather, a hack---is to fake octavation indications.
 * Articulation::                
 * Text scripts::                
 * Grace notes::                 
+* Glissando ::                  
+* Dynamics::                    
 @end menu
 
 @c .   {Articulation}
@@ -1208,15 +1251,12 @@ Unbeamed eighth notes and shorter by default have a slash through the
 stem.  This behavior can be controlled with the
 @code{Stem}.@code{flag-style} property.
 
-@quotation
 @lilypond[fragment,verbatim]
 \relative c'' {
   \grace c8 c4 \grace { [c16 c16] } c4
-  \grace { \property Grace.Stem \override #'flag-style = ##f c16 } c4
+  \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4
 }
-
 @end lilypond
-@end quotation
 
 
 At present, nesting @code{\grace} notes is not supported. The following
@@ -1252,7 +1292,7 @@ also be implemented.
 
 @c .   {Glissando}
 @node Glissando 
-@subsubsection Glissando
+@subsection Glissando
 @cindex Glissando 
 
 @cindex @code{\glissando}
@@ -1260,11 +1300,9 @@ also be implemented.
 A glissando line can be requested by attaching a @code{\glissando} to a
 note:
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   c'' \glissando c'
 @end lilypond
-@end quotation
 
 @refbugs
 
@@ -1275,7 +1313,7 @@ manually.
 
 @c .   {Dynamics}
 @node Dynamics
-@subsubsection Dynamics
+@subsection Dynamics
 @cindex Dynamics
 
 
@@ -1304,6 +1342,10 @@ note: @code{c4-\ff}.  The available dynamic marks are: @code{\ppp},
 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
 
+@lilypond[verbatim,singleline,fragment,relative]
+  c''\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
+  c2\sf c\rfz
+@end lilypond
 
 @cindex Crescendo and Decrescendo
 @cindex crescendo
@@ -1328,11 +1370,9 @@ want to get several marks during one note, you must use spacer notes.
 
 @lilypond[fragment,verbatim,center]
   c'' \< \! c''   d'' \decr e'' \rced 
-  < f''1 { s4 \< \! s2 \> \! s4 } >
+  < f''1 { s4 s4 \< \! s4 \> \! s4 } >
 @end lilypond
 
-[BUG in \> ! ]
-
 You can also use a text saying @emph{cresc.} instead of hairpins. Here
 is an example how to do it:
 
@@ -1345,7 +1385,11 @@ is an example how to do it:
 @end lilypond
 
 
+@refbugs
 
+When using spacer notes to subdivide note dynamics and @code{linewidth =
+-1}, starting a hairpin on the first spacer note (the one coinciding
+with the real note) exposes an embarassing bug.
 
 
 
@@ -1416,34 +1460,28 @@ Normal notation repeats are used like this:
 @end lilypond
 
 With alternative endings:
-@quotation
 @lilypond[fragment,verbatim]
   c'1
   \repeat volta 2 {c'4 d' e' f'} 
   \alternative { {d'2 d'} {f' f} }
 @end lilypond
-@end quotation
 
 Folded repeats look like this:@footnote{Folded repeats offer little
 more over simultaneous music.  However, it is to be expected that
 more functionality -- especially for the MIDI backend -- will be
 implemented at some point in the future.}
 
-@quotation
 @lilypond[fragment,verbatim]
   c'1
   \repeat fold 2 {c'4 d' e' f'} 
   \alternative { {d'2 d'} {f' f} }
 
 @end lilypond
-@end quotation
-
 
 If you don't give enough alternatives for all of the repeats, then
 the first alternative is assumed to be repeated often enough to equal
 the specified number of repeats.
 
-@quotation
 @lilypond[fragment,verbatim]
 \context Staff {
   \relative c' {
@@ -1453,7 +1491,6 @@ the specified number of repeats.
   }
 }
 @end lilypond
-@end quotation
 
 @refbugs
 
@@ -1551,10 +1588,15 @@ In the @code{percent} style, a note pattern can be repeated. It is
 printed once, and then the pattern is replaced with a special sign.
 
 @lilypond[verbatim,singleline]
- \context Voice { \repeat  "percent" 5  { c'1 } }  
+ \context Voice { \repeat  "percent" 4  { c'4 }
+    \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
+}
 @end lilypond
 
-At present, only repeats of whole measures are supported.
+@refbugs
+
+You can not nest percent repeats, filling in the first measure with
+slashes, and repeating that measure with percents.
 
 @node Rhythmic music
 @section Rhythmic music
@@ -1659,11 +1701,11 @@ context which is a direct child of the a context of type
 @cindex Pedals
 
 Piano pedal instruction can be expressed using 
-@code{\sustainDown}, @code{\sustainUp}, @code{\unaChorda},
-@code{\treChorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
+@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
+@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
 
-These identifiers are short hands for spanner commands of the types
-@code{Sustain}, @code{UnaChorda} and @code{Sostenuto}:
+These identifiers are shorthands for spanner commands of the types
+@code{Sustain}, @code{UnaCorda} and @code{Sostenuto}:
 
 @lilypond[fragment,verbatim]
 c''4 \spanrequest \start "Sustain" c''4 c''4 \spanrequest \stop "Sustain"
@@ -1692,17 +1734,14 @@ You can specify an arpeggio sign on a chord by attaching an
 @code{\arpeggio} to a note of the chord.
 
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \context Voice <c'\arpeggio e g c>
 @end lilypond
-@end quotation
 
 When an arpeggio crosses staffs in piano music, you attach an arpeggio
 to the chords in both staffs, and set
 @code{PianoStaff.connectArpeggios}.
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \context PianoStaff <
     \property PianoStaff.connectArpeggios = ##t
@@ -1710,7 +1749,6 @@ to the chords in both staffs, and set
     \context Voice = other { \clef bass;  <c,,\arpeggio e g>}
   >  
 @end lilypond
-@end quotation
 
 This command creates @code{Arpeggio} grobs. 
 
@@ -1734,7 +1772,6 @@ Whenever a voice switches to another staff a line connecting the notes
 can be printed automatically. This is enabled if the property
 @code{PianoStaff.followVoice} is set to true:
 
-@quotation
 @lilypond[fragment,relative,verbatim]
   \context PianoStaff <
     \property PianoStaff.followVoice = ##t
@@ -1746,7 +1783,6 @@ can be printed automatically. This is enabled if the property
     \context Staff=two {\clef bass; \skip 1*2;}
   >  
 @end lilypond
-@end quotation
 
 
 @c . {Lyrics}
@@ -2006,9 +2042,6 @@ must be separated by a dot (@code{.}).
 Throughout these examples, chords have been shifted around the staff
 using @code{\transpose}.
 
-
-@quotation
-
 @lilypond[fragment,verbatim]
 \transpose c'' {
   \chords {
@@ -2016,9 +2049,7 @@ using @code{\transpose}.
     c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
   }
 }
-
 @end lilypond
-@end quotation
 
 @cindex @code{aug}
 @cindex @code{dim}
@@ -2033,17 +2064,13 @@ raises the 5th, `@code{dim}' which lowers the 5th,
 `@code{maj}' which adds a raised 7th, and `@code{sus}'
 which replaces the 5th with a 4th.
 
-@quotation
-
 @lilypond[fragment,verbatim]
 \transpose c'' {
   \chords {
     c1:m c:min7 c:maj c:aug c:dim c:sus
   }
 }
-
 @end lilypond
-@end quotation
  
 
 Chord subtractions are used to eliminate notes from a chord.  The
@@ -2105,7 +2132,6 @@ For displaying printed chord names, use the @code{ChordNames} context.
 The chords may be entered either using the notation described above, or
 directly using simultaneous music.
 
-@quotation
 @lilypond[verbatim,singleline]
 scheme = \notes {
   \chords {a1 b c} <d f g>  <e g b>
@@ -2117,14 +2143,12 @@ scheme = \notes {
   >
 }
 @end lilypond
-@end quotation
 
 You can make the chord changes stand out by setting property
 @code{ChordNames.chordChanges} to true.  This will only display chord
 names when there's a change in the chords scheme and at the start of the
 line.
 
-@quotation
 @lilypond[verbatim]
 scheme = \chords {
   c1:m \break c:m c:m c:m d
@@ -2138,16 +2162,12 @@ scheme = \chords {
     \context Staff \transpose c'' \scheme
   > }
 @end lilypond
-@end quotation
 
 LilyPond examines chords specified as lists of notes to determine a name
 to give the chord. LilyPond will not try to identify chord inversions or
-added base, which may result in strange chord names when chords are
-entered as a list of pitches:
+an added bass note, which may result in strange chord names when chords
+are entered as a list of pitches:
 
-[base vs. bass ?]
-
-@quotation
 @lilypond[verbatim,center,singleline]
 scheme = \notes {
   <c'1 e' g'>
@@ -2157,12 +2177,11 @@ scheme = \notes {
 
 \score {
   <
-    \context ChordNamesVoice \scheme
+    \context ChordNames \scheme
     \context Staff \scheme
   >
 }
 @end lilypond
-@end quotation
 
 
 By default LilyPond uses chord name system proposed by Harald Banter
@@ -2174,9 +2193,33 @@ chordnames.
 
 Routines that determine the names to be printed are written in Scheme,
 and may be customized by the user.  The code can be found in
-@file{scm/chord-name.scm}.
+@file{scm/chord-name.scm}.  Here's an example showing the differences in
+chord name styles:
+
+@c too long?
+@c maybe just junk verbatim option?
+@lilypond[verbatim,singleline]
+scheme = \chords {
+  c1 c:5^3 c:4^3 c:5+
+  c:m7+ c:m5-.7
+  c:5-.7 c:5+.7
+  c:9^7
+}
+
+\score {
+  \notes <
+    \context ChordNames = banter \scheme
+    \context ChordNames = american {
+      \property ChordNames.ChordName \override
+        #'style = #'american \scheme }
+    \context ChordNames = jazz {
+      \property ChordNames.ChordName \override
+        #'style = #'jazz \scheme }
+    \context Staff \transpose c'' \scheme
+  >
+}
+@end lilypond
 
-[3 short examples showing differences between american, banter and jazz]
 
 @node Writing parts
 @section Writing parts
@@ -2257,7 +2300,21 @@ used, for the next ones @code{instr} is used.
 @end lilypond
 
 This requires  that you add the @code{Instrument_name_engraver} to the
-staff context.
+staff context. You can also  use markup texts:
+
+
+@lilypond[verbatim,singleline]
+#(define text-flat
+  '((font-relative-size . -2 ) (music "accidentals--1")))
+
+\score { \notes {
+  \property Staff.instrument = #`((kern . 0.5) (lines
+    "2 Clarinetti" (rows "     (B" ,text-flat ")")))
+    c'' 4 }
+  \paper { 
+    \translator { \StaffContext
+    \consists "Instrument_name_engraver"; } } }
+@end lilypond
 
 
 @node Transpose
@@ -2280,7 +2337,6 @@ This means that middle C in @var{musicexpr} is transposed to
 a tone.  The first version will print sharps and the second version
 will print flats.
 
-@quotation
 @lilypond[fragment,verbatim]
 \context Staff {
   \clef "F";
@@ -2289,9 +2345,7 @@ will print flats.
   \transpose des'' { \key e \major; c d e f }
   \transpose cis'' { \key e \major; c d e f }
 }
-
 @end lilypond
-@end quotation
 
 If you want to use both @code{\transpose} and @code{\relative}, then
 you must use @code{\transpose} first.  @code{\relative} will have no
@@ -2355,22 +2409,20 @@ The syntax for part combining is
 @end example
 
 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
-combined into one context @var{context}.  The names of the music
+combined into one context @var{context}.  The context names of the music
 expressions must start with the prefixes @code{one} and @code{two}.
 
-[Name of music expressions?  is that context name? ]
-
 The most useful function of the part combiner to combining threads into
 one voice, as common for wind parts in orchestral scores:
 
 @lilypond[verbatim,singleline,fragment]
   \context Staff <
     \context Voice=one \partcombine Voice
-      \context Thread=one \notes\relative c'' {
-        g g a b r2
+      \context Thread=one \relative c'' {
+        g a b r
       }
-      \context Thread=two \notes\relative c'' {
-        g g r2 g4 f4
+      \context Thread=two \relative c'' {
+        g r2 f4
       }
   >
 @end lilypond
@@ -2383,11 +2435,44 @@ while @code{two} always gets down stems and "Solo II".
 
 If you just want the splitting of Threads and setting of directions, and
 not the textual markings, you may set the property @var{soloADue} to
-false. There are a number of other properties that you can use to tweak
+false.  This mode can be used to set hymns:
+
+@lilypond[verbatim,singleline,fragment]
+  \context Staff <
+    \property Staff.soloADue = ##f
+    \context Voice=one \partcombine Voice
+      \context Thread=one \relative c'' {
+        b4 a c g
+      }
+      \context Thread=two \relative c'' {
+        d,2 a4 g'
+      }
+  >
+@end lilypond
+
+There are a number of other properties that you can use to tweak
 the behavior of part combining, refer to the automatically generated
 documentation. Look for @code{Thread_devnull_engraver}
 @code{Voice_devnull_engraver} and @code{A2_engraver}. 
 
+@refbugs
+
+In @code{soloADue} mode, when the two voices play the same notes on and
+off, the part combiner may typeset @code{a2} more than once in a
+measure.
+
+@lilypond[fragment,singleline]
+  \context Staff <
+    \context Voice=one \partcombine Voice
+      \context Thread=one \relative c'' {
+        c b c b c a c a
+      }
+      \context Thread=two \relative c'' {
+        b b b b f a f a
+      }
+  >
+@end lilypond
+
 @cindex @code{Thread_devnull_engraver}
 @cindex @code{Voice_engraver}
 @cindex @code{A2_engraver}
@@ -2395,11 +2480,31 @@ documentation. Look for @code{Thread_devnull_engraver}
 @node Hara-kiri staffs
 @subsection Hara-kiri staffs
 
+In orchestral scores, staffs that only have rests are usually removed.
+This saves some space.  LilyPond also supports this through the
+hara-kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide
+of the Japanese Samourai warriors.} staff. This staff commits suicide
+when it finds itself to be empty after the line-breaking process---note
+that it will not disappear when it contains normal rests, you must use
+multi measure rests.
+
+The hara kiri staff is specialized version of the Staff context. It is
+available as the context identifier @code{\HaraKiriStaffContext}.
+Observe how the second staff in this example disappears in the second
+line.
 
-[TODO]
-
-@footnote{Harakiri, also called Seppuku, is the ritual suicide of
-the Japanese Samourai warriors.}
+@lilypond[verbatim]
+\score  {
+  \notes \relative c' <
+    \context Staff = SA { e4 f g a \break c1 }
+    \context Staff = SB { c4 d e f \break R1 }
+  >
+  \paper {
+    linewidth = 6.\cm ; 
+    \translator { \HaraKiriStaffContext }
+  }
+}
+@end lilypond
 
 
 
@@ -2415,7 +2520,6 @@ anticipates the pitch of the first note(s) of the following line and
 thus helps the player or singer to manage line breaks during
 performance, thus enhancing readability of a score.
 
-@quotation
 @lilypond[verbatim]
 \score {
   \notes { c'1 d' e' d' \break c' d' e' d' }
@@ -2428,7 +2532,6 @@ performance, thus enhancing readability of a score.
   }
 }
 @end lilypond
-@end quotation
 
 Custodes were frequently used in music notation until the 16th century.
 There were different appearences for different notation styles.
@@ -2488,7 +2591,9 @@ grob property.
 * Tuning groups of grobs ::     
 * Tuning per grob ::            
 * What to tune?::               
+* Font selection::              
 * Text markup::                 
+* Embedded @TeX{}::             
 @end menu
 
 @node Tuning groups of grobs 
@@ -2501,12 +2606,17 @@ property.  By assigning to that property (using plain @code{\property}),
 you can change the resulting grobs.
 
 @lilypond[verbatim, fragment]
-c'4 \property Voice.Stem \override #'meta = #'((interfaces . ())) c'4
+c'4 \property Voice.Stem  = #'((meta . ((interfaces . ())))) c'4
 @end lilypond
 
-The @code{\property} statement effectively empties the definition of the
-Stem object. One of the effects is that property specifying how it
+The @code{\property} assignment effectively empties the definition of
+the Stem object. One of the effects is that property specifying how it
 should be printed is erased, with the effect of rendering it invisible.
+The above assignment is available as a standard identifier, lest you
+find this useful:
+@example
+  \property Voice.Stem = \turnOff
+@end example
 
 @cindex \override
 @cindex \revert
@@ -2551,9 +2661,35 @@ Formally the syntax for these constructions is
 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
 and @var{grobname} are strings and @var{value} is a Scheme expression.
 
+If you want to be
+Correct nesting of @code{\override}, @code{\set}, @code{\revert} is as
+follows
+
+@example 
+\override \set \set \set \set
+\revert
+@end example
+
+This is always correct, but if you know the default value, you can also use 
+@example
+\set \set \set \set
+\set @var{to default value}
+@end example
+
+If there is no default (i.e. by default, the grob property is unset),
+then you can use
+@example
+\set \set \set \set \set
+\revert
+@end example
+
+
 @refbugs
 
 LilyPond will hang or crash if @var{value} contains cyclic references.
+The backend is not very strict in type-checking grob properties. If you
+@code{\revert} properties that are expected to be set by default,
+LilyPond may crash.
 
 
 
@@ -2646,6 +2782,85 @@ There is also a master list of contexts. Clicking each takes you to an
 overview of the context, listing which grob types are created there.
 
 
+@node Font selection
+@subsection Font selection
+
+Most graphics in LilyPond are composed of characters of fonts.  You can
+alter the characteristics of the font by setting certain grob
+properties. The mechanism that is used for this resembles LaTeX's New
+Font Selection Scheme. Within this scheme, a font is entirely
+characterized by its font name.
+
+For each grob that uses fonts (in other words, each grob that supports
+@code{font-interface}) a font-name must be selected before it can be
+printed.  The font name is selected by looking at a number of grob
+properties:
+
+@table @code
+@item font-family
+  The general class of the typeface.  Supported are roman (Computer
+Modern), braces (for piano staff braces), music (the standard music
+font), dynamic (font for dynamic signs) and typewriter
+
+@item font-shape
+  A symbol indicating the shape of the font, a finer gradation than
+  font-family. Choices are italic and upright
+@item font-series
+  Symbol indicating the serie of the font.  Series form a finer gradation
+  than font-shape. Choices are medium and bold.
+
+@item font-relative-size
+  A number indicating the size relative the standard size.  For example,
+  with 20pt staff height, relative size -1  corresponds to 16pt staff
+  height, and relative size +1 corresponds to 23 pt staff height.
+
+@item font-design-size
+A number indicating  the design size of the font. 
+
+This is a feature of the Computer Modern Font: each point size has a
+slightly different design. Smaller design sizes are relatively wider,
+which enhances readability. Scalable type faces such TrueType and Adobe
+Type1 usually come as ``one design fits all sizes''.
+
+@item font-name
+  The name of the font, without the design size, eg. @code{cmr},
+@code{cmti}, etc. Setting this overrides font-family, font-shape and
+font-series.
+
+@end table
+
+The font is selected by taking the first font that satisfies all
+qualifiers specified. You can override any of these fields through
+@code{\override} and @code{\revert}. The special value @code{*} matches
+any value for that qualifier.
+
+@example
+  \property Lyrics.LyricText \override #'font-series = #'bold
+  \property Lyrics.LyricText \override #'font-shape = #'*
+@end example
+
+@cindex @code{font-style}
+
+There are also pre-cooked font selection qualifiers. These are selected
+through the grob property @code{font-style}.  For example, the style
+@code{finger} selects family @code{number} and relative size @code{-3}.
+Styles available include: volta, finger, tuplet, timesig, mmrest,
+script, large, Large and dynamic.
+
+The style sheets and tables for selecting fonts are located in
+@file{scm/font.scm}. Refer to this file for more information.
+
+@refbugs
+
+Relative size is not linked to any real size.  There is no mechanism to
+select magnifications of fonts, meaning that you can not scale fonts
+continuoussly. There is no style sheet provided for other fonts besides
+the @TeX{} family.
+
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
+
 
 @node Text markup
 @subsection Text markup
@@ -2656,16 +2871,16 @@ LilyPond has an internal mechanism to typeset texts. You can
 form text markup expressions by composing scheme expressions
 in the following way.
 
-
-[BUG]
-
 @lilypond[verbatim, singleline]
  \relative c' {
-    b_#"italic"
-    c^#'(upright "upright")
-    c_#'((bold upright) "bold")
-    d^#'(lines "one" ((bold upright) "two"))
-    e_#'(music (named "noteheads-2" "flags-u3"))
+    \fatText
+    a^#"upright"
+    b_#'(bold "bold")
+    c^#'(italic "italic")
+    d_#'((bold italic) "ff")
+    e^#'(dynamic "ff")
+    f_#'(lines "one" (bold "two"))
+    g^#'(music "noteheads-2" "flags-u3")
   }
 @end lilypond
 
@@ -2675,17 +2890,17 @@ of a grob.  Formally, it is defined as follows:
 @example
 text: string | (head? text+)
 head: markup | (markup+)
-markup-item: property | abbrev | @var{fontstyle}
+markup-item: property | abbrev
 property: (@var{key} . @var{value})
 abbrev: @code{rows lines roman music bold italic named super sub text}
+        @code{finger volta timesig mmrest mark script large Large dynamic}
 @end example
 
 The markup is broken down and converted into a list of grob properties,
 which are prepended to the property list.  The @var{key}-@var{value}
 pair is a grob property.
 
-The following abbreviations are currently
-defined:
+The following abbreviations are currently defined:
 
 @table @code
 @item rows
@@ -2708,19 +2923,96 @@ horizontal mode: set all text on one line (default)
  superscript
 @item sub
  subscript
+@item finger
+ select fingering number fontstyle
+@item volta
+ select volta number fontstyle
+@item timesig
+ select time signature number fontstyle
+@item mmrest
+ select multi measure rest number fontstyle
+@item mark
+ select mark number fontstyle
+@item script
+ select scriptsize roman fontstyle
+@item large
+ select large roman fontstyle
+@item Large
+ select Large roman fontstyle
+@item dynamic
+ select dynamics fontstyle
 @end table
 
-@var{fontstyle} may be any of @code{finger volta timesig mmrest mark
-script large Large dynamic}
-
-[wat is het verschil tussen fontstyle en abbrev?]
-
-
 It is possible to use @TeX{} commands in the strings, but this should be
 avoided because this makes it impossible for LilyPond to compute the
 exact length of the string, which may lead to collisions.  Also, @TeX{}
 commands won't work with direct postscript output.
 
+@cindex metronome mark
+
+One practical application of complicated markup is to fake a metronome
+marking:
+
+@lilypond[verbatim]
+#(define note '(rows
+  (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
+#(define eight-note `(rows ,note ((kern . -0.1)
+  (music ((raise . 3.5) "flags-u3")))))
+#(define dotted-eight-note
+  `(rows ,eight-note (music "dots-dot")))
+
+\score {
+  \notes\relative c'' {
+    a1^#`((rows (font-relative-size . -1)) ,dotted-eight-note " = 64")
+  }
+  \paper {
+    linewidth = -1.;
+    \translator{
+      \ScoreContext
+      TextScript \override #'font-shape = #'upright
+    }
+  }
+}
+@end lilypond
+
+@node Embedded @TeX{}
+@subsection Embeded @TeX{}
+@cindex embedded tex
+@cindex embedded tex
+
+You can use @TeX{} commands in text scripts, but this should be avoided
+because this makes it impossible for LilyPond to compute the exact
+length of the string, which may lead to collisions.  Also, @TeX{}
+commands won't work with direct PostScript output.
+
+@lilypond[fragment,relative,verbatim]
+  a''^"3 $\\times$ \\`a deux"
+@end lilypond
+
+@subsection Embedded PostScript
+@cindex embedded postscript
+@cindex embedded postscript
+
+You can also use raw PostScript commands embedded in text scripts.  This
+offers ultimate flexibitily, but you'll have to learn the arcane
+PostScript language.  Currently, embedded PostScript will @strong{not}
+work with direct PostScript output.  Note that all dimensions that you
+use are in @code{staff-space}s.
+
+@lilypond[verbatim]
+\score {
+  \notes \relative c'' {
+    a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
+    -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
+    b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
+    s2
+    a'1
+  }
+  \paper { linewidth = 70 * \staffspace; }
+}
+@end lilypond
+
+
 @c . {Page layout}
 @node Page layout
 @section Page layout
@@ -2762,7 +3054,7 @@ where each of the items is one of
        @end example
 
         See @file{scm/font.scm} for details of @var{alist}.
-@item an \elementdescriptions declaration.
+  @item an \elementdescriptions declaration.
         @example
                 \elementdescriptions @var{alist}
         @end example
@@ -2793,8 +3085,10 @@ use either this or @code{stafflinethickness}
   @item @code{linewidth}  
     Sets the width of the lines.
 
-If set to a negative value, a single
-    unjustified line is produced.
+If set to a negative value, a single unjustified line is produced.
+@c rename to singleLinePaper ?
+The shorthand @code{\singleLine} defines a default paper block that
+produces a single line.
 
 @cindex @code{textheight}
 
@@ -2944,13 +3238,25 @@ details, see the example file @file{input/test/between-systems.ly}
 @cindex Sound
 
 LilyPond can produce MIDI output.  The performance lacks lots of
-interesting effects, such as swing, articulation, slurring, tieing,
-etc., but it is good enough for proof-hearing the music you enter.
-
-Dynamics and tempo changes are interpreted.
-
-[TODO: mention volume control/Instrument Equaliser]
-
+interesting effects, such as swing, articulation, slurring, etc., but it
+is good enough for proof-hearing the music you have entered.  Ties,
+dynamics and tempo changes are interpreted.
+
+The MIDI volume is composed of two elements: the current dynamics of the
+voice and the type of musical instrument.
+
+Dynamic marks, crescendi and decrescendi translate into MIDI volume
+levels.  Dynamic marks translate to a fixed fraction of the available
+MIDI volume range, crescendi and decrescendi make the the volume vary
+linearly between their two extremities.  The fractions be adjusted by
+overriding the @code{absolute-volume-alist} defined in
+@file{scm/midi.scm}.
+
+For each type of musical instrument (that MIDI supports), a volume range
+can be defined.  This gives you basic equaliser control, which can
+enhance the quality of the MIDI output remarkably.  You can add
+instruments and ranges or change the default settings by overriding
+the @code{instrument-equaliser-alist} defined in @file{scm/midi.scm}.
 
 @refbugs
 
@@ -3112,8 +3418,6 @@ relocated, so this can also be used to shorten measures.
 
 A bar check is entered using the bar symbol, @code{|}
 
-
-
 @c .  {Point and click}
 @node Point and click
 @subsection Point and click
@@ -3157,7 +3461,7 @@ package) to @file{emacsclient.c} and @file{server.el} from the emacs
 source code. Recompile and stick the recompiled emacsclient into a bin
 directory, and put @file{server.el} into a elisp directory
 (eg. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
-init file, beifore invoking server-start.
+init file, before invoking server-start.
 
 @example
  (setq load-path (cons "~/usr/share/emacs" load-path))
@@ -3182,6 +3486,24 @@ will complain about not finding @code{src:X:Y} files. Those complaints are
 harmless, and can be ignored.
 
 
+@node Skipping corrected music
+@section Skipping corrected music
+
+The property @code{Score.skipTypesetting} can be used to switch on and
+off typesetting completely during the interpretation phase. When
+typesetting is switched off, the music is processed much more quickly.
+You can use this to skip over the parts of a score that you have already
+checked for errors. 
+
+@lilypond[fragment,singleline,verbatim]
+\relative c'' { c8 d
+\property Score.skipTypesetting = ##t
+  e f g a g c, f e d
+\property Score.skipTypesetting = ##f
+c d b bes a g c2 } 
+@end lilypond
+
+
 @node Interpretation context
 @section Interpretation context
 
@@ -3245,8 +3567,6 @@ This instructs lilypond to interpret @var{musicexpr} within the context
  of type @var{contexttype} and with name @var{contextname}.  If this
 context does not exist, it will be created.  
 
-@quotation
-
 @lilypond[verbatim,singleline]
 \score {
   \notes \relative c'' {
@@ -3255,7 +3575,6 @@ context does not exist, it will be created.
 }
 
 @end lilypond
-@end quotation
 
 In this example, the @code{c} and @code{d} are printed on the
 default staff.  For the @code{e}, a context Staff called
@@ -3508,7 +3827,6 @@ be used as the very first item of a translator.  In order to define
 such an identifier outside of @code{\score}, you must do
 
 @quotation
-
 @example 
 \paper @{
   foo = \translator @{ @dots{} @}
@@ -3728,7 +4046,8 @@ This means that @var{func} is applied to @var{music}.  The function
 This example replaces the text string of a script. It also shows a dump
 of the music it processes, which is useful if you want to know more
 about how music is stored.
-@lilypond[verbatim]
+
+@lilypond[verbatim,singleline]
 #(define (testfunc x)
         (if (equal? (ly-get-mus-property x 'text) "foo")
                 (ly-set-mus-property x 'text "bar"))
@@ -3743,15 +4062,36 @@ about how music is stored.
 } 
 @end lilypond
 
-For more information on what is possible, see the @ref{Tricks} and the
-automatically generated documentation.
+For more information on what is possible, see the automatically
+generated documentation.
 
 
 Directly accessing internal representations is dangerous: the
 implementation is subject to changes, so you should avoid this feature
 if possible.
-  
-  
+
+A final example is a function that reverses a piece of music in time:
+
+@lilypond[verbatim,singleline]
+#(define (reverse-music music)
+  (let* ((elements (ly-get-mus-property music 'elements))
+         (reversed (reverse elements))
+         (span-dir (ly-get-mus-property music 'span-direction)))
+    (ly-set-mus-property music 'elements reversed)
+    (if (dir? span-dir)
+        (ly-set-mus-property music 'span-direction (- span-dir)))
+    (map reverse-music reversed)
+    music))
+
+music = \notes { c'4 d'4( e'4 f'4 }
+
+\score { \context Voice {
+    \music
+    \apply #reverse-music \music
+  }
+}
+@end lilypond
+
 
 @c .   {Span requests}
 @menu