[ << lilypond-book ][Top][Contents][Index][ External programs >> ]
[ < DocBook ][ Up : lilypond-book ][]

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 (expressed in unit). unit is one of the following: cm, mm, in, pt, or bp. This option affects LilyPond output (that is, the staff length of the music fragment), 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

Set paper size to string (for example a5 or letter) for music fragments that use \book. See Predefined paper sizes for a list of available paper sizes.

This option affects LilyPond output (that is, the paper size of the music fragment), not the text layout. Unknown values of string are ignored: a warning is emitted and the snippet is printed using the default a4 size.

paper-width=size\unit

Set paper width to size (expressed in unit) for music fragments that use \book. unit is one of the following: cm, mm, in, pt, or bp.

This option affects LilyPond output (that is, the paper width of the music fragment), not the text layout. If set, it overrides option ‘papersize’ if given. If option ‘paper-height’ is not specified, the paper height is set to the default A4 paper height (296mm).

paper-height=size\unit

Set paper height to size (expressed in unit) for music fragments that use \book. unit is one of the following: cm, mm, in, pt, or bp.

This option affects LilyPond output (that is, the paper height of the music fragment), not the text layout. If set, it overrides option ‘papersize’ if given. If option ‘paper-width’ is not specified, the paper width is set to the default A4 paper width (210mm).

Example: 

\lilypond[paper-width=10\cm, paper-height=57\mm]{
  \book {
    ...
  }
}
notime

Do not print the time signature and turn 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.

inline

Set up snippet for inline use, that is, to be typeset within a paragraph. The snippet itself is formatted with a very small left padding (approximately the same as the right padding), ignoring the value given by the command line option ‘--left-padding’.

For Texinfo output, it suppresses the insertion of a blank line before and after the snippet. For HTML output, it suppresses the insertion of <p> before and </p> after the snippet.

To actually make a snippet appear inline in LaTeX and Texinfo mode, it is necessary to position it within a paragraph, avoiding an empty line before and after the snippet. For example 

The motive
\lilypond[inline,staffsize=11]{
  { \time 2/4 r8 g'[ g' g'] | es'2 }
}
is widely known.

becomes

The motive [image of music] is widely known.

indent=size\unit

Set indentation of the first music system to size (expressed in unit). unit is one of the following: cm, mm, in, pt, or bp. 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 { % begin verbatim
  c'4 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.

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 \
  --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.

[ << lilypond-book ][Top][Contents][Index][ External programs >> ]
[ < DocBook ][ Up : lilypond-book ][]

<< Back to Documentation Index

LilyPond — Usage v2.23.82 (development-branch).