7 ** AARGH.e We also have tutorial.itely: Integrating text and music.
9 Could also do with a cleanup. Lost inspiration to fix this manual
10 where to describe what?
15 @node Integrating text and music
16 @chapter Integrating text and music
18 If you want to add pictures of music to a document, you can simply do
19 it the way you would do with other types of pictures. The pictures
20 are created separately, yielding PostScript pictures or PNG images,
21 and those are included into a La@TeX{} or HTML document.
23 @command{lilypond-book} provides a way to automate this process: this
24 program extracts snippets of music from your document, runs LilyPond
25 on them, and outputs the document with pictures substituted for the
26 music. The line width and font size definitions for the music are
27 adjusted to match the layout of your document.
29 This procedure may be applied to La@TeX{}, @code{html} or Texinfo
36 * An example of a musicological document::
37 * Integrating Texinfo and music::
38 * Integrating LaTeX and music::
39 * Integrating HTML and music::
40 * Music fragment options::
41 * Invoking lilypond-book::
47 @node An example of a musicological document
48 @section An example of a musicological document
51 @cindex La@TeX{}, music in
52 @cindex HTML, music in
53 @cindex Texinfo, music in
54 Some texts contain music examples. These texts are musicological
55 treatises, songbooks or manuals like this. Such texts can be made by
56 hand, simply by importing a PostScript figure into the word processor.
57 However, there is an automated procedure to reduce the amount of work
58 involved HTML, La@TeX{}, and Texinfo documents.
60 A script called @code{lilypond-book} will extract the music fragments,
61 format them, and put back the resulting notation. Here we show a
62 small example for use with La@TeX{}. The example also contains explanatory text, so we will
63 not comment on it further
66 \documentclass[a4paper]{article}
69 Documents for lilypond-book may freely mix music and text. For
74 c2 g'2 \times 2/3 { f8 e d } c'2 g4
78 Options are put in brackets.
80 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
84 Larger examples can be put in a separate file, and introduced with
87 \lilypondfile[quote,noindent]{screech-boink.ly}
92 Under Unix, you can view the results as follows
97 lilypond-book --output=out/ lilybook.tex
98 @emph{lilypond-book (GNU LilyPond) 2.3.11}
99 @emph{Reading `input/tutorial/lilybook.tex'}
100 @emph{..lots of stuff deleted..}
101 @emph{Compiling `out//lilybook.tex'}
104 @emph{lots of stuff deleted}
108 To convert the file into a nice PDF document, run the following
112 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
116 Running lilypond-book and running latex creates a lot of temporary
117 files, which would clutter up the working directory. To remedy this,
118 use the @code{--output=@var{dir}} option. It will create the files in
119 a separate subdirectory @file{dir}.
121 Finally the result of the La@TeX{} example shown above.@footnote{ This
122 tutorial is processed with Texinfo, so the example is as well. This
123 gives slightly different results in layout.} This finishes the
128 Documents for lilypond-book may freely mix music and text. For
133 c2 g'2 \times 2/3 { f8 e d } c'2 g4
137 Options are put in brackets.
139 @lilypond[fragment,quote,staffsize=26,verbatim]
143 Larger examples can be put in a separate file, and introduced with
144 @code{\lilypondfile}.
146 @lilypondfile[quote,noindent]{screech-boink.ly}
154 @cindex documents, adding music to
157 @c @TeX{} in node name seems to barf
158 @node Integrating LaTeX and music
159 @section Integrating LaTeX and music
161 La@TeX{} is the de facto standard for publishing papers in the exact
162 sciences. It is built on top of the @TeX{} typesetting engine, so it
163 provides the best typography available anywhere.
165 For more information about La@TeX{}
166 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
167 Short Introduction to La@TeX{}} provides a introduction to using
170 For La@TeX{}, music is entered using
173 \begin[options,go,here]@{lilypond@}
179 \lilypondfile[options,go,here]@{@var{filename}@}
186 \lilypond@{ YOUR LILYPOND CODE @}
189 Running lilypond-book yields a file that can be processed with
193 We show some examples here:
196 \begin[staffsize=26]@{lilypond@}
204 @lilypond[fragment,staffsize=26]
208 Then the short version:
211 \lilypond[staffsize=11]@{<c' e' g'>@}
217 @lilypond[fragment,staffsize=11]{<c' e' g'>}
219 The linewidth of the music will be adjust by examining the commands in
220 the document preamble, the part of the document before
221 @code{\begin@{document@}}. The @command{lilypond-book} command sends
222 these to La@TeX{} to find out how wide the text is. The line width
223 for the music fragments is then adjusted to the text width.
225 After @code{\begin@{document@}}, the column changing commands
226 @code{\onecolumn}, @code{\twocolumn} commands
229 @code{multicols} environment from the multicol package
231 are also interpreted.
233 @cindex titling and lilypond-book
234 @cindex @code{\header} in La@TeX{} documents
237 The music will be surrounded by @code{\preLilyPondExample} and
238 @code{\postLilyPondExample}, which are defined to be empty by default.
240 @cindex outline fonts
243 @cindex invoking dvips
245 For printing the La@TeX{} document, you will need to use dvips. For
246 producing PostScript with scalable fonts, add the following options to
247 the dvips command line:
249 -Ppdf -u+lilypond.map -u+ec-mftrace.map
253 PDF can then be produced with @code{ps2pdf}.
255 @cindex international characters
258 LilyPond does not use the La@TeX{} font handling scheme for lyrics and text
259 markups, so if you use characters in your lilypond-book
260 documents that are not included in the standard US-ASCII character set,
261 include @code{\usepackage[latin1]@{inputenc@}} in the file
262 header but do not include @code{\usepackage[T1]@{fontenc@}}. Character
263 sets other than latin1 are not supported directly but may be handled by
264 explicitly specifying the @code{font-name} property in LilyPond and
265 using the corresponding La@TeX{} packages. Please consult the mailing list
271 @node Integrating Texinfo and music
272 @section Integrating Texinfo and music
274 Texinfo is the standard format for documentation at the GNU
275 project. An example of a texinfo document is this manual. The HTML,
276 PDF and Info versions of the manual are made from the document.
278 When run on a lilypond-book, produces a @file{.texi} file containing
279 @code{@@image} tags for HTML and info. For the printed edition, the
280 raw @TeX{} output of LilyPond is included into the main document.
282 In the input file, music is specified like
285 @@lilypond[options,go,here]
288 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
289 @@lilypondfile[options,go,here]@{@var{filename}@}
292 When lilypond-book is run on it, this results in a texinfo file. We
293 show two simple examples here. First a complete block:
296 @@lilypond[staffsize=26]
308 Then the short version:
311 @@lilypond[staffsize=11]@{<c' e' g'>@}
317 @lilypond[fragment,staffsize=11]{ <c' e' g'> }
319 When producing texinfo, lilypond-book also generates bitmaps of the
320 music, so you can make a HTML document with embedded music.
326 @node Integrating HTML and music
327 @section Integrating HTML and music
329 Music is entered using
332 <lilypond relative=1 verbatim>
333 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
338 of which lilypond-book will produce a HTML with appropriate image tags for the
342 <lilypond relative=2 verbatim>
343 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
347 @lilypond[fragment,relative=2]
348 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
351 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
353 Some music in <lilypond a b c/> a line of text.
356 A special feature not (yet) available in other output formats, is the
357 @code{<lilypondfile>} tag, for example,
359 <lilypondfile>trip.ly</lilypondfile>
361 This runs @file{trip.ly} through @code{lilypond} (see also
362 @ref{Invoking lilypond}), and substitutes a preview image in the
363 output. The image links to a separate HTML file, so clicking it will
364 take the viewer to a menu, with links to images, midi and printouts.
366 @cindex titling in THML
367 @cindex preview image
370 @node Music fragment options
371 @section Music fragment options
373 The commands for lilypond-book have room to specify one or more of the
378 @var{contents} is copied into the source, enclosed in a verbatim block;
379 followed by any text given with the @code{intertext} option; then
380 the actual music is displayed. This option does not work with
381 the short version of the music blocks:
383 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
385 @item filename=@var{filename}
386 This names the file for the @code{printfilename} option. The argument
389 @item staffsize=@var{ht}
390 Sets the staff height to @var{ht}, which is measured in points.
393 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
394 works well for small music fragments.
396 @item linewidth=@var{size}\@var{unit}
397 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
398 This option affects LilyPond output, not the text layout.
401 prevents printing time signature.
404 adds some boilerplate code, so you can enter like
411 without @code{\paper}, @code{\score} or other red tape.
413 @item indent=@var{size}\@var{unit}
414 sets indentation of the first music system to @var{size},
415 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
416 not the text layout. For single-line fragments, the default is to
421 \begin[indent=5\cm,raggedright]@{lilypond@}
428 sets indentation of the first music system to zero. This option
429 affects LilyPond, not the text layout.
432 sets linewidth to the width of a quotation and puts the output
433 in a quotation block.
436 Includes the @code{texidoc} field, if defined in the file. This is
437 only for Texinfo output.
439 In Texinfo, the music fragment is normally preceded by the
440 @code{texidoc} field from the @code{\header}. The LilyPond test
441 documents are composed from small @file{.ly} files in this way:
445 texidoc = "this file demonstrates a single note"
450 @item relative, relative=@var{N}
451 uses relative octave mode. By default, notes are specified relative
452 to middle C. The optional integer argument specifies the octave of the
453 starting note, where the default @code{1} is middle C.
457 @node Invoking lilypond-book
458 @section Invoking lilypond-book
461 Running @command{lilypond-book} generates lots of small files that
462 LilyPond will process. To avoid all that garbage in the source
463 directory use the @option{--output} command line option, and change to
464 that directory before running La@TeX{} or @file{makeinfo}:
467 lilypond-book --output=out yourfile.lytex
468 cd out && latex yourfile.tex
472 @command{lilypond-book} accepts the following command line options:
475 @item @option{-f @var{format}}, @option{--format=@var{format}}
476 Specify the document type to process: @code{html}, @code{latex} or
477 @code{texi} (the default). @command{lilypond-book} figures this
480 The @code{texi} document type produces a texinfo file with music
481 fragments in the DVI output only. For getting images in the HTML
483 @code{texi-html} must be used.
485 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
486 Pipe snippets through @var{filter}.
490 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
493 @item @option{--help}
494 Print a short help message.
496 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
497 Add @var{DIR} to the include path.
499 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
500 Place generated files in @var{dir}.
502 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
503 Process lilypond snippets using @var{command}. The default command is
506 @item @option{--verbose}
509 @item @option{--version}
510 Print version information.
513 For La@TeX{} input, the file to give to La@TeX{} has extension
514 @file{.latex}. Texinfo input will be written to a file with extension
521 The Texinfo command @code{pagesize} is not interpreted. Almost all
522 La@TeX{} commands that change margins and line widths are ignored.
524 Only the first @code{\score} of a LilyPond block is processed.
527 The size of a music block is limited to 1.5 KB, due to technical
528 problems with the Python regular expression engine. For longer files,
529 use @code{\lilypondfile}.