X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftext.itely;h=485ef646b9224325db19651ad3ed3a3f49d0adf0;hb=1b67b706db8d1098bd2724e99f99a22132c99c68;hp=dc8c011519e5dea36e4c09fcd389cb2bc3a98513;hpb=33da8a7ea4971d226b13337de0e7ba2f3d539474;p=lilypond.git

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index dc8c011519..485ef646b9 100644
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -6,7 +6,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.61"
+@c \version "2.12.0"
 
 @node Text
 @section Text
@@ -21,27 +21,27 @@ Some text elements that are not dealt with here are discussed in other
 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
 
 @menu
-* Writing text::                
-* Formatting text::             
-* Fonts::                       
+* Writing text::
+* Formatting text::
+* Fonts::
 @end menu
 
+@node Writing text
+@subsection Writing text
+
+This section introduces different ways of adding text to a score.
+
 @cindex Text, other languages
 @warning{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}.}
 
-@node Writing text
-@subsection Writing text
-
-This section introduces different ways of adding text to a score.
-
 @menu
-* Text scripts::                
-* Text spanners::               
-* Text marks::                  
-* Separate text::               
+* Text scripts::
+* Text spanners::
+* Text marks::
+* Separate text::
 @end menu
 
 
@@ -60,40 +60,40 @@ above or below the staff, using the
 syntax described in @ref{Direction and
 placement}.
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-d8^"pizz." e f g a4-"scherz." f
+@lilypond[quote,verbatim,relative=2]
+a8^"pizz." g f e a4-"scherz." f
 @end lilypond
 
 This syntax is actually a shorthand; more complex text
 formatting may be added to a note by explicitly using a
 @code{\markup} block, as described in @ref{Formatting text}.
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-d8^\markup { \italic pizz. } e f g 
+@lilypond[quote,verbatim,relative=2]
+a8^\markup { \italic pizz. } g f e
 a4_\markup { \tiny scherz. \bold molto } f
 @end lilypond
 
 By default, text indications do not influence the note spacing.
 However, their widths can be taken into account:
-in the following example, the first text string does not affect 
+in the following example, the first text string does not affect
 spacing, whereas the second one does.
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-d8^"pizz." e f g
+@lilypond[quote,verbatim,relative=2]
+a8^"pizz." g f e
 \textLengthOn
 a4_"scherzando" f
 @end lilypond
 
-@predefined
 
+@predefined
 @funindex \textLengthOn
 @code{\textLengthOn},
 @funindex \textLengthOff
-@code{\textLengthOff}
+@code{\textLengthOff}.
+@endpredefined
 
 
 @seealso
-
 Notation Reference:
 @ref{Formatting text},
 @ref{Direction and placement}.
@@ -104,6 +104,7 @@ Snippets:
 Internals Reference:
 @rinternals{TextScript}.
 
+
 @knownissues
 
 Checking to make sure that text scripts and lyrics are within the
@@ -127,9 +128,9 @@ multiple notes with dotted lines.
 Such objects, called @qq{spanners}, may be created
 from one note to another using the following syntax:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-\override TextSpanner #'bound-details #'left #'text = "rit." 
-b1\startTextSpan 
+@lilypond[verbatim,quote,relative=2]
+\override TextSpanner #'(bound-details left text) = "rit."
+b1\startTextSpan
 e,\stopTextSpan
 @end lilypond
 
@@ -139,9 +140,9 @@ object properties.  By default it is printed in italic characters,
 but different formatting can be obtained using
 @code{\markup} blocks, as described in @ref{Formatting text}.
 
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text =
-  \markup { \upright "rit." } 
+@lilypond[quote,relative=2,verbatim]
+\override TextSpanner #'(bound-details left text) =
+  \markup { \upright "rit." }
 b1\startTextSpan c
 e,\stopTextSpan
 @end lilypond
@@ -149,17 +150,18 @@ e,\stopTextSpan
 The line style, as well as the text string, can be defined as an
 object property.  This syntax is described in @ref{Line styles}.
 
-@predefined
 
+@predefined
 @funindex textSpannerUp
 @code{\textSpannerUp},
 @funindex textSpannerDown
 @code{\textSpannerDown},
 @funindex textSpannerNeutral
