New upstream version 2.19.80

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

diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely
index 39e9d815c3af58b5cc6dd0fdb4225607495c2dc0..0d802ac6312a706ff3766624ad4250ecef1f4a95 100644 (file)
--- a/Documentation/notation/text.itely
+++ b/Documentation/notation/text.itely
@@ -1430,7 +1430,7 @@ DejaVu Sans Mono,
 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,
+Where a character doesn'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.
@@ -1477,6 +1477,42 @@ 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}.
@@ -1573,13 +1609,90 @@ described. For an explanation of fonts, see @ref{Fonts explained}.
 }
 @end lilypond
 
+Note: @code{make-pango-font-tree} resets the notation fonts to default of
+Emmentaler.
+
 @c we don't do Helvetica / Courier, since GS incorrectly loads
 @c Apple TTF fonts
 
+The following syntax allows you to change the specific fonts,
+leaving others to the default values.
+The following example has the same effect
+as the above @code{make-pango-font-tree} example.
+The same as  @code{make-pango-font-tree},
+you can specify a comma-separated list of @q{fonts} for @code{roman},
+@code{sans}, and @code{typewriter} categories.
+If you don't change the staff size from the default of 20 pt,
+@code{#:factor (/ staff-height pt 20)} is unnecessary.
+
+@funindex set-global-fonts
+
+@example
+\paper @{
+  #(define fonts
+    (set-global-fonts
+     #:roman "Times New Roman"
+     #:sans "Nimbus Sans,Nimbus Sans L"
+     #:typewriter "Luxi Mono"
+     #:factor (/ staff-height pt 20) ; unnecessary if the staff size is default
+    ))
+@}
+@end example
+
+It also can specify the notation fonts.
+The following example also has the same effect as the above examples,
+because it sets the notation fonts as the default.
+For more information, see @ref{Replacing the notation font}.
+
+@example
+\paper @{
+  #(define fonts
+    (set-global-fonts
+     #:music "emmentaler"            ; default
+     #:brace "emmentaler"            ; default
+     #:roman "Times New Roman"
+     #:sans "Nimbus Sans,Nimbus Sans L"
+     #:typewriter "Luxi Mono"
+     #:factor (/ staff-height pt 20) ; unnecessary if the staff size is default
+    ))
+@}
+@end example
+
+Note: Each call to @code{set-global-fonts} completely resets both the main
+notation and text fonts. If any category is left unspecified, then the default
+font will be used for that category.
+Each call of @code{set-global-fonts} affects each @code{\book} blocks that
+follow it.
+If there are multiple @code{\book} blocks and you want to use different fonts
+for each, simply call @code{set-global-fonts} again, like this:
+
+@example
+\paper @{
+  #(define fonts
+    (set-global-fonts
+     @dots{}
+    ))
+@}
+\book @{
+  @dots{}
+@}
+
+\paper @{
+  #(define fonts
+    (set-global-fonts
+     @dots{}
+    ))
+@}
+\book @{
+  @dots{}
+@}
+@end example
+
 @seealso
 Notation Reference:
 @ref{Fonts explained},
 @ref{Single entry fonts},
 @ref{Selecting font and font size},
-@ref{Font}.
+@ref{Font},
+@ref{Replacing the notation font}.