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 22471b86b312c810b548bfe507144a6fccbb7934..fabee1a937628909748f2d94d01e25dd157cb045 100644 (file)
--- a/Documentation/notation/text.itely
+++ b/Documentation/notation/text.itely
@@ -121,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


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


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


@@ -543,9 +543,9 @@ Basic font switching is supported in markup mode:
 @funindex \magnify
 
 The font size can be altered, relative to the global staff size, in a
 @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' {
 
 @lilypond[quote,verbatim]
 \relative b' {


@@ -555,7 +555,7 @@ It can be set to predefined size,
 }
 @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 b' {
 
 @lilypond[quote,verbatim]
 \relative b' {


@@ -566,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
 @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' {
 
 @lilypond[quote,verbatim]
 \relative b' {


@@ -577,7 +577,7 @@ global staff size,
 @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' {
 
 @lilypond[quote,verbatim]
 \relative b' {


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


@@ -1248,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:


@@ -1357,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,
 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 {
 
 @lilypond[quote,verbatim,fragment]
 a'1^\markup {


@@ -1388,17 +1387,53 @@ left braces; right braces may be obtained by rotation, see
 @ref{Rotating objects}.
 
 Three families of text fonts are made available:
 @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,
 
 Each family may include different shapes and series.  The following
 example demonstrates the ability to select alternate families, shapes,


@@ -1442,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},