Docs: NR 1.8 Text: Clarify use of fetaBraces

[lilypond.git] / Documentation / user / text.itely

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index f82dc783dba78869f0209a071427e18b23ce5f6e..b235dfda0896cd7f9d36a80376b41c133ba9e1d3 100644 (file)
--- 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
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.57"
+@c \version "2.12.0"

 
 @node Text
 @section Text
 
 @node Text
 @section Text


@@ -20,89 +20,90 @@ formatting) in music scores.
 Some text elements that are not dealt with here are discussed in other
 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
 
 Some text elements that are not dealt with here are discussed in other
 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
 

-
-@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}.}
-

 @menu
 @menu

-* Writing text::                
-* Formatting text::             
-* Fonts::                       
+* Writing text::
+* Formatting text::
+* Fonts::

 @end menu
 
 @end menu
 

-

 @node Writing text
 @subsection Writing text
 
 This section introduces different ways of adding text to a score.
 
 @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}.}
+

 @menu
 @menu

-* Text scripts::                
-* Text spanners::               
-* Text marks::                  
-* Separate text::               
+* Text scripts::
+* Text spanners::
+* Text marks::
+* Separate text::

 @end menu
 
 
 @node Text scripts
 @end menu
 
 
 @node Text scripts

-@subsubsection Text scripts
+@unnumberedsubsubsec Text scripts

 
 @cindex Text scripts
 @cindex text items, non-empty
 @cindex non-empty texts
 @cindex quoted text
 
 
 @cindex Text scripts
 @cindex text items, non-empty
 @cindex non-empty texts
 @cindex quoted text
 

-Simple @q{quoted text} indications may be added
+Simple @qq{quoted text} indications may be added

 to a score, as demonstrated in the following example.
 to a score, as demonstrated in the following example.

-Such indications can be manually placed
+Such indications may be manually placed

 above or below the staff, using the
 syntax described in @ref{Direction and
 placement}.
 
 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}.
 
 @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:
 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.
 
 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
 
 \textLengthOn
 a4_"scherzando" f
 @end lilypond
 

-@predefined

 
 

+@predefined

 @funindex \textLengthOn
 @code{\textLengthOn},
 @funindex \textLengthOff
 @funindex \textLengthOn
 @code{\textLengthOn},
 @funindex \textLengthOff

-@code{\textLengthOff}
+@code{\textLengthOff}.
+@endpredefined

 
 
 @seealso
 
 
 @seealso

-
-Notation Reference: @ref{Formatting text},
+Notation Reference:
+@ref{Formatting text},

 @ref{Direction and placement}.
 
 Snippets:
 @rlsr{Text}.
 
 @ref{Direction and placement}.
 
 Snippets:
 @rlsr{Text}.
 

-Internals Reference: @rinternals{TextScript}.
+Internals Reference:
+@rinternals{TextScript}.
+

 
 @knownissues
 
 
 @knownissues
 


@@ -117,19 +118,19 @@ default; to enable it, use
 
 
 @node Text spanners
 
 
 @node Text spanners

-@subsubsection Text spanners
+@unnumberedsubsubsec Text spanners

 
 @cindex Text spanners
 
 Some performance indications, e.g., @notation{rallentando} or
 @notation{accelerando}, are written as text and are extended over
 multiple notes with dotted lines.
 
 @cindex Text spanners
 
 Some performance indications, e.g., @notation{rallentando} or
 @notation{accelerando}, are written as text and are extended over
 multiple notes with dotted lines.

-Such objects, called @q{spanners}, may be created
+Such objects, called @qq{spanners}, may be created

 from one note to another using the following syntax:
 
 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
 
 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}.
 
 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
 b1\startTextSpan c
 e,\stopTextSpan
 @end lilypond


@@ -149,27 +150,31 @@ 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}.
 
 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
 @funindex textSpannerUp
 @code{\textSpannerUp},
 @funindex textSpannerDown
 @code{\textSpannerDown},
 @funindex textSpannerNeutral

-@code{\textSpannerNeutral}
+@code{\textSpannerNeutral}.
+@endpredefined

 
 

-@seealso

 
 

-Notation Reference: @ref{Line styles}.
+@seealso
+Notation Reference:
+@ref{Line styles},
+@ref{Dynamics}.

 
 Snippets:
 @rlsr{Text}.
 
 
 Snippets:
 @rlsr{Text}.
 

