X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=52d18c5f484c2c4ec7d599a8488a8e7e8929b201;hb=63ed51a9691f1f792f0e6a7df898d1db5f734e26;hp=08640cb8a2fcc0392c0100b4d91aa06390c8d7ce;hpb=d79cbfc7e9552f133eb8e3bca00daea1aaa4c1ba;p=lilypond.git diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index 08640cb8a2..52d18c5f48 100644 --- a/Documentation/user/lilypond-book.itely +++ b/Documentation/user/lilypond-book.itely @@ -12,38 +12,139 @@ TODO: cleanup @end ignore -@node Integrating text and music with lilypond-book -@chapter Integrating text and music with lilypond-book +@node Integrating text and music +@chapter Integrating text and music If you want to add pictures of music to a document, you can simply do -it the way you would do with other types of pictures. You write -LilyPond code, process it separately to embedded PostScript or -@code{png}, and include it as a picture into your La@TeX{} or -@code{html} source. - -@command{lilypond-book} provides you with a way to automate this -process: This program extracts snippets of music from your document, -runs LilyPond on them, and outputs your document with the resulting -pictures substituted for the music you entered. The line width and -font size definitions for the music are adjusted to match the layout -of your document. - -It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial -on using lilypond-book is in @ref{Integrating text and music}. In -case that you do not know La@TeX{}, then -@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so -Short Introduction to LaTeX} provides a introction to using La@TeX{}. +it the way you would do with other types of pictures. The pictures +are created separately, yielding PostScript pictures or PNG images, +and those are included into a La@TeX{} or HTML document. + +@command{lilypond-book} provides a way to automate this process: this +program extracts snippets of music from your document, runs LilyPond +on them, and outputs the document with pictures substituted for the +music. The line width and font size definitions for the music are +adjusted to match the layout of your document. + +This procedure may be applied to La@TeX{}, @code{html} or Texinfo +documents. + + @menu -* Integrating Texinfo and music:: -* Integrating La@TeX{} and music:: -* Integrating HTML and music:: -* Music fragment options:: +* An example of a musicological document:: +* Integrating Texinfo and music:: +* Integrating LaTeX and music:: +* Integrating HTML and music:: +* Music fragment options:: * Invoking lilypond-book:: +* Filename extensions:: @end menu -TODO: explain how to use lilypond fonts in text. + + + +@node An example of a musicological document +@section An example of a musicological document + +@cindex musicology +@cindex La@TeX{}, music in +@cindex HTML, music in +@cindex Texinfo, music in +Some texts contain music examples. These texts are musicological +treatises, songbooks or manuals like this. Such texts can be made by +hand, simply by importing a PostScript figure into the word processor. +However, there is an automated procedure to reduce the amount of work +involved HTML, La@TeX{}, and Texinfo documents. + +A script called @code{lilypond-book} will extract the music fragments, +format them, and put back the resulting notation. Here we show a +small example for use with La@TeX{}. The example also contains explanatory text, so we will +not comment on it further + +@verbatim +\documentclass[a4paper]{article} +\begin{document} + +Documents for lilypond-book may freely mix music and text. For +example, + +\begin{lilypond} +\relative { + c2 g'2 \times 2/3 { f8 e d } c'2 g4 +} +\end{lilypond} + +Options are put in brackets. + +\begin[fragment,quote,staffsize=26,verbatim]{lilypond} + c'4 f16 +\end{lilypond} + +Larger examples can be put in a separate file, and introduced with +\verb+\lilypondfile+. + +\lilypondfile[quote,noindent]{screech-boink.ly} + +\end{document} +@end verbatim + +Under Unix, you can view the results as follows + +@example +cd input/tutorial +mkdir -p out/ +lilypond-book --output=out/ lilybook.tex +@emph{lilypond-book (GNU LilyPond) 2.3.11} +@emph{Reading `input/tutorial/lilybook.tex'} +@emph{..lots of stuff deleted..} +@emph{Compiling `out//lilybook.tex'} +cd out +latex lilybook +@emph{lots of stuff deleted} +xdvi lilybook +@end example + +To convert the file into a nice PDF document, run the following +commands + +@example +dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook +ps2pdf lilybook.ps +@end example + +Running lilypond-book and running latex creates a lot of temporary +files, which would clutter up the working directory. To remedy this, +use the @code{--output=@var{dir}} option. It will create the files in +a separate subdirectory @file{dir}. + +Finally the result of the La@TeX{} example shown above.@footnote{ This +tutorial is processed with Texinfo, so the example is as well. This +gives slightly different results in layout.} This finishes the +tutorial section. + +@page + +Documents for lilypond-book may freely mix music and text. For +example, + +@lilypond +\relative c' { + c2 g'2 \times 2/3 { f8 e d } c'2 g4 +} +@end lilypond + +Options are put in brackets. + +@lilypond[fragment,quote,staffsize=26,verbatim] +c'4 f16 +@end lilypond + +Larger examples can be put in a separate file, and introduced with +@code{\lilypondfile}. + +@lilypondfile[quote,noindent]{screech-boink.ly} @cindex texinfo @@ -54,173 +155,217 @@ TODO: explain how to use lilypond fonts in text. @cindex documents, adding music to -@node Integrating Texinfo and music -@section Integrating Texinfo and music +@c @TeX{} in node name seems to barf +@node Integrating LaTeX and music +@section Integrating LaTeX and music + +La@TeX{} is the de facto standard for publishing layouts in the exact +sciences. It is built on top of the @TeX{} typesetting engine, so it +provides the best typography available anywhere. + +For more information about La@TeX{} +@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so +Short Introduction to La@TeX{}} provides a introduction to using +La@TeX{}. -You specify the LilyPond code like this: +For La@TeX{}, music is entered using @example -@@lilypond[options, go, here] +\begin[options,go,here]@{lilypond@} YOUR LILYPOND CODE -@@end lilypond -@@lilypond[options, go, here]@{ YOUR LILYPOND CODE @} -@@lilypondfile[options, go, here]@{@var{filename}@} +\end@{lilypond@} @end example -Then you run lilypond-book on it, and the result is a file you can -process with texinfo. We show two simple examples here. First a -complete block: +@example +\lilypondfile[options,go,here]@{@var{filename}@} +@end example + +@noindent +or @example -@@lilypond[26pt] - c' d' e' f' g'2 g' -@@end lilypond +\lilypond@{ YOUR LILYPOND CODE @} +@end example + +Running lilypond-book yields a file that can be processed with +La@TeX{}. + + +We show some examples here: + +@example +\begin[staffsize=26]@{lilypond@} + c' d' e' f' g'2 g'2 +\end@{lilypond@} @end example @noindent -produces this music: +produces -@lilypond - c' d' e' f' g'2 g' +@lilypond[fragment,staffsize=26] + c' d' e' f' g'2 g'2 @end lilypond Then the short version: @example -@@lilypond[11pt]@{<>@} +\lilypond[staffsize=11]@{@} @end example @noindent -and its music: +produces + +@lilypond[fragment,staffsize=11]{} + +The linewidth of the music will be adjust by examining the commands in +the document preamble, the part of the document before +@code{\begin@{document@}}. The @command{lilypond-book} command sends +these to La@TeX{} to find out how wide the text is. The line width +for the music fragments is then adjusted to the text width. + +After @code{\begin@{document@}}, the column changing commands +@code{\onecolumn}, @code{\twocolumn} commands +@ignore +and the +@code{multicols} environment from the multicol package +@end ignore +are also interpreted. + +@cindex titling and lilypond-book +@cindex @code{\header} in La@TeX{} documents + -@lilypond[11pt]{ <> } +The music will be surrounded by @code{\preLilyPondExample} and +@code{\postLilyPondExample}, which are defined to be empty by default. -@command{lilypond-book} knows the default margins and a few paper -sizes. One of these commands should be in the beginning of the document: +@cindex outline fonts +@cindex type1 fonts +@cindex dvips +@cindex invoking dvips -@itemize @bullet -@item @code{@@afourpaper} -@item @code{@@afourlatex} -@item @code{@@afourwide} -@item @code{@@smallbook} -@end itemize +For printing the La@TeX{} document, you will need to use dvips. For +producing PostScript with scalable fonts, add the following options to +the dvips command line: +@example + -Ppdf -u+lilypond.map -u+ec-mftrace.map +@end example @noindent -@code{@@pagesizes} are not yet supported. +PDF can then be produced with @code{ps2pdf}. -When producing texinfo, lilypond-book also generates bitmaps of the -music, so you can make a HTML document with embedded music. +@cindex international characters +@cindex latin1 +LilyPond does not use the La@TeX{} font handling scheme for lyrics and text +markups, so if you use characters in your lilypond-book +documents that are not included in the standard US-ASCII character set, +include @code{\usepackage[latin1]@{inputenc@}} in the file +header but do not include @code{\usepackage[T1]@{fontenc@}}. Character +sets other than latin1 are not supported directly but may be handled by +explicitly specifying the @code{font-name} property in LilyPond and +using the corresponding La@TeX{} packages. Please consult the mailing list +for more details. -@node Integrating La@TeX{} and music -@section Integrating La@TeX{} and music - You specify LilyPond code like this: -@example -\begin[options, go, here]@{lilypond@} - YOUR LILYPOND CODE -\end@{lilypond@} -@end example +@node Integrating Texinfo and music +@section Integrating Texinfo and music -@example -\lilypondfile[options, go,here]@{@var{filename}@} -@end example +Texinfo is the standard format for documentation at the GNU +project. An example of a texinfo document is this manual. The HTML, +PDF and Info versions of the manual are made from the document. -@noindent -or +When run on a lilypond-book, produces a @file{.texi} file containing +@code{@@image} tags for HTML and info. For the printed edition, the +raw @TeX{} output of LilyPond is included into the main document. + +In the input file, music is specified like @example -\lilypond@{ YOUR LILYPOND CODE @} +@@lilypond[options,go,here] + YOUR LILYPOND CODE +@@end lilypond +@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @} +@@lilypondfile[options,go,here]@{@var{filename}@} @end example -Then you run lilypond-book on it, and the result is a file you can -process with La@TeX{}. We show some examples here. +When lilypond-book is run on it, this results in a texinfo file. We +show two simple examples here. First a complete block: @example -\begin[26pt]@{lilypond@} - c' d' e' f' g'2 g'2 -\end@{lilypond@} +@@lilypond[staffsize=26] + c' d' e' f' g'2 g' +@@end lilypond @end example @noindent -produces this music: +produces -@lilypond[26pt] - c' d' e' f' g'2 g'2 +@lilypond[fragment] + c' d' e' f' g'2 g' @end lilypond Then the short version: @example -\lilypond[11pt]@{<>@} +@@lilypond[staffsize=11]@{@} @end example @noindent -and its music: +produces + +@lilypond[fragment,staffsize=11]{ } -@lilypond[11pt]{<>} +When producing texinfo, lilypond-book also generates bitmaps of the +music, so you can make a HTML document with embedded music. -You can use whatever commands you like in the document preamble, -the part of the document before @code{\begin@{document@}}. -@command{lilypond-book} will send it to La@TeX{} to find out how wide -the text is and adjust the linewidth variable in the paper definition of -your music according to that. -After @code{\begin@{document@}} you must be a little more careful -when you use commands that change the width of the text and how -many columns there are. @command{lilypond-book} knows about the -@code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols} -environment from the multicol package. -The music will be surrounded by @code{\preLilypondExample} and -@code{\postLilypondExample}. The variables are -defined to nothing by default, and the user can redefine them -to whatever he wants. @node Integrating HTML and music @section Integrating HTML and music -You specify LilyPond code like this: +Music is entered using @example - + \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 @end example @noindent -Then you run lilypond-book on it, and the result is a file you can -process with La@TeX{}. The final result look like +of which lilypond-book will produce a HTML with appropriate image tags for the +music fragments: +@c why the second example? -gp @example - + \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 @end example -@lilypond[relative1] +@lilypond[fragment,relative=2] \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 @end lilypond -For inline pictures, use @code{} syntax, eg. +For inline pictures, use @code{} syntax, e.g. @example Some music in a line of text. @end example +@c FIXME: check if this feature is coming soon; if not, @ignore this stuff. A special feature not (yet) available in other output formats, is the -@code{} tag, for example +@code{} tag, for example, @example - trip.ly + trip.ly @end example -This runs @file{trip.ly} through ly2dvi (See also @ref{Invoking -ly2dvi}), and substitutes a preview image in the output. The image -links to a separate HTML file, so clicking it will take the viewer to -a menu, with links to images, midi and printouts. +This runs @file{trip.ly} through @code{lilypond} (see also +@ref{Invoking lilypond}), and substitutes a preview image in the +output. The image links to a separate HTML file, so clicking it will +take the viewer to a menu, with links to images, midi and printouts. -@cindex ly2dvi @cindex titling in THML @cindex preview image @cindex thumbnail @@ -228,238 +373,192 @@ a menu, with links to images, midi and printouts. @node Music fragment options @section Music fragment options -The commands for lilypond-book have room to specify options. These -are all of the options: +The commands for lilypond-book have room to specify one or more of the +following options: @table @code -@item eps -This will create the music as eps graphics and include it into the -document with the @code{\includegraphics} command. It works in -La@TeX{} only. - -This enables you to place music examples in the running text (and not in -a separate paragraph). To avoid that La@TeX{} places the music on a line -of its own, there should be no empty lines between the normal text and -the LilyPond environment. For inline music, you probably also need a -smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt}) - @item verbatim -CONTENTS is copied into the source enclosed in a verbatim block, -followed by any text given with the @code{intertext} option, then +@var{contents} is copied into the source, enclosed in a verbatim block; +followed by any text given with the @code{intertext} option; then the actual music is displayed. This option does not work with -the short version of the LilyPond blocks: +the short version of the music blocks: @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} } -@item smallverbatim -Like @code{verbatim}, but in a smaller font. - -@item intertext="@var{text}" -Used in conjunction with @code{verbatim} option: This puts -@var{text} between the code and the music (without indentation). - -@item filename="@var{filename}" -Save the LilyPond code to @var{filename}. By default, a hash value -of the code is used. - -@item 11pt -@lilypond[11pt, eps] -\relative c' { - r16 [c d e][f d e c] [g'8 c][b-\prall c] | - [d16 g, a b][c a b g][d'8 g f-\prall g] -} -@end lilypond - -@item 13pt -@lilypond[13pt, eps] -\relative c' { - r16 [c d e][f d e c] [g'8 c][b-\prall c] | - [d16 g, a b][c a b g][d'8 g f-\prall g] -} -@end lilypond - -@item 16pt -@lilypond[16pt, eps] -\relative c' { - r16 [c d e][f d e c] [g'8 c][b-\prall c] | -} -@end lilypond - -@item 20pt -@lilypond[20pt, eps] -\relative c' { - r16 [c d e][f d e c] [g'8 c][b-\prall c] | -} -@end lilypond - -@item 26pt -@lilypond[26pt, eps] -\relative c' { - r16 [c d e][f d e c] [g'8 c][b-\prall c] | -} -@end lilypond +@item filename=@var{filename} +This names the file for the @code{printfilename} option. The argument +should be unquoted. -@item singleline -Produce a single, naturally spaced, unjustified line -(i.e., linewidth = @minus{}1). +@item staffsize=@var{ht} +Sets the staff height to @var{ht}, which is measured in points. -@item multiline -The opposite of @code{singleline}: Justify and break lines. +@item raggedright +produces naturally spaced lines (i.e., @code{raggedright = ##t}); this +works well for small music fragments. -@item linewidth=@var{size}@var{unit} -Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt. +@item linewidth=@var{size}\@var{unit} +sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt. This option affects LilyPond output, not the text layout. @item notime -Don't print time signature. +prevents printing time signature. @item fragment -@itemx nofragment -Override @command{lilypond-book} auto detection of what type of code is -in the LilyPond block, voice contents or complete code. +adds some boilerplate code, so you can enter like + +@example + c'4 +@end example -@item indent=@var{size}@var{unit} -Set indentation of the first music system to @var{size}, +@noindent +without @code{\layout}, @code{\score} or other red tape. + +@item indent=@var{size}\@var{unit} +sets indentation of the first music system to @var{size}, where @var{unit} = cm, mm, in, or pt. This option affects LilyPond, -not the text layout. For single-line fragments the default is to +not the text layout. For single-line fragments, the default is to use no indentation. +For example +@example + \begin[indent=5\cm,raggedright]@{lilypond@} + ... + \end@{lilypond@} +@end example + + @item noindent -Set indentation of the first music system to zero. This option +sets indentation of the first music system to zero. This option affects LilyPond, not the text layout. -@item notexidoc -Do not include the .texidoc header. This is only for Texinfo output. +@item quote +sets linewidth to the width of a quotation and puts the output +in a quotation block. -@item noquote -By default, @command{lilypond-book} puts both La@TeX{} and texinfo output -into a quotation block. Using this option prevents this; no indentation -will be used. +@item texidoc +Includes the @code{texidoc} field, if defined in the file. This is +only for Texinfo output. -@item printfilename -Prints the file name before the music example. Useful in conjunction -with @code{\lilypondfile}. +In Texinfo, the music fragment is normally preceded by the +@code{texidoc} field from the @code{\header}. The LilyPond test +documents are composed from small @file{.ly} files in this way: -@item relative, relative @var{N} -Use relative octave mode. By default, notes are specified relative -central C. The optional integer argument specifies how many octaves -higher (positive number) or lower (negative number) to place the -starting note. +@example + \header @{ + texidoc = "this file demonstrates a single note" + @} + @{ c'4 @} +@end example + +@item relative, relative=@var{N} +uses relative octave mode. By default, notes are specified relative +to middle C. The optional integer argument specifies the octave of the +starting note, where the default @code{1} is middle C. @end table @node Invoking lilypond-book @section Invoking lilypond-book -When you run @command{lilypond-book} it will generate lots of small -files that LilyPond will process. To avoid all the garbage in -your source directory, you should either change to a temporary -directory, or use the @option{--outdir} command line options: - -@code{cd out && lilypond-book ../yourfile.tex} - -@code{lilypond-book --outdir=out yourfile.tex} -For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}. -Texinfo input will be written to a file with extension @file{.texi}. +Running @command{lilypond-book} generates lots of small files that +LilyPond will process. To avoid all that garbage in the source +directory use the @option{--output} command line option, and change to +that directory before running La@TeX{} or @file{makeinfo}: -If you use @option{--outdir}, you should also @code{cd} to that directory -before running La@TeX{} or @command{makeinfo}. This may seem a little -kludgy, but both La@TeX{} and @command{makeinfo} expect picture files -(the music) to be in the current working directory. Moreover, if you do -this, La@TeX{} will not clutter your normal working directory with output -files. - -@cindex titling and lilypond-book -@cindex lilypond-book and titling -@cindex @code{\header} in La@TeX{} documents +@example +lilypond-book --output=out yourfile.lytex +cd out +@end example -If you want to add titling from the @code{\header} section of the -files, you should add the following to the top of your La@TeX{} file: +This will produce a .tex or .texi file. To produce a pdf from the +.tex file, you should do @example -\input titledefs.tex -\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@} +latex yourfile.tex +dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi +ps2pdf yourfile.ps @end example +To produce a texinfo document (in any output format), follow the normal +procedures for texinfo. + @command{lilypond-book} accepts the following command line options: @table @code @item @option{-f @var{format}}, @option{--format=@var{format}} Specify the document type to process: @code{html}, @code{latex} or -@code{texi} (the default). @command{lilypond-book} usually figures this +@code{texi} (the default). @command{lilypond-book} figures this out automatically. -Note that the @code{texi} document type produces a DVI file; to -convert a texinfo document to @code{html}, you should use the additional -format @code{texi-html} instead of @code{texi} to convert lilypond -fragments to PNG images. +The @code{texi} document type produces a texinfo file with music +fragments in the DVI output only. For getting images in the HTML +version, the format +@code{texi-html} must be used. -@item @option{--default-music-fontsize=@var{sz}pt} -Set the fontsize to use for LilyPond if no fontsize is given -as option. +@item @option{-F @var{filter}}, @option{--filter=@var{filter}} +Pipe snippets through @var{filter}. -@item @option{--force-music-fontsize=@var{sz}pt} -Force all LilyPond code to use this fontsize, overriding options -given to @code{\begin@{lilypond@}}. +For example: +@example + lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely +@end example + +@item @option{--help} +Print a short help message. @item @option{-I @var{dir}}, @option{--include=@var{dir}} Add @var{DIR} to the include path. -@item @option{-M}, @option{--dependencies} -Write dependencies to @file{filename.dep}. +@item @option{-o @var{dir}}, @option{--output=@var{dir}} +Place generated files in @var{dir}. -@item @option{--dep-prefix=@var{pref}} -Prepend @var{pref} before each @option{-M} dependency. +@item @option{-P @var{process}}, @option{--process=@var{COMMAND}} +Process lilypond snippets using @var{command}. The default command is +@code{lilypond}. -@item @option{-n}, @option{--no-lily} -Don't run LilyPond, but do generate the @code{.ly} files. +@item @option{--verbose} +Be verbose. -@item @option{--no-music} -Strip all LilyPond blocks from the file. +@item @option{--version} +Print version information. +@end table -@item @option{--no-pictures} -Don't generate pictures when processing Texinfo. +For La@TeX{} input, the file to give to La@TeX{} has extension +@file{.latex}. Texinfo input will be written to a file with extension +@file{.texi}. -@item @option{--read-lys} -Don't write ly files. This way you can do -@example -lilypond-book file.tely -convert-ly -lilypond-book --read-lys -@end example -@item @option{--outname=@var{file}} -The name of La@TeX{} file to output. If this option is not given, -the output name is derived from the input name. +@refbugs -@item @option{--outdir=@var{dir}} -Place generated files in @var{dir}. +The Texinfo command @code{pagesize} is not interpreted. Almost all +La@TeX{} commands that change margins and line widths are ignored. -@item @option{--version} -Print version information. +Only the first @code{\score} of a LilyPond block is processed. + +@c CHECKME--FIXME +The size of a music block is limited to 1.5 KB, due to technical +problems with the Python regular expression engine. For longer files, +use @code{\lilypondfile}. -@item @option{--help} -Print a short help message. -@end table +@node Filename extensions +@section Filename extensions -@section Bugs +You can use any filename extension, but if you do not use the +recommended extension, you may need to manually specify what output +format you want. See @ref{Invoking lilypond-book} for details. -The La@TeX{} @code{\includeonly@{...@}} command is ignored. +@code{Lilypond-book} automatically selects the output format based +on the filename. -The Texinfo command @code{pagesize} is on the TODO list for LilyPond -1.8, but changing the linewidth in other ways will not give you a -straight right margin. +@table @code -Almost all La@TeX{} commands that change margins and line widths are -ignored. +@item @emph{.html} produces html output -There is no way to automatically apply @command{convert-ly} only to fragments -inside a lilypond-book file. +@item @emph{.itely} produces texinfo output -@command{lilypond-book} processes all music fragments in one big run. The -state of the GUILE interpreter is not reset between fragments; this -means that global GUILE definitions, e.g., done with @code{#(define @dots{})} -and @code{#(set! @dots{})} can leak from one fragment into the next fragment. +@item @emph{.lytex} produces latex output + +@end table