-@c -*-texinfo-*-
+@c -*- coding: latin-1; mode: texinfo; -*-
+
@ignore
@end ignore
-@node lilypond-book manual
-@chapter lilypond-book manual
+@node Integrating text and music
+@chapter 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
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
-@cindex texinfo
-@cindex latex
-@cindex texinfo
-@cindex @code{texi}
-@cindex html
-@cindex documents, adding music to
+@node An example of a musicological document
+@section An example of a musicological document
-@node Integrating Texinfo and music
-@section Integrating Texinfo and music
+@cindex musicology
+@cindex La@TeX{}, music in
+@cindex HTML, music in
+@cindex Texinfo, 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 HTML, La@TeX{}, and Texinfo 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
+
+@verbatim
+\documentclass[a4paper]{article}
+\begin{document}
+
+Documents for lilypond-book may freely mix music and text. For
+example,
+
+\begin{lilypond}
+\relative {
+ 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 in a separate file, and introduced with
+\verb+\lilypondfile+.
-Music is specified like this:
+\lilypondfile[quote,noindent]{screech-boink.ly}
+
+\end{document}
+@end verbatim
+
+Under Unix, you can view the results as follows
@example
-@@lilypond[options,go,here]
- YOUR LILYPOND CODE
-@@end lilypond
-@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options,go,here]@{@var{filename}@}
+cd input/tutorial
+mkdir -p out/
+lilypond-book --output=out/ lilybook.tex
+@emph{lilypond-book (GNU LilyPond) 2.3.11}
+@emph{Reading `input/tutorial/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
-When lilypond-book is run on it, this results in a texinfo file. We
-show two simple examples here. First a complete block:
+To convert the file into a nice PDF document, run the following
+commands
@example
-@@lilypond[staffsize=26]
- c' d' e' f' g'2 g'
-@@end lilypond
+dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+ps2pdf lilybook.ps
@end example
-@noindent
-produces
+Running lilypond-book and running 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}.
+
+Finally the result of the La@TeX{} example shown above.@footnote{ This
+tutorial is processed with Texinfo, so the example is as well. This
+gives slightly different results in layout.} This finishes the
+tutorial section.
+
+@page
+
+Documents for lilypond-book may freely mix music and text. For
+example,
@lilypond
- c' d' e' f' g'2 g'
+\relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
@end lilypond
-Then the short version:
+Options are put in brackets.
-@example
-@@lilypond[staffsize=11]@{<c' e' g'>@}
-@end example
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
-@noindent
-produces
+Larger examples can be put in a separate file, and introduced with
+@code{\lilypondfile}.
-@lilypond[staffsize=11]{ <c' e' g'> }
+@lilypondfile[quote,noindent]{screech-boink.ly}
+
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to
-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
@noindent
produces
-@lilypond[staffsize=26]
+@lilypond[fragment,staffsize=26]
c' d' e' f' g'2 g'2
@end lilypond
@noindent
produces
-@lilypond[staffsize=11]{<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.
+@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
- -Ppdf -u +lilypond.map
+ -Ppdf -u+lilypond.map -u+ec-mftrace.map
@end example
@noindent
@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
</lilypond>
@end example
-@lilypond[relative=2]
+@lilypond[fragment,relative=2]
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
@end lilypond
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},
\header @{
texidoc = "this file demonstrates a single note"
@}
- \score @{ \notes @{ c'4 @} @}
+ @{ 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}
@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
Process lilypond snippets using @var{command}. The default command is
-@var{lilypond-bin}.
+@code{lilypond}.
@item @option{--verbose}
Be verbose.
-@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
projects / lilypond.git / blobdiff