Add doctitle fragment option in docs, including policy update

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

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index 2eca283eaf1eeee916726400ed54a8658f8b6182..dea840d0cb088e0f2929328cef79b9712e7fc825 100644 (file)
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -14,7 +14,7 @@
 @lilypondfile[quote]{text-headword.ly}
 
 This section explains how to include text (with various
 @lilypondfile[quote]{text-headword.ly}
 
 This section explains how to include text (with various

-formatting) in your scores.
+formatting) in music scores.

 
 @noindent
 Some text elements that are not dealt with here are discussed in other
 
 @noindent
 Some text elements that are not dealt with here are discussed in other


@@ -29,18 +29,21 @@ information, see @ref{Text encoding}.}
 
 @menu
 * Writing text::                
 
 @menu
 * Writing text::                

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

 @end menu
 
 
 @node Writing text
 @subsection Writing text
 
 @end menu
 
 
 @node Writing text
 @subsection Writing text
 

-@menu     
+This section introduces different ways of adding text to a score.
+
+@menu

 * Text scripts::                
 * Text spanners::               
 * Text marks::                  
 * Text scripts::                
 * Text spanners::               
 * Text marks::                  

-* Separate text::                  
+* Separate text::               

 @end menu
 
 
 @end menu
 
 


@@ -94,9 +97,10 @@ d8^"pizz." e f g \textLengthOn a4_"scherzando" f
 Notation Reference: @ref{Formatting text},
 @ref{Controlling direction and placement}.
 
 Notation Reference: @ref{Formatting text},
 @ref{Controlling direction and placement}.
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

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

 
 @knownissues
 
 
 @knownissues
 


@@ -118,9 +122,8 @@ default; to enable it, use
 Some performance indications, e.g., @i{rallentando} or
 @i{accelerando}, are written as text and are extended over many
 measures with dotted lines.
 Some performance indications, e.g., @i{rallentando} or
 @i{accelerando}, are written as text and are extended over many
 measures with dotted lines.

-

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

-from one note to another by 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." 
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \override TextSpanner #'bound-details #'left #'text = "rit." 


@@ -130,9 +133,9 @@ e,\stopTextSpan
 
 @noindent
 The string to be printed is set through
 
 @noindent
 The string to be printed is set through

-object properties. By default it is printed in italic characters,
+object properties.  By default it is printed in italic characters,

 but different formatting can be obtained using
 but different formatting can be obtained using

-@code{\markup} blocks:
+@code{\markup} blocks, as described in @ref{Formatting text}.

 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \override TextSpanner #'bound-details #'left #'text =
 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \override TextSpanner #'bound-details #'left #'text =


@@ -142,7 +145,7 @@ 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

-object property. This syntax is described in @ref{Line styles}.
+object property.  This syntax is described in @ref{Line styles}.

 
 @predefined
 
 
 @predefined
 


@@ -157,9 +160,10 @@ object property. This syntax is described in @ref{Line styles}.
 
 Notation Reference: @ref{Line styles}.
 
 
 Notation Reference: @ref{Line styles}.
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

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

 
 
 @node Text marks
 
 
 @node Text marks


@@ -175,7 +179,7 @@ Various text elements can be added to a score using
 the syntax described in @ref{Rehearsal marks}:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 the syntax described in @ref{Rehearsal marks}:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]

-c4\mark "dolce" c c c
+c4\mark "Allegro" c c c

 @end lilypond
 
 This syntax makes possible to put any text on a bar line;
 @end lilypond
 
 This syntax makes possible to put any text on a bar line;


@@ -190,14 +194,14 @@ c1
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-Such objects are only typeset above the top staff of the score; they
-can be placed above the bar line or between notes, depending on whether
-you specify it at the end or the middle of a bar. When specified at the
-beginning of a score or at a line break, the mark will be printed at
+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).
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 the beginning of the line (the next line, in case of a line break).
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]

