@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-program.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
@end ignore
-@ignore
-
-TODO: cleanup
-
-** AARGH. We also have tutorial.itely: Integrating text and music.
-
- Could also do with a cleanup. Lost inspiration to fix this manual
- where to describe what?
-
-@end ignore
-
-
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node LilyPond-book
@chapter @command{lilypond-book}: Integrating text and music
substituted for the music. The line width and font size definitions for
the music are adjusted to match the layout of your document.
+This is a separate programs from lilypond itself, and is run
+on the command-line; see @ref{Command-line usage} for more information.
+
This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex texi
+@cindex html
+@cindex docbook
+@cindex documents, adding music to
+@cindex HTML, music in
+@cindex Texinfo, music in
+@cindex DocBook, music in
+@cindex @LaTeX{}, music in
+
@menu
* An example of a musicological document::
-* Integrating LaTeX and music::
-* Integrating Texinfo and music::
-* Integrating HTML and music::
-* Integrating DocBook and music::
+* Integrating music and text::
* Music fragment options::
* Invoking lilypond-book::
* Filename extensions::
-* Many quotes of a large score::
-* Inserting LilyPond output into OpenOffice.org::
-* Inserting LilyPond output into other programs::
+* Alternate methods of mixing text and music::
@end menu
@section An example of a musicological document
@cindex musicology
-@cindex @LaTeX{}, music in
-@cindex HTML, music in
-@cindex Texinfo, music in
-@cindex DocBook, 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.
example for use with @LaTeX{}. The example also contains explanatory
text, so we will not comment on it further.
+@subheading Input
+
@quotation
@verbatim
\documentclass[a4paper]{article}
@end verbatim
@end quotation
+@subheading Processing
+
Under Unix, you can view the results as follows
@example
@page
+@subheading Output
+
Documents for @command{lilypond-book} may freely mix music and text.
For example,
@lilypondfile[quote,noindent]{screech-boink.ly}
+
@page
-@cindex texinfo
-@cindex latex
-@cindex texinfo
-@funindex texi
-@cindex html
-@cindex docbook
-@cindex documents, adding music to
+@node Integrating music and text
+@section Integrating music and text
+Here we explain how to integrate LilyPond with various output formats.
+
+@menu
+* LaTeX::
+* Texinfo::
+* HTML::
+* DocBook::
+@end menu
-@node Integrating LaTeX and music
-@section Integrating @LaTeX{} and music
+@node LaTeX
+@subsection @LaTeX{}
@LaTeX{} is the de-facto standard for publishing layouts in the exact
sciences. It is built on top of the @TeX{} typesetting engine,
use the @code{line-width} music fragment option.
@cindex titling and lilypond-book
-@funindex \header in @LaTeX{} documents
+@cindex \header in @LaTeX{} documents
Each snippet will call the following macros if they have been defined by
the user:
@noindent
where the @var{file}@command{psfonts} file is obtained from
-@command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
+@command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
can then be produced with a PostScript to PDF translator like
@code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
will produce some warnings about fonts; these are harmless and may
@end example
-@node Integrating Texinfo and music
-@section Integrating Texinfo and music
+@node Texinfo
+@subsection Texinfo
Texinfo is the standard format for documentation of the GNU project. An
example of a Texinfo document is this manual. The HTML, PDF, and Info
document with embedded music.
-@node Integrating HTML and music
-@section Integrating HTML and music
+@node HTML
+@subsection HTML
Music is entered using
@cindex preview image
@cindex thumbnail
-@node Integrating DocBook and music
-@section Integrating DocBook and music
+@node DocBook
+@subsection DocBook
For inserting LilyPond snippets it is good to keep the conformity of
our DocBook document, thus allowing us to use DocBook editors,
validation etc. So we don't use custom tags, only specify a convention
based on the standard DocBook elements.
-@unnumberedsubsec Common conventions
+@subheading Common conventions
For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
formatted inline or not inline.
-The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
+The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
chosen to allow DocBook editors format the content gracefully.
The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
-@unnumberedsubsec Including a LilyPond file
+@subheading Including a LilyPond file
-This is the most simple case. We must use the @file{.ly} extension for the included file, and insert it as a standard @code{imageobject},
+This is the most simple case. We must use the @file{.ly} extension for the included file, and insert it as a standard @code{imageobject},
with the following structure:
@example
Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
-@unnumberedsubsec Including LilyPond code
+@subheading Including LilyPond code
Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
As you can see, the outermost element is a @code{mediaobject} or @code{inlinemediaobject}, and there is a @code{textobject} containing the @code{programlisting} inside.
-@unnumberedsubsec Processing the DocBook document
+@subheading Processing the DocBook document
+
+Running @command{lilypond-book} on our @file{.lyxml} file will create a
+valid DocBook document to be further processed with @file{.xml}
+extension. If you use
+@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
+PDF file from this document automatically. For HTML (HTML Help,
+JavaHelp etc.) generation you can use the official DocBook XSL
+stylesheets, however, it is possible that you have to make some
+customization for it.
-Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
-If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
-For HTML (HTML Help, JavaHelp etc.) generation you can use the official DocBook XSL stylesheets, however, it is possible that you have to make some customization for it.
@node Music fragment options
@section Music fragment options
the output into a quotation block. The value @q{0.4@dmn{in}} can be
controlled with the @code{exampleindent} option.
+@c in lilypond-book.py at l.953, it is said that this option is broken.
+@c remove?
@item exampleindent
Set the amount by which the @code{quote} option indents a music snippet.
displayed. This option does not work well with @code{\lilypond@{@}} if
it is part of a paragraph.
+If @code{verbatim} is used in a @code{lilypondfile} command, it is
+possible to enclose verbatim only a part of the source file. If the
+source file contain a comment containing @samp{begin verbatim} (without
+quotes), quoting the source in the verbatim block will start after the
+last occurence of such a comment; similarly, quoting the source verbatim
+will stop just before the first occurence of a comment containing
+@samp{end verbatim}, it there is any. In the following source file
+example, the music will be interpreted in relative mode, but the
+verbatim quote will not show the @code{relative} block.
+
+@example
+\relative c' @{ % begin verbatim
+ c4 e2 g4
+ f2 e % end verbatim
+@}
+@end example
+
@item texidoc
(Only for Texinfo output.) If @command{lilypond} is called with the
@option{--header=@/texidoc} option, and the file to be processed is
Most LilyPond test documents (in the @file{input} directory of the
distribution) are small @file{.ly} files which look exactly like this.
+@item lilyquote
+(Only for Texinfo output.) This option is similar to quote, but only
+the music snippet (and the optional verbatim block implied by
+@code{verbatim} option) is put into a quotation block. This option is
+useful if you want to @code{quote} the music snippet but not the
+@code{texidoc} documentation block.
+
@item printfilename
If a LilyPond input file is included with @code{\lilypondfile}, print
the file name right before the music snippet. For HTML output, this is
@item fontload
This option includes fonts in all of the generated EPS-files for this
-snippet. This should be used if the snippet uses any font that LaTeX
+snippet. This should be used if the snippet uses any font that LaTeX
cannot find on its own.
@end table
...
@end example
-@itemx --padding=@var{amount}
+@itemx --left-padding=@var{amount}
Pad EPS boxes by this much. @var{amount} is measured in milimeters,
and is 3.0 by default. This option should be used if the lines of
music stick out of the right margin.
The width of a tightly clipped systems can vary, due to notation
elements that stick into the left margin, such as bar numbers and
-instrument names. This option will shorten each line and move each
+instrument names. This option will shorten each line and move each
line to the right by the same amount.
@end quotation
-@node Many quotes of a large score
-@section Many quotes of a large score
+@node Alternate methods of mixing text and music
+@section Alternative methods of mixing text and music
+
+@menu
+* Many quotes from a large score::
+* Inserting LilyPond output into OpenOffice.org::
+* Inserting LilyPond output into other programs::
+@end menu
+
+@node Many quotes from a large score
+@subsection Many quotes from a large score
-If you need to quote many fragments of a large score, you can also use
-the clip systems feature, see @ref{Extracting fragments of notation}.
+If you need to quote many fragments from a large score, you can also use
+the clip systems feature, see @ruser{Extracting fragments of notation}.
@node Inserting LilyPond output into OpenOffice.org
-@section Inserting LilyPond output into OpenOffice.org
+@subsection Inserting LilyPond output into OpenOffice.org
@cindex OpenOffice.org
@node Inserting LilyPond output into other programs
-@section Inserting LilyPond output into other programs
+@subsection Inserting LilyPond output into other programs
To insert LilyPond output in other programs, use @code{lilypond}
instead of @code{lilypond-book}. Each example must be created
projects / lilypond.git / blobdiff