LilyPond Application Usage: 3.3 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. This is the default for the `\lilypond{}` command if no `line-width` option is present. It is also the default for the `lilypond` environment if the `fragment` option is set, and no line width is explicitly specified.

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

  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`’.

`lilyquote`

  (Only for Texinfo output.) This option is similar to quote, but only the music snippet (and the optional verbatim block implied by `verbatim` option) is put into a quotation block. This option is useful if you want to `quote` the music snippet but not the `texidoc` documentation block.

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

Jiné jazyky: deutsch, español, français, magyar, italiano.

#### LilyPond — Usage