-\mark "dolce" c1
+\mark "Allegro" c1

 c\mark "assai" \break
 c c
 @end lilypond
 c\mark "assai" \break
 c c
 @end lilypond


@@ -205,13 +209,13 @@ c c
 
 @snippets
 
 
 @snippets
 

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

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

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

 {aligning-marks-with-various-notation-objects.ly}
 
 {aligning-marks-with-various-notation-objects.ly}
 

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

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


@@ -219,9 +223,10 @@ c c
 Notation Reference: @ref{Rehearsal marks},
 @ref{Formatting text}, @ref{The Feta font}.
 
 Notation Reference: @ref{Rehearsal marks},
 @ref{Formatting text}, @ref{The Feta font}.
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

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

 
 @knownissues
 @c  IMO this is a bug; hopefully it'll be fixed soon, so I can
 
 @knownissues
 @c  IMO this is a bug; hopefully it'll be fixed soon, so I can


@@ -242,16 +247,14 @@ all.
 @funindex \markup
 
 A @code{\markup} block can exist by itself, outside of any
 @funindex \markup
 
 A @code{\markup} block can exist by itself, outside of any

-any @code{\score} block.  This syntax is called a @q{top-level
-expression}, and is described in @code{File structure}.
-
-@c TODO: turn this into a @lilypond example
+any @code{\score} block, as a @qq{top-level
+expression}.  This syntax is described in @ref{File structure}.

 
 

-@example
-\markup @{
-  @var{..}
-@}
-@end example
+@lilypond[quote,ragged-right,verbatim]
+\markup {
+  Tomorrow, and tomorrow, and tomorrow...
+}
+@end lilypond

 
 @noindent
 This allows to print text separately
 
 @noindent
 This allows to print text separately


@@ -260,59 +263,63 @@ useful when the input file contains
 several music pieces, as described in
 @ref{Multiple scores in a book}.
 
 several music pieces, as described in
 @ref{Multiple scores in a book}.
 

-@example
-\score @{
-  @var{..}
-@}
-\markup @{
-  @var{..}
-@}
-\score @{
-  @var{..}
-@}
-@end example
+@lilypond[quote,ragged-right,verbatim]
+\score {
+  c'1
+}
+\markup {
+  Tomorrow, and tomorrow, and tomorrow...
+}
+\score {
+  c'1
+}
+@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
 
 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{Page wrapping text}.
+@ref{Multi-page markup}.
+
+@predefined
+
+@funindex \markup
+@code{\markup},
+@funindex \markuplines
+@code{\markuplines}

 
 @ignore
 @snippets
 
 
 @ignore
 @snippets
 

-TODO: add convenient snippets, e.g.
-"Inserting large plain text sections"
-(this requires the LSR to be updated) -vv
+TODO: add convenient snippets in input/new -vv

 @end ignore
 
 @seealso
 
 @end ignore
 
 @seealso
 

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

 @ref{Multiple scores in a book},
 @ref{Multiple scores in a book},

-@ref{Page wrapping text}.
+@ref{Multi-page markup}.

 
 

-Snippets: @lsrdir{Text,Text}.
+Snippets:
+@rlsr{Text}.

 
 

-Internals Reference: @internalsref{TextScript}.
-
-@predefined
-
-@funindex \markup
-@code{\markup},
-@funindex \markuplines
-@code{\markuplines}
+Internals Reference: @rinternals{TextScript}.

 
 
 @node Formatting text
 @subsection Formatting text
 
 
 
 @node Formatting text
 @subsection Formatting text
 

+This section presents basic and advanced text formatting,
+using the @code{\markup} mode specific syntax.
+

 @menu
 * Text markup introduction::    
 @menu
 * Text markup introduction::    

-* Nested scores::               
-* Page wrapping text::          
-* Font selection::              
+* Common markup commands::      
+* 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


@@ -323,122 +330,229 @@ Internals Reference: @internalsref{TextScript}.
 @cindex markup text
 @cindex typeset text
 
 @cindex markup text
 @cindex typeset text
 