-Internals Reference: @rinternals{TextSpanner}.
+Internals Reference:
+@rinternals{TextSpanner}.

 
 
 @node Text marks
 
 
 @node Text marks

-@subsubsection Text marks
+@unnumberedsubsubsec Text marks

 
 @cindex coda on bar line
 @cindex segno on bar line
 
 @cindex coda on bar line
 @cindex segno on bar line


@@ -183,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
 
 @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
 c4
 \mark "Allegro"
 c c c


@@ -191,24 +196,33 @@ c c c
 
 This syntax makes it possible to put any text on a bar line;
 more complex text formatting may be added using a @code{\markup}
 
 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}.  This can be used to print
-signs like coda, segno or fermata, by specifying the appropriate
-symbol name:
+block, as described in @ref{Formatting text}:

 
 

-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-c1
+@lilypond[quote,verbatim,relative=1]
+<c e>1
+\mark \markup { \italic { colla parte } }
+<d f>2 <e g>
+<c f aes>1
+@end lilypond
+
+@noindent
+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[quote,verbatim,relative=2]
+<bes f>2 <aes d>

 \mark \markup { \musicglyph #"scripts.ufermata" }
 \mark \markup { \musicglyph #"scripts.ufermata" }

-c1
+<e g>1

 @end lilypond
 
 @noindent
 Such objects are only typeset above the top staff of the score; depending on
 @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
 \mark "Allegro"
 c1 c
 \mark "assai" \break


@@ -227,15 +241,20 @@ c  c
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {printing-marks-on-every-staff.ly}
 
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {printing-marks-on-every-staff.ly}
 

-@seealso

 
 

-Notation Reference: @ref{Rehearsal marks},
-@ref{Formatting text}, @ref{The Feta font}.
+@seealso
+Notation Reference:
+@ref{Rehearsal marks},
+@ref{Formatting text},
+@ref{Music notation inside markup},
+@ref{The Feta font}.

 
 Snippets:
 @rlsr{Text}.
 
 
 Snippets:
 @rlsr{Text}.
 

-Internals Reference: @rinternals{RehearsalMark}.
+Internals Reference:
+@rinternals{RehearsalMark}.
+

 
 @knownissues
 @c  To be removed when Issue 69 in the tracker gets fixed. -vv
 
 @knownissues
 @c  To be removed when Issue 69 in the tracker gets fixed. -vv


@@ -245,7 +264,7 @@ there is no next line), then the mark will not be printed at
 all.
 
 @node Separate text
 all.
 
 @node Separate text

-@subsubsection Separate text
+@unnumberedsubsubsec Separate text

 
 @cindex separate text
 @cindex standalone text
 
 @cindex separate text
 @cindex standalone text


@@ -265,12 +284,12 @@ expression}.  This syntax is described in @ref{File structure}.
 
 @noindent
 This allows printing text separately
 
 @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}.
 
 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
 }
 \score {
   c'1
 }


@@ -282,28 +301,27 @@ several music pieces, as described in
 }
 @end lilypond
 
 }
 @end lilypond
 

-Using a specific syntax, text blocks can be spread
-over multiple pages, making 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
 @funindex \markuplines

-@code{\markuplines}
+@code{\markup},
+@code{\markuplines}.
+@endpredefined
+

 
 

-@ignore

 @snippets
 
 @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
 
 @seealso

-

 Notation Reference: @ref{Formatting text},
 Notation Reference: @ref{Formatting text},

-@ref{File structure}, 
+@ref{File structure},

 @ref{Multiple scores in a book},
 @ref{Multi-page markup}.
 
 @ref{Multiple scores in a book},
 @ref{Multi-page markup}.
 


@@ -320,16 +338,16 @@ This section presents basic and advanced text formatting,
 using the @code{\markup} mode specific syntax.
 
 @menu
 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
 @end menu
 
 @node Text markup introduction

-@subsubsection Text markup introduction
+@unnumberedsubsubsec Text markup introduction

 
 @cindex markup
 @cindex text markup
 
 @cindex markup
 @cindex text markup


@@ -338,7 +356,7 @@ using the @code{\markup} mode specific syntax.
 @funindex \markup
 
 A @code{\markup} block is used to typeset text with an extensible
 @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
 
 @cindex markup expressions
 @cindex markup syntax


