-@c -*-texinfo-*-
+@c -*- coding: latin-1; mode: texinfo; -*-
+
@ignore
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 introduction to using La@TeX{}.
+documents.
@menu
+* An example of a musicological document::
* Integrating Texinfo and music::
* Integrating LaTeX and music::
* Integrating HTML and music::
* Music fragment options::
-* Invoking lilypond-book::
+* Invoking lilypond-book::
+* Filename extensions::
@end menu
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 @LaTeX{}. The example also contains explanatory text, so we will
+small example for use with La@TeX{}. The example also contains explanatory text, so we will
not comment on it further
@verbatim
\lilypondfile[quote,noindent]{screech-boink.ly}
\end{document}
-@end verb+
+@end verbatim
Under Unix, you can view the results as follows
@emph{lilypond-book (GNU LilyPond) 2.3.11}
@emph{Reading `input/tutorial/lilybook.tex'}
@emph{..lots of stuff deleted..}
-@emph{Compiling `out//lilybook.tex'
+@emph{Compiling `out//lilybook.tex'}
cd out
latex lilybook
@emph{lots of stuff deleted}
@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
-@@end lilypond
-@@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:
-
-@example
-@@lilypond[staffsize=26]
- c' d' e' f' g'2 g'
-@@end lilypond
-@end example
-
-@noindent
-produces
-
-@lilypond[fragment]
- c' d' e' f' g'2 g'
-@end lilypond
-
-Then the short version:
-
-@example
-@@lilypond[staffsize=11]@{<c' e' g'>@}
-@end example
-
-@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.
-
@c @TeX{} in node name seems to barf
@node Integrating LaTeX and music
@section Integrating LaTeX and music
+La@TeX{} is the de facto standard for publishing layouts in the exact
+sciences. It is built on top of the @TeX{} typesetting engine, so it
+provides the best typography available anywhere.
+
+For more information about La@TeX{}
+@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
+Short Introduction to La@TeX{}} provides a introduction to using
+La@TeX{}.
For La@TeX{}, music is entered using
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.
+@code{\begin@{document@}}. The @command{lilypond-book} command sends
+these to La@TeX{} to find out how wide the text is. The line width
+for the music fragments is then adjusted to the text width.
After @code{\begin@{document@}}, the column changing commands
@code{\onecolumn}, @code{\twocolumn} commands
@cindex dvips
@cindex invoking dvips
-For printing the LaTeX document, you will need to use dvips. For
+For printing the La@TeX{} document, you will need to use dvips. For
producing PostScript with scalable fonts, add the following options to
the dvips command line:
@example
@cindex international characters
@cindex latin1
-LilyPond does not use the LaTeX font handling scheme for lyrics and text
+LilyPond does not use the La@TeX{} font handling scheme for lyrics and text
markups, so if you use characters in your lilypond-book
documents that are not included in the standard US-ASCII character set,
include @code{\usepackage[latin1]@{inputenc@}} in the file
-header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
+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
+using the corresponding La@TeX{} packages. Please consult the mailing list
for more details.
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
+
+Texinfo is the standard format for documentation at the GNU
+project. An example of a texinfo document is this manual. The HTML,
+PDF and Info versions of the manual are made from the document.
+
+When run on a lilypond-book, produces a @file{.texi} file containing
+@code{@@image} tags for HTML and info. For the printed edition, the
+raw @TeX{} output of LilyPond is included into the main document.
+
+In the input file, music is specified like
+
+@example
+@@lilypond[options,go,here]
+ YOUR LILYPOND CODE
+@@end lilypond
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options,go,here]@{@var{filename}@}
+@end example
+
+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[staffsize=26]
+ c' d' e' f' g'2 g'
+@@end lilypond
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment]
+ c' d' e' f' g'2 g'
+@end lilypond
+
+Then the short version:
+
+@example
+@@lilypond[staffsize=11]@{<c' e' g'>@}
+@end example
+
+@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.
+
+
+
+
@node Integrating HTML and music
@section Integrating HTML and music
Music is entered using
@example
-<lilypond relative=1 verbatim>
+<lilypond relative=2 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:
-
+
+@c why the second example? -gp
@example
<lilypond relative=2 verbatim>
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
Some music in <lilypond a b c/> a line of text.
@end example
+@c FIXME: check if this feature is coming soon; if not, @ignore this stuff.
A special feature not (yet) available in other output formats, is the
@code{<lilypondfile>} tag, for example,
@example
prevents printing time signature.
@item fragment
-@item nofragment
-overrides @command{lilypond-book} auto detection of what type of code is
-in the LilyPond block, voice contents, or complete code.
+adds some boilerplate code, so you can enter like
+
+@example
+ c'4
+@end example
+
+@noindent
+without @code{\layout}, @code{\score} or other red tape.
@item indent=@var{size}\@var{unit}
sets indentation of the first music system to @var{size},
@{ 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
@example
lilypond-book --output=out yourfile.lytex
-cd out && latex yourfile.tex
+cd out
@end example
+This will produce a .tex or .texi file. To produce a pdf from the
+.tex file, you should do
+
+@example
+latex yourfile.tex
+dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
+ps2pdf yourfile.ps
+@end example
+
+To produce a texinfo document (in any output format), follow the normal
+procedures for texinfo.
@command{lilypond-book} accepts the following command line options:
For example:
@example
- lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
+ lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
@end example
@item @option{--help}
-@section Bugs
-
-The La@TeX{} @code{\includeonly@{...@}} command is ignored.
+@refbugs
The Texinfo command @code{pagesize} is not interpreted. Almost all
La@TeX{} commands that change margins and line widths are ignored.
problems with the Python regular expression engine. For longer files,
use @code{\lilypondfile}.
+
+@node Filename extensions
+@section Filename extensions
+
+You can use any filename extension, but if you do not use the
+recommended extension, you may need to manually specify what output
+format you want. See @ref{Invoking lilypond-book} for details.
+
+@code{Lilypond-book} automatically selects the output format based
+on the filename.
+
+@table @code
+
+@item @emph{.html} produces html output
+
+@item @emph{.itely} produces texinfo output
+
+@item @emph{.lytex} produces latex output
+
+@end table