15
@node lilypond-book manual
16
@chapter lilypond-book manual
18
If you want to add pictures of music to a document, you can simply do
19
it the way you would do with other types of pictures. The pictures
20
are created separately, yielding PostScript pictures or PNG images,
21
and those are included into a La@TeX{} or HTML document.
23
@command{lilypond-book} provides a way to automate this process: this
24
program extracts snippets of music from your document, runs LilyPond
25
on them, and outputs the document with pictures substituted for the
26
music. The line width and font size definitions for the music are
27
adjusted to match the layout of your document.
29
This procedure may be applied to La@TeX{}, @code{html} or Texinfo
30
documents. A tutorial on using lilypond-book is in @ref{Integrating
31
text and music}. For more information about La@TeX{}
32
@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
33
Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
16
@c Note: keep this node named so that `info lilypond-book' brings you here.
18
@chapter @command{lilypond-book}: Integrating text and music
20
If you want to add pictures of music to a document, you can simply do it
21
the way you would do with other types of pictures. The pictures are
22
created separately, yielding PostScript output or PNG images, and those
23
are included into a La@TeX{} or HTML document.
25
@command{lilypond-book} provides a way to automate this process: This
26
program extracts snippets of music from your document, runs
27
@command{lilypond} on them, and outputs the document with pictures
28
substituted for the music. The line width and font size definitions for
29
the music are adjusted to match the layout of your document.
31
This procedure may be applied to La@TeX{}, HTML or Texinfo documents.
39
* Integrating Texinfo and music::
40
* Integrating LaTeX and music::
41
* Integrating HTML and music::
42
* Music fragment options::
43
* Invoking lilypond-book::
34
* An example of a musicological document::
35
* Integrating LaTeX and music::
36
* Integrating Texinfo and music::
37
* Integrating HTML and music::
38
* Music fragment options::
39
* Invoking lilypond-book::
40
* Filename extensions::
44
@node An example of a musicological document
45
@section An example of a musicological document
48
@cindex La@TeX{}, music in
49
@cindex HTML, music in
50
@cindex Texinfo, music in
51
Some texts contain music examples. These texts are musicological
52
treatises, songbooks, or manuals like this. Such texts can be made by
53
hand, simply by importing a PostScript figure into the word processor.
54
However, there is an automated procedure to reduce the amount of work
55
involved in HTML, La@TeX{}, and Texinfo documents.
57
A script called @code{lilypond-book} will extract the music fragments,
58
format them, and put back the resulting notation. Here we show a small
59
example for use with La@TeX{}. The example also contains explanatory
60
text, so we will not comment on it further.
64
\documentclass[a4paper]{article}
68
Documents for @command{lilypond-book} may freely mix music and text.
73
c2 g'2 \times 2/3 { f8 e d } c'2 g4
77
Options are put in brackets.
79
\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
83
Larger examples can be put into a separate file, and introduced with
86
\lilypondfile[quote,noindent]{screech-boink.ly}
92
Under Unix, you can view the results as follows
97
lilypond-book --output=out --psfonts lilybook.tex
98
@emph{lilypond-book (GNU LilyPond) 2.6.0}
99
@emph{Reading lilybook.tex...}
100
@emph{..lots of stuff deleted..}
101
@emph{Compiling out/lilybook.tex...}
104
@emph{lots of stuff deleted}
108
To convert the file into a PDF document, run the following commands
111
dvips -o -Ppdf -h lilybook.psfonts lilybook
115
Running @command{lilypond-book} and @command{latex} creates a lot of
116
temporary files, which would clutter up the working directory. To
117
remedy this, use the @code{--output=@var{dir}} option. It will create
118
the files in a separate subdirectory @file{dir}.
120
Running dvips will produce many warnings about fonts. They are not
121
harmful; please ignore them.
123
Finally the result of the La@TeX{} example shown above.@footnote{This
124
tutorial is processed with Texinfo, so the example gives slightly
125
different results in layout.} This finishes the tutorial section.
129
Documents for @command{lilypond-book} may freely mix music and text.
134
c2 g'2 \times 2/3 { f8 e d } c'2 g4
138
Options are put in brackets.
140
@lilypond[fragment,quote,staffsize=26,verbatim]
144
Larger examples can be put into a separate file, and introduced with
145
@code{\lilypondfile}.
147
@lilypondfile[quote,noindent]{screech-boink.ly}
138
@lilypond[staffsize=26]
207
@lilypond[quote,fragment,staffsize=26]
142
Then the short version:
145
\lilypond[staffsize=11]@{<c' e' g'>@}
214
\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
151
@lilypond[staffsize=11]{<c' e' g'>}
153
The linewidth of the music will be adjust by examining the commands in
154
the document preamble, the part of the document before
155
@code{\begin@{document@}}: @command{lilypond-book} sends these to
156
La@TeX{} to find out how wide the text is. The line width variable for
157
the music fragments are adjusted to the text width.
159
After @code{\begin@{document@}}, the column changing commands
160
@code{\onecolumn}, @code{\twocolumn} commands
163
@code{multicols} environment from the multicol package
165
are also interpreted.
220
@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
223
Currently, you cannot include @code{@{} or @code{@}} within
224
@code{\lilypond@{@}}, so this command is only useful with the
225
@code{fragment} option.
227
The default line width of the music will be adjusted by examining the
228
commands in the document preamble, the part of the document before
229
@code{\begin@{document@}}. The @command{lilypond-book} command sends
230
these to La@TeX{} to find out how wide the text is. The line width for
231
the music fragments is then adjusted to the text width. Note that this
232
heuristic algorithm can fail easily; in such cases it is necessary to
233
use the @code{line-width} music fragment option.
167
235
@cindex titling and lilypond-book
168
@cindex lilypond-book and titling
169
236
@cindex @code{\header} in La@TeX{} documents
171
The titling from the @code{\header} section of the fragments can be
172
imported by adding the following to the top of the La@TeX{} file:
176
\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
179
The music will be surrounded by @code{\preLilyPondExample} and
180
@code{\postLilyPondExample}, which are defined to be empty by default.
238
Each snippet will call the following macros if they have been defined by
241
@code{\preLilyPondExample} called before the music
243
@code{\postLilyPondExample} called after the music
245
@code{\betweenLilyPondSystem[1]} is called between systems if
246
@code{lilypond-book} has split the snippet into several postscript
247
files. It must be defined as taking one parameter and will be
248
passed the number of files already included in this snippet.
249
The default is to simply insert a @code{\linebreak}.
254
@cindex Latex, feta symbols
257
To include feta symbols (such as flat, segno, etc) in a LaTeX
258
document, use @code{\input@{titledefs@}}
261
\documentclass[a4paper]@{article@}
272
The font symbol names are defined in the file feta20.tex; to find
273
the location of this file, use the command
182
281
@cindex outline fonts
183
282
@cindex type1 fonts
185
284
@cindex invoking dvips
187
For printing the LaTeX document, you will need to use dvips. For
188
producing PostScript with scalable fonts, add the following options to
189
the dvips command line:
286
For printing the La@TeX{} document you need a DVI to PostScript
287
translator like @command{dvips}. To use @command{dvips} to produce
288
a PostScript file, add the following options to the @command{dvips}
191
-Ppdf -u +lilypond.map
292
-o -Ppdf -h @var{file}.psfonts
195
PDF can then be produced with @code{ps2pdf}.
296
where the @var{file}@command{psfonts} file is obtained from
297
@command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
298
can then be produced with a PostScript to PDF translator like
299
@code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
300
will produce some warnings about fonts; these are harmless and may
197
303
@cindex international characters
200
LilyPond does not use the LaTeX font handling scheme for lyrics and text
201
markups, so if you use characters in your lilypond-book
202
documents that are not included in the standard US-ASCII character set,
203
include @code{\usepackage[latin1]@{inputenc@}} in the file
204
header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
205
sets other than latin1 are not supported directly but may be handled by
206
explicitly specifying the @code{font-name} property in LilyPond and
207
using the corresponding LaTeX packages. Please consult the mailing list
307
@node Integrating Texinfo and music
308
@section Integrating Texinfo and music
310
Texinfo is the standard format for documentation of the GNU project. An
311
example of a Texinfo document is this manual. The HTML, PDF, and Info
312
versions of the manual are made from the Texinfo document.
314
In the input file, music is specified with
317
@@lilypond[options,go,here]
326
@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
333
@@lilypondfile[options,go,here]@{@var{filename}@}
336
When @command{lilypond-book} is run on it, this results in a Texinfo
337
file (with extension @file{.texi}) containing @code{@@image} tags for
338
HTML and info output. For the printed edition, the raw @TeX{} output of
339
LilyPond is included in the main document.
341
We show two simple examples here. A @code{lilypond} environment
359
@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
365
@lilypond[fragment,staffsize=11]{<c' e' g'>}
367
Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
368
in-line image. It always gets a paragraph of its own.
370
When using the Texinfo output format, @command{lilypond-book} also
371
generates bitmaps of the music (in PNG format), so you can make an HTML
372
document with embedded music.
214
375
@node Integrating HTML and music
217
378
Music is entered using
220
<lilypond relative=1 verbatim>
221
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
381
<lilypond fragment relative=2>
382
\key c \minor c4 es g2
226
of which lilypond-book will produce a HTML with appropriate image tags for the
230
<lilypond relative=2 verbatim>
231
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
387
@command{lilypond-book} then produces an HTML file with appropriate image
388
tags for the music fragments:
235
@lilypond[relative=2]
236
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
390
@lilypond[fragment,relative=2]
391
\key c \minor c4 es g2
239
For inline pictures, use @code{<lilypond ... />} syntax, e.g.
241
Some music in <lilypond a b c/> a line of text.
244
A special feature not (yet) available in other output formats, is the
245
@code{<lilypondfile>} tag, for example,
247
<lilypondfile>trip.ly</lilypondfile>
249
This runs @file{trip.ly} through @code{lilypond} (see also
250
@ref{Invoking lilypond}), and substitutes a preview image in the
251
output. The image links to a separate HTML file, so clicking it will
252
take the viewer to a menu, with links to images, midi and printouts.
254
@cindex titling in THML
394
For inline pictures, use @code{<lilypond ... />}, where the options
395
are separated by a colon from the music, for example
398
Some music in <lilypond relative=2: a b c/> a line of text.
401
To include separate files, say
404
<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
407
@cindex titling in HTML
255
408
@cindex preview image
256
409
@cindex thumbnail
258
412
@node Music fragment options
259
413
@section Music fragment options
261
The commands for lilypond-book have room to specify one or more of the
415
In the following, a ``LilyPond command'' refers to any command described
416
in the previous sections which is handled by @command{lilypond-book} to
417
produce a music snippet. For simplicity, LilyPond commands are only
418
shown in La@TeX{} syntax.
420
Note that the option string is parsed from left to right; if an option
421
occurs multiple times, the last one is taken.
423
The following options are available for LilyPond commands:
266
@var{contents} is copied into the source, enclosed in a verbatim block;
267
followed by any text given with the @code{intertext} option; then
268
the actual music is displayed. This option does not work with
269
the short version of the music blocks:
271
@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
273
@item filename=@var{filename}
274
This names the file for the @code{printfilename} option. The argument
277
426
@item staffsize=@var{ht}
278
Sets the staff height to @var{ht}, which is measured in points.
281
produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
282
works well for small music fragments.
284
@item linewidth=@var{size}\@var{unit}
285
sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
286
This option affects LilyPond output, not the text layout.
427
Set staff size to @var{ht}, which is measured in points.
430
Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
431
= ##t} is added to the LilyPond snippet). This is the default for the
432
@code{\lilypond@{@}} command if no @code{line-width} option is present.
433
It is also the default for the @code{lilypond} environment if the
434
@code{fragment} option is set, and no line width is explicitly
438
Produce lines with packed spacing (i.e., @code{packed = ##t} is added
439
to the LilyPond snippet).
442
@itemx line-width=@var{size}\@var{unit}
443
Set line width to @var{size}, using @var{unit} as units. @var{unit} is
444
one of the following strings: @code{cm}, @code{mm}, @code{in}, or
445
@code{pt}. This option affects LilyPond output (this is, the staff
446
length of the music snippet), not the text layout.
448
If used without an argument, set line width to a default value (as
449
computed with a heuristic algorithm).
451
If no @code{line-width} option is given, @command{lilypond-book} tries to
452
guess a default for @code{lilypond} environments which don't use the
453
@code{ragged-right} option.
289
prevents printing time signature.
456
Do not print the time signature, and turns off the timing (key signature,
457
bar lines) in the score.
460
Make @command{lilypond-book} add some boilerplate code so that you can
468
without @code{\layout}, @code{\score}, etc.
293
overrides @command{lilypond-book} auto detection of what type of code is
294
in the LilyPond block, voice contents, or complete code.
471
Don't add additional code to complete LilyPond code in music snippets.
472
Since this is the default, @code{nofragment} is redundant normally.
296
474
@item indent=@var{size}\@var{unit}
297
sets indentation of the first music system to @var{size},
298
where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
299
not the text layout. For single-line fragments, the default is to
304
\begin[indent=5\cm,raggedright]@{lilypond@}
475
Set indentation of the first music system to @var{size}, using
476
@var{unit} as units. @var{unit} is one of the following strings:
477
@code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
478
LilyPond, not the text layout.
311
sets indentation of the first music system to zero. This option
312
affects LilyPond, not the text layout.
481
Set indentation of the first music system to zero. This option affects
482
LilyPond, not the text layout. Since no indentation is the default,
483
@code{noindent} is redundant normally.
315
sets linewidth to the width of a quotation and puts the output
316
in a quotation block.
486
Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
487
the output into a quotation block. The value `0.4@dmn{in}' can be
488
controlled with the @code{exampleindent} option.
491
Set the amount by which the @code{quote} option indents a music snippet.
494
@itemx relative=@var{n}
495
Use relative octave mode. By default, notes are specified relative to
496
middle@tie{}C. The optional integer argument specifies the octave of
497
the starting note, where the default @code{1} is middle C.
500
LilyPond also uses @command{lilypond-book} to produce its own
501
documentation. To do that, some more obscure music fragment options are
506
The argument of a LilyPond command is copied to the output file and
507
enclosed in a verbatim block, followed by any text given with the
508
@code{intertext} option (not implemented yet); then the actual music is
509
displayed. This option does not work well with @code{\lilypond@{@}} if
510
it is part of a paragraph.
319
Includes the @code{texidoc} field, if defined in the file. This is
320
only for Texinfo output.
322
In Texinfo, the music fragment is normally preceded by the
323
@code{texidoc} field from the @code{\header}. The LilyPond test
324
documents are composed from small @file{.ly} files in this way:
328
texidoc = "this file demonstrates a single note"
330
\score @{ \notes @{ c'4 @} @}
333
@item relative, relative=@var{N}
334
uses relative octave mode. By default, notes are specified relative
335
to middle C. The optional integer argument specifies the octave of the
336
@item relative, relative=@var{N}
337
uses relative octave mode. By default, notes are specified relative
338
to middle C. The optional integer argument specifies the octave of the
339
starting note, where the default @code{1} is middle C.
513
(Only for Texinfo output.) If @command{lilypond} is called with the
514
@option{--header=@/texidoc} option, and the file to be processed is
515
called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
516
is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
517
option makes @command{lilypond-book} include such files, adding its
518
contents as a documentation block right before the music snippet.
520
Assuming the file @file{foo@/.ly} contains
524
texidoc = "This file demonstrates a single note."
530
and we have this in our Texinfo document @file{test.texinfo}
533
@@lilypondfile[texidoc]@{foo.ly@}
537
the following command line gives the expected result
540
lilypond-book --process="lilypond --format=tex --tex \
541
--header=texidoc test.texinfo
544
Most LilyPond test documents (in the @file{input} directory of the
545
distribution) are small @file{.ly} files which look exactly like this.
548
If a LilyPond input file is included with @code{\lilypondfile}, print
549
the file name right before the music snippet. For HTML output, this is
553
This option includes fonts in all of the generated EPS-files for this
554
snippet. This should be used if the snippet uses any font that LaTeX
555
cannot find on its own.
343
560
@node Invoking lilypond-book
344
@section Invoking lilypond-book
347
Running @command{lilypond-book} generates lots of small files that
348
LilyPond will process. To avoid all that garbage in the source
349
directory use the @option{--output} command line option, and change to
350
that directory before running La@TeX{} or @file{makeinfo}:
561
@section Invoking @command{lilypond-book}
563
@command{lilypond-book} produces a file with one of the following
564
extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
565
output format. Both @file{.tex} and @file{.texi} files need further
568
@command{lilypond-book} can also create a PSFONTS file, which is required
569
by @command{dvips} to produce Postscript and PDF files. You can call
570
this file whatever you want as long as you refer to the same file when
571
you call @command{dvips}.
573
To produce PDF output from the lilypond-book file (here called
574
@code{yourfile.lytex}), you should do
353
lilypond-book --output=out yourfile.lytex
354
cd out && latex yourfile.tex
577
lilypond-book --psfonts yourfile.lytex
579
dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
583
The @file{.dvi} file created by this process will not contain
584
noteheads. This is normal; if you follow the instructions, they
585
will be included in the @file{.ps} and @file{.pdf} files.
587
To produce a Texinfo document (in any output format), follow the normal
588
procedures for Texinfo (this is, either call @command{texi2dvi} or
589
@command{makeinfo}, depending on the output format you want to
592
@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
593
an Info File, , , texinfo, GNU Texinfo}.
596
See the documentation of Texinfo for further details.
358
600
@command{lilypond-book} accepts the following command line options:
361
@item @option{-f @var{format}}, @option{--format=@var{format}}
362
Specify the document type to process: @code{html}, @code{latex} or
363
@code{texi} (the default). @command{lilypond-book} figures this
366
The @code{texi} document type produces a texinfo file with music
367
fragments in the DVI output only. For getting images in the HTML
369
@code{texi-html} must be used.
371
@item @option{-F @var{filter}}, @option{--filter=@var{filter}}
372
Pipe snippets through @var{filter}.
603
@item -f @var{format}
604
@itemx --format=@var{format}
605
Specify the document type to process: @code{html}, @code{latex}, or
606
@code{texi} (the default). If this option is missing,
607
@command{lilypond-book} tries to detect the format automatically.
609
The @code{texi} document type produces a Texinfo file with music
610
fragments in the DVI output only. For getting images in the HTML
611
version, the format @code{texi-html} must be used instead.
613
[Note: Currently, @code{texi} is the same as @code{texi-html}.]
615
@item -F @var{filter}
616
@itemx --filter=@var{filter}
617
Pipe snippets through @var{filter}. @code{lilypond-book} will
618
not --filter and --process at the same time.
376
lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
622
lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
379
@item @option{--help}
380
627
Print a short help message.
382
@item @option{-I @var{dir}}, @option{--include=@var{dir}}
383
Add @var{DIR} to the include path.
385
@item @option{-o @var{dir}}, @option{--output=@var{dir}}
386
Place generated files in @var{dir}.
388
@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
389
Process lilypond snippets using @var{command}. The default command is
392
@item @option{--verbose}
630
@itemx --include=@var{dir}
631
Add @var{dir} to the include path.
634
@itemx --output=@var{dir}
635
Place generated files in directory @var{dir}. Running
636
@command{lilypond-book} generates lots of small files that LilyPond will
637
process. To avoid all that garbage in the source directory use the
638
@option{--output} command line option, and change to that directory
639
before running @command{latex} or @command{makeinfo}:
642
lilypond-book --output=out yourfile.lytex
647
@item -P @var{process}
648
@itemx --process=@var{command}
649
Process LilyPond snippets using @var{command}. The default command is
650
@code{lilypond}. @code{lilypond-book} will not --filter and --process
654
extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
655
This is necessary for @command{dvips -h @var{file}.psfonts}.
395
@item @option{--version}
396
663
Print version information.
399
For La@TeX{} input, the file to give to La@TeX{} has extension
400
@file{.latex}. Texinfo input will be written to a file with extension
407
The La@TeX{} @code{\includeonly@{...@}} command is ignored.
409
The Texinfo command @code{pagesize} is not interpreted. Almost all
410
La@TeX{} commands that change margins and line widths are ignored.
668
The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
669
La@TeX{} commands that change margins and line widths after the preamble
412
672
Only the first @code{\score} of a LilyPond block is processed.
415
The size of a music block is limited to 1.5 KB, due to technical
416
problems with the Python regular expression engine. For longer files,
417
use @code{\lilypondfile}.
675
@node Filename extensions
676
@section Filename extensions
678
You can use any filename extension for the input file, but if you do not
679
use the recommended extension for a particular format you may need to
680
manually specify the output format. @xref{Invoking lilypond-book}, for
681
details. Otherwise, @command{lilypond-book} automatically selects the
682
output format based on the input filename's extension.
685
@multitable @columnfractions .2 .5
686
@item @strong{extension} @tab @strong{output format}
688
@item @file{.html} @tab HTML
689
@item @file{.itely} @tab Texinfo
690
@item @file{.latex} @tab La@TeX{}
691
@item @file{.lytex} @tab La@TeX{}
692
@item @file{.tely} @tab Texinfo
693
@item @file{.tex} @tab La@TeX{}
694
@item @file{.texi} @tab Texinfo
695
@item @file{.texinfo} @tab Texinfo
696
@item @file{.xml} @tab HTML
added
removed
Documentation/user/lilypond-book.itely