-@code{\textSpannerNeutral}
+@code{\textSpannerNeutral}.
+@endpredefined
 
-@seealso
 
+@seealso
 Notation Reference:
 @ref{Line styles},
 @ref{Dynamics}.
@@ -186,7 +188,7 @@ the syntax described in @ref{Rehearsal marks}:
 @c \mark needs to be placed on a separate line (it's not
 @c attached to an object like \markup is). -vv
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c4
 \mark "Allegro"
 c c c
@@ -196,7 +198,7 @@ This syntax makes it possible to put any text on a bar line;
 more complex text formatting may be added using a @code{\markup}
 block, as described in @ref{Formatting text}:
 
-@lilypond[fragment,quote,ragged-right,verbatim,relative=1]
+@lilypond[quote,verbatim,relative=1]
 <c e>1
 \mark \markup { \italic { colla parte } }
 <d f>2 <e g>
@@ -208,20 +210,19 @@ This syntax also allows to print special signs, like coda, segno
 or fermata, by specifying the appropriate symbol name as explained in
 @ref{Music notation inside markup}:
 
-@lilypond[fragment,quote,ragged-right,verbatim,relative=1]
-<f bes>2 <d aes'>
+@lilypond[quote,verbatim,relative=2]
+<bes f>2 <aes d>
 \mark \markup { \musicglyph #"scripts.ufermata" }
 <e g>1
 @end lilypond
 
 @noindent
 Such objects are only typeset above the top staff of the score; depending on
-whether they are specified at the end or the middle of a bar, they 
-can be placed above the bar line or between notes.  When specified at the
-beginning of a score or at a line break, marks will be printed at
-the beginning of the line (the next line, in case of a line break).
+whether they are specified at the end or the middle of a bar, they
+can be placed above the bar line or between notes.  When specified at a
+line break, the mark will be printed at the beginning of the next line.
 
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
 \mark "Allegro"
 c1 c
 \mark "assai" \break
@@ -240,8 +241,8 @@ c  c
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {printing-marks-on-every-staff.ly}
 
-@seealso
 
+@seealso
 Notation Reference:
 @ref{Rehearsal marks},
 @ref{Formatting text},
@@ -254,6 +255,7 @@ Snippets:
 Internals Reference:
 @rinternals{RehearsalMark}.
 
+
 @knownissues
 @c  To be removed when Issue 69 in the tracker gets fixed. -vv
 
@@ -282,12 +284,12 @@ expression}.  This syntax is described in @ref{File structure}.
 
 @noindent
 This allows printing text separately
-from the music, which is particularly 
+from the music, which is particularly
 useful when the input file contains
 several music pieces, as described in
 @ref{Multiple scores in a book}.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[quote,verbatim]
 \score {
   c'1
 }
@@ -299,28 +301,27 @@ several music pieces, as described in
 }
 @end lilypond
 
-Using a specific syntax, text blocks can be spread
-over multiple pages, making it possible to print
-text documents or books (and therefore to
-use LilyPond as a word processor).  This syntax is described in
-@ref{Multi-page markup}.
+Separate text blocks can be spread over multiple pages,
+making it possible to print text documents or books entirely
+within LilyPond.  This feature, and the specific syntax it
+requires, are described in @ref{Multi-page markup}.
 
-@predefined
 
-@code{\markup},
+@predefined
 @funindex \markuplines
-@code{\markuplines}
+@code{\markup},
+@code{\markuplines}.
+@endpredefined
+
 
-@ignore
 @snippets
 
-TODO: add convenient snippets in input/new -vv
-@end ignore
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{stand-alone-two-column-markup.ly}
 
 @seealso
-
 Notation Reference: @ref{Formatting text},
-@ref{File structure}, 
+@ref{File structure},
 @ref{Multiple scores in a book},
 @ref{Multi-page markup}.
 
@@ -337,12 +338,12 @@ This section presents basic and advanced text formatting,
 using the @code{\markup} mode specific syntax.
 
 @menu
-* Text markup introduction::    
-* Selecting font and font size::      
-* Text alignment::              
-* Graphic notation inside markup::  
-* Music notation inside markup::  
-* Multi-page markup::          
+* Text markup introduction::
+* Selecting font and font size::
+* Text alignment::
+* Graphic notation inside markup::
+* Music notation inside markup::
+* Multi-page markup::
 @end menu
 
 @node Text markup introduction
