1 @c -*- coding: latin-1; mode: texinfo; -*-
8 ** AARGH. We also have tutorial.itely: Integrating text and music.
10 Could also do with a cleanup. Lost inspiration to fix this manual
11 where to describe what?
17 @node Integrating text and music
18 @chapter Integrating text and music
20 If you want to add pictures of music to a document, you can simply do it
21 the way you would do with other types of pictures. The pictures are
22 created separately, yielding PostScript output or PNG images, and those
23 are included into a La@TeX{} or HTML document.
25 @command{lilypond-book} provides a way to automate this process: This
26 program extracts snippets of music from your document, runs
27 @command{lilypond} on them, and outputs the document with pictures
28 substituted for the music. The line width and font size definitions for
29 the music are adjusted to match the layout of your document.
31 This procedure may be applied to La@TeX{}, HTML or Texinfo documents.
34 * An example of a musicological document::
35 * Integrating LaTeX and music::
36 * Integrating Texinfo and music::
37 * Integrating HTML and music::
38 * Music fragment options::
39 * Invoking lilypond-book::
40 * Filename extensions::
44 @node An example of a musicological document
45 @section An example of a musicological document
48 @cindex La@TeX{}, music in
49 @cindex HTML, music in
50 @cindex Texinfo, music in
51 Some texts contain music examples. These texts are musicological
52 treatises, songbooks, or manuals like this. Such texts can be made by
53 hand, simply by importing a PostScript figure into the word processor.
54 However, there is an automated procedure to reduce the amount of work
55 involved in HTML, La@TeX{}, and Texinfo documents.
57 A script called @code{lilypond-book} will extract the music fragments,
58 format them, and put back the resulting notation. Here we show a small
59 example for use with La@TeX{}. The example also contains explanatory
60 text, so we will not comment on it further.
64 \documentclass[a4paper]{article}
67 Documents for @command{lilypond-book} may freely mix music and text.
72 c2 g'2 \times 2/3 { f8 e d } c'2 g4
76 Options are put in brackets.
78 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
82 Larger examples can be put into a separate file, and introduced with
85 \lilypondfile[quote,noindent]{screech-boink.ly}
91 Under Unix, you can view the results as follows
96 lilypond-book --output=out lilybook.tex
97 @emph{lilypond-book (GNU LilyPond) 2.5.0}
98 @emph{Reading lilybook.tex...}
99 @emph{..lots of stuff deleted..}
100 @emph{Compiling out/lilybook.tex...}
103 @emph{lots of stuff deleted}
107 To convert the file into a nice PDF document, run the following commands
110 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
114 Running @command{lilypond-book} and @command{latex} creates a lot of
115 temporary files, which would clutter up the working directory. To
116 remedy this, use the @code{--output=@var{dir}} option. It will create
117 the files in a separate subdirectory @file{dir}.
119 Finally the result of the La@TeX{} example shown above.@footnote{This
120 tutorial is processed with Texinfo, so the example gives slightly
121 different results in layout.} This finishes the tutorial section.
125 Documents for @command{lilypond-book} may freely mix music and text.
130 c2 g'2 \times 2/3 { f8 e d } c'2 g4
134 Options are put in brackets.
136 @lilypond[fragment,quote,staffsize=26,verbatim]
140 Larger examples can be put into a separate file, and introduced with
141 @code{\lilypondfile}.
143 @lilypondfile[quote,noindent]{screech-boink.ly}
152 @cindex documents, adding music to
155 @node Integrating LaTeX and music
156 @section Integrating La@TeX{} and music
158 La@TeX{} is the de-facto standard for publishing layouts in the exact
159 sciences. It is built on top of the @TeX{} typesetting engine,
160 providing the best typography available anywhere.
163 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
164 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
167 Music is entered using
170 \begin[options,go,here]@{lilypond@}
179 \lilypondfile[options,go,here]@{@var{filename}@}
186 \lilypond@{ YOUR LILYPOND CODE @}
189 Running @command{lilypond-book} yields a file that can be further
190 processed with La@TeX{}.
192 We show some examples here. The lilypond environment
195 \begin[quote,fragment,staffsize=26]@{lilypond@}
203 @lilypond[quote,fragment,staffsize=26]
210 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
216 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
219 Currently, you cannot include @code{@{} or @code{@}} within
220 @code{\lilypond@{@}}, so this command is only useful with the
221 @code{fragment} option.
223 The default linewidth of the music will be adjusted by examining the
224 commands in the document preamble, the part of the document before
225 @code{\begin@{document@}}. The @command{lilypond-book} command sends
226 these to La@TeX{} to find out how wide the text is. The line width for
227 the music fragments is then adjusted to the text width. Note that this
228 heuristic algorithm can fail easily; in such cases it is necessary to
229 use the @code{linewidth} music fragment option.
231 @cindex titling and lilypond-book
232 @cindex @code{\header} in La@TeX{} documents
234 Each snippet calls @code{\preLilyPondExample} before and
235 @code{\postLilyPondExample} after the music if those macros have been
238 @cindex outline fonts
241 @cindex invoking dvips
243 For printing the La@TeX{} document you need a DVI to PostScript
244 translator like @command{dvips}. For producing PostScript with scalable
245 fonts, add the following options to the @command{dvips} command line:
248 -Ppdf -u+lilypond.map -u+ec-mftrace.map
252 PDF can then be produced with a PostScript to PDF translator like
253 @code{ps2pdf} (which is part of GhostScript).
255 @cindex international characters
258 LilyPond does not use the La@TeX{} font handling scheme for lyrics and
259 text markups; it uses the EC font family and has limited support for
260 selecting an input encoding with the @code{\encoding} keyword if the
261 output is directly processed (these limitations primarily affect
262 LilyPond's native PostScript output). With @command{lilypond-book}, the
263 encoding issues are completely handled by the document which includes
264 LilyPond snippets; @command{lilypond} outputs all text strings without
265 modification. The drawback is that LilyPond always applies the EC font
266 metrics to those strings for computing the locations within the music
267 snippets; this often causes unpleasant horizontal (and vertical) shifts.
268 With other words, support for encodings other than @w{latin-1} is
269 possible but usually yields badly positioned text. Future versions of
270 LilyPond will fix this.
272 Since @w{latin-1} is the default encoding for LilyPond markup and lyrics
273 it is not necessary to explicitly add @code{\encoding "latin1"} to
274 LilyPond snippets. You might also consider the use of @code{\encoding
275 "TeX"} instead which basically makes LilyPond skip @TeX{} commands
276 (starting with a backslash) and braces in text strings -- it is not
277 recommended, though, since LilyPond gives only a rough approximation to
278 the real string length.
280 As a corrolary of the last paragraphs the following two lines should be
281 present in the La@TeX{} document preamble
284 \usepackage[latin1]@{inputenc@}
285 \usepackage[T1]@{fontenc@}
289 and real @w{latin-1} characters should be used in LilyPond snippets; for
290 example, use @code{ß}, not @code{\ss}.
293 @node Integrating Texinfo and music
294 @section Integrating Texinfo and music
296 Texinfo is the standard format for documentation of the GNU project. An
297 example of a Texinfo document is this manual. The HTML, PDF, and Info
298 versions of the manual are made from the Texinfo document.
300 In the input file, music is specified with
303 @@lilypond[options,go,here]
312 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
319 @@lilypondfile[options,go,here]@{@var{filename}@}
322 When @command{lilypond-book} is run on it, this results in a Texinfo
323 file (with extension @file{.texi}) containing @code{@@image} tags for
324 HTML and info output. For the printed edition, the raw @TeX{} output of
325 LilyPond is included in the main document.
327 We show two simple examples here. A @code{lilypond} environment
345 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
351 @lilypond[fragment,staffsize=11]{<c' e' g'>}
353 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
354 in-line image. It always gets a paragraph of its own.
356 When using the Texinfo output format, @command{lilypond-book} also
357 generates bitmaps of the music (in PNG format), so you can make an HTML
358 document with embedded music.
361 @node Integrating HTML and music
362 @section Integrating HTML and music
364 Music is entered using
367 <lilypond fragment relative=2>
368 \key c \minor c4 es g2
373 @command{lilypond-book} then produces an HTML file with appropriate image
374 tags for the music fragments:
376 @lilypond[fragment,relative=2]
377 \key c \minor c4 es g2
380 For inline pictures, use @code{<lilypond ... />}, where the options
381 are separated by a colon from the music, for example
384 Some music in <lilypond relative=2: a b c/> a line of text.
387 To include separate files, say
390 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
393 @cindex titling in HTML
394 @cindex preview image
398 @node Music fragment options
399 @section Music fragment options
401 In the following, a ``LilyPond command'' refers to any command described
402 in the previous sections which is handled by @command{lilypond-book} to
403 produce a music snippet. For simplicity, LilyPond commands are only
404 shown in La@TeX{} syntax.
406 Note that the option string is parsed from left to right; if an option
407 occurs multiple times, the last one is taken.
409 The following options are available for LilyPond commands:
412 @item staffsize=@var{ht}
413 Set staff size to @var{ht}, which is measured in points.
416 Produce ragged-right lines with natural spacing (i.e., @code{raggedright
417 = ##t} is added to the LilyPond snippet). This is the default for the
418 @code{\lilypond@{@}} command if no @code{linewidth} option is present.
419 It is also the default for the @code{lilypond} environment if the
420 @code{fragment} option is set, and no line width is explicitly
424 @itemx linewidth=@var{size}\@var{unit}
425 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
426 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
427 @code{pt}. This option affects LilyPond output (this is, the staff
428 length of the music snippet), not the text layout.
430 If used without an argument, set line width to a default value (as
431 computed with a heuristic algorithm).
433 If no @code{linewidth} option is given, @command{lilypond-book} tries to
434 guess a default for @code{lilypond} environments which don't use the
435 @code{raggedright} option.
438 Do not print the time signature.
441 Make @command{lilypond-book} add some boilerplate code so that you can
449 without @code{\layout}, @code{\score}, etc.
452 Don't add additional code to complete LilyPond code in music snippets.
453 Since this is the default, @code{nofragment} is redundant normally.
455 @item indent=@var{size}\@var{unit}
456 Set indentation of the first music system to @var{size}, using
457 @var{unit} as units. @var{unit} is one of the following strings:
458 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
459 LilyPond, not the text layout.
462 Set indentation of the first music system to zero. This option affects
463 LilyPond, not the text layout. Since no indentation is the default,
464 @code{noindent} is redundant normally.
467 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
468 the output into a quotation block. The value `0.4@dmn{in}' can be
469 controlled with the @code{exampleindent} option.
472 Set the amount by which the @code{quote} option indents a music snippet.
475 @itemx relative=@var{n}
476 Use relative octave mode. By default, notes are specified relative to
477 middle@tie{}C. The optional integer argument specifies the octave of
478 the starting note, where the default @code{1} is middle C.
481 LilyPond also uses @command{lilypond-book} to produce its own
482 documentation. To do that, some more obscure music fragment options are
487 The argument of a LilyPond command is copied to the output file and
488 enclosed in a verbatim block, followed by any text given with the
489 @code{intertext} option (not implemented yet); then the actual music is
490 displayed. This option does not work well with @code{\lilypond@{@}} if
491 it is part of a paragraph.
494 (Only for Texinfo output.) If @command{lilypond} is called with the
495 @option{--header=@/texidoc} option, and the file to be processed is
496 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
497 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
498 option makes @command{lilypond-book} include such files, adding its
499 contents as a documentation block right before the music snippet.
501 Assuming the file @file{foo@/.ly} contains
505 texidoc = "This file demonstrates a single note."
511 and we have this in our Texinfo document @file{test.texinfo}
514 @@lilypondfile[texidoc]@{foo.ly@}
518 the following command line gives the expected result
521 lilypond-book --process="lilypond --format=tex --tex \
522 --header=texidoc test.texinfo
525 Most LilyPond test documents (in the @file{input} directory of the
526 distribution) are small @file{.ly} files which look exactly like this.
529 If a LilyPond input file is included with @code{\lilypondfile}, print
530 the file name right before the music snippet. For HTML output, this is
535 @node Invoking lilypond-book
536 @section Invoking @command{lilypond-book}
538 Running @command{lilypond-book} generates lots of small files that
539 LilyPond will process. To avoid all that garbage in the source
540 directory use the @option{--output} command line option, and change to
541 that directory before running La@TeX{} or @file{makeinfo}:
544 lilypond-book --output=out yourfile.lytex
548 This will produce a @file{.tex} or @file{.texi} file. To produce pdf
549 output from the @file{.tex} file, you should do
553 dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
557 To produce a Texinfo document (in any output format), follow the normal
558 procedures for Texinfo.
560 @command{lilypond-book} accepts the following command line options:
563 @item @option{-f @var{format}}, @option{--format=@var{format}}
564 Specify the document type to process: @code{html}, @code{latex}, or
565 @code{texi} (the default). @command{lilypond-book} figures this
568 The @code{texi} document type produces a Texinfo file with music
569 fragments in the DVI output only. For getting images in the HTML
571 @code{texi-html} must be used.
573 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
574 Pipe snippets through @var{filter}.
578 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
581 @item @option{--help}
582 Print a short help message.
584 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
585 Add @var{DIR} to the include path.
587 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
588 Place generated files in @var{dir}.
590 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
591 Process LilyPond snippets using @var{command}. The default command is
594 @item @option{--verbose}
597 @item @option{--version}
598 Print version information.
601 For La@TeX{} input, the file to give to La@TeX{} has the extension
602 @file{.latex}. Texinfo input will be written to a file with the extension
607 The Texinfo command @code{pagesize} is not interpreted. Almost all
608 La@TeX{} commands that change margins and line widths are ignored.
610 Only the first @code{\score} of a LilyPond block is processed.
613 The size of a music block is limited to 1.5 KB, due to technical
614 problems with the Python regular expression engine. For longer files,
615 use @code{\lilypondfile}.
618 @node Filename extensions
619 @section Filename extensions
621 You can use any filename extension, but if you do not use the
622 recommended extension, you may need to manually specify what output
623 format you want. See @ref{Invoking lilypond-book} for details.
625 @command{lilypond-book} automatically selects the output format based
630 @item @file{.html} produces html output
632 @item @file{.itely} produces texinfo output
634 @item @file{.lytex} produces latex output