@@ -348,17 +366,17 @@ The markup syntax is similar to LilyPond's usual syntax: a
 @dots{} @}}.  A single word is regarded as a minimal expression,
 and therefore does not need to be enclosed with braces.
 
 @dots{} @}}.  A single word is regarded as a minimal expression,
 and therefore does not need to be enclosed with braces.
 

-Unlike simple @q{quoted text} indications, @code{\markup} blocks
-may contain nested expressions or specific commands,
+Unlike simple @qq{quoted text} indications, @code{\markup} blocks
+may contain nested expressions or markup commands,

 entered using the backslash @code{\} character.
 Such commands only affect the first following expression.
 
 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" }
 a2^\markup { poco \italic più forte  }
 c e1
 d2_\markup { \italic "string. assai" }

-e 
+e

 b1^\markup { \bold { molto \italic  agitato } }
 c
 @end lilypond
 b1^\markup { \bold { molto \italic  agitato } }
 c
 @end lilypond


@@ -373,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
 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 way markup expressions are defined affects 
-how these expressions will be stacked, centered and aligned
-when using the commands explained in @ref{Text alignment}.
+the formatting of the text.  Double quotation marks themselves
+may be printed by preceding them with backslashes.

 
 

-@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
 
 @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 } }
 c1^\markup { \center-column { a { bbb c } } }
 c1^\markup { \center-column { a \line { bbb c } } }

+c1^\markup { \center-column { a "bbb c" } }

 @end lilypond
 
 @end lilypond
 

-

 Markups can be stored in variables.  Such variables may be
 directly attached to notes:
 
 Markups can be stored in variables.  Such variables may be
 directly attached to notes:
 


@@ -423,16 +433,12 @@ An exhaustive list of @code{\markup}-specific commands can be found in
 
 
 @seealso
 
 
 @seealso

-

 Notation Reference:
 @ref{Text markup commands}.
 
 Snippets:
 @rlsr{Text}.
 
 Notation Reference:
 @ref{Text markup commands}.
 
 Snippets:
 @rlsr{Text}.
 

-Internals Reference:
-@rinternals{TextScript}.
-

 Installed files:
 @file{scm/@/markup@/.scm}.
 
 Installed files:
 @file{scm/@/markup@/.scm}.
 


@@ -443,7 +449,7 @@ Syntax errors for markup mode can be confusing.
 
 
 @node Selecting font and font size
 
 
 @node Selecting font and font size

-@subsubsection Selecting font and font size
+@unnumberedsubsubsec Selecting font and font size

 
 @cindex font switching
 @funindex \italic
 
 @cindex font switching
 @funindex \italic


@@ -453,15 +459,13 @@ Syntax errors for markup mode can be confusing.
 Basic font switching is supported in markup mode:
 
 @lilypond[quote,verbatim,relative=2]
 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
 @end lilypond
 
 @cindex font size


@@ -469,16 +473,15 @@ Basic font switching is supported in markup mode:
 @funindex \fontsize
 @funindex \smaller
 @funindex \larger
 @funindex \fontsize
 @funindex \smaller
 @funindex \larger

-@funindex \bigger

 @funindex \magnify
 
 The size of the characters can also be altered in different ways:
 @itemize
 @item
 @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
 
 @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.
 
 @item
 the font size can also be changed relatively to its previous value.


@@ -487,21 +490,23 @@ the font size can also be changed relatively to its previous value.
 @noindent
 The following example demonstrates these three methods:
 
 @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
 @end lilypond
 
 @cindex subscript


@@ -516,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 }
 \markup {
   \column {
     \line { 1 \super st movement }

-    \line { 1 \normal-size-super st movement 
+    \line { 1 \normal-size-super st movement

       \sub { (part two) }  }
   }
 }
       \sub { (part two) }  }
   }
 }


@@ -526,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
 
 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.
 
 last line of the following example, there is no difference
 between the first and the second word.
 


@@ -569,26 +574,32 @@ easily be solved by concatenating the text elements together:
 }
 @end lilypond
 
 }
 @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}.
 
 
 Defining custom font sets is also possible, as explained in
 @ref{Fonts}.
 

-@predefined

 
 

+@predefined

 @funindex \teeny
 @funindex \teeny

-@funindex \tiny
-@funindex \small
-@funindex \normalsize
-@funindex \large
-@funindex \huge

 @code{\teeny},
 @code{\teeny},

+@funindex \tiny

 @code{\tiny},
 @code{\tiny},

