Issue 5164: Doc: Add usage of OpenType font feature

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

diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely
index e6a085fc56e0b6488be5580168fdd8fafb5e6104..fabee1a937628909748f2d94d01e25dd157cb045 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.17.6"
+@c \version "2.19.21"

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


@@ -59,27 +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
 
 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,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
 
 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.
 
 @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.
 

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


@@ -89,9 +92,7 @@ For more information about the relative ordering of text scripts and
 articulations, see @rlearning{Placement of objects}.
 
 @funindex \textLengthOn
 articulations, see @rlearning{Placement of objects}.
 
 @funindex \textLengthOn

-@funindex textLengthOn

 @funindex \textLengthOff
 @funindex \textLengthOff

-@funindex textLengthOff

 
 @predefined
 @code{\textLengthOn},
 
 @predefined
 @code{\textLengthOn},


@@ -120,7 +121,7 @@ Internals Reference:
 
 @knownissues
 Checking to make sure that text scripts and lyrics are within the
 
 @knownissues
 Checking to make sure that text scripts and lyrics are within the

-margins requires additonal calculations. In cases where slightly faster
+margins requires additional calculations. In cases where slightly faster

 performance is desired, use
 
 @example
 performance is desired, use
 
 @example


@@ -139,10 +140,12 @@ multiple notes with dotted lines.  Such objects, called
 @qq{spanners}, may be created from one note to another using the
 following syntax:
 
 @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


@@ -154,22 +157,21 @@ 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
 object property.  This syntax is described in @ref{Line styles}.
 
 @funindex \textSpannerUp
 @end lilypond
 
 The line style, as well as the text string, can be defined as an
 object property.  This syntax is described in @ref{Line styles}.
 
 @funindex \textSpannerUp

-@funindex textSpannerUp

 @funindex \textSpannerDown
 @funindex \textSpannerDown

-@funindex textSpannerDown

 @funindex \textSpannerNeutral
 @funindex \textSpannerNeutral

-@funindex textSpannerNeutral

 
 
 @predefined
 
 
 @predefined


@@ -216,9 +218,7 @@ Internals Reference:
 @cindex bar lines, symbols on
 
 @funindex \mark
 @cindex bar lines, symbols on
 
 @funindex \mark

-@funindex mark

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


@@ -226,21 +226,28 @@ 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 {
+  \mark "Verse"
+  c'2 g'
+  \bar "||"
+  \mark "Chorus"
+  g2 c,
+  \bar "|."
+}

 @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


@@ -248,10 +255,12 @@ 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


@@ -261,22 +270,28 @@ 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.
 
 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
+@lilypond[quote,verbatim,ragged-right]
+\relative c'' {
+  \mark "Allegro"
+  c1 c
+  \mark "assai" \break
+  c  c
+}

 @end lilypond
 
 @end lilypond
 

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

 
 @snippets
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-marks-at-the-end-of-a-line.ly}
 
 
 @snippets
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-marks-at-the-end-of-a-line.ly}
 

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

 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-marks-on-every-staff.ly}
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-marks-on-every-staff.ly}
 


@@ -285,7 +300,7 @@ Notation Reference:
 @ref{Rehearsal marks},
 @ref{Formatting text},
 @ref{Music notation inside markup},
 @ref{Rehearsal marks},
 @ref{Formatting text},
 @ref{Music notation inside markup},

-@ref{The Feta font}.
+@ref{The Emmentaler font}.

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


@@ -307,7 +322,6 @@ Internals Reference:
 @cindex text, standalone
 
 @funindex \markup
 @cindex text, standalone
 
 @funindex \markup

-@funindex markup

 
 A @code{\markup} block can exist by itself, outside of any
 @code{\score} block, as a @qq{top-level expression}.  This syntax
 
 A @code{\markup} block can exist by itself, outside of any
 @code{\score} block, as a @qq{top-level expression}.  This syntax


@@ -343,9 +357,7 @@ requires, are described in @ref{Multi-page markup}.
 
 
 @funindex \markup
 
 
 @funindex \markup

