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 \tuplet 3/2 { 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{@dots{}lots of stuff deleted@dots{}}
122 @emph{Compiling lilybook.tex...}
125 @emph{@dots{}lots of stuff deleted@dots{}}
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 \tuplet 3/2 { 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@{@dots{}@}} command, where you can directly enter
214 the @code{\begin@{lilypond@}@dots{}\end@{lilypond@}} environment, where
215 you can directly enter longer lilypond code
218 the @code{\lilypondfile@{@dots{}@}} command to insert a lilypond file
221 the @code{\musicxmlfile@{@dots{}@}} command to insert a MusicXML file,
222 which 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@}@dots{}\end@{lilypond@}
400 \onlyFirstNSystems@{1@}
401 \begin@{lilypond@}@dots{}\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@{@dots{}@}} command, where you can directly enter
428 the @code{@@lilypond@dots{}@@end lilypond} environment, where you can
429 directly enter longer lilypond code
432 the @code{@@lilypondfile@{@dots{}@}} command to insert a lilypond file
435 the @code{@@musicxmlfile@{@dots{}@}} command to insert a MusicXML file,
436 which 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@{@dots{}@}} 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 @dots{} />} command, where you can directly enter
506 the @code{<lilyond>@dots{}</lilypond>} environment, where you can
507 directly enter longer lilypond code
510 the @code{<lilypondfile>@dots{}</lilypondfile>} command to insert a
514 the @code{<musicxmlfile>@dots{}</musicxmlfile>} command to insert a
515 MusicXML file, which will be processed by @code{musicxml2ly} and
520 In the input file, music is specified with any of the following commands:
523 <lilypond options go here>
527 <lilypond options go here: YOUR LILYPOND CODE />
529 <lilypondfile options go here>@var{filename}</lilypondfile>
531 <musicxmlfile options go here>@var{filename}</musicxmlfile>
534 For example, you can write
536 <lilypond fragment relative=2>
537 \key c \minor c4 es g2
542 @command{lilypond-book} then produces an HTML file with appropriate image
543 tags for the music fragments:
545 @lilypond[fragment,relative=2]
546 \key c \minor c4 es g2
549 For inline pictures, use @code{<lilypond @dots{} />}, where the options
550 are separated by a colon from the music, for example
553 Some music in <lilypond relative=2: a b c/> a line of text.
556 To include separate files, say
559 <lilypondfile @var{option1} @var{option2} @dots{}>@var{filename}</lilypondfile>
562 @code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but
563 simply references a MusicXML file rather than a LilyPond file.
565 For a list of options to use with the @code{lilypond} or
566 @code{lilypondfile} tags, see @ref{Music fragment options}.
568 Additionally, @code{<lilypondversion/>} displays the current version
572 @cindex titling in HTML
573 @cindex preview image
579 For inserting LilyPond snippets it is good to keep the conformity of our
580 DocBook document, thus allowing us to use DocBook editors, validation
581 etc. So we don't use custom tags, only specify a convention based on the
582 standard DocBook elements.
584 @subheading Common conventions
586 For inserting all type of snippets we use the @code{mediaobject} and
587 @code{inlinemediaobject} element, so our snippets can be formatted
588 inline or not inline. The snippet formatting options are always
589 provided in the @code{role} property of the innermost element (see in
590 next sections). Tags are chosen to allow DocBook editors format the
591 content gracefully. The DocBook files to be processed with
592 @command{lilypond-book} should have the extension @file{.lyxml}.
594 @subheading Including a LilyPond file
596 This is the most simple case. We must use the @file{.ly} extension for
597 the included file, and insert it as a standard @code{imageobject}, with
598 the following structure:
603 <imagedata fileref="music1.ly" role="printfilename" />
608 Note that you can use @code{mediaobject} or @code{inlinemediaobject}
609 as the outermost element as you wish.
611 @subheading Including LilyPond code
613 Including LilyPond code is possible by using a @code{programlisting},
614 where the language is set to @code{lilypond} with the following
620 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
621 \context Staff \with @{
622 \remove "Time_signature_engraver"
623 \remove "Clef_engraver"@}
630 As you can see, the outermost element is a @code{mediaobject} or
631 @code{inlinemediaobject}, and there is a @code{textobject} containing
632 the @code{programlisting} inside.
634 @subheading Processing the DocBook document
636 Running @command{lilypond-book} on our @file{.lyxml} file will create a
637 valid DocBook document to be further processed with @file{.xml}
638 extension. If you use
639 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
640 PDF file from this document automatically. For HTML (HTML Help,
641 JavaHelp etc.) generation you can use the official DocBook XSL
642 stylesheets, however, it is possible that you have to make some
643 customization for it.
646 @node Music fragment options
647 @section Music fragment options
649 In the following, a @q{LilyPond command} refers to any command described
650 in the previous sections which is handled by @command{lilypond-book} to
651 produce a music snippet. For simplicity, LilyPond commands are only
652 shown in @LaTeX{} syntax.
654 Note that the option string is parsed from left to right; if an option
655 occurs multiple times, the last one is taken.
657 The following options are available for LilyPond commands:
660 @item staffsize=@var{ht}
661 Set staff size to @var{ht}, which is measured in points.
664 Produce ragged-right lines with natural spacing, i.e.,
665 @code{ragged-right = ##t} is added to the LilyPond snippet. Single-line
666 snippets will always be typeset by default as ragged-right, unless
667 @code{noragged-right} is explicitly given.
670 For single-line snippets, allow the staff length to be stretched to
671 equal that of the line width, i.e., @code{ragged-right = ##f} is
672 added to the LilyPond snippet.
675 @itemx line-width=@var{size}\@var{unit}
676 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
677 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
678 @code{pt}. This option affects LilyPond output (this is, the staff
679 length of the music snippet), not the text layout.
681 If used without an argument, set line width to a default value (as
682 computed with a heuristic algorithm).
684 If no @code{line-width} option is given, @command{lilypond-book} tries to
685 guess a default for @code{lilypond} environments which don't use the
686 @code{ragged-right} option.
688 @item papersize=@var{string}
689 Where @var{string} is a paper size defined in @file{scm/paper.scm} i.e.
690 @code{a5}, @code{quarto}, @code{11x17} etc.
692 Values not defined in @file{scm/paper.scm} will be ignored, a warning
693 will be posted and the snippet will be printed using the default
697 Do not print the time signature, and turns off the timing (time signature,
698 bar lines) in the score.
701 Make @command{lilypond-book} add some boilerplate code so that you can
709 without @code{\layout}, @code{\score}, etc.
712 Do not add additional code to complete LilyPond code in music snippets.
713 Since this is the default, @code{nofragment} is redundant normally.
715 @item indent=@var{size}\@var{unit}
716 Set indentation of the first music system to @var{size}, using
717 @var{unit} as units. @var{unit} is one of the following strings:
718 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
719 LilyPond, not the text layout.
722 Set indentation of the first music system to zero. This option affects
723 LilyPond, not the text layout. Since no indentation is the default,
724 @code{noindent} is redundant normally.
727 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
728 the output into a quotation block. The value @q{0.4@dmn{in}} can be
729 controlled with the @code{exampleindent} option.
732 Set the amount by which the @code{quote} option indents a music snippet.
735 @itemx relative=@var{n}
736 Use relative octave mode. By default, notes are specified relative to
737 middle@tie{}C. The optional integer argument specifies the octave of
738 the starting note, where the default @code{1} is middle C.
739 @code{relative} option only works when @code{fragment} option is set,
740 so @code{fragment} is automatically implied by @code{relative},
741 regardless of the presence of any @code{(no)fragment} option in the
745 LilyPond also uses @command{lilypond-book} to produce its own
746 documentation. To do that, some more obscure music fragment options are
751 The argument of a LilyPond command is copied to the output file and
752 enclosed in a verbatim block, followed by any text given with the
753 @code{intertext} option (not implemented yet); then the actual music is
754 displayed. This option does not work well with @code{\lilypond@{@}} if
755 it is part of a paragraph.
757 If @code{verbatim} is used in a @code{lilypondfile} command, it is
758 possible to enclose verbatim only a part of the source file. If the
759 source file contain a comment containing @samp{begin verbatim} (without
760 quotes), quoting the source in the verbatim block will start after the
761 last occurrence of such a comment; similarly, quoting the source verbatim
762 will stop just before the first occurrence of a comment containing
763 @samp{end verbatim}, if there is any. In the following source file
764 example, the music will be interpreted in relative mode, but the
765 verbatim quote will not show the @code{relative} block, i.e.
768 \relative c' @{ % begin verbatim
775 will be printed with a verbatim block like
783 If you would like to translate comments and variable names in verbatim
784 output but not in the sources, you may set the environment variable
785 @code{LYDOC_LOCALEDIR} to a directory path; the directory should
786 contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
790 (Only for Texinfo output.) Prepend line @code{\version
791 @@w@{"@@version@{@}"@}} to @code{verbatim} output.
794 (Only for Texinfo output.) If @command{lilypond} is called with the
795 @option{--header=@/texidoc} option, and the file to be processed is
796 called @file{foo.ly}, it creates a file @file{foo.texidoc} if there
797 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
798 option makes @command{lilypond-book} include such files, adding its
799 contents as a documentation block right before the music snippet (but
800 outside the @code{example} environment generated by a @code{quote}
803 Assuming the file @file{foo.ly} contains
807 texidoc = "This file demonstrates a single note."
813 and we have this in our Texinfo document @file{test.texinfo}
816 @@lilypondfile[texidoc]@{foo.ly@}
820 the following command line gives the expected result
823 lilypond-book --pdf --process="lilypond \
824 -dbackend=eps --header=texidoc" test.texinfo
827 Most LilyPond test documents (in the @file{input} directory of the
828 distribution) are small @file{.ly} files which look exactly like this.
830 For localization purpose, if the Texinfo document contains
831 @code{@@documentlanguage @var{LANG}} and @file{foo.ly} header
832 contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
833 is called with @option{--header=@/texidoc@var{LANG}}, then
834 @file{foo.texidoc@var{LANG}} will be included instead of
838 (Only for Texinfo output.) This option works similarly to
839 @code{texidoc} option: if @command{lilypond} is called with the
840 @option{--header=@/doctitle} option, and the file to be processed is
841 called @file{foo.ly} and contains a @code{doctitle} field in the
842 @code{\header}, it creates a file @file{foo.doctitle}. When
843 @code{doctitle} option is used, the contents of @file{foo.doctitle},
844 which should be a single line of @var{text}, is inserted in the
845 Texinfo document as @code{@@lydoctitle @var{text}}.
846 @code{@@lydoctitle} should be a macro defined in the Texinfo document.
847 The same remark about @code{texidoc} processing with localized
848 languages also applies to @code{doctitle}.
851 (Only for Texinfo output.) Do not translate comments and variable
852 names in the snippet quoted verbatim.
855 If a LilyPond input file is included with @code{\lilypondfile}, print
856 the file name right before the music snippet. For HTML output, this
857 is a link. Only the base name of the file is printed, i.e. the
858 directory part of the file path is stripped.
863 @node Invoking lilypond-book
864 @section Invoking @command{lilypond-book}
866 @command{lilypond-book} produces a file with one of the following
867 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
868 depending on the output format. All of @file{.tex}, @file{.texi} and
869 @file{.xml} files need further processing.
871 @subheading Format-specific instructions
873 @subsubheading @LaTeX{}
875 There are two ways of processing your @LaTeX{} document for printing or
876 publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
877 PostScript file with @LaTeX{} via a DVI to PostScript translator like
878 @command{dvips}. The first way is simpler and recommended@footnote{Note
879 that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
880 @LaTeX{} document, that is why we explain the two ways.}, and whichever
881 way you use, you can easily convert between PostScript and PDF with
882 tools, like @command{ps2pdf} and @command{pdf2ps} included in
885 To produce a PDF file through PDF@LaTeX{}, use
888 lilypond-book --pdf yourfile.lytex
889 pdflatex yourfile.tex
892 @cindex outline fonts
895 @cindex invoking dvips
896 To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
900 lilypond-book yourfile.lytex
902 dvips -Ppdf yourfile.dvi
907 The @file{.dvi} file created by this process will not contain
908 note heads. This is normal; if you follow the instructions, they
909 will be included in the @file{.ps} and @file{.pdf} files.
911 Running @command{dvips} may produce some warnings about fonts; these
912 are harmless and may be ignored. If you are running @command{latex} in
913 twocolumn mode, remember to add @option{-t landscape} to the
914 @command{dvips} options.
917 The @code{\pageBreak} command will not work within a
918 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment.
920 Many @code{\paper} block variables will also not work within a
921 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment. Use
922 @code{\newcommand} with @code{\betweenLilyPondSystem} in the preamble;
925 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
929 @subsubheading Texinfo
931 To produce a Texinfo document (in any output format), follow the normal
932 procedures for Texinfo; this is, either call @command{texi2pdf} or
933 @command{texi2dvi} or @command{makeinfo}, depending on the output format
936 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
937 an Info File, , , texinfo, GNU Texinfo}.
940 See the documentation of Texinfo for further details.
944 @subheading Command line options
946 @command{lilypond-book} accepts the following command line options:
949 @item -f @var{format}
950 @itemx --format=@var{format}
951 Specify the document type to process: @code{html}, @code{latex},
952 @code{texi} (the default) or @code{docbook}. If this option is missing,
953 @command{lilypond-book} tries to detect the format automatically, see
954 @ref{Filename extensions}. Currently, @code{texi} is the same as
957 @c This complicated detail is not implemented, comment it out -jm
959 The @code{texi} document type produces a Texinfo file with music
960 fragments in the printed output only. For getting images in the HTML
961 version, the format @code{texi-html} must be used instead.
964 @item -F @var{filter}
965 @itemx --filter=@var{filter}
966 Pipe snippets through @var{filter}. @code{lilypond-book} will
967 not --filter and --process at the same time. For example,
970 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
975 Print a short help message.
978 @itemx --include=@var{dir}
979 Add @var{dir} to the include path. @command{lilypond-book} also looks
980 for already compiled snippets in the include path, and does not write
981 them back to the output directory, so in some cases it is necessary to
982 invoke further processing commands such as @command{makeinfo} or
983 @command{latex} with the same @option{-I @var{dir}} options.
985 @item -l @var{loglevel}
986 @itemx --loglevel=@var{loglevel}
987 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
988 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}. If
989 this option is not used, and the environment variable
990 @code{LILYPOND_BOOK_LOGLEVEL} is set, its value is used as the loglevel.
993 @itemx --output=@var{dir}
994 Place generated files in directory @var{dir}. Running
995 @command{lilypond-book} generates lots of small files that LilyPond will
996 process. To avoid all that garbage in the source directory, use the
997 @option{--output} command line option, and change to that directory
998 before running @command{latex} or @command{makeinfo}.
1001 lilypond-book --output=out yourfile.lytex
1006 @item --skip-lily-check
1007 Do not fail if no lilypond output is found. It is used for LilyPond
1008 Info documentation without images.
1010 @item --skip-png-check
1011 Do not fail if no PNG images are found for EPS files. It is used for
1012 LilyPond Info documentation without images.
1014 @item --lily-output-dir=@var{dir}
1015 Write lily-XXX files to directory @var{dir}, link into @option{--output}
1016 directory. Use this option to save building time for documents in
1017 different directories which share a lot of identical snippets.
1019 @item --lily-loglevel=@var{loglevel}
1020 Set the output verbosity of the invoked @command{lilypond} calls to
1021 @var{loglevel}. Possible values are @code{NONE}, @code{ERROR},
1022 @code{WARNING}, @code{BASIC_PROGRESS}, @code{PROGRESS}, @code{INFO}
1023 (default) and @code{DEBUG}. If this option is not used, and the
1024 environment variable @code{LILYPOND_LOGLEVEL} is set, its value is used
1028 @item --info-images-dir=@var{dir}
1029 Format Texinfo output so that Info will look for images of music in
1032 @item --latex-program=@var{prog}
1033 Run executable @command{prog} instead of @command{latex}. This is
1034 useful if your document is processed with @command{xelatex}, for
1037 @item --left-padding=@var{amount}
1038 Pad EPS boxes by this much. @var{amount} is measured in millimeters,
1039 and is 3.0 by default. This option should be used if the lines of
1040 music stick out of the right margin.
1042 The width of a tightly clipped system can vary, due to notation
1043 elements that stick into the left margin, such as bar numbers and
1044 instrument names. This option will shorten each line and move each
1045 line to the right by the same amount.
1047 @item -P @var{command}
1048 @itemx --process=@var{command}
1049 Process LilyPond snippets using @var{command}. The default command is
1050 @code{lilypond}. @code{lilypond-book} will not @option{--filter} and
1051 @option{--process} at the same time.
1054 Create PDF files for use with PDF@LaTeX{}.
1056 @item --redirect-lilypond-output
1057 By default, output is displayed on the terminal. This option redirects
1058 all output to log files in the same directory as the source files.
1060 @item --use-source-file-names
1061 Write snippet output files with the same base name as their source file.
1062 This option works only for snippets included with @code{lilypondfile}
1063 and only if directories implied by @option{--output-dir} and
1064 @option{--lily-output-dir} options are different.
1068 Be verbose. This is equivalent to @code{--loglevel=DEBUG}.
1072 Print version information.
1079 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
1080 @LaTeX{} commands that change margins and line widths after the preamble
1083 Only the first @code{\score} of a LilyPond block is processed.
1086 @node Filename extensions
1087 @section Filename extensions
1089 You can use any filename extension for the input file, but if you do not
1090 use the recommended extension for a particular format you may need to
1091 manually specify the output format; for details, see @ref{Invoking
1092 lilypond-book}. Otherwise, @command{lilypond-book} automatically
1093 selects the output format based on the input filename's extension.
1096 @multitable @columnfractions .2 .5
1097 @item @strong{extension} @tab @strong{output format}
1099 @item @file{.html} @tab HTML
1100 @item @file{.htmly} @tab HTML
1101 @item @file{.itely} @tab Texinfo
1102 @item @file{.latex} @tab @LaTeX{}
1103 @item @file{.lytex} @tab @LaTeX{}
1104 @item @file{.lyxml} @tab DocBook
1105 @item @file{.tely} @tab Texinfo
1106 @item @file{.tex} @tab @LaTeX{}
1107 @item @file{.texi} @tab Texinfo
1108 @item @file{.texinfo} @tab Texinfo
1109 @item @file{.xml} @tab HTML
1113 If you use the same filename extension for the input file than the
1114 extension @command{lilypond-book} uses for the output file, and if the
1115 input file is in the same directory as @command{lilypond-book} working
1116 directory, you must use @option{--output} option to make
1117 @command{lilypond-book} running, otherwise it will exit with an error
1118 message like @qq{Output would overwrite input file}.
1121 @node lilypond-book templates
1122 @section lilypond-book templates
1124 These templates are for use with @code{lilypond-book}. If you're not familiar
1125 with this program, please refer to
1126 @ref{lilypond-book}.
1130 You can include LilyPond fragments in a LaTeX document.
1133 \documentclass[]@{article@}
1145 More LaTeX text, and options in square brackets.
1147 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1155 You can include LilyPond fragments in Texinfo; in fact, this entire manual
1156 is written in Texinfo.
1159 \input texinfo @c -*-texinfo-*-
1171 More Texinfo text, and options in brackets.
1173 @@lilypond[verbatim,fragment,ragged-right]
1184 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1190 Documents for lilypond-book may freely mix music and text. For
1200 Another bit of lilypond, this time with options:
1202 <lilypond fragment quote staffsize=26 verbatim>
1216 \documentclass{article}
1217 \usepackage{ifxetex}
1219 %xetex specific stuff
1220 \usepackage{xunicode,fontspec,xltxtra}
1221 \setmainfont[Numbers=OldStyle]{Times New Roman}
1224 %This can be empty if you are not going to use pdftex
1225 \usepackage[T1]{fontenc}
1226 \usepackage[utf8]{inputenc}
1227 \usepackage{mathptmx}%Times
1228 \usepackage{helvet}%Helvetica
1230 %Here you can insert all packages that pdftex also understands
1231 \usepackage[ngerman,finnish,english]{babel}
1232 \usepackage{graphicx}
1235 \title{A short document with LilyPond and xelatex}
1238 Normal \textbf{font} commands inside the \emph{text} work,
1239 because they \textsf{are supported by \LaTeX{} and XeteX.}
1240 If you want to use specific commands like \verb+\XeTeX+, you
1241 should include them again in a \verb+\ifxetex+ environment.
1242 You can use this to print the \ifxetex \XeTeX{} command \else
1243 XeTeX command \fi which is not known to normal \LaTeX .
1245 In normal text you can easily use LilyPond commands, like this:
1254 The fonts of snippets set with LilyPond will have to be set from
1256 of the snippet. For this you should read the AU on how to use
1259 \selectlanguage{ngerman}
1260 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1262 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1263 unterst__tzt werden.
1268 @node Sharing the table of contents
1269 @section Sharing the table of contents
1271 These functions already exist in the OrchestralLily package:
1274 @url{http://repo.or.cz/w/orchestrallily.git}
1277 For greater flexibility in text handling, some users prefer to
1278 export the table of contents from lilypond and read it into
1281 @subsubheading Exporting the ToC from LilyPond
1283 This assumes that your score has multiple movements in the same lilypond
1287 #(define (oly:create-toc-file layout pages)
1288 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1289 (if (not (null? label-table))
1290 (let* ((format-line (lambda (toc-item)
1291 (let* ((label (car toc-item))
1292 (text (caddr toc-item))
1293 (label-page (and (list? label-table)
1294 (assoc label label-table)))
1295 (page (and label-page (cdr label-page))))
1296 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1297 (formatted-toc-items (map format-line (toc-items)))
1298 (whole-string (string-join formatted-toc-items ",\n"))
1299 (output-name (ly:parser-output-name parser))
1300 (outfilename (format "~a.toc" output-name))
1301 (outfile (open-output-file outfilename)))
1302 (if (output-port? outfile)
1303 (display whole-string outfile)
1304 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1305 (close-output-port outfile)))))
1308 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1312 @subsubheading Importing the ToC into LaTeX
1314 In LaTeX, the header should include:
1316 @c no, this doesn't require the smallexample, but since the other
1317 @c two blocks on this page use it, I figured I might as well
1318 @c user it here as well, for consistency. -gp
1320 \usepackage@{pdfpages@}
1321 \includescore@{nameofthescore@}
1325 where @code{\includescore} is defined as:
1328 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1329 % \includescore@{PossibleExtension@}
1330 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1332 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1333 % This requires some heave latex tweaking, since reading in things from a file
1334 % and inserting it into the arguments of a macro is not (easily) possible
1336 % Solution by Patrick Fimml on #latex on April 18, 2009:
1337 % \readfile@{filename@}@{\variable@}
1338 % reads in the contents of the file into \variable (undefined if file
1340 \newread\readfile@@f
1341 \def\readfile@@line#1@{%
1342 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1343 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1344 \ifeof\readfile@@f\else%
1345 \readfile@@line@{#1@}%
1348 \def\readfile#1#2@{%
1349 \openin\readfile@@f=#1 %
1351 \typeout@{No TOC file #1 available!@}%
1354 \readfile@@line@{#2@}%
1356 \closein\readfile@@f%
1360 \newcommand@{\includescore@}[1]@{
1361 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1362 \let\oly@@addtotoc\undefined
1363 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1364 \ifx\oly@@addtotoc\undefined
1365 \includepdf[pages=-]@{\oly@@fname@}
1367 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1368 @{\oly@@fname@}@}\includeit
1374 @node Alternate methods of mixing text and music
1375 @section Alternative methods of mixing text and music
1377 Other means of mixing text and music (without
1378 @command{lilypond-book}) are discussed in
1379 @ref{LilyPond output in other programs}.