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
30 documents. A tutorial on using lilypond-book is in @ref{Integrating
31 text and music}. For more information about La@TeX{}
32 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
33 Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
39 * An example of a musicological document::
40 * Integrating Texinfo and music::
41 * Integrating LaTeX and music::
42 * Integrating HTML and music::
43 * Music fragment options::
44 * Invoking lilypond-book::
50 @node An example of a musicological document
51 @section An example of a musicological document
54 @cindex La@TeX{}, music in
55 @cindex HTML, music in
56 @cindex Texinfo, music in
57 Some texts contain music examples. These texts are musicological
58 treatises, songbooks or manuals like this. Such texts can be made by
59 hand, simply by importing a PostScript figure into the word processor.
60 However, there is an automated procedure to reduce the amount of work
61 involved HTML, La@TeX{}, and Texinfo documents.
63 A script called @code{lilypond-book} will extract the music fragments,
64 format them, and put back the resulting notation. Here we show a
65 small example for use with @LaTeX{}. The example also contains explanatory text, so we will
66 not comment on it further
69 \documentclass[a4paper]{article}
72 Documents for lilypond-book may freely mix music and text. For
77 c2 g'2 \times 2/3 { f8 e d } c'2 g4
81 Options are put in brackets.
83 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
87 Larger examples can be put in a separate file, and introduced with
90 \lilypondfile[quote,noindent]{screech-boink.ly}
95 Under Unix, you can view the results as follows
100 lilypond-book --output=out/ lilybook.tex
101 @emph{lilypond-book (GNU LilyPond) 2.3.11}
102 @emph{Reading `input/tutorial/lilybook.tex'}
103 @emph{..lots of stuff deleted..}
104 @emph{Compiling `out//lilybook.tex'}
107 @emph{lots of stuff deleted}
111 To convert the file into a nice PDF document, run the following
115 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
119 Running lilypond-book and running latex creates a lot of temporary
120 files, which would clutter up the working directory. To remedy this,
121 use the @code{--output=@var{dir}} option. It will create the files in
122 a separate subdirectory @file{dir}.
124 Finally the result of the La@TeX{} example shown above.@footnote{ This
125 tutorial is processed with Texinfo, so the example is as well. This
126 gives slightly different results in layout.} This finishes the
131 Documents for lilypond-book may freely mix music and text. For
136 c2 g'2 \times 2/3 { f8 e d } c'2 g4
140 Options are put in brackets.
142 @lilypond[fragment,quote,staffsize=26,verbatim]
146 Larger examples can be put in a separate file, and introduced with
147 @code{\lilypondfile}.
149 @lilypondfile[quote,noindent]{screech-boink.ly}
157 @cindex documents, adding music to
160 @node Integrating Texinfo and music
161 @section Integrating Texinfo and music
163 Music is specified like this:
166 @@lilypond[options,go,here]
169 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
170 @@lilypondfile[options,go,here]@{@var{filename}@}
173 When lilypond-book is run on it, this results in a texinfo file. We
174 show two simple examples here. First a complete block:
177 @@lilypond[staffsize=26]
189 Then the short version:
192 @@lilypond[staffsize=11]@{<c' e' g'>@}
198 @lilypond[fragment,staffsize=11]{ <c' e' g'> }
200 When producing texinfo, lilypond-book also generates bitmaps of the
201 music, so you can make a HTML document with embedded music.
203 @c @TeX{} in node name seems to barf
204 @node Integrating LaTeX and music
205 @section Integrating LaTeX and music
208 For La@TeX{}, music is entered using
211 \begin[options,go,here]@{lilypond@}
217 \lilypondfile[options,go,here]@{@var{filename}@}
224 \lilypond@{ YOUR LILYPOND CODE @}
227 Running lilypond-book yields a file that can be processed with
231 We show some examples here:
234 \begin[staffsize=26]@{lilypond@}
242 @lilypond[fragment,staffsize=26]
246 Then the short version:
249 \lilypond[staffsize=11]@{<c' e' g'>@}
255 @lilypond[fragment,staffsize=11]{<c' e' g'>}
257 The linewidth of the music will be adjust by examining the commands in
258 the document preamble, the part of the document before
259 @code{\begin@{document@}}: @command{lilypond-book} sends these to
260 La@TeX{} to find out how wide the text is. The line width variable for
261 the music fragments are adjusted to the text width.
263 After @code{\begin@{document@}}, the column changing commands
264 @code{\onecolumn}, @code{\twocolumn} commands
267 @code{multicols} environment from the multicol package
269 are also interpreted.
271 @cindex titling and lilypond-book
272 @cindex @code{\header} in La@TeX{} documents
275 The music will be surrounded by @code{\preLilyPondExample} and
276 @code{\postLilyPondExample}, which are defined to be empty by default.
278 @cindex outline fonts
281 @cindex invoking dvips
283 For printing the LaTeX document, you will need to use dvips. For
284 producing PostScript with scalable fonts, add the following options to
285 the dvips command line:
287 -Ppdf -u+lilypond.map -u+ec-mftrace.map
291 PDF can then be produced with @code{ps2pdf}.
293 @cindex international characters
296 LilyPond does not use the LaTeX font handling scheme for lyrics and text
297 markups, so if you use characters in your lilypond-book
298 documents that are not included in the standard US-ASCII character set,
299 include @code{\usepackage[latin1]@{inputenc@}} in the file
300 header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
301 sets other than latin1 are not supported directly but may be handled by
302 explicitly specifying the @code{font-name} property in LilyPond and
303 using the corresponding LaTeX packages. Please consult the mailing list
310 @node Integrating HTML and music
311 @section Integrating HTML and music
313 Music is entered using
316 <lilypond relative=1 verbatim>
317 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
322 of which lilypond-book will produce a HTML with appropriate image tags for the
326 <lilypond relative=2 verbatim>
327 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
331 @lilypond[fragment,relative=2]
332 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
335 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
337 Some music in <lilypond a b c/> a line of text.
340 A special feature not (yet) available in other output formats, is the
341 @code{<lilypondfile>} tag, for example,
343 <lilypondfile>trip.ly</lilypondfile>
345 This runs @file{trip.ly} through @code{lilypond} (see also
346 @ref{Invoking lilypond}), and substitutes a preview image in the
347 output. The image links to a separate HTML file, so clicking it will
348 take the viewer to a menu, with links to images, midi and printouts.
350 @cindex titling in THML
351 @cindex preview image
354 @node Music fragment options
355 @section Music fragment options
357 The commands for lilypond-book have room to specify one or more of the
362 @var{contents} is copied into the source, enclosed in a verbatim block;
363 followed by any text given with the @code{intertext} option; then
364 the actual music is displayed. This option does not work with
365 the short version of the music blocks:
367 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
369 @item filename=@var{filename}
370 This names the file for the @code{printfilename} option. The argument
373 @item staffsize=@var{ht}
374 Sets the staff height to @var{ht}, which is measured in points.
377 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
378 works well for small music fragments.
380 @item linewidth=@var{size}\@var{unit}
381 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
382 This option affects LilyPond output, not the text layout.
385 prevents printing time signature.
389 overrides @command{lilypond-book} auto detection of what type of code is
390 in the LilyPond block, voice contents, or complete code.
392 @item indent=@var{size}\@var{unit}
393 sets indentation of the first music system to @var{size},
394 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
395 not the text layout. For single-line fragments, the default is to
400 \begin[indent=5\cm,raggedright]@{lilypond@}
407 sets indentation of the first music system to zero. This option
408 affects LilyPond, not the text layout.
411 sets linewidth to the width of a quotation and puts the output
412 in a quotation block.
415 Includes the @code{texidoc} field, if defined in the file. This is
416 only for Texinfo output.
418 In Texinfo, the music fragment is normally preceded by the
419 @code{texidoc} field from the @code{\header}. The LilyPond test
420 documents are composed from small @file{.ly} files in this way:
424 texidoc = "this file demonstrates a single note"
429 @item relative, relative=@var{N}
430 uses relative octave mode. By default, notes are specified relative
431 to middle C. The optional integer argument specifies the octave of the
432 @item relative, relative=@var{N}
433 uses relative octave mode. By default, notes are specified relative
434 to middle C. The optional integer argument specifies the octave of the
435 starting note, where the default @code{1} is middle C.
439 @node Invoking lilypond-book
440 @section Invoking lilypond-book
443 Running @command{lilypond-book} generates lots of small files that
444 LilyPond will process. To avoid all that garbage in the source
445 directory use the @option{--output} command line option, and change to
446 that directory before running La@TeX{} or @file{makeinfo}:
449 lilypond-book --output=out yourfile.lytex
450 cd out && latex yourfile.tex
454 @command{lilypond-book} accepts the following command line options:
457 @item @option{-f @var{format}}, @option{--format=@var{format}}
458 Specify the document type to process: @code{html}, @code{latex} or
459 @code{texi} (the default). @command{lilypond-book} figures this
462 The @code{texi} document type produces a texinfo file with music
463 fragments in the DVI output only. For getting images in the HTML
465 @code{texi-html} must be used.
467 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
468 Pipe snippets through @var{filter}.
472 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
475 @item @option{--help}
476 Print a short help message.
478 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
479 Add @var{DIR} to the include path.
481 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
482 Place generated files in @var{dir}.
484 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
485 Process lilypond snippets using @var{command}. The default command is
488 @item @option{--verbose}
491 @item @option{--version}
492 Print version information.
495 For La@TeX{} input, the file to give to La@TeX{} has extension
496 @file{.latex}. Texinfo input will be written to a file with extension
503 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
505 The Texinfo command @code{pagesize} is not interpreted. Almost all
506 La@TeX{} commands that change margins and line widths are ignored.
508 Only the first @code{\score} of a LilyPond block is processed.
511 The size of a music block is limited to 1.5 KB, due to technical
512 problems with the Python regular expression engine. For longer files,
513 use @code{\lilypondfile}.