Issue 4591 / 3: Fix font-name overriding wrong name

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

diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely
index d9f82d886fbd9f8a8f8ec7f17e8ed311387d350a..ae40256caa28a5536cb8a16ef78a17f5ae153486 100644 (file)
--- a/Documentation/notation/text.itely
+++ b/Documentation/notation/text.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.13.36"
+@c \version "2.19.21"

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


@@ -59,28 +59,30 @@ demonstrated in the following example.  Such indications may be
 manually placed above or below the staff, using the syntax described
 in @ref{Direction and placement}.
 
 manually placed above or below the staff, using the syntax described
 in @ref{Direction and placement}.
 

-@lilypond[quote,verbatim,relative=2]
-a8^"pizz." g f e a4-"scherz." f
+@lilypond[quote,verbatim]
+\relative { a'8^"pizz." g f e a4-"scherz." f }

 @end lilypond
 
 @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}.
+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,verbatim,relative=2]
-a8^\markup { \italic pizz. } g f e
-a4_\markup { \tiny scherz. \bold molto } f
+@lilypond[quote,verbatim]
+\relative {
+  a'8^\markup { \italic pizz. } g f e
+  a4_\markup { \tiny scherz. \bold molto } f }

 @end lilypond
 
 @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
-spacing, whereas the second one does.
+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 spacing, whereas the second one does.

 
 

-@lilypond[quote,verbatim,relative=2]
-a8^"pizz." g f e
-\textLengthOn
-a4_"scherzando" f
+@lilypond[quote,verbatim]
+\relative {
+  a'8^"pizz." g f e
+  \textLengthOn
+  a4_"scherzando" f
+}

 @end lilypond
 
 In addition to text scripts, articulations can be attached to notes.
 @end lilypond
 
 In addition to text scripts, articulations can be attached to notes.


@@ -99,14 +101,14 @@ articulations, see @rlearning{Placement of objects}.
 @code{\textLengthOff}.
 @endpredefined
 
 @code{\textLengthOff}.
 @endpredefined
 

-

 @seealso
 Learning Manual:
 @rlearning{Placement of objects}.
 
 Notation Reference:
 @ref{Formatting text},
 @seealso
 Learning Manual:
 @rlearning{Placement of objects}.
 
 Notation Reference:
 @ref{Formatting text},

-@ref{Direction and placement}.
+@ref{Direction and placement},
+@ref{Articulations and ornamentations}.

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


@@ -114,22 +116,18 @@ Snippets:
 Internals Reference:
 @rinternals{TextScript}.
 
 Internals Reference:
 @rinternals{TextScript}.
 

-

 @cindex text outside margin
 @cindex margin, text running over
 @cindex text, keeping inside margin
 @cindex lyrics, keeping inside margin
 
 @cindex text outside margin
 @cindex margin, text running over
 @cindex text, keeping inside margin
 @cindex lyrics, keeping inside margin
 

-

 @knownissues
 @knownissues

-

 Checking to make sure that text scripts and lyrics are within the
 Checking to make sure that text scripts and lyrics are within the

-margins is a relatively large computational task.  To speed up
-processing, LilyPond does not perform such calculations by
-default; to enable it, use
+margins requires additonal calculations. In cases where slightly faster
+performance is desired, use

 
 @example
 
 @example

-\override Score.PaperColumn #'keep-inside-line = ##t
+\override Score.PaperColumn.keep-inside-line = ##f

 @end example
 
 
 @end example
 
 


@@ -140,13 +138,16 @@ default; to enable it, use
 
 Some performance indications, e.g., @notation{rallentando} or
 @notation{accelerando}, are written as text and are extended over
 
 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 @qq{spanners},
-may be created from one note to another using the following syntax:
+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,relative=2]
-\override TextSpanner #'(bound-details left text) = "rit."
-b1\startTextSpan
-e,\stopTextSpan
+@lilypond[verbatim,quote]
+\relative {
+  \override TextSpanner.bound-details.left.text = "rit."
+  b'1\startTextSpan
+  e,\stopTextSpan
+}

 @end lilypond
 
 @cindex text spanners, formatting
 @end lilypond
 
 @cindex text spanners, formatting


@@ -158,11 +159,13 @@ it is printed in italic characters, but different formatting can be
 obtained using @code{\markup} blocks, as described in
 @ref{Formatting text}.
 
 obtained using @code{\markup} blocks, as described in
 @ref{Formatting text}.
 

