X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=5c549ddc5137ddbce02dda30fb89ec3c045cadd3;hb=3e6884efdd233f749317cd623dd76c701e504233;hp=a0ea6b389c325cdc6470a55139302a499aeb19f6;hpb=76771037dc7948c202c25a5dc0f66e9ee6bc8efb;p=lilypond.git diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index a0ea6b389c..5c549ddc51 100644 --- a/Documentation/user/lilypond-book.itely +++ b/Documentation/user/lilypond-book.itely @@ -11,28 +11,139 @@ TODO: cleanup @end ignore -@c @node Merging text and music with lilypond-book -@c @chapter Merging text and music with lilypond-book -@c fix this node name , this is too long. - -@node lilypond-book: Integrating text and music -@chapter lilypond-book: Integrating text and music +@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. +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 +* An example of a musicological document:: +* Integrating Texinfo and music:: +* Integrating LaTeX and music:: +* Integrating HTML and music:: +* Music fragment options:: +* Invoking lilypond-book:: +@end menu + + + + +@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 -@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 substitutes the resulting pictures back. -The line width and font size definitions for the music are adjusted so -they match the layout of your document. +Options are put in brackets. -It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial -on using lilypond-book is in @ref{integrating text and music}. +@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 @@ -43,336 +154,377 @@ on using lilypond-book is in @ref{integrating text and music}. @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 papers 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{}. + +For La@TeX{}, music is entered using -You specify the LilyPond code like this: @example -@@lilypond[options, go, here] +\begin[options,go,here]@{lilypond@} YOUR LILYPOND CODE -@@end lilypond -@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @} -@@lilypondfile[options, go,here]@{@var{filename}@} +\end@{lilypond@} @end example -We show two simple examples here. First a complete block: @example -@@lilypond[26pt] -c' d' e' f' g'2 g' -@@end lilypond +\lilypondfile[options,go,here]@{@var{filename}@} @end example -produces this music: -@lilypond -c' d' e' f' g'2 g' -@end lilypond +@noindent +or -Then the short version: @example -@@lilypond[11pt]@{@} +\lilypond@{ YOUR LILYPOND CODE @} @end example -and its music: +Running lilypond-book yields a file that can be processed with +La@TeX{}. -@lilypond[11pt]{} - -@command{lilypond-book} knows the default margins, and a few paper -sizes. One of these commands should be in the beginning of the document: -@itemize @bullet -@item @code{@@afourpaper} -@item @code{@@afourlatex} -@item @code{@@afourwide} -@item @code{@@smallbook} -@end itemize -@code{@@pagesizes} are not yet supported. - -When producing texinfo, lilypond-book also generates bitmaps of the -music, so you can make a HTML document with embedded music. -@node Integrating La@TeX{} and music -@section Integrating La@TeX{} and music +We show some examples here: -You specify the LilyPond code like this: @example -\begin[option, go, here]@{lilypond@} - YOUR LILYPOND CODE +\begin[staffsize=26]@{lilypond@} + c' d' e' f' g'2 g'2 \end@{lilypond@} @end example +@noindent +produces + +@lilypond[fragment,staffsize=26] + c' d' e' f' g'2 g'2 +@end lilypond + +Then the short version: + @example -\lilypondfile[options, go,here]@{@var{filename}@} +\lilypond[staffsize=11]@{@} @end example -or + +@noindent +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 + + +The music will be surrounded by @code{\preLilyPondExample} and +@code{\postLilyPondExample}, which are defined to be empty by default. + +@cindex outline fonts +@cindex type1 fonts +@cindex dvips +@cindex invoking dvips + +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 -\lilypond@{ YOUR LILYPOND CODE @} + -Ppdf -u+lilypond.map -u+ec-mftrace.map +@end example + +@noindent +PDF can then be produced with @code{ps2pdf}. + +@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 Texinfo and music +@section Integrating Texinfo and music + +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. + +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[options,go,here] + YOUR LILYPOND CODE +@@end lilypond +@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @} +@@lilypondfile[options,go,here]@{@var{filename}@} @end example -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 -produces this music: +@noindent +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 -and its music: +@noindent +produces -@lilypond[11pt]{} +@lilypond[fragment,staffsize=11]{ } +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, -that is 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 -you 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} know 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 the LilyPond code like this: +Music is entered using -@quotation @example - + \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 - + @end example -@end quotation - -produces -@quotation +@noindent +of which lilypond-book will produce a HTML with appropriate image tags for the +music fragments: + @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 -@end quotation -Inline picture: - -@quotation +For inline pictures, use @code{} syntax, e.g. @example Some music in a line of text. @end example -@end quotation + +A special feature not (yet) available in other output formats, is the +@code{} tag, for example, +@example + trip.ly +@end example +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 titling in THML +@cindex preview image +@cindex thumbnail @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. +@item verbatim +@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 music blocks: -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 (eg. 11 pt or 13 pt) +@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} } +@item filename=@var{filename} +This names the file for the @code{printfilename} option. The argument +should be unquoted. -@item verbatim - 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: - - @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. -@item filename="@var{filename}" - Save the LilyPond code to @var{filename}. By default, a hash value -of the code is used. - -@item @code{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 @code{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 @code{16pt} -@lilypond[16pt, 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 @code{20pt} -@lilypond[20pt, 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 @code{26pt} -@lilypond[26pt, eps] - \relative c'{ - r16 [c d e][f d e c] [g'8 c][b-\prall c] | - } -@end lilypond +@item staffsize=@var{ht} +Sets the staff height to @var{ht}, which is measured in points. + +@item raggedright +produces naturally spaced lines (i.e., @code{raggedright = ##t}); this +works well for small music fragments. + +@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 +prevents printing time signature. -@item singleline - Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1). -@item multiline - The opposite of @code{singleline}: justify and break lines. -@item linewidth=@var{size}@var{unit} - Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt. @item fragment -@item nofragment - Override @command{lilypond-book} auto detection of what type of code is in the - LilyPond block, voice contents or complete code. -@item indent=@var{size}@var{unit} - Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt. +adds some boilerplate code, so you can enter like + +@example + c'4 +@end example + +@noindent +without @code{\paper}, @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 +use no indentation. + +For example +@example + \begin[indent=5\cm,raggedright]@{lilypond@} + ... + \end@{lilypond@} +@end example + + @item noindent - Set first line indent to zero. -@item printfilename - Prints the file name before the music example. Useful in conjunction -with @code{\lilypondfile}. -@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. -@end table +sets indentation of the first music system to zero. This option +affects LilyPond, not the text layout. -@node Invoking lilypond-book -@section Invoking lilypond-book +@item quote +sets linewidth to the width of a quotation and puts the output +in a quotation block. -When you run @command{lilypond-book} it will generate lots of small -files that LilyPond will process. So to avoid all the garbage in -your source directory, you should either change to a temporary -directory, or use the @code{--outdir} command line options: +@item texidoc +Includes the @code{texidoc} field, if defined in the file. This is +only for Texinfo output. -@code{cd out && lilypond-book ../yourfile.tex} +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: -@code{lilypond-book --outdir=out yourfile.tex} +@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 -For latex input, the file to give to latex has extension @file{.latex}. -Texinfo input will be written to a file with extension @file{.texi}. -If you use @code{--outdir}, you should also @code{cd} to that directory -before running LaTeX or makeinfo. This may seem a little kludgey, but -both Latex and makeinfo expect picture files (the music) to be in the -current working directory. Moreover, if you do this, LaTeX will not -clutter you normal working directory with output files. +@node Invoking lilypond-book +@section Invoking lilypond-book -@cindex titling and lilypond-book -@cindex lilypond-book and titling -@cindex \header in LaTeX documents -If you want to add titling from the @code{\header} section of the -files, you should add the following to the top of your LaTeX +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}: + @example -\input titledefs.tex -\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@} +lilypond-book --output=out yourfile.lytex +cd out && latex yourfile.tex @end example -lilypond-book accepts the following command-line options: + +@command{lilypond-book} accepts the following command line options: + @table @code -@item @option{-f}, @option{--format=} - Specify the document type to process: @code{html}, @code{latex} or -@code{texi} (default). @command{lilypond-book} usually figures this +@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} figures this out automatically. -@item --default-music-fontsize=@var{sz}pt - Set the fontsize to use for LilyPond if no fontsize is given - as option. -@item --force-music-fontsize=@var{sz}pt - Force all LilyPond to use this fontsize, overriding options - given to @code{\begin@{lilypond@}} -@item -I @var{DIR}, --include=@var{DIR} - Add @var{DIR} to the include path. -@item -M, --dependencies - Write dependencies to @file{filename.dep} -@item --dep-prefix=@code{PREF} - prepend @code{PREF} before each @code{-M} dependency -@item -n, --no-lily - don't run LilyPond, but do generate the @code{.ly} files -@item --no-music - strip all LilyPond blocks from the file. -@item --no-pictures - don't generate pictures when processing Texinfo. -@item --read-lys - don't write ly files. This way you can do +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{-F @var{filter}}, @option{--filter=@var{filter}} +Pipe snippets through @var{filter}. + +For example: @example - lilypond-book file.tely - convert-ly - lilypond-book --read-lys + lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely @end example -@item --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. -@item --outdir=@var{DIR} - place generated files in @var{DIR}. -@item --version - print version information -@item --help - Print a short help message +@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{-o @var{dir}}, @option{--output=@var{dir}} +Place generated files in @var{dir}. + +@item @option{-P @var{process}}, @option{--process=@var{COMMAND}} +Process lilypond snippets using @var{command}. The default command is +@code{lilypond}. + +@item @option{--verbose} +Be verbose. + +@item @option{--version} +Print version information. @end table +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}. + + -@section Bugs - -The La@TeX{} \includeonly@{...@} command is ignored. +@refbugs -The Texinfo command @code{pagesize} is on the TODO list for LilyPond -1.6, but changing the linewidth in other ways will not give you a -straight right margin. +The Texinfo command @code{pagesize} is not interpreted. Almost all +La@TeX{} commands that change margins and line widths are ignored. -Almost all La@TeX{} commands that change margins and line widths are -ignored. +Only the first @code{\score} of a LilyPond block is processed. -There is no way to automatically apply convert-ly only to fragments -inside a lilypond-book file. +@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}. -@file{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, eg. done with @code{#(define -.. )} and @code{#(set! .. )} can leak from one fragment into a next -fragment.