+@funindex \small

 @code{\small},
 @code{\small},

+@funindex \normalsize

 @code{\normalsize},
 @code{\normalsize},

+@funindex \large

 @code{\large},
 @code{\large},

-@code{\huge}.
+@funindex \huge
+@code{\huge},
+@funindex \smaller
+@code{\smaller},
+@funindex \larger
+@code{\larger}.
+@endpredefined
+

 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:


@@ -608,15 +619,14 @@ Installed files:
 
 
 @node Text alignment
 
 
 @node Text alignment

-@subsubsection Text alignment
+@unnumberedsubsubsec Text alignment

 
 @cindex text, aligning
 @cindex aligning text
 
 
 @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
 
 @c Padding commands should be mentioned on this page, but
 @c most of these require \box to be more clearly illustrated. -vv


@@ -632,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.
 
 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
 @end lilypond
 
 @funindex \halign


@@ -647,7 +657,7 @@ a,-\markup { \right-align poco }
 Horizontal alignment may be fine-tuned
 using a numeric value:
 
 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 }
 a1-\markup { \halign #-1 poco }
 e'
 a,-\markup { \halign #0 poco }


@@ -661,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
 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
 
 @cindex text, vertical alignment
 @cindex vertical text alignment


@@ -677,17 +687,20 @@ 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.
 
 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
   Acte I

-  \raise #2 { Scène 1 } }
+  \raise #2 { Scène 1 }
+}

 a'
 g_\markup {
   \null
 a'
 g_\markup {
   \null

-  \lower #4 \bold { Très modéré } }
+  \lower #4 \bold { Très modéré }
+}

 a
 d,^\markup {
 a
 d,^\markup {

-  \raise #4 \italic { Une forêt. } }
+  \raise #4 \italic { Une forêt. }
+}

 a'4 a g2 a
 @end lilypond
 
 a'4 a g2 a
 @end lilypond
 


@@ -700,18 +713,21 @@ alignment of text objects in markup mode.  Any object
 affected by these commands must be preceded with an
 anchor point:
 
 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
 d2^\markup {
   Acte I

-  \translate #'(-1 . 2) "Scène 1" }
+  \translate #'(-1 . 2) "Scène 1"
+}

 a'
 g_\markup {
   \null
 a'
 g_\markup {
   \null

-  \general-align #Y #3.2 \bold "Très modéré" }
+  \general-align #Y #3.2 \bold "Très modéré"
+}

 a
 d,^\markup {
   \null
 a
 d,^\markup {
   \null

-  \translate-scaled #'(-1 . 2) \teeny "Une forêt." }
+  \translate-scaled #'(-1 . 2) \teeny "Une forêt."
+}

 a'4 a g2 a
 @end lilypond
 
 a'4 a g2 a
 @end lilypond
 


@@ -765,7 +781,7 @@ or any other markup expression:
   }
 }
 \markup {
   }
 }
 \markup {

-  \fill-line { 1885 } 
+  \fill-line { 1885 }

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -788,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
     \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
       una Fragua, iluminado por los rojos resplandores

-      del fuego.) 
+      del fuego.)

     }
     \hspace #0
 
     }
     \hspace #0
 


@@ -809,6 +825,7 @@ the following example.
 An exhaustive list of text alignment commands
 can be found in @ref{Align}.
 
 An exhaustive list of text alignment commands
 can be found in @ref{Align}.
 

+

 @seealso
 Learning Manual:
 @rlearning{Moving objects}.
 @seealso
 Learning Manual:
 @rlearning{Moving objects}.


@@ -827,13 +844,13 @@ Installed files:
 
 
 @node Graphic notation inside markup
 
 
 @node Graphic notation inside markup

-@subsubsection Graphic notation inside markup
+@unnumberedsubsubsec Graphic notation inside markup

 
 @cindex graphics, embedding
 @cindex drawing graphic objects
 
 Various graphic objects may be added to a score,
 
 @cindex graphics, embedding
 @cindex drawing graphic objects
 
 Various graphic objects may be added to a score,

-using specific markup commands.
+using markup commands.

 
 @funindex \box
 @funindex \circle
 
 @funindex \box
 @funindex \circle


@@ -844,7 +861,7 @@ using specific markup commands.
 @cindex decorating text
 @cindex framing text
 
 @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]
 with graphics, as demonstrated in the following example.
 
 @lilypond[quote,verbatim]


