X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Ftext.itely;h=fabee1a937628909748f2d94d01e25dd157cb045;hb=07125596018d32e3235e80627915cfac77323272;hp=1f66c48a714603cfcba3bd341fbf27bf8c2c5414;hpb=15c207fe1e0c7a70184ec82e9f060d3ae599326d;p=lilypond.git

diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely
index 1f66c48a71..fabee1a937 100644
--- a/Documentation/notation/text.itely
+++ b/Documentation/notation/text.itely
@@ -92,9 +92,7 @@ For more information about the relative ordering of text scripts and
 articulations, see @rlearning{Placement of objects}.
 
 @funindex \textLengthOn
-@funindex textLengthOn
 @funindex \textLengthOff
-@funindex textLengthOff
 
 @predefined
 @code{\textLengthOn},
@@ -123,7 +121,7 @@ Internals Reference:
 
 @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
@@ -172,11 +170,8 @@ 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 \textSpannerNeutral
-@funindex textSpannerNeutral
 
 
 @predefined
@@ -223,9 +218,7 @@ Internals Reference:
 @cindex bar lines, symbols on
 
 @funindex \mark
-@funindex mark
 @funindex \markup
-@funindex markup
 
 Various text elements may be added to a score using the syntax described
 in @ref{Rehearsal marks}:
@@ -235,9 +228,12 @@ in @ref{Rehearsal marks}:
 
 @lilypond[verbatim,quote]
 \relative {
-  c''4
-  \mark "Allegro"
-  c c c
+  \mark "Verse"
+  c'2 g'
+  \bar "||"
+  \mark "Chorus"
+  g2 c,
+  \bar "|."
 }
 @end lilypond
 
@@ -284,9 +280,7 @@ the next line.
 @end lilypond
 
 @funindex \markLengthOn
-@funindex markLengthOn
 @funindex \markLengthOff
-@funindex markLengthOff
 
 @predefined
 @code{\markLengthOn},
@@ -306,7 +300,7 @@ Notation Reference:
 @ref{Rehearsal marks},
 @ref{Formatting text},
 @ref{Music notation inside markup},
-@ref{The Feta font}.
+@ref{The Emmentaler font}.
 
 Snippets:
 @rlsr{Text}.
@@ -328,7 +322,6 @@ Internals Reference:
 @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
@@ -364,9 +357,7 @@ requires, are described in @ref{Multi-page markup}.
 
 
 @funindex \markup
-@funindex markup
 @funindex \markuplist
-@funindex markuplist
 
 @predefined
 @code{\markup},
@@ -417,7 +408,6 @@ using the @code{\markup} mode specific syntax.
 @cindex typeset text
 
 @funindex \markup
-@funindex markup
 
 A @code{\markup} block is used to typeset text with an extensible
 syntax called @qq{markup mode}.
@@ -515,7 +505,7 @@ Installed Files:
 @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
@@ -526,11 +516,8 @@ Syntax errors for markup mode can be confusing.
 @cindex switching fonts
 
 @funindex \italic
-@funindex italic
 @funindex \bold
-@funindex bold
 @funindex \underline
-@funindex underline
 
 Basic font switching is supported in markup mode:
 
@@ -551,18 +538,14 @@ Basic font switching is supported in markup mode:
 
 @funindex \abs-fontsize
 @funindex \fontsize
-@funindex fontsize
 @funindex \smaller
-@funindex smaller
 @funindex \larger
-@funindex larger
 @funindex \magnify
-@funindex magnify
 
 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 b' {
@@ -572,7 +555,7 @@ It can be set to predefined size,
 }
 @end lilypond
 
-It can be set relative to its previous value,
+It can be set relative to its previous value.
 
 @lilypond[quote,verbatim]
 \relative b' {
@@ -583,7 +566,7 @@ It can be set relative to its previous value,
 @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 b' {
@@ -594,7 +577,7 @@ global staff size,
 @end lilypond
 
 It can also be set to a fixed point-size, regardless of the global staff
-size,
+size.
 
 @lilypond[quote,verbatim]
 \relative b' {
@@ -617,11 +600,8 @@ other characters.
 @cindex superscript
 
 @funindex \super
-@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:
@@ -688,21 +668,13 @@ Defining custom font sets is also possible, as explained in
 @ref{Fonts}.
 
 @funindex \teeny
-@funindex teeny
 @funindex \tiny
-@funindex tiny
 @funindex \small
-@funindex small
 @funindex \normalsize
-@funindex normalsize
 @funindex \large
-@funindex large
 @funindex \huge
-@funindex huge
 @funindex \smaller
-@funindex smaller
 @funindex \larger
-@funindex larger
 
 
 @predefined
