X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fadvanced-notation.itely;h=428a793359a6ea6b36274293982f26c812fa2a5a;hb=370250b3e8840a48c1ea2eabdf8a94e946706c93;hp=0ba5eefc2b58fa003a3657be1a0afa65b232d057;hpb=e0fa8f5336d294a4d27f8d951f6211d1c1cad211;p=lilypond.git

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 0ba5eefc2b..428a793359 100644
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -1,5 +1,11 @@
 @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
@@ -28,17 +34,21 @@ This section explains how to include text (with various formatting) in
 your scores.
 
 @cindex Text, other languages
-To write non-ascii text (such as characters from other languages), simply
+To write accented and special text (such as characters from other languages),
+simply
 insert the characters directly into the lilypond file.  The file must be
 saved as UTF-8.  For more information, see @ref{Text encoding}.
 
 @menu
 * Text scripts::                
+* Text and line spanners::      
 * Text spanners::               
 * Text marks::                  
 * Text markup::                 
 * Nested scores::               
+* Page wrapping text::          
 * Overview of text markup commands::  
+* Overview of text markup list commands::  
 * Font selection::              
 * New dynamic marks::           
 @end menu
@@ -51,7 +61,7 @@ saved as UTF-8.  For more information, see @ref{Text encoding}.
 @cindex text items, non-empty
 @cindex non-empty texts
 
-It is possible to place arbitrary strings of text or @ref{Text markup}
+It is possible to place arbitrary strings of text or @ref{Text markup},
 above or below notes by using a string @code{c^"text"}.  By default,
 these indications do not influence the note spacing, but by using the
 command @code{\fatText}, the widths will be taken into account
@@ -99,6 +109,137 @@ In this manual: @ref{Text markup}.
 Program reference: @internalsref{TextScript}.
 
 