-@funindex markup

 @funindex \markuplist
 @funindex \markuplist

-@funindex markuplist

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


@@ -396,7 +408,6 @@ using the @code{\markup} mode specific syntax.
 @cindex typeset text
 
 @funindex \markup
 @cindex typeset text
 
 @funindex \markup

-@funindex markup

 
 A @code{\markup} block is used to typeset text with an extensible
 syntax called @qq{markup mode}.
 
 A @code{\markup} block is used to typeset text with an extensible
 syntax called @qq{markup mode}.


@@ -416,14 +427,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


@@ -441,10 +454,12 @@ will be printed verbatim without affecting the formatting of the text.
 Double quotation marks themselves may be printed by preceding them
 with backslashes.
 
 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


@@ -453,11 +468,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


@@ -488,7 +505,7 @@ Installed Files:
 @file{scm/markup.scm}.
 
 @knownissues
 @file{scm/markup.scm}.
 
 @knownissues

-Syntax errors for markup mode can be confusing.
+Syntax error messages for markup mode can be confusing.

 
 
 @node Selecting font and font size
 
 
 @node Selecting font and font size


@@ -499,22 +516,21 @@ Syntax errors for markup mode can be confusing.
 @cindex switching fonts
 
 @funindex \italic
 @cindex switching fonts
 
 @funindex \italic

-@funindex italic

 @funindex \bold
 @funindex \bold

-@funindex bold

 @funindex \underline
 @funindex \underline

-@funindex underline

 
 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
 @end lilypond
 
 @cindex font size


@@ -522,60 +538,70 @@ f1 d2 r
 
 @funindex \abs-fontsize
 @funindex \fontsize
 
 @funindex \abs-fontsize
 @funindex \fontsize

-@funindex fontsize

 @funindex \smaller
 @funindex \smaller

-@funindex smaller

 @funindex \larger
 @funindex \larger

-@funindex larger

 @funindex \magnify
 @funindex \magnify

-@funindex magnify

 
 The font size can be altered, relative to the global staff size, in a
 
 The font size can be altered, relative to the global staff size, in a

-number of different ways
+number of different ways.

 
 

-It can be set to predefined size,
+It can be set to predefined size.

 
 

-@lilypond[quote,verbatim,relative=2]
-b1_\markup { \huge Sinfonia }
-b1^\markup { \teeny da }
-b1-\markup { \normalsize camera }
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \huge Sinfonia }
+  b1^\markup { \teeny da }
+  b1-\markup { \normalsize camera }
+}

 @end lilypond
 
 @end lilypond
 

-It can be set relative to its previous value,
+It can be set relative to its previous value.

 
 

-@lilypond[quote,verbatim,relative=2]
-b1_\markup { \larger Sinfonia }
-b1^\markup { \smaller da }
-b1-\markup { \magnify #0.6  camera }
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \larger Sinfonia }
+  b1^\markup { \smaller da }
+  b1-\markup { \magnify #0.6  camera }
+}

 @end lilypond
 
 It can be increased or decreased relative to the value set by the
 @end lilypond
 
 It can be increased or decreased relative to the value set by the

-global staff size,
+global staff size.

 
 

