1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Note: keep this node named so that `info lilypond-book' brings you here.
15 @chapter Running @command{lilypond-book}
17 If you want to add pictures of music to a document, you can simply do it
18 the way you would do with other types of pictures. The pictures are
19 created separately, yielding PostScript output or PNG images, and those
20 are included into a @LaTeX{} or HTML document.
22 @command{lilypond-book} provides a way to automate this process: This
23 program extracts snippets of music from your document, runs
24 @command{lilypond} on them, and outputs the document with pictures
25 substituted for the music. The line width and font size definitions for
26 the music are adjusted to match the layout of your document.
28 This is a separate program from @command{lilypond} itself, and is run
29 on the command line; for more information, see
30 @ref{Command-line usage}. If you have trouble running
31 @code{lilypond-book} on Windows or Mac OS X using the command line, then
32 see either @rweb{Windows} or @rweb{MacOS X}.
34 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
43 @cindex documents, adding music
44 @cindex HTML, adding music
45 @cindex Texinfo, adding music
46 @cindex DocBook, adding music
47 @cindex LaTeX, adding music
50 * An example of a musicological document::
51 * Integrating music and text::
52 * Music fragment options::
53 * Invoking lilypond-book::
54 * Filename extensions::
55 * lilypond-book templates::
56 * Sharing the table of contents::
57 * Alternate methods of mixing text and music::
61 @node An example of a musicological document
62 @section An example of a musicological document
65 Some texts contain music examples. These texts are musicological
66 treatises, songbooks, or manuals like this. Such texts can be made by
67 hand, simply by importing a PostScript figure into the word processor.
68 However, there is an automated procedure to reduce the amount of work
69 involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
71 A script called @code{lilypond-book} will extract the music fragments,
72 format them, and put back the resulting notation. Here we show a small
73 example for use with @LaTeX{}. The example also contains explanatory
74 text, so we will not comment on it further.
80 \documentclass[a4paper]{article}
84 Documents for \verb+lilypond-book+ may freely mix music and text.
89 c2 e2 \times 2/3 { f8 a b } a2 e4
93 Options are put in brackets.
95 \begin{lilypond}[fragment,quote,staffsize=26,verbatim]
99 Larger examples can be put into a separate file, and introduced with
100 \verb+\lilypondfile+.
102 \lilypondfile[quote,noindent]{screech-and-boink.ly}
104 (If needed, replace @file{screech-and-boink.ly} by any @file{.ly} file
105 you put in the same directory as this file.)
111 @subheading Processing
113 Save the code above to a file called @file{lilybook.lytex}, then in a
116 @c keep space after @version{} so TeX doesn't choke
118 lilypond-book --output=out --pdf lilybook.lytex
119 @emph{lilypond-book (GNU LilyPond) @version{} }
120 @emph{Reading lilybook.lytex...}
121 @emph{..lots of stuff deleted..}
122 @emph{Compiling lilybook.tex...}
125 @emph{..lots of stuff deleted..}
127 @emph{(replace @command{xpdf} by your favorite PDF viewer)}
130 Running @command{lilypond-book} and @command{latex} creates a lot of
131 temporary files, which would clutter up the working directory. To
132 remedy this, use the @option{--output=@var{dir}} option. It will create
133 the files in a separate subdirectory @file{dir}.
135 Finally the result of the @LaTeX{} example shown above.@footnote{This
136 tutorial is processed with Texinfo, so the example gives slightly
137 different results in layout.} This finishes the tutorial section.
143 Documents for @command{lilypond-book} may freely mix music and text.
148 c2 e2 \times 2/3 { f8 a b } a2 e4
152 Options are put in brackets.
154 @lilypond[fragment,quote,staffsize=26,verbatim]
158 Larger examples can be put into a separate file, and introduced with
159 @code{\lilypondfile}.
161 @lilypondfile[quote,noindent]{screech-and-boink.ly}
163 If a @code{tagline} is required, either default or custom, then the
164 entire snippet must be enclosed in a @code{\book @{ @}} construct.
166 @lilypond[papersize=a8,verbatim]
169 title = "A scale in LilyPond"
180 @node Integrating music and text
181 @section Integrating music and text
183 Here we explain how to integrate LilyPond with various output formats.
195 @LaTeX{} is the de-facto standard for publishing layouts in the exact
196 sciences. It is built on top of the @TeX{} typesetting engine,
197 providing the best typography available anywhere.
200 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
201 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
204 @code{lilypond-book} provides the following commands and environments to
205 include music in @LaTeX{} files:
210 the @code{\lilypond@{...@}} command, where you can directly enter short
214 the @code{\begin@{lilypond@}...\end@{lilypond@}} environment, where you
215 can directly enter longer lilypond code
218 the @code{\lilypondfile@{...@}} command to insert a lilypond file
221 the @code{\musicxmlfile@{...@}} command to insert a MusicXML file, which
222 will be processed by @code{musicxml2ly} and @code{lilypond}.
226 In the input file, music is specified with any of the following commands:
229 \begin@{lilypond@}[options,go,here]
233 \lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
235 \lilypondfile[options,go,here]@{@var{filename}@}
237 \musicxmlfile[options,go,here]@{@var{filename}@}
243 Additionally, @code{\lilypondversion} displays the current version
245 Running @command{lilypond-book} yields a file that can be further
246 processed with @LaTeX{}.
248 We show some examples here. The @code{lilypond} environment
251 \begin@{lilypond@}[quote,fragment,staffsize=26]
259 @lilypond[quote,fragment,staffsize=26]
266 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
272 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
275 Currently, you cannot include @code{@{} or @code{@}} within
276 @code{\lilypond@{@}}, so this command is only useful with the
277 @code{fragment} option.
279 The default line width of the music will be adjusted by examining the
280 commands in the document preamble, the part of the document before
281 @code{\begin@{document@}}. The @command{lilypond-book} command sends
282 these to @LaTeX{} to find out how wide the text is. The line width for
283 the music fragments is then adjusted to the text width. Note that this
284 heuristic algorithm can fail easily; in such cases it is necessary to
285 use the @code{line-width} music fragment option.
287 @cindex titling and lilypond-book
288 @cindex \header in @LaTeX{} documents
290 Each snippet will call the following macros if they have been defined by
294 @item @code{\preLilyPondExample} called before the music,
296 @item @code{\postLilyPondExample} called after the music,
298 @item @code{\betweenLilyPondSystem[1]} is called between systems if
299 @code{lilypond-book} has split the snippet into several PostScript
300 files. It must be defined as taking one parameter and will be
301 passed the number of files already included in this snippet.
302 The default is to simply insert a @code{\linebreak}.
308 @cindex Latex, feta symbols
311 To include feta symbols (such as flat, segno, etc) in a LaTeX
312 document, use @code{\input@{titledefs@}}
315 \documentclass[a4paper]@{article@}
326 The font symbol names are defined in the file feta20.tex; to find
327 the location of this file, use the command
337 Sometimes it is useful to display music elements (such as ties and slurs)
338 as if they continued after the end of the fragment. This can be done by
339 breaking the staff and suppressing inclusion of the rest of the LilyPond
342 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
343 inclusion of other systems is terminated once the required number of
344 systems are included. Since @code{\betweenLilyPondSystem} is first
345 called @emph{after} the first system, including only the first system
349 \def\betweenLilyPondSystem#1@{\endinput@}
351 \begin@{lilypond@}[fragment]
352 c'1\( e'( c'~ \break c' d) e f\)
356 If a greater number of systems is requested, a @TeX{} conditional must
357 be used before the @code{\endinput}. In this example, replace @q{2} by
358 the number of systems you want in the output.
361 \def\betweenLilyPondSystem#1@{
362 \ifnum#1<2\else\expandafter\endinput\fi
367 (Since @code{\endinput} immediately stops the processing of the current
368 input file we need @code{\expandafter} to delay the call of @code{\endinput}
369 after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
372 Remember that the definition of @code{\betweenLilyPondSystem} is
373 effective until @TeX{} quits the current group (such as the @LaTeX{}
374 environment) or is overridden by another definition (which is, in
375 most cases, for the rest of the document). To reset your
379 \let\betweenLilyPondSystem\undefined
383 in your @LaTeX{} source.
385 This may be simplified by defining a @TeX{} macro
388 \def\onlyFirstNSystems#1@{
389 \def\betweenLilyPondSystem##1@{%
390 \ifnum##1<#1\else\expandafter\endinput\fi@}
395 and then saying only how many systems you want before each fragment,
398 \onlyFirstNSystems@{3@}
399 \begin@{lilypond@}...\end@{lilypond@}
400 \onlyFirstNSystems@{1@}
401 \begin@{lilypond@}...\end@{lilypond@}
406 There are specific @command{lilypond-book} command line options and
407 other details to know when processing @LaTeX{} documents, see
408 @ref{Invoking lilypond-book}.
414 Texinfo is the standard format for documentation of the GNU project. An
415 example of a Texinfo document is this manual. The HTML, PDF, and Info
416 versions of the manual are made from the Texinfo document.
418 @code{lilypond-book} provides the following commands and environments to
419 include music into Texinfo files:
424 the @code{@@lilypond@{...@}} command, where you can directly enter short
428 the @code{@@lilypond...@@end lilypond} environment, where you can directly
429 enter longer lilypond code
432 the @code{@@lilypondfile@{...@}} command to insert a lilypond file
435 the @code{@@musicxmlfile@{...@}} command to insert a MusicXML file, which
436 will be processed by @code{musicxml2ly} and @code{lilypond}.
440 In the input file, music is specified with any of the following commands
443 @@lilypond[options,go,here]
447 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
449 @@lilypondfile[options,go,here]@{@var{filename}@}
451 @@musicxmlfile[options,go,here]@{@var{filename}@}
454 Additionally, @code{@@lilypondversion} displays the current version
457 When @command{lilypond-book} is run on it, this results in a Texinfo
458 file (with extension @file{.texi}) containing @code{@@image} tags for
459 HTML, Info and printed output. @command{lilypond-book} generates images
460 of the music in EPS and PDF formats for use in the printed output, and
461 in PNG format for use in HTML and Info output.
463 We show two simple examples here. A @code{lilypond} environment
481 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
487 @lilypond[fragment,staffsize=11]{<c' e' g'>}
489 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
490 in-line image. It always gets a paragraph of its own.
496 @code{lilypond-book} provides the following commands and environments to
497 include music in HTML files:
502 the @code{<lilypond ... />} command, where you can directly enter short
506 the @code{<lilyond>...</lilypond>} environment, where you can directly
507 enter longer lilypond code
510 the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file
513 the @code{<musicxmlfile>...</musicxmlfile>} command to insert a MusicXML
514 file, which will be processed by @code{musicxml2ly} and @code{lilypond}.
518 In the input file, music is specified with any of the following commands:
521 <lilypond options go here>
525 <lilypond options go here: YOUR LILYPOND CODE />
527 <lilypondfile options go here>@var{filename}</lilypondfile>
529 <musicxmlfile options go here>@var{filename}</musicxmlfile>
532 For example, you can write
534 <lilypond fragment relative=2>
535 \key c \minor c4 es g2
540 @command{lilypond-book} then produces an HTML file with appropriate image
541 tags for the music fragments:
543 @lilypond[fragment,relative=2]
544 \key c \minor c4 es g2
547 For inline pictures, use @code{<lilypond ... />}, where the options
548 are separated by a colon from the music, for example
551 Some music in <lilypond relative=2: a b c/> a line of text.
554 To include separate files, say
557 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
560 @code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but
561 simply references a MusicXML file rather than a LilyPond file.
563 For a list of options to use with the @code{lilypond} or
564 @code{lilypondfile} tags, see @ref{Music fragment options}.
566 Additionally, @code{<lilypondversion/>} displays the current version
570 @cindex titling in HTML
571 @cindex preview image
577 For inserting LilyPond snippets it is good to keep the conformity of our
578 DocBook document, thus allowing us to use DocBook editors, validation
579 etc. So we don't use custom tags, only specify a convention based on the
580 standard DocBook elements.
582 @subheading Common conventions
584 For inserting all type of snippets we use the @code{mediaobject} and
585 @code{inlinemediaobject} element, so our snippets can be formatted
586 inline or not inline. The snippet formatting options are always
587 provided in the @code{role} property of the innermost element (see in
588 next sections). Tags are chosen to allow DocBook editors format the
589 content gracefully. The DocBook files to be processed with
590 @command{lilypond-book} should have the extension @file{.lyxml}.
592 @subheading Including a LilyPond file
594 This is the most simple case. We must use the @file{.ly} extension for
595 the included file, and insert it as a standard @code{imageobject}, with
596 the following structure:
601 <imagedata fileref="music1.ly" role="printfilename" />
606 Note that you can use @code{mediaobject} or @code{inlinemediaobject}
607 as the outermost element as you wish.
609 @subheading Including LilyPond code
611 Including LilyPond code is possible by using a @code{programlisting},
612 where the language is set to @code{lilypond} with the following
618 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
619 \context Staff \with @{
620 \remove Time_signature_engraver
621 \remove Clef_engraver@}
628 As you can see, the outermost element is a @code{mediaobject} or
629 @code{inlinemediaobject}, and there is a @code{textobject} containing
630 the @code{programlisting} inside.
632 @subheading Processing the DocBook document
634 Running @command{lilypond-book} on our @file{.lyxml} file will create a
635 valid DocBook document to be further processed with @file{.xml}
636 extension. If you use
637 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
638 PDF file from this document automatically. For HTML (HTML Help,
639 JavaHelp etc.) generation you can use the official DocBook XSL
640 stylesheets, however, it is possible that you have to make some
641 customization for it.
644 @node Music fragment options
645 @section Music fragment options
647 In the following, a @q{LilyPond command} refers to any command described
648 in the previous sections which is handled by @command{lilypond-book} to
649 produce a music snippet. For simplicity, LilyPond commands are only
650 shown in @LaTeX{} syntax.
652 Note that the option string is parsed from left to right; if an option
653 occurs multiple times, the last one is taken.
655 The following options are available for LilyPond commands:
658 @item staffsize=@var{ht}
659 Set staff size to @var{ht}, which is measured in points.
662 Produce ragged-right lines with natural spacing, i.e.,
663 @code{ragged-right = ##t} is added to the LilyPond snippet. Single-line
664 snippets will always be typeset by default as ragged-right, unless
665 @code{noragged-right} is explicitly given.
668 For single-line snippets, allow the staff length to be stretched to
669 equal that of the line width, i.e., @code{ragged-right = ##f} is
670 added to the LilyPond snippet.
673 @itemx line-width=@var{size}\@var{unit}
674 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
675 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
676 @code{pt}. This option affects LilyPond output (this is, the staff
677 length of the music snippet), not the text layout.
679 If used without an argument, set line width to a default value (as
680 computed with a heuristic algorithm).
682 If no @code{line-width} option is given, @command{lilypond-book} tries to
683 guess a default for @code{lilypond} environments which don't use the
684 @code{ragged-right} option.
686 @item papersize=@var{string}
687 Where @var{string} is a paper size defined in @file{scm/paper.scm} i.e.
688 @code{a5}, @code{quarto}, @code{11x17} etc.
690 Values not defined in @file{scm/paper.scm} will be ignored, a warning
691 will be posted and the snippet will be printed using the default
695 Do not print the time signature, and turns off the timing (time signature,
696 bar lines) in the score.
699 Make @command{lilypond-book} add some boilerplate code so that you can
707 without @code{\layout}, @code{\score}, etc.
710 Do not add additional code to complete LilyPond code in music snippets.
711 Since this is the default, @code{nofragment} is redundant normally.
713 @item indent=@var{size}\@var{unit}
714 Set indentation of the first music system to @var{size}, using
715 @var{unit} as units. @var{unit} is one of the following strings:
716 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
717 LilyPond, not the text layout.
720 Set indentation of the first music system to zero. This option affects
721 LilyPond, not the text layout. Since no indentation is the default,
722 @code{noindent} is redundant normally.
725 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
726 the output into a quotation block. The value @q{0.4@dmn{in}} can be
727 controlled with the @code{exampleindent} option.
730 Set the amount by which the @code{quote} option indents a music snippet.
733 @itemx relative=@var{n}
734 Use relative octave mode. By default, notes are specified relative to
735 middle@tie{}C. The optional integer argument specifies the octave of
736 the starting note, where the default @code{1} is middle C.
737 @code{relative} option only works when @code{fragment} option is set,
738 so @code{fragment} is automatically implied by @code{relative},
739 regardless of the presence of any @code{(no)fragment} option in the
743 LilyPond also uses @command{lilypond-book} to produce its own
744 documentation. To do that, some more obscure music fragment options are
749 The argument of a LilyPond command is copied to the output file and
750 enclosed in a verbatim block, followed by any text given with the
751 @code{intertext} option (not implemented yet); then the actual music is
752 displayed. This option does not work well with @code{\lilypond@{@}} if
753 it is part of a paragraph.
755 If @code{verbatim} is used in a @code{lilypondfile} command, it is
756 possible to enclose verbatim only a part of the source file. If the
757 source file contain a comment containing @samp{begin verbatim} (without
758 quotes), quoting the source in the verbatim block will start after the
759 last occurrence of such a comment; similarly, quoting the source verbatim
760 will stop just before the first occurrence of a comment containing
761 @samp{end verbatim}, if there is any. In the following source file
762 example, the music will be interpreted in relative mode, but the
763 verbatim quote will not show the @code{relative} block, i.e.
766 \relative c' @{ % begin verbatim
773 will be printed with a verbatim block like
781 If you would like to translate comments and variable names in verbatim
782 output but not in the sources, you may set the environment variable
783 @code{LYDOC_LOCALEDIR} to a directory path; the directory should
784 contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
788 (Only for Texinfo output.) Prepend line @code{\version
789 @@w@{"@@version@{@}"@}} to @code{verbatim} output.
792 (Only for Texinfo output.) If @command{lilypond} is called with the
793 @option{--header=@/texidoc} option, and the file to be processed is
794 called @file{foo.ly}, it creates a file @file{foo.texidoc} if there
795 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
796 option makes @command{lilypond-book} include such files, adding its
797 contents as a documentation block right before the music snippet (but
798 outside the @code{example} environment generated by a @code{quote}
801 Assuming the file @file{foo.ly} contains
805 texidoc = "This file demonstrates a single note."
811 and we have this in our Texinfo document @file{test.texinfo}
814 @@lilypondfile[texidoc]@{foo.ly@}
818 the following command line gives the expected result
821 lilypond-book --pdf --process="lilypond \
822 -dbackend=eps --header=texidoc" test.texinfo
825 Most LilyPond test documents (in the @file{input} directory of the
826 distribution) are small @file{.ly} files which look exactly like this.
828 For localization purpose, if the Texinfo document contains
829 @code{@@documentlanguage @var{LANG}} and @file{foo.ly} header
830 contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
831 is called with @option{--header=@/texidoc@var{LANG}}, then
832 @file{foo.texidoc@var{LANG}} will be included instead of
836 (Only for Texinfo output.) This option works similarly to
837 @code{texidoc} option: if @command{lilypond} is called with the
838 @option{--header=@/doctitle} option, and the file to be processed is
839 called @file{foo.ly} and contains a @code{doctitle} field in the
840 @code{\header}, it creates a file @file{foo.doctitle}. When
841 @code{doctitle} option is used, the contents of @file{foo.doctitle},
842 which should be a single line of @var{text}, is inserted in the
843 Texinfo document as @code{@@lydoctitle @var{text}}.
844 @code{@@lydoctitle} should be a macro defined in the Texinfo document.
845 The same remark about @code{texidoc} processing with localized
846 languages also applies to @code{doctitle}.
849 (Only for Texinfo output.) Do not translate comments and variable
850 names in the snippet quoted verbatim.
853 If a LilyPond input file is included with @code{\lilypondfile}, print
854 the file name right before the music snippet. For HTML output, this
855 is a link. Only the base name of the file is printed, i.e. the
856 directory part of the file path is stripped.
861 @node Invoking lilypond-book
862 @section Invoking @command{lilypond-book}
864 @command{lilypond-book} produces a file with one of the following
865 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
866 depending on the output format. All of @file{.tex}, @file{.texi} and
867 @file{.xml} files need further processing.
869 @subheading Format-specific instructions
871 @subsubheading @LaTeX{}
873 There are two ways of processing your @LaTeX{} document for printing or
874 publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
875 PostScript file with @LaTeX{} via a DVI to PostScript translator like
876 @command{dvips}. The first way is simpler and recommended@footnote{Note
877 that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
878 @LaTeX{} document, that is why we explain the two ways.}, and whichever
879 way you use, you can easily convert between PostScript and PDF with
880 tools, like @command{ps2pdf} and @command{pdf2ps} included in
883 To produce a PDF file through PDF@LaTeX{}, use
886 lilypond-book --pdf yourfile.lytex
887 pdflatex yourfile.tex
890 @cindex outline fonts
893 @cindex invoking dvips
894 To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
898 lilypond-book yourfile.lytex
900 dvips -Ppdf yourfile.dvi
905 The @file{.dvi} file created by this process will not contain
906 note heads. This is normal; if you follow the instructions, they
907 will be included in the @file{.ps} and @file{.pdf} files.
909 Running @command{dvips} may produce some warnings about fonts; these
910 are harmless and may be ignored. If you are running @command{latex} in
911 twocolumn mode, remember to add @option{-t landscape} to the
912 @command{dvips} options.
915 The @code{\pageBreak} command will not work within a
916 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment.
918 Many @code{\paper} block variables will also not work within a
919 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment. Use
920 @code{\newcommand} with @code{\betweenLilyPondSystem} in the preamble;
923 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
927 @subsubheading Texinfo
929 To produce a Texinfo document (in any output format), follow the normal
930 procedures for Texinfo; this is, either call @command{texi2pdf} or
931 @command{texi2dvi} or @command{makeinfo}, depending on the output format
934 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
935 an Info File, , , texinfo, GNU Texinfo}.
938 See the documentation of Texinfo for further details.
942 @subheading Command line options
944 @command{lilypond-book} accepts the following command line options:
947 @item -f @var{format}
948 @itemx --format=@var{format}
949 Specify the document type to process: @code{html}, @code{latex},
950 @code{texi} (the default) or @code{docbook}. If this option is missing,
951 @command{lilypond-book} tries to detect the format automatically, see
952 @ref{Filename extensions}. Currently, @code{texi} is the same as
955 @c This complicated detail is not implemented, comment it out -jm
957 The @code{texi} document type produces a Texinfo file with music
958 fragments in the printed output only. For getting images in the HTML
959 version, the format @code{texi-html} must be used instead.
962 @item -F @var{filter}
963 @itemx --filter=@var{filter}
964 Pipe snippets through @var{filter}. @code{lilypond-book} will
965 not --filter and --process at the same time. For example,
968 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
973 Print a short help message.
976 @itemx --include=@var{dir}
977 Add @var{dir} to the include path. @command{lilypond-book} also looks
978 for already compiled snippets in the include path, and does not write
979 them back to the output directory, so in some cases it is necessary to
980 invoke further processing commands such as @command{makeinfo} or
981 @command{latex} with the same @option{-I @var{dir}} options.
983 @item -l @var{loglevel}
984 @itemx --loglevel=@var{loglevel}
985 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
986 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}. If
987 this option is not used, and the environment variable
988 @code{LILYPOND_BOOK_LOGLEVEL} is set, its value is used as the loglevel.
991 @itemx --output=@var{dir}
992 Place generated files in directory @var{dir}. Running
993 @command{lilypond-book} generates lots of small files that LilyPond will
994 process. To avoid all that garbage in the source directory, use the
995 @option{--output} command line option, and change to that directory
996 before running @command{latex} or @command{makeinfo}.
999 lilypond-book --output=out yourfile.lytex
1004 @itemx --skip-lily-check
1005 Do not fail if no lilypond output is found. It is used for LilyPond
1006 Info documentation without images.
1008 @itemx --skip-png-check
1009 Do not fail if no PNG images are found for EPS files. It is used for
1010 LilyPond Info documentation without images.
1012 @itemx --lily-output-dir=@var{dir}
1013 Write lily-XXX files to directory @var{dir}, link into @option{--output}
1014 directory. Use this option to save building time for documents in
1015 different directories which share a lot of identical snippets.
1017 @itemx --lily-loglevel=@var{loglevel}
1018 Set the output verbosity of the invoked @command{lilypond} calls to
1019 @var{loglevel}. Possible values are @code{NONE}, @code{ERROR},
1020 @code{WARNING}, @code{BASIC_PROGRESS}, @code{PROGRESS}, @code{INFO}
1021 (default) and @code{DEBUG}. If this option is not used, and the
1022 environment variable @code{LILYPOND_LOGLEVEL} is set, its value is used
1026 @itemx --info-images-dir=@var{dir}
1027 Format Texinfo output so that Info will look for images of music in
1030 @itemx --latex-program=@var{prog}
1031 Run executable @command{prog} instead of @command{latex}. This is
1032 useful if your document is processed with @command{xelatex}, for
1035 @itemx --left-padding=@var{amount}
1036 Pad EPS boxes by this much. @var{amount} is measured in millimeters,
1037 and is 3.0 by default. This option should be used if the lines of
1038 music stick out of the right margin.
1040 The width of a tightly clipped system can vary, due to notation
1041 elements that stick into the left margin, such as bar numbers and
1042 instrument names. This option will shorten each line and move each
1043 line to the right by the same amount.
1045 @item -P @var{command}
1046 @itemx --process=@var{command}
1047 Process LilyPond snippets using @var{command}. The default command is
1048 @code{lilypond}. @code{lilypond-book} will not @option{--filter} and
1049 @option{--process} at the same time.
1052 Create PDF files for use with PDF@LaTeX{}.
1054 @item --redirect-lilypond-output
1055 By default, output is displayed on the terminal. This option redirects
1056 all output to log files in the same directory as the source files.
1058 @itemx --use-source-file-names
1059 Write snippet output files with the same base name as their source file.
1060 This option works only for snippets included with @code{lilypondfile}
1061 and only if directories implied by @option{--output-dir} and
1062 @option{--lily-output-dir} options are different.
1066 Be verbose. This is equivalent to @code{--loglevel=DEBUG}.
1070 Print version information.
1077 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
1078 @LaTeX{} commands that change margins and line widths after the preamble
1081 Only the first @code{\score} of a LilyPond block is processed.
1084 @node Filename extensions
1085 @section Filename extensions
1087 You can use any filename extension for the input file, but if you do not
1088 use the recommended extension for a particular format you may need to
1089 manually specify the output format; for details, see @ref{Invoking
1090 lilypond-book}. Otherwise, @command{lilypond-book} automatically
1091 selects the output format based on the input filename's extension.
1094 @multitable @columnfractions .2 .5
1095 @item @strong{extension} @tab @strong{output format}
1097 @item @file{.html} @tab HTML
1098 @item @file{.htmly} @tab HTML
1099 @item @file{.itely} @tab Texinfo
1100 @item @file{.latex} @tab @LaTeX{}
1101 @item @file{.lytex} @tab @LaTeX{}
1102 @item @file{.lyxml} @tab DocBook
1103 @item @file{.tely} @tab Texinfo
1104 @item @file{.tex} @tab @LaTeX{}
1105 @item @file{.texi} @tab Texinfo
1106 @item @file{.texinfo} @tab Texinfo
1107 @item @file{.xml} @tab HTML
1111 If you use the same filename extension for the input file than the
1112 extension @command{lilypond-book} uses for the output file, and if the
1113 input file is in the same directory as @command{lilypond-book} working
1114 directory, you must use @option{--output} option to make
1115 @command{lilypond-book} running, otherwise it will exit with an error
1116 message like @qq{Output would overwrite input file}.
1119 @node lilypond-book templates
1120 @section lilypond-book templates
1122 These templates are for use with @code{lilypond-book}. If you're not familiar
1123 with this program, please refer to
1124 @ref{lilypond-book}.
1128 You can include LilyPond fragments in a LaTeX document.
1131 \documentclass[]@{article@}
1143 More LaTeX text, and options in square brackets.
1145 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1153 You can include LilyPond fragments in Texinfo; in fact, this entire manual
1154 is written in Texinfo.
1157 \input texinfo @c -*-texinfo-*-
1169 More Texinfo text, and options in brackets.
1171 @@lilypond[verbatim,fragment,ragged-right]
1182 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1188 Documents for lilypond-book may freely mix music and text. For
1198 Another bit of lilypond, this time with options:
1200 <lilypond fragment quote staffsize=26 verbatim>
1214 \documentclass{article}
1215 \usepackage{ifxetex}
1217 %xetex specific stuff
1218 \usepackage{xunicode,fontspec,xltxtra}
1219 \setmainfont[Numbers=OldStyle]{Times New Roman}
1222 %This can be empty if you are not going to use pdftex
1223 \usepackage[T1]{fontenc}
1224 \usepackage[utf8]{inputenc}
1225 \usepackage{mathptmx}%Times
1226 \usepackage{helvet}%Helvetica
1228 %Here you can insert all packages that pdftex also understands
1229 \usepackage[ngerman,finnish,english]{babel}
1230 \usepackage{graphicx}
1233 \title{A short document with LilyPond and xelatex}
1236 Normal \textbf{font} commands inside the \emph{text} work,
1237 because they \textsf{are supported by \LaTeX{} and XeteX.}
1238 If you want to use specific commands like \verb+\XeTeX+, you
1239 should include them again in a \verb+\ifxetex+ environment.
1240 You can use this to print the \ifxetex \XeTeX{} command \else
1241 XeTeX command \fi which is not known to normal \LaTeX .
1243 In normal text you can easily use LilyPond commands, like this:
1252 The fonts of snippets set with LilyPond will have to be set from
1254 of the snippet. For this you should read the AU on how to use
1257 \selectlanguage{ngerman}
1258 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1260 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1261 unterst__tzt werden.
1266 @node Sharing the table of contents
1267 @section Sharing the table of contents
1269 These functions already exist in the OrchestralLily package:
1272 @url{http://repo.or.cz/w/orchestrallily.git}
1275 For greater flexibility in text handling, some users prefer to
1276 export the table of contents from lilypond and read it into
1279 @subsubheading Exporting the ToC from LilyPond
1281 This assumes that your score has multiple movements in the same lilypond
1285 #(define (oly:create-toc-file layout pages)
1286 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1287 (if (not (null? label-table))
1288 (let* ((format-line (lambda (toc-item)
1289 (let* ((label (car toc-item))
1290 (text (caddr toc-item))
1291 (label-page (and (list? label-table)
1292 (assoc label label-table)))
1293 (page (and label-page (cdr label-page))))
1294 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1295 (formatted-toc-items (map format-line (toc-items)))
1296 (whole-string (string-join formatted-toc-items ",\n"))
1297 (output-name (ly:parser-output-name parser))
1298 (outfilename (format "~a.toc" output-name))
1299 (outfile (open-output-file outfilename)))
1300 (if (output-port? outfile)
1301 (display whole-string outfile)
1302 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1303 (close-output-port outfile)))))
1306 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1310 @subsubheading Importing the ToC into LaTeX
1312 In LaTeX, the header should include:
1314 @c no, this doesn't require the smallexample, but since the other
1315 @c two blocks on this page use it, I figured I might as well
1316 @c user it here as well, for consistency. -gp
1318 \usepackage@{pdfpages@}
1319 \includescore@{nameofthescore@}
1323 where @code{\includescore} is defined as:
1326 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1327 % \includescore@{PossibleExtension@}
1328 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1330 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1331 % This requires some heave latex tweaking, since reading in things from a file
1332 % and inserting it into the arguments of a macro is not (easily) possible
1334 % Solution by Patrick Fimml on #latex on April 18, 2009:
1335 % \readfile@{filename@}@{\variable@}
1336 % reads in the contents of the file into \variable (undefined if file
1338 \newread\readfile@@f
1339 \def\readfile@@line#1@{%
1340 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1341 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1342 \ifeof\readfile@@f\else%
1343 \readfile@@line@{#1@}%
1346 \def\readfile#1#2@{%
1347 \openin\readfile@@f=#1 %
1349 \typeout@{No TOC file #1 available!@}%
1352 \readfile@@line@{#2@}%
1354 \closein\readfile@@f%
1358 \newcommand@{\includescore@}[1]@{
1359 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1360 \let\oly@@addtotoc\undefined
1361 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1362 \ifx\oly@@addtotoc\undefined
1363 \includepdf[pages=-]@{\oly@@fname@}
1365 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1366 @{\oly@@fname@}@}\includeit
1372 @node Alternate methods of mixing text and music
1373 @section Alternative methods of mixing text and music
1375 Other means of mixing text and music (without
1376 @command{lilypond-book}) are discussed in
1377 @ref{LilyPond output in other programs}.