+@node Text and line spanners
+@subsection Text and line spanners
+
+Some performance indications, e.g., @i{rallentando} and
+@i{accelerando} and @i{trills} are written as text and are extended
+over many measures with lines, sometimes dotted or wavy.
+
+These all use the same routines as the glissando for drawing the texts
+and the lines, and tuning their behavior is therefore also done in the
+same way. It is done with a spanner, and the routine responsible for
+drawing the spanners is @code{ly:line-interface::print}. This
+routine determines the exact location of the two @i{span
+points} and draws a line in between, in the style requested.
+
+Here is an example of the different line styles available, and how to
+tune them.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+d2 \glissando d'2
+\once \override Glissando #'dash-fraction = #0.5
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+The information that determines the end-points is computed on-the-fly
+for every graphic object, but it is possible to override these. 
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+e2 \glissando f
+\once \override Glissando #'bound-details #'right #'Y = #-2
+e2 \glissando f
+@end lilypond
+
+The @code{Glissando} object, like any other using the
+@code{ly:line-interface::print} routine, carries a nested
+association list. In the above statement, the value for @code{Y}
+is set to @code{-2} for the association list corresponding to the right
+end point. Of course, it is also possible to adjust the left side with
+@code{left} instead of @code{right}.
+
+If @code{Y} is not set, the value is computed from the vertical
+position of right attachment point of the spanner. 
+
+In case of a line break, the values for the span-points are extended
+with contents of the @code{left-broken} and @code{right-broken}
+sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T 
+\override Glissando #'bound-details #'right-broken #'Y = #-3
+c1 \glissando \break
+f1
+@end lilypond
+
+The following properties can be used for the
+
+@table @code
+@item Y
+This sets the Y-coordinate of the end point, in staff space.  By
+default, it is the center of the bound object, so for a glissando it
+points to the vertical center of the note head.
+
+For horizontal spanners, such as text spanner and trill spanners, it
+is hardcoded to 0.
+
+@item attach-dir
+This determines where the line starts and ends in X-direction,
+relative to the bound object.  So, a value of @code{-1} (or
+@code{LEFT}) makes the line start/end at the left side of the note
+head it is attached to.
+
+@item X
+This is the absolute coordinate of the end point. It is usually
+computed on the fly, and there is little use in overriding it. 
+
+@item stencil
+Line spanners may have symbols at the beginning or end, which is
+contained in this sub-property.  This is for internal use, it is
+recommended to use @code{text}.
+
+@item text
+This is a markup that is evaluated to yield stencil. It is
+used to put @i{cresc.} and @i{tr} on horizontal spanners.
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+   = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@end lilypond
+
+@item stencil-align-dir-y
+@item stencil-offset
+Without setting this, the stencil is simply put there at the
+end-point, as defined by the @code{X} and @code{Y} sub properties.
+Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
+will move the symbol at the edge relative to the end point of the line
+
+@lilypond[relative=1,fragment,verbatim]
+\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN
+\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP
+
+\override TextSpanner #'bound-details #'left #'text = #"gggg"
+\override TextSpanner #'bound-details #'right #'text = #"hhhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+@item arrow
+Setting this sub property to @code{#t} produce an arrowhead at the end
+of the line.
+
+@item padding
+This sub property controls the space between the specified end-point
+of the line and the actual end.  Without padding, a glissando would
+start and end in the center of each note head.
+
+@end table
+
+@seealso
+
+Program reference: @internalsref{TextSpanner},
+@internalsref{Glissando}, @internalsref{VoiceFollower},
+@internalsref{TrillSpanner}, @internalsref{line-spanner-interface}.
+
+Examples: @lsr{expressive,line-styles.ly}, @lsr{expressive,line-arrows.ly}
+
+
 @node Text spanners
 @subsection Text spanners
 
@@ -116,22 +257,24 @@ properties
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 c1
 \textSpannerDown
-\override TextSpanner #'edge-text = #'("rall " . "")
+\override TextSpanner #'bound-details #'left #'text =
+  \markup { \upright "rall" } 
 c2\startTextSpan b c\stopTextSpan a
 \break
 \textSpannerUp
-\override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+\override TextSpanner #'bound-details #'left #'text =
+  \markup { \italic "rit" } 
 c2\startTextSpan b c\stopTextSpan a
 @end lilypond
 
 @refcommands
 
-@cindex textSpannerUp
-@code{textSpannerUp},
-@cindex textSpannerDown
-@code{textSpannerDown},
-@cindex textSpannerNeutral
-@code{textSpannerNeutral}.
+@funindex textSpannerUp
+@code{\textSpannerUp},
+@funindex textSpannerDown
+@code{\textSpannerDown},
+@funindex textSpannerNeutral
+@code{\textSpannerNeutral}.
 
 
 @commonprop
@@ -147,8 +290,6 @@ To print a solid line, use
 
 Program reference: @internalsref{TextSpanner}.
 
-Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.
-
 
 @node Text marks
 @subsection Text marks
@@ -164,7 +305,7 @@ The @code{\mark} command is primarily used for
 but it can also be used to put signs like coda,
 segno, and fermata on a bar line.  Use @code{\markup} to
 access the appropriate symbol (symbols are listed in
-@ref{The Feta font})
+@ref{The Feta font}).
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
@@ -213,15 +354,15 @@ bar lines,
   c1
   \key cis \major
   \clef alto
-  \override Score.RehearsalMark #'break-align-symbol = #'key-signature
+  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
   \mark "on key"
   cis
   \key ces \major
-  \override Score.RehearsalMark #'break-align-symbol = #'clef
+  \override Score.RehearsalMark #'break-align-symbols = #'(clef)
   \clef treble
   \mark "on clef"
   ces
-  \override Score.RehearsalMark #'break-align-symbol = #'time-signature
+  \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
   \key d \minor
   \clef tenor
   \time 3/4
@@ -230,6 +371,42 @@ bar lines,
 }
 @end lilypond
 
+Possible symbols for the @code{break-align-symbols} list are
+@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
+@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
+@code{key-signature}, and @code{time-signature}.
+
+The text marks will, by default, be aligned with the middle of the notation
+object, but this can be changed by overriding the
+@code{break-align-anchor-alignment} and
+@code{break-align-anchor} properties for the appropriate grob.
+
+@lilypond[fragment,quote,ragged-right,verbatim]
+{
+  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+  c1
+  \key cis \major
+
+  % the RehearsalMark will be aligned with the left edge of the KeySignature
+  \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
+  \mark \default
+  cis1
+  \key ces \major
+
+  % the RehearsalMark will be aligned with the right edge of the KeySignature
+  \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
+  \mark \default
+  ces1
+  \key cis \major
+
+  % the RehearsalMark will be aligned with the left edge of the KeySignature
+  % and then shifted right by 2 units.
+  \once \override Staff.KeySignature #'break-align-anchor = #2
+  \mark \default
+  ces1
+}
+@end lilypond
+
 Although text marks are normally only printed above the topmost
 staff, you may alter this to print them on every staff,
 