@@ -760,11 +732,8 @@ objects can also be moved as a whole, using the syntax described in
 @cindex horizontal text alignment
 
 @funindex \left-align
-@funindex left-align
 @funindex \center-align
-@funindex center-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,
@@ -783,7 +752,6 @@ there is no difference between the first and the second markup.
 @end lilypond
 
 @funindex \halign
-@funindex halign
 
 Horizontal alignment may be fine-tuned using a numeric value:
 
@@ -809,11 +777,8 @@ markup objects as a whole, as shown for instance in
 @cindex vertical text alignment
 
 @funindex \raise
-@funindex raise
 @funindex \lower
-@funindex lower
 @funindex \null
-@funindex null
 
 @c QUERY Should the function of ``\null'' be clarified? rp
 
@@ -845,11 +810,8 @@ has no anchor point, and therefore is not moved.
 @end lilypond
 
 @funindex \general-align
-@funindex general-align
 @funindex \translate
-@funindex translate
 @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
@@ -883,9 +845,7 @@ must be preceded with an anchor point:
 @cindex columns, text
 
 @funindex \column
-@funindex 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
@@ -912,7 +872,6 @@ left-aligned or centered:
 @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
@@ -944,9 +903,7 @@ multi-line text or any other markup expression:
 @cindex markup text, justified
 
 @funindex \wordwrap
-@funindex wordwrap
 @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,
@@ -1023,15 +980,10 @@ commands.
 @cindex markup text, framing
 
 @funindex \box
-@funindex box
 @funindex \circle
-@funindex circle
 @funindex \rounded-box
-@funindex rounded-box
 @funindex \bracket
-@funindex bracket
 @funindex \hbracket
-@funindex hbracket
 
 Some markup commands allow decoration of text elements with graphics,
 as demonstrated in the following example.
@@ -1058,13 +1010,9 @@ as demonstrated in the following example.
 @cindex markup text padding
 
 @funindex \pad-markup
-@funindex pad-markup
 @funindex \pad-x
-@funindex pad-x
 @funindex \pad-to-box
-@funindex pad-to-box
 @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
@@ -1098,17 +1046,11 @@ Flute quartet keeps very uneven time."
 @cindex notation, graphic
 
 @funindex \combine
-@funindex combine
 @funindex \draw-circle
-@funindex draw-circle
 @funindex \filled-box
-@funindex filled-box
 @funindex \triangle
-@funindex triangle
 @funindex \draw-line
-@funindex draw-line
 @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.
@@ -1135,9 +1077,7 @@ text.  As with any markup expression, such objects can be combined.
 @cindex postscript
 
 @funindex \epsfile
-@funindex epsfile
 @funindex \postscript
-@funindex postscript
 
 Advanced graphic features include the ability to include external
 image files converted to the Encapsulated PostScript format
@@ -1238,7 +1178,7 @@ in markup mode:
 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}.
+@ref{The Emmentaler font}.
 
 @lilypond[quote,verbatim]
 \relative {
@@ -1308,7 +1248,7 @@ An exhaustive list of music notation related commands can be found in
 @seealso
 Notation Reference:
 @ref{Music},
-@ref{The Feta font},
+@ref{The Emmentaler font},
 @ref{Fonts explained}.
 
 Installed Files:
@@ -1332,11 +1272,8 @@ Internals Reference:
 @cindex text spread over multiple pages
 
 @funindex \markuplist
-@funindex markuplist
 @funindex \justified-lines
-@funindex justified-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
@@ -1386,7 +1323,6 @@ Internals Reference:
 @rinternals{TextScript}.
 
 @funindex \markuplist
-@funindex markuplist
 
 @predefined
 @code{\markuplist}.
@@ -1421,9 +1357,8 @@ 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,
-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,fragment]
 a'1^\markup {
@@ -1452,17 +1387,53 @@ left braces; right braces may be obtained by rotation, see
 @ref{Rotating objects}.
 
 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
+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,
@@ -1506,13 +1477,49 @@ is preferable to use the simpler syntax explained in
 }
 @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:
-@ref{The Feta font},
+@ref{The Emmentaler font},
 @ref{Music notation inside markup},
 @ref{Rotating objects},
 @ref{Selecting font and font size},
@@ -1541,6 +1548,12 @@ a'1_\markup {
 @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
 
 Running lilypond with the following option displays a list of all
@@ -1570,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
-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
@@ -1581,7 +1596,7 @@ size.  For an explanation of fonts, see @ref{Fonts explained}.
 \paper  {
   #(define fonts
     (make-pango-font-tree "Times New Roman"
-                          "Nimbus Sans"
+                          "Nimbus Sans,Nimbus Sans L"
                           "Luxi Mono"
                           (/ staff-height pt 20)))
 }