+@c -*-texinfo-*-
-@tex
-\def\preLilypondExample{\vspace{0.5cm}}
-@end tex
+@ignore
-@node lilypond-book
-@chapter lilypond-book
+TODO: cleanup
-[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
+** AARGH.e We also have tutorial.itely: Integrating text and music.
-@command{lilypond-book} is a script that helps integrating lilypond with
-La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
-of lilypond in your source 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 with formatted music
-integrated.
+ Could also do with a cleanup. Lost inspiration to fix this manual
+ where to describe what?
-@command{lilypond-book} will do its best to try to align the music to
-the left and right margins. Currently all papersizes, one- and
-twocolumn mode and the @code{geometry} package is supported.
-The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
-But changing the linewidth in other ways will not give you a straight
-right margin.
+@end ignore
-This document assumes you have basic knowledge of GNU LilyPond and
-La@TeX{} or texinfo.
+@c @node Merging text and music with lilypond-book
+@c @chapter Merging text and music with lilypond-book
-@section TeXinfo reference
+@c fix this node name , this is too long.
-Your markup the lilypond code like this:
-@example
-@@lilypond[options, go, here]
- YOUR LILYPOND CODE
-@@end lilypond
-@end example
+@node lilypond-book: Integrating text and music
+@chapter lilypond-book: Integrating text and music
-or
+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.
-@example
-@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
-@end example
+@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.
+
+It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
+on using lilypond-book is in @ref{integrating text and music}.
+
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to
-@command{lilypond-book} knows the default margins, and a few papersizes.
-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.
-@subsection Examples
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
-Two simple examples. First a complete block:
+You specify the LilyPond code like this:
+@example
+@@lilypond[options, go, here]
+ YOUR LILYPOND CODE
+@@end lilypond
+@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options, go,here]@{@var{filename}@}
+@end example
+We show two simple examples here. First a complete block:
@example
@@lilypond[26pt]
c' d' e' f' g'2 g'
@lilypond[11pt]{<c' e' g'>}
+@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.
-@subsection @@example and @@code
-
-I'm not sure if this will go into the final documentation, this is
-here mostly to remember me on why things are the way they are.
-
-@command{lilypond-book} will do nothing with special with @code{@@code} and
-@code{@@example} environments. The 'code' and 'example' commands
-should work just as normal. People looking at document that should be
-processed by @command{lilypond-book}, should notice nothing special, except from
-some block like this:
-@example
-@@lilypond
-BLABLA
-@@end lilypond
-@end example
-
-or this:
-
-@code{@@lilypond@{ BLABLA @}}
-
-Anything other is a bug in @command{lilypond-book}.
-
-So to get this in the printed manual:
-
-@example
-@@lilypond[26pt]
-\relative c'@{c d e f g2 g@}
-@@end lilypond
-@end example
-
-you have to write this:
-
-@example
-@@example
-@@@@lilypond[26pt]
-\relative c'@@@{c d e f g2 g@@@}
-@@@@end lilypond
-@@end example
-@end example
-
-Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
-'@@@}' and '@@@@'. This is how it works in plain texinfo too.
-
+When producing texinfo, lilypond-book also generates bitmaps of the
+music, so you can make a HTML document with embedded music.
-@section La@TeX{} reference
+@node Integrating La@TeX{} and music
+@section Integrating La@TeX{} and music
-Your markup the lilypond code like this:
+You specify the LilyPond code like this:
@example
\begin[option, go, here]@{lilypond@}
YOUR LILYPOND CODE
\end@{lilypond@}
@end example
+@example
+\lilypondfile[options, go,here]@{@var{filename}@}
+@end example
or
-
@example
\lilypond@{ YOUR LILYPOND CODE @}
@end example
-Lilypond-book know about the @code{\onecolumn} and
-@code{\twocolumn} commands, the @code{geometry} package and
-all the standard paper sizes.
-
-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.
-@strong{[UGH: THIS DOES NOT HAPPEN WHEN
-YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
-
-@subsection Examples
+We show some examples here.
@example
\begin[26pt]@{lilypond@}
@lilypond[11pt]{<c' e' g'>}
-@subsection \begin@{verbatim@} and \verb|\verb|
+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:
+
+@quotation
+@example
+<lilypond relative1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
+@end quotation
+
+produces
+
+@quotation
+@example
+<lilypond relative1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
+@lilypond[relative1]
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+@end lilypond
+@end quotation
-There work just as expected. Look at @file{mb-latex.tex} for details.
+Inline picture:
-@section Options
+@quotation
+@example
+Some music in <lilypond a b c/> a line of text.
+@end example
+@end quotation
+
+@node Music fragment options
+@section Music fragment options
+
+The commands for lilypond-book have room to specify options. These are
+all of the options:
@table @code
@item eps
- the music is created as eps graphics that can be inserted in
- the middle of a text line, not only as a separate paragraph.
- (La@TeX{} only)
+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 (eg. 11 pt or 13 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
the actual music is displayed. This option does not work with
- the short version of the lilypond blocks:
+ the short version of the LilyPond blocks:
@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
-
-@item intertext="text inside apostrophs"
- Used in conjunction with @code{verbatim} option.
-@item filename=FILENAME
- Save the lilypond code to FILENAME instead of using a hash value
- of CONTENTS.
-@item 11pt, 13pt, 16pt, 20pt, 26pt
- set the fontsize to use for the music
+
+@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 singleline
- linewidth = -1.
+ Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
@item multiline
- linewidth = textwidth
+ 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} autodetection of what type of code is in the
- lilypond block, voice contents or complete code.
+ 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.
+@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
-@section Invocation
+@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. So to avoid all the garbage in
+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} commandline options:
+directory, or use the @code{--outdir} command line options:
@code{cd out && lilypond-book ../yourfile.tex}
@code{lilypond-book --outdir=out yourfile.tex}
-For latex input, the file to give to latex has ext @file{.latex}.
-TeXinfo input will be written to a file with ext @file{.texi}. So be
-careful, don't give the source file that ext, or the file will be
-overwritten.
+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 kludgy, but
+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.
-@strong{About the input}
-
-If the file contains the ``block''
-
-@example
-
- \begin@{lilypond@}
- CONTENTS
- \end@{lilypond@}
-
-@end example
-
-then LilyPond is run on CONTENTS. @command{lilypond-book} puts the result back,
-surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
-commands. @code{\preLilypondExample} and @code{posLilypondExample} is
-defined to nothing by default, and the user can redefine them
-to whatever he wants.
-
@cindex titling and lilypond-book
@cindex lilypond-book and titling
@cindex \header in LaTeX documents
-If you want to combine music that has titling in @code{\header}
+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
@example
\input titledefs.tex
\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
@end example
-
-
-@subsection Command line options
-
+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 out this automatically.
-@item --default-music-fontsize=??pt
- Set the fontsize to use for lilypond if no fontsize is given
+ Specify the document type to process: @code{html}, @code{latex} or
+@code{texi} (default). @command{lilypond-book} usually 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=??pt
- Force all lilypond to use this fontsize, overriding options
- given to \begin@{lilypond@}
-@item -I DIR, --include=DIR
- include path
+@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 out-www/filename.dep
-@item --dep-prefix=PREF
- prepend PREF before each -M dependency
+ 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
+ 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
+ don't generate pictures when processing Texinfo.
@item --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 --outname=FILE
+@example
+ lilypond-book file.tely
+ convert-ly
+ lilypond-book --read-lys
+@end example
+
+@item --outname=@var{FILE}
The name of La@TeX{} file to output. If this option is not given,
- the output name derived from the input name.
-@item --outdir=
- where to place generated files
+ 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
@end table
-
-@command{lilypond-book} is written in python 1.5, so you have to install
-@uref{http://www.python.org,python}.
-
-
-
@section Bugs
The La@TeX{} \includeonly@{...@} command is ignored.
-Ignores almost all La@TeX{} commands that changes margins and linewidths.
-
-@section Authors
+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.
-@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
+Almost all La@TeX{} commands that change margins and line widths are
+ignored.
-@email{tca@@gnu.org, Tom Cato Amundsen}
+There is no way to automatically apply convert-ly only to fragments
+inside a lilypond-book file.
+@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.
projects / lilypond.git / blobdiff