1 c -*- coding: utf-8; mode: texinfo; -*-
8 ** AARGH. We also have tutorial.itely: Integrating text and music.
10 Could also do with a cleanup. Lost inspiration to fix this manual
11 where to describe what?
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.
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}
156 @cindex documents, adding music to
159 @node Integrating LaTeX and music
160 @section Integrating La@TeX{} and music
162 La@TeX{} is the de-facto standard for publishing layouts in the exact
163 sciences. It is built on top of the @TeX{} typesetting engine,
164 providing the best typography available anywhere.
167 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
168 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
171 Music is entered using
174 \begin[options,go,here]@{lilypond@}
183 \lilypondfile[options,go,here]@{@var{filename}@}
190 \lilypond@{ YOUR LILYPOND CODE @}
193 Running @command{lilypond-book} yields a file that can be further
194 processed with La@TeX{}.
196 We show some examples here. The lilypond environment
199 \begin[quote,fragment,staffsize=26]@{lilypond@}
207 @lilypond[quote,fragment,staffsize=26]
214 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
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.
235 @cindex titling and lilypond-book
236 @funindex \header in La@TeX{} documents
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
281 @cindex outline fonts
284 @cindex invoking dvips
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}
292 -o -Ppdf -h @var{file}.psfonts
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
303 @cindex international characters
306 Sometimes it is useful to display music elements (such as ties and slurs)
307 as if they continued after the end of the fragment. This can be done by
308 breaking the staff and suppressing inclusion of the rest of the lilypond
311 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
312 inclusion of other systems is terminated once the required number of
313 systems are included. Since @code{\betweenLilypondSystem} is first
314 called @b{after} the first system, including only the first system
318 \def\betweenLilyPondSystem#1@{\endinput@}
320 \begin[fragment]@{lilypond@}
321 c'1\( e'( c'~ \break c' d) e f\)
325 If a greater number of systems is requested, a TeX conditional must be
326 used before the @code{\endinput}. In this example, replace "2" by
327 the numer of systems you want in the output,
330 \def\betweenLilyPondSystem#1@{
331 \ifnum##1<2\else\endinput\fi
335 Remember that the definition of @code{\betweenLilyPondSystem} is
336 effective until @TeX{} quits the current group (such as the La@TeX{}
337 environment) or is overridden by another definition (which is, in
338 most cases, for the rest of the document). To reset your
342 \let\betweenLilyPondSystem\undefined
346 in your LaTeX source.
348 This may be simplified by defining a @TeX{} macro
351 \def\onlyFirstNSystems#1@{
352 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
357 and then saying only how many systems you want before each fragment,
360 \onlyFirstNSystems@{3@}
361 \begin@{lilypond@}...\end@{lilypond@}
362 \onlyFirstNSystems@{1@}
363 \begin@{lilypond@}...\end@{lilypond@}
367 @node Integrating Texinfo and music
368 @section Integrating Texinfo and music
370 Texinfo is the standard format for documentation of the GNU project. An
371 example of a Texinfo document is this manual. The HTML, PDF, and Info
372 versions of the manual are made from the Texinfo document.
374 In the input file, music is specified with
377 @@lilypond[options,go,here]
386 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
393 @@lilypondfile[options,go,here]@{@var{filename}@}
396 When @command{lilypond-book} is run on it, this results in a Texinfo
397 file (with extension @file{.texi}) containing @code{@@image} tags for
398 HTML and info output. For the printed edition, the raw @TeX{} output of
399 LilyPond is included in the main document.
401 We show two simple examples here. A @code{lilypond} environment
419 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
425 @lilypond[fragment,staffsize=11]{<c' e' g'>}
427 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
428 in-line image. It always gets a paragraph of its own.
430 When using the Texinfo output format, @command{lilypond-book} also
431 generates bitmaps of the music (in PNG format), so you can make an HTML
432 document with embedded music.
435 @node Integrating HTML and music
436 @section Integrating HTML and music
438 Music is entered using
441 <lilypond fragment relative=2>
442 \key c \minor c4 es g2
447 @command{lilypond-book} then produces an HTML file with appropriate image
448 tags for the music fragments:
450 @lilypond[fragment,relative=2]
451 \key c \minor c4 es g2
454 For inline pictures, use @code{<lilypond ... />}, where the options
455 are separated by a colon from the music, for example
458 Some music in <lilypond relative=2: a b c/> a line of text.
461 To include separate files, say
464 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
467 @cindex titling in HTML
468 @cindex preview image
472 @node Music fragment options
473 @section Music fragment options
475 In the following, a ``LilyPond command'' refers to any command described
476 in the previous sections which is handled by @command{lilypond-book} to
477 produce a music snippet. For simplicity, LilyPond commands are only
478 shown in La@TeX{} syntax.
480 Note that the option string is parsed from left to right; if an option
481 occurs multiple times, the last one is taken.
483 The following options are available for LilyPond commands:
486 @item staffsize=@var{ht}
487 Set staff size to @var{ht}, which is measured in points.
490 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
491 = ##t} is added to the LilyPond snippet). This is the default for the
492 @code{\lilypond@{@}} command if no @code{line-width} option is present.
493 It is also the default for the @code{lilypond} environment if the
494 @code{fragment} option is set, and no line width is explicitly
498 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
499 to the LilyPond snippet).
502 @itemx line-width=@var{size}\@var{unit}
503 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
504 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
505 @code{pt}. This option affects LilyPond output (this is, the staff
506 length of the music snippet), not the text layout.
508 If used without an argument, set line width to a default value (as
509 computed with a heuristic algorithm).
511 If no @code{line-width} option is given, @command{lilypond-book} tries to
512 guess a default for @code{lilypond} environments which don't use the
513 @code{ragged-right} option.
516 Do not print the time signature, and turns off the timing (key signature,
517 bar lines) in the score.
520 Make @command{lilypond-book} add some boilerplate code so that you can
528 without @code{\layout}, @code{\score}, etc.
531 Don't add additional code to complete LilyPond code in music snippets.
532 Since this is the default, @code{nofragment} is redundant normally.
534 @item indent=@var{size}\@var{unit}
535 Set indentation of the first music system to @var{size}, using
536 @var{unit} as units. @var{unit} is one of the following strings:
537 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
538 LilyPond, not the text layout.
541 Set indentation of the first music system to zero. This option affects
542 LilyPond, not the text layout. Since no indentation is the default,
543 @code{noindent} is redundant normally.
546 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
547 the output into a quotation block. The value `0.4@dmn{in}' can be
548 controlled with the @code{exampleindent} option.
551 Set the amount by which the @code{quote} option indents a music snippet.
554 @itemx relative=@var{n}
555 Use relative octave mode. By default, notes are specified relative to
556 middle@tie{}C. The optional integer argument specifies the octave of
557 the starting note, where the default @code{1} is middle C.
560 LilyPond also uses @command{lilypond-book} to produce its own
561 documentation. To do that, some more obscure music fragment options are
566 The argument of a LilyPond command is copied to the output file and
567 enclosed in a verbatim block, followed by any text given with the
568 @code{intertext} option (not implemented yet); then the actual music is
569 displayed. This option does not work well with @code{\lilypond@{@}} if
570 it is part of a paragraph.
573 (Only for Texinfo output.) If @command{lilypond} is called with the
574 @option{--header=@/texidoc} option, and the file to be processed is
575 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
576 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
577 option makes @command{lilypond-book} include such files, adding its
578 contents as a documentation block right before the music snippet.
580 Assuming the file @file{foo@/.ly} contains
584 texidoc = "This file demonstrates a single note."
590 and we have this in our Texinfo document @file{test.texinfo}
593 @@lilypondfile[texidoc]@{foo.ly@}
597 the following command line gives the expected result
600 lilypond-book --process="lilypond --format=tex --tex \
601 --header=texidoc test.texinfo
604 Most LilyPond test documents (in the @file{input} directory of the
605 distribution) are small @file{.ly} files which look exactly like this.
608 If a LilyPond input file is included with @code{\lilypondfile}, print
609 the file name right before the music snippet. For HTML output, this is
613 This option includes fonts in all of the generated EPS-files for this
614 snippet. This should be used if the snippet uses any font that LaTeX
615 cannot find on its own.
620 @node Invoking lilypond-book
621 @section Invoking @command{lilypond-book}
623 @command{lilypond-book} produces a file with one of the following
624 extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
625 output format. Both @file{.tex} and @file{.texi} files need further
628 @command{lilypond-book} can also create a PSFONTS file, which is required
629 by @command{dvips} to produce Postscript and PDF files. You can call
630 this file whatever you want as long as you refer to the same file when
631 you call @command{dvips}.
633 To produce PDF output from the lilypond-book file (here called
634 @code{yourfile.lytex}) via LaTeX, you should do
637 lilypond-book --psfonts yourfile.lytex
639 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
643 The @file{.dvi} file created by this process will not contain
644 noteheads. This is normal; if you follow the instructions, they
645 will be included in the @file{.ps} and @file{.pdf} files.
647 To produce a PDF file through PDF(La)TeX, you should pass the options
648 @code{-deps-font-load} and @code{--pdf} to the lilypond process, with
649 the @code{--process} option of lilypond-book, e.g.
652 lilypond-book --process='lilypond -deps-font-load --pdf' yourfile.pdftex
656 To produce a Texinfo document (in any output format), follow the normal
657 procedures for Texinfo (this is, either call @command{texi2dvi} or
658 @command{makeinfo}, depending on the output format you want to
661 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
662 an Info File, , , texinfo, GNU Texinfo}.
665 See the documentation of Texinfo for further details.
669 @command{lilypond-book} accepts the following command line options:
672 @item -f @var{format}
673 @itemx --format=@var{format}
674 Specify the document type to process: @code{html}, @code{latex}, or
675 @code{texi} (the default). If this option is missing,
676 @command{lilypond-book} tries to detect the format automatically.
678 The @code{texi} document type produces a Texinfo file with music
679 fragments in the DVI output only. For getting images in the HTML
680 version, the format @code{texi-html} must be used instead.
682 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
684 @item -F @var{filter}
685 @itemx --filter=@var{filter}
686 Pipe snippets through @var{filter}. @code{lilypond-book} will
687 not --filter and --process at the same time.
691 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
696 Print a short help message.
699 @itemx --include=@var{dir}
700 Add @var{dir} to the include path.
703 @itemx --output=@var{dir}
704 Place generated files in directory @var{dir}. Running
705 @command{lilypond-book} generates lots of small files that LilyPond will
706 process. To avoid all that garbage in the source directory use the
707 @option{--output} command line option, and change to that directory
708 before running @command{latex} or @command{makeinfo}:
711 lilypond-book --output=out yourfile.lytex
716 @item -P @var{process}
717 @itemx --process=@var{command}
718 Process LilyPond snippets using @var{command}. The default command is
719 @code{lilypond}. @code{lilypond-book} will not --filter and --process
723 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
724 This is necessary for @command{dvips -h @var{file}.psfonts}.
732 Print version information.
737 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
738 La@TeX{} commands that change margins and line widths after the preamble
741 Only the first @code{\score} of a LilyPond block is processed.
744 @node Filename extensions
745 @section Filename extensions
747 You can use any filename extension for the input file, but if you do not
748 use the recommended extension for a particular format you may need to
749 manually specify the output format. @xref{Invoking lilypond-book}, for
750 details. Otherwise, @command{lilypond-book} automatically selects the
751 output format based on the input filename's extension.
754 @multitable @columnfractions .2 .5
755 @item @strong{extension} @tab @strong{output format}
757 @item @file{.html} @tab HTML
758 @item @file{.itely} @tab Texinfo
759 @item @file{.latex} @tab La@TeX{}
760 @item @file{.lytex} @tab La@TeX{}
761 @item @file{.tely} @tab Texinfo
762 @item @file{.tex} @tab La@TeX{}
763 @item @file{.texi} @tab Texinfo
764 @item @file{.texinfo} @tab Texinfo
765 @item @file{.xml} @tab HTML