@@ -277,7 +454,7 @@ c1_\markup { "\special {weird} #characters" }
 @end lilypond
 
 @noindent
-See @ref{Overview of text markup commands} for a list of all
+See @ref{Overview of text markup commands}, for a list of all
 commands.
 
 @code{\markup} is primarily used for @internalsref{TextScript}s,
@@ -293,7 +470,7 @@ but it can also be used anywhere text is called in lilypond
 
     \set Staff.instrumentName = \markup{ \column{ Alto solo } }
     c2^\markup{ don't be \flat }
-    \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+    \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
     b2\startTextSpan
     a2\mark \markup{ \large \bold Fine }
     r2\stopTextSpan
@@ -381,7 +558,7 @@ effect.
 
 In addition, vertical placement is performed after creating the
 text markup object.  If you wish to move an entire piece of markup,
-you need to use the #'padding property or create an "anchor" point
+you need to use the #'padding property or create an @q{anchor} point
 inside the markup (generally with @code{\hspace #0}).
 
 @lilypond[quote,verbatim,fragment,relative=1]
@@ -395,7 +572,7 @@ c'4^\markup{ \hspace #0 \raise #1.5 raised }
 Some situations (such as dynamic marks) have preset font-related
 properties.  If you are creating text in such situations, it
 is advisable to cancel those properties with
-@code{normal-text}.  See @ref{Overview of text markup commands}
+@code{normal-text}.  See @ref{Overview of text markup commands},
 for more details.
 
 
@@ -436,6 +613,40 @@ block.
 }
 @end lilypond
 
+@node Page wrapping text
+@subsection Page wrapping text
+Whereas @code{\markup} is used to enter a non-breakable block of text,
+@code{\markuplines} can be used at top-level to enter lines of text that
+can spread over multiple pages:
+
+@verbatim
+\markuplines {
+  \justified-lines {
+    A very long text of justified lines.
+    ...
+  }
+  \justified-lines {
+    An other very long paragraph.
+    ...
+  }
+  ...
+}
+@end verbatim
+
+@code{\markuplines} accepts a list of markup, that is either the result
+of a markup list command, or a list of markups or of markup lists. The
+built-in markup list commands are described in
+@ref{Overview of text markup list commands}.
+
+@seealso
+
+This manual: @ref{Overview of text markup list commands}, 
+@ref{New markup list command definition}.
+
+@refcommands
+
+@funindex \markuplines
+@code{\markuplines}
 
 @node Overview of text markup commands
 @subsection Overview of text markup commands
@@ -444,6 +655,12 @@ The following commands can all be used inside @code{\markup @{ @}}.
 
 @include markup-commands.tely
 
+@node Overview of text markup list commands
+@subsection Overview of text markup list commands
+
+The following commands can all be used with @code{\markuplines}.
+
+@include markup-list-commands.tely
 
 @node Font selection
 @subsection Font selection
@@ -552,7 +769,7 @@ example,
 
 @seealso
 
-Examples: @inputfileref{input/@/regression,font@/-family@/-override.ly}.
+Examples: @lsr{text,font@/-family@/-override.ly}.
 
 
 @node New dynamic marks
@@ -566,7 +783,7 @@ marks.  Note that the dynamic font only contains the characters
 Some situations (such as dynamic marks) have preset font-related
 properties.  If you are creating text in such situations, it
 is advisable to cancel those properties with
-@code{normal-text}.  See @ref{Overview of text markup commands}
+@code{normal-text}.  See @ref{Overview of text markup commands},
 for more details.
 
 @cindex make-dynamic-script
@@ -621,7 +838,7 @@ individual parts.
 @cindex whole rests for a full measure
 @funindex R
 
-Rests for one full measure (or many bars) are entered using `@code{R}'.  It
+Rests for one full measure (or many bars) are entered using @samp{R}.  It
 is specifically meant for full bar rests and for entering parts: the rest
 can expand to fill a score with rests, or it can be printed as a single
 multi-measure rest.  This expansion is controlled by the property
@@ -650,7 +867,7 @@ R1*13/8*12 |
 An @code{R} spanning a single measure is printed as either a whole rest
 or a breve, centered in the measure regardless of the time signature.
 
-If there are only a few measures of rest, LilyPond prints ``church rests''
+If there are only a few measures of rest, LilyPond prints @q{church rests}
 (a series of rectangles) in the staff.  To replace that with a simple
 rest, use @code{MultiMeasureRest.expand-limit}.
 
@@ -766,7 +983,7 @@ c4^\markup {
 @end lilypond
 
 @noindent
-See @ref{Text markup} for more details.
+See @ref{Text markup}, for more details.
 
 
 @seealso
@@ -804,8 +1021,8 @@ c1 \mark \default
 @end lilypond
 
 @noindent
-The letter@tie{}`I' is skipped in accordance with engraving traditions.
-If you wish to include the letter `I', then use
+The letter@tie{}@q{I} is skipped in accordance with engraving traditions.
+If you wish to include the letter @q{I}, then use
 
 @example
 \set Score.markFormatter = #format-mark-alphabet
@@ -871,33 +1088,10 @@ c1
 @end lilypond
 
 @noindent
-See @ref{The Feta font} for a list of symbols which may be
+See @ref{The Feta font}, for a list of symbols which may be
 printed with @code{\musicglyph}.
 
-The horizontal location of rehearsal marks can be adjusted by
-setting @code{break-align-symbol}
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative]
-c1
-\key cis \major
-\clef alto
-\override Score.RehearsalMark #'break-align-symbol = #'key-signature
-\mark "on-key"
-cis
-\key ces \major
-\override Score.RehearsalMark #'break-align-symbol = #'clef
-\clef treble
-\mark "on clef"
-ces
-@end lilypond
-
-@code{break-align-symbol} may also accept the following values:
-@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
-@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
-@code{key-signature}, and @code{time-signature}.  Setting
-@code{break-align-symbol} will only have an effect if the symbol
-appears at that point in the music.
-
+For common tweaks to the positioning of rehearsal marks, see @ref{Text marks}.
 
 @seealso
 
@@ -910,9 +1104,7 @@ definition of @code{format-mark-numbers} and
 @code{format-mark-letters}.  They can be used as inspiration for other
 formatting functions.
 
-Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},
-
-@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}.
+Examples: @lsr{parts,rehearsal-mark-numbers.ly}
 
 
 @node Bar numbers
@@ -946,7 +1138,7 @@ be added
 Bar numbers can be typeset at regular intervals instead of at the
 beginning of each line.  This is illustrated in the following example,
 whose source is available as
-@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}
+@lsr{staff,making-bar-numbers-appear-at-regular-intervals.ly}.
 
 @lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly}
 
@@ -971,9 +1163,7 @@ c4 c c c
 
 Program reference: @internalsref{BarNumber}.
 
-Examples:
-@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
-and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
+Examples: @lsrdir{staff}
 
 
 @refbugs
@@ -1145,7 +1335,7 @@ c'4^"in G"
 @node Ottava brackets
 @subsection Ottava brackets
 
-`Ottava' brackets introduce an extra transposition of an octave for
+@q{Ottava} brackets introduce an extra transposition of an octave for
 the staff.  They are created by invoking the function
 @code{set-octavation}
 
@@ -1182,9 +1372,6 @@ and -2 (for 15ma bassa) as arguments.  Internally the function sets the properti
 
 Program reference: @internalsref{OttavaBracket}.
 
-Examples: @inputfileref{input/@/regression,ottava@/.ly},
-@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
-
 
 @refbugs
 
@@ -1258,7 +1445,7 @@ a piece of music with multiple @code{\tag} entries,
 
 @seealso
 
-Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
+Examples: @lsr{parts,tag@/-filter@/.ly}
 
 
 @refbugs
@@ -1317,8 +1504,8 @@ The first @code{g} appears only once, although it was
 specified twice (once in each part).  Stem, slur, and tie directions are
 set automatically, depending whether there is a solo or unisono.  The
 first part (with context called @code{one}) always gets up stems, and
-`Solo', while the second (called @code{two}) always gets down stems and
-`Solo II'.
+@q{Solo}, while the second (called @code{two}) always gets down stems and
+@q{Solo II}.
 
 If you just want the merging parts, and not the textual markings, you
 may set the property @code{printPartCombineTexts} to false
@@ -1389,7 +1576,7 @@ will be ignored.
 @cindex Hiding staves
 
 In orchestral scores, staff lines that only have rests are usually
-removed; this saves some space.  This style is called `French Score'.
+removed; this saves some space.  This style is called @q{French Score}.
 For @internalsref{Lyrics},
 @internalsref{ChordNames} and @internalsref{FiguredBass}, this is
 switched on by default.  When the lines of these contexts turn out
@@ -1518,12 +1705,14 @@ statements that would switch to a different Voice.
 
 Quoting grace notes is broken and can even cause LilyPond to crash.
 
+Quoting nested triplets may result in poor notation.
+
+
 @seealso
 
 In this manual: @ref{Instrument transpositions}.
 
-Examples: @inputfileref{input/@/regression,quote@/.ly}
-@inputfileref{input/@/regression,quote@/-transposition@/.ly}
+Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly}
 
 Program reference: @internalsref{QuoteMusic}.
 
@@ -1561,19 +1750,19 @@ smaller = {
 
 \addQuote clarinet \relative {
   R1*20
-  r2 r8 c f f
+  r2 r8 c' f f
 }
 
 \new Staff \relative  <<
 
-  % setup a context for  cue  notes.
+  % setup a context for cue notes.
   \new Voice = "cue" { \smaller \skip 1*21 }
 
   \set Score.skipBars = ##t
 
   \new Voice {
     R1*20
-    \cueDuring #"clarinet" #1 {
+    \cueDuring #"clarinet" #UP {
       R1
     }
     g4 g2.
@@ -1676,7 +1865,7 @@ cadenza = \relative c' {
 
 In the 20th century, composers have greatly expanded the musical
 vocabulary.  With this expansion, many innovations in musical notation
-have been tried.  The book ``Music Notation in the 20th century'' by
+have been tried.  The book @q{Music Notation in the 20th century} by
 Kurt Stone gives a comprehensive overview (see @ref{Literature
 list}).
 
@@ -1690,7 +1879,7 @@ see those sections of the documentation.
 @menu
 * Polymetric notation::         
 * Time administration::         
-* Proportional notation::       
+* Proportional notation (introduction)::  
 * Clusters::                    
 * Special noteheads::           
 * Feathered beams::             
@@ -1711,7 +1900,7 @@ Double time signatures are not supported explicitly, but they can be
 faked.  In the next example, the markup for the time signature is
 created with a markup text.  This markup text is inserted in the
 @internalsref{TimeSignature} grob. See also
-@inputfileref{input/@/test,compound@/-time@/.ly}).
+@lsr{contemporary,compound-time-signature}.
 
 @lilypond[verbatim,ragged-right]
 % create 2/4 + 5/8
@@ -1906,10 +2095,15 @@ note duration and @code{ly:make-moment 7 16} is the duration of
 seven sixteenths notes.
 
 
-@node Proportional notation
-@subsection Proportional notation
+@node Proportional notation (introduction)
+@subsection Proportional notation (introduction)
 @cindex Proportional notation
 
+See @ref{Proportional notation}.
+
+
+TODO: remove all this stuff?
+
 Notes can be spaced proportionally to their time-difference by
 assigning a duration to @code{proportionalNotationDuration}
 
@@ -1944,9 +2138,9 @@ is removed by setting the @code{strict-note-spacing} property to
 
 @seealso
 
-@inputfileref{input/@/regression,spacing-proportional/.ly}
-@inputfileref{input/@/regression,spacing-strict-notespacing/.ly}
-@inputfileref{input/@/regression,spacing-strict-spacing-grace/.ly}
+Examples: @lsr{spacing,proportional@/-spacing@/.ly}, 
+@lsr{spacing,proportional@/-strict@/-grace@/-notes@/.ly}, and
+@lsr{spacing,proportional@/-strict@/-notespacing@/.ly}
 
 An example of strict proportional notation is in the
 example file @file{input/proportional.ly}.
@@ -1965,12 +2159,6 @@ chords, e.g.,
 \makeClusters { <c e > <b f'> }
 @end lilypond
 
-The following example (from
-@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
-looks like
-
-@lilypondfile[ragged-right,quote]{cluster.ly}
-
 Ordinary notes and clusters can be put together in the same staff,
 even simultaneously.  In such a case no attempt is made to
 automatically avoid collisions between ordinary notes and clusters.
@@ -1981,7 +2169,7 @@ Program reference: @internalsref{ClusterSpanner},
 @internalsref{ClusterSpannerBeacon},
 @internalsref{Cluster_spanner_engraver}.
 
-Examples: @inputfileref{input/@/regression,cluster@/.ly}.
+Examples: @lsr{contemporary,cluster@/.ly}.
 
 @refbugs
 
@@ -1995,7 +2183,7 @@ accurately.  Use @code{<g a>8 <e a>8} instead.
 @cindex note heads, special
 
 Different noteheads are used by various instruments for various
-meanings -- crosses are used for ``parlato'' with vocalists, stopped
+meanings -- crosses are used for @q{parlato} with vocalists, stopped
 notes on guitar; diamonds are used for harmonics on string instruments,
 etc.  There is a shorthand (@code{\harmonic}) for diamond shapes; the
 other notehead styles are produced by tweaking the property
@@ -2010,7 +2198,7 @@ e d <c f\harmonic> <d a'\harmonic>
 
 @noindent
 To see all notehead styles, please see
-@inputfileref{input/@/regression,note@/-head@/-style@/.ly}.
+@ref{Note head styles}.
 
 
 @seealso
@@ -2026,9 +2214,9 @@ property of a @code{Beam}.  The @code{\featherDurations} function
 can be used to adjust note durations.
 
 @lilypond[ragged-right,relative=1,fragment,verbatim,quote]
+\override Beam #'grow-direction = #LEFT
 \featherDurations #(ly:make-moment 5 4) 
 {
-  \override Beam #'grow-direction = #LEFT
   c16[ c c c c c c]
 }
 @end lilypond
@@ -2043,7 +2231,7 @@ music snippets.
 
 Improvisation is sometimes denoted with slashed note heads.  Such note
 heads can be created by adding a @internalsref{Pitch_squash_engraver}
-to the @internalsref{Staff} or @internalsref{Voice} context.  Then, the
+to the @internalsref{Voice} context.  Then, the
 following command
 
 @example
@@ -2059,7 +2247,7 @@ There are shortcuts @code{\improvisationOn} (and an accompanying
 the following example
 
 @lilypond[verbatim,ragged-right,quote]
-\new Staff \with {
+\new Voice \with {
   \consists Pitch_squash_engraver
 } \transpose c c' {
   e8 e g a a16(bes)(a8) g \improvisationOn
@@ -2094,7 +2282,9 @@ of @code{font-size} is a number indicating the size relative to the
 standard size for the current staff height.  Each step up is an
 increase of approximately 12% of the font size.  Six steps is exactly a
 factor two.  The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor.
+@code{font-size} number to a scaling factor.  The @code{font-size}
+property can also be set directly, so that only certain layout objects are
+affected.
 
 @lilypond[quote,fragment,relative=1,verbatim]
 c8
@@ -2173,8 +2363,6 @@ The other arguments  are the offset and the text of the label.
 
 Program reference: @internalsref{text-balloon-interface}.
 
-Examples: @inputfileref{input/@/regression,balloon@/.ly}.
-
 
 
 
@@ -2277,7 +2465,7 @@ combinations are possible, e.g.
 @cindex easy notation
 @cindex Hal Leonard
 
-The `easy play' note head includes a note name inside the head.  It is
+The @q{easy play} note head includes a note name inside the head.  It is
 used in music for beginners
 
 @lilypond[quote,ragged-right,verbatim,fragment,staffsize=26]
@@ -2327,8 +2515,6 @@ to @internalsref{Staff} context.  A bracket is started with
 
 Program reference: @internalsref{HorizontalBracket}.
 
-Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
-
 
 @node Coloring objects
 @subsection Coloring objects
@@ -2406,7 +2592,7 @@ An x11 color is not necessarily exactly the same shade as a similarly
 named normal color.
 
 Notes in a chord cannot be colored with @code{\override}; use
-@code{\tweak} instead.  See @ref{Objects connected to the input}
+@code{\tweak} instead.  See @ref{Objects connected to the input},
 for details.
 
 
@@ -2441,5 +2627,40 @@ This only functions inside chords, even for single notes
 Vertical lines can be drawn between staves synchronized with
 the notes.
 
-Examples: @inputfileref{input/@/regression,grid@/-lines@/.ly}.
+@lilypond[ragged-right,quote,verbatim]
+\layout {
+  \context {
+    \Staff
+    \consists "Grid_point_engraver" %% sets of grid
+    gridInterval = #(ly:make-moment 1 4)
+  }
+}
+
+\new Score \with {
+  \consists "Grid_line_span_engraver"
+  %% centers grid lines  horizontally below noteheads
+  \override NoteColumn #'X-offset = #-0.5
+}
+
+\new ChoirStaff <<
+  \new Staff {
+    \stemUp
+    \relative {
+      c'4. d8 e8 f g4
+    }
+  }
+  \new Staff {
+    %% centers grid lines  vertically
+    \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
+    \stemDown
+    \clef bass
+    \relative c {
+      c4  g'  f  e
+    }
+  }
+>>
+@end lilypond
+
+Examples: @lsrdir{education}
+