-@lilypond[quote,relative=2,verbatim]
-\override TextSpanner #'(bound-details left text) =
-  \markup { \upright "rit." }
-b1\startTextSpan c
-e,\stopTextSpan
+@lilypond[quote,verbatim]
+\relative {
+  \override TextSpanner.bound-details.left.text =
+    \markup { \upright "rit." }
+  b'1\startTextSpan c
+  e,\stopTextSpan
+}

 @end lilypond
 
 The line style, as well as the text string, can be defined as an
 @end lilypond
 
 The line style, as well as the text string, can be defined as an


@@ -187,16 +190,17 @@ LilyPond is only able to handle one text spanner per voice.
 
 @snippets
 
 
 @snippets
 

-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]

 {dynamics-text-spanner-postfix.ly}
 
 {dynamics-text-spanner-postfix.ly}
 

-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]

 {dynamics-custom-text-spanner-postfix.ly}
 
 @seealso
 Notation Reference:
 @ref{Line styles},
 {dynamics-custom-text-spanner-postfix.ly}
 
 @seealso
 Notation Reference:
 @ref{Line styles},

-@ref{Dynamics}.
+@ref{Dynamics},
+@ref{Formatting text}.

 
 Snippets:
 @rlsr{Text},
 
 Snippets:
 @rlsr{Text},


@@ -223,27 +227,31 @@ Internals Reference:
 @funindex \markup
 @funindex markup
 
 @funindex \markup
 @funindex markup
 

-Various text elements may be added to a score using
-the syntax described in @ref{Rehearsal marks}:
+Various text elements may be added to a score using 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,relative=2]
-c4
-\mark "Allegro"
-c c c
+@lilypond[verbatim,quote]
+\relative {
+  c''4
+  \mark "Allegro"
+  c c c
+}

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

 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent


@@ -251,38 +259,48 @@ 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}:
 
 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" }