@@ -355,7 +356,7 @@ using the @code{\markup} mode specific syntax.
 @funindex \markup
 
 A @code{\markup} block is used to typeset text with an extensible
-specific syntax called @qq{markup mode}.
+syntax called @qq{markup mode}.
 
 @cindex markup expressions
 @cindex markup syntax
@@ -366,16 +367,16 @@ The markup syntax is similar to LilyPond's usual syntax: a
 and therefore does not need to be enclosed with braces.
 
 Unlike simple @qq{quoted text} indications, @code{\markup} blocks
-may contain nested expressions or specific commands,
+may contain nested expressions or markup commands,
 entered using the backslash @code{\} character.
 Such commands only affect the first following expression.
 
-@lilypond[quote,verbatim,fragment,relative=1]
-e1-\markup intenso
+@lilypond[quote,verbatim,relative=2]
+a1-\markup intenso
 a2^\markup { poco \italic più forte  }
 c e1
 d2_\markup { \italic "string. assai" }
-e 
+e
 b1^\markup { \bold { molto \italic  agitato } }
 c
 @end lilypond
@@ -390,37 +391,29 @@ A @code{\markup} block may also contain quoted text strings.
 Such strings are treated as minimal text expressions, and
 therefore any markup command or special character (such as
 @code{\} and @code{#}) will be printed verbatim without affecting
-the formatting of the text.  This syntax even allows to print
-double quotation marks, by preceding them with backslashes
-
-@lilypond[quote,verbatim,fragment,relative=1]
-d1^"\italic markup..."
-d_\markup \italic "... prints \"italic\" letters!"
-d d
-@end lilypond
+the formatting of the text.  Double quotation marks themselves
+may be printed by preceding them with backslashes.
 
-The way markup expressions are defined affects 
-how these expressions will be stacked, centered and aligned
-when using the commands explained in @ref{Text alignment}.
-
-@lilypond[quote,verbatim,fragment,relative=1]
-c1^\markup { \column { a bbbb \line { c d } } }
-c1^\markup { \center-column { a bbbb c } }
-c1^\markup { \line { a b c } }
+@lilypond[quote,verbatim,relative=2]
+a1^"\italic markup..."
+a_\markup { \italic "... prints \"italic\" letters!" }
+a a
 @end lilypond
 
-Lists of words that are not enclosed with double quotes
-or preceded by a command are not treated as a distinct
-expression.  In the following example, the first two
-@code{\markup} expressions are equivalent:
+To be treated as a distinct expression, a list of words needs
+to be enclosed with double quotes or preceded by a command.
+The way markup expressions are defined affects how these
+expressions will be stacked, centered and aligned; in the
+following example, the second @code{\markup} expression is
+treated the same as the first one:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=2]
 c1^\markup { \center-column { a bbb c } }
 c1^\markup { \center-column { a { bbb c } } }
 c1^\markup { \center-column { a \line { bbb c } } }
+c1^\markup { \center-column { a "bbb c" } }
 @end lilypond
 
-
 Markups can be stored in variables.  Such variables may be
 directly attached to notes:
 
@@ -440,16 +433,12 @@ An exhaustive list of @code{\markup}-specific commands can be found in
 
 
 @seealso
-
 Notation Reference:
 @ref{Text markup commands}.
 
 Snippets:
 @rlsr{Text}.
 
-Internals Reference:
-@rinternals{TextScript}.
-
 Installed files:
 @file{scm/@/markup@/.scm}.
 
@@ -470,15 +459,13 @@ Syntax errors for markup mode can be confusing.
 Basic font switching is supported in markup mode:
 
 @lilypond[quote,verbatim,relative=2]
-{
-  d1^\markup { 
-    \bold { Più mosso } 
-    \italic { non troppo \underline Vivo } 
-  }
-  r2 r4 r8
-  d,_\markup { \italic quasi \smallCaps Tromba }
-  f1 d2 r
+d1^\markup {
+  \bold { Più mosso }
+  \italic { non troppo \underline Vivo }
 }
+r2 r4 r8
+d,_\markup { \italic quasi \smallCaps Tromba }
+f1 d2 r
 @end lilypond
 
 @cindex font size
@@ -486,16 +473,15 @@ Basic font switching is supported in markup mode:
 @funindex \fontsize
 @funindex \smaller
 @funindex \larger
-@funindex \bigger
 @funindex \magnify
 
 The size of the characters can also be altered in different ways:
 @itemize
 @item
-the font size can be defined to an absolute value,
+the font size can be set to predefined standard sizes,
 
 @item
-predefined commands allow to easily select standard sizes,
+the font size can be set to an absolute value,
 
 @item
 the font size can also be changed relatively to its previous value.
@@ -504,21 +490,23 @@ the font size can also be changed relatively to its previous value.
 @noindent
 The following example demonstrates these three methods:
 
-@lilypond[quote,verbatim,relative=2]
-{
-  f1^\markup { \fontsize #5 Sinfonia } 
-  a,_\markup { 
-    \tiny espressivo
-    \large e
-    \normalsize intenso 
-  }
-  bes^\markup { (con 
-    \larger grande 
-    \smaller emozione 
-    \magnify #0.6 { e sentimento } )
-  }
-  d c2 r8 c bes a g1
+@lilypond[quote,verbatim,relative=1]
+f1_\markup {
+  \tiny espressivo
+  \large e
+  \normalsize intenso
+}
+a^\markup {
+  \fontsize #5 Sinfonia
+  \fontsize #2 da
+  \fontsize #3 camera
 }
+bes^\markup { (con
+  \larger grande
+  \smaller emozione
+  \magnify #0.6 { e sentimento } )
+}
+d c2 r8 c bes a g1
 @end lilypond
 
 @cindex subscript
@@ -533,7 +521,7 @@ these are printed in a smaller size, but a normal size can be used as well:
 \markup {
   \column {
     \line { 1 \super st movement }
-    \line { 1 \normal-size-super st movement 
+    \line { 1 \normal-size-super st movement
       \sub { (part two) }  }
   }
 }
@@ -543,7 +531,7 @@ these are printed in a smaller size, but a normal size can be used as well:
 
 The markup mode provides an easy way to select alternate
 font families.  The default serif font, of roman type, is
-automatically selected unless specified otherwise: on the
+automatically selected unless specified otherwise; on the
 last line of the following example, there is no difference
 between the first and the second word.
 
@@ -586,26 +574,32 @@ easily be solved by concatenating the text elements together:
 }
 @end lilypond
 
-An exhaustive list of font-switching, font-size
-and font-families related commands can be found in @ref{Font}.
+An exhaustive list of font switching, and custom font usage
+commands can be found in @ref{Font}.
 
 Defining custom font sets is also possible, as explained in
 @ref{Fonts}.
 
-@predefined
 
+@predefined
 @funindex \teeny
-@funindex \tiny
-@funindex \small
-@funindex \normalsize
-@funindex \large
-@funindex \huge
 @code{\teeny},
+@funindex \tiny
 @code{\tiny},
+@funindex \small
 @code{\small},
+@funindex \normalsize
 @code{\normalsize},
+@funindex \large
 @code{\large},
-@code{\huge}.
+@funindex \huge
+@code{\huge},
+@funindex \smaller
+@code{\smaller},
+@funindex \larger
+@code{\larger}.
+@endpredefined
+
 
 @seealso
 Notation Reference:
@@ -630,10 +624,9 @@ Installed files:
 @cindex text, aligning
 @cindex aligning text
 
-This subsection discusses how to place text in markup mode,
-inside a @code{\markup} block.  Markup objects can also
-be moved as a whole, using the syntax described in
-@rlearning{Moving objects}.
+This subsection discusses how to place text in markup mode.
+Markup objects can also be moved as a whole, using the syntax
+described in @rlearning{Moving objects}.
 
 @c Padding commands should be mentioned on this page, but
 @c most of these require \box to be more clearly illustrated. -vv
@@ -649,14 +642,14 @@ a text indication is aligned on its left edge: in the following
 example, there is no difference
 between the first and the second markup.
 
-@lilypond[quote,verbatim,fragment,relative=1]
-a1-\markup { poco }
-e'
-a,-\markup { \left-align poco }
-e'
-a,-\markup { \center-align { poco } }
-e'
-a,-\markup { \right-align poco }
+@lilypond[quote,verbatim,relative=2]
+d1-\markup { poco }
+f
+d-\markup { \left-align poco }
+f
+d-\markup { \center-align { poco } }
+f
+d-\markup { \right-align poco }
 @end lilypond
 
 @funindex \halign
@@ -664,7 +657,7 @@ a,-\markup { \right-align poco }
 Horizontal alignment may be fine-tuned
 using a numeric value:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=2]
 a1-\markup { \halign #-1 poco }
 e'
 a,-\markup { \halign #0 poco }
@@ -678,7 +671,7 @@ a,-\markup { \halign #2 poco }
 Some objects may have alignment procedures of their own,
 and therefore are not affected by these commands.  It is
 possible to move such markup objects as a whole, as shown
-for instance in @ref{Text marks},
+for instance in @ref{Text marks}.
 
 @cindex text, vertical alignment
 @cindex vertical text alignment
@@ -694,8 +687,8 @@ or an invisible object.  The following example demonstrates these
 two possibilities; the last markup in this example has no anchor
 point, and therefore is not moved.
 
-@lilypond[quote,verbatim,fragment,relative=1]
-d2^\markup { 
+@lilypond[quote,verbatim,relative=1]
+d2^\markup {
   Acte I
   \raise #2 { Scène 1 }
 }
@@ -720,7 +713,7 @@ alignment of text objects in markup mode.  Any object
 affected by these commands must be preceded with an
 anchor point:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=1]
 d2^\markup {
   Acte I
   \translate #'(-1 . 2) "Scène 1"
@@ -788,7 +781,7 @@ or any other markup expression:
   }
 }
 \markup {
-  \fill-line { 1885 } 
+  \fill-line { 1885 }
 }
 @end lilypond
 
@@ -811,9 +804,9 @@ the following example.
     \wordwrap \italic {
       (La escena representa el corral de una casa de
       gitanos en el Albaicín de Granada. Al fondo una
-      puerta por la que se vé el negro interior de
+      puerta por la que se ve el negro interior de
       una Fragua, iluminado por los rojos resplandores
-      del fuego.) 
+      del fuego.)
     }
     \hspace #0
 
@@ -832,6 +825,7 @@ the following example.
 An exhaustive list of text alignment commands
 can be found in @ref{Align}.
 
+
 @seealso
 Learning Manual:
 @rlearning{Moving objects}.
@@ -856,7 +850,7 @@ Installed files:
 @cindex drawing graphic objects
 
 Various graphic objects may be added to a score,
-using specific markup commands.
+using markup commands.
 
 @funindex \box
 @funindex \circle
@@ -867,7 +861,7 @@ using specific markup commands.
 @cindex decorating text
 @cindex framing text
 
-Some markup commands allow to decorate text elements
+Some markup commands allow decoration of text elements
 with graphics, as demonstrated in the following example.
 
 @lilypond[quote,verbatim]
@@ -895,8 +889,8 @@ with graphics, as demonstrated in the following example.
 @cindex padding around text
 @cindex text padding
 
-Some commands may require to increase the padding around
-the text: this is achieved with some specific commands
+Some commands may require an increase in the padding around
+the text; this is achieved with some markup commands
 exhaustively described in @ref{Align}.
 
 @lilypond[quote,verbatim]
@@ -933,7 +927,7 @@ Flute quartet keeps very uneven time."
 
 Other graphic elements or symbols may be printed
 without requiring any text.  As with any markup
-expression, such objects can be combined together:
+expression, such objects can be combined.
 
 @lilypond[quote,verbatim]
 \markup {
@@ -967,7 +961,7 @@ using native PostScript code.  In such a case, it
 may be useful to explicitely specify the size of the
 drawing, as demonstrated below:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=1]
 c1^\markup {
   \combine
     \epsfile #X #10 #"./context-example.eps"
@@ -990,6 +984,7 @@ c
 An exhaustive list of graphics-specific commands
 can be found in @ref{Graphic}.
 
+
 @seealso
 Notation Reference:
 @ref{Graphic},
@@ -1004,16 +999,17 @@ Installed files:
 @file{scm/@/define@/-markup@/-commands@/.scm},
 @file{scm/@/stencil@/.scm}.
 
+
 @node Music notation inside markup
 @unnumberedsubsubsec Music notation inside markup
 
 Various musical notation elements may be added
 to a score, inside a markup object.
 
-Notes and accidentals can be entered using specific
+Notes and accidentals can be entered using markup
 commands:
 
-@lilypond[quote,verbatim,fragment,relative=2]
+@lilypond[quote,verbatim,relative=2]
 a2 a^\markup {
   \note #"4" #1
   =
@@ -1034,7 +1030,7 @@ a1_\markup {
 Other notation objects may also be printed
 in markup mode:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=1]
 g1 bes
 ees-\markup {
   \finger 4
@@ -1050,14 +1046,14 @@ d-\markup {
   \markalphabet #8
   \markletter #8
 }
-@end lilypond 
+@end lilypond
 
 More generally, any available musical symbol may be
 included separately in a markup object, as demonstrated
 below; an exhaustive list of these symbols and their
 names can be found in @ref{The Feta font}.
 
-@lilypond[quote,verbatim,fragment,relative=2]
+@lilypond[quote,verbatim,relative=2]
 c2
 c'^\markup { \musicglyph #"eight" }
 c,4
@@ -1065,7 +1061,11 @@ c,8._\markup { \musicglyph #"clefs.G_change" }
 c16
 c2^\markup { \musicglyph #"timesig.neomensural94" }
 @end lilypond
+
 @c TODO: add \lookup here? -vv
+@c Probably better not to document \lookup, which is useful only for
+@c printing braces, and instead document \left-brace and \right-brace
+@c when these become available  -td
 
 @noindent
 Another way of printing non-text glyphs is described
@@ -1074,7 +1074,7 @@ in @ref{Fonts explained}.
 The markup mode also supports diagrams for specific
 instruments:
 
-@lilypond[quote,verbatim,fragment,relative=2]
+@lilypond[quote,verbatim,relative=2]
 c1^\markup {
   \fret-diagram-terse #"x;x;o;2;3;2;"
 }
@@ -1100,10 +1100,10 @@ A whole score can even be nested inside a markup object.
 In such a case, the nested @code{\score} block must
 contain a @code{\layout} block, as demonstrated here:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=1]
 c4 d^\markup {
   \score {
-    \relative { c4 d e f }
+    \relative c' { c4 d e f }
     \layout { }
   }
 }
@@ -1114,6 +1114,7 @@ c d e f
 An exhaustive list of music notation related commands can be
 found in @ref{Music}.
 
+
 @seealso
 Notation Reference:
 @ref{Music},
@@ -1130,11 +1131,12 @@ Installed files:
 @file{scm/@/fret@/-diagrams@/.scm},
 @file{scm/@/harp@/-pedals@/.scm}.
 
+
 @node Multi-page markup
 @unnumberedsubsubsec Multi-page markup
 
 Although standard markup objects are not breakable, a
-specific syntax allows to enter lines of text that can
+specific syntax makes it possible to enter lines of text that can
 spread over multiple pages:
 
 @lilypond[quote,verbatim]
@@ -1144,14 +1146,14 @@ spread over multiple pages:
     ...
   }
   \wordwrap-lines {
-    An other very long paragraph.
+    Another very long paragraph.
     ...
   }
   ...
 }
 @end lilypond
 
-This specific syntax accepts a list of markups, that can be
+This syntax accepts a list of markups, that can be
 @itemize
 @item
 the result of a markup list command,
@@ -1164,6 +1166,7 @@ a list of markup lists.
 An exhaustive list of markup list commands can be found in
 @ref{Text markup list commands}.
 
+
 @seealso
 Notation Reference:
 @ref{Text markup list commands},
@@ -1177,9 +1180,11 @@ Internals Reference: @rinternals{TextScript}.
 Installed files:
 @file{scm/@/define@/-markup@/-commands@/.scm}.
 
+
 @predefined
 @funindex \markuplines
-@code{\markuplines}
+@code{\markuplines}.
+@endpredefined
 
 
 @node Fonts
@@ -1207,10 +1212,10 @@ the selected fonts are rendered using Pango.
 
 Music notation fonts can be described as a set of
 specific glyphs, ordered in several families.
-The following syntax allows to directly use various
-LilyPond @code{feta} non-text fonts in markup mode:
+The following syntax allows various LilyPond @code{feta} non-text
+fonts to be used directly in markup mode:
 
-@lilypond[quote,verbatim,fragment,relative=2]
+@lilypond[quote,verbatim,relative=2]
 a1^\markup {
   \vcenter {
     \override #'(font-encoding . fetaBraces)
@@ -1237,16 +1242,18 @@ determined by the Pango installation.
 
 Each family may include different shapes and series.
 The following example demonstrates the ability to select
-alternate families, shapes, series and sizes:
-
-@lilypond[quote,verbatim,fragment,relative=2]
-  \override Score.RehearsalMark #'font-family = #'typewriter
-  \mark \markup "Ouverture"
-  \key d \major
-  \override  Voice.TextScript #'font-shape = #'italic
-  \override  Voice.TextScript #'font-series = #'bold
-  d''2.^\markup "Allegro"
-  r4
+alternate families, shapes, series and sizes.  The value
+supplied to @code{font-size} is the required change from the
+default size.
+
+@lilypond[quote,verbatim,relative=2]
+\override Score.RehearsalMark #'font-family = #'typewriter
+\mark \markup "Ouverture"
+\override Voice.TextScript #'font-shape = #'italic
+\override Voice.TextScript #'font-series = #'bold
+d2.^\markup "Allegro"
+\override Voice.TextScript #'font-size = #-3
+c4^smaller
 @end lilypond
 
 @noindent
@@ -1276,19 +1283,12 @@ it is preferable to use the simpler syntax explained in
 }
 @end lilypond
 
-@ignore
-@c FIXME: This needs an example -vv
-
-The size of the font may be set with the @code{font-size}
-property.  The resulting size is taken relative to the
-@code{text-font-size} as defined in the @code{\paper} block.
-@end ignore
-
 Although it is easy to switch between preconfigured fonts,
 it is also possible to use other fonts, as explained in the
 following sections: @ref{Single entry fonts} and
 @ref{Entire document fonts}.
 
+
 @seealso
 Notation Reference:
 @ref{The Feta font},
@@ -1296,18 +1296,19 @@ Notation Reference:
 @ref{Selecting font and font size},
 @ref{Font}.
 
+
 @node Single entry fonts
 @unnumberedsubsubsec Single entry fonts
 
 Any font that is installed on the operating system and recognized
 by FontConfig may be used in a score, using the following syntax:
 
-@lilypond[quote,verbatim,fragment,relative=1]
+@lilypond[quote,verbatim,relative=2]
 \override Staff.TimeSignature #'font-name = #"Charter"
 \override Staff.TimeSignature #'font-size = #2
 \time 3/4
 
-c1_\markup {
+a1_\markup {
   \override #'(font-name . "Vera Bold")
     { Vera Bold }
 }
@@ -1326,6 +1327,7 @@ lilypond -dshow-available-fonts x
 The last argument of the command can be anything, but has to be
 present.
 
+
 @seealso
 Notation Reference:
 @ref{Fonts explained},
@@ -1337,15 +1339,14 @@ Snippets:
 Installed files:
 @file{lily/@/font@/-config@/-scheme@/.cc}.
 
+
 @node Entire document fonts
 @unnumberedsubsubsec Entire document fonts
 
-
-It is possible to change the default font families for the
-entire document.  In such a case, the following syntax has
-to be used, by providing three font families that will be
-respectively used as @emph{roman}, @emph{sans} and @emph{typewriter}
-fonts, as explained in @ref{Fonts explained}.
+It is possible to change the fonts to be used as the default fonts in
+the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
+specifying them, in that order, as shown in the example below.  For an
+explanation of fonts, see @ref{Fonts explained}.
 
 @cindex font families, setting
 @funindex make-pango-font-tree
@@ -1371,6 +1372,7 @@ fonts, as explained in @ref{Fonts explained}.
 @c we don't do Helvetica / Courier, since GS incorrectly loads
 @c Apple TTF fonts
 
+
 @seealso
 Notation Reference:
 @ref{Fonts explained},