From 5b3fe792ba44266c295e78381ac121cf3de4e1ac Mon Sep 17 00:00:00 2001 From: Trevor Daniels Date: Wed, 24 Sep 2008 11:29:28 +0100 Subject: [PATCH] Docs: NR 1.8.3 Fonts This commit adds quite a bunch of explanations and modifications (I hope I didn't break anything this time). A new "Fonts explained" subsection has been added at the beginning of the section; it aims to explain how both text- and non-text fonts are handled. The two following sections have been inverted (in order to introduce complexity more gradually). I have added @refs everywhere I could. --- Documentation/user/text.itely | 254 ++++++++++++++++++++++------------ 1 file changed, 163 insertions(+), 91 deletions(-) diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely index b1600dc22b..f82dc783db 100644 --- a/Documentation/user/text.itely +++ b/Documentation/user/text.itely @@ -1027,8 +1027,9 @@ d-\markup { @end lilypond More generally, any available musical symbol may be -included separately in a markup object, using the -following syntax: +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,fragment,relative=2] c2 @@ -1041,8 +1042,8 @@ c2^\markup { \musicglyph #"timesig.neomensural94" } @c TODO: add \lookup here? -vv @noindent -An exhaustive list of these symbols and their names can -be found in @ref{The Feta font}. +Another way of including non-text glyphs is described +in @ref{Fonts explained}. The markup mode also supports diagrams for specific instruments: @@ -1067,7 +1068,8 @@ c^\markup { @c The accordion diagram is actually taken from a snippet. @noindent -Such diagrams are documented in @ref{Instrument Specific Markup}. +@c VV: don't know what you intend here -td +@c Such diagrams are documented in @ref{Instrument Specific Markup}. A whole score can even be nested inside a markup object. In such a case, the nested @code{\score} block must @@ -1085,12 +1087,13 @@ c d e f @end lilypond An exhaustive list of music notation related commands can be -found in @ref{Music}. +found in @ref{Music notation inside markup}. @seealso Notation Reference: -@ref{Music}, -@ref{The Feta font}. +@ref{Music notation inside markup}, +@ref{The Feta font}, +@ref{Fonts explained}. Snippets: @rlsr{Text}. @@ -1157,127 +1160,196 @@ Installed files: @node Fonts @subsection Fonts +This section presents the way fonts are handled, +and how they may be changed in scores. + @menu -* Entire document fonts:: -* Single entry fonts:: +* Fonts explained:: +* Single entry fonts:: +* Entire document 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, +@node Fonts explained +@subsubsection Fonts explained -@cindex font families, setting @cindex Pango +@cindex fonts, explained +@funindex font-interface +Fonts are handled through several libraries. +FontConfig is used to detect available fonts on the system; +the selected fonts are rendered using Pango. -@lilypond[verbatim] -\paper { - myStaffSize = #20 - - #(define fonts - (make-pango-font-tree "Times New Roman" - "Nimbus Sans" - "Luxi Mono" - (/ myStaffSize 20))) -} +Music notation fonts can be described as a set of +specific glyphs, ordered in several families. +The following syntax allows to directly use various +LilyPond @code{feta} non-text fonts in markup mode: -{ - c'^\markup { roman: foo \sans bla \typewriter bar } +@lilypond[quote,verbatim,fragment,relative=2] +a1^\markup { + \vcenter { + \override #'(font-encoding . fetaBraces) + \lookup #"brace120" + \override #'(font-encoding . fetaNumber) + \column { 1 3 } + \override #'(font-encoding . fetaDynamic) + sf + \override #'(font-encoding . fetaMusic) + \lookup #"noteheads.s0petrucci" + } } @end lilypond -@c we don't do Helvetica / Courier, since GS incorrectly loads -@c Apple TTF fonts +@noindent +A simpler, but more limited syntax is also described in +@ref{Music notation inside markup}. +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. -@node Single entry fonts -@subsubsection Single entry fonts +Each family may include different shapes and series. +The following example demonstrates the ability to select +alternate families, shapes, series and sizes: -@cindex font selection -@cindex font magnification -@funindex font-interface +@lilypond[quote,verbatim,fragment,relative=2] + \override Score.RehearsalMark #'font-family = #'typewriter + \mark \markup "Ouverture" + \key d \major + \override Voice.TextScript #'font-shape = #'italic + \override Voice.TextScript #'font-series = #'bold + d''2.^\markup "Allegro" + r4 +@end lilypond -By setting the object properties described below, you can select a -font from the preconfigured font families. LilyPond has default -support for the feta music fonts. Text fonts are selected through -Pango/FontConfig. The serif font defaults to New Century -Schoolbook, the sans and typewriter to whatever the Pango -installation defaults to. +@noindent +A similar syntax may be used in markup mode, however in this case +it is preferable to use the simpler syntax explained in +@ref{Selecting font and font size}: +@lilypond[quote,verbatim] +\markup { + \column { + \line { + \override #'(font-shape . italic) + \override #'(font-size . 4) + Idomeneo, + } + \line { + \override #'(font-family . typewriter) + { + \override #'(font-series . bold) + re + di + } + \override #'(font-family . sans) + Creta + } + } +} +@end lilypond -@itemize -@item @code{font-encoding} -is a symbol that sets layout of the glyphs. This should only be -set to select different types of non-text fonts, e.g. +@ignore +@c FIXME: This needs an example -vv -@code{fetaBraces} for piano staff braces, @code{fetaMusic} the -standard music font, including ancient glyphs, @code{fetaDynamic} -for dynamic signs and @code{fetaNumber} for the number font. +The size of the font may be set with the @code{font-size} +property. The resulting size is taken relative to the +@code{text-font-size} as defined in the @code{\paper} block. +@end ignore -@item @code{font-family} -is a symbol indicating the general class of the typeface. -Supported are @code{roman} (Computer Modern), @code{sans}, and -@code{typewriter}. +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}. -@item @code{font-shape} -is a symbol indicating the shape of the font. There are typically -several font shapes available for each font family. Choices are -@code{italic}, @code{caps}, and @code{upright}. +@seealso +Notation Reference: +@ref{The Feta font}, +@ref{Music notation inside markup}, +@ref{Selecting font and font size}, +@ref{Font}. -@item @code{font-series} -is a symbol indicating the series of the font. There are -typically several font series for each font family and shape. -Choices are @code{medium} and @code{bold}. +@node Single entry fonts +@subsubsection Single entry fonts -@end itemize +Any font that is installed on the operating system and recognized +by FontConfig may be used in a score, using the following syntax: -Fonts selected in the way sketched above come from a predefined -style sheet. If you want to use a font from outside the style -sheet, then set the @code{font-name} property, +@lilypond[quote,verbatim,fragment,relative=1] +\override Staff.TimeSignature #'font-name = #"Charter" +\override Staff.TimeSignature #'font-size = #2 +\time 3/4 -@lilypond[fragment,verbatim] -{ - \override Staff.TimeSignature #'font-name = #"Charter" - \override Staff.TimeSignature #'font-size = #2 - \time 3/4 - c'1_\markup { - \override #'(font-name . "Vera Bold") - { This text is in Vera Bold } - } +c1_\markup { + \override #'(font-name . "Vera Bold") + { Vera Bold } } @end lilypond -@noindent -Any font can be used, as long as it is available to -Pango/FontConfig. To get a full list of all available fonts, run -the command +@funindex show-available-fonts + +The following command displays a list of all available fonts +on the operating system: @example -lilypond -dshow-available-fonts blabla +lilypond -dshow-available-fonts x @end example -(the last argument of the command can be anything, but has to be -present). +@noindent +The last argument of the command can be anything, but has to be +present. +@seealso +Notation Reference: +@ref{Fonts explained}, +@ref{Entire document fonts}. -The size of the font may be set with the @code{font-size} -property. The resulting size is taken relative to the -@code{text-font-size} as defined in the @code{\paper} block. +Snippets: +@rlsr{Text}. -@cindex font size -@cindex font magnification +Installed files: +@file{lily/@/font@/-config@/-scheme@/.cc}. +@node Entire document fonts +@subsubsection Entire document fonts +It is possible to change the default font families for the +entire document. In such a case, the following syntax has +to be used, by providing three font families that will be +respectively used as @emph{roman}, @emph{sans} and @emph{typewriter} +fonts, as explained in @ref{Fonts explained}. -@seealso +@cindex font families, setting +@funindex make-pango-font-tree -Snippets: -@rlsr{Text}. +@lilypond[verbatim,quote] +\paper { + myStaffSize = #20 + #(define fonts + (make-pango-font-tree "Times New Roman" + "Nimbus Sans" + "Luxi Mono" + (/ myStaffSize 20))) +} + +\relative c'{ + c1-\markup { + roman, + \sans sans, + \typewriter typewriter. } +} +@end lilypond +@c we don't do Helvetica / Courier, since GS incorrectly loads +@c Apple TTF fonts + +@seealso +Notation Reference: +@ref{Fonts explained}, +@ref{Single entry fonts}, +@ref{Selecting font and font size}, +@ref{Font}. -- 2.39.5