-<e g>1
+@lilypond[quote,verbatim]
+\relative {
+  <bes' f>2 <aes d>
+  \mark \markup { \musicglyph #"scripts.ufermata" }
+  <e g>1
+}

 @end lilypond
 
 @noindent
 @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 a
-line break, the mark will be printed at the beginning of the next line.
-
-@lilypond[quote,verbatim,relative=2]
-\mark "Allegro"
-c1 c
-\mark "assai" \break
-c  c
+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 a line break, the mark will be printed at the beginning of
+the next line.
+
+@lilypond[quote,verbatim,ragged-right]
+\relative c'' {
+  \mark "Allegro"
+  c1 c
+  \mark "assai" \break
+  c  c
+}

 @end lilypond
 
 @end lilypond
 

+@funindex \markLengthOn
+@funindex markLengthOn
+@funindex \markLengthOff
+@funindex markLengthOff
+
+@predefined
+@code{\markLengthOn},
+@code{\markLengthOff}.
+@endpredefined

 
 @snippets
 
 
 @snippets
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {printing-marks-at-the-end-of-a-line.ly}
 
 {printing-marks-at-the-end-of-a-line.ly}
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{aligning-marks-with-various-notation-objects.ly}
-
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {printing-marks-on-every-staff.ly}
 
 {printing-marks-on-every-staff.ly}
 

-

 @seealso
 Notation Reference:
 @ref{Rehearsal marks},
 @seealso
 Notation Reference:
 @ref{Rehearsal marks},


@@ -347,21 +365,20 @@ requires, are described in @ref{Multi-page markup}.
 
 @funindex \markup
 @funindex markup
 
 @funindex \markup
 @funindex markup

-@funindex \markuplines
-@funindex markuplines
+@funindex \markuplist
+@funindex markuplist

 
 @predefined
 @code{\markup},
 
 @predefined
 @code{\markup},

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

 @endpredefined
 
 
 @snippets
 
 @endpredefined
 
 
 @snippets
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {stand-alone-two-column-markup.ly}
 
 {stand-alone-two-column-markup.ly}
 

-

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


@@ -411,8 +428,8 @@ syntax called @qq{markup mode}.
 @cindex syntax, markup
 
 The markup syntax is similar to LilyPond's usual syntax: a
 @cindex syntax, markup
 
 The markup syntax is similar to LilyPond's usual syntax: a

-@code{\markup} expression is enclosed in curly braces @code{@{
-@dots{} @}}.  A single word is regarded as a minimal expression,
+@code{\markup} expression is enclosed in curly braces
+@code{@{@dots{} @}}.  A single word is regarded as a minimal expression,

 and therefore does not need to be enclosed with braces.
 
 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
 and therefore does not need to be enclosed with braces.
 
 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may


@@ -420,14 +437,16 @@ contain nested expressions or markup commands, entered using the
 backslash @code{\} character.  Such commands only affect the first
 following expression.
 
 backslash @code{\} character.  Such commands only affect the first
 following expression.
 

-@lilypond[quote,verbatim,relative=2]
-a1-\markup intenso
-a2^\markup { poco \italic più forte  }
-c e1
-d2_\markup { \italic "string. assai" }
-e
-b1^\markup { \bold { molto \italic  agitato } }
-c
+@lilypond[quote,verbatim]
+\relative {
+  a'1-\markup intenso
+  a2^\markup { poco \italic più forte  }
+  c e1
+  d2_\markup { \italic "string. assai" }
+  e
+  b1^\markup { \bold { molto \italic  agitato } }
+  c
+}

 @end lilypond
 
 @cindex special characters in markup mode
 @end lilypond
 
 @cindex special characters in markup mode


@@ -440,15 +459,17 @@ c
 
 A @code{\markup} block may also contain quoted text strings.  Such
 strings are treated as minimal text expressions, and therefore any
 
 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{#})
+markup command or special character (such as @code{\} and@tie{}@code{#})

 will be printed verbatim without affecting the formatting of the text.
 Double quotation marks themselves may be printed by preceding them
 with backslashes.
 
 will be printed verbatim without affecting the formatting of the text.
 Double quotation marks themselves may be printed by preceding them
 with backslashes.
 

-@lilypond[quote,verbatim,relative=2]
-a1^"\italic markup..."
-a_\markup { \italic "... prints \"italic\" letters!" }
-a a
+@lilypond[quote,verbatim]
+\relative {
+  a'1^"\italic markup..."
+  a_\markup { \italic "... prints \"italic\" letters!" }
+  a a
+}

 @end lilypond
 
 To be treated as a distinct expression, a list of words needs to be
 @end lilypond
 
 To be treated as a distinct expression, a list of words needs to be


@@ -457,11 +478,13 @@ 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:
 
 centered and aligned; in the following example, the second
 @code{\markup} expression is treated the same as the first one:
 

-@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" } }
+@lilypond[quote,verbatim]
+\relative 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
 
 Markups can be stored in variables.  Such variables may be
 @end lilypond
 
 Markups can be stored in variables.  Such variables may be


@@ -481,7 +504,6 @@ allegro = \markup { \bold \large Allegro }
 An exhaustive list of @code{\markup}-specific commands can be found in
 @ref{Text markup commands}.
 
 An exhaustive list of @code{\markup}-specific commands can be found in
 @ref{Text markup commands}.
 

-

 @seealso
 Notation Reference:
 @ref{Text markup commands}.
 @seealso
 Notation Reference:
 @ref{Text markup commands}.


@@ -492,9 +514,7 @@ Snippets:
 Installed Files:
 @file{scm/markup.scm}.
 
 Installed Files:
 @file{scm/markup.scm}.
 

-

 @knownissues
 @knownissues

-

 Syntax errors for markup mode can be confusing.
 
 
 Syntax errors for markup mode can be confusing.
 
 


@@ -514,19 +534,22 @@ Syntax errors for markup mode can be confusing.
 
 Basic font switching is supported in markup mode:
 
 
 Basic font switching is supported in markup mode:
 

-@lilypond[quote,verbatim,relative=2]
-d1^\markup {
-  \bold { Più mosso }
-  \italic { non troppo \underline Vivo }
+@lilypond[quote,verbatim]
+\relative {
+  d''1^\markup {
+    \bold { Più mosso }
+    \italic { non troppo \underline Vivo }
+  }
+  r2 r4 r8
+  d,_\markup { \italic quasi \smallCaps Tromba }
+  f1 d2 r

 }
 }

-r2 r4 r8
-d,_\markup { \italic quasi \smallCaps Tromba }
-f1 d2 r

 @end lilypond
 
 @cindex font size
 @cindex text size
 
 @end lilypond
 
 @cindex font size
 @cindex text size
 

+@funindex \abs-fontsize

 @funindex \fontsize
 @funindex fontsize
 @funindex \smaller
 @funindex \fontsize
 @funindex fontsize
 @funindex \smaller


@@ -536,38 +559,58 @@ f1 d2 r
 @funindex \magnify
 @funindex magnify
 
 @funindex \magnify
 @funindex magnify
 

-The size of the characters can also be altered in different ways:
-@itemize
-@item
-the font size can be set to predefined standard sizes,
+The font size can be altered, relative to the global staff size, in a
+number of different ways

 
 

-@item
-the font size can be set to an absolute value,
+It can be set to predefined size,

 
 

-@item
-the font size can also be changed relatively to its previous value.
-@end itemize
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \huge Sinfonia }
+  b1^\markup { \teeny da }
+  b1-\markup { \normalsize camera }
+}
+@end lilypond

 
 

-@noindent
-The following example demonstrates these three methods:
+It can be set relative to its previous value,

 
 

-@lilypond[quote,verbatim,relative=1]
-f1_\markup {
-  \tiny espressivo
-  \large e
-  \normalsize intenso
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \larger Sinfonia }
+  b1^\markup { \smaller da }
+  b1-\markup { \magnify #0.6  camera }

 }
 }

-a^\markup {
-  \fontsize #5 Sinfonia
-  \fontsize #2 da
-  \fontsize #3 camera
+@end lilypond
+
+It can be increased or decreased relative to the value set by the
+global staff size,
+
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \fontsize #-2 Sinfonia }
+  b1^\markup { \fontsize #1 da }
+  b1-\markup { \fontsize #3 camera }

 }
 }

-bes^\markup { (con
-  \larger grande
-  \smaller emozione
-  \magnify #0.6 { e sentimento } )
+@end lilypond
+
+It can also be set to a fixed point-size, regardless of the global staff
+size,
+
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \abs-fontsize #20 Sinfonia }
+  b1^\markup { \abs-fontsize #8 da }
+  b1-\markup { \abs-fontsize #14 camera }

 }
 }

-d c2 r8 c bes a g1
+@end lilypond
+
+If the text includes spaces, then it is best to put it all inside quote
+marks, so that the size of each space is appropriate for the size of the
+other characters.
+
+@lilypond[quote,verbatim]
+\markup \fontsize #6 \bold { Sinfonia da camera }
+\markup \fontsize #6 \bold { "Sinfonia da camera" }

 @end lilypond
 
 @cindex subscript
 @end lilypond
 
 @cindex subscript


@@ -577,6 +620,8 @@ d c2 r8 c bes a g1
 @funindex super
 @funindex \sub
 @funindex sub
 @funindex super
 @funindex \sub
 @funindex sub

+@funindex \normal-size-super
+@funindex normal-size-super

 
 Text may be printed as subscript or superscript.  By default these are
 printed in a smaller size, but a normal size can be used as well:
 
 Text may be printed as subscript or superscript.  By default these are
 printed in a smaller size, but a normal size can be used as well:


@@ -671,7 +716,6 @@ Defining custom font sets is also possible, as explained in
 @code{\larger}.
 @endpredefined
 
 @code{\larger}.
 @endpredefined
 

-

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


@@ -679,15 +723,15 @@ Notation Reference:
 @ref{Manual repeat marks},
 @ref{Fonts}.
 
 @ref{Manual repeat marks},
 @ref{Fonts}.
 

+Installed Files:
+@file{scm/define-markup-commands.scm}.
+

 Snippets:
 @rlsr{Text}.
 
 Internals Reference:
 @rinternals{TextScript}.
 
 Snippets:
 @rlsr{Text}.
 
 Internals Reference:
 @rinternals{TextScript}.
 

-Installed Files:
-@file{scm/define-markup-commands.scm}.
-

 @knownissues
 Using the font sizing commands @code{\teeny}, @code{\tiny},
 @code{\small}, @code{\normalsize}, @code{\large}, and
 @knownissues
 Using the font sizing commands @code{\teeny}, @code{\tiny},
 @code{\small}, @code{\normalsize}, @code{\large}, and


@@ -726,14 +770,16 @@ Markup objects may be aligned in different ways.  By default, a text
 indication is aligned on its left edge: in the following example,
 there is no difference between the first and the second markup.
 
 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,relative=2]
-d1-\markup { poco }
-f
-d-\markup { \left-align poco }
-f
-d-\markup { \center-align { poco } }
-f
-d-\markup { \right-align poco }
+@lilypond[quote,verbatim]
+\relative {
+  d''1-\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


@@ -741,20 +787,23 @@ d-\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,relative=2]
-a1-\markup { \halign #-1 poco }
-e'
-a,-\markup { \halign #0 poco }
-e'
-a,-\markup { \halign #0.5 poco }
-e'
-a,-\markup { \halign #2 poco }
+@lilypond[quote,verbatim]
+\relative {
+  a'1-\markup { \halign #-1 poco }
+  e'
+  a,-\markup { \halign #0 poco }
+  e'
+  a,-\markup { \halign #0.5 poco }
+  e'
+  a,-\markup { \halign #2 poco }
+}

 @end lilypond
 
 @noindent
 Some objects may have alignment procedures of their own, and therefore
 are not affected by these commands.  It is possible to move such
 @end lilypond
 
 @noindent
 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}.
+markup objects as a whole, as shown for instance in
+@ref{Text marks}.

 
 @cindex text, vertical alignment
 @cindex vertical text alignment
 
 @cindex text, vertical alignment
 @cindex vertical text alignment


@@ -776,21 +825,23 @@ another markup element 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.
 
 demonstrates these two possibilities; the last markup in this example
 has no anchor point, and therefore is not moved.
 

-@lilypond[quote,verbatim,relative=1]
-d2^\markup {
-  Acte I
-  \raise #2 { Scène 1 }
-}
-a'
-g_\markup {
-  \null
-  \lower #4 \bold { Très modéré }
-}
-a
-d,^\markup {
-  \raise #4 \italic { Une forêt. }
+@lilypond[quote,verbatim]
+\relative {
+  d'2^\markup {
+    Acte I
+    \raise #2 { Scène 1 }
+  }
+  a'
+  g_\markup {
+    \null
+    \lower #4 \bold { Très modéré }
+  }
+  a
+  d,^\markup {
+    \raise #4 \italic { Une forêt. }
+  }
+  a'4 a g2 a

 }
 }

-a'4 a g2 a

 @end lilypond
 
 @funindex \general-align
 @end lilypond
 
 @funindex \general-align


@@ -804,22 +855,24 @@ Some commands can affect both the horizontal and vertical alignment of
 text objects in markup mode.  Any object affected by these commands
 must be preceded with an anchor point:
 
 text objects in markup mode.  Any object affected by these commands
 must be preceded with an anchor point:
 

-@lilypond[quote,verbatim,relative=1]
-d2^\markup {
-  Acte I
-  \translate #'(-1 . 2) "Scène 1"
-}
-a'
-g_\markup {
-  \null
-  \general-align #Y #3.2 \bold "Très modéré"
-}
-a
-d,^\markup {
-  \null
-  \translate-scaled #'(-1 . 2) \teeny "Une forêt."
+@lilypond[quote,verbatim]
+\relative {
+  d'2^\markup {
+    Acte I
+    \translate #'(-1 . 2) "Scène 1"
+  }
+  a'
+  g_\markup {
+    \null
+    \general-align #Y #3.2 \bold "Très modéré"
+  }
+  a
+  d,^\markup {
+    \null
+    \translate-scaled #'(-1 . 2) \teeny "Une forêt."
+  }
+  a'4 a g2 a

 }
 }

-a'4 a g2 a

 @end lilypond
 
 @cindex multi-line markup
 @end lilypond
 
 @cindex multi-line markup


@@ -932,7 +985,6 @@ as shown in 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}.


@@ -941,15 +993,15 @@ Notation Reference:
 @ref{Align},
 @ref{Text marks}.
 
 @ref{Align},
 @ref{Text marks}.
 

+Installed Files:
+@file{scm/define-markup-commands.scm}.
+

 Snippets:
 @rlsr{Text}.
 
 Internals Reference:
 @rinternals{TextScript}.
 
 Snippets:
 @rlsr{Text}.
 
 Internals Reference:
 @rinternals{TextScript}.
 

-Installed Files:
-@file{scm/define-markup-commands.scm}.
-

 
 @node Graphic notation inside markup
 @unnumberedsubsubsec Graphic notation inside markup
 
 @node Graphic notation inside markup
 @unnumberedsubsubsec Graphic notation inside markup


@@ -1093,8 +1145,8 @@ image files converted to the Encapsulated PostScript format
 native PostScript code.  In such a case, it may be useful to
 explicitly specify the size of the drawing, as demonstrated below:
 
 native PostScript code.  In such a case, it may be useful to
 explicitly specify the size of the drawing, as demonstrated below:
 

-@lilypond[quote,verbatim,relative=1]
-c1^\markup {
+@lilypond[quote,verbatim,fragment]
+c'1^\markup {

   \combine
     \epsfile #X #10 #"./context-example.eps"
     \with-dimensions #'(0 . 6) #'(0 . 10)
   \combine
     \epsfile #X #10 #"./context-example.eps"
     \with-dimensions #'(0 . 6) #'(0 . 10)


@@ -1110,17 +1162,22 @@ c1^\markup {
       closepath
       stroke"
   }
       closepath
       stroke"
   }

-c
+c'

 @end lilypond
 
 An exhaustive list of graphics-specific commands can be found in
 @ref{Graphic}.
 
 @end lilypond
 
 An exhaustive list of graphics-specific commands can be found in
 @ref{Graphic}.
 

-

 @seealso
 Notation Reference:
 @seealso
 Notation Reference:

-@ref{Graphic},
-@ref{Editorial annotations}.
+@ref{Align},
+@ref{Dimensions},
+@ref{Editorial annotations},
+@ref{Graphic}.
+
+Installed Files:
+@file{scm/define-markup-commands.scm},
+@file{scm/stencil.scm}.

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


@@ -1128,10 +1185,6 @@ Snippets:
 Internals Reference:
 @rinternals{TextScript}.
 
 Internals Reference:
 @rinternals{TextScript}.
 

-Installed Files:
-@file{scm/define-markup-commands.scm},
-@file{scm/stencil.scm}.
-

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


@@ -1145,42 +1198,40 @@ markup object.
 
 Notes and accidentals can be entered using markup commands:
 
 
 Notes and accidentals can be entered using markup commands:
 

-@lilypond[quote,verbatim,relative=2]
-a2 a^\markup {
+@lilypond[quote,verbatim,fragment]
+a'2 a'^\markup {

   \note #"4" #1
   =
   \note-by-number #1 #1 #1.5
 }
   \note #"4" #1
   =
   \note-by-number #1 #1 #1.5
 }

-b1_\markup {
+b'1_\markup {

   \natural \semiflat \flat
   \sesquiflat \doubleflat
 }
 \glissando
   \natural \semiflat \flat
   \sesquiflat \doubleflat
 }
 \glissando

-a1_\markup {
+a'1_\markup {

   \natural \semisharp \sharp
   \sesquisharp \doublesharp
 }
   \natural \semisharp \sharp
   \sesquisharp \doublesharp
 }

-\glissando b
+\glissando b'

 @end lilypond
 
 Other notation objects may also be printed
 in markup mode:
 
 @end lilypond
 
 Other notation objects may also be printed
 in markup mode:
 

-@lilypond[quote,verbatim,relative=1]
-g1 bes
-ees-\markup {
-  \finger 4
-  \tied-lyric #"~"
-  \finger 1
-}
-fis_\markup { \dynamic rf }
-bes^\markup {
-  \beam #8 #0.1 #0.5
-}
-cis
-d-\markup {
-  \markalphabet #8
-  \markletter #8
+@lilypond[quote,verbatim]
+\relative {
+  g1 bes
+  ees\finger \markup \tied-lyric #"4~1"
+  fis_\markup { \dynamic rf }
+  bes^\markup {
+    \beam #8 #0.1 #0.5
+  }
+  cis
+  d-\markup {
+    \markalphabet #8
+    \markletter #8
+  }

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -1189,13 +1240,15 @@ 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}.
 
 list of these symbols and their names can be found in
 @ref{The Feta font}.
 

-@lilypond[quote,verbatim,relative=2]
-c2
-c'^\markup { \musicglyph #"eight" }
-c,4
-c,8._\markup { \musicglyph #"clefs.G_change" }
-c16
-c2^\markup { \musicglyph #"timesig.neomensural94" }
+@lilypond[quote,verbatim]
+\relative {
+  c''2
+  c'^\markup { \musicglyph #"eight" }
+  c,4
+  c,8._\markup { \musicglyph #"clefs.G_change" }
+  c16
+  c2^\markup { \musicglyph #"timesig.neomensural94" }
+}

 @end lilypond
 
 Another way of printing non-text glyphs is described in
 @end lilypond
 
 Another way of printing non-text glyphs is described in


@@ -1205,20 +1258,22 @@ sizes.
 The markup mode also supports diagrams for specific
 instruments:
 
 The markup mode also supports diagrams for specific
 instruments:
 

-@lilypond[quote,verbatim,relative=2]
-c1^\markup {
-  \fret-diagram-terse #"x;x;o;2;3;2;"
-}
-c^\markup {
-  \harp-pedal #"^-v|--ov^"
-}
-c
-c^\markup {
-  \combine
-    \musicglyph #"accordion.discant"
+@lilypond[quote,verbatim]
+\relative {
+  c''1^\markup {
+    \fret-diagram-terse #"x;x;o;2;3;2;"
+  }
+  c^\markup {
+    \harp-pedal #"^-v|--ov^"
+  }
+  c
+  c^\markup {

     \combine
     \combine

-      \raise #0.5 \musicglyph #"accordion.dot"
-      \raise #1.5 \musicglyph #"accordion.dot"
+      \musicglyph #"accordion.discant"
+      \combine
+       \raise #0.5 \musicglyph #"accordion.dot"
+       \raise #1.5 \musicglyph #"accordion.dot"
+  }

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -1234,38 +1289,39 @@ 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:
 
 case, the nested @code{\score} block must contain a @code{\layout}
 block, as demonstrated here:
 

-@lilypond[quote,verbatim,relative=1]
-c4 d^\markup {
-  \score {
-    \relative c' { c4 d e f }
-    \layout { }
+@lilypond[quote,verbatim]
+\relative {
+  c'4 d^\markup {
+    \score {
+      \relative { c'4 d e f }
+      \layout { }
+    }

   }
   }

+  e f |
+  c d e f

 }
 }

-e f |
-c d e f

 @end lilypond
 
 An exhaustive list of music notation related commands can be found in
 @ref{Music}.
 
 @end lilypond
 
 An exhaustive list of music notation related commands can be found in
 @ref{Music}.
 

-

 @seealso
 Notation Reference:
 @ref{Music},
 @ref{The Feta font},
 @ref{Fonts explained}.
 
 @seealso
 Notation Reference:
 @ref{Music},
 @ref{The Feta font},
 @ref{Fonts explained}.
 

+Installed Files:
+@file{scm/define-markup-commands.scm},
+@file{scm/fret-diagrams.scm},
+@file{scm/harp-pedals.scm}.
+

 Snippets:
 @rlsr{Text}.
 
 Internals Reference:
 @rinternals{TextScript}.
 
 Snippets:
 @rlsr{Text}.
 
 Internals Reference:
 @rinternals{TextScript}.
 

-Installed Files:
-@file{scm/define-markup-commands.scm},
-@file{scm/fret-diagrams.scm},
-@file{scm/harp-pedals.scm}.
-

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


@@ -1275,8 +1331,8 @@ Installed Files:
 @cindex markup text, multi-page
 @cindex text spread over multiple pages
 
 @cindex markup text, multi-page
 @cindex text spread over multiple pages
 

-@funindex \markuplines
-@funindex markuplines
+@funindex \markuplist
+@funindex markuplist

 @funindex \justified-lines
 @funindex justified-lines
 @funindex \wordwrap-lines
 @funindex \justified-lines
 @funindex justified-lines
 @funindex \wordwrap-lines


@@ -1287,7 +1343,7 @@ makes it possible to enter lines of text that can spread over multiple
 pages:
 
 @lilypond[quote,verbatim]
 pages:
 
 @lilypond[quote,verbatim]

-\markuplines {
+\markuplist {

   \justified-lines {
     A very long text of justified lines.
     ...
   \justified-lines {
     A very long text of justified lines.
     ...


@@ -1313,29 +1369,27 @@ 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:
 @seealso
 Notation Reference:

-@ref{Text markup list commands},
-
-Snippets:
-@rlsr{Text}.
+@ref{Text markup list commands}.

 
 

-Extending:
+Extending LilyPond:

 @rextend{New markup list command definition}.
 
 @rextend{New markup list command definition}.
 

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

 Installed Files:
 @file{scm/define-markup-commands.scm}.
 
 Installed Files:
 @file{scm/define-markup-commands.scm}.
 

+Snippets:
+@rlsr{Text}.

 
 

-@funindex \markuplines
-@funindex markuplines
+Internals Reference:
+@rinternals{TextScript}.
+
+@funindex \markuplist
+@funindex markuplist

 
 @predefined
 
 @predefined

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

 @endpredefined
 
 
 @endpredefined
 
 


@@ -1371,8 +1425,8 @@ ordered in several families.  The following syntax allows various
 LilyPond @code{feta} non-text fonts to be used directly in markup
 mode:
 
 LilyPond @code{feta} non-text fonts to be used directly in markup
 mode:
 

-@lilypond[quote,verbatim,relative=2]
-a1^\markup {
+@lilypond[quote,verbatim,fragment]
+a'1^\markup {

   \vcenter {
     \override #'(font-encoding . fetaBraces)
     \lookup #"brace120"
   \vcenter {
     \override #'(font-encoding . fetaBraces)
     \lookup #"brace120"


@@ -1397,24 +1451,32 @@ 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}.
 
 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 Schoolbook, the @emph{sans}
-font and the monospaced @emph{typewriter} font -- these last two
-families are determined by the Pango installation.
+Three families of text fonts are made available:
+@itemize
+@item
+The @emph{roman} (serif) font,
+which defaults to LilyPond Serif (an alias of TeX Gyre Schola).
+@item
+The @emph{sans} font,
+which defaults to LilyPond Sans Serif (an alias of TeX Gyre Heros).
+@item
+The @emph{typewriter} (monospaced) font,
+which defaults to LilyPond Monospace (an alias of TeX Gyre Cursor).
+@end itemize

 
 Each family may include different shapes and series.  The following
 example demonstrates the ability to select alternate families, shapes,
 series and sizes.  The value supplied to @code{font-size} is the
 required change from the default size.
 
 
 Each family may include different shapes and series.  The following
 example demonstrates the ability to select 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
+@lilypond[quote,verbatim,fragment]
+\override Score.RehearsalMark.font-family = #'typewriter

 \mark \markup "Ouverture"
 \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
+\override Voice.TextScript.font-shape = #'italic
+\override Voice.TextScript.font-series = #'bold
+d''2.^\markup "Allegro"
+\override Voice.TextScript.font-size = #-3
+c''4^smaller

 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent


@@ -1448,11 +1510,11 @@ 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}.
 
 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},
 @ref{Music notation inside markup},
 @seealso
 Notation Reference:
 @ref{The Feta font},
 @ref{Music notation inside markup},

+@ref{Rotating objects},

 @ref{Selecting font and font size},
 @ref{Font}.
 
 @ref{Selecting font and font size},
 @ref{Font}.
 


@@ -1463,13 +1525,13 @@ Notation Reference:
 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,relative=2]
-\override Staff.TimeSignature #'font-name = #"Bitstream Charter"
-\override Staff.TimeSignature #'font-size = #2
+@lilypond[quote,verbatim,fragment]
+\override Staff.TimeSignature.font-name = #"Bitstream Charter"
+\override Staff.TimeSignature.font-size = #2

 \time 3/4
 
 \time 3/4
 

-a1_\markup {
-  \override #'(font-name . "Vera Bold")
+a'1_\markup {
+  \override #'(font-name . "Bitstream Vera Sans Bold")

     { Vera Bold }
 }
 @end lilypond
     { Vera Bold }
 }
 @end lilypond


@@ -1481,14 +1543,13 @@ a1_\markup {
 
 @funindex show-available-fonts
 
 
 @funindex show-available-fonts
 

-The following command displays a list of all available fonts on the
-operating system:
+Running lilypond with the following option displays a list of all
+available fonts on the operating system:

 
 @example
 lilypond -dshow-available-fonts x
 @end example
 
 
 @example
 lilypond -dshow-available-fonts x
 @end example
 

-

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


@@ -1507,8 +1568,9 @@ Snippets:
 
 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
 
 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}.
+specifying them, in that order, as shown in the example below, which
+automatically scales the fonts with the value set for the global staff
+size.  For an explanation of fonts, see @ref{Fonts explained}.

 
 @cindex font families, setting
 @cindex fonts, changing for entire document
 
 @cindex font families, setting
 @cindex fonts, changing for entire document


@@ -1517,12 +1579,11 @@ explanation of fonts, see @ref{Fonts explained}.
 
 @lilypond[verbatim,quote]
 \paper  {
 
 @lilypond[verbatim,quote]
 \paper  {

-  myStaffSize = #20

   #(define fonts
     (make-pango-font-tree "Times New Roman"
                           "Nimbus Sans"
                           "Luxi Mono"
   #(define fonts
     (make-pango-font-tree "Times New Roman"
                           "Nimbus Sans"
                           "Luxi Mono"

-                           (/ myStaffSize 20)))
+                          (/ staff-height pt 20)))

 }
 
 \relative c'{
 }
 
 \relative c'{


@@ -1536,7 +1597,6 @@ explanation of fonts, see @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},