@c -*-texinfo-*-
-@node Merging text and music with lilypond-book
-@chapter Merging text and music with lilypond-book
+@ignore
-@command{lilypond-book} runs Lilypond on fragments of lilypond in a
-La@TeX{} or Texinfo file, and includes the results into a document that
-can be processed with La@TeX{}, @command{makeinfo} or
-@command{texi2dvi}. The result is a text document containing formatted
-music integrated.
+TODO: cleanup
-More precisely, if a La@TeX{} file contains
-@example
+** AARGH.e We also have tutorial.itely: Integrating text and music.
- \begin@{lilypond@}
- CONTENTS
- \end@{lilypond@}
-
-@end example
-or
-@example
- \lilypond@{CONTENTS@}
-@end example
-then LilyPond is run on CONTENTS. @command{lilypond-book} puts the
-result back into the latex file. When you run the result through latex,
-you get a document that mixes text and music. lilypond-book will insert
-line width and font size definitions before @code{CONTENTS}, so the
-music samples will match the layout of your document.
-
-Very often, if you mix music and text, the music is only a few
-notes or at most a few bars. This music should be as short as possible
-and not stretched to be aligned to the right margin. lilypond-book does
-this automatically if you don't use a @code{\score} block in
-@code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
-@}}.
-
-You can also use @code{lilypondfile} to include another file:
-@example
- \lilypondfile@{foo.ly@}
-@end example
+ Could also do with a cleanup. Lost inspiration to fix this manual
+ where to describe what?
-All three forms can take several options. They are specified in brackets
-as follows:
-@example
- \lilypondfile[options, go, here]@{ .. @}
- \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
- \lilypond[options, go,here]@{ .. @}
-@end example
+@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.
-In the Texinfo version, bitmaps of the music are also generated, so you
-can make a HTML document with embedded music.
+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 introduction to using La@TeX{}.
-@section Texinfo reference
-You specify the lilypond code like this:
+
+@menu
+* Integrating Texinfo and music::
+* Integrating LaTeX and music::
+* Integrating HTML and music::
+* Music fragment options::
+* Invoking lilypond-book::
+@end menu
+
+
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to
+
+
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
+
+Music is specified like this:
+
@example
-@@lilypond[options, go, here]
- YOUR LILYPOND CODE
+@@lilypond[options,go,here]
+ YOUR LILYPOND CODE
@@end lilypond
-@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options, go,here]@{@var{filename}@}
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options,go,here]@{@var{filename}@}
@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:
-@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.
-
-We show two simple examples here. First a complete block:
@example
-@@lilypond[26pt]
-c' d' e' f' g'2 g'
+@@lilypond[staffsize=26]
+ c' d' e' f' g'2 g'
@@end lilypond
@end example
-produces this music:
-@lilypond
-c' d' e' f' g'2 g'
+@noindent
+produces
+
+@lilypond[fragment]
+ c' d' e' f' g'2 g'
@end lilypond
Then the short version:
+
@example
-@@lilypond[11pt]@{<c' e' g'>@}
+@@lilypond[staffsize=11]@{<c' e' g'>@}
@end example
-and its music:
+@noindent
+produces
+
+@lilypond[fragment,staffsize=11]{ <c' e' g'> }
+
+When producing texinfo, lilypond-book also generates bitmaps of the
+music, so you can make a HTML document with embedded music.
-@lilypond[11pt]{<c' e' g'>}
+@c @TeX{} in node name seems to barf
+@node Integrating LaTeX and music
+@section Integrating LaTeX and music
-@section La@TeX{} reference
-You specify the lilypond code like this:
+For La@TeX{}, music is entered using
+
@example
-\begin[option, go, here]@{lilypond@}
- YOUR LILYPOND CODE
+\begin[options,go,here]@{lilypond@}
+ YOUR LILYPOND CODE
\end@{lilypond@}
@end example
@example
-\lilypondfile[options, go,here]@{@var{filename}@}
+\lilypondfile[options,go,here]@{@var{filename}@}
@end example
-or
+
+@noindent
+or
+
@example
\lilypond@{ YOUR LILYPOND CODE @}
@end example
-Lilypond-book know about the @code{\onecolumn} and
-@code{\twocolumn} commands, the @code{geometry} package
-(all except the following options: paperwidth, papersize,
-hdivide, divide, textwidth, mag, offset) and all the
-standard paper sizes.
+Running lilypond-book yields a file that can be processed with
+La@TeX{}.
-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.
-We show some examples here.
+We show some examples here:
@example
-\begin[26pt]@{lilypond@}
-c' d' e' f' g'2 g'2
+\begin[staffsize=26]@{lilypond@}
+ c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example
-produces this music:
+@noindent
+produces
-@lilypond[26pt]
-c' d' e' f' g'2 g'2
+@lilypond[fragment,staffsize=26]
+ c' d' e' f' g'2 g'2
@end lilypond
Then the short version:
+
@example
-\lilypond[11pt]@{<c' e' g'>@}
+\lilypond[staffsize=11]@{<c' e' g'>@}
@end example
-and its music:
+@noindent
+produces
-@lilypond[11pt]{<c' e' g'>}
+@lilypond[fragment,staffsize=11]{<c' e' g'>}
+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.
-@section Options
+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.
-@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.
+@cindex titling and lilypond-book
+@cindex @code{\header} in La@TeX{} documents
-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)
+The music will be surrounded by @code{\preLilyPondExample} and
+@code{\postLilyPondExample}, which are defined to be empty by default.
-@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] |
- }
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+For printing the LaTeX 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
+@end example
+
+@noindent
+PDF can then be produced with @code{ps2pdf}.
+
+@cindex international characters
+@cindex latin1
+
+LilyPond does not use the LaTeX 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 LaTeX packages. Please consult the mailing list
+for more details.
+
+
+
+
+
+@node Integrating HTML and music
+@section Integrating HTML and music
+
+Music is entered using
+
+@example
+<lilypond relative=1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
+
+@noindent
+of which lilypond-book will produce a HTML with appropriate image tags for the
+music fragments:
+
+@example
+<lilypond relative=2 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
+
+@lilypond[fragment,relative=2]
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
@end lilypond
-@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.
+For inline pictures, use @code{<lilypond ... />} syntax, e.g.
+@example
+Some music in <lilypond a b c/> a line of text.
+@end example
+
+A special feature not (yet) available in other output formats, is the
+@code{<lilypondfile>} tag, for example,
+@example
+ <lilypondfile>trip.ly</lilypondfile>
+@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 one or more of the
+following options:
+
+@table @code
+@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:
+
+@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 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 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.
+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.
+
+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.
-@section Invocation
+@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"
+ @}
+ \score @{ \notes @{ 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
+@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{latex} or @code{texi}.
- @command{lilypond-book} usually figure 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
+@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.
+
+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
-[TODO not a useful option unless you can undump the input file]
-
-@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.
-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 La@TeX{} @code{\includeonly@{...@}} command is ignored.
+
+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.
-Almost all La@TeX{} commands that change margins and line widths are
-ignored.
+@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}.
-There is no way to automatically apply convert-ly to fragments inside a
-lilypond-book file.
projects / lilypond.git / blobdiff