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 and
262 so if you use characters in your @command{lilypond-book}
263 documents that are not included in the standard US-ASCII character set,
264 include @code{\usepackage[latin1]@{inputenc@}} in the file
265 header but do not include @code{\usepackage[T1]@{fontenc@}}. Character
266 sets other than latin1 are not supported directly but may be handled by
267 explicitly specifying the @code{font-name} property in LilyPond and
268 using the corresponding La@TeX{} packages. Please consult the mailing list
272 @node Integrating Texinfo and music
273 @section Integrating Texinfo and music
275 Texinfo is the standard format for documentation at the GNU
276 project. An example of a texinfo document is this manual. The HTML,
277 PDF and Info versions of the manual are made from the document.
279 In the input file, music is specified like
282 @@lilypond[options,go,here]
285 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
286 @@lilypondfile[options,go,here]@{@var{filename}@}
289 When @command{lilypond-book} is run on it, this results in a texinfo file
290 (with extension @file{.texi}) containing @code{@@image} tags for HTML and
291 info. For the printed edition, the raw @TeX{} output of LilyPond is
292 included into the main document.
294 We show two simple examples here. A lilypond environment
312 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
318 @lilypond[fragment,staffsize=11]{<c' e' g'>}
320 When producing texinfo, @command{lilypond-book} also generates bitmaps of
321 the music (in PNG format), so you can make an HTML document with embedded
325 @node Integrating HTML and music
326 @section Integrating HTML and music
328 Music is entered using
331 <lilypond fragment relative=2>
332 \key c \minor c4 es g2
337 of which @command{lilypond-book} will produce a HTML with appropriate image
338 tags for the music fragments:
340 @lilypond[fragment,relative=2]
341 \key c \minor c4 es g2
344 For inline pictures, use @code{<lilypond ... />} syntax, where the options
345 are separated by a colon from the music, for example
348 Some music in <lilypond relative=2: a b c/> a line of text.
351 @c FIXME: check if this feature is coming soon; if not, @ignore this stuff.
352 A special feature not (yet) available in other output formats, is the
353 @code{<lilypondfile>} tag, for example,
355 <lilypondfile>trip.ly</lilypondfile>
357 This runs @file{trip.ly} through @code{lilypond} (see also
358 @ref{Invoking lilypond}), and substitutes a preview image in the
359 output. The image links to a separate HTML file, so clicking it will
360 take the viewer to a menu, with links to images, midi and printouts.
362 @cindex titling in THML
363 @cindex preview image
367 @node Music fragment options
368 @section Music fragment options
370 The commands for @command{lilypond-book} have room to specify one or more
371 of the following options:
375 @var{contents} is copied into the source, enclosed in a verbatim block;
376 followed by any text given with the @code{intertext} option; then
377 the actual music is displayed. This option does not work with
378 the short version of the music blocks:
380 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
382 @item filename=@var{filename}
383 This names the file for the @code{printfilename} option. The argument
386 @item staffsize=@var{ht}
387 Sets the staff height to @var{ht}, which is measured in points.
390 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
391 works well for small music fragments.
393 @item linewidth=@var{size}\@var{unit}
394 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
395 This option affects LilyPond output, not the text layout.
398 prevents printing time signature.
401 adds some boilerplate code, so you can enter like
408 without @code{\layout}, @code{\score} or other red tape.
410 @item indent=@var{size}\@var{unit}
411 sets indentation of the first music system to @var{size},
412 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
413 not the text layout. For single-line fragments, the default is to
418 \begin[indent=5\cm,raggedright]@{lilypond@}
424 sets indentation of the first music system to zero. This option
425 affects LilyPond, not the text layout.
428 sets linewidth to the width of a quotation and puts the output
429 in a quotation block.
432 Includes the @code{texidoc} field, if defined in the file. This is
433 only for Texinfo output.
435 In Texinfo, the music fragment is normally preceded by the
436 @code{texidoc} field from the @code{\header}. The LilyPond test
437 documents are composed from small @file{.ly} files in this way:
441 texidoc = "this file demonstrates a single note"
446 @item relative, relative=@var{N}
447 uses relative octave mode. By default, notes are specified relative
448 to middle C. The optional integer argument specifies the octave of the
449 starting note, where the default @code{1} is middle C.
453 @node Invoking lilypond-book
454 @section Invoking @command{lilypond-book}
456 Running @command{lilypond-book} generates lots of small files that
457 LilyPond will process. To avoid all that garbage in the source
458 directory use the @option{--output} command line option, and change to
459 that directory before running La@TeX{} or @file{makeinfo}:
462 lilypond-book --output=out yourfile.lytex
466 This will produce a @file{.tex} or @file{.texi} file. To produce pdf
467 output from the @file{.tex} file, you should do
471 dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
475 To produce a texinfo document (in any output format), follow the normal
476 procedures for texinfo.
478 @command{lilypond-book} accepts the following command line options:
481 @item @option{-f @var{format}}, @option{--format=@var{format}}
482 Specify the document type to process: @code{html}, @code{latex} or
483 @code{texi} (the default). @command{lilypond-book} figures this
486 The @code{texi} document type produces a texinfo file with music
487 fragments in the DVI output only. For getting images in the HTML
489 @code{texi-html} must be used.
491 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
492 Pipe snippets through @var{filter}.
496 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
499 @item @option{--help}
500 Print a short help message.
502 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
503 Add @var{DIR} to the include path.
505 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
506 Place generated files in @var{dir}.
508 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
509 Process lilypond snippets using @var{command}. The default command is
512 @item @option{--verbose}
515 @item @option{--version}
516 Print version information.
519 For La@TeX{} input, the file to give to La@TeX{} has extension
520 @file{.latex}. Texinfo input will be written to a file with extension
525 The Texinfo command @code{pagesize} is not interpreted. Almost all
526 La@TeX{} commands that change margins and line widths are ignored.
528 Only the first @code{\score} of a LilyPond block is processed.
531 The size of a music block is limited to 1.5 KB, due to technical
532 problems with the Python regular expression engine. For longer files,
533 use @code{\lilypondfile}.
536 @node Filename extensions
537 @section Filename extensions
539 You can use any filename extension, but if you do not use the
540 recommended extension, you may need to manually specify what output
541 format you want. See @ref{Invoking lilypond-book} for details.
543 @code{Lilypond-book} automatically selects the output format based
548 @item @emph{.html} produces html output
550 @item @emph{.itely} produces texinfo output
552 @item @emph{.lytex} produces latex output