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
+text documents or books (and therefore to
+use LilyPond as a word processor). This syntax is described in
@ref{Multi-page markup}.
@predefined
The markup syntax is similar to LilyPond's usual syntax: a
@code{\markup} expression is enclosed in curly braces @code{@{
-@dots{} @}}.
+@dots{} @}}. A single word is regarded as a minimal expression,
+and therefore does not need to be enclosed with braces.
Unlike simple @q{quoted text} indications, @code{\markup} blocks
may contain nested expressions or specific commands,
Such commands only affect the first following expression.
@lilypond[quote,verbatim,fragment,relative=1]
-e1-\markup "intenso"
+e1-\markup intenso
a2^\markup { poco \italic più forte }
c e1
d2_\markup { \italic "string. assai" }
@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:
+A @code{\markup} block may also contain quoted text strings.
+Such strings are treated as minimal text expressions, and
+therefore any markup command or special character (such as
+@code{\} and @code{#}) will be printed verbatim without affecting
+the formatting of the text. This syntax even allows to print
+double quotation marks, by preceding them 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
+d1^"\italic markup..."
+d_\markup \italic "... prints \"italic\" letters!"
+d d
@end lilypond
The way markup expressions are defined affects
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
+example, there is no difference
between the first and the second markup.
@lilypond[quote,verbatim,fragment,relative=1]
a'4 a g2 a
@end lilypond
+@funindex \column
+@funindex \center-align
+
@cindex multi-line markup
@cindex multi-line text
@cindex columns, text
}
@end lilypond
+@funindex \fill-line
+
+@cindex centering text on the page
+
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.
+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:
}
@end lilypond
+@funindex \wordwrap
+@funindex \justify
+
+@cindex wordwrapped text
+@cindex justified text
+
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
@node Graphic notation inside markup
@subsubsection Graphic notation inside markup
-Graphics around text:
-\box
-\circle
+@cindex graphics, embedding
+@cindex drawing graphic objects
+
+Various graphic objects may be added to a score,
+using specific markup commands.
+
+@funindex \box
+@funindex \circle
+@funindex \rounded-box
+@funindex \bracket
+@funindex \hbracket
+
+@cindex decorating text
+@cindex framing text
+
+Some markup commands allow to decorate text elements
+with graphics, as demonstrated in the following example.
+
+@lilypond[quote,verbatim]
+\markup \fill-line {
+ \center-align {
+ \circle Jack
+ \box "in the box"
+ \null
+ \line {
+ Erik Satie
+ \hspace #3
+ \bracket "1866 - 1925"
+ }
+ \null
+ \rounded-box \bold Prelude
+ }
+}
+@end lilypond
+
+@funindex \pad-markup
+@funindex \pad-x
+@funindex \pad-to-box
+@funindex \pad-around
+
+@cindex padding around text
+@cindex text padding
+
+Some commands may require to increase the padding around
+the text: this is achieved with some specific commands
+exhaustively described in @ref{Align}.
-(TODO: document padding commands here)
+@lilypond[quote,verbatim]
+\markup \fill-line {
+ \center-align {
+ \box "Charles Ives (1874 - 1954)"
+ \null
+ \box \pad-markup #2 "THE UNANSWERED QUESTION"
+ \box \pad-x #8 "A Cosmic Landscape"
+ \null
+ }
+}
+\markup \column {
+ \line {
+ \hspace #10
+ \box \pad-to-box #'(-5 . 20) #'(0 . 5)
+ \bold "Largo to Presto"
+ }
+ \pad-around #3
+ "String quartet keeps very even time,
+Flute quartet keeps very uneven time."
+}
+@end lilypond
+
+@funindex \combine
+@funindex \draw-circle
+@funindex \filled-box
+@funindex \triangle
+@funindex \draw-line
+@funindex \arrow-head
+
+@cindex graphic notation
+@cindex symbols, non-musical
+
+Other graphic elements or symbols may be printed
+without requiring any text. As with any markup
+expression, such objects can be combined together:
-\bracket
-\hbracket
+@lilypond[quote,verbatim]
+\markup {
+ \combine
+ \draw-circle #4 #0.4 ##f
+ \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
+ \hspace #5
-"Standalone" graphics:
+ \center-align {
+ \triangle ##t
+ \combine
+ \draw-line #'(0 . 4)
+ \arrow-head #Y #DOWN ##f
+ }
+}
+@end lilypond
-\arrow-head
-\draw-line
-\draw-circle
-\filled-box
-\triangle
-\strut
+@funindex \epsfile
+@funindex \postscript
-\with-color
+@cindex embedded graphics
+@cindex images, embedding
+@cindex graphics, embedding
+@cindex postscript
+Advanced graphic features include the ability to
+include external image files converted to the
+Encapsulated PostScript format (@emph{eps}), or
+to directly embed graphics into the input file,
+using native PostScript code.
-Advanced graphics:
-\stencil
+@lilypond[quote,verbatim,fragment,relative=1]
+c1^\markup {
+ \combine
+ \epsfile #X #10 #"./context-example.eps"
+ \postscript #"
+ -2 3 translate
+ 2.7 2 scale
+ newpath
+ 2 -1 moveto
+ 4 -2 4 1 1 arct
+ 4 2 3 3 1 arct
+ 0 4 0 3 1 arct
+ 0 0 1 -1 1 arct
+ closepath
+ stroke"
+ }
+c
+@end lilypond
-\postscript
-\epsfile
+An exhaustive list of graphics-specific commands
+can be found in @ref{Graphic}.
-\with-dimensions
+@c TODO: add @seealso (and link with NR Editorial)
@node Music notation inside markup
@subsubsection Music notation inside markup
projects / lilypond.git / commitdiff