-A @code{\markup} block is used to typeset text with an extensible syntax,
-called @q{markup mode}.
-Specific commands can be entered in this mode, using the
-backslash @code{\} character.
-@c TODO: move the following sentence (and add an example?) -vv
-To @emph{print} such characters as
-@code{\} and @code{#} in the output, use double
-quotation marks.
+A @code{\markup} block is used to typeset text with an extensible
+specific syntax called @qq{markup mode}.
+
+@cindex markup expressions
+@cindex markup syntax
+
+The markup syntax is similar to LilyPond's usual syntax: a
+@code{\markup} expression is enclosed in curly braces @code{@{
+@dots{} @}}.
+
+In markup mode, specific commands are entered using the backslash
+@code{\} character.  Such commands only affect the first following
+expression.
+
+Markup expressions may also be enclosed in double quotes
+@code{"..."}. Such expressions are treated as text strings
+and may not contain nested expressions or commands.
+Therefore, braces are generally prefered to double quotes;
+the following example demonstrates both syntaxes.

 
 @lilypond[quote,verbatim,fragment,relative=1]
 
 @lilypond[quote,verbatim,fragment,relative=1]

-c1^\markup { hello }
-c1_\markup { hi there }
-c1^\markup { hi \bold there, is \italic {anyone home?} }
-c1_\markup { "\special {weird} #characters" }
+e1-\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
 
 @end lilypond
 

-@noindent
-An exhaustive list of @code{\markup}-specific commands can be found in
-@ref{Text markup commands}.
+@cindex special characters in markup mode
+@cindex markup mode, special characters
+@cindex reserved characters, printing
+@cindex printing special characters
+
+Special characters such as @code{\} and @code{#}
+can be printed in the output simply using double
+quotes.  Double quotation marks are only printed
+in the output when preceded by backslashes:
+
+@lilypond[quote,verbatim,fragment,relative=1]
+\clef bass
+a^\markup "##\ LEPORELLO \##"
+a_\markup "Bravi! \"Cosa rara\"!"
+r a8 d
+cis a r4 r2
+@end lilypond

 
 

-@code{\markup} blocks can be used anywhere text is called,
-and not only for @internalsref{TextScript}s objects.
+The way markup expressions are defined affects 
+how these expressions will stacked, centered and aligned
+when using the commands explained in @ref{Text alignment}.
+
+@lilypond[quote,verbatim,fragment,relative=1]
+c1^\markup { \column { a bbbb \line { c d } } }
+c1^\markup { \center-align { a bbbb c } }
+c1^\markup { \line { a b c } }
+@end lilypond
+
+Lists of words that are not enclosed with double quotes
+or preceded by a previous command are not kept distinct.  In
+the following example, the first two @code{\markup} expressions
+are equivalent:
+
+@lilypond[quote,verbatim,fragment,relative=1]
+c1^\markup { \center-align { a bbb c } }
+c1^\markup { \center-align { a { bbb c } } }
+c1^\markup { \center-align { a \line { bbb c } } }
+@end lilypond
+
+
+Markups can be stored in variables.  These variables may be
+directly attached to notes:

 
 @lilypond[quote,verbatim]
 
 @lilypond[quote,verbatim]

-\header{ title = \markup{ \bold { foo \italic { bar! } } } }
-\score{
-  \relative c'' {
-    \override Score.RehearsalMark
-      #'break-visibility = #begin-of-line-invisible
-    \override Score.RehearsalMark #'self-alignment-X = #right
-
-    \set Staff.instrumentName = \markup{ \column{ Alto solo } }
-    c2^\markup{ don't be \flat }
-    \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
-    b2\startTextSpan
-    a2\mark \markup{ \large \bold Fine }
-    r2\stopTextSpan
-    \bar "||"
-  }
-  \addlyrics { bar, foo \markup{ \italic bar! } }
+allegro = \markup { \bold \large Allegro }
+
+{
+  d''8.^\allegro
+  d'16 d'4 r2

 }
 @end lilypond
 
 }
 @end lilypond
 

-A @code{\markup} block can also be printed on its own at the top-level
-of the input file, away from
-any @code{\score} block. This syntax is described in
-@ref{Multiple scores in a book}.

 
 

-@lilypond[quote,ragged-right,verbatim]
-\markup{ Here is some text. }
-@end lilypond
+@noindent
+An exhaustive list of @code{\markup}-specific commands can be found in
+@ref{Text markup commands}.
+
+
+@seealso
+
+This manual: @ref{Text markup commands}.
+
+Snippets:
+@rlsr{Text}.
+
+Internals Reference: @rinternals{TextScript}.
+
+Init files: @file{scm/@/new@/-markup@/.scm}.
+
+
+@knownissues
+
+@c FIXME: this is totally deprecated, isn't it? -vv
+Kerning or generation of ligatures is only done when the @TeX{}
+backend is used.  In this case, LilyPond does not account for them
+so texts will be spaced slightly too wide.
+
+@c is the following sentence really relevant? -vv
+Syntax errors for markup mode are confusing.
+
+
+@node Common markup commands
+@subsubsection Common markup commands
+
+Some basic formatting can be used blah blah
+
+
+
+@ignore
+TODO: here are some commands that could be described here.
+I'm putting them in bulk, prior to working on this section. -vv
+
+\simple
+
+\char
+\fraction
+
+\combine
+\concat
+\put-adjacent
+
+
+\page-ref (see also "Table of contents")
+\fromproperty
+\verbatim-file
+\with-url
+
+\on-the-fly 
+\override
+
+
+\null
+\hspace
+
+\lower
+\raise 
+\translate 
+\translate-scaled
+\rotate
+\transparent
+\whiteout
+
+@end ignore
+
+

 
 @cindex font switching
 
 
 @cindex font switching
 

-Some font switching commands are demonstrated here. Such commands
-apply only to the first following word; several words may be affected
-by enclosing them in braces.
+Some font switching commands are demonstrated here.

 
 

-@example
-\markup @{ \bold @{ hi there @} @}
-@end example
+\italic 
+\upright
+\bold 
+\medium        
+\underline
+       

 
 

-@c TODO: remove the following line and example? -vv
-@noindent
-For clarity, you can also do this for single arguments, e.g.,
+@c TODO: what's the difference between the following commands? -vv
+\smallCaps     
+\caps 
+\fontCaps

 
 

-@example
-\markup @{ is \italic @{ anyone @} home @}
-@end example

 
 

-The markup mode can be used to compose expressions, similar to
-mathematical expressions, XML documents, and music expressions.
-Such expressions can be vertically stacked, horizontally centered, 
-or aligned in different ways:
+Some alternate font families can easily be selected:

 
 

-@lilypond[quote,verbatim,fragment,relative=1]
-c1^\markup { \column { a bbbb \line { c d } } }
-c1^\markup { \center-align { a bbbb c } }
-c1^\markup { \line { a b c } }
-@end lilypond
+\sans
+\typewriter
+\roman
+\number (only for numbers, such as fingerings and time signatures)
+@c TODO: add \slashed-digit here? -vv

 
 

-Lists with no previous command are not kept distinct.  In
-the following example, the two @code{\markup} expressions
-are equivalent:
+The size can be blah blah blah

 
 

-@c TODO: merge these two examples in a @lilypond example -vv
+\fontsize

 
 

-@example
-\center-align @{ @{ a b @} @{ c d @} @}
-\center-align @{ a b c d @}
-@end example
+Some predefined font sizes can be used blah blah

 
 

-@noindent
+\teeny
+\tiny
+\small 
+\normalsize
+\large
+\huge

 
 

-To keep lists of words distinct, please use quotes @code{"} or
-the @code{\line} command
+Some shorcuts allow to change the font size relatively to its previous value 

 
 

-@lilypond[quote,verbatim,fragment,relative=1]
-\textLengthOn
-c4^\markup{ \center-align { on three lines } }
-c4^\markup{ \center-align { "all one line" } }
-c4^\markup{ \center-align { { on three lines } } }
-c4^\markup{ \center-align { \line { on one line } } }
-@end lilypond
+\smaller
+\bigger
+\larger

 
 

-Markups can be stored in variables and these variables may be
-attached to notes, like
+\magnify
+
+Text may be printed as subscript or superscript:
+
+\sub 
+\super
+
+To obtain subscripts or superscripts in a normal text size, use
+\normal-size-sub
+\normal-size-super
+
+All these settings (except the size) can be reverted to the default font:
+
+\normal-text 
+
+
+@node Text alignment
+@subsubsection Text alignment

 
 

-@example
-allegro = \markup @{ \bold \large @{ Allegro @} @}
- @{ a^\allegro b c d @}
-@end example

 
 Some objects have alignment procedures of their own, which cancel
 out any effects of alignments applied to their markup arguments as
 
 Some objects have alignment procedures of their own, which cancel
 out any effects of alignments applied to their markup arguments as

-a whole.  For example, the @internalsref{RehearsalMark} is
+a whole.  For example, the @rinternals{RehearsalMark} is

 horizontally centered, so using @code{\mark \markup @{ \left-align
 .. @}} has no effect.
 
 horizontally centered, so using @code{\mark \markup @{ \left-align
 .. @}} has no effect.
 


@@ -462,32 +576,122 @@ advisable to cancel those properties with @code{normal-text}.  See
 @ref{Text markup commands}, for more details.
 
 
 @ref{Text markup commands}, for more details.
 
 

-@seealso
+Alignment basics:
+\left-align
+\center-align
+\right-align

 
 

-This manual: @ref{Text markup commands}.
+Horizontal alignment:
+\hcenter
+\general-align
+\halign 

 
 

-Snippets: @lsrdir{Text,Text}

 
 

-Internals Reference: @internalsref{TextScript}.
+Vertical alignment: 
+\vcenter
+\column 
+\dir-column 

 
 

-Init files: @file{scm/@/new@/-markup@/.scm}.
+Building a "large" markup:

 
 

+\line

 
 

-@knownissues
+\fill-line

 
 

-Kerning or generation of ligatures is only done when the @TeX{}
-backend is used.  In this case, LilyPond does not account for them
-so texts will be spaced slightly too wide.
+\hcenter-in
+       
+\pad-around
+\pad-markup
+\pad-to-box
+\pad-x
+       
+Alignment inside a "large" markup:

 
 

-Syntax errors for markup mode are confusing.
+\justify-field 
+\justify
+\justify-string
+
+\wordwrap-field
+\wordwrap
+\wordwrap-string
+
+@node Graphic notation inside markup
+@subsubsection Graphic notation inside markup
+Graphics around text:
+\box
+\circle
+
+\bracket
+\hbracket
+
+"Standalone" graphics:
+
+\arrow-head
+\draw-line
+\draw-circle
+\filled-box
+\triangle
+\strut

 
 

+\with-color

 
 

-@node Nested scores
-@subsubsection Nested scores

 
 

-It is possible to nest music inside markups, by adding a
-@code{\score} block to a markup expression.  Such a score must
-contain a @code{\layout} block.
+Advanced graphics:
+\stencil
+
+\postscript
+\epsfile
+
+\with-dimensions
+
+@node Music notation inside markup
+@subsubsection Music notation inside markup
+
+Notes can be printed in markup mode blah blah:
+
+\note  
+\note-by-number
+
+Accidental symbols can be obtained easily:
+
+\doubleflat
+\sesquiflat
+\flat
+\semiflat
+\natural
+\semisharp
+\sharp
+\sesquisharp
+\doublesharp
+
+Some other notation objects blah blah
+
+\beam
+\finger
+\dynamic
+\tied-lyric
+\markalphabet
+\markletter
+@c TODO: add \text here? -vv
+
+Any musical symbol can be printed
+
+\musicglyph
+@c TODO: add \lookup here? -vv
+
+
+The markup mode has support for fret diagrams:
+
+\fret-diagram 
+\fret-diagram-terse
+\fret-diagram-verbose
+
+An entire @code{\score} block can even be nested in a @code{\markup}
+block.  In such a case, the @code{\score} must contain a @code{\layout} block.
+
+
+\score
+

 
 @lilypond[quote,verbatim,ragged-right]
 \relative {
 
 @lilypond[quote,verbatim,ragged-right]
 \relative {


@@ -503,10 +707,11 @@ contain a @code{\layout} block.
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

-@node Page wrapping text
-@subsubsection Page wrapping text
+@node Multi-page markup
+@subsubsection Multi-page markup

 
 Whereas @code{\markup} is used to enter a non-breakable block of
 text, @code{\markuplines} can be used at top-level to enter lines
 
 Whereas @code{\markup} is used to enter a non-breakable block of
 text, @code{\markuplines} can be used at top-level to enter lines


@@ -536,15 +741,61 @@ lists.  The built-in markup list commands are described in
 This manual: @ref{Text markup list commands}, @ref{New
 markup list command definition}.
 
 This manual: @ref{Text markup list commands}, @ref{New
 markup list command definition}.
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 @predefined
 
 @funindex \markuplines
 @code{\markuplines}
 
 
 @predefined
 
 @funindex \markuplines
 @code{\markuplines}
 

-@node Font selection
-@subsubsection Font selection
+
+
+@c TODO: move the following subsubsec into NR3 -vv
+@c maybe.  -gp
+@node Fonts
+@subsection Fonts
+
+@menu
+* Entire document fonts::       
+* Single entry fonts::          
+@end menu
+
+@node Entire document fonts
+@subsubsection Entire document fonts
+
+It is also possible to change the default font family for the
+entire document.  This is done by calling the
+@code{make-pango-font-tree} from within the @code{\paper} block.
+The function takes names for the font families to use for roman,
+sans serif and monospaced text.  For example,
+
+@cindex font families, setting
+@cindex Pango
+
+
+@lilypond[verbatim]
+\paper  {
+  myStaffSize = #20
+
+  #(define fonts
+    (make-pango-font-tree "Times New Roman"
+                          "Nimbus Sans"
+                          "Luxi Mono"
+                           (/ myStaffSize 20)))
+}
+
+{
+  c'^\markup { roman: foo \sans bla \typewriter bar }
+}
+@end lilypond
+
+@c we don't do Helvetica / Courier, since GS incorrectly loads
+@c Apple TTF fonts
+
+
+@node Single entry fonts
+@subsubsection Single entry fonts

 
 @cindex font selection
 @cindex font magnification
 
 @cindex font selection
 @cindex font magnification


@@ -621,39 +872,11 @@ property.  The resulting size is taken relative to the
 @cindex font magnification
 
 
 @cindex font magnification
 
 

-It is also possible to change the default font family for the
-entire document.  This is done by calling the
-@code{make-pango-font-tree} from within the @code{\paper} block.
-The function takes names for the font families to use for roman,
-sans serif and monospaced text.  For example,
-
-@cindex font families, setting
-@cindex Pango
-
-
-@lilypond[verbatim]
-\paper  {
-  myStaffSize = #20
-
-  #(define fonts
-    (make-pango-font-tree "Times New Roman"
-                          "Nimbus Sans"
-                          "Luxi Mono"
-                           (/ myStaffSize 20)))
-}
-
-{
-  c'^\markup { roman: foo \sans bla \typewriter bar }
-}
-@end lilypond
-
-@c we don't do Helvetica / Courier, since GS incorrectly loads
-@c Apple TTF fonts
-

 
 
 @seealso
 
 
 
 @seealso
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.