+@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.
-@section TeXinfo reference
+@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{}.
+
+
+
+
+@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:
-Your markup the lilypond code like this:
@example
@@lilypond[options, go, here]
- YOUR LILYPOND CODE
+ YOUR LILYPOND CODE
@@end lilypond
+@@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options, go, here]@{@var{filename}@}
@end example
-or
+When lilypond-book is run on it, this results in a texinfo file. We
+show two simple examples here. First a complete block:
@example
-@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
+@@lilypond[26pt]
+ c' d' e' f' g'2 g'
+@@end lilypond
+@end example
+
+@noindent
+produces
+
+@lilypond
+ c' d' e' f' g'2 g'
+@end lilypond
+
+Then the short version:
+
+@example
+@@lilypond[11pt]@{<<c' e' g'>>@}
@end example
-@command{lilypond-book} knows the default margins, and a few papersizes.
-These commands should be in the beginning of the document:
+@noindent
+produces
+
+@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
+
+@noindent
@code{@@pagesizes} are not yet supported.
-@subsection Examples
+When producing texinfo, lilypond-book also generates bitmaps of the
+music, so you can make a HTML document with embedded music.
-Two simple examples. First a complete block:
+
+@c @TeX{} in node name seems to barf
+@node Integrating LaTeX and music
+@section Integrating LaTeX and music
+
+
+For La@TeX{}, music is entered using
@example
-@@lilypond[26pt]
-c' d' e' f' g'2 g'
-@@end lilypond
+\begin[options, go, here]@{lilypond@}
+ YOUR LILYPOND CODE
+\end@{lilypond@}
@end example
-produces this music:
-@lilypond
-c' d' e' f' g'2 g'
-@end lilypond
+@example
+\lilypondfile[options, go,here]@{@var{filename}@}
+@end example
+
+@noindent
+or
-Then the short version:
@example
-@@lilypond[11pt]@{<c' e' g'>@}
+\lilypond@{ YOUR LILYPOND CODE @}
@end example
-and its music:
+Running lilypond-book yields a file that can be processed with
+La@TeX{}. We show some examples here:
-@lilypond[11pt]{<c' e' g'>}
+@example
+\begin[26pt]@{lilypond@}
+ c' d' e' f' g'2 g'2
+\end@{lilypond@}
+@end example
+@noindent
+produces
-@subsection @@example and @@code
+@lilypond[26pt]
+ c' d' e' f' g'2 g'2
+@end lilypond
-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.
+Then the short version:
-@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
+\lilypond[11pt]@{<<c' e' g'>>@}
@end example
-or this:
+@noindent
+produces
-@code{@@lilypond@{ BLABLA @}}
+@lilypond[11pt]{<<c' e' g'>>}
-Anything other is a bug in @command{lilypond-book}.
+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.
-So to get this in the printed manual:
+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.
-@example
-@@lilypond[26pt]
-\relative c'@{c d e f g2 g@}
-@@end lilypond
-@end example
-
-you have to write this:
+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
-@@example
-@@@@lilypond[26pt]
-\relative c'@@@{c d e f g2 g@@@}
-@@@@end lilypond
-@@end example
+\input titledefs.tex
+\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
@end example
-Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
-'@@@}' and '@@@@'. This is how it works in plain texinfo too.
+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
-@section La@TeX{} reference
+Music is entered using
-Your markup the lilypond code like this:
@example
-\begin[option, go, here]@{lilypond@}
- YOUR LILYPOND CODE
-\end@{lilypond@}
+<lilypond relative1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
@end example
-or
-
+@noindent
+of which lilypond-book will produce a HTML with appropriate image tags for the
+music fragments:
+
@example
-\lilypond@{ YOUR LILYPOND CODE @}
+<lilypond relative1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
@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]}
+@lilypond[relative1]
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+@end lilypond
-@subsection Examples
+For inline pictures, use @code{<lilypond ... />} syntax, eg.
+@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{<ly2dvifile>} tag, for example,
@example
-\begin[26pt]@{lilypond@}
-c' d' e' f' g'2 g'2
-\end@{lilypond@}
+ <ly2dvifile>trip.ly</ly2dvifile>
@end example
+This runs @file{trip.ly} through ly2dvi (see also @ref{Invoking
+ly2dvi}), and substitutes a preview image in the output. The image
+links to a separate HTML file, so clicking it will take the viewer to
+a menu, with links to images, midi and printouts.
-produces this music:
+@cindex ly2dvi
+@cindex titling in THML
+@cindex preview image
+@cindex thumbnail
-@lilypond[26pt]
-c' d' e' f' g'2 g'2
-@end lilypond
+@node Music fragment options
+@section Music fragment options
-Then the short version:
-@example
-\lilypond[11pt]@{<c' e' g'>@}
-@end example
+The commands for lilypond-book have room to specify one or more of the
+following options:
-and its music:
+@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:
+
+@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
+
+@item smallverbatim
+works like @code{verbatim}, but in a smaller font.
+
+@item intertext="@var{text}"
+is used in conjunction with @code{verbatim} option: This puts
+@var{text} between the code and the music (without indentation).
+
+@item filename="@var{filename}"
+saves the LilyPond code to @var{filename}. By default, a hash value
+of the code is used.
+
+@item 11pt
+@lilypond[11pt, eps]
+\relative c' {
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
+ d16[ g, a b] c[ a b g] d'8[ g f\prall g]
+}
+@end lilypond
-@lilypond[11pt]{<c' e' g'>}
+@item 13pt
+@lilypond[13pt, eps]
+\relative c' {
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
+ d16[ g, a b] c[ a b g] d'8[ g f\prall g]
+}
+@end lilypond
+@item 16pt
+@lilypond[16pt, eps]
+\relative c' {
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
+}
+@end lilypond
-@subsection \begin@{verbatim@} and \verb|\verb|
+@item 20pt
+@lilypond[20pt, eps]
+\relative c' {
+ r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+}
+@end lilypond
-There work just as expected. Look at @file{mb-latex.tex} for details.
+@item 26pt
+@lilypond[26pt, eps]
+\relative c' {
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
+}
+@end lilypond
-@section Options
+@item raggedright
+produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
+works well for small music fragments.
-@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)
-@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 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 singleline
- linewidth = -1.
@item multiline
- linewidth = textwidth
+is the opposite of @code{singleline}: it justifies and breaks lines.
+
+@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} autodetection of what type of code is in the
- lilypond block, voice contents or complete code.
-@end table
+@itemx nofragment
+overrides @command{lilypond-book} auto detection of what type of code is
+in the LilyPond block, voice contents or complete code.
-@section Invocation
+@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.
-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} commandline options:
+@item noindent
+sets indentation of the first music system to zero. This option
+affects LilyPond, not the text layout.
-@code{cd out && lilypond-book ../yourfile.tex}
+@item notexidoc
+prevents including @code{texidoc}. This is only for Texinfo output.
-@code{lilypond-book --outdir=out 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:
+@example
+ \header @{
+ texidoc = "this file demonstrates a single note"
+ @}
+ \score @{ \notes @{ c'4 @} @}
+@end example
-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.
+@item quote
+instructs @command{lilypond-book} to put La@TeX{} and Texinfo output
+into a quotation block.
-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
-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.
+@item printfilename
+prints the file name before the music example. Useful in conjunction
+with @code{\lilypondfile}.
-@strong{About the input}
+@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
-If the file contains the ``block''
-@example
+@node Invoking lilypond-book
+@section Invoking lilypond-book
- \begin@{lilypond@}
- CONTENTS
- \end@{lilypond@}
-
+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
+@end example
+
+@noindent
+or to use the @option{--outdir} command line option, and change to
+that director before running La@TeX{} or @file{makeinfo}:
+
+@example
+lilypond-book --outdir=out yourfile.tex
+cd out && latex yourfile.latex
+@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}.
+
+@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:
+@example
+\input titledefs.tex
+\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
+@end example
+
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+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
-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.
-@subsection Command line options
+@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 @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
- 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 -M, --dependencies
- Write dependencies to out-www/filename.dep
-@item --dep-prefix=PREF
- prepend PREF before each -M dependency
-@item -n, --no-lily
- don't run lilypond
-@item --no-pictures
- don't generate pictures
-@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
- 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
-@item --version
- print version information
-@item --help
- Print a short help message
-@end table
+The @code{texi} document type produces a texinfo file with music
+fragments in the DVI output only. For getting images in the HTML
+version, the format
+@code{texi-html} must be used.
+@item @option{--default-music-fontsize=@var{sz}pt}
+Set the music font size to use if no fontsize is given as option.
+@item @option{--force-music-fontsize=@var{sz}pt}
+Force all music to use this fontsize, overriding options given to
+@code{\begin@{lilypond@}}.
-@command{lilypond-book} is written in python 1.5, so you have to install
-@uref{http://www.python.org,python}.
+@item @option{-I @var{dir}}, @option{--include=@var{dir}}
+Add @var{DIR} to the include path.
+@item @option{-M}, @option{--dependencies}
+Write dependencies to @file{filename.dep}.
+@item @option{--dep-prefix=@var{pref}}
+Prepend @var{pref} before each @option{-M} dependency.
-@section Bugs
-
-The La@TeX{} \includeonly@{...@} command is ignored.
+@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.
+
+@item @option{--no-pictures}
+Do not generate pictures when processing Texinfo.
+
+@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.
-Ignores almost all La@TeX{} commands that changes margins and linewidths.
+@item @option{--outdir=@var{dir}}
+Place generated files in @var{dir}.
+
+@item @option{--version}
+Print version information.
+
+@item @option{--help}
+Print a short help message.
+@end table
+
+
+
+@section Bugs
-@section Authors
+The La@TeX{} @code{\includeonly@{...@}} command is ignored.
-@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
+The Texinfo command @code{pagesize} is not interpreted. Almost all
+La@TeX{} commands that change margins and line widths are ignored.
-@email{tca@@gnu.org, Tom Cato Amundsen}
+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.
projects / lilypond.git / blobdiff