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 c'2 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 c'2 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 @{ % 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}:
899 lilypond-book yourfile.lytex
901 dvips -Ppdf yourfile.dvi
906 The @file{.dvi} file created by this process will not contain note heads.
907 This is normal; if you follow the instructions, they will be included in
908 the @file{.ps} and @file{.pdf} files.
910 Running @command{dvips} may produce some warnings about fonts; these
911 are harmless and may be ignored. If you are running @command{latex} in
912 twocolumn mode, remember to add @option{-t landscape} to the
913 @command{dvips} options.
915 Environments such as;
918 \begin@{lilypond@} @dots{} \end@{lilypond@}
922 are not interpreted by @LaTeX{}. Instead, @code{lilypond-book} extracts
923 those @q{environments} into files of its own and runs LilyPond on them.
924 It then takes the resulting graphics and creates a @file{.tex} file
925 where the @code{\begin@{lilypond@}}@dots{}@code{\end@{lilypond@}} macros
926 are then replaced by @q{graphics inclusion} commands. It is at this
927 time that @LaTeX{} is run (although @LaTeX{} will have run previously,
928 it will have been, effectively, on an @q{empty} document in order to
929 calculate things like @code{\linewidth}).
933 The @code{\pageBreak} command will not work within a
934 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment.
936 Many @code{\paper} block variables will also not work within a
937 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment. Use
938 @code{\newcommand} with @code{\betweenLilyPondSystem} in the preamble;
941 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
945 @subsubheading Texinfo
947 To produce a Texinfo document (in any output format), follow the normal
948 procedures for Texinfo; this is, either call @command{texi2pdf} or
949 @command{texi2dvi} or @command{makeinfo}, depending on the output format
952 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
953 an Info File, , , texinfo, GNU Texinfo}.
956 See the documentation of Texinfo for further details.
960 @subheading Command line options
962 @command{lilypond-book} accepts the following command line options:
965 @item -f @var{format}
966 @itemx --format=@var{format}
967 Specify the document type to process: @code{html}, @code{latex},
968 @code{texi} (the default) or @code{docbook}. If this option is missing,
969 @command{lilypond-book} tries to detect the format automatically, see
970 @ref{Filename extensions}. Currently, @code{texi} is the same as
973 @c This complicated detail is not implemented, comment it out -jm
975 The @code{texi} document type produces a Texinfo file with music
976 fragments in the printed output only. For getting images in the HTML
977 version, the format @code{texi-html} must be used instead.
980 @item -F @var{filter}
981 @itemx --filter=@var{filter}
982 Pipe snippets through @var{filter}. @code{lilypond-book} will
983 not --filter and --process at the same time. For example,
986 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
991 Print a short help message.
994 @itemx --include=@var{dir}
995 Add @var{dir} to the include path. @command{lilypond-book} also looks
996 for already compiled snippets in the include path, and does not write
997 them back to the output directory, so in some cases it is necessary to
998 invoke further processing commands such as @command{makeinfo} or
999 @command{latex} with the same @option{-I @var{dir}} options.
1001 @item -l @var{loglevel}
1002 @itemx --loglevel=@var{loglevel}
1003 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
1004 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}. If
1005 this option is not used, and the environment variable
1006 @code{LILYPOND_BOOK_LOGLEVEL} is set, its value is used as the loglevel.
1009 @itemx --output=@var{dir}
1010 Place generated files in directory @var{dir}. Running
1011 @command{lilypond-book} generates lots of small files that LilyPond will
1012 process. To avoid all that garbage in the source directory, use the
1013 @option{--output} command line option, and change to that directory
1014 before running @command{latex} or @command{makeinfo}.
1017 lilypond-book --output=out yourfile.lytex
1022 @item --skip-lily-check
1023 Do not fail if no lilypond output is found. It is used for LilyPond
1024 Info documentation without images.
1026 @item --skip-png-check
1027 Do not fail if no PNG images are found for EPS files. It is used for
1028 LilyPond Info documentation without images.
1030 @item --lily-output-dir=@var{dir}
1031 Write lily-XXX files to directory @var{dir}, link into @option{--output}
1032 directory. Use this option to save building time for documents in
1033 different directories which share a lot of identical snippets.
1035 @item --lily-loglevel=@var{loglevel}
1036 Set the output verbosity of the invoked @command{lilypond} calls to
1037 @var{loglevel}. Possible values are @code{NONE}, @code{ERROR},
1038 @code{WARNING}, @code{BASIC_PROGRESS}, @code{PROGRESS}, @code{INFO}
1039 (default) and @code{DEBUG}. If this option is not used, and the
1040 environment variable @code{LILYPOND_LOGLEVEL} is set, its value is used
1044 @item --info-images-dir=@var{dir}
1045 Format Texinfo output so that Info will look for images of music in
1048 @item --latex-program=@var{prog}
1049 Run executable @command{prog} instead of @command{latex}. This is
1050 useful if your document is processed with @command{xelatex}, for
1053 @item --left-padding=@var{amount}
1054 Pad EPS boxes by this much. @var{amount} is measured in millimeters,
1055 and is 3.0 by default. This option should be used if the lines of
1056 music stick out of the right margin.
1058 The width of a tightly clipped system can vary, due to notation
1059 elements that stick into the left margin, such as bar numbers and
1060 instrument names. This option will shorten each line and move each
1061 line to the right by the same amount.
1063 @item -P @var{command}
1064 @itemx --process=@var{command}
1065 Process LilyPond snippets using @var{command}. The default command is
1066 @code{lilypond}. @code{lilypond-book} will not @option{--filter} and
1067 @option{--process} at the same time.
1070 Create PDF files for use with PDF@LaTeX{}.
1072 @item --redirect-lilypond-output
1073 By default, output is displayed on the terminal. This option redirects
1074 all output to log files in the same directory as the source files.
1076 @item --use-source-file-names
1077 Write snippet output files with the same base name as their source file.
1078 This option works only for snippets included with @code{lilypondfile}
1079 and only if directories implied by @option{--output-dir} and
1080 @option{--lily-output-dir} options are different.
1084 Be verbose. This is equivalent to @code{--loglevel=DEBUG}.
1088 Print version information.
1095 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
1096 @LaTeX{} commands that change margins and line widths after the preamble
1099 Only the first @code{\score} of a LilyPond block is processed.
1102 @node Filename extensions
1103 @section Filename extensions
1105 You can use any filename extension for the input file, but if you do not
1106 use the recommended extension for a particular format you may need to
1107 manually specify the output format; for details, see @ref{Invoking
1108 lilypond-book}. Otherwise, @command{lilypond-book} automatically
1109 selects the output format based on the input filename's extension.
1112 @multitable @columnfractions .2 .5
1113 @item @strong{extension} @tab @strong{output format}
1115 @item @file{.html} @tab HTML
1116 @item @file{.htmly} @tab HTML
1117 @item @file{.itely} @tab Texinfo
1118 @item @file{.latex} @tab @LaTeX{}
1119 @item @file{.lytex} @tab @LaTeX{}
1120 @item @file{.lyxml} @tab DocBook
1121 @item @file{.tely} @tab Texinfo
1122 @item @file{.tex} @tab @LaTeX{}
1123 @item @file{.texi} @tab Texinfo
1124 @item @file{.texinfo} @tab Texinfo
1125 @item @file{.xml} @tab HTML
1129 If you use the same filename extension for the input file than the
1130 extension @command{lilypond-book} uses for the output file, and if the
1131 input file is in the same directory as @command{lilypond-book} working
1132 directory, you must use @option{--output} option to make
1133 @command{lilypond-book} running, otherwise it will exit with an error
1134 message like @qq{Output would overwrite input file}.
1137 @node lilypond-book templates
1138 @section lilypond-book templates
1140 These templates are for use with @code{lilypond-book}. If you're not familiar
1141 with this program, please refer to
1142 @ref{lilypond-book}.
1146 You can include LilyPond fragments in a LaTeX document.
1149 \documentclass[]@{article@}
1161 More LaTeX text, and options in square brackets.
1163 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1171 You can include LilyPond fragments in Texinfo; in fact, this entire manual
1172 is written in Texinfo.
1175 \input texinfo @c -*-texinfo-*-
1187 More Texinfo text, and options in brackets.
1189 @@lilypond[verbatim,fragment,ragged-right]
1200 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1206 Documents for lilypond-book may freely mix music and text. For
1216 Another bit of lilypond, this time with options:
1218 <lilypond fragment quote staffsize=26 verbatim>
1232 \documentclass{article}
1233 \usepackage{ifxetex}
1235 %xetex specific stuff
1236 \usepackage{xunicode,fontspec,xltxtra}
1237 \setmainfont[Numbers=OldStyle]{Times New Roman}
1240 %This can be empty if you are not going to use pdftex
1241 \usepackage[T1]{fontenc}
1242 \usepackage[utf8]{inputenc}
1243 \usepackage{mathptmx}%Times
1244 \usepackage{helvet}%Helvetica
1246 %Here you can insert all packages that pdftex also understands
1247 \usepackage[ngerman,finnish,english]{babel}
1248 \usepackage{graphicx}
1251 \title{A short document with LilyPond and xelatex}
1254 Normal \textbf{font} commands inside the \emph{text} work,
1255 because they \textsf{are supported by \LaTeX{} and XeteX.}
1256 If you want to use specific commands like \verb+\XeTeX+, you
1257 should include them again in a \verb+\ifxetex+ environment.
1258 You can use this to print the \ifxetex \XeTeX{} command \else
1259 XeTeX command \fi which is not known to normal \LaTeX .
1261 In normal text you can easily use LilyPond commands, like this:
1270 The fonts of snippets set with LilyPond will have to be set from
1272 of the snippet. For this you should read the AU on how to use
1275 \selectlanguage{ngerman}
1276 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1278 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1279 unterst__tzt werden.
1284 @node Sharing the table of contents
1285 @section Sharing the table of contents
1287 These functions already exist in the OrchestralLily package:
1290 @url{http://repo.or.cz/w/orchestrallily.git}
1293 For greater flexibility in text handling, some users prefer to
1294 export the table of contents from lilypond and read it into
1297 @subsubheading Exporting the ToC from LilyPond
1299 This assumes that your score has multiple movements in the same lilypond
1303 #(define (oly:create-toc-file layout pages)
1304 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1305 (if (not (null? label-table))
1306 (let* ((format-line (lambda (toc-item)
1307 (let* ((label (car toc-item))
1308 (text (caddr toc-item))
1309 (label-page (and (list? label-table)
1310 (assoc label label-table)))
1311 (page (and label-page (cdr label-page))))
1312 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1313 (formatted-toc-items (map format-line (toc-items)))
1314 (whole-string (string-join formatted-toc-items ",\n"))
1315 (output-name (ly:parser-output-name))
1316 (outfilename (format "~a.toc" output-name))
1317 (outfile (open-output-file outfilename)))
1318 (if (output-port? outfile)
1319 (display whole-string outfile)
1320 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1321 (close-output-port outfile)))))
1324 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1328 @subsubheading Importing the ToC into LaTeX
1330 In LaTeX, the header should include:
1332 @c no, this doesn't require the smallexample, but since the other
1333 @c two blocks on this page use it, I figured I might as well
1334 @c user it here as well, for consistency. -gp
1336 \usepackage@{pdfpages@}
1337 \includescore@{nameofthescore@}
1341 where @code{\includescore} is defined as:
1344 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1345 % \includescore@{PossibleExtension@}
1346 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1348 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1349 % This requires some heave latex tweaking, since reading in things from a file
1350 % and inserting it into the arguments of a macro is not (easily) possible
1352 % Solution by Patrick Fimml on #latex on April 18, 2009:
1353 % \readfile@{filename@}@{\variable@}
1354 % reads in the contents of the file into \variable (undefined if file
1356 \newread\readfile@@f
1357 \def\readfile@@line#1@{%
1358 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1359 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1360 \ifeof\readfile@@f\else%
1361 \readfile@@line@{#1@}%
1364 \def\readfile#1#2@{%
1365 \openin\readfile@@f=#1 %
1367 \typeout@{No TOC file #1 available!@}%
1370 \readfile@@line@{#2@}%
1372 \closein\readfile@@f%
1376 \newcommand@{\includescore@}[1]@{
1377 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1378 \let\oly@@addtotoc\undefined
1379 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1380 \ifx\oly@@addtotoc\undefined
1381 \includepdf[pages=-]@{\oly@@fname@}
1383 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1384 @{\oly@@fname@}@}\includeit
1390 @node Alternate methods of mixing text and music
1391 @section Alternative methods of mixing text and music
1393 Other means of mixing text and music (without
1394 @command{lilypond-book}) are discussed in
1395 @ref{LilyPond output in other programs}.