lilypond-usage: Music fragment options
3.3 Music fragment options
==========================
In the following, a ‘LilyPond command’ refers to any command described
in the previous sections which is handled by ‘lilypond-book’ to produce
a music snippet. For simplicity, LilyPond commands are only shown in
LaTeX syntax.
Note that the option string is parsed from left to right; if an
option occurs multiple times, the last one is taken.
The following options are available for LilyPond commands:
‘staffsize=HT’
Set staff size to HT, which is measured in points.
‘ragged-right’
Produce ragged-right lines with natural spacing, i.e.,
‘ragged-right = ##t’ is added to the LilyPond snippet. Single-line
snippets will always be typeset by default as ragged-right, unless
‘noragged-right’ is explicitly given.
‘noragged-right’
For single-line snippets, allow the staff length to be stretched to
equal that of the line width, i.e., ‘ragged-right = ##f’ is added
to the LilyPond snippet.
‘line-width’
‘line-width=SIZE\UNIT’
Set line width to SIZE, using UNIT as units. UNIT is one of the
following strings: ‘cm’, ‘mm’, ‘in’, or ‘pt’. This option affects
LilyPond output (this is, the staff length of the music snippet),
not the text layout.
If used without an argument, set line width to a default value (as
computed with a heuristic algorithm).
If no ‘line-width’ option is given, ‘lilypond-book’ tries to guess
a default for ‘lilypond’ environments which don’t use the
‘ragged-right’ option.
‘papersize=STRING’
Where STRING is a paper size defined in ‘scm/paper.scm’ i.e. ‘a5’,
‘quarto’, ‘11x17’ etc.
Values not defined in ‘scm/paper.scm’ will be ignored, a warning
will be posted and the snippet will be printed using the default
‘a4’ size.
‘notime’
Do not print the time signature, and turns off the timing (time
signature, bar lines) in the score.
‘fragment’
Make ‘lilypond-book’ add some boilerplate code so that you can
simply enter, say,
c'4
without ‘\layout’, ‘\score’, etc.
‘nofragment’
Do not add additional code to complete LilyPond code in music
snippets. Since this is the default, ‘nofragment’ is redundant
normally.
‘indent=SIZE\UNIT’
Set indentation of the first music system to SIZE, using UNIT as
units. UNIT is one of the following strings: ‘cm’, ‘mm’, ‘in’, or
‘pt’. This option affects LilyPond, not the text layout.
‘noindent’
Set indentation of the first music system to zero. This option
affects LilyPond, not the text layout. Since no indentation is the
default, ‘noindent’ is redundant normally.
‘quote’
Reduce line length of a music snippet by 2*0.4in and put the output
into a quotation block. The value ‘0.4in’ can be controlled with
the ‘exampleindent’ option.
‘exampleindent’
Set the amount by which the ‘quote’ option indents a music snippet.
‘relative’
‘relative=N’
Use relative octave mode. By default, notes are specified relative
to middle C. The optional integer argument specifies the octave of
the starting note, where the default ‘1’ is middle C. ‘relative’
option only works when ‘fragment’ option is set, so ‘fragment’ is
automatically implied by ‘relative’, regardless of the presence of
any ‘(no)fragment’ option in the source.
LilyPond also uses ‘lilypond-book’ to produce its own documentation.
To do that, some more obscure music fragment options are available.
‘verbatim’
The argument of a LilyPond command is copied to the output file and
enclosed in a verbatim block, followed by any text given with the
‘intertext’ option (not implemented yet); then the actual music is
displayed. This option does not work well with ‘\lilypond{}’ if it
is part of a paragraph.
If ‘verbatim’ is used in a ‘lilypondfile’ command, it is possible
to enclose verbatim only a part of the source file. If the source
file contain a comment containing ‘begin verbatim’ (without
quotes), quoting the source in the verbatim block will start after
the last occurrence of such a comment; similarly, quoting the
source verbatim will stop just before the first occurrence of a
comment containing ‘end verbatim’, if there is any. In the
following source file example, the music will be interpreted in
relative mode, but the verbatim quote will not show the ‘relative’
block, i.e.
\relative c' { % begin verbatim
c4 e2 g4
f2 e % end verbatim
}
will be printed with a verbatim block like
c4 e2 g4
f2 e
If you would like to translate comments and variable names in
verbatim output but not in the sources, you may set the environment
variable ‘LYDOC_LOCALEDIR’ to a directory path; the directory
should contain a tree of ‘.mo’ message catalogs with ‘lilypond-doc’
as a domain.
‘addversion’
(Only for Texinfo output.) Prepend line ‘\version
@w{"@version{}"}’ to ‘verbatim’ output.
‘texidoc’
(Only for Texinfo output.) If ‘lilypond’ is called with the
‘--header=texidoc’ option, and the file to be processed is called
‘foo.ly’, it creates a file ‘foo.texidoc’ if there is a ‘texidoc’
field in the ‘\header’. The ‘texidoc’ option makes ‘lilypond-book’
include such files, adding its contents as a documentation block
right before the music snippet (but outside the ‘example’
environment generated by a ‘quote’ option).
Assuming the file ‘foo.ly’ contains
\header {
texidoc = "This file demonstrates a single note."
}
{ c'4 }
and we have this in our Texinfo document ‘test.texinfo’
@lilypondfile[texidoc]{foo.ly}
the following command line gives the expected result
lilypond-book --pdf --process="lilypond \
-dbackend=eps --header=texidoc" test.texinfo
Most LilyPond test documents (in the ‘input’ directory of the
distribution) are small ‘.ly’ files which look exactly like this.
For localization purpose, if the Texinfo document contains
‘@documentlanguage LANG’ and ‘foo.ly’ header contains a
‘texidocLANG’ field, and if ‘lilypond’ is called with
‘--header=texidocLANG’, then ‘foo.texidocLANG’ will be included
instead of ‘foo.texidoc’.
‘doctitle’
(Only for Texinfo output.) This option works similarly to
‘texidoc’ option: if ‘lilypond’ is called with the
‘--header=doctitle’ option, and the file to be processed is called
‘foo.ly’ and contains a ‘doctitle’ field in the ‘\header’, it
creates a file ‘foo.doctitle’. When ‘doctitle’ option is used, the
contents of ‘foo.doctitle’, which should be a single line of TEXT,
is inserted in the Texinfo document as ‘@lydoctitle TEXT’.
‘@lydoctitle’ should be a macro defined in the Texinfo document.
The same remark about ‘texidoc’ processing with localized languages
also applies to ‘doctitle’.
‘nogettext’
(Only for Texinfo output.) Do not translate comments and variable
names in the snippet quoted verbatim.
‘printfilename’
If a LilyPond input file is included with ‘\lilypondfile’, print
the file name right before the music snippet. For HTML output,
this is a link. Only the base name of the file is printed, i.e.
the directory part of the file path is stripped.
Info Catalog
lilypond-usage: Integrating music and text
lilypond-usage: lilypond-book
lilypond-usage: Invoking lilypond-book