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

3.3 Music fragment options

In the following, a ‘lilypond-book command’ refers to any command described in the previous sections that is handled by lilypond-book to produce a music snippet. For simplicity, lilypond-book commands are only shown in Texinfo syntax (i.e., starting with ‘@’) to make them better distinguishable from LilyPond commands.

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-book 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, or if no line-width option is given, lilypond-book tries to guess a default for lilypond environments that don’t use the ragged-right option.

See also option papersize.

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 document’s paper size for LaTeX and Texinfo, and the A4 paper format for HTML and DocBook.

If option papersize is given without option line-width (more specifically, option line-width without an argument), LilyPond uses its own idea of the default line width within the snippet, also ignoring option quote (which still makes lilypond-book emit a quotation block, though).

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 document’s paper height for LaTeX and Texinfo, and the A4 paper height (296mm) for HTML and DocBook.

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 document’s paper width for LaTeX and Texinfo, and the A4 paper width (210mm) for HTML and DocBook.

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
inline=vshift

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 the LaTeX backend, the inline image gets shifted vertically; vshift is a factor of the current image’s height. If no argument is given a default value of -0.3 is used, thus moving the image down by approx. one third of its height. The default value can be adjusted with command-line option --inline-vshift.

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, this LaTeX code 

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.

See also option papersize.

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-book 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, and only for @lilypondfile.) 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 block of foo.ly. lilypond-book’s texidoc option makes it include such a file, 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

All LilyPond documentation snippets (in the Documentation/snippets directory of the distribution) are .ly files that have such texidoc fields in their \header blocks.

For localization purposes, if the Texinfo document contains @documentlanguage XX and foo.ly’s \header block contains a texidocXX field, and if lilypond is called with --header=texidocXX, then foo.texidocXX gets included instead of foo.texidoc, if present. XX is usually a two-letter string like ‘de’ (for German) or ‘ca’ (for Catalan).

doctitle

(Only for Texinfo output, and only for @lilypondfile.) This option works similarly to the 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 block, it creates a file foo.doctitle. When the 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 documentation 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 command, 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.

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

<< Back to Documentation Index

LilyPond Application Usage v2.25.14 (development-branch).