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::
42 * Filename extensions::
48 @node An example of a musicological document
49 @section An example of a musicological document
52 @cindex La@TeX{}, music in
53 @cindex HTML, music in
54 @cindex Texinfo, music in
55 Some texts contain music examples. These texts are musicological
56 treatises, songbooks or manuals like this. Such texts can be made by
57 hand, simply by importing a PostScript figure into the word processor.
58 However, there is an automated procedure to reduce the amount of work
59 involved HTML, La@TeX{}, and Texinfo documents.
61 A script called @code{lilypond-book} will extract the music fragments,
62 format them, and put back the resulting notation. Here we show a
63 small example for use with La@TeX{}. The example also contains explanatory text, so we will
64 not comment on it further
67 \documentclass[a4paper]{article}
70 Documents for lilypond-book may freely mix music and text. For
75 c2 g'2 \times 2/3 { f8 e d } c'2 g4
79 Options are put in brackets.
81 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
85 Larger examples can be put in a separate file, and introduced with
88 \lilypondfile[quote,noindent]{screech-boink.ly}
93 Under Unix, you can view the results as follows
98 lilypond-book --output=out/ lilybook.tex
99 @emph{lilypond-book (GNU LilyPond) 2.3.11}
100 @emph{Reading `input/tutorial/lilybook.tex'}
101 @emph{..lots of stuff deleted..}
102 @emph{Compiling `out//lilybook.tex'}
105 @emph{lots of stuff deleted}
109 To convert the file into a nice PDF document, run the following
113 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
117 Running lilypond-book and running latex creates a lot of temporary
118 files, which would clutter up the working directory. To remedy this,
119 use the @code{--output=@var{dir}} option. It will create the files in
120 a separate subdirectory @file{dir}.
122 Finally the result of the La@TeX{} example shown above.@footnote{ This
123 tutorial is processed with Texinfo, so the example is as well. This
124 gives slightly different results in layout.} This finishes the
129 Documents for lilypond-book may freely mix music and text. For
134 c2 g'2 \times 2/3 { f8 e d } c'2 g4
138 Options are put in brackets.
140 @lilypond[fragment,quote,staffsize=26,verbatim]
144 Larger examples can be put in a separate file, and introduced with
145 @code{\lilypondfile}.
147 @lilypondfile[quote,noindent]{screech-boink.ly}
155 @cindex documents, adding music to
158 @c @TeX{} in node name seems to barf
159 @node Integrating LaTeX and music
160 @section Integrating LaTeX and music
162 La@TeX{} is the de facto standard for publishing layouts in the exact
163 sciences. It is built on top of the @TeX{} typesetting engine, so it
164 provides the best typography available anywhere.
166 For more information about La@TeX{}
167 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
168 Short Introduction to La@TeX{}} provides a introduction to using
171 For La@TeX{}, music is entered using
174 \begin[options,go,here]@{lilypond@}
180 \lilypondfile[options,go,here]@{@var{filename}@}
187 \lilypond@{ YOUR LILYPOND CODE @}
190 Running lilypond-book yields a file that can be processed with
194 We show some examples here:
197 \begin[staffsize=26]@{lilypond@}
205 @lilypond[fragment,staffsize=26]
209 Then the short version:
212 \lilypond[staffsize=11]@{<c' e' g'>@}
218 @lilypond[fragment,staffsize=11]{<c' e' g'>}
220 The linewidth of the music will be adjust by examining the commands in
221 the document preamble, the part of the document before
222 @code{\begin@{document@}}. The @command{lilypond-book} command sends
223 these to La@TeX{} to find out how wide the text is. The line width
224 for the music fragments is then adjusted to the text width.
226 After @code{\begin@{document@}}, the column changing commands
227 @code{\onecolumn}, @code{\twocolumn} commands
230 @code{multicols} environment from the multicol package
232 are also interpreted.
234 @cindex titling and lilypond-book
235 @cindex @code{\header} in La@TeX{} documents
238 The music will be surrounded by @code{\preLilyPondExample} and
239 @code{\postLilyPondExample}, which are defined to be empty by default.
241 @cindex outline fonts
244 @cindex invoking dvips
246 For printing the La@TeX{} document, you will need to use dvips. For
247 producing PostScript with scalable fonts, add the following options to
248 the dvips command line:
250 -Ppdf -u+lilypond.map -u+ec-mftrace.map
254 PDF can then be produced with @code{ps2pdf}.
256 @cindex international characters
259 LilyPond does not use the La@TeX{} font handling scheme for lyrics and text
260 markups, so if you use characters in your lilypond-book
261 documents that are not included in the standard 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 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
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 When run on a lilypond-book, produces a @file{.texi} file containing
280 @code{@@image} tags for HTML and info. For the printed edition, the
281 raw @TeX{} output of LilyPond is included into the main document.
283 In the input file, music is specified like
286 @@lilypond[options,go,here]
289 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
290 @@lilypondfile[options,go,here]@{@var{filename}@}
293 When lilypond-book is run on it, this results in a texinfo file. We
294 show two simple examples here. First a complete block:
297 @@lilypond[staffsize=26]
309 Then the short version:
312 @@lilypond[staffsize=11]@{<c' e' g'>@}
318 @lilypond[fragment,staffsize=11]{ <c' e' g'> }
320 When producing texinfo, lilypond-book also generates bitmaps of the
321 music, so you can make a HTML document with embedded music.
327 @node Integrating HTML and music
328 @section Integrating HTML and music
330 Music is entered using
333 <lilypond relative=1 verbatim>
334 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
339 of which lilypond-book will produce a HTML with appropriate image tags for the
343 <lilypond relative=2 verbatim>
344 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
348 @lilypond[fragment,relative=2]
349 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
352 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
354 Some music in <lilypond a b c/> a line of text.
357 A special feature not (yet) available in other output formats, is the
358 @code{<lilypondfile>} tag, for example,
360 <lilypondfile>trip.ly</lilypondfile>
362 This runs @file{trip.ly} through @code{lilypond} (see also
363 @ref{Invoking lilypond}), and substitutes a preview image in the
364 output. The image links to a separate HTML file, so clicking it will
365 take the viewer to a menu, with links to images, midi and printouts.
367 @cindex titling in THML
368 @cindex preview image
371 @node Music fragment options
372 @section Music fragment options
374 The commands for lilypond-book have room to specify one or more of the
379 @var{contents} is copied into the source, enclosed in a verbatim block;
380 followed by any text given with the @code{intertext} option; then
381 the actual music is displayed. This option does not work with
382 the short version of the music blocks:
384 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
386 @item filename=@var{filename}
387 This names the file for the @code{printfilename} option. The argument
390 @item staffsize=@var{ht}
391 Sets the staff height to @var{ht}, which is measured in points.
394 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
395 works well for small music fragments.
397 @item linewidth=@var{size}\@var{unit}
398 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
399 This option affects LilyPond output, not the text layout.
402 prevents printing time signature.
405 adds some boilerplate code, so you can enter like
412 without @code{\layout}, @code{\score} or other red tape.
414 @item indent=@var{size}\@var{unit}
415 sets indentation of the first music system to @var{size},
416 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
417 not the text layout. For single-line fragments, the default is to
422 \begin[indent=5\cm,raggedright]@{lilypond@}
429 sets indentation of the first music system to zero. This option
430 affects LilyPond, not the text layout.
433 sets linewidth to the width of a quotation and puts the output
434 in a quotation block.
437 Includes the @code{texidoc} field, if defined in the file. This is
438 only for Texinfo output.
440 In Texinfo, the music fragment is normally preceded by the
441 @code{texidoc} field from the @code{\header}. The LilyPond test
442 documents are composed from small @file{.ly} files in this way:
446 texidoc = "this file demonstrates a single note"
451 @item relative, relative=@var{N}
452 uses relative octave mode. By default, notes are specified relative
453 to middle C. The optional integer argument specifies the octave of the
454 starting note, where the default @code{1} is middle C.
458 @node Invoking lilypond-book
459 @section Invoking lilypond-book
462 Running @command{lilypond-book} generates lots of small files that
463 LilyPond will process. To avoid all that garbage in the source
464 directory use the @option{--output} command line option, and change to
465 that directory before running La@TeX{} or @file{makeinfo}:
468 lilypond-book --output=out yourfile.lytex
469 cd out && latex yourfile.tex
473 @command{lilypond-book} accepts the following command line options:
476 @item @option{-f @var{format}}, @option{--format=@var{format}}
477 Specify the document type to process: @code{html}, @code{latex} or
478 @code{texi} (the default). @command{lilypond-book} figures this
481 The @code{texi} document type produces a texinfo file with music
482 fragments in the DVI output only. For getting images in the HTML
484 @code{texi-html} must be used.
486 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
487 Pipe snippets through @var{filter}.
491 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
494 @item @option{--help}
495 Print a short help message.
497 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
498 Add @var{DIR} to the include path.
500 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
501 Place generated files in @var{dir}.
503 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
504 Process lilypond snippets using @var{command}. The default command is
507 @item @option{--verbose}
510 @item @option{--version}
511 Print version information.
514 For La@TeX{} input, the file to give to La@TeX{} has extension
515 @file{.latex}. Texinfo input will be written to a file with 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