<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Music fragment options - GNU LilyPond program usage</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="GNU LilyPond program usage">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="LilyPond_002dbook.html#LilyPond_002dbook" title="LilyPond-book">
<link rel="prev" href="Integrating-music-and-text.html#Integrating-music-and-text" title="Integrating music and text">
<link rel="next" href="Invoking-lilypond_002dbook.html#Invoking-lilypond_002dbook" title="Invoking lilypond-book">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1999--2007 by the authors
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections. A copy of the license is
included in the section entitled ``GNU Free Documentation
License''.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
hr { border:0; height:1; color: #000000; background-color: #000000; }
/* hr {
border: none;
height: 1px;
color: #666666;
background-color: #666666;
}
body {
border-left: 1px solid #666666;
border-right: 1px solid #666666;
color: #332d28;
margin-right: auto;
margin-left: auto;
width: 60em;
list-style-type: square;
font-family: Arial,Helvetica,sans-serif;
padding-right: 1em;
padding-left: 1em;
}
a {
border-bottom: 1px dashed #344242;
text-decoration: none;
color: #344242;
}
a:link {
text-decoration: none;
}
a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
a:active {
border-bottom: 1px solid #00cccc;
color: #00cccc;
}
a:hover {
border-bottom: 1px solid #1d7b85;
color: #1d7b85;
}
blockquote {
border: 1px solid #cccccc;
padding: 3px;
width: 40em;
}
.node {
border-left: 1px solid #666666;
margin: -0.5em 0px 1em;
padding: 2px 1px 0px;
font-style: italic;
}
.node a {
border: none;
text-decoration: underline;
font-style: normal;
font-weight: bold;
}
.verbatim {
font-family: "Courier New",Courier,monospace;
}
.unnumberedsubsubsec {
font-size: large;
color: #1d7b85;
}
.subsubheading {
font-size: large;
color: #3b220d;
}
.contents {
border: 1px dashed #339999;
margin: 3px 2em;
list-style-type: square;
padding-right: 1em;
width: 40em;
background-color: #fcfff9;
}
.contents a {
border-bottom: 1px dashed #423d34;
text-decoration: none;
color: #423d34;
}
.contents a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
.contents a:active {
border-bottom: 1px solid #f0d86d;
color: #f0d86d;
}
.contents a:hover {
border-bottom: 1px solid #3b220d;
color: #3b220d;
}
.menu {
border-left: 1px dashed #339999;
margin: 3px 2em 1em;
list-style-type: square;
padding-left: 1.4em;
width: 40em;
}
.unnumbered {
}
h2 {
font-size: x-large;
color: #1d7b85;
}
*/
--></style>
</head>
<BODY BGCOLOR=WHITE TEXT=BLACK>
<div class="node">
<p>
<a name="Music-fragment-options"></a>
Next: <a rel="next" accesskey="n" href="Invoking-lilypond_002dbook.html#Invoking-lilypond_002dbook">Invoking lilypond-book</a>,
Previous: <a rel="previous" accesskey="p" href="Integrating-music-and-text.html#Integrating-music-and-text">Integrating music and text</a>,
Up: <a rel="up" accesskey="u" href="LilyPond_002dbook.html#LilyPond_002dbook">LilyPond-book</a>
<hr>
</div>
<h3 class="section">4.3 Music fragment options</h3>
<p>In the following, a ‘LilyPond command’ refers to any command described
in the previous sections which is handled by <samp><span class="command">lilypond-book</span></samp> to
produce a music snippet. For simplicity, LilyPond commands are only
shown in LaTeX syntax.
<p>Note that the option string is parsed from left to right; if an option
occurs multiple times, the last one is taken.
<p>The following options are available for LilyPond commands:
<dl>
<dt><code>staffsize=</code><var>ht</var><dd>Set staff size to <var>ht</var>, which is measured in points.
<br><dt><code>ragged-right</code><dd>Produce ragged-right lines with natural spacing, i.e.,
<code>ragged-right = ##t</code> is added to the LilyPond snippet. This is the
default for the <code>\lilypond{}</code> command if no <code>line-width</code>
option is present. It is also the default for the <code>lilypond</code>
environment if the <code>fragment</code> option is set, and no line width is
explicitly specified.
<br><dt><code>noragged-right</code><dd>For single-line snippets, allow the staff length to be stretched to
equal that of the line width, i.e., <code>ragged-right = ##f</code> is
added to the LilyPond snippet.
<!-- does this option still exist in lilypond? -jm -->
<br><dt><code>packed</code><dd>Produce lines with packed spacing, i.e., <code>packed = ##t</code> is added
to the LilyPond snippet.
<br><dt><code>line-width</code><dt><code>line-width=</code><var>size</var><code>\</code><var>unit</var><dd>Set line width to <var>size</var>, using <var>unit</var> as units. <var>unit</var> is
one of the following strings: <code>cm</code>, <code>mm</code>, <code>in</code>, or
<code>pt</code>. This option affects LilyPond output (this is, the staff
length of the music snippet), not the text layout.
<p>If used without an argument, set line width to a default value (as
computed with a heuristic algorithm).
<p>If no <code>line-width</code> option is given, <samp><span class="command">lilypond-book</span></samp> tries to
guess a default for <code>lilypond</code> environments which don't use the
<code>ragged-right</code> option.
<br><dt><code>notime</code><dd>Do not print the time signature, and turns off the timing (key signature,
bar lines) in the score.
<br><dt><code>fragment</code><dd>Make <samp><span class="command">lilypond-book</span></samp> add some boilerplate code so that you can
simply enter, say,
<pre class="example"> c'4
</pre>
<p class="noindent">without <code>\layout</code>, <code>\score</code>, etc.
<br><dt><code>nofragment</code><dd>Do not add additional code to complete LilyPond code in music snippets.
Since this is the default, <code>nofragment</code> is redundant normally.
<br><dt><code>indent=</code><var>size</var><code>\</code><var>unit</var><dd>Set indentation of the first music system to <var>size</var>, using
<var>unit</var> as units. <var>unit</var> is one of the following strings:
<code>cm</code>, <code>mm</code>, <code>in</code>, or <code>pt</code>. This option affects
LilyPond, not the text layout.
<br><dt><code>noindent</code><dd>Set indentation of the first music system to zero. This option affects
LilyPond, not the text layout. Since no indentation is the default,
<code>noindent</code> is redundant normally.
<br><dt><code>quote</code><dd>Reduce line length of a music snippet by 2*0.4<span class="dmn">in</span> and put
the output into a quotation block. The value ‘0.4<span class="dmn">in</span>’ can be
controlled with the <code>exampleindent</code> option.
<br><dt><code>exampleindent</code><dd>Set the amount by which the <code>quote</code> option indents a music snippet.
<br><dt><code>relative</code><dt><code>relative=</code><var>n</var><dd>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 <code>1</code> is middle C.
<code>relative</code> option only works when <code>fragment</code> option is set,
so <code>fragment</code> is automatically implied by <code>relative</code>,
regardless of the presence of any <code>(no)fragment</code> option in the
source.
</dl>
<p>LilyPond also uses <samp><span class="command">lilypond-book</span></samp> to produce its own
documentation. To do that, some more obscure music fragment options are
available.
<dl>
<dt><code>verbatim</code><dd>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
<code>intertext</code> option (not implemented yet); then the actual music is
displayed. This option does not work well with <code>\lilypond{}</code> if
it is part of a paragraph.
<p>If <code>verbatim</code> is used in a <code>lilypondfile</code> command, it is
possible to enclose verbatim only a part of the source file. If the
source file contain a comment containing ‘<samp><span class="samp">begin verbatim</span></samp>’ (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
‘<samp><span class="samp">end verbatim</span></samp>’, it 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 <code>relative</code> block, i.e.
<pre class="example"> \relative c' { % begin verbatim
c4 e2 g4
f2 e % end verbatim
}
</pre>
<p class="noindent">will be printed with a verbatim block like
<pre class="example"> c4 e2 g4
f2 e
</pre>
<br><dt><code>addversion</code><dd>(Only for Texinfo output.) Prepend line <code>\version
@w{"@version{}"}</code> to <code>verbatim</code> output.
<br><dt><code>texidoc</code><dd>(Only for Texinfo output.) If <samp><span class="command">lilypond</span></samp> is called with the
<samp><span class="option">--header=texidoc</span></samp> option, and the file to be processed is
called <samp><span class="file">foo.ly</span></samp>, it creates a file <samp><span class="file">foo.texidoc</span></samp> if there
is a <code>texidoc</code> field in the <code>\header</code>. The <code>texidoc</code>
option makes <samp><span class="command">lilypond-book</span></samp> include such files, adding its
contents as a documentation block right before the music snippet.
<p>Assuming the file <samp><span class="file">foo.ly</span></samp> contains
<pre class="example"> \header {
texidoc = "This file demonstrates a single note."
}
{ c'4 }
</pre>
<p class="noindent">and we have this in our Texinfo document <samp><span class="file">test.texinfo</span></samp>
<pre class="example"> @lilypondfile[texidoc]{foo.ly}
</pre>
<p class="noindent">the following command line gives the expected result
<pre class="example"> lilypond-book --process="lilypond --format=tex --tex \
--header=texidoc test.texinfo
</pre>
<p>Most LilyPond test documents (in the <samp><span class="file">input</span></samp> directory of the
distribution) are small <samp><span class="file">.ly</span></samp> files which look exactly like this.
<p>For localization purpose, if the Texinfo document contains
<code>@documentlanguage </code><var>LANG</var> and <samp><span class="file">foo.ly</span></samp> header
contains a <code>texidoc</code><var>LANG</var> field, and if <samp><span class="command">lilypond</span></samp>
is called with <samp><span class="option">--header=texidoc</span><var>LANG</var></samp>, then
<samp><span class="file">foo.texidoc</span><var>LANG</var></samp> will be included instead of
<samp><span class="file">foo.texidoc</span></samp>.
<br><dt><code>lilyquote</code><dd>(Only for Texinfo output.) This option is similar to quote, but only
the music snippet (and the optional verbatim block implied by
<code>verbatim</code> option) is put into a quotation block. This option is
useful if you want to <code>quote</code> the music snippet but not the
<code>texidoc</code> documentation block.
<br><dt><code>doctitle</code><dd>(Only for Texinfo output.) This option works similarly to
<code>texidoc</code> option: if <samp><span class="command">lilypond</span></samp> is called with the
<samp><span class="option">--header=doctitle</span></samp> option, and the file to be processed is
called <samp><span class="file">foo.ly</span></samp> and contains a <code>doctitle</code> field in the
<code>\header</code>, it creates a file <samp><span class="file">foo.doctitle</span></samp>. When
<code>doctitle</code> option is used, the contents of <samp><span class="file">foo.doctitle</span></samp>,
which should be a single line of <var>text</var>, is inserted in the
Texinfo document as <code>@lydoctitle </code><var>text</var>.
<code>@lydoctitle</code> should be a macro defined in the Texinfo document.
The same remark about <code>texidoc</code> processing with localized
languages also applies to <code>doctitle</code>.
<br><dt><code>printfilename</code><dd>If a LilyPond input file is included with <code>\lilypondfile</code>, 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.
<br><dt><code>fontload</code><dd>This option includes fonts in all of the generated EPS-files for this
snippet. This should be used if the snippet uses any font that LaTeX
cannot find on its own.
</dl>
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Next: <a rel="next" accesskey="n" href="Invoking-lilypond_002dbook.html#Invoking-lilypond_002dbook">Invoking lilypond-book</a>,
Previous: <a rel="previous" accesskey="p" href="Integrating-music-and-text.html#Integrating-music-and-text">Integrating music and text</a>,
Up: <a rel="up" accesskey="u" href="LilyPond_002dbook.html#LilyPond_002dbook">LilyPond-book</a>
</div>
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
This page is for LilyPond-2.11.57 (development-branch).
<br>
<address>
Report errors to <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a>. </address>
<br>
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome.
</font>
</p>
</div>
<P>
Other languages: <a href="Music-fragment-options.es.html">español</a>.
<BR>
</P>
</BODY></html>
