1 @c -*- coding: latin-1; mode: texinfo; -*-
8 ** AARGH.e 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
21 it the way you would do with other types of pictures. The pictures
22 are created separately, yielding PostScript output or PNG images,
23 and those 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
59 small example for use with La@TeX{}. The example also contains
60 explanatory 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
111 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
115 Running @command{lilypond-book} and @command{latex} creates a lot of
116 temporary files, which would clutter up the working directory. To remedy
117 this, use the @code{--output=@var{dir}} option. It will create the files
118 in a separate subdirectory @file{dir}.
120 Finally the result of the La@TeX{} example shown above.@footnote{This
121 tutorial is processed with Texinfo, so the example gives slightly
122 different results in layout.} This finishes the tutorial section.
126 Documents for @command{lilypond-book} may freely mix music and text.
131 c2 g'2 \times 2/3 { f8 e d } c'2 g4
135 Options are put in brackets.
137 @lilypond[fragment,quote,staffsize=26,verbatim]
141 Larger examples can be put into a separate file, and introduced with
142 @code{\lilypondfile}.
144 @lilypondfile[quote,noindent]{screech-boink.ly}
153 @cindex documents, adding music to
156 @node Integrating LaTeX and music
157 @section Integrating La@TeX{} and music
159 La@TeX{} is the de-facto standard for publishing layouts in the exact
160 sciences. It is built on top of the @TeX{} typesetting engine, providing
161 the best typography available anywhere.
163 See @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
164 The Not So Short Introduction to La@TeX{}} for an overview on how to use
167 Music is entered using
170 \begin[options,go,here]@{lilypond@}
179 \lilypondfile[options,go,here]@{@var{filename}@}
186 \lilypond@{ YOUR LILYPOND CODE @}
190 Running @command{lilypond-book} yields a file that can be further processed
193 We show some examples here. The lilypond environment
196 \begin[quote,fragment,staffsize=26]@{lilypond@}
204 @lilypond[quote,fragment,staffsize=26]
211 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
217 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
220 You cannot include @{ or @} in the short version of @code{\lilypond@{@}},
221 so it is only useful with the @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
227 for the music fragments is then adjusted to the text width. Note that
228 this heuristic algorithm can fail easily; in such cases it is necessary
229 to 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 translator
244 like @command{dvips}. For producing PostScript with scalable fonts, add
245 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 text
259 markups; it uses the EC font family, so if you use characters in your
260 @command{lilypond-book} documents that are not included in the standard
261 US-ASCII character set,
262 include @code{\usepackage[latin1]@{inputenc@}} in the file
263 header but do not include @code{\usepackage[T1]@{fontenc@}}. Character
264 sets other than @code{latin1} are not supported directly but may be handled by
265 explicitly specifying the @code{font-name} property in LilyPond and
266 using the corresponding La@TeX{} packages. Please consult the mailing list
270 @node Integrating Texinfo and music
271 @section Integrating Texinfo and music
273 Texinfo is the standard format for documentation at the GNU
274 project. An example of a Texinfo document is this manual. The HTML,
275 PDF, and Info versions of the manual are made from the Texinfo document.
277 In the input file, music is specified like
280 @@lilypond[options,go,here]
283 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
284 @@lilypondfile[options,go,here]@{@var{filename}@}
287 When @command{lilypond-book} is run on it, this results in a Texinfo file
288 (with extension @file{.texi}) containing @code{@@image} tags for HTML and
289 info. For the printed edition, the raw @TeX{} output of LilyPond is
290 included into the main document.
292 We show two simple examples here. A @code{lilypond} environment
310 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
316 @lilypond[fragment,staffsize=11]{<c' e' g'>}
318 When producing Texinfo, @command{lilypond-book} also generates bitmaps of
319 the music (in PNG format), so you can make an HTML document with embedded
323 @node Integrating HTML and music
324 @section Integrating HTML and music
326 Music is entered using
329 <lilypond fragment relative=2>
330 \key c \minor c4 es g2
335 of which @command{lilypond-book} will produce a HTML with appropriate image
336 tags for the music fragments:
338 @lilypond[fragment,relative=2]
339 \key c \minor c4 es g2
342 For inline pictures, use @code{<lilypond ... />} syntax, where the options
343 are separated by a colon from the music, for example
346 Some music in <lilypond relative=2: a b c/> a line of text.
349 @c FIXME: check if this feature is coming soon; if not, @ignore this stuff.
350 A special feature not (yet) available in other output formats, is the
351 @code{<lilypondfile>} tag, for example,
353 <lilypondfile>trip.ly</lilypondfile>
355 This runs @file{trip.ly} through @code{lilypond} (see also
356 @ref{Invoking lilypond}), and substitutes a preview image in the
357 output. The image links to a separate HTML file, so clicking it will
358 take the viewer to a menu, with links to images, midi output, and printouts.
360 @cindex titling in THML
361 @cindex preview image
365 @node Music fragment options
366 @section Music fragment options
368 The commands for @command{lilypond-book} have room to specify one or more
369 of the following options:
373 @var{contents} is copied into the source, enclosed in a verbatim block;
374 followed by any text given with the @code{intertext} option; then
375 the actual music is displayed. This option does not work with
376 the short version of the music blocks:
378 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
380 @item filename=@var{filename}
381 This names the file for the @code{printfilename} option. The argument
384 @item staffsize=@var{ht}
385 Sets the staff height to @var{ht}, which is measured in points.
388 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
389 works well for small music fragments.
391 @item linewidth=@var{size}\@var{unit}
392 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
393 This option affects LilyPond output, not the text layout.
396 prevents printing the time signature.
399 adds some boilerplate code, so you can enter like
406 without @code{\layout}, @code{\score} or other red tape.
408 @item indent=@var{size}\@var{unit}
409 sets indentation of the first music system to @var{size},
410 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
411 not the text layout. The default is to use no indentation.
415 \begin[indent=5\cm,raggedright]@{lilypond@}
421 sets indentation of the first music system to zero. This option
422 affects LilyPond, not the text layout.
425 sets linewidth to the width of a quotation and puts the output
426 in a quotation block.
429 Includes the @code{texidoc} field, if defined in the file. This is
430 only for Texinfo output.
432 In Texinfo, the music fragment is normally preceded by the
433 @code{texidoc} field from the @code{\header}. The LilyPond test
434 documents are composed from small @file{.ly} files in this way:
438 texidoc = "this file demonstrates a single note"
443 @item relative, relative=@var{N}
444 uses relative octave mode. By default, notes are specified relative
445 to middle C. The optional integer argument specifies the octave of the
446 starting note, where the default @code{1} is middle C.
450 @node Invoking lilypond-book
451 @section Invoking @command{lilypond-book}
453 Running @command{lilypond-book} generates lots of small files that
454 LilyPond will process. To avoid all that garbage in the source
455 directory use the @option{--output} command line option, and change to
456 that directory before running La@TeX{} or @file{makeinfo}:
459 lilypond-book --output=out yourfile.lytex
463 This will produce a @file{.tex} or @file{.texi} file. To produce pdf
464 output from the @file{.tex} file, you should do
468 dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
472 To produce a Texinfo document (in any output format), follow the normal
473 procedures for Texinfo.
475 @command{lilypond-book} accepts the following command line options:
478 @item @option{-f @var{format}}, @option{--format=@var{format}}
479 Specify the document type to process: @code{html}, @code{latex}, or
480 @code{texi} (the default). @command{lilypond-book} figures this
483 The @code{texi} document type produces a Texinfo file with music
484 fragments in the DVI output only. For getting images in the HTML
486 @code{texi-html} must be used.
488 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
489 Pipe snippets through @var{filter}.
493 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
496 @item @option{--help}
497 Print a short help message.
499 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
500 Add @var{DIR} to the include path.
502 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
503 Place generated files in @var{dir}.
505 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
506 Process LilyPond snippets using @var{command}. The default command is
509 @item @option{--verbose}
512 @item @option{--version}
513 Print version information.
516 For La@TeX{} input, the file to give to La@TeX{} has the extension
517 @file{.latex}. Texinfo input will be written to a file with the extension
522 The Texinfo command @code{pagesize} is not interpreted. Almost all
523 La@TeX{} commands that change margins and line widths are ignored.
525 Only the first @code{\score} of a LilyPond block is processed.
528 The size of a music block is limited to 1.5 KB, due to technical
529 problems with the Python regular expression engine. For longer files,
530 use @code{\lilypondfile}.
533 @node Filename extensions
534 @section Filename extensions
536 You can use any filename extension, but if you do not use the
537 recommended extension, you may need to manually specify what output
538 format you want. See @ref{Invoking lilypond-book} for details.
540 @code{Lilypond-book} automatically selects the output format based
545 @item @emph{.html} produces html output
547 @item @emph{.itely} produces texinfo output
549 @item @emph{.lytex} produces latex output