-@lilypond[quote,verbatim,relative=2]
-b1_\markup { \fontsize #-2 Sinfonia }
-b1^\markup { \fontsize #1 da }
-b1-\markup { \fontsize #3 camera }
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \fontsize #-2 Sinfonia }
+  b1^\markup { \fontsize #1 da }
+  b1-\markup { \fontsize #3 camera }
+}

 @end lilypond
 
 It can also be set to a fixed point-size, regardless of the global staff
 @end lilypond
 
 It can also be set to a fixed point-size, regardless of the global staff

-size,
+size.
+
+@lilypond[quote,verbatim]
+\relative b' {
+  b1_\markup { \abs-fontsize #20 Sinfonia }
+  b1^\markup { \abs-fontsize #8 da }
+  b1-\markup { \abs-fontsize #14 camera }
+}
+@end lilypond

 
 

-@lilypond[quote,verbatim,relative=2]
-b1_\markup { \abs-fontsize #20 Sinfonia }
-b1^\markup { \abs-fontsize #8 da }
-b1-\markup { \abs-fontsize #14 camera }
+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
 @cindex superscript
 
 @funindex \super
 @end lilypond
 
 @cindex subscript
 @cindex superscript
 
 @funindex \super

-@funindex super

 @funindex \sub
 @funindex \sub

-@funindex sub

 @funindex \normal-size-super
 @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:


@@ -642,21 +668,13 @@ Defining custom font sets is also possible, as explained in
 @ref{Fonts}.
 
 @funindex \teeny
 @ref{Fonts}.
 
 @funindex \teeny

-@funindex teeny

 @funindex \tiny
 @funindex \tiny

-@funindex tiny

 @funindex \small
 @funindex \small

-@funindex small

 @funindex \normalsize
 @funindex \normalsize

-@funindex normalsize

 @funindex \large
 @funindex \large

-@funindex large

 @funindex \huge
 @funindex \huge

-@funindex huge

 @funindex \smaller
 @funindex \smaller

-@funindex smaller

 @funindex \larger
 @funindex \larger

-@funindex larger

 
 
 @predefined
 
 
 @predefined


@@ -714,39 +732,39 @@ objects can also be moved as a whole, using the syntax described in
 @cindex horizontal text alignment
 
 @funindex \left-align
 @cindex horizontal text alignment
 
 @funindex \left-align

-@funindex left-align

 @funindex \center-align
 @funindex \center-align

-@funindex center-align

 @funindex \right-align
 @funindex \right-align

-@funindex right-align

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

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

-@funindex halign

 
 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
 @end lilypond
 
 @noindent


@@ -759,11 +777,8 @@ markup objects as a whole, as shown for instance in
 @cindex vertical text alignment
 
 @funindex \raise
 @cindex vertical text alignment
 
 @funindex \raise

-@funindex raise

 @funindex \lower
 @funindex \lower

-@funindex lower

 @funindex \null
 @funindex \null

-@funindex null

 
 @c QUERY Should the function of ``\null'' be clarified? rp
 
 
 @c QUERY Should the function of ``\null'' be clarified? rp
 


@@ -775,50 +790,51 @@ 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

-@funindex general-align

 @funindex \translate
 @funindex \translate

-@funindex translate

 @funindex \translate-scaled
 @funindex \translate-scaled

-@funindex translate-scaled

 
 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:
 
 
 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:
 

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


@@ -829,9 +845,7 @@ a'4 a g2 a
 @cindex columns, text
 
 @funindex \column
 @cindex columns, text
 
 @funindex \column

-@funindex column

 @funindex \center-column
 @funindex \center-column

-@funindex center-column

 
 A markup object may include several lines of text.  In the following
 example, each element or expression is placed on its own line, either
 
 A markup object may include several lines of text.  In the following
 example, each element or expression is placed on its own line, either


@@ -858,7 +872,6 @@ left-aligned or centered:
 @cindex markup, centering on the page
 
 @funindex \fill-line
 @cindex markup, centering on the page
 
 @funindex \fill-line

-@funindex fill-line

 
 Similarly, a list of elements or expressions may be spread to fill the
 entire horizontal line width (if there is only one element, it will be
 
 Similarly, a list of elements or expressions may be spread to fill the
 entire horizontal line width (if there is only one element, it will be


@@ -890,9 +903,7 @@ multi-line text or any other markup expression:
 @cindex markup text, justified
 
 @funindex \wordwrap
 @cindex markup text, justified
 
 @funindex \wordwrap

-@funindex wordwrap

 @funindex \justify
 @funindex \justify

-@funindex justify

 
 Long text indications can also be automatically wrapped accordingly to
 the given line width.  These will be either left-aligned or justified,
 
 Long text indications can also be automatically wrapped accordingly to
 the given line width.  These will be either left-aligned or justified,


@@ -969,15 +980,10 @@ commands.
 @cindex markup text, framing
 
 @funindex \box
 @cindex markup text, framing
 
 @funindex \box

-@funindex box

 @funindex \circle
 @funindex \circle

-@funindex circle

 @funindex \rounded-box
 @funindex \rounded-box

-@funindex rounded-box

 @funindex \bracket
 @funindex \bracket

-@funindex bracket

 @funindex \hbracket
 @funindex \hbracket

-@funindex hbracket

 
 Some markup commands allow decoration of text elements with graphics,
 as demonstrated in the following example.
 
 Some markup commands allow decoration of text elements with graphics,
 as demonstrated in the following example.


@@ -1004,13 +1010,9 @@ as demonstrated in the following example.
 @cindex markup text padding
 
 @funindex \pad-markup
 @cindex markup text padding
 
 @funindex \pad-markup

-@funindex pad-markup

 @funindex \pad-x
 @funindex \pad-x

-@funindex pad-x

 @funindex \pad-to-box
 @funindex \pad-to-box

-@funindex pad-to-box

 @funindex \pad-around
 @funindex \pad-around

-@funindex pad-around

 
 Some commands may require an increase in the padding around the text;
 this is achieved with some markup commands exhaustively described in
 
 Some commands may require an increase in the padding around the text;
 this is achieved with some markup commands exhaustively described in


@@ -1044,17 +1046,11 @@ Flute quartet keeps very uneven time."
 @cindex notation, graphic
 
 @funindex \combine
 @cindex notation, graphic
 
 @funindex \combine

-@funindex combine

 @funindex \draw-circle
 @funindex \draw-circle

-@funindex draw-circle

 @funindex \filled-box
 @funindex \filled-box

-@funindex filled-box

 @funindex \triangle
 @funindex \triangle

-@funindex triangle

 @funindex \draw-line
 @funindex \draw-line

-@funindex draw-line

 @funindex \arrow-head
 @funindex \arrow-head

-@funindex arrow-head

 
 Other graphic elements or symbols may be printed without requiring any
 text.  As with any markup expression, such objects can be combined.
 
 Other graphic elements or symbols may be printed without requiring any
 text.  As with any markup expression, such objects can be combined.


@@ -1081,9 +1077,7 @@ text.  As with any markup expression, such objects can be combined.
 @cindex postscript
 
 @funindex \epsfile
 @cindex postscript
 
 @funindex \epsfile

-@funindex epsfile

 @funindex \postscript
 @funindex \postscript

-@funindex postscript

 
 Advanced graphic features include the ability to include external
 image files converted to the Encapsulated PostScript format
 
 Advanced graphic features include the ability to include external
 image files converted to the Encapsulated PostScript format


@@ -1091,8 +1085,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)


@@ -1108,7 +1102,7 @@ c1^\markup {
       closepath
       stroke"
   }
       closepath
       stroke"
   }

-c
+c'

 @end lilypond
 
 An exhaustive list of graphics-specific commands can be found in
 @end lilypond
 
 An exhaustive list of graphics-specific commands can be found in


@@ -1116,9 +1110,10 @@ An exhaustive list of graphics-specific commands can be found in
 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

-@ref{Graphic},
+@ref{Align},
+@ref{Dimensions},

 @ref{Editorial annotations},
 @ref{Editorial annotations},

-@ref{Align}.
+@ref{Graphic}.

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


@@ -1143,53 +1138,57 @@ 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\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
+@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
 
 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
 }
 @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,relative=2]
-c2
-c'^\markup { \musicglyph #"eight" }
-c,4
-c,8._\markup { \musicglyph #"clefs.G_change" }
-c16
-c2^\markup { \musicglyph #"timesig.neomensural94" }
+@ref{The Emmentaler font}.
+
+@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


@@ -1199,20 +1198,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
 


@@ -1228,15 +1229,17 @@ 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
 @end lilypond
 
 An exhaustive list of music notation related commands can be found in


@@ -1245,7 +1248,7 @@ An exhaustive list of music notation related commands can be found in
 @seealso
 Notation Reference:
 @ref{Music},
 @seealso
 Notation Reference:
 @ref{Music},

-@ref{The Feta font},
+@ref{The Emmentaler font},

 @ref{Fonts explained}.
 
 Installed Files:
 @ref{Fonts explained}.
 
 Installed Files:


@@ -1269,11 +1272,8 @@ Internals Reference:
 @cindex text spread over multiple pages
 
 @funindex \markuplist
 @cindex text spread over multiple pages
 
 @funindex \markuplist

-@funindex markuplist

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

-@funindex justified-lines

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

-@funindex wordwrap-lines

 
 Although standard markup objects are not breakable, a specific syntax
 makes it possible to enter lines of text that can spread over multiple
 
 Although standard markup objects are not breakable, a specific syntax
 makes it possible to enter lines of text that can spread over multiple


@@ -1323,7 +1323,6 @@ Internals Reference:
 @rinternals{TextScript}.
 
 @funindex \markuplist
 @rinternals{TextScript}.
 
 @funindex \markuplist

-@funindex markuplist

 
 @predefined
 @code{\markuplist}.
 
 @predefined
 @code{\markuplist}.


@@ -1358,12 +1357,11 @@ detect available fonts on the system; the selected fonts are rendered
 using Pango.
 
 Music notation fonts can be described as a set of specific glyphs,
 using Pango.
 
 Music notation fonts can be described as a set of specific glyphs,

-ordered in several families.  The following syntax allows various
-LilyPond @code{feta} non-text fonts to be used directly in markup
-mode:
+ordered in several families.  The following syntax allows LilyPond's
+various @emph{Feta} glyphs 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"


@@ -1388,24 +1386,68 @@ 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:
+the @emph{roman} (serif) font,
+the @emph{sans} font, and the @emph{typewriter} font.
+
+For @code{svg} backend:
+@multitable @columnfractions .15 .30
+@headitem Family @tab Default font
+@item @emph{roman} @tab @code{serif}
+@item @emph{sans} @tab @code{sans-serif}
+@item @emph{typewriter} @tab @code{monospace}
+@end multitable
+
+@code{serif}, @code{sans-serif}, and @code{monospace} are
+@code{generic-family} in SVG and CSS specifications.
+
+For other backends:
+@multitable @columnfractions .15 .30 .55
+@headitem Family @tab Default font (alias) @tab Alias definition lists
+@item @emph{roman}
+@tab @code{LilyPond Serif}
+@tab
+TeX Gyre Schola,
+C059, Century SchoolBook URW, Century Schoolbook L,
+DejaVu Serif,
+..., serif
+@item @emph{sans}
+@tab @code{LilyPond Sans Serif}
+@tab
+TeX Gyre Heros,
+Nimbus Sans, Nimbus Sans L, DejaVu Sans,
+..., sans-serif
+@item @emph{typewriter}
+@tab @code{LilyPond Monospace}
+@tab
+TeX Gyre Cursor,
+Nimbus Mono PS, Nimbus Mono, Nimbus Mono L,
+DejaVu Sans Mono,
+..., monospace
+@end multitable
+
+@code{LilyPond Serif}, @code{LilyPond Sans Serif},
+and @code{LilyPond Monospace} are font aliases defined
+in the LilyPond dedicated FontConfig configuration file
+@code{00-lilypond-fonts.conf}.
+Where a character dosen't exist in the first font listed,
+the next font listed will be used instead for that character.
+For details of alias definitions, please see
+to @code{00-lilypond-fonts.conf} under the installed directory.

 
 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]
+@lilypond[quote,verbatim,fragment]

 \override Score.RehearsalMark.font-family = #'typewriter
 \mark \markup "Ouverture"
 \override Voice.TextScript.font-shape = #'italic
 \override Voice.TextScript.font-series = #'bold
 \override Score.RehearsalMark.font-family = #'typewriter
 \mark \markup "Ouverture"
 \override Voice.TextScript.font-shape = #'italic
 \override Voice.TextScript.font-series = #'bold

-d2.^\markup "Allegro"
+d''2.^\markup "Allegro"

 \override Voice.TextScript.font-size = #-3
 \override Voice.TextScript.font-size = #-3

-c4^smaller
+c''4^smaller

 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent


@@ -1435,13 +1477,49 @@ is preferable to use the simpler syntax explained in
 }
 @end lilypond
 
 }
 @end lilypond
 

+@noindent
+When using OpenType fonts, font features can be used.
+OpenType font scripts and languages can not be specified.
+Note: Not all OpenType fonts have all functions.
+If you request a feature that doesn't exist in the chosen font,
+then the feature is simply ignored.
+
+@lilypond[quote,verbatim]
+% True small caps
+\markup { Normal Style: Hello HELLO }
+\markup { \caps { Small Caps: Hello } }
+\markup { \override #'(font-features . ("smcp"))
+          { True Small Caps: Hello } }
+
+% Number styles
+\markup { Normal Number Style: 0123456789 }
+\markup { \override #'(font-features . ("onum"))
+          { Old Number Style: 0123456789 } }
+
+% Stylistic Alternates
+\markup { \override #'(font-features . ("salt 0"))
+          { Stylistic Alternates 0: εφπρθ } }
+\markup { \override #'(font-features . ("salt 1"))
+          { Stylistic Alternates 1: εφπρθ } }
+
+% Multiple features
+\markup { \override #'(font-features . ("onum" "smcp" "salt 1"))
+          { Multiple features: Hello 0123456789 εφπρθ } }
+@end lilypond
+
+@noindent For the full OpenType font feature list please see:
+@uref{https://www.microsoft.com/typography/otspec/featurelist.htm}
+
+@noindent For identifying features of OpenType fonts please see:
+@uref{http://lists.gnu.org/archive/html/lilypond-devel/2017-08/msg00004.html}
+

 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:
 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},
+@ref{The Emmentaler font},

 @ref{Music notation inside markup},
 @ref{Rotating objects},
 @ref{Selecting font and font size},
 @ref{Music notation inside markup},
 @ref{Rotating objects},
 @ref{Selecting font and font size},


@@ -1454,14 +1532,14 @@ 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]
+@lilypond[quote,verbatim,fragment]

 \override Staff.TimeSignature.font-name = #"Bitstream Charter"
 \override Staff.TimeSignature.font-size = #2
 \time 3/4
 
 \override Staff.TimeSignature.font-name = #"Bitstream Charter"
 \override Staff.TimeSignature.font-size = #2
 \time 3/4
 

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

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -1470,10 +1548,16 @@ a1_\markup {
 @cindex listing available fonts
 @cindex available fonts, listing
 
 @cindex listing available fonts
 @cindex available fonts, listing
 

+@var{font-name} can be described using a comma-separated list of @q{fonts}
+and a white-space separated list of @q{styles}.
+As long as the @q{font} in the list is installed
+and contains requested glyph, it will be used,
+otherwise the @emph{next} font in the list will be used instead.
+

 @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
 
 @example
 lilypond -dshow-available-fonts x


@@ -1499,7 +1583,9 @@ 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, which
 automatically scales the fonts with the value set for the global staff
 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
 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}.
+size. Similar to @ref{Single entry fonts}, it can be described using a
+comma-separated list of @q{fonts}. However, font @q{styles} can not be
+described. 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


@@ -1510,7 +1596,7 @@ size.  For an explanation of fonts, see @ref{Fonts explained}.
 \paper  {
   #(define fonts
     (make-pango-font-tree "Times New Roman"
 \paper  {
   #(define fonts
     (make-pango-font-tree "Times New Roman"

-                          "Nimbus Sans"
+                          "Nimbus Sans,Nimbus Sans L"

                           "Luxi Mono"
                           (/ staff-height pt 20)))
 }
                           "Luxi Mono"
                           (/ staff-height pt 20)))
 }