X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftext.itely;h=43f4e942278624dff03208331c3bac84febbc0e2;hb=b486cb8f17cf0281a20e0a7e5fa1afd5226f19a8;hp=90860e00de846b46ac0967f1659d0578464a5ea2;hpb=de7ce41c15df0f6bf78fda51b4ba95e31b50afb3;p=lilypond.git diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely index 90860e00de..43f4e94227 100644 --- a/Documentation/user/text.itely +++ b/Documentation/user/text.itely @@ -6,13 +6,20 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.51" + @node Text @section Text @lilypondfile[quote]{text-headword.ly} This section explains how to include text (with various -formatting) in your scores. +formatting) in music scores. + +@noindent +Some text elements that are not dealt with here are discussed in other +specific sections: @ref{Vocal music}, @ref{Titles and headers}. + @cindex Text, other languages @warning{To write accented and special text (such as characters @@ -22,68 +29,23 @@ information, see @ref{Text encoding}.} @menu * Writing text:: -* Text markup:: -* Special text concerns:: +* Formatting text:: +* Fonts:: @end menu @node Writing text @subsection Writing text +This section introduces different ways of adding text to a score. + @menu -* Overview of text entry:: * Text scripts:: * Text spanners:: * Text marks:: +* Separate text:: @end menu -@node Overview of text entry -@subsubsection Overview of text entry - -There are four ways to add text to scores: - -@itemize -@item -@ref{Text scripts}: blah blah - -@lilypond[verbatim,quote,ragged-right,fragment,relative=2] -c4^"text" c c c -@end lilypond - -@item -@ref{Text spanners}: blah blah - -@lilypond[verbatim,quote,ragged-right,fragment,relative=2] -c1 -\override TextSpanner #'bound-details #'left #'text = - \markup { \upright "rall" } -c2\startTextSpan b c\stopTextSpan a -@end lilypond - -@item -@ref{Text marks}: blah blah - -@lilypond[verbatim,quote,ragged-right,fragment,relative=2] -c4\mark "foo" c c c -@end lilypond - -@item -@ref{Vocal music}: blah blah, not in this section. - -@lilypond[verbatim,quote,ragged-right] -<< - \relative c'' { c4 c c c } - \addlyrics { one two three four } ->> -@end lilypond - -@end itemize - -@seealso - -Snippets: @lsrdir{Text,Text} - - @node Text scripts @subsubsection Text scripts @@ -91,22 +53,22 @@ Snippets: @lsrdir{Text,Text} @cindex Text scripts @cindex text items, non-empty @cindex non-empty texts +@cindex quoted text -It is possible to add arbitrary text indications with -@var{note}@code{-"}@var{text}@code{"}. -Such indications can also be manually placed +Simple @q{quoted text} indications may be added +to a score, as demonstrated in the following example. +Such indications can be manually placed above or below the staff, using the -simple syntax described in @ref{Controlling direction and +syntax described in @ref{Direction and placement}. @lilypond[quote,fragment,ragged-right,verbatim,relative=1] d8^"pizz." e f g a4-"scherz." f @end lilypond -In LilyPond, such text strings are called @command{markup} -objects. This syntax is actually a shorthand; more complex text -formatting may be added to a note by explicitly using the -@code{\markup} command, as described in @ref{Text markup}. +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,fragment,ragged-right,verbatim,relative=1] d8^\markup { \italic pizz. } e f g @@ -119,7 +81,9 @@ in the following example, the first text string does not affect spacing, whereas the second one does. @lilypond[quote,fragment,ragged-right,verbatim,relative=1] -d8^"pizz." e f g \textLengthOn a4_"scherzando" f +d8^"pizz." e f g +\textLengthOn +a4_"scherzando" f @end lilypond @predefined @@ -127,16 +91,18 @@ d8^"pizz." e f g \textLengthOn a4_"scherzando" f @funindex \textLengthOn @code{\textLengthOn}, @funindex \textLengthOff -@code{\textLengthOff}. +@code{\textLengthOff} @seealso -Notation Reference: @ref{Text markup}. +Notation Reference: @ref{Formatting text}, +@ref{Direction and placement}. -Snippets: @lsrdir{Text,Text} +Snippets: +@rlsr{Text}. -Internals Reference: @internalsref{TextScript}. +Internals Reference: @rinternals{TextScript}. @knownissues @@ -155,13 +121,11 @@ default; to enable it, use @cindex Text spanners -@c TODO: merge these explanations with the ones below in -@c "Text and Line spanners" -vv - -Some performance indications, e.g., @i{rallentando} or -@i{accelerando}, are written as text and are extended over many -measures with dotted lines; you can create such text spanners -from one note to another by using the following syntax: +Some performance indications, e.g., @notation{rallentando} or +@notation{accelerando}, are written as text and are extended over +multiple notes with dotted lines. +Such objects, called @q{spanners}, may be created +from one note to another using the following syntax: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] \override TextSpanner #'bound-details #'left #'text = "rit." @@ -171,9 +135,9 @@ e,\stopTextSpan @noindent The string to be printed is set through -object properties. By default it is printed in italic characters, +object properties. By default it is printed in italic characters, but different formatting can be obtained using -@code{\markup} blocks: +@code{\markup} blocks, as described in @ref{Formatting text}. @lilypond[quote,ragged-right,fragment,relative=2,verbatim] \override TextSpanner #'bound-details #'left #'text = @@ -182,6 +146,9 @@ b1\startTextSpan c e,\stopTextSpan @end lilypond +The line style, as well as the text string, can be defined as an +object property. This syntax is described in @ref{Line styles}. + @predefined @funindex textSpannerUp @@ -189,17 +156,16 @@ e,\stopTextSpan @funindex textSpannerDown @code{\textSpannerDown}, @funindex textSpannerNeutral -@code{\textSpannerNeutral}. - -The line style, as well as the text string, can be defined as an -object property, as described in @ref{Line styles}. - +@code{\textSpannerNeutral} @seealso -Snippets: @lsrdir{Text,Text} +Notation Reference: @ref{Line styles}. + +Snippets: +@rlsr{Text}. -Internals Reference: @internalsref{TextSpanner}. +Internals Reference: @rinternals{TextSpanner}. @node Text marks @@ -214,165 +180,152 @@ Internals Reference: @internalsref{TextSpanner}. Various text elements can be added to a score using the syntax described 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,ragged-right,fragment,relative=2] -c4\mark "dolce" c c c +c4 +\mark "Allegro" +c c c @end lilypond -This syntax makes possible to put any text on a bar line, but also -signs like coda, segno, or fermata, by specifying the appropriate -symbol name. These symbols are listed in @ref{The Feta font}. +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}. This can be used to print +signs like coda, segno or fermata, by specifying the appropriate +symbol name: @lilypond[fragment,quote,ragged-right,verbatim,relative=2] -c1 \mark \markup { \musicglyph #"scripts.ufermata" } +c1 +\mark \markup { \musicglyph #"scripts.ufermata" } c1 @end lilypond @noindent -Such objects are only typeset above the top staff of the score; they -can be placed above the bar line or between notes, depending on whether -you specify it at the end or the middle of a bar. When specified at the -beginning of a score or at a line break, the mark will be printed at +Such objects are only typeset above the top staff of the score; depending on +whether they are specified at the end or the middle of a bar, they +can be placed above the bar line or between notes. When specified at the +beginning of a score or at a line break, marks will be printed at the beginning of the line (the next line, in case of a line break). @lilypond[fragment,quote,ragged-right,verbatim,relative=2] -\mark "dolce" c1 -c\mark "assai" \break -c c +\mark "Allegro" +c1 c +\mark "assai" \break +c c @end lilypond @snippets -@c TODO: to be LSR-ized stuff -vv +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{printing-marks-at-the-end-of-a-line-or-a-score.ly} -To print the mark at the end of the current line, use +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{aligning-marks-with-various-notation-objects.ly} -@example -\override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible -@end example +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{printing-marks-on-every-staff.ly} -@code{\mark} is often useful for adding text to the end of bar. -In such cases, changing the @code{#'self-alignment} is very useful +@seealso -@lilypond[fragment,quote,ragged-right,verbatim,relative=2] -\override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible -c1 c c c4 c c c -\once \override Score.RehearsalMark #'self-alignment-X = #right -\mark "D.S. al Fine " -@end lilypond +Notation Reference: @ref{Rehearsal marks}, +@ref{Formatting text}, @ref{The Feta font}. -If specified, text marks may be aligned with notation objects -other than bar lines. These objects include @code{ambitus}, -@code{breathing-sign}, @code{clef}, @code{custos}, -@code{staff-bar}, @code{left-edge}, @code{key-cancellation}, -@code{key-signature}, and @code{time-signature}. - - -In such cases, text marks will be, by default, horizontally centered -above the object. However, this can be changed, as demonstrated -on the second line of this example (in a score with multiple staves, -this setting should be done for all the staves). - - -@lilypond[fragment,quote,ragged-right,verbatim,relative=1] - e1 - - % the RehearsalMark will be centered above the Clef - \override Score.RehearsalMark #'break-align-symbols = #'(clef) - \key a \major - \clef treble - \mark "↓" - e - - % the RehearsalMark will be centered above the TimeSignature - \override Score.RehearsalMark #'break-align-symbols = #'(time-signature) - \key a \major - \clef treble - \time 3/4 - \mark "↓" - e2. - - % the RehearsalMark will be centered above the KeySignature - \override Score.RehearsalMark #'break-align-symbols = #'(key-signature) - \key a \major - \clef treble - \time 4/4 - \mark "↓" - e1 - - \break - e - - % the RehearsalMark will be aligned with the left edge of the KeySignature - \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT - \mark "↓" - \key a \major - e - - % the RehearsalMark will be aligned with the right edge of the KeySignature - \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT - \key a \major - \mark "↓" - e - - % the RehearsalMark will be aligned with the left edge of the KeySignature - % and then shifted right by 1 unit. - \once \override Score.KeySignature #'break-align-anchor = #1 - \key a \major - \mark "↓" - e1 +Snippets: +@rlsr{Text}. + +Internals Reference: @rinternals{RehearsalMark}. + +@knownissues +@c To be removed when Issue 69 in the tracker gets fixed. -vv + +If a mark is entered at the end of the last bar of the score (where +there is no next line), then the mark will not be printed at +all. + +@node Separate text +@subsubsection Separate text + +@cindex separate text +@cindex standalone text +@cindex top-level text +@cindex text, standalone +@funindex \markup + +A @code{\markup} block can exist by itself, outside of any +any @code{\score} block, as a @qq{top-level +expression}. This syntax is described in @ref{File structure}. + +@lilypond[verbatim,quote] +\markup { + Tomorrow, and tomorrow, and tomorrow... +} @end lilypond -Although text marks are normally only printed above the topmost -staff, you may alter this to print them on every staff, +@noindent +This allows printing text separately +from the music, which is particularly +useful when the input file contains +several music pieces, as described in +@ref{Multiple scores in a book}. -@lilypond[quote,ragged-right,verbatim,relative=2] -{ - \new Score \with { - \remove "Mark_engraver" - } - << - \new Staff \with { - \consists "Mark_engraver" - } - { c''1 \mark "foo" c'' } - \new Staff \with { - \consists "Mark_engraver" - } - { c'1 \mark "foo" c' } - >> +@lilypond[quote,ragged-right,verbatim] +\score { + c'1 +} +\markup { + Tomorrow, and tomorrow, and tomorrow... +} +\score { + c'1 } @end lilypond +Using a specific syntax, text blocks can be spread +over multiple pages, making possible to print +text documents or books -- and therefore to +use LilyPond as a word processor. This syntax is described in +@ref{Multi-page markup}. + +@predefined + +@code{\markup}, +@funindex \markuplines +@code{\markuplines} + +@ignore +@snippets + +TODO: add convenient snippets in input/new -vv +@end ignore @seealso -Snippets: @lsrdir{Text,Text} +Notation Reference: @ref{Formatting text}, +@ref{File structure}, +@ref{Multiple scores in a book}, +@ref{Multi-page markup}. -Internals Reference: @internalsref{RehearsalMark}. +Snippets: +@rlsr{Text}. -@knownissues -@c IMO this is a bug; hopefully it'll be fixed soon, so I can -@c delete this sentence. -gp +Internals Reference: @rinternals{TextScript}. -If a mark is entered at the end of the last bar of the score (where -there is no next line), then the mark will not be printed at -all. -@c TODO: add this here? -vv -@c @node Text marks -@c @subsubsection Text marks +@node Formatting text +@subsection Formatting text -@node Text markup -@subsection Text markup +This section presents basic and advanced text formatting, +using the @code{\markup} mode specific syntax. @menu * Text markup introduction:: -* Nested scores:: -* Page wrapping text:: -* Font selection:: +* Selecting font and font size:: +* Text alignment:: +* Graphic notation inside markup:: +* Music notation inside markup:: +* Multi-page markup:: @end menu @node Text markup introduction @@ -382,170 +335,531 @@ all. @cindex text markup @cindex markup text @cindex typeset text +@funindex \markup + +A @code{\markup} block is used to typeset text with an extensible +specific syntax called @qq{markup mode}. + +@cindex markup expressions +@cindex markup syntax + +The markup syntax is similar to LilyPond's usual syntax: a +@code{\markup} expression is enclosed in curly braces @code{@{ +@dots{} @}}. -Use @code{\markup} to typeset text. Commands are entered with the -backslash @code{\}. To enter @code{\} and @code{#}, use double -quotation marks. +Unlike simple @q{quoted text} indications, @code{\markup} blocks +may contain nested expressions or specific commands, +entered using the backslash @code{\} character. +Such commands only affect the first following expression. @lilypond[quote,verbatim,fragment,relative=1] -c1^\markup { hello } -c1_\markup { hi there } -c1^\markup { hi \bold there, is \italic {anyone home?} } -c1_\markup { "\special {weird} #characters" } +e1-\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 -@noindent -See @ref{Overview of text markup commands}, for a list of all -commands. +@cindex special characters in markup mode +@cindex markup mode, special characters +@cindex reserved characters, printing +@cindex printing special characters +@cindex quoted text in markup mode + +A @code{\markup} block may also contain quoted text, which +can be useful to print special characters such as @code{\} and @code{#}, +or even double quotation marks -- these have to be preceded +with backslashes: + +@lilypond[quote,verbatim,fragment,relative=1] +\clef bass +a^\markup "##\ LEPORELLO \##" +a_\markup "Bravi! \"Cosa rara\"!" +r a8 d +cis a r4 r2 +@end lilypond -@code{\markup} is primarily used for @internalsref{TextScript}s, -but it can also be used anywhere text is called in LilyPond +The way markup expressions are defined affects +how these expressions will stacked, centered and aligned +when using the commands explained in @ref{Text alignment}. + +@lilypond[quote,verbatim,fragment,relative=1] +c1^\markup { \column { a bbbb \line { c d } } } +c1^\markup { \center-align { a bbbb c } } +c1^\markup { \line { a b c } } +@end lilypond + +Lists of words that are not enclosed with double quotes +or preceded by a command are not treated as a distinct +expression. In the following example, the first two +@code{\markup} expressions are equivalent: + +@lilypond[quote,verbatim,fragment,relative=1] +c1^\markup { \center-align { a bbb c } } +c1^\markup { \center-align { a { bbb c } } } +c1^\markup { \center-align { a \line { bbb c } } } +@end lilypond + + +Markups can be stored in variables. These variables may be +directly attached to notes: @lilypond[quote,verbatim] -\header{ title = \markup{ \bold { foo \italic { bar! } } } } -\score{ - \relative c'' { - \override Score.RehearsalMark - #'break-visibility = #begin-of-line-invisible - \override Score.RehearsalMark #'self-alignment-X = #right - - \set Staff.instrumentName = \markup{ \column{ Alto solo } } - c2^\markup{ don't be \flat } - \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit } - b2\startTextSpan - a2\mark \markup{ \large \bold Fine } - r2\stopTextSpan - \bar "||" - } - \addlyrics { bar, foo \markup{ \italic bar! } } +allegro = \markup { \bold \large Allegro } + +{ + d''8.^\allegro + d'16 d'4 r2 } @end lilypond -A @code{\markup} command can also be placed on its own, away from -any @code{\score} block, see @ref{Multiple scores in a book}. -@lilypond[quote,ragged-right,verbatim] -\markup{ Here is some text. } -@end lilypond +@noindent +An exhaustive list of @code{\markup}-specific commands can be found in +@ref{Text markup commands}. + + +@seealso + +This manual: @ref{Text markup commands}. + +Snippets: +@rlsr{Text}. + +Internals Reference: @rinternals{TextScript}. + +Init files: @file{scm/@/new@/-markup@/.scm}. + + +@knownissues + +Syntax errors for markup mode can be confusing. + + +@node Selecting font and font size +@subsubsection Selecting font and font size @cindex font switching +@funindex \italic +@funindex \bold +@funindex \underline -The markup in the example demonstrates font switching commands. -The command @code{\bold} and @code{\italic} apply to the first -following word only; to apply a command to more than one word, -enclose the words with braces, +Basic font switching is supported in markup mode: -@example -\markup @{ \bold @{ hi there @} @} -@end example +@lilypond[quote,verbatim,relative=2] +{ + d1^\markup { + \bold { Più mosso } + \italic { non troppo \underline Vivo } + } + r2 r4 r8 + d,_\markup { \italic quasi \smallCaps Tromba } + f1 d2 r +} +@end lilypond + +@cindex font size +@cindex text size +@funindex \fontsize +@funindex \smaller +@funindex \larger +@funindex \bigger +@funindex \magnify + +The size of the characters can also be altered in different ways: +@itemize +@item +the font size can be defined to an absolute value, + +@item +predefined commands allow to easily select standard sizes, + +@item +the font size can also be changed relatively to its previous value. +@end itemize @noindent -For clarity, you can also do this for single arguments, e.g., +The following example demonstrates these three methods: -@example -\markup @{ is \italic @{ anyone @} home @} -@end example +@lilypond[quote,verbatim,relative=2] +{ + f1^\markup { \fontsize #5 Sinfonia } + a,_\markup { + \tiny espressivo + \large e + \normalsize intenso + } + bes^\markup { (con + \larger grande + \smaller emozione + \magnify #0.6 { e sentimento } ) + } + d c2 r8 c bes a g1 +} +@end lilypond -In markup mode you can compose expressions, similar to -mathematical expressions, XML documents, and music expressions. -You can stack expressions grouped vertically with the command -@code{\column}. Similarly, @code{\center-align} aligns texts by -their center lines: +@cindex subscript +@cindex superscript +@funindex \super +@funindex \sub -@lilypond[quote,verbatim,fragment,relative=1] -c1^\markup { \column { a bbbb \line { c d } } } -c1^\markup { \center-align { a bbbb c } } -c1^\markup { \line { a b c } } +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: + +@lilypond[quote,verbatim] +\markup { + \column { + \line { 1 \super st movement } + \line { 1 \normal-size-super st movement + \sub { (part two) } } + } +} @end lilypond -Lists with no previous command are not kept distinct. The -expression +@cindex font families -@example -\center-align @{ @{ a b @} @{ c d @} @} -@end example +The markup mode provides an easy way to select alternate +font families. The default serif font, of roman type, is +automatically selected unless specified otherwise: on the +last line of the following example, there is no difference +between the first and the second word. + +@lilypond[quote,verbatim] +\markup { + \column { + \line { Act \number 1 } + \line { \sans { Scene I. } } + \line { \typewriter { Verona. An open place. } } + \line { Enter \roman Valentine and Proteus. } + } +} +@end lilypond @noindent +Some of these font families, used for specific items +such as numbers or dynamics, do not provide all +characters, as mentioned in @ref{New dynamic marks} and +@ref{Manual repeat marks}. -is equivalent to +@c \concat is actually documented in Align (it is not +@c a font-switching command). But we need it here. -vv -@example -\center-align @{ a b c d @} -@end example +When used inside a word, some font-switching or formatting +commands may produce an unwanted blank space. This can +easily be solved by concatenating the text elements together: -@noindent +@lilypond[quote,verbatim] +\markup { + \column { + \line { + \concat { 1 \super st } + movement + } + \line { + \concat { \dynamic p , } + \italic { con dolce espressione } + } + } +} +@end lilypond + +An exhaustive list of font-switching, font-size +and font-families related commands can be found in @ref{Font}. -To keep lists of words distinct, please use quotes @code{"} or -the @code{\line} command +Defining custom font sets is also possible, as explained in +@ref{Fonts}. + +@predefined + +@funindex \teeny +@funindex \tiny +@funindex \small +@funindex \normalsize +@funindex \large +@funindex \huge +@code{\teeny}, +@code{\tiny}, +@code{\small}, +@code{\normalsize}, +@code{\large}, +@code{\huge}. + +@c TODO: add @seealso + + +@node Text alignment +@subsubsection Text alignment + +@cindex text, aligning +@cindex aligning text + +This subsection discusses how to place text in markup mode, +inside a @code{\markup} block. Markup objects can also +be moved as a whole, using the syntax described in +@rlearning{Moving objects}. + +@c The padding commands should be mentioned on this page, but +@c most of these require \box to be more clearly illustrated. -vv + +@cindex text, horizontal alignment +@cindex horizontal text alignment +@funindex \left-align +@funindex \hcenter +@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, there's no difference +between the first and the second markup. @lilypond[quote,verbatim,fragment,relative=1] -\textLengthOn -c4^\markup{ \center-align { on three lines } } -c4^\markup{ \center-align { "all one line" } } -c4^\markup{ \center-align { { on three lines } } } -c4^\markup{ \center-align { \line { on one line } } } +a1-\markup { poco } +e' +a,-\markup { \left-align poco } +e' +a,-\markup { \hcenter { poco } } +e' +a,-\markup { \right-align poco } @end lilypond -Markups can be stored in variables and these variables may be -attached to notes, like +@funindex \halign -@example -allegro = \markup @{ \bold \large @{ Allegro @} @} - @{ a^\allegro b c d @} -@end example +The horizontal alignment may be fine-tuned +using a numeric value: -Some objects have alignment procedures of their own, which cancel -out any effects of alignments applied to their markup arguments as -a whole. For example, the @internalsref{RehearsalMark} is -horizontally centered, so using @code{\mark \markup @{ \left-align -.. @}} has no effect. +@lilypond[quote,verbatim,fragment,relative=1] +a1-\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 -In addition, vertical placement is performed after creating the -text markup object. If you wish to move an entire piece of -markup, you need to use the #'padding property or create an -@q{anchor} point inside the markup (generally with @code{\hspace -#0}). +@noindent +Some objects may have alignment procedures of their own, +and therefore are not affected by these commands. It is +possible to move such markup objects as a whole, as shown +for instance in @ref{Text marks}, + +@cindex text, vertical alignment +@cindex vertical text alignment +@funindex \raise +@funindex \lower + +Vertical alignment is a bit more complex. As stated above, +markup objects can be moved as a whole; however, it is also +possible to move specific elements inside a markup block. +In this case, the element to be moved needs to be preceded +with an @emph{anchor point}, that can be 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,fragment,relative=1] -\textLengthOn -c'4^\markup{ \raise #5 "not raised" } -\once \override TextScript #'padding = #3 -c'4^\markup{ raised } -c'4^\markup{ \hspace #0 \raise #1.5 raised } +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. } } +a'4 a g2 a @end lilypond -Some situations (such as dynamic marks) have preset font-related -properties. If you are creating text in such situations, it is -advisable to cancel those properties with @code{normal-text}. See -@ref{Overview of text markup commands}, for more details. +@funindex \general-align +@funindex \translate +@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 must be preceded with an +anchor point: -@seealso +@lilypond[quote,verbatim,fragment,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." } +a'4 a g2 a +@end lilypond -This manual: @ref{Overview of text markup commands}. +@cindex multi-line markup +@cindex multi-line text +@cindex columns, text -Snippets: @lsrdir{Text,Text} +A markup object may include several lines of text. +In the following example, each element or expression +is placed on its own line, either left-aligned or centered: -Internals Reference: @internalsref{TextScript}. +@lilypond[quote,verbatim] +\markup { + \column { + a + "b c" + \line { d e f } + } + \hspace #10 + \center-align { + a + "b c" + \line { d e f } + } +} +@end lilypond -Init files: @file{scm/@/new@/-markup@/.scm}. +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 centered on the page. +These expressions can, in turn, include multi-line text +or any other markup expression: +@lilypond[quote,verbatim] +\markup { + \fill-line { + \line { William S. Gilbert } + \center-align { + \huge \smallCaps "The Mikado" + or + \smallCaps "The Town of Titipu" + } + \line { Sir Arthur Sullivan } + } +} +\markup { + \fill-line { 1885 } +} +@end lilypond -@knownissues +Long text indications can also be automatically wrapped +accordingly to the given line width. These will be +either left-aligned or justified, as shown in +the following example. + +@lilypond[quote,verbatim] +\markup { + \column { + \line \smallCaps { La vida breve } + \line \bold { Acto I } + \wordwrap \italic { + (La escena representa el corral de una casa de + gitanos en el Albaicín de Granada. Al fondo una + puerta por la que se vé el negro interior de + una Fragua, iluminado por los rojos resplandores + del fuego.) + } + \hspace #0 + + \line \bold { Acto II } + \override #'(line-width . 50) + \justify \italic { + (Calle de Granada. Fachada de la casa de Carmela + y su hermano Manuel con grandes ventanas abiertas + a través de las que se ve el patio + donde se celebra una alegre fiesta) + } + } +} +@end lilypond + +An exhaustive list of text alignment commands +can be found in @ref{Align}. + +@c TODO: add @seealso + +@node Graphic notation inside markup +@subsubsection Graphic notation inside markup + +Graphics around text: +\box +\circle + +(TODO: document padding commands here) + +\bracket +\hbracket + +"Standalone" graphics: + +\arrow-head +\draw-line +\draw-circle +\filled-box +\triangle +\strut + +\with-color + + +Advanced graphics: +\stencil -Kerning or generation of ligatures is only done when the @TeX{} -backend is used. In this case, LilyPond does not account for them -so texts will be spaced slightly too wide. +\postscript +\epsfile -Syntax errors for markup mode are confusing. +\with-dimensions +@node Music notation inside markup +@subsubsection Music notation inside markup -@node Nested scores -@subsubsection Nested scores +Notes can be printed in markup mode blah blah: + +\note +\note-by-number + +Accidental symbols can be obtained easily: + +\doubleflat +\sesquiflat +\flat +\semiflat +\natural +\semisharp +\sharp +\sesquisharp +\doublesharp + +Some other notation objects blah blah + +\beam +\finger +\dynamic +\tied-lyric +\markalphabet +\markletter +@c TODO: add \text here? -vv + +Any musical symbol can be printed + +\musicglyph +@c TODO: add \lookup here? -vv + + +The markup mode has support for fret diagrams: + +\fret-diagram +\fret-diagram-terse +\fret-diagram-verbose + +An entire @code{\score} block can even be nested in a @code{\markup} +block. In such a case, the @code{\score} must contain a @code{\layout} block. + + +\score -It is possible to nest music inside markups, by adding a -@code{\score} block to a markup expression. Such a score must -contain a @code{\layout} block. @lilypond[quote,verbatim,ragged-right] \relative { @@ -561,10 +875,11 @@ contain a @code{\layout} block. @seealso -Snippets: @lsrdir{Text,Text} +Snippets: +@rlsr{Text}. -@node Page wrapping text -@subsubsection Page wrapping text +@node Multi-page markup +@subsubsection Multi-page markup Whereas @code{\markup} is used to enter a non-breakable block of text, @code{\markuplines} can be used at top-level to enter lines @@ -587,22 +902,65 @@ of text that can spread over multiple pages: @code{\markuplines} accepts a list of markup, that is either the result of a markup list command, or a list of markups or of markup lists. The built-in markup list commands are described in -@ref{Overview of text markup list commands}. +@ref{Text markup list commands}. @seealso -This manual: @ref{Overview of text markup list commands}, @ref{New +This manual: @ref{Text markup list commands}, @ref{New markup list command definition}. -Snippets: @lsrdir{Text,Text} +Snippets: +@rlsr{Text}. @predefined @funindex \markuplines @code{\markuplines} -@node Font selection -@subsubsection Font selection + +@node Fonts +@subsection Fonts + +@menu +* Entire document fonts:: +* Single entry 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, + +@cindex font families, setting +@cindex Pango + + +@lilypond[verbatim] +\paper { + myStaffSize = #20 + + #(define fonts + (make-pango-font-tree "Times New Roman" + "Nimbus Sans" + "Luxi Mono" + (/ myStaffSize 20))) +} + +{ + c'^\markup { roman: foo \sans bla \typewriter bar } +} +@end lilypond + +@c we don't do Helvetica / Courier, since GS incorrectly loads +@c Apple TTF fonts + + +@node Single entry fonts +@subsubsection Single entry fonts @cindex font selection @cindex font magnification @@ -679,94 +1037,11 @@ property. The resulting size is taken relative to the @cindex font magnification -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, - -@cindex font families, setting -@cindex Pango - -@lilypond[verbatim] -\paper { - myStaffSize = #20 - - #(define fonts - (make-pango-font-tree "Times New Roman" - "Nimbus Sans" - "Luxi Mono" - (/ myStaffSize 20))) -} - -{ - c'^\markup { roman: foo \sans bla \typewriter bar } -} -@end lilypond - -@c we don't do Helvetica / Courier, since GS incorrectly loads -@c Apple TTF fonts - - - -@seealso - -Snippets: @lsrdir{Text,Text} - - -@node Special text concerns -@subsection Special text concerns - -@c FIXME: this section is to be removed -@c (see comments below) -vv - -@menu -* New dynamic marks:: -* Text and line spanners:: -@end menu - -@node New dynamic marks -@subsubsection New dynamic marks - -@c FIXME: this whole section should be removed and put in -@c "Writing text" -vv - -It is possible to print new dynamic marks or text that should be -aligned with dynamics. Use @code{make-dynamic-script} to create -these marks. Note that the dynamic font only contains the -characters @code{f,m,p,r,s} and @code{z}. - -Some situations (such as dynamic marks) have preset font-related -properties. If you are creating text in such situations, it is -advisable to cancel those properties with @code{normal-text}. See -@ref{Overview of text markup commands}, for more details. - -@cindex make-dynamic-script - -@lilypond[quote,verbatim,ragged-right] -sfzp = #(make-dynamic-script "sfzp") -\relative c' { - c4 c c\sfzp c -} -@end lilypond - -@cindex Dynamics, editorial -@cindex Dynamics, parenthesis - -It is also possible to print dynamics in round parenthesis or -square brackets. These are often used for adding editorial -dynamics. - -@lilypond[quote,verbatim,ragged-right] -rndf = \markup{ \center-align {\line { \bold{\italic (} - \dynamic f \bold{\italic )} }} } -boxf = \markup{ \bracket { \dynamic f } } -{ c'1_\rndf c'1_\boxf } -@end lilypond @seealso -Snippets: @lsrdir{Text,Text} +Snippets: +@rlsr{Text}.