]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/basic-notation.itely
Merge branch 'master' of ssh+git://hanwen@git.sv.gnu.org/srv/git/lilypond
[lilypond.git] / Documentation / user / basic-notation.itely
index f4590459a83eaa342aa62fa7644f6a0aefc25269..e17f3e480f4a9b3f17fc47eade0c293194d5349e 100644 (file)
@@ -1,5 +1,12 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
+
 
 @c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update
@@ -13,7 +20,7 @@ This chapter explains how to use basic notation features.
 @menu
 * Pitches::                     
 * Rhythms::                     
-* Multiple notes at once::      
+* Polyphony::                   
 * Staff notation::              
 * Connecting notes::            
 * Expressive marks::            
@@ -32,7 +39,7 @@ This section discusses how to specify the pitch of notes.
 * Accidentals::                 
 * Cautionary accidentals::      
 * Micro tones::                 
-* Notes names in other languages::  
+* Note names in other languages::  
 * Relative octaves::            
 * Octave check::                
 * Transpose::                   
@@ -64,13 +71,13 @@ c1
 c1
 @end lilypond
 
-@findex '
-@findex ,
+@funindex '
+@funindex ,
 
 The optional octave specification takes the form of a series of
-single quote (`@code{'}') characters or a series of comma
-(`@code{,}') characters.  Each @code{'} raises the pitch by one
-octave; each @code{,} lowers the pitch by an octave.
+single quote (@samp{'}) characters or a series of comma
+(@samp{,}) characters.  Each @samp{'} raises the pitch by one
+octave; each @samp{,} lowers the pitch by an octave.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 \clef treble
@@ -92,20 +99,21 @@ octave specifications (@code{'} and @code{,}).  See
 @cindex note names, default
 
 A sharp is formed by adding @code{-is} to the end of a pitch name and
-a flat is formed by adding @code{-es}
+a flat is formed by adding @code{-es}.  Double sharps and double flats
+are obtained by adding @code{-isis} or @code{-eses} to a note name.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 a2 ais a aes
+a2 aisis a aeses
 @end lilypond
 
-Double sharps and double flats
-are obtained by adding @code{-isis} or @code{-eses} to a note name.  These
-are the Dutch note names.  In Dutch, @code{aes} is contracted to
+@noindent
+These are the Dutch note names.  In Dutch, @code{aes} is contracted to
 @code{as}, but both forms are accepted.  Similarly, both
 @code{es} and @code{ees} are accepted
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-a2 aisis a aeses
+a2 as e es
 @end lilypond
 
 A natural will cancel the effect of an accidental or key signature.
@@ -116,6 +124,18 @@ suffix; a natural pitch is shown as a simple note name
 a4 aes a2
 @end lilypond
 
+The input @code{d e f} is interpreted as @q{print a D-natural,
+E-natural, and an F-natural,} regardless of the key
+signature.  For more information about the distinction between
+musical content and the presentation of that content, see
+@ref{Accidentals and key signatures}.
+
+@lilypond[fragment,quote,ragged-right,verbatim,relative]
+\key d \major
+d e f g
+d e fis g
+@end lilypond
+
 
 @commonprop
 
@@ -144,17 +164,17 @@ Program reference: @internalsref{LedgerLineSpanner},
 @cindex accidental, cautionary
 @cindex accidental, parenthesized
 @cindex reminder accidental
-@findex ?
+@funindex ?
 @cindex cautionary accidental
 @cindex parenthesized accidental
-@findex !
+@funindex !
 
 Normally accidentals are printed automatically, but you may also
 print them manually.  A reminder accidental
 can be forced by adding an exclamation mark @code{!}
 after the pitch.  A cautionary accidental
 (i.e., an accidental within parentheses) can be obtained by adding the
-question mark `@code{?}' after the pitch.  These extra accidentals
+question mark @samp{?} after the pitch.  These extra accidentals
 can be used to produce natural signs, too.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
@@ -192,8 +212,8 @@ three-quarter flats, so LilyPond's symbol does not conform to any
 standard.
 
 
-@node Notes names in other languages
-@subsection Notes names in other languages
+@node Note names in other languages
+@subsection Note names in other languages
 
 There are predefined sets of note names for various other languages.
 To use them, include the language specific init file.  For
@@ -201,24 +221,60 @@ example, add @code{\include "english.ly"} to the top of the input
 file.  The available language files
 and the note names they define are
 
-@c  what about micro-tunes, double-sharps, and double-flats?  add
-@c  more clumns to the table?
-@c  Oh, and should this be made into a multitable?
+@c  Should this be made into a multitable?
 @cindex note names, other languages
 @example
-                        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
-italiano.ly    do  re  mi  fa  sol la  sib si  -d          -b
-catalan.ly     do  re  mi  fa  sol la  sib si  -d/-s       -b
-espanol.ly     do  re  mi  fa  sol la  sib si  -s          -b
+                        Note Names               sharp       flat     double        double
+                                                                       sharp        flat
+
+nederlands.ly  c   d   e   f   g   a   bes b   -is         -es       -isis         -eses
+english.ly     c   d   e   f   g   a   bf  b   -s/-sharp   -f/-flat  -ss/-x/       -ff/
+                                                                     -sharpsharp   -flatflat
+deutsch.ly     c   d   e   f   g   a   b   h   -is         -es       -isis         -eses
+norsk.ly       c   d   e   f   g   a   b   h   -iss/-is    -ess/-es  -ississ/-isis -essess/-eses
+svenska.ly     c   d   e   f   g   a   b   h   -iss        -ess      -ississ       -essess
+italiano.ly    do  re  mi  fa  sol la  sib si  -d          -b        -dd           -bb
+catalan.ly     do  re  mi  fa  sol la  sib si  -d/-s       -b        -dd/-ss       -bb
+espanol.ly     do  re  mi  fa  sol la  sib si  -s          -b        -ss           -bb
+@end example
+
+@noindent
+Note that in Dutch, German, Norwegian, and Swedish, the flat
+alterations of @samp{a} like for example @code{aes} and @code{aeses}
+are usually contracted to @code{as} and @code{ases} (or more commonly
+@code{asas}). Sometimes only these contracted names are defined in the
+corresponding language files (this also applies to the suffixes for
+quartertones below).
+
+@noindent
+Some music uses microtones whose alterations are fractions of a
+@q{regular} sharp or flat. The note names for quartertones defined in
+the various language files are listed in the following table. Here the
+prefixes @q{semi-} and @q{sesqui-} mean @q{half} and @q{one and a
+half}, respectively. For Norwegian, Swedish, Catalan and Spanish no
+special names have been defined yet.
+@c What about Turkish Maquam music and similar microtonal systems?
+@c
+@c Note that the term "three-quarter-sharp/-flat" used in lilypond's source code 
+@c is actually misleading since the alteration is in fact one and a half
+@c of a regular sharp/flat. Whence the naming "sesqui-sharp/-flat" used below.
+
+@example
+                        Note Names             semi-   semi-  sesqui-  sesqui-
+                                               sharp   flat    sharp    flat
+
+nederlands.ly  c   d   e   f   g   a   bes b   -ih     -eh    -isih    -eseh
+english.ly     c   d   e   f   g   a   bf  b   -qs     -qf    -tqs     -tqf
+deutsch.ly     c   d   e   f   g   a   b   h   -ih     -eh    -isih    -eseh
+norsk.ly       c   d   e   f   g   a   b   h   
+svenska.ly     c   d   e   f   g   a   b   h   
+italiano.ly    do  re  mi  fa  sol la  sib si  -sd     -sb    -dsd     -bsb
+catalan.ly     do  re  mi  fa  sol la  sib si  
+espanol.ly     do  re  mi  fa  sol la  sib si  
 @end example
 
 
+
 @node Relative octaves
 @subsection Relative octaves
 
@@ -270,6 +326,7 @@ Here is the relative mode shown in action
 @end lilypond
 
 Octave changing marks are used for intervals greater than a fourth
+
 @lilypond[quote,ragged-right,fragment,verbatim]
 \relative c'' {
   c g c f, c' a, e''
@@ -287,7 +344,7 @@ to determine the first note of the next chord
 }
 @end lilypond
 
-The pitch after the @code{\relative} contains a note name.
+The pitch after @code{\relative} contains a note name.
 
 The relative conversion will not affect @code{\transpose},
 @code{\chordmode} or @code{\relative} sections in its argument.  To use
@@ -321,11 +378,13 @@ There is also an octave check that produces no visible output.  The syntax
 @end example
 
 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
-quotes) in @code{\relative} mode.  If not, a warning is printed, and the
+quotes) in @code{\relative} mode compared to the note given in the
+@code{\relative} command.  If not, a warning is printed, and the
 octave is corrected.  The @var{pitch} is not printed as a note.
 
 In the example below, the first check passes without incident, since
-the @code{e} (in relative mode) is within a fifth of @code{a'}.  However,
+the @code{e} (in @code{relative} mode) is within a fifth of
+@code{a'}.  However,
 the second check produces a warning, since the @code{e} is not within
 a fifth of @code{b'}.  The warning message is printed, and the octave
 is adjusted so that the following notes are in the correct octave
@@ -360,7 +419,7 @@ the output of the piece.
 
 @cindex Transpose
 @cindex Transposition of pitches
-@findex \transpose
+@funindex \transpose
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
@@ -406,7 +465,7 @@ mus = { \key d \major cis d fis g }
 
 @code{\transpose} may also be used to input written notes for a
 transposing instrument.  Pitches are normally entered into LilyPond
-in C (or ``concert pitch''), but they may be entered in another
+in C (or @q{concert pitch}), but they may be entered in another
 key.  For example, when entering music for a B-flat trumpet which
 begins on concert D, one would write
 
@@ -414,7 +473,7 @@ begins on concert D, one would write
 \transpose c bes @{ e4 @dots{} @}
 @end example
 
-To print this music in B-flat again (i.e. producing a trumpet part,
+To print this music in B-flat again (i.e., producing a trumpet part,
 instead of a concert pitch conductor's score) you would wrap the
 existing music with another @code{transpose}
 
@@ -427,12 +486,14 @@ existing music with another @code{transpose}
 
 Program reference: @internalsref{TransposedMusic}.
 
+Example: @inputfileref{input/@/test,smart@/-transpose@/.ly}.
+
 
 @refbugs
 
 If you want to use both @code{\transpose} and @code{\relative},
 you must put @code{\transpose} outside of @code{\relative}, since
-@code{\relative} will have no effect music that appears inside a
+@code{\relative} will have no effect on music that appears inside a
 @code{\transpose}.
 
 
@@ -440,8 +501,8 @@ you must put @code{\transpose} outside of @code{\relative}, since
 @subsection Rests
 @cindex Rests
 
-@findex \rest
-@findex r
+@funindex \rest
+@funindex r
 
 Rests are entered like notes with the note name @code{r}
 
@@ -478,11 +539,11 @@ Program reference: @internalsref{Rest}.
 @cindex Skip
 @cindex Invisible rest
 @cindex Space note
-@findex \skip
-@findex s
+@funindex \skip
+@funindex s
 
-An invisible rest (also called a `skip') can be entered like a note
-with note name `@code{s}' or with @code{\skip @var{duration}}
+An invisible rest (also called a @q{skip}) can be entered like a note
+with note name @samp{s} or with @code{\skip @var{duration}}
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 a4 a4 s4 a4 \skip 1 a4
@@ -538,16 +599,16 @@ This section discusses rhythms, durations, and bars.
 @subsection Durations
 
 @cindex duration
-@findex \longa
-@findex \breve
-@findex \maxima
+@funindex \longa
+@funindex \breve
+@funindex \maxima
 
 In Note, Chord, and Lyrics mode, durations are designated by numbers and
 dots: durations are entered as their reciprocal values.  For example, a
 quarter note is entered using a @code{4} (since it is a 1/4 note), while
 a half note is entered using a @code{2} (since it is a 1/2 note).  For
-notes longer than a whole you must use the variables @code{\longa} and
-@code{\breve}
+notes longer than a whole you must use the @code{\longa} and
+@code{\breve} commands
 
 @example
 c'\breve
@@ -568,6 +629,11 @@ r1 r2 r4 r8 r16 r32 r64 r64
   }
   \layout {
     ragged-right = ##t
+    indent=0\mm
+    \context {
+      \Score
+        \remove "Bar_number_engraver"
+    }
     \context {
       \Staff
         \remove "Clef_engraver"
@@ -591,9 +657,9 @@ duration.  The default for the first note is a quarter note.
 @node Augmentation dots
 @subsection Augmentation dots
 
-@findex .
+@funindex .
 
-To obtain dotted note lengths, simply add a dot (`@code{.}') to
+To obtain dotted note lengths, simply add a dot (@samp{.}) to
 the number.  Double-dotted notes are produced in a similar way.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
@@ -606,11 +672,11 @@ Dots are normally moved up to avoid staff lines, except in polyphonic
 situations.  The following commands may be used to force a particular
 direction manually
 
-@findex \dotsUp
+@funindex \dotsUp
 @code{\dotsUp},
-@findex \dotsDown
+@funindex \dotsDown
 @code{\dotsDown},
-@findex \dotsNeutral
+@funindex \dotsNeutral
 @code{\dotsNeutral}.
 
 @seealso
@@ -623,7 +689,7 @@ Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
 
 @cindex tuplets
 @cindex triplets
-@findex \times
+@funindex \times
 
 Tuplets are made out of a music expression by multiplying all durations
 with a fraction
@@ -646,7 +712,7 @@ g'4 \times 2/3 {c'4 c' c'} d'4 d'4
 Tuplets may be nested, for example,
 
 @lilypond[fragment,ragged-right,verbatim,relative=2]
-\set tupletNumberFormatFunction = #fraction-tuplet-formatter
+\override TupletNumber #'text = #tuplet-number::calc-fraction-text
 \times 4/6 {
   a4 a
   \times 3/5 { a a a a a }
@@ -655,17 +721,17 @@ Tuplets may be nested, for example,
 
 @refcommands
 
-@findex \tupletUp
+@funindex \tupletUp
 @code{\tupletUp},
-@findex \tupletDown
+@funindex \tupletDown
 @code{\tupletDown},
-@findex \tupletNeutral
+@funindex \tupletNeutral
 @code{\tupletNeutral}.
 
 
 @commonprop
 
-@findex tupletNumberFormatFunction
+@funindex tupletNumberFormatFunction
 @cindex tuplet formatting
 
 The property @code{tupletSpannerDuration} specifies how long each
@@ -683,11 +749,10 @@ used once
 For more information about @code{make-moment}, see
 @ref{Time administration}.
 
-The format of the number is determined by the property
-@code{tupletNumberFormatFunction}.  The default prints only the
-denominator, but if it is set to the Scheme function
-@code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
-instead.
+The format of the number is determined by the property @code{text} in
+@code{TupletNumber}.  The default prints only the denominator, but if
+it is set to the function @code{tuplet-number::calc-fraction-text},
+@var{num}:@var{den} will be printed instead.
 
 To avoid printing tuplet numbers, use
 
@@ -697,25 +762,88 @@ To avoid printing tuplet numbers, use
 \times 2/3 { c8 c c } \times 2/3 { c8 c c }
 @end lilypond
 
+Use the @code{\tweak} function to override nested tuplets beginning at the
+same music moment.  In this example, @code{\tweak} specifies fraction
+text for the
+outer @code{TupletNumber} and denominator text for the @code{TupletNumber}
+of the first of the three inner tuplets.
+
+@lilypond[quote,ragged-right,verbatim]
+\new Staff {
+  \tweak #'text #tuplet-number::calc-fraction-text
+  \times 4/3 {
+     \tweak #'text #tuplet-number::calc-denominator-text
+     \times 2/3 { c'8[ c'8 c'8] }
+     \times 2/3 { c'8[ c'8 c'8] }
+     \times 2/3 { c'8[ c'8 c'8] }
+  }
+}
+@end lilypond
+
+Here @code{\tweak} and @code{\override} work together to specify
+@code{TupletBracket} direction.  The first @code{\tweak} positions
+the @code{TupletBracket} of the outer
+tuplet above the staff.  The second @code{\tweak} positions the
+@code{TupletBracket} of the first of the three inner tuplets below the
+staff.  Note that this pair of @code{\tweak} functions affects only
+the outer tuplet and the first of the three inner tuplets because only
+those two tuplets begin at the same music moment.  We use @code{\override}
+in the usual way to position the @code{TupletBrackets} of
+the second and third of the inner tuplets below the staff.
+
+@lilypond[quote,ragged-right,verbatim]
+\new Staff {
+  \tweak #'text #tuplet-number::calc-fraction-text
+  \tweak #'direction #up
+  \times 4/3 {
+     \tweak #'direction #down
+     \times 2/3 { c'8[ c'8 c'8] }
+     \override TupletBracket #'direction = #down
+     \times 2/3 { c'8[ c'8 c'8] }
+     \times 2/3 { c'8[ c'8 c'8] }
+  }
+}
+@end lilypond
+
+Tuplet brackets can be made to run to prefatory matter or
+the next note
+
+@lilypond[ragged-right]
+\new RhythmicStaff {
+  \set tupletFullLength = ##t
+  \time 4/4
+  \times 4/5 {
+    c4 c1
+  }
+  \set tupletFullLengthNote = ##t
+  \time 2/4
+  \times 2/3 {
+    c4 c c 
+  }
+  \time 3/4
+  c4 
+}
+@end lilypond
+
 
 @seealso
 
 Program reference: @internalsref{TupletBracket},
 @internalsref{TupletNumber}, and @internalsref{TimeScaledMusic}.
 
-Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
-
 
 
 @node Scaling durations
 @subsection Scaling durations
 
 You can alter the length of duration by a fraction @var{N/M}
-appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}).  This
-will not affect the appearance of the notes or rests produced.
+appending @samp{*@var{N/M}} (or @samp{*@var{N}} if @var{M=1}).  This
+will not affect the appearance of the notes or rests produced.  These
+may be combined such as @samp{*M*N}.
 
 In the following example, the first three notes take up exactly two
 beats, but no triplet bracket is printed.
+
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \time 2/4
 a4*2/3 gis4*2/3 a4*2/3
@@ -726,18 +854,18 @@ b16*4 c4
 
 @seealso
 
-This manual: @ref{Tuplets}
+This manual: @ref{Tuplets}.
 
 
 @node Bar check
 @subsection Bar check
 
 @cindex Bar check
-@findex barCheckSynchronize
-@findex |
+@funindex barCheckSynchronize
+@funindex |
 
 Bar checks help detect errors in the durations.  A bar check is
-entered using the bar symbol, `@code{|}'.  Whenever it is encountered
+entered using the bar symbol, @samp{|}.  Whenever it is encountered
 during interpretation, it should fall on a measure boundary.  If it
 does not, a warning is printed.  In the next example, the second bar
 check will signal an error
@@ -759,8 +887,8 @@ durations.  Incorrect durations often completely garble up the score,
 especially if the score is polyphonic, so a good place to start correcting
 input is by scanning for failed bar checks and incorrect durations.
 
-@findex |
-@findex pipeSymbol
+@funindex |
+@funindex pipeSymbol
 
 It is also possible to redefine the meaning of @code{|}.  This is done
 by assigning a music expression to @code{pipeSymbol},
@@ -811,6 +939,10 @@ ties.  One of its uses is to debug complex scores: if the measures are
 not entirely filled, then the ties exactly show how much each measure
 is off.
 
+If you want to allow line breaking on the bar lines where
+@internalsref{Completion_heads_engraver} splits notes, you must
+also remove @internalsref{Forbid_line_breaks_engraver}.
+
 
 @refbugs
 
@@ -824,15 +956,11 @@ rests.
 
 @seealso
 
-Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
-
-@noindent
-
 Program reference: @internalsref{Completion_heads_engraver}.
 
 
-@node Multiple notes at once
-@section Multiple notes at once
+@node Polyphony
+@section Polyphony
 
 Polyphony in music refers to having more than one voice occurring in
 a piece of music.  Polyphony in LilyPond refers to having more than
@@ -852,8 +980,8 @@ one voice on the same staff.
 
 @cindex Chords
 
-A chord is formed by a enclosing a set of pitches in @code{<} and
-@code{>}.  A chord may be followed by a duration, and a set of
+A chord is formed by a enclosing a set of pitches between @code{<}
+and @code{>}.  A chord may be followed by a duration, and a set of
 articulations, just like simple notes
 
 @lilypond[verbatim,ragged-right,fragment,quote,relative=1]
@@ -872,11 +1000,11 @@ made invisible.
 
 @refcommands
 
-@findex \stemUp
+@funindex \stemUp
 @code{\stemUp},
-@findex \stemDown
+@funindex \stemDown
 @code{\stemDown},
-@findex \stemNeutral
+@funindex \stemNeutral
 @code{\stemNeutral}.
 
 
@@ -902,7 +1030,7 @@ The easiest way to enter fragments with more than one voice on a staff
 is to enter each voice as a sequence (with @code{@{...@}}), and combine
 them simultaneously, separating the voices with @code{\\}
 
-@findex \\
+@funindex \\
 
 @lilypond[quote,verbatim,fragment]
 \new Staff \relative c' {
@@ -916,7 +1044,7 @@ them simultaneously, separating the voices with @code{\\}
 @end lilypond
 
 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
-voices are sometimes called ``layers'' in other notation packages}
+voices are sometimes called @q{layers} in other notation packages}
 @cindex layers
 to be instantiated.  They bear the names @code{"1"}, @code{"2"}, etc.  In
 each of these contexts, vertical direction of slurs, stems, etc., is set
@@ -966,6 +1094,7 @@ to the note immediately preceding it.
 @code{noteD} is relative to @code{noteC}, not @code{noteB} or
 @code{noteA}.
 
+
 @node Explicitly instantiating voices
 @subsection Explicitly instantiating voices
 
@@ -1068,13 +1197,29 @@ the music.
 }
 @end lilypond
 
+In some instances of complex polyphonic music, you may need additional
+voices to avoid collisions between notes.  Additional voices are added
+by defining an identifier, as shown below:
+
+@lilypond[quote,verbatim,ragged-right,relative=2]
+voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
+
+\relative c''' <<
+  { \voiceOne g4 ~  \stemDown g32[ f( es d c b a b64 )g] } \\
+  { \voiceThree  b4} \\
+  { \voiceFive d,} \\
+  { \voiceTwo g,}
+>>
+@end lilypond
+
 
 @node Collision Resolution
 @subsection Collision Resolution
 
 Normally, note heads with a different number of dots are not merged, but
 when the object property @code{merge-differently-dotted} is set in
-the @internalsref{NoteCollision} object, they are merged
+the @internalsref{NoteCollision} object, they are merged:
+
 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 \new Voice << {
   g8 g8
@@ -1085,7 +1230,8 @@ the @internalsref{NoteCollision} object, they are merged
 @end lilypond
 
 Similarly, you can merge half note heads with eighth notes, by setting
-@code{merge-differently-headed}
+@code{merge-differently-headed}:
+
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \new Voice << {
   c8 c4.
@@ -1094,6 +1240,10 @@ Similarly, you can merge half note heads with eighth notes, by setting
 c8 c4. } \\ { c2 c2 } >>
 @end lilypond
 
+@noindent
+@code{merge-differently-headed} and @code{merge-differently-dotted}
+only apply to opposing stem directions (ie. Voice 1 & 2).
+
 LilyPond also vertically shifts rests that are opposite of a stem,
 for example
 
@@ -1101,29 +1251,54 @@ for example
 \new Voice << c''4 \\ r4 >>
 @end lilypond
 
+If three or more notes line up in the same column,
+@code{merge-differently-headed} cannot
+successfully complete the merge of the two notes that should be merged.
+To allow the merge to work properly, apply a @code{\shift} to the note that
+should not be merged.  In the first measure of following example,
+@code{merge-differently-headed} does not work (the half-note head is
+solid).  In the second measure, @code{\shiftOn} is applied to move the
+top @code{g} out of the column, and @code{merge-differently-headed}
+works properly.
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\override Staff.NoteCollision #'merge-differently-headed = ##t
+<<
+  { d=''2 g2 } \\
+  { \oneVoice d=''8 c8 r4 e,8 c'8 r4 } \\
+  { \voiceFour e,,2 e'2}
+>>
+<<
+  { d'=''2 \shiftOn g2 } \\ 
+  { \oneVoice d=''8 c8 r4 e,8 c'8 r4 } \\
+  { \voiceFour e,,2 e'2}
+>>
+@end lilypond
+
 
 @refcommands
 
-@findex \oneVoice
+@funindex \oneVoice
 @code{\oneVoice},
-@findex \voiceOne
+@funindex \voiceOne
 @code{\voiceOne},
-@findex \voiceTwo
+@funindex \voiceTwo
 @code{\voiceTwo},
-@findex \voiceThree
+@funindex \voiceThree
 @code{\voiceThree},
-@findex \voiceFour
+@funindex \voiceFour
 @code{\voiceFour}.
 
-@findex \shiftOn
+@funindex \shiftOn
 @code{\shiftOn},
-@findex \shiftOnn
+@funindex \shiftOnn
 @code{\shiftOnn},
-@findex \shiftOnnn
+@funindex \shiftOnnn
 @code{\shiftOnnn},
-@findex \shiftOff
-@code{\shiftOff}: these commands specify in what chords of the current
-voice should be shifted.  The outer voices (normally: voice one and
+@funindex \shiftOff
+@code{\shiftOff}: these commands specify the
+degree to which chords of the current voice should be shifted.
+The outer voices (normally: voice one and
 two) have @code{\shiftOff}, while the inner voices (three and four)
 have @code{\shiftOn}.  @code{\shiftOnn} and @code{\shiftOnnn} define
 further shift levels.
@@ -1150,13 +1325,6 @@ be used to override typesetting decisions.
 Program reference: the objects responsible for resolving collisions are
 @internalsref{NoteCollision} and @internalsref{RestCollision}.
 
-Examples:
-@inputfileref{input/@/regression,collision@/-dots@/.ly},
-@inputfileref{input/@/regression,collision@/-head-chords@/.ly},
-@inputfileref{input/@/regression,collision@/-heads@/.ly},
-@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
-@inputfileref{input/@/regression,collisions@/.ly}.
-
 
 @refbugs
 
@@ -1195,7 +1363,7 @@ such as key signatures, clefs and time signatures.
 @node Clef
 @subsection Clef
 
-@findex \clef
+@funindex \clef
 
 The clef indicates which lines of the staff correspond to which
 pitches.  The clef is set with the @code{\clef} command
@@ -1291,6 +1459,8 @@ possibilities when setting properties manually.
 
 @seealso
 
+Manual: @ref{Grace notes}.
+
 Program reference: @internalsref{Clef}.
 
 
@@ -1298,7 +1468,7 @@ Program reference: @internalsref{Clef}.
 @subsection Key signature
 
 @cindex Key signature
-@findex \key
+@funindex \key
 
 The key signature indicates the tonality in which a piece is played.  It
 is denoted by a set of alterations (flats or sharps) at the start of the
@@ -1311,21 +1481,21 @@ command
 @code{\key} @var{pitch} @var{type}
 @end example
 
-@findex \minor
-@findex \major
-@findex \minor
-@findex \ionian
-@findex \locrian
-@findex \aeolian
-@findex \mixolydian
-@findex \lydian
-@findex \phrygian
-@findex \dorian
+@funindex \minor
+@funindex \major
+@funindex \minor
+@funindex \ionian
+@funindex \locrian
+@funindex \aeolian
+@funindex \mixolydian
+@funindex \lydian
+@funindex \phrygian
+@funindex \dorian
 @cindex church modes
 
 Here, @var{type} should be @code{\major} or @code{\minor} to get
 @var{pitch}-major or @var{pitch}-minor, respectively.  You may also
-use the standard mode names (also called ``church modes''): @code{\ionian},
+use the standard mode names (also called @q{church modes}): @code{\ionian},
 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
 @code{\phrygian}, and @code{\dorian}.
 
@@ -1335,7 +1505,13 @@ can be specified by setting this property directly.
 
 Accidentals and key signatures often confuse new users, because
 unaltered notes get natural signs depending on the key signature.  For
-more information, see @ref{More about pitches}.
+more information, see @ref{Accidentals}, or @ref{Accidentals and key signatures}.
+
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+\key g \major
+f1
+fis
+@end lilypond
 
 
 @commonprop
@@ -1368,7 +1544,7 @@ Program reference: @internalsref{KeyCancellation},
 
 @cindex Time signature
 @cindex meter
-@findex \time
+@funindex \time
 
 Time signature indicates the metrum of a piece: a regular pattern of
 strong and weak beats.  It is denoted by a fraction at the start of the
@@ -1395,7 +1571,7 @@ property.  Setting it to @code{#'()} uses fraction style for 4/4 and
 @end lilypond
 
 There are many more options for its layout.  See @ref{Ancient time
-signatures} for more examples.
+signatures}, for more examples.
 
 @code{\time} sets the property @code{timeSignatureFraction},
 @code{beatLength} and @code{measureLength} in the @code{Timing}
@@ -1453,7 +1629,7 @@ Automatic beaming does not use the measure grouping specified with
 @cindex partial measure
 @cindex measure, partial
 @cindex shorten measures
-@findex \partial
+@funindex \partial
 
 Partial measures, such as an anacrusis or upbeat, are entered using the
 
@@ -1467,6 +1643,9 @@ The syntax for this command is
 \partial @var{duration}
 @end example
 
+where @code{duration} is the rhythmic length to be added before
+the next bar.
+
 This is internally translated into
 
 @example
@@ -1474,7 +1653,9 @@ This is internally translated into
 @end example
 
 The property @code{measurePosition} contains a rational number
-indicating how much of the measure has passed at this point.
+indicating how much of the measure has passed at this point.  Note
+that this is a negative number; @code{\partial 4} is internally
+translated to mean @qq{there is a quarter note left in the bar.}
 
 
 @refbugs
@@ -1490,12 +1671,16 @@ g4
 a2 g2
 @end lilypond
 
+@code{\partial} is only intended to be used at the beginning of a
+piece.  If you use it after the beginning, some odd warnings may
+occur.
+
 
 @node Bar lines
 @subsection Bar lines
 
 @cindex Bar lines
-@findex \bar
+@funindex \bar
 @cindex measure lines
 @cindex repeat bars
 
@@ -1526,11 +1711,12 @@ To allow a line break where there is no visible bar line, use
 
 @noindent
 This will insert an invisible bar line and allow line breaks at this
-point.
+point (without increasing the bar number counter).
 
 In scores with many staves, a @code{\bar} command in one staff is
 automatically applied to all staves.  The resulting bar lines are
-connected between different staves of a StaffGroup
+connected between different staves of a @code{StaffGroup},
+@code{PianoStaff}, or @code{GrandStaff}.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 <<
@@ -1549,9 +1735,9 @@ connected between different staves of a StaffGroup
 
 @commonprop
 
-@findex whichBar
-@findex repeatCommands
-@findex defaultBarType
+@funindex whichBar
+@funindex repeatCommands
+@funindex defaultBarType
 
 The command @code{\bar }@var{bartype} is a short cut for doing
 @code{\set Timing.whichBar = }@var{bartype}.  Whenever @code{whichBar}
@@ -1574,15 +1760,13 @@ In this manual: @ref{Repeats}, @ref{System start delimiters}.
 Program reference: @internalsref{BarLine} (created at
 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
 
-Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
-
 
 @node Unmetered music
 @subsection Unmetered music
 
 @cindex cadenza
-@findex \cadenzaOn
-@findex \cadenzaOff
+@funindex \cadenzaOn
+@funindex \cadenzaOff
 
 Bar lines and bar numbers are calculated automatically.  For unmetered
 music (cadenzas, for example), this is not desirable.  To turn off
@@ -1601,8 +1785,9 @@ d4 e d c
 
 @refbugs
 
-LilyPond will only insert page breaks at a barline.  Unless the unmetered
-music ends before the end of the staff line, you will need to insert
+LilyPond will only insert line breaks and page breaks at a
+barline.  Unless the unmetered music ends before the end of
+the staff line, you will need to insert
 invisible bar lines
 
 @example
@@ -1610,7 +1795,7 @@ invisible bar lines
 @end example
 
 @noindent
-to indicate where line breaks can occur.
+to indicate where breaks can occur.
 
 
 @node System start delimiters
@@ -1680,7 +1865,25 @@ The bar lines at the start of each system are
 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
 @internalsref{SystemStartBracket}.  Only one of these types is created
 in every context, and that type is determined by the property
-@code{systemStartDelimiter}.
+@internalsref{systemStartDelimiter}.
+
+
+@commonprop
+
+System start delimiters may be deeply nested,
+
+@lilypond[quote,ragged-right,verbatim]
+\new StaffGroup 
+\relative <<
+  \set StaffGroup.systemStartDelimiterHierarchy
+    = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d)
+  \new Staff { c1 }
+  \new Staff { c1 }
+  \new Staff { c1 }
+  \new Staff { c1 }
+  \new Staff { c1 }
+>>
+@end lilypond
 
 
 @node Staff symbol
@@ -1689,9 +1892,9 @@ in every context, and that type is determined by the property
 @cindex adjusting staff symbol
 
 Notes, dynamic signs, etc., are grouped
-with a set of horizontal lines, called a staff (plural `staves').  In
+with a set of horizontal lines, called a staff (plural @q{staves}).  In
 LilyPond, these lines are drawn using a separate layout object called
-staff symbol.
+@code{staff symbol}.
 
 The staff symbol may be tuned in the number, thickness and distance
 of lines, using properties.  This is demonstrated in the example files
@@ -1712,8 +1915,7 @@ b b
 @end lilypond
 
 In combination with Frenched staves, this may be used to typeset ossia
-sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
-shown here
+sections. An example is shown here
 
 @cindex ossia
 
@@ -1731,7 +1933,7 @@ Program reference: @internalsref{StaffSymbol}.
 Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
 @inputfileref{input/@/test@/,ossia.ly},
 @inputfileref{input/@/test,staff@/-size@/.ly},
-@inputfileref{input/@/regression,staff@/-line@/-positions@/.ly}.
+@lsr{staff,staff-line-positions.ly}
 
 
 @node Writing music in parallel
@@ -1755,6 +1957,47 @@ Music for multiple parts can be interleaved
 >>
 @end lilypond
 
+This works quite well for piano music
+
+@lilypond[quote,verbatim]
+music = {
+  \key c \major
+  \time 4/4
+  \parallelMusic #'(voiceA voiceB voiceC voiceD) {
+    % Bar 1
+    r8  g'16[ c''] e''[ g' c'' e''] r8  g'16[ c''] e''[ g' c''
+e''] |
+    c'2                                 c'2 |
+    r8  a16[ d'] f'[ a d' f']       r8  a16[ d'] f'[ a d' f'] |
+    c2                                  c2 |
+
+    % Bar 2
+    a'8 b'      c'' d''    e'' f''    g'' a'' |
+    d'4         d'         d'         d' |
+    c16 d e f   d e f g    e f g a    f g a b |
+    a,4         a,4        a,4        a,4 |
+
+    % Bar 3 ...
+  }
+}
+
+\score {
+  \new PianoStaff <<
+    \music
+    \new Staff <<
+      \voiceA \\
+      \voiceB
+    >>
+    \new Staff {
+      \clef bass
+      <<
+        \voiceC \\
+        \voiceD
+      >>
+    }
+  >>
+}
+@end lilypond
 
 
 @node Connecting notes
@@ -1777,19 +2020,24 @@ This section deals with notation that affects groups of notes.
 @subsection Ties
 
 @cindex tie
-@findex ~
+@funindex ~
 
 A tie connects two adjacent note heads of the same pitch.  The tie in
 effect extends the length of a note.  Ties should not be confused with
 slurs, which indicate articulation, or phrasing slurs, which indicate
-musical phrasing.  A tie is entered using the tilde symbol `@code{~}'
+musical phrasing.  A tie is entered using the tilde symbol @samp{~}
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 e' ~ e' <c' e' g'> ~ <c' e' g'>
 @end lilypond
 
 When a tie is applied to a chord, all note heads whose pitches match
-are connected.  When no note heads match, no ties will be created.
+are connected.  When no note heads match, no ties will be created.  Chords
+may be partially tied by placing the tie inside the chord,
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+<c~ e g~ b> <c e g b>
+@end lilypond
 
 A tie is just a way of extending a note duration, similar to the
 augmentation dot.  The following example shows two ways of notating
@@ -1815,6 +2063,8 @@ automatic note splitting (see @ref{Automatic note splitting}).  This
 mechanism automatically splits long notes, and ties them across bar
 lines.
 
+@funindex \repeatTie
+
 When a second alternative of a repeat starts with a tied note, you
 have to repeat the tie. This can be achieved with @code{\repeatTie},
 
@@ -1832,27 +2082,40 @@ notes need not be consecutive.  This can be achieved by setting the
 @code{tieWaitForNote} property to true. The same feature is also useful,
 for example, to tie a tremolo to a chord. For example,
 
-@lilypond[fragment,verbatim,relative=1,ragged-right]
+@lilypond[fragment,verbatim,relative=1,ragged-right,quote]
 \set tieWaitForNote = ##t
 \grace { c16[~ e~ g]~ } <c, e g>2
 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
+e8~ c~ a~ f~ <e' c a f>2
+@end lilypond
+
+Ties may be engraved manually by changing the @code{tie-configuration}
+property.  The first number indicates the distance from the center
+of the staff in staff-spaces, and the second number indicates the
+direction (1=up, -1=down).
+
+@lilypond[fragment,verbatim,relative=1,ragged-right,quote]
+<c e g>2~ <c e g> |
+\override TieColumn #'tie-configuration =
+  #'((0.0 . 1) (-2.0 . 1) (-4.0 . 1))
+<c e g>~ <c e g> |
 @end lilypond
 
 
 @refcommands
 
 
-@findex \tieUp
+@funindex \tieUp
 @code{\tieUp},
-@findex \tieDown
+@funindex \tieDown
 @code{\tieDown},
-@findex \tieNeutral
+@funindex \tieNeutral
 @code{\tieNeutral},
-@findex \tieDotted
+@funindex \tieDotted
 @code{\tieDotted},
-@findex \tieDashed
+@funindex \tieDashed
 @code{\tieDashed},
-@findex \tieSolid
+@funindex \tieSolid
 @code{\tieSolid}.
 
 
@@ -1862,17 +2125,14 @@ In this manual: @ref{Automatic note splitting}.
 
 Program reference: @internalsref{Tie}.
 
-Examples:
-@inputfileref{input/@/regression,tie-arpeggio.ly}
-@inputfileref{input/@/regression,tie-manual.ly}
-
-
-
 
 @refbugs
 
 Switching staves when a tie is active will not produce a slanted tie.
 
+Changing clefs or octavations during a tie is not really
+well-defined.  In these cases, a slur may be preferable.
+
 
 @node Slurs
 @subsection Slurs
@@ -1917,17 +2177,17 @@ be achieved in LilyPond by setting @code{doubleSlurs},
 
 @refcommands
 
-@findex \slurUp
+@funindex \slurUp
 @code{\slurUp},
-@findex \slurDown
+@funindex \slurDown
 @code{\slurDown},
-@findex \slurNeutral
+@funindex \slurNeutral
 @code{\slurNeutral},
-@findex \slurDashed
+@funindex \slurDashed
 @code{\slurDashed},
-@findex \slurDotted
+@funindex \slurDotted
 @code{\slurDotted},
-@findex \slurSolid
+@funindex \slurSolid
 @code{\slurSolid}.
 
 @seealso
@@ -1960,11 +2220,11 @@ You cannot have simultaneous phrasing slurs.
 
 @refcommands
 
-@findex \phrasingSlurUp
+@funindex \phrasingSlurUp
 @code{\phrasingSlurUp},
-@findex \phrasingSlurDown
+@funindex \phrasingSlurDown
 @code{\phrasingSlurDown},
-@findex \phrasingSlurNeutral
+@funindex \phrasingSlurNeutral
 @code{\phrasingSlurNeutral}.
 
 
@@ -1993,7 +2253,7 @@ Program reference:
 @internalsref{LaissezVibrerTieColumn}
 
 Example files:
-@inputfileref{input/regression,laissez-vibrer-tie.ly}
+@lsr{connecting,laissez-vibrer-ties.ly}
 
 
 @node Automatic beams
@@ -2007,7 +2267,7 @@ LilyPond inserts beams automatically
 
 When these automatic decisions are not good enough, beaming can be
 entered explicitly.  It is also possible to define beaming patterns
-that differ from the defaults.  See @ref{Setting automatic beam behavior}
+that differ from the defaults.  See @ref{Setting automatic beam behavior},
 for details.
 
 Individual notes may be marked with @code{\noBeam} to prevent them
@@ -2027,8 +2287,8 @@ Program reference: @internalsref{Beam}.
 @subsection Manual beams
 
 @cindex beams, manual
-@findex ]
-@findex [
+@funindex ]
+@funindex [
 
 In some cases it may be necessary to override the automatic beaming
 algorithm.  For example, the autobeamer will not put beams over rests
@@ -2044,8 +2304,8 @@ and end point with @code{[} and @code{]}
 
 @commonprop
 
-@findex stemLeftBeamCount
-@findex stemRightBeamCount
+@funindex stemLeftBeamCount
+@funindex stemRightBeamCount
 
 Normally, beaming patterns within a beam are determined automatically.
 If necessary, the properties @code{stemLeftBeamCount} and
@@ -2074,16 +2334,17 @@ c16[ c c c c c c c]
 \set Score.beatLength = #(ly:make-moment 1 8)
 c16[ c c c c c c c]
 @end lilypond
-@findex subdivideBeams
+@funindex subdivideBeams
 
 @noindent
 For more information about @code{make-moment}, see
 @ref{Time administration}.
 
 Line breaks are normally forbidden when beams cross bar lines.  This
-behavior can be changed by setting @code{allowBeamBreak}.
+behavior can be changed by setting @code{breakable}.
+
+@funindex breakable
 
-@findex allowBeamBreak
 @cindex beams and line breaks
 @cindex beams, kneed
 @cindex kneed beams
@@ -2093,7 +2354,8 @@ behavior can be changed by setting @code{allowBeamBreak}.
 @refbugs
 
 Kneed beams are inserted automatically when a large gap is detected
-between the note heads.  This behavior can be tuned through the object.
+between the note heads.  This behavior can be tuned through the
+@code{auto-knee-gap} object.
 
 Automatically kneed cross-staff beams cannot be used together with
 hidden staves.  See @ref{Hiding staves}.
@@ -2105,7 +2367,7 @@ texts and accidentals.
 @node Grace notes
 @subsection Grace notes
 
-@findex \grace
+@funindex \grace
 @cindex ornaments
 @cindex grace notes
 @cindex appoggiatura
@@ -2137,7 +2399,7 @@ c4 \grace c16 c4
 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
 @code{\grace} command does not start a slur.
 
-Internally, timing for grace notes is done using a second, `grace'
+Internally, timing for grace notes is done using a second, @q{grace}
 timing.  Every point in time consists of two rational numbers: one
 denotes the logical time, one denotes the grace timing.  The above
 example is shown here with timing tuples
@@ -2173,7 +2435,7 @@ every eighth grace note
    \new Staff { c4 \grace { g8[ b] } c4 } >>
 @end lilypond
 
-@findex \afterGrace
+@funindex \afterGrace
 
 If you want to end a note with a grace, use the @code{\afterGrace}
 command.  It takes two arguments: the main note, and the grace notes
@@ -2183,12 +2445,12 @@ following the main note.
 c1 \afterGrace d1 { c16[ d] } c4
 @end lilypond
 
-This will put the grace notes after a ``space'' lasting 3/4 of the
+This will put the grace notes after a @q{space} lasting 3/4 of the
 length of the main note.  The fraction 3/4 can be changed by setting
 @code{afterGraceFraction}, ie.
 
 @example
-afterGraceFraction = #(cons 7 8)
+#(define afterGraceFraction (cons 7 8))
 @end example
 
 @noindent
@@ -2212,6 +2474,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[quote,ragged-right,fragment,verbatim,relative=2]
 \new Voice {
   \acciaccatura {
@@ -2228,8 +2491,8 @@ The overrides should also be reverted inside the grace section.
 
 The layout of grace sections can be changed throughout the music using
 the function @code{add-grace-property}.  The following example
-undefines the Stem direction for this grace, so stems do not always
-point up.
+undefines the @code{Stem} direction for this grace, so
+that stems do not always point up.
 
 @example
 \new Staff @{
@@ -2249,6 +2512,30 @@ Another option is to change the variables @code{startGraceMusic},
 The slash through the stem in acciaccaturas can be obtained
 in other situations by @code{\override Stem  #'stroke-style = #"grace"}.
 
+
+@commonprop
+
+Grace notes may be forced to use floating spacing,
+
+@lilypond[relative=2,ragged-right]
+<<
+  \override Score.SpacingSpanner #'strict-grace-spacing = ##t
+  \new Staff {
+     c'4
+     \afterGrace
+     c'4
+     { c'16[ c'8 c'16] }
+     c'4
+  }  
+  \new Staff {
+     c'16[ c'16 c'16 c'16]
+     c'16[ c'16 c'16 c'16]
+     c'4
+  }
+>>
+@end lilypond
+
+
 @seealso
 
 Program reference: @internalsref{GraceMusic}.
@@ -2297,6 +2584,7 @@ notes and rhythms.
 * Trills::                      
 * Glissando::                   
 * Arpeggio::                    
+* Falls and doits::             
 @end menu
 
 
@@ -2455,30 +2743,30 @@ very close to note heads in monophonic music,
 
 Program reference: @internalsref{Fingering}.
 
-Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
+Examples: @lsr{expressive,fingering-chords.ly}
 
 
 @node Dynamics
 @subsection Dynamics
 
 @cindex Dynamics
-@findex \pppp
-@findex \ppp
-@findex \pp
-@findex \p
-@findex \mp
-@findex \mf
-@findex \f
-@findex \ff
-@findex \fff
-@findex \ffff
-@findex \fp
-@findex \sf
-@findex \sff
-@findex \sp
-@findex \spp
-@findex \sfz
-@findex \rfz
+@funindex \pppp
+@funindex \ppp
+@funindex \pp
+@funindex \p
+@funindex \mp
+@funindex \mf
+@funindex \f
+@funindex \ff
+@funindex \fff
+@funindex \ffff
+@funindex \fp
+@funindex \sf
+@funindex \sff
+@funindex \sp
+@funindex \spp
+@funindex \sfz
+@funindex \rfz
 
 Absolute dynamic marks are specified using a command after a note
 @code{c4\ff}.  The available dynamic marks are @code{\ppppp},
@@ -2492,9 +2780,9 @@ c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
 c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
 @end lilypond
 
-@findex \<
-@findex \>
-@findex \!
+@funindex \<
+@funindex \>
+@funindex \!
 
 A crescendo mark is started with @code{\<} and terminated with
 @code{\!} or an absolute dynamic.  A decrescendo is started with
@@ -2509,8 +2797,16 @@ c\< c\! d\> e\!
 @end lilypond
 
 @noindent
-A hairpin starts at the left edge of the beginning note and ends on the
-right edge of the ending note.
+A hairpin normally starts at the left edge of the beginning note
+and ends on the right edge of the ending note.  If the ending
+note falls on the downbeat, the hairpin ends on the immediately
+preceding barline. This may be modified by setting the
+@code{hairpinToBarline} property,
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\set hairpinToBarline = ##f
+c4\< c2. c4\!
+@end lilypond
 
 In some situations the @code{\espressivo} articulation mark may
 be suitable to indicate a crescendo and decrescendo on the one note,
@@ -2524,14 +2820,27 @@ in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
 example
 
 @example
-\override Staff.Hairpin #'minimum-length = #5
+\override Voice.Hairpin #'minimum-length = #5
 @end example
 
+@cindex al niente
+@cindex niente, al
+
+Hairpins may be printed with a circled tip (al niente notation) by
+setting the @code{circled-tip} property,
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+\override Hairpin #'circled-tip = ##t
+c2\< c\!
+c4\> c\< c2\!
+@end lilypond
+
+
 @cindex crescendo
 @cindex decrescendo
 @cindex diminuendo
 
-You can also use text saying @emph{cresc.} instead of hairpins
+You can also use text saying @emph{cresc.} instead of hairpins
 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \setTextCresc
@@ -2554,6 +2863,9 @@ a'2\< a a a\!\mf
 To create new dynamic marks or text that should be aligned
 with dynamics, see @ref{New dynamic marks}.
 
+Vertical positioning of dynamics is handled by
+@internalsref{DynamicLineSpanner}.
+
 
 @commonprop
 
@@ -2576,7 +2888,8 @@ new line are not printed.  To change this behavior, use
 \override Score.Hairpin #'after-line-breaking = ##t
 @end example
 
-Text style dynamic changes (such as cresc. and dim.) are printed with a
+Text style dynamic changes (such as @emph{cresc.} and @emph{dim.})
+are printed with a
 dashed line showing their extent.  To surpress printing this line, use
 
 @example
@@ -2586,11 +2899,11 @@ dashed line showing their extent.  To surpress printing this line, use
 
 @refcommands
 
-@findex \dynamicUp
+@funindex \dynamicUp
 @code{\dynamicUp},
-@findex \dynamicDown
+@funindex \dynamicDown
 @code{\dynamicDown},
-@findex \dynamicNeutral
+@funindex \dynamicNeutral
 @code{\dynamicNeutral}.
 
 
@@ -2628,7 +2941,7 @@ d4
 
 Program reference: @internalsref{BreathingSign}.
 
-Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
+Examples: @lsr{expressive,breathing-sign.ly}
 
 
 @node Trills
@@ -2651,7 +2964,7 @@ Long running trills are made with @code{\startTrillSpan} and
 Trills that should be executed on an explicitly specified pitch can be
 typeset with the command @code{pitchedTrill},
 
-@lilypond[ragged-right,verbatim,fragment,relative=1]
+@lilypond[ragged-right,verbatim,fragment,relative=1,quote]
 \pitchedTrill c4\startTrillSpan fis
 f\stopTrillSpan
 @end lilypond
@@ -2663,9 +2976,9 @@ is printed as a stemless note head in parentheses.
 @refcommands
 
 @code{\startTrillSpan},
-@findex \startTrillSpan
+@funindex \startTrillSpan
 @code{\stopTrillSpan}.
-@findex \stopTrillSpan
+@funindex \stopTrillSpan
 
 
 @seealso
@@ -2677,7 +2990,7 @@ Program reference: @internalsref{TrillSpanner}.
 @subsection Glissando
 
 @cindex Glissando
-@findex \glissando
+@funindex \glissando
 
 A glissando is a smooth change in pitch.  It is denoted by a line or a
 wavy line between two notes.  It is requested by attaching
@@ -2694,7 +3007,9 @@ c2\glissando c,
 
 Program reference: @internalsref{Glissando}.
 
-Example files: @file{input/@/regression/@/glissando@/.ly}.
+Example files:
+@lsr{expressive,glissando.ly}, @lsr{expressive,line-styles.ly}
+
 
 
 @refbugs
@@ -2707,7 +3022,7 @@ Printing text over the line (such as @emph{gliss.}) is not supported.
 
 @cindex Arpeggio
 @cindex broken chord
-@findex \arpeggio
+@funindex \arpeggio
 
 You can specify an arpeggio sign (also known as broken chord) on a
 chord by attaching an @code{\arpeggio} to a chord
@@ -2755,13 +3070,13 @@ in both staves and set
 @refcommands
 
 @code{\arpeggio},
-@findex \arpeggioUp
+@funindex \arpeggioUp
 @code{\arpeggioUp},
-@findex \arpeggioDown
+@funindex \arpeggioDown
 @code{\arpeggioDown},
-@findex \arpeggioNeutral
+@funindex \arpeggioNeutral
 @code{\arpeggioNeutral},
-@findex \arpeggioBracket
+@funindex \arpeggioBracket
 @code{\arpeggioBracket}.
 
 
@@ -2778,7 +3093,17 @@ It is not possible to mix connected arpeggios and unconnected
 arpeggios in one @internalsref{PianoStaff} at the same point in time.
 
 
+@node Falls and doits
+@subsection Falls and doits
 
+Falls and doits can be added to notes using the @code{\bendAfter}
+command,
+
+@lilypond[fragment,ragged-right,relative=2]
+\override Score.SpacingSpanner #'shortest-duration-space = #3.0
+c4-\bendAfter #+5
+c4-\bendAfter #-3
+@end lilypond
 
 
 @node Repeats
@@ -2802,7 +3127,7 @@ for repetitions.
 @subsection Repeat types
 
 @cindex repeats
-@findex \repeat
+@funindex \repeat
 
 The following types of repetition are supported
 
@@ -2818,12 +3143,6 @@ printed, left to right with brackets.  This is the standard notation
 for repeats with alternatives.  These are not played in MIDI output by
 default.
 
-@ignore
-@item fold
-Alternative endings are written stacked.  This has limited use but may be
-used to typeset two lines of lyrics in songs with repeats, see
-@inputfileref{input,star-spangled-banner@/.ly}.
-@end ignore
 
 @item tremolo
 Make tremolo beams.  These are not played in MIDI output by default.
@@ -2831,7 +3150,7 @@ Make tremolo beams.  These are not played in MIDI output by default.
 @item percent
 Make beat or measure repeats.  These look like percent signs.  These
 are not played in MIDI output by default.  Percent repeats must be
-declared within a Voice context.
+declared within a @code{Voice} context.
 
 @end table
 
@@ -2839,6 +3158,10 @@ declared within a Voice context.
 @node Repeat syntax
 @subsection Repeat syntax
 
+@cindex volta
+@cindex prima volta
+@cindex seconda volta
+
 LilyPond has one syntactic construct for specifying different types of
 repeats.  The syntax is
 
@@ -2847,7 +3170,7 @@ repeats.  The syntax is
 @end example
 
 If you have alternative endings, you may add
-@findex \alternative
+@funindex \alternative
 @example
 \alternative @{
   @var{alternative1}
@@ -2863,6 +3186,7 @@ give enough alternatives for all of the repeats, the first alternative
 is assumed to be played more than once.
 
 Standard repeats are used like this
+
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 c1
 \repeat volta 2 { c4 d e f }
@@ -2870,27 +3194,33 @@ c1
 @end lilypond
 
 With alternative endings
+
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 c1
 \repeat volta 2 {c4 d e f}
 \alternative { {d2 d} {f f,} }
 @end lilypond
 
-In this example, the first ending is not a complete bar (it
-only had 3 beats).  The beginning of the second ending
-contains the 4th beat from the first ending.  This ``extra''
-beat in the second ending is due to the first time ending,
-and has nothing to do with the @code{\partial} at the
-beginning of the example.
+Repeats with upbeats may be created.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \new Staff {
-  \partial 4
-  \repeat volta 4 { e | c2 d2 | e2 f2 | }
-  \alternative { { g4 g g } { a | a a a a | b2. } }
+  \partial 4 e |
+  \repeat volta 4 { c2 d2 | e2 f2 | }
+  \alternative { { g4 g g e } { a a a a | b2. } }
 }
 @end lilypond
 
+@funindex \repeatTie
+
+Ties may be added to a second ending,
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+c1
+\repeat volta 2 {c4 d e f ~ }
+\alternative { {f2 d} {f\repeatTie f,} }
+@end lilypond
+
 It is possible to shorten volta brackets
 by setting @code{voltaSpannerDuration}.  In the next example, the
 bracket only lasts one measure, which is a duration of 3/4.
@@ -2913,7 +3243,9 @@ Examples:
 
 Brackets for the repeat are normally only printed over the topmost
 staff.  This can be adjusted by setting the @code{voltaOnThisStaff}
-property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
+property; see
+
+@lsr{repeats,volta@/-multi@/-staff@/.ly}.
 
 
 @refbugs
@@ -2935,20 +3267,22 @@ having the @code{\alternative} belong to the inner @code{\repeat}.
 For clarity, it is advisable to use braces in such situations.
 
 Timing information is not remembered at the start of an alternative,
-so after a repeat timing information must be reset by hand, for
-example by setting @code{Score.measurePosition} or entering
+so after a repeat timing information must be reset by hand; for
+example, by setting @code{Score.measurePosition} or entering
 @code{\partial}.  Similarly, slurs or ties are also not repeated.
 
+Volta brackets are not vertically aligned.
+
 
 @node Repeats and MIDI
 @subsection Repeats and MIDI
 
 @cindex expanding repeats
-@findex \unfoldRepeats
+@funindex \unfoldRepeats
 
 With a little bit of tweaking, all types of repeats can be present
 in the MIDI output.  This is achieved by applying the
-@code{\unfoldRepeats} music function.  This functions changes all
+@code{\unfoldRepeats} music function.  This function changes all
 repeats to unfold repeats.
 
 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
@@ -2964,8 +3298,8 @@ repeats to unfold repeats.
 \bar "|."
 @end lilypond
 
-When creating a score file using @code{\unfoldRepeats} for midi, then
-it is necessary to make two @code{\score} blocks.  One for MIDI (with
+When creating a score file using @code{\unfoldRepeats} for MIDI,
+it is necessary to make two @code{\score} blocks: one for MIDI (with
 unfolded repeats) and one for notation (with volta, tremolo, and
 percent repeats).  For example,
 
@@ -2984,7 +3318,7 @@ percent repeats).  For example,
 @node Manual repeat commands
 @subsection Manual repeat commands
 
-@findex repeatCommands
+@funindex repeatCommands
 
 The property @code{repeatCommands} can be used to control the layout of
 repeats.  Its value is a Scheme list of repeat commands.
@@ -3055,18 +3389,15 @@ In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
 
 Program reference: @internalsref{Beam}, @internalsref{StemTremolo}.
 
-Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
-@inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
-
 
 @node Tremolo subdivisions
 @subsection Tremolo subdivisions
 
 @cindex tremolo marks
-@findex tremoloFlags
+@funindex tremoloFlags
 
 Tremolo marks can be printed on a single note by adding
-`@code{:}[@var{number}]' after the note.  The number indicates the
+@q{@code{:}[@var{number}]} after the note.  The number indicates the
 duration of the subdivision, and it must be at least 8.  A
 @var{length} value of 8 gives one line across the note stem.  If the
 length is omitted, the last value (stored in @code{tremoloFlags}) is
@@ -3120,10 +3451,10 @@ on the @code{countPercentRepeats} property,
 
 
 
-Isolated percents can also be printed. This is done by putting a multi
-measure rest with a different print function,
+Isolated percents can also be printed. This is done by putting a
+multi-measure rest with a different print function,
 
-@lilypond[fragment,verbatim]
+@lilypond[fragment,verbatim,quote]
 \override MultiMeasureRest #'stencil
   = #ly:multi-measure-rest::percent
 R1