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. For single-line fragments, the default is to
416 \begin[indent=5\cm,raggedright]@{lilypond@}
422 sets indentation of the first music system to zero. This option
423 affects LilyPond, not the text layout.
426 sets linewidth to the width of a quotation and puts the output
427 in a quotation block.
430 Includes the @code{texidoc} field, if defined in the file. This is
431 only for Texinfo output.
433 In Texinfo, the music fragment is normally preceded by the
434 @code{texidoc} field from the @code{\header}. The LilyPond test
435 documents are composed from small @file{.ly} files in this way:
439 texidoc = "this file demonstrates a single note"
444 @item relative, relative=@var{N}
445 uses relative octave mode. By default, notes are specified relative
446 to middle C. The optional integer argument specifies the octave of the
447 starting note, where the default @code{1} is middle C.
451 @node Invoking lilypond-book
452 @section Invoking @command{lilypond-book}
454 Running @command{lilypond-book} generates lots of small files that
455 LilyPond will process. To avoid all that garbage in the source
456 directory use the @option{--output} command line option, and change to
457 that directory before running La@TeX{} or @file{makeinfo}:
460 lilypond-book --output=out yourfile.lytex
464 This will produce a @file{.tex} or @file{.texi} file. To produce pdf
465 output from the @file{.tex} file, you should do
469 dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
473 To produce a Texinfo document (in any output format), follow the normal
474 procedures for Texinfo.
476 @command{lilypond-book} accepts the following command line options:
479 @item @option{-f @var{format}}, @option{--format=@var{format}}
480 Specify the document type to process: @code{html}, @code{latex}, or
481 @code{texi} (the default). @command{lilypond-book} figures this
484 The @code{texi} document type produces a Texinfo file with music
485 fragments in the DVI output only. For getting images in the HTML
487 @code{texi-html} must be used.
489 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
490 Pipe snippets through @var{filter}.
494 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
497 @item @option{--help}
498 Print a short help message.
500 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
501 Add @var{DIR} to the include path.
503 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
504 Place generated files in @var{dir}.
506 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
507 Process LilyPond snippets using @var{command}. The default command is
510 @item @option{--verbose}
513 @item @option{--version}
514 Print version information.
517 For La@TeX{} input, the file to give to La@TeX{} has the extension
518 @file{.latex}. Texinfo input will be written to a file with the extension
523 The Texinfo command @code{pagesize} is not interpreted. Almost all
524 La@TeX{} commands that change margins and line widths are ignored.
526 Only the first @code{\score} of a LilyPond block is processed.
529 The size of a music block is limited to 1.5 KB, due to technical
530 problems with the Python regular expression engine. For longer files,
531 use @code{\lilypondfile}.
534 @node Filename extensions
535 @section Filename extensions
537 You can use any filename extension, but if you do not use the
538 recommended extension, you may need to manually specify what output
539 format you want. See @ref{Invoking lilypond-book} for details.
541 @code{Lilypond-book} automatically selects the output format based
546 @item @emph{.html} produces html output
548 @item @emph{.itely} produces texinfo output
550 @item @emph{.lytex} produces latex output