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 @ref{Command-line
30 usage}. If you have MacOS 10.3 or 10.4 and you have trouble running
31 @code{lilypond-book}, see @rweb{MacOS X}.
33 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
42 @cindex documents, adding music to
43 @cindex HTML, music in
44 @cindex Texinfo, music in
45 @cindex DocBook, music in
46 @cindex @LaTeX{}, music in
49 * An example of a musicological document::
50 * Integrating music and text::
51 * Music fragment options::
52 * Invoking lilypond-book::
53 * Filename extensions::
54 * lilypond-book templates::
55 * Sharing the table of contents::
56 * Alternate methods of mixing text and music::
60 @node An example of a musicological document
61 @section An example of a musicological document
64 Some texts contain music examples. These texts are musicological
65 treatises, songbooks, or manuals like this. Such texts can be made by
66 hand, simply by importing a PostScript figure into the word processor.
67 However, there is an automated procedure to reduce the amount of work
68 involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
70 A script called @code{lilypond-book} will extract the music fragments,
71 format them, and put back the resulting notation. Here we show a small
72 example for use with @LaTeX{}. The example also contains explanatory
73 text, so we will not comment on it further.
79 \documentclass[a4paper]{article}
83 Documents for \verb+lilypond-book+ may freely mix music and text.
88 c2 e2 \times 2/3 { f8 a b } a2 e4
92 Options are put in brackets.
94 \begin{lilypond}[fragment,quote,staffsize=26,verbatim]
98 Larger examples can be put into a separate file, and introduced with
101 \lilypondfile[quote,noindent]{screech-boink.ly}
103 (If needed, replace @file{screech-boink.ly} by any @file{.ly} file
104 you put in the same directory as this file.)
110 @subheading Processing
112 Save the code above to a file called @file{lilybook.lytex}, then in a
115 @c keep space after @version{} so TeX doesn't choke
117 lilypond-book --output=out --pdf lilybook.lytex
118 @emph{lilypond-book (GNU LilyPond) @version{} }
119 @emph{Reading lilybook.lytex...}
120 @emph{..lots of stuff deleted..}
121 @emph{Compiling lilybook.tex...}
124 @emph{..lots of stuff deleted..}
126 @emph{(replace @command{xpdf} by your favorite PDF viewer)}
129 Running @command{lilypond-book} and @command{latex} creates a lot of
130 temporary files, which would clutter up the working directory. To
131 remedy this, use the @option{--output=@var{dir}} option. It will create
132 the files in a separate subdirectory @file{dir}.
134 Finally the result of the @LaTeX{} example shown above.@footnote{This
135 tutorial is processed with Texinfo, so the example gives slightly
136 different results in layout.} This finishes the tutorial section.
142 Documents for @command{lilypond-book} may freely mix music and text.
147 c2 e2 \times 2/3 { f8 a b } a2 e4
151 Options are put in brackets.
153 @lilypond[fragment,quote,staffsize=26,verbatim]
157 Larger examples can be put into a separate file, and introduced with
158 @code{\lilypondfile}.
160 @lilypondfile[quote,noindent]{screech-boink.ly}
162 If a @code{tagline} is required, either default or custom, then the
163 entire snippet must be enclosed in a @code{\book @{ @}} construct.
165 @lilypond[papersize=a8,verbatim]
168 title = "A scale in LilyPond"
179 @node Integrating music and text
180 @section Integrating music and text
182 Here we explain how to integrate LilyPond with various output formats.
194 @LaTeX{} is the de-facto standard for publishing layouts in the exact
195 sciences. It is built on top of the @TeX{} typesetting engine,
196 providing the best typography available anywhere.
199 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
200 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
203 @code{lilypond-book} provides the following commands and environments to include
204 music in @LaTeX{} files:
209 the @code{\lilypond@{...@}} command, where you can directly enter short
213 the @code{\begin@{lilypond@}...\end@{lilypond@}} environment, where you
214 can directly enter longer lilypond code
217 the @code{\lilypondfile@{...@}} command to insert a lilypond file
220 the @code{\musicxmlfile@{...@}} command to insert a MusicXML file, which
221 will be processed by @code{musicxml2ly} and @code{lilypond}.
225 In the input file, music is specified with any of the following commands:
228 \begin@{lilypond@}[options,go,here]
232 \lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
234 \lilypondfile[options,go,here]@{@var{filename}@}
236 \musicxmlfile[options,go,here]@{@var{filename}@}
242 Additionally, @code{\lilypondversion} displays the current version
244 Running @command{lilypond-book} yields a file that can be further
245 processed with @LaTeX{}.
247 We show some examples here. The @code{lilypond} environment
250 \begin@{lilypond@}[quote,fragment,staffsize=26]
258 @lilypond[quote,fragment,staffsize=26]
265 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
271 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
274 Currently, you cannot include @code{@{} or @code{@}} within
275 @code{\lilypond@{@}}, so this command is only useful with the
276 @code{fragment} option.
278 The default line width of the music will be adjusted by examining the
279 commands in the document preamble, the part of the document before
280 @code{\begin@{document@}}. The @command{lilypond-book} command sends
281 these to @LaTeX{} to find out how wide the text is. The line width for
282 the music fragments is then adjusted to the text width. Note that this
283 heuristic algorithm can fail easily; in such cases it is necessary to
284 use the @code{line-width} music fragment option.
286 @cindex titling and lilypond-book
287 @cindex \header in @LaTeX{} documents
289 Each snippet will call the following macros if they have been defined by
293 @item @code{\preLilyPondExample} called before the music,
295 @item @code{\postLilyPondExample} called after the music,
297 @item @code{\betweenLilyPondSystem[1]} is called between systems if
298 @code{lilypond-book} has split the snippet into several PostScript
299 files. It must be defined as taking one parameter and will be
300 passed the number of files already included in this snippet.
301 The default is to simply insert a @code{\linebreak}.
307 @cindex Latex, feta symbols
310 To include feta symbols (such as flat, segno, etc) in a LaTeX
311 document, use @code{\input@{titledefs@}}
314 \documentclass[a4paper]@{article@}
325 The font symbol names are defined in the file feta20.tex; to find
326 the location of this file, use the command
336 Sometimes it is useful to display music elements (such as ties and slurs)
337 as if they continued after the end of the fragment. This can be done by
338 breaking the staff and suppressing inclusion of the rest of the LilyPond
341 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
342 inclusion of other systems is terminated once the required number of
343 systems are included. Since @code{\betweenLilyPondSystem} is first
344 called @emph{after} the first system, including only the first system
348 \def\betweenLilyPondSystem#1@{\endinput@}
350 \begin@{lilypond@}[fragment]
351 c'1\( e'( c'~ \break c' d) e f\)
355 If a greater number of systems is requested, a @TeX{} conditional must
356 be used before the @code{\endinput}. In this example, replace @q{2} by
357 the number of systems you want in the output.
360 \def\betweenLilyPondSystem#1@{
361 \ifnum#1<2\else\expandafter\endinput\fi
366 (Since @code{\endinput} immediately stops the processing of the current
367 input file we need @code{\expandafter} to delay the call of @code{\endinput}
368 after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
371 Remember that the definition of @code{\betweenLilyPondSystem} is
372 effective until @TeX{} quits the current group (such as the @LaTeX{}
373 environment) or is overridden by another definition (which is, in
374 most cases, for the rest of the document). To reset your
378 \let\betweenLilyPondSystem\undefined
382 in your @LaTeX{} source.
384 This may be simplified by defining a @TeX{} macro
387 \def\onlyFirstNSystems#1@{
388 \def\betweenLilyPondSystem##1@{%
389 \ifnum##1<#1\else\expandafter\endinput\fi@}
394 and then saying only how many systems you want before each fragment,
397 \onlyFirstNSystems@{3@}
398 \begin@{lilypond@}...\end@{lilypond@}
399 \onlyFirstNSystems@{1@}
400 \begin@{lilypond@}...\end@{lilypond@}
405 There are specific @command{lilypond-book} command line options and
406 other details to know when processing @LaTeX{} documents, see
407 @ref{Invoking lilypond-book}.
413 Texinfo is the standard format for documentation of the GNU project. An
414 example of a Texinfo document is this manual. The HTML, PDF, and Info
415 versions of the manual are made from the Texinfo document.
417 @code{lilypond-book} provides the following commands and environments to include
418 music into Texinfo files:
423 the @code{@@lilypond@{...@}} command, where you can directly enter short
427 the @code{@@lilypond...@@end lilypond} environment, where you can directly
428 enter longer lilypond code
431 the @code{@@lilypondfile@{...@}} command to insert a lilypond file
434 the @code{@@musicxmlfile@{...@}} command to insert a MusicXML file, which
435 will be processed by @code{musicxml2ly} and @code{lilypond}.
439 In the input file, music is specified with any of the following commands
442 @@lilypond[options,go,here]
446 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
448 @@lilypondfile[options,go,here]@{@var{filename}@}
450 @@musicxmlfile[options,go,here]@{@var{filename}@}
453 Additionally, @code{@@lilypondversion} displays the current version
456 When @command{lilypond-book} is run on it, this results in a Texinfo
457 file (with extension @file{.texi}) containing @code{@@image} tags for
458 HTML, Info and printed output. @command{lilypond-book} generates images
459 of the music in EPS and PDF formats for use in the printed output, and
460 in PNG format for use in HTML and Info output.
462 We show two simple examples here. A @code{lilypond} environment
480 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
486 @lilypond[fragment,staffsize=11]{<c' e' g'>}
488 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
489 in-line image. It always gets a paragraph of its own.
495 @code{lilypond-book} provides the following commands and environments to include
501 the @code{<lilypond ... />} command, where you can directly enter short lilypond code
504 the @code{<lilyond>...</lilypond>} environment, where you can directly enter longer
508 the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file
511 the @code{<musicxmlfile>...</musicxmlfile>} command to insert a MusicXML file, which
512 will be processed by @code{musicxml2ly} and @code{lilypond}.
516 In the input file, music is specified with any of the following commands:
518 \begin@{lilypond@}[options,go,here]
522 \lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
524 \lilypondfile[options,go,here]@{@var{filename}@}
526 \musicxmlfile[options,go,here]@{@var{filename}@}
528 <lilypond options go here>
532 <lilypond options go here: YOUR LILYPOND CODE />
534 <lilypondfile options go here>@var{filename}</lilypondfile>
536 <musicxmlfile options go here>@var{filename}</musicxmlfile>
539 For example, you can write
541 <lilypond fragment relative=2>
542 \key c \minor c4 es g2
547 @command{lilypond-book} then produces an HTML file with appropriate image
548 tags for the music fragments:
550 @lilypond[fragment,relative=2]
551 \key c \minor c4 es g2
554 For inline pictures, use @code{<lilypond ... />}, where the options
555 are separated by a colon from the music, for example
558 Some music in <lilypond relative=2: a b c/> a line of text.
561 To include separate files, say
564 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
567 @code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but simply
568 references a MusicXML file rather than a LilyPond file.
570 For a list of options to use with the @code{lilypond} or
571 @code{lilypondfile} tags, see @ref{Music fragment options}.
573 Additionally, @code{<lilypondversion/>} displays the current version
577 @cindex titling in HTML
578 @cindex preview image
584 For inserting LilyPond snippets it is good to keep the conformity of our
585 DocBook document, thus allowing us to use DocBook editors, validation
586 etc. So we don't use custom tags, only specify a convention based on the
587 standard DocBook elements.
589 @subheading Common conventions
591 For inserting all type of snippets we use the @code{mediaobject} and
592 @code{inlinemediaobject} element, so our snippets can be formatted
593 inline or not inline. The snippet formatting options are always
594 provided in the @code{role} property of the innermost element (see in
595 next sections). Tags are chosen to allow DocBook editors format the
596 content gracefully. The DocBook files to be processed with
597 @command{lilypond-book} should have the extension @file{.lyxml}.
599 @subheading Including a LilyPond file
601 This is the most simple case. We must use the @file{.ly} extension for
602 the included file, and insert it as a standard @code{imageobject}, with
603 the following structure:
608 <imagedata fileref="music1.ly" role="printfilename" />
613 Note that you can use @code{mediaobject} or @code{inlinemediaobject}
614 as the outermost element as you wish.
616 @subheading Including LilyPond code
618 Including LilyPond code is possible by using a @code{programlisting},
619 where the language is set to @code{lilypond} with the following
625 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
626 \context Staff \with @{
627 \remove Time_signature_engraver
628 \remove Clef_engraver@}
635 As you can see, the outermost element is a @code{mediaobject} or
636 @code{inlinemediaobject}, and there is a @code{textobject} containing
637 the @code{programlisting} inside.
639 @subheading Processing the DocBook document
641 Running @command{lilypond-book} on our @file{.lyxml} file will create a
642 valid DocBook document to be further processed with @file{.xml}
643 extension. If you use
644 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
645 PDF file from this document automatically. For HTML (HTML Help,
646 JavaHelp etc.) generation you can use the official DocBook XSL
647 stylesheets, however, it is possible that you have to make some
648 customization for it.
651 @node Music fragment options
652 @section Music fragment options
654 In the following, a @q{LilyPond command} refers to any command described
655 in the previous sections which is handled by @command{lilypond-book} to
656 produce a music snippet. For simplicity, LilyPond commands are only
657 shown in @LaTeX{} syntax.
659 Note that the option string is parsed from left to right; if an option
660 occurs multiple times, the last one is taken.
662 The following options are available for LilyPond commands:
665 @item staffsize=@var{ht}
666 Set staff size to @var{ht}, which is measured in points.
669 Produce ragged-right lines with natural spacing, i.e.,
670 @code{ragged-right = ##t} is added to the LilyPond snippet. Single-line
671 snippets will always be typeset by default as ragged-right, unless
672 @code{noragged-right} is explicitly given.
675 For single-line snippets, allow the staff length to be stretched to
676 equal that of the line width, i.e., @code{ragged-right = ##f} is
677 added to the LilyPond snippet.
680 @itemx line-width=@var{size}\@var{unit}
681 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
682 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
683 @code{pt}. This option affects LilyPond output (this is, the staff
684 length of the music snippet), not the text layout.
686 If used without an argument, set line width to a default value (as
687 computed with a heuristic algorithm).
689 If no @code{line-width} option is given, @command{lilypond-book} tries to
690 guess a default for @code{lilypond} environments which don't use the
691 @code{ragged-right} option.
693 @item papersize=@var{string}
694 Where @var{string} is a paper size defined in @file{scm/paper.scm} i.e.
695 @code{a5}, @code{quarto}, @code{11x17} etc.
697 Values not defined in @file{scm/paper.scm} will be ignored, a warning
698 will be posted and the snippet will be printed using the default
702 Do not print the time signature, and turns off the timing (time signature,
703 bar lines) in the score.
706 Make @command{lilypond-book} add some boilerplate code so that you can
714 without @code{\layout}, @code{\score}, etc.
717 Do not add additional code to complete LilyPond code in music snippets.
718 Since this is the default, @code{nofragment} is redundant normally.
720 @item indent=@var{size}\@var{unit}
721 Set indentation of the first music system to @var{size}, using
722 @var{unit} as units. @var{unit} is one of the following strings:
723 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
724 LilyPond, not the text layout.
727 Set indentation of the first music system to zero. This option affects
728 LilyPond, not the text layout. Since no indentation is the default,
729 @code{noindent} is redundant normally.
732 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
733 the output into a quotation block. The value @q{0.4@dmn{in}} can be
734 controlled with the @code{exampleindent} option.
737 Set the amount by which the @code{quote} option indents a music snippet.
740 @itemx relative=@var{n}
741 Use relative octave mode. By default, notes are specified relative to
742 middle@tie{}C. The optional integer argument specifies the octave of
743 the starting note, where the default @code{1} is middle C.
744 @code{relative} option only works when @code{fragment} option is set,
745 so @code{fragment} is automatically implied by @code{relative},
746 regardless of the presence of any @code{(no)fragment} option in the
750 LilyPond also uses @command{lilypond-book} to produce its own
751 documentation. To do that, some more obscure music fragment options are
756 The argument of a LilyPond command is copied to the output file and
757 enclosed in a verbatim block, followed by any text given with the
758 @code{intertext} option (not implemented yet); then the actual music is
759 displayed. This option does not work well with @code{\lilypond@{@}} if
760 it is part of a paragraph.
762 If @code{verbatim} is used in a @code{lilypondfile} command, it is
763 possible to enclose verbatim only a part of the source file. If the
764 source file contain a comment containing @samp{begin verbatim} (without
765 quotes), quoting the source in the verbatim block will start after the
766 last occurrence of such a comment; similarly, quoting the source verbatim
767 will stop just before the first occurrence of a comment containing
768 @samp{end verbatim}, if there is any. In the following source file
769 example, the music will be interpreted in relative mode, but the
770 verbatim quote will not show the @code{relative} block, i.e.
773 \relative c' @{ % begin verbatim
780 will be printed with a verbatim block like
788 If you would like to translate comments and variable names in verbatim
789 output but not in the sources, you may set the environment variable
790 @code{LYDOC_LOCALEDIR} to a directory path; the directory should
791 contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
795 (Only for Texinfo output.) Prepend line @code{\version
796 @@w@{"@@version@{@}"@}} to @code{verbatim} output.
799 (Only for Texinfo output.) If @command{lilypond} is called with the
800 @option{--header=@/texidoc} option, and the file to be processed is
801 called @file{foo.ly}, it creates a file @file{foo.texidoc} if there
802 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
803 option makes @command{lilypond-book} include such files, adding its
804 contents as a documentation block right before the music snippet (but
805 outside the @code{example} environment generated by a @code{quote}
808 Assuming the file @file{foo.ly} contains
812 texidoc = "This file demonstrates a single note."
818 and we have this in our Texinfo document @file{test.texinfo}
821 @@lilypondfile[texidoc]@{foo.ly@}
825 the following command line gives the expected result
828 lilypond-book --pdf --process="lilypond \
829 -dbackend=eps --header=texidoc" test.texinfo
832 Most LilyPond test documents (in the @file{input} directory of the
833 distribution) are small @file{.ly} files which look exactly like this.
835 For localization purpose, if the Texinfo document contains
836 @code{@@documentlanguage @var{LANG}} and @file{foo.ly} header
837 contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
838 is called with @option{--header=@/texidoc@var{LANG}}, then
839 @file{foo.texidoc@var{LANG}} will be included instead of
843 (Only for Texinfo output.) This option works similarly to
844 @code{texidoc} option: if @command{lilypond} is called with the
845 @option{--header=@/doctitle} option, and the file to be processed is
846 called @file{foo.ly} and contains a @code{doctitle} field in the
847 @code{\header}, it creates a file @file{foo.doctitle}. When
848 @code{doctitle} option is used, the contents of @file{foo.doctitle},
849 which should be a single line of @var{text}, is inserted in the
850 Texinfo document as @code{@@lydoctitle @var{text}}.
851 @code{@@lydoctitle} should be a macro defined in the Texinfo document.
852 The same remark about @code{texidoc} processing with localized
853 languages also applies to @code{doctitle}.
856 (Only for Texinfo output.) Do not translate comments and variable
857 names in the snippet quoted verbatim.
860 If a LilyPond input file is included with @code{\lilypondfile}, print
861 the file name right before the music snippet. For HTML output, this
862 is a link. Only the base name of the file is printed, i.e. the
863 directory part of the file path is stripped.
868 @node Invoking lilypond-book
869 @section Invoking @command{lilypond-book}
871 @command{lilypond-book} produces a file with one of the following
872 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
873 depending on the output format. All of @file{.tex}, @file{.texi} and
874 @file{.xml} files need further processing.
876 @subheading Format-specific instructions
878 @subsubheading @LaTeX{}
880 There are two ways of processing your @LaTeX{} document for printing or
881 publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
882 PostScript file with @LaTeX{} via a DVI to PostScript translator like
883 @command{dvips}. The first way is simpler and recommended@footnote{Note
884 that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
885 @LaTeX{} document, that is why we explain the two ways.}, and whichever
886 way you use, you can easily convert between PostScript and PDF with
887 tools, like @command{ps2pdf} and @command{pdf2ps} included in
890 To produce a PDF file through PDF@LaTeX{}, use
893 lilypond-book --pdf yourfile.lytex
894 pdflatex yourfile.tex
897 @cindex outline fonts
900 @cindex invoking dvips
901 To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
905 lilypond-book yourfile.lytex
907 dvips -Ppdf yourfile.dvi
912 The @file{.dvi} file created by this process will not contain
913 note heads. This is normal; if you follow the instructions, they
914 will be included in the @file{.ps} and @file{.pdf} files.
916 Running @command{dvips} may produce some warnings about fonts; these
917 are harmless and may be ignored. If you are running @command{latex} in
918 twocolumn mode, remember to add @option{-t landscape} to the
919 @command{dvips} options.
921 @subsubheading Texinfo
923 To produce a Texinfo document (in any output format), follow the normal
924 procedures for Texinfo; this is, either call @command{texi2pdf} or
925 @command{texi2dvi} or @command{makeinfo}, depending on the output format
928 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
929 an Info File, , , texinfo, GNU Texinfo}.
932 See the documentation of Texinfo for further details.
936 @subheading Command line options
938 @command{lilypond-book} accepts the following command line options:
941 @item -f @var{format}
942 @itemx --format=@var{format}
943 Specify the document type to process: @code{html}, @code{latex},
944 @code{texi} (the default) or @code{docbook}. If this option is missing,
945 @command{lilypond-book} tries to detect the format automatically, see
946 @ref{Filename extensions}. Currently, @code{texi} is the same as
949 @c This complicated detail is not implemented, comment it out -jm
951 The @code{texi} document type produces a Texinfo file with music
952 fragments in the printed output only. For getting images in the HTML
953 version, the format @code{texi-html} must be used instead.
956 @item -F @var{filter}
957 @itemx --filter=@var{filter}
958 Pipe snippets through @var{filter}. @code{lilypond-book} will
959 not --filter and --process at the same time. For example,
962 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
967 Print a short help message.
970 @itemx --include=@var{dir}
971 Add @var{dir} to the include path. @command{lilypond-book} also looks
972 for already compiled snippets in the include path, and does not write
973 them back to the output directory, so in some cases it is necessary to
974 invoke further processing commands such as @command{makeinfo} or
975 @command{latex} with the same @option{-I @var{dir}} options.
977 @item -l @var{loglevel}
978 @itemx --loglevel=@var{loglevel}
979 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
980 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}. If
981 this option is not used, and the environment variable
982 @code{LILYPOND_BOOK_LOGLEVEL} is set, its value is used as the loglevel.
985 @itemx --output=@var{dir}
986 Place generated files in directory @var{dir}. Running
987 @command{lilypond-book} generates lots of small files that LilyPond will
988 process. To avoid all that garbage in the source directory, use the
989 @option{--output} command line option, and change to that directory
990 before running @command{latex} or @command{makeinfo}.
993 lilypond-book --output=out yourfile.lytex
998 @itemx --skip-lily-check
999 Do not fail if no lilypond output is found. It is used for LilyPond
1000 Info documentation without images.
1002 @itemx --skip-png-check
1003 Do not fail if no PNG images are found for EPS files. It is used for
1004 LilyPond Info documentation without images.
1006 @itemx --lily-output-dir=@var{dir}
1007 Write lily-XXX files to directory @var{dir}, link into @option{--output}
1008 directory. Use this option to save building time for documents in
1009 different directories which share a lot of identical snippets.
1011 @itemx --lily-loglevel=@var{loglevel}
1012 Set the output verbosity of the invoked @command{lilypond} calls to @var{loglevel}.
1013 Possible values are @code{NONE}, @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS},
1014 @code{PROGRESS}, @code{INFO} (default) and @code{DEBUG}. If
1015 this option is not used, and the environment variable
1016 @code{LILYPOND_LOGLEVEL} is set, its value is used as the loglevel.
1019 @itemx --info-images-dir=@var{dir}
1020 Format Texinfo output so that Info will look for images of music in
1023 @itemx --latex-program=@var{prog}
1024 Run executable @command{prog} instead of @command{latex}. This is
1025 useful if your document is processed with @command{xelatex}, for
1028 @itemx --left-padding=@var{amount}
1029 Pad EPS boxes by this much. @var{amount} is measured in millimeters,
1030 and is 3.0 by default. This option should be used if the lines of
1031 music stick out of the right margin.
1033 The width of a tightly clipped system can vary, due to notation
1034 elements that stick into the left margin, such as bar numbers and
1035 instrument names. This option will shorten each line and move each
1036 line to the right by the same amount.
1038 @item -P @var{command}
1039 @itemx --process=@var{command}
1040 Process LilyPond snippets using @var{command}. The default command is
1041 @code{lilypond}. @code{lilypond-book} will not @option{--filter} and
1042 @option{--process} at the same time.
1045 Create PDF files for use with PDF@LaTeX{}.
1047 @item --redirect-lilypond-output
1048 By default, output is displayed on the terminal. This option redirects
1049 all output to log files in the same directory as the source files.
1051 @itemx --use-source-file-names
1052 Write snippet output files with the same base name as their source file.
1053 This option works only for snippets included with @code{lilypondfile}
1054 and only if directories implied by @option{--output-dir} and
1055 @option{--lily-output-dir} options are different.
1059 Be verbose. This is equivalent to @code{--loglevel=DEBUG}.
1063 Print version information.
1070 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
1071 @LaTeX{} commands that change margins and line widths after the preamble
1074 Only the first @code{\score} of a LilyPond block is processed.
1077 @node Filename extensions
1078 @section Filename extensions
1080 You can use any filename extension for the input file, but if you do not
1081 use the recommended extension for a particular format you may need to
1082 manually specify the output format; for details, see @ref{Invoking
1083 lilypond-book}. Otherwise, @command{lilypond-book} automatically
1084 selects the output format based on the input filename's extension.
1087 @multitable @columnfractions .2 .5
1088 @item @strong{extension} @tab @strong{output format}
1090 @item @file{.html} @tab HTML
1091 @item @file{.htmly} @tab HTML
1092 @item @file{.itely} @tab Texinfo
1093 @item @file{.latex} @tab @LaTeX{}
1094 @item @file{.lytex} @tab @LaTeX{}
1095 @item @file{.lyxml} @tab DocBook
1096 @item @file{.tely} @tab Texinfo
1097 @item @file{.tex} @tab @LaTeX{}
1098 @item @file{.texi} @tab Texinfo
1099 @item @file{.texinfo} @tab Texinfo
1100 @item @file{.xml} @tab HTML
1104 If you use the same filename extension for the input file than the
1105 extension @command{lilypond-book} uses for the output file, and if the
1106 input file is in the same directory as @command{lilypond-book} working
1107 directory, you must use @option{--output} option to make
1108 @command{lilypond-book} running, otherwise it will exit with an error
1109 message like @qq{Output would overwrite input file}.
1112 @node lilypond-book templates
1113 @section lilypond-book templates
1115 These templates are for use with @code{lilypond-book}. If you're not familiar
1116 with this program, please refer to
1117 @ref{lilypond-book}.
1121 You can include LilyPond fragments in a LaTeX document.
1124 \documentclass[]@{article@}
1136 More LaTeX text, and options in square brackets.
1138 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1146 You can include LilyPond fragments in Texinfo; in fact, this entire manual
1147 is written in Texinfo.
1150 \input texinfo @c -*-texinfo-*-
1162 More Texinfo text, and options in brackets.
1164 @@lilypond[verbatim,fragment,ragged-right]
1175 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1181 Documents for lilypond-book may freely mix music and text. For
1191 Another bit of lilypond, this time with options:
1193 <lilypond fragment quote staffsize=26 verbatim>
1207 \documentclass{article}
1208 \usepackage{ifxetex}
1210 %xetex specific stuff
1211 \usepackage{xunicode,fontspec,xltxtra}
1212 \setmainfont[Numbers=OldStyle]{Times New Roman}
1215 %This can be empty if you are not going to use pdftex
1216 \usepackage[T1]{fontenc}
1217 \usepackage[utf8]{inputenc}
1218 \usepackage{mathptmx}%Times
1219 \usepackage{helvet}%Helvetica
1221 %Here you can insert all packages that pdftex also understands
1222 \usepackage[ngerman,finnish,english]{babel}
1223 \usepackage{graphicx}
1226 \title{A short document with LilyPond and xelatex}
1229 Normal \textbf{font} commands inside the \emph{text} work,
1230 because they \textsf{are supported by \LaTeX{} and XeteX.}
1231 If you want to use specific commands like \verb+\XeTeX+, you
1232 should include them again in a \verb+\ifxetex+ environment.
1233 You can use this to print the \ifxetex \XeTeX{} command \else
1234 XeTeX command \fi which is not known to normal \LaTeX .
1236 In normal text you can easily use LilyPond commands, like this:
1245 The fonts of snippets set with LilyPond will have to be set from
1247 of the snippet. For this you should read the AU on how to use
1250 \selectlanguage{ngerman}
1251 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1253 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1254 unterst__tzt werden.
1259 @node Sharing the table of contents
1260 @section Sharing the table of contents
1262 These functions already exist in the OrchestralLily package:
1265 @url{http://repo.or.cz/w/orchestrallily.git}
1268 For greater flexibility in text handling, some users prefer to
1269 export the table of contents from lilypond and read it into
1272 @subsubheading Exporting the ToC from LilyPond
1274 This assumes that your score has multiple movements in the same lilypond
1278 #(define (oly:create-toc-file layout pages)
1279 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1280 (if (not (null? label-table))
1281 (let* ((format-line (lambda (toc-item)
1282 (let* ((label (car toc-item))
1283 (text (caddr toc-item))
1284 (label-page (and (list? label-table)
1285 (assoc label label-table)))
1286 (page (and label-page (cdr label-page))))
1287 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1288 (formatted-toc-items (map format-line (toc-items)))
1289 (whole-string (string-join formatted-toc-items ",\n"))
1290 (output-name (ly:parser-output-name parser))
1291 (outfilename (format "~a.toc" output-name))
1292 (outfile (open-output-file outfilename)))
1293 (if (output-port? outfile)
1294 (display whole-string outfile)
1295 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1296 (close-output-port outfile)))))
1299 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1303 @subsubheading Importing the ToC into LaTeX
1305 In LaTeX, the header should include:
1307 @c no, this doesn't require the smallexample, but since the other
1308 @c two blocks on this page use it, I figured I might as well
1309 @c user it here as well, for consistency. -gp
1311 \usepackage@{pdfpages@}
1312 \includescore@{nameofthescore@}
1316 where @code{\includescore} is defined as:
1319 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1320 % \includescore@{PossibleExtension@}
1321 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1323 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1324 % This requires some heave latex tweaking, since reading in things from a file
1325 % and inserting it into the arguments of a macro is not (easily) possible
1327 % Solution by Patrick Fimml on #latex on April 18, 2009:
1328 % \readfile@{filename@}@{\variable@}
1329 % reads in the contents of the file into \variable (undefined if file
1331 \newread\readfile@@f
1332 \def\readfile@@line#1@{%
1333 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1334 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1335 \ifeof\readfile@@f\else%
1336 \readfile@@line@{#1@}%
1339 \def\readfile#1#2@{%
1340 \openin\readfile@@f=#1 %
1342 \typeout@{No TOC file #1 available!@}%
1345 \readfile@@line@{#2@}%
1347 \closein\readfile@@f%
1351 \newcommand@{\includescore@}[1]@{
1352 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1353 \let\oly@@addtotoc\undefined
1354 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1355 \ifx\oly@@addtotoc\undefined
1356 \includepdf[pages=-]@{\oly@@fname@}
1358 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1359 @{\oly@@fname@}@}\includeit
1365 @node Alternate methods of mixing text and music
1366 @section Alternative methods of mixing text and music
1368 Other means of mixing text and music (without
1369 @command{lilypond-book}) are discussed in
1370 @ref{LilyPond output in other programs}.