X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Ftext.itely;h=3a9cdbd6d2d9bb27893bc417405cfc4b0423b7bd;hb=629a98d913218597d04dfc3c41154e7ff2c76582;hp=7b056dbdbd3fe4e67625ad60acba4278e0469f82;hpb=522f419e3ed3e09ecf834bbb5315ac1777ab13e0;p=lilypond.git diff --git a/Documentation/notation/text.itely b/Documentation/notation/text.itely index 7b056dbdbd..3a9cdbd6d2 100644 --- a/Documentation/notation/text.itely +++ b/Documentation/notation/text.itely @@ -7,7 +7,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.16.0" +@c \version "2.19.21" @node Text @section Text @@ -59,27 +59,30 @@ demonstrated in the following example. Such indications may be manually placed above or below the staff, using the syntax described in @ref{Direction and placement}. -@lilypond[quote,verbatim,relative=2] -a8^"pizz." g f e a4-"scherz." f +@lilypond[quote,verbatim] +\relative { a'8^"pizz." g f e a4-"scherz." f } @end lilypond This syntax is actually a shorthand; more complex text formatting may be added to a note by explicitly using a @code{\markup} block, as described in @ref{Formatting text}. -@lilypond[quote,verbatim,relative=2] -a8^\markup { \italic pizz. } g f e -a4_\markup { \tiny scherz. \bold molto } f +@lilypond[quote,verbatim] +\relative { + a'8^\markup { \italic pizz. } g f e + a4_\markup { \tiny scherz. \bold molto } f } @end lilypond By default, text indications do not influence the note spacing. However, their widths can be taken into account: in the following example, the first text string does not affect spacing, whereas the second one does. -@lilypond[quote,verbatim,relative=2] -a8^"pizz." g f e -\textLengthOn -a4_"scherzando" f +@lilypond[quote,verbatim] +\relative { + a'8^"pizz." g f e + \textLengthOn + a4_"scherzando" f +} @end lilypond In addition to text scripts, articulations can be attached to notes. @@ -124,7 +127,7 @@ margins requires additonal calculations. In cases where slightly faster performance is desired, use @example -\override Score.PaperColumn #'keep-inside-line = ##f +\override Score.PaperColumn.keep-inside-line = ##f @end example @@ -139,10 +142,12 @@ multiple notes with dotted lines. Such objects, called @qq{spanners}, may be created from one note to another using the following syntax: -@lilypond[verbatim,quote,relative=2] -\override TextSpanner #'(bound-details left text) = "rit." -b1\startTextSpan -e,\stopTextSpan +@lilypond[verbatim,quote] +\relative { + \override TextSpanner.bound-details.left.text = "rit." + b'1\startTextSpan + e,\stopTextSpan +} @end lilypond @cindex text spanners, formatting @@ -154,11 +159,13 @@ it is printed in italic characters, but different formatting can be obtained using @code{\markup} blocks, as described in @ref{Formatting text}. -@lilypond[quote,relative=2,verbatim] -\override TextSpanner #'(bound-details left text) = - \markup { \upright "rit." } -b1\startTextSpan c -e,\stopTextSpan +@lilypond[quote,verbatim] +\relative { + \override TextSpanner.bound-details.left.text = + \markup { \upright "rit." } + b'1\startTextSpan c + e,\stopTextSpan +} @end lilypond The line style, as well as the text string, can be defined as an @@ -226,21 +233,28 @@ in @ref{Rehearsal marks}: @c \mark needs to be placed on a separate line (it's not @c attached to an object like \markup is). -vv -@lilypond[verbatim,quote,relative=2] -c4 -\mark "Allegro" -c c c +@lilypond[verbatim,quote] +\relative { + \mark "Verse" + c'2 g' + \bar "||" + \mark "Chorus" + g2 c, + \bar "|." +} @end lilypond This syntax makes it possible to put any text on a bar line; more complex text formatting may be added using a @code{\markup} block, as described in @ref{Formatting text}: -@lilypond[quote,verbatim,relative=1] -1 -\mark \markup { \italic { colla parte } } -2 -1 +@lilypond[quote,verbatim] +\relative { + 1 + \mark \markup { \italic { colla parte } } + 2 + 1 +} @end lilypond @noindent @@ -248,10 +262,12 @@ This syntax also allows to print special signs, like coda, segno or fermata, by specifying the appropriate symbol name as explained in @ref{Music notation inside markup}: -@lilypond[quote,verbatim,relative=2] -2 -\mark \markup { \musicglyph #"scripts.ufermata" } -1 +@lilypond[quote,verbatim] +\relative { + 2 + \mark \markup { \musicglyph #"scripts.ufermata" } + 1 +} @end lilypond @noindent @@ -261,22 +277,30 @@ bar, they can be placed above the bar line or between notes. When specified at a line break, the mark will be printed at the beginning of the next line. -@lilypond[quote,verbatim,relative=2] -\mark "Allegro" -c1 c -\mark "assai" \break -c c +@lilypond[quote,verbatim,ragged-right] +\relative c'' { + \mark "Allegro" + c1 c + \mark "assai" \break + c c +} @end lilypond +@funindex \markLengthOn +@funindex markLengthOn +@funindex \markLengthOff +@funindex markLengthOff + +@predefined +@code{\markLengthOn}, +@code{\markLengthOff}. +@endpredefined @snippets @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle] {printing-marks-at-the-end-of-a-line.ly} -@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle] -{aligning-marks-with-various-notation-objects.ly} - @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle] {printing-marks-on-every-staff.ly} @@ -416,14 +440,16 @@ contain nested expressions or markup commands, entered using the backslash @code{\} character. Such commands only affect the first following expression. -@lilypond[quote,verbatim,relative=2] -a1-\markup intenso -a2^\markup { poco \italic più forte } -c e1 -d2_\markup { \italic "string. assai" } -e -b1^\markup { \bold { molto \italic agitato } } -c +@lilypond[quote,verbatim] +\relative { + a'1-\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 @cindex special characters in markup mode @@ -441,10 +467,12 @@ will be printed verbatim without affecting the formatting of the text. Double quotation marks themselves may be printed by preceding them with backslashes. -@lilypond[quote,verbatim,relative=2] -a1^"\italic markup..." -a_\markup { \italic "... prints \"italic\" letters!" } -a a +@lilypond[quote,verbatim] +\relative { + a'1^"\italic markup..." + a_\markup { \italic "... prints \"italic\" letters!" } + a a +} @end lilypond To be treated as a distinct expression, a list of words needs to be @@ -453,11 +481,13 @@ expressions are defined affects how these expressions will be stacked, centered and aligned; in the following example, the second @code{\markup} expression is treated the same as the first one: -@lilypond[quote,verbatim,relative=2] -c1^\markup { \center-column { a bbb c } } -c1^\markup { \center-column { a { bbb c } } } -c1^\markup { \center-column { a \line { bbb c } } } -c1^\markup { \center-column { a "bbb c" } } +@lilypond[quote,verbatim] +\relative c'' { + c1^\markup { \center-column { a bbb c } } + c1^\markup { \center-column { a { bbb c } } } + c1^\markup { \center-column { a \line { bbb c } } } + c1^\markup { \center-column { a "bbb c" } } +} @end lilypond Markups can be stored in variables. Such variables may be @@ -507,14 +537,16 @@ Syntax errors for markup mode can be confusing. Basic font switching is supported in markup mode: -@lilypond[quote,verbatim,relative=2] -d1^\markup { - \bold { Più mosso } - \italic { non troppo \underline Vivo } +@lilypond[quote,verbatim] +\relative { + d''1^\markup { + \bold { Più mosso } + \italic { non troppo \underline Vivo } + } + r2 r4 r8 + d,_\markup { \italic quasi \smallCaps Tromba } + f1 d2 r } -r2 r4 r8 -d,_\markup { \italic quasi \smallCaps Tromba } -f1 d2 r @end lilypond @cindex font size @@ -535,36 +567,53 @@ number of different ways It can be set to predefined size, -@lilypond[quote,verbatim,relative=2] -b1_\markup { \huge Sinfonia } -b1^\markup { \teeny da } -b1-\markup { \normalsize camera } +@lilypond[quote,verbatim] +\relative b' { + b1_\markup { \huge Sinfonia } + b1^\markup { \teeny da } + b1-\markup { \normalsize camera } +} @end lilypond It can be set relative to its previous value, -@lilypond[quote,verbatim,relative=2] -b1_\markup { \larger Sinfonia } -b1^\markup { \smaller da } -b1-\markup { \magnify #0.6 camera } +@lilypond[quote,verbatim] +\relative b' { + b1_\markup { \larger Sinfonia } + b1^\markup { \smaller da } + b1-\markup { \magnify #0.6 camera } +} @end lilypond It can be increased or decreased relative to the value set by the global staff size, -@lilypond[quote,verbatim,relative=2] -b1_\markup { \fontsize #-2 Sinfonia } -b1^\markup { \fontsize #1 da } -b1-\markup { \fontsize #3 camera } +@lilypond[quote,verbatim] +\relative b' { + b1_\markup { \fontsize #-2 Sinfonia } + b1^\markup { \fontsize #1 da } + b1-\markup { \fontsize #3 camera } +} @end lilypond It can also be set to a fixed point-size, regardless of the global staff size, -@lilypond[quote,verbatim,relative=2] -b1_\markup { \abs-fontsize #20 Sinfonia } -b1^\markup { \abs-fontsize #8 da } -b1-\markup { \abs-fontsize #14 camera } +@lilypond[quote,verbatim] +\relative b' { + b1_\markup { \abs-fontsize #20 Sinfonia } + b1^\markup { \abs-fontsize #8 da } + b1-\markup { \abs-fontsize #14 camera } +} +@end lilypond + +If the text includes spaces, then it is best to put it all inside quote +marks, so that the size of each space is appropriate for the size of the +other characters. + +@lilypond[quote,verbatim] +\markup \fontsize #6 \bold { Sinfonia da camera } +\markup \fontsize #6 \bold { "Sinfonia da camera" } @end lilypond @cindex subscript @@ -724,14 +773,16 @@ Markup objects may be aligned in different ways. By default, a text indication is aligned on its left edge: in the following example, there is no difference between the first and the second markup. -@lilypond[quote,verbatim,relative=2] -d1-\markup { poco } -f -d-\markup { \left-align poco } -f -d-\markup { \center-align { poco } } -f -d-\markup { \right-align poco } +@lilypond[quote,verbatim] +\relative { + d''1-\markup { poco } + f + d-\markup { \left-align poco } + f + d-\markup { \center-align { poco } } + f + d-\markup { \right-align poco } +} @end lilypond @funindex \halign @@ -739,14 +790,16 @@ d-\markup { \right-align poco } Horizontal alignment may be fine-tuned using a numeric value: -@lilypond[quote,verbatim,relative=2] -a1-\markup { \halign #-1 poco } -e' -a,-\markup { \halign #0 poco } -e' -a,-\markup { \halign #0.5 poco } -e' -a,-\markup { \halign #2 poco } +@lilypond[quote,verbatim] +\relative { + a'1-\markup { \halign #-1 poco } + e' + a,-\markup { \halign #0 poco } + e' + a,-\markup { \halign #0.5 poco } + e' + a,-\markup { \halign #2 poco } +} @end lilypond @noindent @@ -775,21 +828,23 @@ another markup element or an invisible object. The following example demonstrates these two possibilities; the last markup in this example has no anchor point, and therefore is not moved. -@lilypond[quote,verbatim,relative=1] -d2^\markup { - Acte I - \raise #2 { Scène 1 } -} -a' -g_\markup { - \null - \lower #4 \bold { Très modéré } -} -a -d,^\markup { - \raise #4 \italic { Une forêt. } +@lilypond[quote,verbatim] +\relative { + d'2^\markup { + Acte I + \raise #2 { Scène 1 } + } + a' + g_\markup { + \null + \lower #4 \bold { Très modéré } + } + a + d,^\markup { + \raise #4 \italic { Une forêt. } + } + a'4 a g2 a } -a'4 a g2 a @end lilypond @funindex \general-align @@ -803,22 +858,24 @@ Some commands can affect both the horizontal and vertical alignment of text objects in markup mode. Any object affected by these commands must be preceded with an anchor point: -@lilypond[quote,verbatim,relative=1] -d2^\markup { - Acte I - \translate #'(-1 . 2) "Scène 1" -} -a' -g_\markup { - \null - \general-align #Y #3.2 \bold "Très modéré" -} -a -d,^\markup { - \null - \translate-scaled #'(-1 . 2) \teeny "Une forêt." +@lilypond[quote,verbatim] +\relative { + d'2^\markup { + Acte I + \translate #'(-1 . 2) "Scène 1" + } + a' + g_\markup { + \null + \general-align #Y #3.2 \bold "Très modéré" + } + a + d,^\markup { + \null + \translate-scaled #'(-1 . 2) \teeny "Une forêt." + } + a'4 a g2 a } -a'4 a g2 a @end lilypond @cindex multi-line markup @@ -1091,8 +1148,8 @@ image files converted to the Encapsulated PostScript format native PostScript code. In such a case, it may be useful to explicitly specify the size of the drawing, as demonstrated below: -@lilypond[quote,verbatim,relative=1] -c1^\markup { +@lilypond[quote,verbatim,fragment] +c'1^\markup { \combine \epsfile #X #10 #"./context-example.eps" \with-dimensions #'(0 . 6) #'(0 . 10) @@ -1108,7 +1165,7 @@ c1^\markup { closepath stroke" } -c +c' @end lilypond An exhaustive list of graphics-specific commands can be found in @@ -1116,9 +1173,10 @@ An exhaustive list of graphics-specific commands can be found in @seealso Notation Reference: -@ref{Graphic}, +@ref{Align}, +@ref{Dimensions}, @ref{Editorial annotations}, -@ref{Align}. +@ref{Graphic}. Installed Files: @file{scm/define-markup-commands.scm}, @@ -1143,42 +1201,40 @@ markup object. Notes and accidentals can be entered using markup commands: -@lilypond[quote,verbatim,relative=2] -a2 a^\markup { +@lilypond[quote,verbatim,fragment] +a'2 a'^\markup { \note #"4" #1 = \note-by-number #1 #1 #1.5 } -b1_\markup { +b'1_\markup { \natural \semiflat \flat \sesquiflat \doubleflat } \glissando -a1_\markup { +a'1_\markup { \natural \semisharp \sharp \sesquisharp \doublesharp } -\glissando b +\glissando b' @end lilypond Other notation objects may also be printed in markup mode: -@lilypond[quote,verbatim,relative=1] -g1 bes -ees-\markup { - \finger 4 - \tied-lyric #"~" - \finger 1 -} -fis_\markup { \dynamic rf } -bes^\markup { - \beam #8 #0.1 #0.5 -} -cis -d-\markup { - \markalphabet #8 - \markletter #8 +@lilypond[quote,verbatim] +\relative { + g1 bes + ees\finger \markup \tied-lyric #"4~1" + fis_\markup { \dynamic rf } + bes^\markup { + \beam #8 #0.1 #0.5 + } + cis + d-\markup { + \markalphabet #8 + \markletter #8 + } } @end lilypond @@ -1187,13 +1243,15 @@ 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,relative=2] -c2 -c'^\markup { \musicglyph #"eight" } -c,4 -c,8._\markup { \musicglyph #"clefs.G_change" } -c16 -c2^\markup { \musicglyph #"timesig.neomensural94" } +@lilypond[quote,verbatim] +\relative { + c''2 + c'^\markup { \musicglyph #"eight" } + c,4 + c,8._\markup { \musicglyph #"clefs.G_change" } + c16 + c2^\markup { \musicglyph #"timesig.neomensural94" } +} @end lilypond Another way of printing non-text glyphs is described in @@ -1203,20 +1261,22 @@ sizes. The markup mode also supports diagrams for specific instruments: -@lilypond[quote,verbatim,relative=2] -c1^\markup { - \fret-diagram-terse #"x;x;o;2;3;2;" -} -c^\markup { - \harp-pedal #"^-v|--ov^" -} -c -c^\markup { - \combine - \musicglyph #"accordion.discant" +@lilypond[quote,verbatim] +\relative { + c''1^\markup { + \fret-diagram-terse #"x;x;o;2;3;2;" + } + c^\markup { + \harp-pedal #"^-v|--ov^" + } + c + c^\markup { \combine - \raise #0.5 \musicglyph #"accordion.dot" - \raise #1.5 \musicglyph #"accordion.dot" + \musicglyph #"accordion.discant" + \combine + \raise #0.5 \musicglyph #"accordion.dot" + \raise #1.5 \musicglyph #"accordion.dot" + } } @end lilypond @@ -1232,15 +1292,17 @@ A whole score can even be nested inside a markup object. In such a case, the nested @code{\score} block must contain a @code{\layout} block, as demonstrated here: -@lilypond[quote,verbatim,relative=1] -c4 d^\markup { - \score { - \relative c' { c4 d e f } - \layout { } +@lilypond[quote,verbatim] +\relative { + c'4 d^\markup { + \score { + \relative { c'4 d e f } + \layout { } + } } + e f | + c d e f } -e f | -c d e f @end lilypond An exhaustive list of music notation related commands can be found in @@ -1366,8 +1428,8 @@ ordered in several families. The following syntax allows various LilyPond @code{feta} non-text fonts to be used directly in markup mode: -@lilypond[quote,verbatim,relative=2] -a1^\markup { +@lilypond[quote,verbatim,fragment] +a'1^\markup { \vcenter { \override #'(font-encoding . fetaBraces) \lookup #"brace120" @@ -1392,24 +1454,32 @@ value must be determined by trial and error. These glyphs are all left braces; right braces may be obtained by rotation, see @ref{Rotating objects}. -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. +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 Each family may include different shapes and series. The following example demonstrates the ability to select alternate families, shapes, series and sizes. The value supplied to @code{font-size} is the required change from the default size. -@lilypond[quote,verbatim,relative=2] -\override Score.RehearsalMark #'font-family = #'typewriter +@lilypond[quote,verbatim,fragment] +\override Score.RehearsalMark.font-family = #'typewriter \mark \markup "Ouverture" -\override Voice.TextScript #'font-shape = #'italic -\override Voice.TextScript #'font-series = #'bold -d2.^\markup "Allegro" -\override Voice.TextScript #'font-size = #-3 -c4^smaller +\override Voice.TextScript.font-shape = #'italic +\override Voice.TextScript.font-series = #'bold +d''2.^\markup "Allegro" +\override Voice.TextScript.font-size = #-3 +c''4^smaller @end lilypond @noindent @@ -1458,14 +1528,14 @@ Notation Reference: Any font that is installed on the operating system and recognized by FontConfig may be used in a score, using the following syntax: -@lilypond[quote,verbatim,relative=2] -\override Staff.TimeSignature #'font-name = #"Bitstream Charter" -\override Staff.TimeSignature #'font-size = #2 +@lilypond[quote,verbatim,fragment] +\override Staff.TimeSignature.font-name = #"Bitstream Charter" +\override Staff.TimeSignature.font-size = #2 \time 3/4 -a1_\markup { - \override #'(font-name . "Vera Bold") - { Vera Bold } +a'1_\markup { + \override #'(font-name . "Bitstream Vera Sans,sans-serif, Oblique Bold") + { Vera Oblique Bold } } @end lilypond @@ -1474,10 +1544,16 @@ a1_\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 -The following command displays a list of all available fonts on the -operating system: +Running lilypond with the following option displays a list of all +available fonts on the operating system: @example lilypond -dshow-available-fonts x @@ -1501,8 +1577,11 @@ Snippets: 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. For an -explanation of fonts, see @ref{Fonts explained}. +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. 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 @@ -1511,12 +1590,11 @@ explanation of fonts, see @ref{Fonts explained}. @lilypond[verbatim,quote] \paper { - myStaffSize = #20 #(define fonts (make-pango-font-tree "Times New Roman" - "Nimbus Sans" + "Nimbus Sans,Nimbus Sans L" "Luxi Mono" - (/ myStaffSize 20))) + (/ staff-height pt 20))) } \relative c'{