@@ -872,8 +889,8 @@ with graphics, as demonstrated in the following example.
 @cindex padding around text
 @cindex text padding
 
 @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]
 exhaustively described in @ref{Align}.
 
 @lilypond[quote,verbatim]


@@ -910,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
 
 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 {
 
 @lilypond[quote,verbatim]
 \markup {


@@ -940,12 +957,15 @@ Advanced graphic features include the ability to
 include external image files converted to the
 Encapsulated PostScript format (@emph{eps}), or
 to directly embed graphics into the input file,
 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.
+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"
 c1^\markup {
   \combine
     \epsfile #X #10 #"./context-example.eps"

+    \with-dimensions #'(0 . 6) #'(0 . 10)

     \postscript #"
       -2 3 translate
       2.7 2 scale
     \postscript #"
       -2 3 translate
       2.7 2 scale


@@ -964,6 +984,7 @@ c
 An exhaustive list of graphics-specific commands
 can be found in @ref{Graphic}.
 
 An exhaustive list of graphics-specific commands
 can be found in @ref{Graphic}.
 

+

 @seealso
 Notation Reference:
 @ref{Graphic},
 @seealso
 Notation Reference:
 @ref{Graphic},


@@ -978,16 +999,17 @@ Installed files:
 @file{scm/@/define@/-markup@/-commands@/.scm},
 @file{scm/@/stencil@/.scm}.
 
 @file{scm/@/define@/-markup@/-commands@/.scm},
 @file{scm/@/stencil@/.scm}.
 

+

 @node Music notation inside markup
 @node Music notation inside markup

-@subsubsection Music notation inside markup
+@unnumberedsubsubsec Music notation inside markup

 
 Various musical notation elements may be added
 to a score, inside a markup object.
 
 
 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:
 
 commands:
 

-@lilypond[quote,verbatim,fragment,relative=2]
+@lilypond[quote,verbatim,relative=2]

 a2 a^\markup {
   \note #"4" #1
   =
 a2 a^\markup {
   \note #"4" #1
   =


@@ -1008,7 +1030,7 @@ a1_\markup {
 Other notation objects may also be printed
 in markup mode:
 
 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
 g1 bes
 ees-\markup {
   \finger 4


@@ -1024,14 +1046,14 @@ d-\markup {
   \markalphabet #8
   \markletter #8
 }
   \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}.
 
 
 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
 c2
 c'^\markup { \musicglyph #"eight" }
 c,4


@@ -1039,16 +1061,16 @@ c,8._\markup { \musicglyph #"clefs.G_change" }
 c16
 c2^\markup { \musicglyph #"timesig.neomensural94" }
 @end lilypond
 c16
 c2^\markup { \musicglyph #"timesig.neomensural94" }
 @end lilypond

-@c TODO: add \lookup here? -vv

 
 @noindent
 
 @noindent

-Another way of including 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:
 
 
 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;"
 }
 c1^\markup {
   \fret-diagram-terse #"x;x;o;2;3;2;"
 }


@@ -1068,17 +1090,16 @@ c^\markup {
 @c The accordion diagram is actually taken from a snippet.
 
 @noindent
 @c The accordion diagram is actually taken from a snippet.
 
 @noindent

-@c VV: don't know what you intend here  -td
-@c Such diagrams are documented in @ref{Instrument Specific Markup}.
+Such diagrams are documented in @ref{Instrument Specific Markup}.

 
 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:
 
 
 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 {
 c4 d^\markup {
   \score {

-    \relative { c4 d e f }
+    \relative c' { c4 d e f }

     \layout { }
   }
 }
     \layout { }
   }
 }


@@ -1087,11 +1108,12 @@ c d e f
 @end lilypond
 
 An exhaustive list of music notation related commands can be
 @end lilypond
 
 An exhaustive list of music notation related commands can be

-found in @ref{Music notation inside markup}.
+found in @ref{Music}.
+

 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

-@ref{Music notation inside markup},
+@ref{Music},

 @ref{The Feta font},
 @ref{Fonts explained}.
 
 @ref{The Feta font},
 @ref{Fonts explained}.
 


@@ -1105,11 +1127,12 @@ Installed files:
 @file{scm/@/fret@/-diagrams@/.scm},
 @file{scm/@/harp@/-pedals@/.scm}.
 
 @file{scm/@/fret@/-diagrams@/.scm},
 @file{scm/@/harp@/-pedals@/.scm}.
 

+

 @node Multi-page markup
 @node Multi-page markup

-@subsubsection Multi-page markup
+@unnumberedsubsubsec Multi-page markup

 
 Although standard markup objects are not breakable, a
 
 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]
 spread over multiple pages:
 
 @lilypond[quote,verbatim]


@@ -1119,14 +1142,14 @@ spread over multiple pages:
     ...
   }
   \wordwrap-lines {
     ...
   }
   \wordwrap-lines {

-    An other very long paragraph.
+    Another very long paragraph.

     ...
   }
   ...
 }
 @end lilypond
 
     ...
   }
   ...
 }
 @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,
 @itemize
 @item
 the result of a markup list command,


@@ -1139,6 +1162,7 @@ a list of markup lists.
 An exhaustive list of markup list commands can be found in
 @ref{Text markup list commands}.
 
 An exhaustive list of markup list commands can be found in
 @ref{Text markup list commands}.
 

+

 @seealso
 Notation Reference:
 @ref{Text markup list commands},
 @seealso
 Notation Reference:
 @ref{Text markup list commands},


@@ -1152,9 +1176,11 @@ Internals Reference: @rinternals{TextScript}.
 Installed files:
 @file{scm/@/define@/-markup@/-commands@/.scm}.
 
 Installed files:
 @file{scm/@/define@/-markup@/-commands@/.scm}.
 

+

 @predefined
 @funindex \markuplines
 @predefined
 @funindex \markuplines

-@code{\markuplines}
+@code{\markuplines}.
+@endpredefined

 
 
 @node Fonts
 
 
 @node Fonts


@@ -1170,10 +1196,11 @@ and how they may be changed in scores.
 @end menu
 
 @node Fonts explained
 @end menu
 
 @node Fonts explained

-@subsubsection Fonts explained
+@unnumberedsubsubsec Fonts explained

 
 @cindex Pango
 @cindex fonts, explained
 
 @cindex Pango
 @cindex fonts, explained

+@cindex braces, various sizes

 @funindex font-interface
 
 Fonts are handled through several libraries.
 @funindex font-interface
 
 Fonts are handled through several libraries.


@@ -1182,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.
 
 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)
 a1^\markup {
   \vcenter {
     \override #'(font-encoding . fetaBraces)


@@ -1201,8 +1228,17 @@ a1^\markup {
 @end lilypond
 
 @noindent
 @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
 
 Three families of text fonts are made available: the
 @emph{roman} (serif) font, that defaults to New Century


@@ -1212,16 +1248,18 @@ determined by the Pango installation.
 
 Each family may include different shapes and series.
 The following example demonstrates the ability to select
 
 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
 @end lilypond
 
 @noindent


@@ -1251,19 +1289,12 @@ it is preferable to use the simpler syntax explained in
 }
 @end lilypond
 
 }
 @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}.
 
 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},
 @seealso
 Notation Reference:
 @ref{The Feta font},


@@ -1271,18 +1302,19 @@ Notation Reference:
 @ref{Selecting font and font size},
 @ref{Font}.
 
 @ref{Selecting font and font size},
 @ref{Font}.
 

+

 @node Single entry fonts
 @node Single entry fonts

-@subsubsection 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:
 
 
 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
 
 \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 }
 }
   \override #'(font-name . "Vera Bold")
     { Vera Bold }
 }


@@ -1301,6 +1333,7 @@ lilypond -dshow-available-fonts x
 The last argument of the command can be anything, but has to be
 present.
 
 The last argument of the command can be anything, but has to be
 present.
 

+

 @seealso
 Notation Reference:
 @ref{Fonts explained},
 @seealso
 Notation Reference:
 @ref{Fonts explained},


@@ -1312,15 +1345,14 @@ Snippets:
 Installed files:
 @file{lily/@/font@/-config@/-scheme@/.cc}.
 
 Installed files:
 @file{lily/@/font@/-config@/-scheme@/.cc}.
 

-@node Entire document fonts
-@subsubsection Entire document fonts

 
 

+@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
 
 @cindex font families, setting
 @funindex make-pango-font-tree


@@ -1346,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
 
 @c we don't do Helvetica / Courier, since GS incorrectly loads
 @c Apple TTF fonts
 

+

 @seealso
 Notation Reference:
 @ref{Fonts explained},
 @seealso
 Notation Reference:
 @ref{Fonts explained},