X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fuser%2Ftext.itely;h=a6638313447428b4664b844eb94886ca1ee92ed4;hb=b97565a9af1c13369ac7e7e9ea80c2638dbc0e51;hp=39b10e2fc49319d6d10e465125cde65a411bb484;hpb=a3053464dbe2295f66decd9d328b1c20ad6f6678;p=lilypond.git

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index 39b10e2fc4..a663831344 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,19 +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 
+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
@@ -239,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},
@@ -253,6 +255,7 @@ Snippets:
 Internals Reference:
 @rinternals{RehearsalMark}.
 
+
 @knownissues
 @c  To be removed when Issue 69 in the tracker gets fixed. -vv
 
@@ -281,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
 }
@@ -298,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}.
 
@@ -336,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
@@ -354,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
@@ -365,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
@@ -392,10 +394,10 @@ therefore any markup command or special character (such as
 the formatting of the text.  Double quotation marks themselves
 may be printed by preceding them with backslashes.
 
-@lilypond[quote,verbatim,fragment,relative=1]
-d1^"\italic markup..."
-d_\markup { \italic "... prints \"italic\" letters!" }
-d d
+@lilypond[quote,verbatim,relative=2]
+a1^"\italic markup..."
+a_\markup { \italic "... prints \"italic\" letters!" }
+a a
 @end lilypond
 
 To be treated as a distinct expression, a list of words needs
@@ -403,9 +405,9 @@ 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
-not treated differently from the first one :
+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 } } }
@@ -431,7 +433,6 @@ An exhaustive list of @code{\markup}-specific commands can be found in
 
 
 @seealso
-
 Notation Reference:
 @ref{Text markup commands}.
 
@@ -458,9 +459,9 @@ 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 } 
+d1^\markup {
+  \bold { Più mosso }
+  \italic { non troppo \underline Vivo }
 }
 r2 r4 r8
 d,_\markup { \italic quasi \smallCaps Tromba }
@@ -472,16 +473,15 @@ f1 d2 r
 @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 set to an absolute value,
+the font size can be set to predefined standard sizes,
 
 @item
-the font size can be set to predefined 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.
@@ -490,18 +490,18 @@ 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]
+@lilypond[quote,verbatim,relative=1]
 f1_\markup {
   \tiny espressivo
   \large e
   \normalsize intenso
 }
-a,^\markup {
+a^\markup {
   \fontsize #5 Sinfonia
   \fontsize #2 da
   \fontsize #3 camera
 }
-bes^\markup { (con 
+bes^\markup { (con
   \larger grande
   \smaller emozione
   \magnify #0.6 { e sentimento } )
@@ -521,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) }  }
   }
 }
@@ -574,30 +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
-@funindex \smaller
-@funindex \larger
 @code{\teeny},
+@funindex \tiny
 @code{\tiny},
+@funindex \small
 @code{\small},
+@funindex \normalsize
 @code{\normalsize},
+@funindex \large
 @code{\large},
+@funindex \huge
 @code{\huge},
+@funindex \smaller
 @code{\smaller},
+@funindex \larger
 @code{\larger}.
+@endpredefined
+
 
 @seealso
 Notation Reference:
@@ -622,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
@@ -641,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
@@ -656,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 }
@@ -670,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
@@ -686,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 }
 }
@@ -712,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"
@@ -780,7 +781,7 @@ or any other markup expression:
   }
 }
 \markup {
-  \fill-line { 1885 } 
+  \fill-line { 1885 }
 }
 @end lilypond
 
@@ -805,7 +806,7 @@ the following example.
       gitanos en el Albaicín de Granada. Al fondo una
       puerta por la que se ve el negro interior de
       una Fragua, iluminado por los rojos resplandores
-      del fuego.) 
+      del fuego.)
     }
     \hspace #0
 
@@ -824,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}.
@@ -848,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
@@ -888,7 +890,7 @@ with graphics, as demonstrated in the following example.
 @cindex text padding
 
 Some commands may require an increase in the padding around
-the text; this is achieved with some specific commands
+the text; this is achieved with some markup commands
 exhaustively described in @ref{Align}.
 
 @lilypond[quote,verbatim]
@@ -956,10 +958,10 @@ include external image files converted to the
 Encapsulated PostScript format (@emph{eps}), or
 to directly embed graphics into the input file,
 using native PostScript code.  In such a case, it
-may be useful to explicitely specify the size of the
+may be useful to explicitly 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"
@@ -982,6 +984,7 @@ c
 An exhaustive list of graphics-specific commands
 can be found in @ref{Graphic}.
 
+
 @seealso
 Notation Reference:
 @ref{Graphic},
@@ -996,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
   =
@@ -1026,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
@@ -1042,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
@@ -1057,16 +1061,16 @@ c,8._\markup { \musicglyph #"clefs.G_change" }
 c16
 c2^\markup { \musicglyph #"timesig.neomensural94" }
 @end lilypond
-@c TODO: add \lookup here? -vv
 
 @noindent
-Another way of printing non-text glyphs is described
-in @ref{Fonts explained}.
+Another way of printing non-text glyphs is described in
+@ref{Fonts explained}.  This is useful for printing braces of
+various sizes.
 
 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;"
 }
@@ -1092,10 +1096,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 { }
   }
 }
@@ -1106,6 +1110,7 @@ c d e f
 An exhaustive list of music notation related commands can be
 found in @ref{Music}.
 
+
 @seealso
 Notation Reference:
 @ref{Music},
@@ -1122,11 +1127,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]
@@ -1136,14 +1142,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,
@@ -1156,6 +1162,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},
@@ -1169,9 +1176,11 @@ Internals Reference: @rinternals{TextScript}.
 Installed files:
 @file{scm/@/define@/-markup@/-commands@/.scm}.
 
+
 @predefined
 @funindex \markuplines
-@code{\markuplines}
+@code{\markuplines}.
+@endpredefined
 
 
 @node Fonts
@@ -1191,6 +1200,7 @@ and how they may be changed in scores.
 
 @cindex Pango
 @cindex fonts, explained
+@cindex braces, various sizes
 @funindex font-interface
 
 Fonts are handled through several libraries.
@@ -1199,10 +1209,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)
@@ -1218,8 +1228,17 @@ a1^\markup {
 @end lilypond
 
 @noindent
-A simpler, but more limited syntax is also described in
-@ref{Music notation inside markup}.
+However, all these glyphs except the braces of various sizes
+contained in @code{fetaBraces} are available using the
+simpler syntax described in @ref{Music notation inside markup}.
+
+When using the glyphs contained in @code{fetaBraces}, the size of
+the brace is specified by the numerical part of the glyph name, in
+arbitrary units.  Any integer from @code{0} to @code{575} inclusive
+may be specified, @code{0} giving the smallest brace.  The optimum
+value must be determined by trial and error.  These glyphs are all
+left braces; right braces may be obtained by rotation, see
+@ref{Rotating objects}.
 
 Three families of text fonts are made available: the
 @emph{roman} (serif) font, that defaults to New Century
@@ -1229,16 +1248,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
@@ -1268,19 +1289,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},
@@ -1288,18 +1302,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 }
 }
@@ -1318,6 +1333,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},
@@ -1329,15 +1345,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
@@ -1363,6 +1378,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},