X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftext.itely;h=43f4e942278624dff03208331c3bac84febbc0e2;hb=7ffb44d7dbcd7bcf66ab0b0ef64515af416f3709;hp=8fef6bef56add10b697969fac9c7223164b22bb1;hpb=24d7a2abc788061a4f7a81ee3c2a9f330ddca93f;p=lilypond.git diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely index 8fef6bef56..43f4e94227 100644 --- a/Documentation/user/text.itely +++ b/Documentation/user/text.itely @@ -6,7 +6,7 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.38" +@c \version "2.11.51" @node Text @section Text @@ -53,20 +53,20 @@ This section introduces different ways of adding text to a score. @cindex Text scripts @cindex text items, non-empty @cindex non-empty texts +@cindex quoted text -It is possible to add arbitrary text indications +Simple @q{quoted text} indications may be added to a score, as demonstrated in the following example. -Such indications can also be manually placed +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 +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}. @@ -81,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 @@ -95,12 +97,12 @@ d8^"pizz." e f g \textLengthOn a4_"scherzando" f @seealso Notation Reference: @ref{Formatting text}, -@ref{Controlling direction and placement}. +@ref{Direction and placement}. Snippets: -@lsrdir{Text,Text} +@rlsr{Text}. -Internals Reference: @internalsref{TextScript}. +Internals Reference: @rinternals{TextScript}. @knownissues @@ -119,9 +121,9 @@ default; to enable it, use @cindex Text spanners -Some performance indications, e.g., @i{rallentando} or -@i{accelerando}, are written as text and are extended over many -measures with dotted lines. +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: @@ -161,9 +163,9 @@ object property. This syntax is described in @ref{Line styles}. Notation Reference: @ref{Line styles}. Snippets: -@lsrdir{Text,Text} +@rlsr{Text}. -Internals Reference: @internalsref{TextSpanner}. +Internals Reference: @rinternals{TextSpanner}. @node Text marks @@ -178,18 +180,24 @@ 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 "Allegro" c c c +c4 +\mark "Allegro" +c c c @end lilypond -This syntax makes possible to put any text on a bar line; +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 @@ -201,21 +209,22 @@ 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 "Allegro" c1 -c\mark "assai" \break -c c +\mark "Allegro" +c1 c +\mark "assai" \break +c c @end lilypond @snippets -@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] {printing-marks-at-the-end-of-a-line-or-a-score.ly} -@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] {aligning-marks-with-various-notation-objects.ly} -@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] {printing-marks-on-every-staff.ly} @seealso @@ -224,14 +233,12 @@ Notation Reference: @ref{Rehearsal marks}, @ref{Formatting text}, @ref{The Feta font}. Snippets: -@lsrdir{Text,Text} +@rlsr{Text}. -Internals Reference: @internalsref{RehearsalMark}. +Internals Reference: @rinternals{RehearsalMark}. @knownissues -@c IMO this is a bug; hopefully it'll be fixed soon, so I can -@c delete this sentence. -gp -@c A workaround is suggested in the first @snippets item -vv +@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 @@ -250,14 +257,14 @@ 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[quote,ragged-right,verbatim] +@lilypond[verbatim,quote] \markup { Tomorrow, and tomorrow, and tomorrow... } @end lilypond @noindent -This allows to print text separately +This allows printing text separately from the music, which is particularly useful when the input file contains several music pieces, as described in @@ -283,7 +290,6 @@ use LilyPond as a word processor. This syntax is described in @predefined -@funindex \markup @code{\markup}, @funindex \markuplines @code{\markuplines} @@ -302,9 +308,9 @@ Notation Reference: @ref{Formatting text}, @ref{Multi-page markup}. Snippets: -@lsrdir{Text,Text} +@rlsr{Text}. -Internals Reference: @internalsref{TextScript}. +Internals Reference: @rinternals{TextScript}. @node Formatting text @@ -315,7 +321,7 @@ using the @code{\markup} mode specific syntax. @menu * Text markup introduction:: -* Common markup commands:: +* Selecting font and font size:: * Text alignment:: * Graphic notation inside markup:: * Music notation inside markup:: @@ -329,72 +335,55 @@ using the @code{\markup} mode specific syntax. @cindex text markup @cindex markup text @cindex typeset text +@funindex \markup -A @code{\markup} block is used to typeset text with an extensible syntax, -called @qq{markup mode}. -Specific commands can be entered in this mode, using the -backslash @code{\} character. -@c TODO: move the following sentence (and add an example?) -vv -To @emph{print} such characters as -@code{\} and @code{#} in the output, use double -quotation marks. +A @code{\markup} block is used to typeset text with an extensible +specific syntax called @qq{markup mode}. -@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" } -@end lilypond +@cindex markup expressions +@cindex markup syntax -@noindent -An exhaustive list of @code{\markup}-specific commands can be found in -@ref{Text markup commands}. +The markup syntax is similar to LilyPond's usual syntax: a +@code{\markup} expression is enclosed in curly braces @code{@{ +@dots{} @}}. +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] -\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! } } -} +@lilypond[quote,verbatim,fragment,relative=1] +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 +@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: -@cindex font switching - -Some font switching commands are demonstrated here. Such commands -apply only to the first following word; several words may be affected -by enclosing them in braces. - -@example -\markup @{ \bold @{ hi there @} @} -@end example - -@c TODO: remove the following line and example? -vv -@noindent -For clarity, you can also do this for single arguments, e.g., - -@example -\markup @{ is \italic @{ anyone @} home @} -@end example +@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 -The markup mode can be used to compose expressions, similar to -mathematical expressions, XML documents, and music expressions. -Such expressions can be vertically stacked, horizontally centered, -or aligned in different ways: +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 } } } @@ -402,228 +391,404 @@ c1^\markup { \center-align { a bbbb c } } c1^\markup { \line { a b c } } @end lilypond -Lists with no previous command are not kept distinct. In -the following example, the two @code{\markup} expressions -are equivalent: +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: -@c TODO: merge these two examples in a @lilypond example -vv +@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 -@example -\center-align @{ @{ a b @} @{ c d @} @} -\center-align @{ a b c d @} -@end example -@noindent +Markups can be stored in variables. These variables may be +directly attached to notes: -To keep lists of words distinct, please use quotes @code{"} or -the @code{\line} command +@lilypond[quote,verbatim] +allegro = \markup { \bold \large Allegro } -@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 } } } +{ + d''8.^\allegro + d'16 d'4 r2 +} @end lilypond -Markups can be stored in variables and these variables may be -attached to notes, like -@example -allegro = \markup @{ \bold \large @{ Allegro @} @} - @{ a^\allegro b c d @} -@end example +@noindent +An exhaustive list of @code{\markup}-specific commands can be found in +@ref{Text markup commands}. -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. -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}). +@seealso -@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 } -@end lilypond +This manual: @ref{Text markup commands}. -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{Text markup commands}, for more details. +Snippets: +@rlsr{Text}. -@ignore -TODO: here are some commands that could be described here. -I'm putting them in bulk, prior to working on this section. -vv +Internals Reference: @rinternals{TextScript}. -\simple +Init files: @file{scm/@/new@/-markup@/.scm}. -\char -\fraction -\combine -\concat -\put-adjacent +@knownissues +Syntax errors for markup mode can be confusing. -\page-ref (see also "Table of contents") -\fromproperty -\verbatim-file -\with-url -\on-the-fly -\override +@node Selecting font and font size +@subsubsection Selecting font and font size +@cindex font switching +@funindex \italic +@funindex \bold +@funindex \underline -\null -\hspace +Basic font switching is supported in markup mode: -\lower -\raise -\translate -\translate-scaled -\rotate -\transparent -\whiteout +@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 -@end ignore +@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, -@seealso +@item +predefined commands allow to easily select standard sizes, -This manual: @ref{Text markup commands}. +@item +the font size can also be changed relatively to its previous value. +@end itemize -Snippets: -@lsrdir{Text,Text} +@noindent +The following example demonstrates these three methods: -Internals Reference: @internalsref{TextScript}. +@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 -Init files: @file{scm/@/new@/-markup@/.scm}. +@cindex subscript +@cindex superscript +@funindex \super +@funindex \sub +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: -@knownissues +@lilypond[quote,verbatim] +\markup { + \column { + \line { 1 \super st movement } + \line { 1 \normal-size-super st movement + \sub { (part two) } } + } +} +@end lilypond -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. +@cindex font families -Syntax errors for markup mode are confusing. +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. -@node Common markup commands -@subsubsection Common markup commands +@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 -Some basic formatting can be used blah blah +@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}. -\italic -\upright -\bold -\medium -\underline - +@c \concat is actually documented in Align (it is not +@c a font-switching command). But we need it here. -vv -@c TODO: what's the difference between the following commands? -vv -\smallCaps -\caps -\fontCaps +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: +@lilypond[quote,verbatim] +\markup { + \column { + \line { + \concat { 1 \super st } + movement + } + \line { + \concat { \dynamic p , } + \italic { con dolce espressione } + } + } +} +@end lilypond -Some alternate font families can easily be selected: +An exhaustive list of font-switching, font-size +and font-families related commands can be found in @ref{Font}. -\sans -\typewriter -\roman -\number (only for numbers, such as fingerings and time signatures) -@c TODO: add \slashed-digit here? -vv +Defining custom font sets is also possible, as explained in +@ref{Fonts}. -The size can be blah blah blah +@predefined -\fontsize +@funindex \teeny +@funindex \tiny +@funindex \small +@funindex \normalsize +@funindex \large +@funindex \huge +@code{\teeny}, +@code{\tiny}, +@code{\small}, +@code{\normalsize}, +@code{\large}, +@code{\huge}. -Some predefined font sizes can be used blah blah +@c TODO: add @seealso -\teeny -\tiny -\small -\normalsize -\large -\huge -Some shorcuts allow to change the font size relatively to its previous value +@node Text alignment +@subsubsection Text alignment -\smaller -\bigger -\larger +@cindex text, aligning +@cindex aligning text -\magnify +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}. -Text may be printed as subscript or superscript: +@c The padding commands should be mentioned on this page, but +@c most of these require \box to be more clearly illustrated. -vv -\sub -\super +@cindex text, horizontal alignment +@cindex horizontal text alignment +@funindex \left-align +@funindex \hcenter +@funindex \right-align -To obtain subscripts or superscripts in a normal text size, use -\normal-size-sub -\normal-size-super +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. -All these settings (except the size) can be reverted to the default font: +@lilypond[quote,verbatim,fragment,relative=1] +a1-\markup { poco } +e' +a,-\markup { \left-align poco } +e' +a,-\markup { \hcenter { poco } } +e' +a,-\markup { \right-align poco } +@end lilypond -\normal-text +@funindex \halign +The horizontal alignment may be fine-tuned +using a numeric value: -@node Text alignment -@subsubsection Text alignment +@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 -Alignment basics: -\left-align -\center-align -\right-align +@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. -Horizontal alignment: -\hcenter -\general-align -\halign +@lilypond[quote,verbatim,fragment,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. } } +a'4 a g2 a +@end lilypond + +@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: + +@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 + +@cindex multi-line markup +@cindex multi-line text +@cindex columns, 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: -Vertical alignment: -\vcenter -\column -\dir-column +@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 -Building a "large" markup: +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: -\line +@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 -\fill-line +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. -\hcenter-in - -\pad-around -\pad-markup -\pad-to-box -\pad-x - -Alignment inside a "large" markup: +@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 -\justify-field -\justify -\justify-string +An exhaustive list of text alignment commands +can be found in @ref{Align}. -\wordwrap-field -\wordwrap -\wordwrap-string +@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 @@ -711,7 +876,7 @@ block. In such a case, the @code{\score} must contain a @code{\layout} block. @seealso Snippets: -@lsrdir{Text,Text} +@rlsr{Text}. @node Multi-page markup @subsubsection Multi-page markup @@ -745,7 +910,7 @@ This manual: @ref{Text markup list commands}, @ref{New markup list command definition}. Snippets: -@lsrdir{Text,Text} +@rlsr{Text}. @predefined @@ -753,9 +918,6 @@ Snippets: @code{\markuplines} - -@c TODO: move the following subsubsec into NR3 -vv -@c maybe. -gp @node Fonts @subsection Fonts @@ -880,6 +1042,6 @@ property. The resulting size is taken relative to the @seealso Snippets: -@lsrdir{Text,Text} +@rlsr{Text}.