X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fuser%2Flilypond-book.itely;h=220796f7f013039521727d7400fa0f30f96fe13c;hb=cc18fd6f82df460cc31695c4c31f47f45b7e434e;hp=d37d12725e188dfa33c80718f998feeeff30b56b;hpb=1b91955adaf3c89540c8ffff7228f0ec7a31dbe4;p=lilypond.git diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index d37d12725e..571bdbc199 100644 --- a/Documentation/user/lilypond-book.itely +++ b/Documentation/user/lilypond-book.itely @@ -1,10 +1,11 @@ -@c -*-texinfo-*- +c -*- coding: utf-8; mode: texinfo; -*- + @ignore TODO: cleanup -** AARGH.e We also have tutorial.itely: Integrating text and music. +** AARGH. We also have tutorial.itely: Integrating text and music. Could also do with a cleanup. Lost inspiration to fix this manual where to describe what? @@ -12,176 +13,436 @@ TODO: cleanup @end ignore -@node lilypond-book manual -@chapter lilypond-book manual - -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. 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. A tutorial on using lilypond-book is in @ref{Integrating -text and music}. For more information about La@TeX{} -@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so -Short Introduction to LaTeX} provides a introction to using La@TeX{}. +@c Note: keep this node named so that `info lilypond-book' brings you here. +@node LilyPond-book +@chapter @command{lilypond-book}: 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. The pictures are +created separately, yielding PostScript output 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 +@command{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{}, HTML, Texinfo or DocBook documents. @menu -* Integrating Texinfo and music:: +* An example of a musicological document:: * Integrating LaTeX and music:: +* Integrating Texinfo and music:: * Integrating HTML and music:: +* Integrating DocBook and music:: * Music fragment options:: * Invoking lilypond-book:: +* Filename extensions:: +* Many quotes of a large score:: +* Inserting LilyPond output into OpenOffice.org:: +* Inserting LilyPond output into other programs:: @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 +@cindex DocBook, 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 in HTML, La@TeX{}, Texinfo and DocBook 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. + +@quotation +@verbatim +\documentclass[a4paper]{article} + +\begin{document} + +Documents for @command{lilypond-book} may freely mix music and text. +For example, + +\begin{lilypond} +\relative c' { + 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 into a separate file, and introduced with +\verb+\lilypondfile+. + +\lilypondfile[quote,noindent]{screech-boink.ly} + +\end{document} +@end verbatim +@end quotation + +Under Unix, you can view the results as follows + +@example +cd input/tutorial +mkdir -p out/ +lilypond-book --output=out --psfonts lilybook.tex +@emph{lilypond-book (GNU LilyPond) 2.6.0} +@emph{Reading 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 PDF document, run the following commands + +@example +dvips -o -Ppdf -h lilybook.psfonts lilybook +ps2pdf lilybook.ps +@end example + +If you are running latex in twocolumn mode, remember to add +@code{-t landscape} to the dvips options. + +Running @command{lilypond-book} and @command{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}. + +Running dvips will produce many warnings about fonts. They are not +harmful; please ignore them. + +Finally the result of the La@TeX{} example shown above.@footnote{This +tutorial is processed with Texinfo, so the example gives slightly +different results in layout.} This finishes the tutorial section. + +@page + +Documents for @command{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 into a separate file, and introduced with +@code{\lilypondfile}. + +@lilypondfile[quote,noindent]{screech-boink.ly} + +@page @cindex texinfo @cindex latex @cindex texinfo -@cindex @code{texi} +@funindex texi @cindex html +@cindex docbook @cindex documents, adding music to -@node Integrating Texinfo and music -@section Integrating Texinfo and music +@node Integrating LaTeX and music +@section Integrating La@TeX{} 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, +providing the best typography available anywhere. -Music is specified like this: +See +@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/, +@emph{The Not So Short Introduction to La@TeX{}}} for an overview on how +to use 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 -When lilypond-book is run on it, this results in a texinfo file. We -show two simple examples here. First a complete block: +@noindent +or @example -@@lilypond[26pt] - c' d' e' f' g'2 g' -@@end lilypond +\lilypondfile[options,go,here]@{@var{filename}@} +@end example + +@noindent +or + +@example +\lilypond@{ YOUR LILYPOND CODE @} +@end example + +Running @command{lilypond-book} yields a file that can be further +processed with La@TeX{}. + +We show some examples here. The lilypond environment + +@example +\begin[quote,fragment,staffsize=26]@{lilypond@} + c' d' e' f' g'2 g'2 +\end@{lilypond@} @end example @noindent produces -@lilypond - c' d' e' f' g'2 g' +@lilypond[quote,fragment,staffsize=26] +c' d' e' f' g'2 g'2 @end lilypond -Then the short version: +The short version @example -@@lilypond[11pt]@{@} +\lilypond[quote,fragment,staffsize=11]@{@} @end example @noindent produces -@lilypond[11pt]{ } +@lilypond[quote,fragment,staffsize=11]{} + +@noindent +Currently, you cannot include @code{@{} or @code{@}} within +@code{\lilypond@{@}}, so this command is only useful with the +@code{fragment} option. + +The default line width of the music will be adjusted 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. Note that this +heuristic algorithm can fail easily; in such cases it is necessary to +use the @code{line-width} music fragment option. + +@cindex titling and lilypond-book +@funindex \header in La@TeX{} documents + +Each snippet will call the following macros if they have been defined by +the user: + +@code{\preLilyPondExample} called before the music + +@code{\postLilyPondExample} called after the music + +@code{\betweenLilyPondSystem[1]} is called between systems if +@code{lilypond-book} has split the snippet into several postscript +files. It must be defined as taking one parameter and will be +passed the number of files already included in this snippet. +The default is to simply insert a @code{\linebreak}. + +@ignore +Broken stuff. :( + +@cindex Latex, feta symbols +@cindex fetachar + +To include feta symbols (such as flat, segno, etc) in a LaTeX +document, use @code{\input@{titledefs@}} + +@example +\documentclass[a4paper]@{article@} + +\input@{titledefs@} + +\begin@{document@} + +\fetachar\fetasharp + +\end@{document@} +@end example + +The font symbol names are defined in the file feta20.tex; to find +the location of this file, use the command + +@example +kpsewhich feta20.tex +@end example -@command{lilypond-book} knows the default margins and a few paper -sizes. One of these commands should be in the beginning of the document: +@end ignore -@itemize @bullet -@item @code{@@afourpaper} -@item @code{@@afourlatex} -@item @code{@@afourwide} -@item @code{@@smallbook} -@end itemize +@cindex outline fonts +@cindex type1 fonts +@cindex dvips +@cindex invoking dvips + +For printing the La@TeX{} document you need a DVI to PostScript +translator like @command{dvips}. To use @command{dvips} to produce +a PostScript file, add the following options to the @command{dvips} +command line: + +@example +-o -Ppdf -h @var{file}.psfonts +@end example @noindent -@code{@@pagesizes} are not yet supported. +where the @var{file}@command{psfonts} file is obtained from +@command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF +can then be produced with a PostScript to PDF translator like +@code{ps2pdf} (which is part of GhostScript). Running @command{dvips} +will produce some warnings about fonts; these are harmless and may +be ignored. + +If you are running latex in twocolumn mode, remember to add +@code{-t landscape} to the dvips options. + +@cindex international characters +@cindex latin1 + +Sometimes it is useful to display music elements (such as ties and slurs) +as if they continued after the end of the fragment. This can be done by +breaking the staff and suppressing inclusion of the rest of the lilypond +output. + +In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that +inclusion of other systems is terminated once the required number of +systems are included. Since @code{\betweenLilypondSystem} is first +called @b{after} the first system, including only the first system +is trivial. + +@example +\def\betweenLilyPondSystem#1@{\endinput@} + +\begin[fragment]@{lilypond@} + c'1\( e'( c'~ \break c' d) e f\) +\end@{lilypond@} +@end example -When producing texinfo, lilypond-book also generates bitmaps of the -music, so you can make a HTML document with embedded music. +If a greater number of systems is requested, a TeX conditional must be +used before the @code{\endinput}. In this example, replace "2" by +the numer of systems you want in the output, +@example +\def\betweenLilyPondSystem#1@{ + \ifnum##1<2\else\endinput\fi +@} +@end example -@c @TeX{} in node name seems to barf -@node Integrating LaTeX and music -@section Integrating LaTeX and music +Remember that the definition of @code{\betweenLilyPondSystem} is +effective until @TeX{} quits the current group (such as the La@TeX{} +environment) or is overridden by another definition (which is, in +most cases, for the rest of the document). To reset your +definition, write +@example +\let\betweenLilyPondSystem\undefined +@end example -For La@TeX{}, music is entered using +@noindent +in your LaTeX source. + +This may be simplified by defining a @TeX{} macro @example -\begin[options, go, here]@{lilypond@} +\def\onlyFirstNSystems#1@{ + \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@} +@} +@end example + +@noindent +and then saying only how many systems you want before each fragment, + +@example +\onlyFirstNSystems@{3@} +\begin@{lilypond@}...\end@{lilypond@} +\onlyFirstNSystems@{1@} +\begin@{lilypond@}...\end@{lilypond@} +@end example + + +@node Integrating Texinfo and music +@section Integrating Texinfo and music + +Texinfo is the standard format for documentation of 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 Texinfo document. + +In the input file, music is specified with + +@example +@@lilypond[options,go,here] YOUR LILYPOND CODE -\end@{lilypond@} +@@end lilypond @end example +@noindent +or + @example -\lilypondfile[options, go,here]@{@var{filename}@} +@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @} @end example @noindent or @example -\lilypond@{ YOUR LILYPOND CODE @} +@@lilypondfile[options,go,here]@{@var{filename}@} @end example -Running lilypond-book yields a file that can be processed with -La@TeX{}. We show some examples here: +When @command{lilypond-book} is run on it, this results in a Texinfo +file (with extension @file{.texi}) containing @code{@@image} tags for +HTML and info output. For the printed edition, the raw @TeX{} output of +LilyPond is included in the main document. + +We show two simple examples here. A @code{lilypond} environment @example -\begin[26pt]@{lilypond@} - c' d' e' f' g'2 g'2 -\end@{lilypond@} +@@lilypond[fragment] +c' d' e' f' g'2 g' +@@end lilypond @end example @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: +The short version @example -\lilypond[11pt]@{@} +@@lilypond[fragment,staffsize=11]@{@} @end example @noindent produces -@lilypond[11pt]{} +@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@}}: @command{lilypond-book} sends these to -La@TeX{} to find out how wide the text is. The line width variable for -the music fragments are adjusted to the text width. +Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an +in-line image. It always gets a paragraph of its own. -After @code{\begin@{document@}}, the column changing commands -@code{\onecolumn} , @code{\twocolumn} commands and the -@code{multicols} environment from the multicol package are also -interpreted. - -The titling from the @code{\header} section of the fragments can be -imported by adding the following to the top of the La@TeX{} file: - -@example -\input titledefs.tex -\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@} -@end example +When using the Texinfo output format, @command{lilypond-book} also +generates bitmaps of the music (in PNG format), so you can make an HTML +document with embedded music. -The music will be surrounded by @code{\preLilyPondExample} and -@code{\postLilyPondExample}, which are defined to be empty by default. @node Integrating HTML and music @section Integrating HTML and music @@ -189,292 +450,442 @@ The music will be surrounded by @code{\preLilyPondExample} and Music is entered using @example - - \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 + +\key c \minor c4 es g2 @end example @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 +@command{lilypond-book} then produces an HTML file with appropriate image +tags for the music fragments: -@lilypond[relative1] - \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 +@lilypond[fragment,relative=2] +\key c \minor c4 es g2 @end lilypond -For inline pictures, use @code{} syntax, eg. +For inline pictures, use @code{}, where the options +are separated by a colon from the music, for example + @example -Some music in a line of text. +Some music in a line of text. @end example -A special feature not (yet) available in other output formats, is the -@code{} tag, for example, +To include separate files, say + @example - trip.ly +@var{filename} @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 titling in HTML @cindex preview image @cindex thumbnail -@node Music fragment options -@section Music fragment options +@node Integrating DocBook and music +@section Integrating DocBook and music -The commands for lilypond-book have room to specify one or more of the -following options: +For inserting LilyPond snippets it is good to keep the conformity of +our DocBook document, thus allowing us to use DocBook editors, +validation etc. So we don't use custom tags, only specify a convention +based on the standard DocBook elements. -@table @code -@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 music blocks: +@unnumberedsubsec Common conventions -@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} } +For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be +formatted inline or not inline. +The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are +chosen to allow DocBook editors format the content gracefully. +The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}. -@item smallverbatim -works like @code{verbatim}, but in a smaller font. +@unnumberedsubsec Including a LilyPond file -@item intertext="@var{text}" -is used in conjunction with @code{verbatim} option: This puts -@var{text} between the code and the music (without indentation). +This is the most simple case. We must use the @file{.ly} extension for the included file, and insert it as a standard @code{imageobject}, +with the following structure: -@item filename="@var{filename}" -saves the LilyPond code to @var{filename}. By default, a hash value -of the code is used. +@example + + + + + +@end example -@item 11pt -@lilypond[11pt] -\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 +Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish. -@item 13pt -@lilypond[13pt] -\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 +@unnumberedsubsec Including LilyPond code -@item 16pt -@lilypond[16pt] -\relative c' { - r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] | -} -@end lilypond +Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure: -@item 20pt -@lilypond[20pt] -\relative c' { - r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] | -} -@end lilypond +@example + + + +\context Staff \with @{ + \remove Time_signature_engraver + \remove Clef_engraver@} + @{ c4( fis) @} + + + +@end example -@item 26pt -@lilypond[26pt] -\relative c' { - r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] | -} -@end lilypond +As you can see, the outermost element is a @code{mediaobject} or @code{inlinemediaobject}, and there is a @code{textobject} containing the @code{programlisting} inside. -@item raggedright -produces naturally spaced lines (i.e., @code{raggedright = ##t}); this -works well for small music fragments. +@unnumberedsubsec Processing the DocBook document -@item multiline -is the opposite of @code{singleline}: it justifies and breaks lines. +Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension. +If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically. +For HTML (HTML Help, JavaHelp etc.) generation you can use the official DocBook XSL stylesheets, however, it is possible that you have to make some customization for it. -@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. +@node Music fragment options +@section Music fragment options + +In the following, a ``LilyPond command'' refers to any command described +in the previous sections which is handled by @command{lilypond-book} to +produce a music snippet. For simplicity, LilyPond commands are only +shown in La@TeX{} syntax. + +Note that the option string is parsed from left to right; if an option +occurs multiple times, the last one is taken. + +The following options are available for LilyPond commands: + +@table @code +@item staffsize=@var{ht} +Set staff size to @var{ht}, which is measured in points. + +@item ragged-right +Produce ragged-right lines with natural spacing (i.e., @code{ragged-right += ##t} is added to the LilyPond snippet). This is the default for the +@code{\lilypond@{@}} command if no @code{line-width} option is present. +It is also the default for the @code{lilypond} environment if the +@code{fragment} option is set, and no line width is explicitly +specified. + +@item packed +Produce lines with packed spacing (i.e., @code{packed = ##t} is added +to the LilyPond snippet). + +@item line-width +@itemx line-width=@var{size}\@var{unit} +Set line width to @var{size}, using @var{unit} as units. @var{unit} is +one of the following strings: @code{cm}, @code{mm}, @code{in}, or +@code{pt}. This option affects LilyPond output (this is, the staff +length of the music snippet), not the text layout. + +If used without an argument, set line width to a default value (as +computed with a heuristic algorithm). + +If no @code{line-width} option is given, @command{lilypond-book} tries to +guess a default for @code{lilypond} environments which don't use the +@code{ragged-right} option. @item notime -prevents printing time signature. +Do not print the time signature, and turns off the timing (key signature, +bar lines) in the score. @item fragment -@itemx nofragment -overrides @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} -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. +Make @command{lilypond-book} add some boilerplate code so that you can +simply enter, say, -For example @example - \begin[indent=5cm,raggedright]{lilypond} - ... - \end{lilypond} +c'4 @end example +@noindent +without @code{\layout}, @code{\score}, etc. + +@item nofragment +Don't add additional code to complete LilyPond code in music snippets. +Since this is the default, @code{nofragment} is redundant normally. + +@item indent=@var{size}\@var{unit} +Set indentation of the first music system to @var{size}, using +@var{unit} as units. @var{unit} is one of the following strings: +@code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects +LilyPond, not the text layout. @item noindent -sets indentation of the first music system to zero. This option -affects LilyPond, not the text layout. +Set indentation of the first music system to zero. This option affects +LilyPond, not the text layout. Since no indentation is the default, +@code{noindent} is redundant normally. + +@item quote +Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put +the output into a quotation block. The value `0.4@dmn{in}' can be +controlled with the @code{exampleindent} option. + +@item exampleindent +Set the amount by which the @code{quote} option indents a music snippet. + +@item relative +@itemx relative=@var{n} +Use relative octave mode. By default, notes are specified relative to +middle@tie{}C. The optional integer argument specifies the octave of +the starting note, where the default @code{1} is middle C. +@end table -@item notexidoc -prevents including @code{texidoc}. This is only for Texinfo output. +LilyPond also uses @command{lilypond-book} to produce its own +documentation. To do that, some more obscure music fragment options are +available. -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: +@table @code +@item verbatim +The argument of a LilyPond command is copied to the output file and +enclosed in a verbatim block, followed by any text given with the +@code{intertext} option (not implemented yet); then the actual music is +displayed. This option does not work well with @code{\lilypond@{@}} if +it is part of a paragraph. + +@item texidoc +(Only for Texinfo output.) If @command{lilypond} is called with the +@option{--header=@/texidoc} option, and the file to be processed is +called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there +is a @code{texidoc} field in the @code{\header}. The @code{texidoc} +option makes @command{lilypond-book} include such files, adding its +contents as a documentation block right before the music snippet. + +Assuming the file @file{foo@/.ly} contains @example - \header @{ - texidoc = "this file demonstrates a single note" - @} - \score @{ \notes @{ c'4 @} @} +\header @{ + texidoc = "This file demonstrates a single note." +@} +@{ c'4 @} @end example -@item quote -instructs @command{lilypond-book} to put La@TeX{} and Texinfo output -into a quotation block. +@noindent +and we have this in our Texinfo document @file{test.texinfo} + +@example +@@lilypondfile[texidoc]@{foo.ly@} +@end example + +@noindent +the following command line gives the expected result + +@example +lilypond-book --process="lilypond --format=tex --tex \ + --header=texidoc test.texinfo +@end example + +Most LilyPond test documents (in the @file{input} directory of the +distribution) are small @file{.ly} files which look exactly like this. @item printfilename -prints the file name before the music example. Useful in conjunction -with @code{\lilypondfile}. +If a LilyPond input file is included with @code{\lilypondfile}, print +the file name right before the music snippet. For HTML output, this is +a link. + +@item fontload +This option includes fonts in all of the generated EPS-files for this +snippet. This should be used if the snippet uses any font that LaTeX +cannot find on its own. -@item relative, relative @var{N} -uses relative octave mode. By default, notes are specified relative -central C. The optional integer argument specifies the octave of the -starting note, where the default @code{1} is central C. @end table @node Invoking lilypond-book -@section Invoking lilypond-book +@section Invoking @command{lilypond-book} + +@command{lilypond-book} produces a file with one of the following +extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the +output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further +processing. + +@command{lilypond-book} can also create a PSFONTS file, which is required +by @command{dvips} to produce Postscript and PDF files. + +To produce PDF output from the lilypond-book file (here called +@code{yourfile.lytex}) via LaTeX, you should do -Running @command{lilypond-book} generates lots of small files that -LilyPond will process. To avoid all that garbage in the source -directory, it is advisable to change to a temporary directory first: @example -cd out && lilypond-book ../yourfile.tex +lilypond-book --psfonts yourfile.lytex +latex yourfile.tex +dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi +ps2pdf yourfile.ps @end example -@noindent -or to use the @option{--outdir} command line option, and change to -that director before running La@TeX{} or @file{makeinfo}: +The @file{.dvi} file created by this process will not contain +noteheads. This is normal; if you follow the instructions, they +will be included in the @file{.ps} and @file{.pdf} files. +To produce a PDF file through PDF(La)TeX, use + @example -lilypond-book --outdir=out yourfile.tex -cd out && latex yourfile.latex +lilypond-book --pdf yourfile.pdftex +pdflatex yourfile.tex @end example + -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}. +To produce a Texinfo document (in any output format), follow the normal +procedures for Texinfo (this is, either call @command{texi2dvi} or +@command{makeinfo}, depending on the output format you want to +create). +@ifinfo +@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating +an Info File, , , texinfo, GNU Texinfo}. +@end ifinfo +@ifnotinfo +See the documentation of Texinfo for further details. +@end ifnotinfo -@cindex titling and lilypond-book -@cindex lilypond-book and titling -@cindex @code{\header} in La@TeX{} documents -To add titling from the @code{\header} section of the files, add the -following to the top of the La@TeX{} file: +@command{lilypond-book} accepts the following command line options: + +@table @code +@item -f @var{format} +@itemx --format=@var{format} +Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing, +@command{lilypond-book} tries to detect the format automatically. + +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 instead. + +[Note: Currently, @code{texi} is the same as @code{texi-html}.] + +@item -F @var{filter} +@itemx --filter=@var{filter} +Pipe snippets through @var{filter}. @code{lilypond-book} will +not --filter and --process at the same time. + +Example: @example -\input titledefs.tex -\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@} +lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely @end example -@cindex outline fonts -@cindex type1 fonts -@cindex dvips -@cindex invoking dvips +@item -h +@itemx --help +Print a short help message. + +@item -I @var{dir} +@itemx --include=@var{dir} +Add @var{dir} to the include path. + +@item -o @var{dir} +@itemx --output=@var{dir} +Place generated files in directory @var{dir}. 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 @command{latex} or @command{makeinfo}: -For printing the LaTeX document, you will need to use dvips. For -producing PS with scalable fonts, add the following options to the dvips -command line: @example - -Ppdf -u +lilypond.map -@end example +lilypond-book --output=out yourfile.lytex +cd out +... +@end example +@itemx --padding=@var{amount} +Pad EPS boxes by this much. @var{amount} is measured in milimeters, +and is 3.0 by default. This option should be used if the lines of +music stick out of the right margin. +The width of a tightly clipped systems can vary, due to notation +elements that stick into the left margin, such as bar numbers and +instrument names. This option will shorten each line and move each +line to the right by the same amount. -@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 -out automatically. +@item -P @var{process} +@itemx --process=@var{command} +Process LilyPond snippets using @var{command}. The default command is +@code{lilypond}. @code{lilypond-book} will not --filter and --process +at the same time. -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. +@itemx --psfonts +extract all PostScript fonts into @file{@var{file}.psfonts} for dvips. +This is necessary for @command{dvips -h @var{file}.psfonts}. -@item @option{--default-music-fontsize=@var{sz}pt} -Set the music font size to use if no fontsize is given as option. +@item -V +@itemx --verbose +Be verbose. -@item @option{--force-music-fontsize=@var{sz}pt} -Force all music to use this fontsize, overriding options given to -@code{\begin@{lilypond@}}. +@item -v +@itemx --version +Print version information. +@end table -@item @option{-I @var{dir}}, @option{--include=@var{dir}} -Add @var{DIR} to the include path. +@refbugs -@item @option{-M}, @option{--dependencies} -Write dependencies to @file{filename.dep}. +The Texinfo command @code{@@pagesizes} is not interpreted. Similarly, +La@TeX{} commands that change margins and line widths after the preamble +are ignored. -@item @option{--dep-prefix=@var{pref}} -Prepend @var{pref} before each @option{-M} dependency. +Only the first @code{\score} of a LilyPond block is processed. -@item @option{-n}, @option{--no-lily} -Generate the @code{.ly} files, but do not process them. -@item @option{--no-music} -Strip all music from the input file. +@node Filename extensions +@section Filename extensions -@item @option{--no-pictures} -Do not generate pictures when processing Texinfo. +You can use any filename extension for the input file, but if you do not +use the recommended extension for a particular format you may need to +manually specify the output format. @xref{Invoking lilypond-book}, for +details. Otherwise, @command{lilypond-book} automatically selects the +output format based on the input filename's extension. -@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. +@quotation +@multitable @columnfractions .2 .5 +@item @strong{extension} @tab @strong{output format} +@item +@item @file{.html} @tab HTML +@item @file{.itely} @tab Texinfo +@item @file{.latex} @tab La@TeX{} +@item @file{.lytex} @tab La@TeX{} +@item @file{.lyxml} @tab DocBook +@item @file{.tely} @tab Texinfo +@item @file{.tex} @tab La@TeX{} +@item @file{.texi} @tab Texinfo +@item @file{.texinfo} @tab Texinfo +@item @file{.xml} @tab HTML +@end multitable +@end quotation -@item @option{--outdir=@var{dir}} -Place generated files in @var{dir}. -@item @option{--version} -Print version information. +@node Many quotes of a large score +@section Many quotes of a large score -@item @option{--help} -Print a short help message. -@end table +If you need to quote many fragments of a large score, you can also use +the clip systems feature, see @ref{Extracting fragments of notation}. +@node Inserting LilyPond output into OpenOffice.org +@section Inserting LilyPond output into OpenOffice.org -@section Bugs +@cindex OpenOffice.org -The La@TeX{} @code{\includeonly@{...@}} command is ignored. +LilyPond notation can be added to OpenOffice.org with +@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond} -The Texinfo command @code{pagesize} is not interpreted. Almost all -La@TeX{} commands that change margins and line widths are ignored. -Only the first @code{\score} of a LilyPond block is processed. +@node Inserting LilyPond output into other programs +@section Inserting LilyPond output into other programs + +To insert LilyPond output in other programs, use @code{lilypond} +instead of @code{lilypond-book}. Each example must be created +individually and added to the document; consult the documentation for +that program. Most programs will be able to insert lilypond output in +@file{PNG}, @file{EPS}, or @file{PDF} formats. -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}. Using @code{\lilypondfile} also makes -upgrading files (through convert-ly, see @ref{Invoking convert-ly}) -easier. - -@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 changes made to global GUILE definitions, e.g. done -with @code{set!} or @code{set-cdr!}, can leak from one fragment into -the next fragment. +To reduce the white space around your lilypond score, use +the following options + +@example +\paper@{ + indent=0\mm + line-width=120\mm + oddFooterMarkup=##f + oddHeaderMarkup=##f + bookTitleMarkup = ##f + scoreTitleMarkup = ##f +@} + +@{ c1 @} +@end example + +To produce a useful @file{eps} file, use + +@example +lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly +@end example