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 screech-boink.ly by any .ly file you put in the same
104 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 @code{--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}
165 @node Integrating music and text
166 @section Integrating music and text
168 Here we explain how to integrate LilyPond with various output formats.
180 @LaTeX{} is the de-facto standard for publishing layouts in the exact
181 sciences. It is built on top of the @TeX{} typesetting engine,
182 providing the best typography available anywhere.
185 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
186 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
189 Music is entered using
192 \begin@{lilypond@}[options,go,here]
201 \lilypondfile[options,go,here]@{@var{filename}@}
208 \lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
211 Additionally, @code{\lilypondversion} displays the current version
213 Running @command{lilypond-book} yields a file that can be further
214 processed with @LaTeX{}.
216 We show some examples here. The @code{lilypond} environment
219 \begin@{lilypond@}[quote,fragment,staffsize=26]
227 @lilypond[quote,fragment,staffsize=26]
234 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
240 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
243 Currently, you cannot include @code{@{} or @code{@}} within
244 @code{\lilypond@{@}}, so this command is only useful with the
245 @code{fragment} option.
247 The default line width of the music will be adjusted by examining the
248 commands in the document preamble, the part of the document before
249 @code{\begin@{document@}}. The @command{lilypond-book} command sends
250 these to @LaTeX{} to find out how wide the text is. The line width for
251 the music fragments is then adjusted to the text width. Note that this
252 heuristic algorithm can fail easily; in such cases it is necessary to
253 use the @code{line-width} music fragment option.
255 @cindex titling and lilypond-book
256 @cindex \header in @LaTeX{} documents
258 Each snippet will call the following macros if they have been defined by
262 @item @code{\preLilyPondExample} called before the music,
264 @item @code{\postLilyPondExample} called after the music,
266 @item @code{\betweenLilyPondSystem[1]} is called between systems if
267 @code{lilypond-book} has split the snippet into several PostScript
268 files. It must be defined as taking one parameter and will be
269 passed the number of files already included in this snippet.
270 The default is to simply insert a @code{\linebreak}.
276 @cindex Latex, feta symbols
279 To include feta symbols (such as flat, segno, etc) in a LaTeX
280 document, use @code{\input@{titledefs@}}
283 \documentclass[a4paper]@{article@}
294 The font symbol names are defined in the file feta20.tex; to find
295 the location of this file, use the command
305 Sometimes it is useful to display music elements (such as ties and slurs)
306 as if they continued after the end of the fragment. This can be done by
307 breaking the staff and suppressing inclusion of the rest of the LilyPond
310 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
311 inclusion of other systems is terminated once the required number of
312 systems are included. Since @code{\betweenLilyPondSystem} is first
313 called @emph{after} the first system, including only the first system
317 \def\betweenLilyPondSystem#1@{\endinput@}
319 \begin@{lilypond@}[fragment]
320 c'1\( e'( c'~ \break c' d) e f\)
324 If a greater number of systems is requested, a @TeX{} conditional must
325 be used before the @code{\endinput}. In this example, replace @q{2} by
326 the number of systems you want in the output.
329 \def\betweenLilyPondSystem#1@{
330 \ifnum#1<2\else\expandafter\endinput\fi
335 (Since @code{\endinput} immediately stops the processing of the current
336 input file we need @code{\expandafter} to delay the call of @code{\endinput}
337 after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
340 Remember that the definition of @code{\betweenLilyPondSystem} is
341 effective until @TeX{} quits the current group (such as the @LaTeX{}
342 environment) or is overridden by another definition (which is, in
343 most cases, for the rest of the document). To reset your
347 \let\betweenLilyPondSystem\undefined
351 in your @LaTeX{} source.
353 This may be simplified by defining a @TeX{} macro
356 \def\onlyFirstNSystems#1@{
357 \def\betweenLilyPondSystem##1@{%
358 \ifnum##1<#1\else\expandafter\endinput\fi@}
363 and then saying only how many systems you want before each fragment,
366 \onlyFirstNSystems@{3@}
367 \begin@{lilypond@}...\end@{lilypond@}
368 \onlyFirstNSystems@{1@}
369 \begin@{lilypond@}...\end@{lilypond@}
374 There are specific @command{lilypond-book} command line options and
375 other details to know when processing @LaTeX{} documents, see
376 @ref{Invoking lilypond-book}.
382 Texinfo is the standard format for documentation of the GNU project. An
383 example of a Texinfo document is this manual. The HTML, PDF, and Info
384 versions of the manual are made from the Texinfo document.
386 In the input file, music is specified with
389 @@lilypond[options,go,here]
398 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
405 @@lilypondfile[options,go,here]@{@var{filename}@}
408 Additionally, @code{@@lilypondversion} displays the current version
411 When @command{lilypond-book} is run on it, this results in a Texinfo
412 file (with extension @file{.texi}) containing @code{@@image} tags for
413 HTML, Info and printed output. @command{lilypond-book} generates images
414 of the music in EPS and PDF formats for use in the printed output, and
415 in PNG format for use in HTML and Info output.
417 We show two simple examples here. A @code{lilypond} environment
435 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
441 @lilypond[fragment,staffsize=11]{<c' e' g'>}
443 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
444 in-line image. It always gets a paragraph of its own.
450 Music is entered using
453 <lilypond fragment relative=2>
454 \key c \minor c4 es g2
458 @command{lilypond-book} then produces an HTML file with appropriate image
459 tags for the music fragments:
461 @lilypond[fragment,relative=2]
462 \key c \minor c4 es g2
465 For inline pictures, use @code{<lilypond ... />}, where the options
466 are separated by a colon from the music, for example
469 Some music in <lilypond relative=2: a b c/> a line of text.
473 To include separate files, say
476 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
479 Additionally, @code{<lilypondversion/>} displays the current version
483 @cindex titling in HTML
484 @cindex preview image
490 For inserting LilyPond snippets it is good to keep the conformity of our
491 DocBook document, thus allowing us to use DocBook editors, validation
492 etc. So we don't use custom tags, only specify a convention based on the
493 standard DocBook elements.
495 @subheading Common conventions
497 For inserting all type of snippets we use the @code{mediaobject} and
498 @code{inlinemediaobject} element, so our snippets can be formatted
499 inline or not inline. The snippet formatting options are always
500 provided in the @code{role} property of the innermost element (see in
501 next sections). Tags are chosen to allow DocBook editors format the
502 content gracefully. The DocBook files to be processed with
503 @command{lilypond-book} should have the extension @file{.lyxml}.
505 @subheading Including a LilyPond file
507 This is the most simple case. We must use the @file{.ly} extension for
508 the included file, and insert it as a standard @code{imageobject}, with
509 the following structure:
514 <imagedata fileref="music1.ly" role="printfilename" />
519 Note that you can use @code{mediaobject} or @code{inlinemediaobject}
520 as the outermost element as you wish.
522 @subheading Including LilyPond code
524 Including LilyPond code is possible by using a @code{programlisting},
525 where the language is set to @code{lilypond} with the following
531 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
532 \context Staff \with @{
533 \remove Time_signature_engraver
534 \remove Clef_engraver@}
541 As you can see, the outermost element is a @code{mediaobject} or
542 @code{inlinemediaobject}, and there is a @code{textobject} containing
543 the @code{programlisting} inside.
545 @subheading Processing the DocBook document
547 Running @command{lilypond-book} on our @file{.lyxml} file will create a
548 valid DocBook document to be further processed with @file{.xml}
549 extension. If you use
550 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
551 PDF file from this document automatically. For HTML (HTML Help,
552 JavaHelp etc.) generation you can use the official DocBook XSL
553 stylesheets, however, it is possible that you have to make some
554 customization for it.
557 @node Music fragment options
558 @section Music fragment options
560 In the following, a @q{LilyPond command} refers to any command described
561 in the previous sections which is handled by @command{lilypond-book} to
562 produce a music snippet. For simplicity, LilyPond commands are only
563 shown in @LaTeX{} syntax.
565 Note that the option string is parsed from left to right; if an option
566 occurs multiple times, the last one is taken.
568 The following options are available for LilyPond commands:
571 @item staffsize=@var{ht}
572 Set staff size to @var{ht}, which is measured in points.
575 Produce ragged-right lines with natural spacing, i.e.,
576 @code{ragged-right = ##t} is added to the LilyPond snippet. This is the
577 default for the @code{\lilypond@{@}} command if no @code{line-width}
578 option is present. It is also the default for the @code{lilypond}
579 environment if the @code{fragment} option is set, and no line width is
580 explicitly specified.
583 For single-line snippets, allow the staff length to be stretched to
584 equal that of the line width, i.e., @code{ragged-right = ##f} is
585 added to the LilyPond snippet.
588 @itemx line-width=@var{size}\@var{unit}
589 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
590 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
591 @code{pt}. This option affects LilyPond output (this is, the staff
592 length of the music snippet), not the text layout.
594 If used without an argument, set line width to a default value (as
595 computed with a heuristic algorithm).
597 If no @code{line-width} option is given, @command{lilypond-book} tries to
598 guess a default for @code{lilypond} environments which don't use the
599 @code{ragged-right} option.
602 Do not print the time signature, and turns off the timing (time signature,
603 bar lines) in the score.
606 Make @command{lilypond-book} add some boilerplate code so that you can
614 without @code{\layout}, @code{\score}, etc.
617 Do not add additional code to complete LilyPond code in music snippets.
618 Since this is the default, @code{nofragment} is redundant normally.
620 @item indent=@var{size}\@var{unit}
621 Set indentation of the first music system to @var{size}, using
622 @var{unit} as units. @var{unit} is one of the following strings:
623 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
624 LilyPond, not the text layout.
627 Set indentation of the first music system to zero. This option affects
628 LilyPond, not the text layout. Since no indentation is the default,
629 @code{noindent} is redundant normally.
632 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
633 the output into a quotation block. The value @q{0.4@dmn{in}} can be
634 controlled with the @code{exampleindent} option.
637 Set the amount by which the @code{quote} option indents a music snippet.
640 @itemx relative=@var{n}
641 Use relative octave mode. By default, notes are specified relative to
642 middle@tie{}C. The optional integer argument specifies the octave of
643 the starting note, where the default @code{1} is middle C.
644 @code{relative} option only works when @code{fragment} option is set,
645 so @code{fragment} is automatically implied by @code{relative},
646 regardless of the presence of any @code{(no)fragment} option in the
650 LilyPond also uses @command{lilypond-book} to produce its own
651 documentation. To do that, some more obscure music fragment options are
656 The argument of a LilyPond command is copied to the output file and
657 enclosed in a verbatim block, followed by any text given with the
658 @code{intertext} option (not implemented yet); then the actual music is
659 displayed. This option does not work well with @code{\lilypond@{@}} if
660 it is part of a paragraph.
662 If @code{verbatim} is used in a @code{lilypondfile} command, it is
663 possible to enclose verbatim only a part of the source file. If the
664 source file contain a comment containing @samp{begin verbatim} (without
665 quotes), quoting the source in the verbatim block will start after the
666 last occurrence of such a comment; similarly, quoting the source verbatim
667 will stop just before the first occurrence of a comment containing
668 @samp{end verbatim}, if there is any. In the following source file
669 example, the music will be interpreted in relative mode, but the
670 verbatim quote will not show the @code{relative} block, i.e.
673 \relative c' @{ % begin verbatim
680 will be printed with a verbatim block like
688 If you would like to translate comments and variable names in verbatim
689 output but not in the sources, you may set the environment variable
690 @code{LYDOC_LOCALEDIR} to a directory path; the directory should
691 contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
695 (Only for Texinfo output.) Prepend line @code{\version
696 @@w@{"@@version@{@}"@}} to @code{verbatim} output.
699 (Only for Texinfo output.) If @command{lilypond} is called with the
700 @option{--header=@/texidoc} option, and the file to be processed is
701 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
702 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
703 option makes @command{lilypond-book} include such files, adding its
704 contents as a documentation block right before the music snippet.
706 Assuming the file @file{foo@/.ly} contains
710 texidoc = "This file demonstrates a single note."
716 and we have this in our Texinfo document @file{test.texinfo}
719 @@lilypondfile[texidoc]@{foo.ly@}
723 the following command line gives the expected result
726 lilypond-book --pdf --process="lilypond \
727 -dbackend=eps --header=texidoc" test.texinfo
730 Most LilyPond test documents (in the @file{input} directory of the
731 distribution) are small @file{.ly} files which look exactly like this.
733 For localization purpose, if the Texinfo document contains
734 @code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
735 contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
736 is called with @option{--header=@/texidoc@var{LANG}}, then
737 @file{foo@/.texidoc@var{LANG}} will be included instead of
738 @file{foo@/.texidoc}.
741 (Only for Texinfo output.) This option is similar to quote, but only
742 the music snippet (and the optional verbatim block implied by
743 @code{verbatim} option) is put into a quotation block. This option is
744 useful if you want to @code{quote} the music snippet but not the
745 @code{texidoc} documentation block.
748 (Only for Texinfo output.) This option works similarly to
749 @code{texidoc} option: if @command{lilypond} is called with the
750 @option{--header=@/doctitle} option, and the file to be processed is
751 called @file{foo@/.ly} and contains a @code{doctitle} field in the
752 @code{\header}, it creates a file @file{foo@/.doctitle}. When
753 @code{doctitle} option is used, the contents of @file{foo@/.doctitle},
754 which should be a single line of @var{text}, is inserted in the
755 Texinfo document as @code{@@lydoctitle @var{text}}.
756 @code{@@lydoctitle} should be a macro defined in the Texinfo document.
757 The same remark about @code{texidoc} processing with localized
758 languages also applies to @code{doctitle}.
761 (Only for Texinfo output.) Do not translate comments and variable
762 names in the snippet quoted verbatim.
765 If a LilyPond input file is included with @code{\lilypondfile}, print
766 the file name right before the music snippet. For HTML output, this
767 is a link. Only the base name of the file is printed, i.e. the
768 directory part of the file path is stripped.
773 @node Invoking lilypond-book
774 @section Invoking @command{lilypond-book}
776 @command{lilypond-book} produces a file with one of the following
777 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
778 depending on the output format. All of @file{.tex}, @file{.texi} and
779 @file{.xml} files need further processing.
781 @subheading Format-specific instructions
783 @subsubheading @LaTeX{}
785 There are two ways of processing your @LaTeX{} document for printing or
786 publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
787 PostScript file with @LaTeX{} via a DVI to PostScript translator like
788 @command{dvips}. The first way is simpler and recommended@footnote{Note
789 that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
790 @LaTeX{} document, that is why we explain the two ways.}, and whichever
791 way you use, you can easily convert between PostScript and PDF with
792 tools, like @command{ps2pdf} and @command{pdf2ps} included in
795 To produce a PDF file through PDF@LaTeX{}, use
798 lilypond-book --pdf yourfile.lytex
799 pdflatex yourfile.tex
802 @cindex outline fonts
805 @cindex invoking dvips
806 To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
810 lilypond-book yourfile.lytex
812 dvips -Ppdf yourfile.dvi
817 The @file{.dvi} file created by this process will not contain
818 note heads. This is normal; if you follow the instructions, they
819 will be included in the @file{.ps} and @file{.pdf} files.
821 Running @command{dvips} may produce some warnings about fonts; these
822 are harmless and may be ignored. If you are running @command{latex} in
823 twocolumn mode, remember to add @code{-t landscape} to the
824 @command{dvips} options.
826 @subsubheading Texinfo
828 To produce a Texinfo document (in any output format), follow the normal
829 procedures for Texinfo; this is, either call @command{texi2pdf} or
830 @command{texi2dvi} or @command{makeinfo}, depending on the output format
833 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
834 an Info File, , , texinfo, GNU Texinfo}.
837 See the documentation of Texinfo for further details.
841 @subheading Command line options
843 @command{lilypond-book} accepts the following command line options:
846 @item -f @var{format}
847 @itemx --format=@var{format}
848 Specify the document type to process: @code{html}, @code{latex},
849 @code{texi} (the default) or @code{docbook}. If this option is missing,
850 @command{lilypond-book} tries to detect the format automatically, see
851 @ref{Filename extensions}. Currently, @code{texi} is the same as
854 @c This complicated detail is not implemented, comment it out -jm
856 The @code{texi} document type produces a Texinfo file with music
857 fragments in the printed output only. For getting images in the HTML
858 version, the format @code{texi-html} must be used instead.
861 @item -F @var{filter}
862 @itemx --filter=@var{filter}
863 Pipe snippets through @var{filter}. @code{lilypond-book} will
864 not --filter and --process at the same time. For example,
867 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
872 Print a short help message.
875 @itemx --include=@var{dir}
876 Add @var{dir} to the include path. @command{lilypond-book} also looks
877 for already compiled snippets in the include path, and does not write
878 them back to the output directory, so in some cases it is necessary to
879 invoke further processing commands such as @command{makeinfo} or
880 @command{latex} with the same @code{-I @var{dir}} options.
883 @itemx --output=@var{dir}
884 Place generated files in directory @var{dir}. Running
885 @command{lilypond-book} generates lots of small files that LilyPond will
886 process. To avoid all that garbage in the source directory, use the
887 @option{--output} command line option, and change to that directory
888 before running @command{latex} or @command{makeinfo}.
891 lilypond-book --output=out yourfile.lytex
896 @itemx --skip-lily-check
897 Do not fail if no lilypond output is found. It is used for LilyPond
898 Info documentation without images.
900 @itemx --skip-png-check
901 Do not fail if no PNG images are found for EPS files. It is used for
902 LilyPond Info documentation without images.
904 @itemx --lily-output-dir=@var{dir}
905 Write lily-XXX files to directory @var{dir}, link into @code{--output}
906 directory. Use this option to save building time for documents in
907 different directories which share a lot of identical snippets.
909 @itemx --info-images-dir=@var{dir}
910 Format Texinfo output so that Info will look for images of music in
913 @itemx --latex-program=@var{prog}
914 Run executable @command{prog} instead of @command{latex}. This is
915 useful if your document is processed with @command{xelatex}, for
918 @itemx --left-padding=@var{amount}
919 Pad EPS boxes by this much. @var{amount} is measured in millimeters,
920 and is 3.0 by default. This option should be used if the lines of
921 music stick out of the right margin.
923 The width of a tightly clipped system can vary, due to notation
924 elements that stick into the left margin, such as bar numbers and
925 instrument names. This option will shorten each line and move each
926 line to the right by the same amount.
928 @item -P @var{command}
929 @itemx --process=@var{command}
930 Process LilyPond snippets using @var{command}. The default command is
931 @code{lilypond}. @code{lilypond-book} will not @code{--filter} and
932 @code{--process} at the same time.
935 Create PDF files for use with PDF@LaTeX{}.
937 @itemx --use-source-file-names
938 Write snippet output files with the same base name as their source file.
939 This option works only for snippets included with @code{lilypondfile}
940 and only if directories implied by @code{--output-dir} and
941 @code{--lily-output-dir} options are different.
949 Print version information.
954 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
955 @LaTeX{} commands that change margins and line widths after the preamble
958 Only the first @code{\score} of a LilyPond block is processed.
961 @node Filename extensions
962 @section Filename extensions
964 You can use any filename extension for the input file, but if you do not
965 use the recommended extension for a particular format you may need to
966 manually specify the output format; for details, see @ref{Invoking
967 lilypond-book}. Otherwise, @command{lilypond-book} automatically
968 selects the output format based on the input filename's extension.
971 @multitable @columnfractions .2 .5
972 @item @strong{extension} @tab @strong{output format}
974 @item @file{.html} @tab HTML
975 @item @file{.htmly} @tab HTML
976 @item @file{.itely} @tab Texinfo
977 @item @file{.latex} @tab @LaTeX{}
978 @item @file{.lytex} @tab @LaTeX{}
979 @item @file{.lyxml} @tab DocBook
980 @item @file{.tely} @tab Texinfo
981 @item @file{.tex} @tab @LaTeX{}
982 @item @file{.texi} @tab Texinfo
983 @item @file{.texinfo} @tab Texinfo
984 @item @file{.xml} @tab HTML
988 If you use the same filename extension for the input file than the
989 extension @command{lilypond-book} uses for the output file, and if the
990 input file is in the same directory as @command{lilypond-book} working
991 directory, you must use @code{--output} option to make
992 @command{lilypond-book} running, otherwise it will exit with an error
993 message like @qq{Output would overwrite input file}.
996 @node lilypond-book templates
997 @section lilypond-book templates
999 These templates are for use with @code{lilypond-book}. If you're not familiar
1000 with this program, please refer to
1001 @ref{lilypond-book}.
1005 You can include LilyPond fragments in a LaTeX document.
1008 \documentclass[]@{article@}
1020 More LaTeX text, and options in square brackets.
1022 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1030 You can include LilyPond fragments in Texinfo; in fact, this entire manual
1031 is written in Texinfo.
1034 \input texinfo @c -*-texinfo-*-
1046 More Texinfo text, and options in brackets.
1048 @@lilypond[verbatim,fragment,ragged-right]
1059 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1065 Documents for lilypond-book may freely mix music and text. For
1075 Another bit of lilypond, this time with options:
1077 <lilypond fragment quote staffsize=26 verbatim>
1091 \documentclass{article}
1092 \usepackage{ifxetex}
1094 %xetex specific stuff
1095 \usepackage{xunicode,fontspec,xltxtra}
1096 \setmainfont[Numbers=OldStyle]{Times New Roman}
1099 %This can be empty if you are not going to use pdftex
1100 \usepackage[T1]{fontenc}
1101 \usepackage[utf8]{inputenc}
1102 \usepackage{mathptmx}%Times
1103 \usepackage{helvet}%Helvetica
1105 %Here you can insert all packages that pdftex also understands
1106 \usepackage[ngerman,finnish,english]{babel}
1107 \usepackage{graphicx}
1110 \title{A short document with LilyPond and xelatex}
1113 Normal \textbf{font} commands inside the \emph{text} work,
1114 because they \textsf{are supported by \LaTeX{} and XeteX.}
1115 If you want to use specific commands like \verb+\XeTeX+, you
1116 should include them again in a \verb+\ifxetex+ environment.
1117 You can use this to print the \ifxetex \XeTeX{} command \else
1118 XeTeX command \fi which is not known to normal \LaTeX .
1120 In normal text you can easily use LilyPond commands, like this:
1129 The fonts of snippets set with LilyPond will have to be set from
1131 of the snippet. For this you should read the AU on how to use
1134 \selectlanguage{ngerman}
1135 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1137 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1138 unterst__tzt werden.
1143 @node Sharing the table of contents
1144 @section Sharing the table of contents
1146 These functions already exist in the OrchestralLily package:
1149 @url{http://repo.or.cz/w/orchestrallily.git}
1152 For greater flexibility in text handling, some users prefer to
1153 export the table of contents from lilypond and read it into
1156 @subsubheading Exporting the ToC from LilyPond
1158 This assumes that your score has multiple movements in the same lilypond
1162 #(define (oly:create-toc-file layout pages)
1163 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1164 (if (not (null? label-table))
1165 (let* ((format-line (lambda (toc-item)
1166 (let* ((label (car toc-item))
1167 (text (caddr toc-item))
1168 (label-page (and (list? label-table)
1169 (assoc label label-table)))
1170 (page (and label-page (cdr label-page))))
1171 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1172 (formatted-toc-items (map format-line (toc-items)))
1173 (whole-string (string-join formatted-toc-items ",\n"))
1174 (output-name (ly:parser-output-name parser))
1175 (outfilename (format "~a.toc" output-name))
1176 (outfile (open-output-file outfilename)))
1177 (if (output-port? outfile)
1178 (display whole-string outfile)
1179 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1180 (close-output-port outfile)))))
1183 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1187 @subsubheading Importing the ToC into LaTeX
1189 In LaTeX, the header should include:
1191 @c no, this doesn't require the smallexample, but since the other
1192 @c two blocks on this page use it, I figured I might as well
1193 @c user it here as well, for consistency. -gp
1195 \usepackage@{pdfpages@}
1196 \includescore@{nameofthescore@}
1200 where @code{\includescore} is defined as:
1203 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1204 % \includescore@{PossibleExtension@}
1205 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1207 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1208 % This requires some heave latex tweaking, since reading in things from a file
1209 % and inserting it into the arguments of a macro is not (easily) possible
1211 % Solution by Patrick Fimml on #latex on April 18, 2009:
1212 % \readfile@{filename@}@{\variable@}
1213 % reads in the contents of the file into \variable (undefined if file
1215 \newread\readfile@@f
1216 \def\readfile@@line#1@{%
1217 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1218 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1219 \ifeof\readfile@@f\else%
1220 \readfile@@line@{#1@}%
1223 \def\readfile#1#2@{%
1224 \openin\readfile@@f=#1 %
1226 \typeout@{No TOC file #1 available!@}%
1229 \readfile@@line@{#2@}%
1231 \closein\readfile@@f%
1235 \newcommand@{\includescore@}[1]@{
1236 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1237 \let\oly@@addtotoc\undefined
1238 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1239 \ifx\oly@@addtotoc\undefined
1240 \includepdf[pages=-]@{\oly@@fname@}
1242 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1243 @{\oly@@fname@}@}\includeit
1249 @node Alternate methods of mixing text and music
1250 @section Alternative methods of mixing text and music
1252 Other means of mixing text and music (without
1253 @command{lilypond-book}) are discussed in
1254 @ref{LilyPond output in other programs}.