-c -*- coding: utf-8; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-program.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
@ignore
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 output or PNG images, and those
-are included into a La@TeX{} or HTML document.
+are included into a @LaTeX{} or HTML document.
@command{lilypond-book} provides a way to automate this process: This
program extracts snippets of music from your document, runs
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{}, HTML or Texinfo documents.
+This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
@menu
* An example of a musicological document::
* Integrating LaTeX and music::
* Integrating Texinfo and music::
* Integrating HTML and music::
+* Integrating DocBook and music::
* 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::
@end menu
@section An example of a musicological document
@cindex musicology
-@cindex La@TeX{}, music in
+@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.
However, there is an automated procedure to reduce the amount of work
-involved in HTML, La@TeX{}, and Texinfo documents.
+involved in HTML, @LaTeX{}, Texinfo and DocBook 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
+example for use with @LaTeX{}. The example also contains explanatory
text, so we will not comment on it further.
@quotation
ps2pdf lilybook.ps
@end example
+If you are running latex in twocolumn mode, remember to add
+@code{-t landscape} to the dvips options.
+
Running @command{lilypond-book} and @command{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
Running dvips will produce many warnings about fonts. They are not
harmful; please ignore them.
-Finally the result of the La@TeX{} example shown above.@footnote{This
+Finally the result of the @LaTeX{} example shown above.@footnote{This
tutorial is processed with Texinfo, so the example gives slightly
different results in layout.} This finishes the tutorial section.
@cindex texinfo
@cindex latex
@cindex texinfo
-@findex texi
+@cindex texi
@cindex html
+@cindex docbook
@cindex documents, adding music to
@node Integrating LaTeX and music
-@section Integrating La@TeX{} and music
+@section Integrating @LaTeX{} and music
-La@TeX{} is the de-facto standard for publishing layouts in the exact
+@LaTeX{} is the de-facto standard for publishing layouts in the exact
sciences. It is built on top of the @TeX{} typesetting engine,
providing the best typography available anywhere.
See
@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
-@emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
-to use La@TeX{}.
+@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
+to use @LaTeX{}.
Music is entered using
@end example
Running @command{lilypond-book} yields a file that can be further
-processed with La@TeX{}.
+processed with @LaTeX{}.
We show some examples here. The lilypond environment
The default line width of the music will be adjusted by examining the
commands in the document preamble, the part of the document before
@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
+these to @LaTeX{} to find out how wide the text is. The line width for
the music fragments is then adjusted to the text width. Note that this
heuristic algorithm can fail easily; in such cases it is necessary to
use the @code{line-width} music fragment option.
@cindex titling and lilypond-book
-@findex \header in La@TeX{} documents
+@cindex \header in @LaTeX{} documents
Each snippet will call the following macros if they have been defined by
the user:
@cindex dvips
@cindex invoking dvips
-For printing the La@TeX{} document you need a DVI to PostScript
+For printing the @LaTeX{} document you need a DVI to PostScript
translator like @command{dvips}. To use @command{dvips} to produce
a PostScript file, add the following options to the @command{dvips}
command line:
will produce some warnings about fonts; these are harmless and may
be ignored.
+If you are running latex in twocolumn mode, remember to add
+@code{-t landscape} to the dvips options.
+
@cindex international characters
@cindex latin1
breaking the staff and suppressing inclusion of the rest of the lilypond
output.
-In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
+In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
inclusion of other systems is terminated once the required number of
systems are included. Since @code{\betweenLilypondSystem} is first
called @b{after} the first system, including only the first system
@end example
If a greater number of systems is requested, a TeX conditional must be
-used before the @code{\endinput}. In this example, replace "2" by
-the numer of systems you want in the output,
+used before the @code{\endinput}. In this example, replace @q{2} by
+the number of systems you want in the output,
@example
\def\betweenLilyPondSystem#1@{
@end example
Remember that the definition of @code{\betweenLilyPondSystem} is
-effective until @TeX{} quits the current group (such as the La@TeX{}
+effective until @TeX{} quits the current group (such as the @LaTeX{}
environment) or is overridden by another definition (which is, in
most cases, for the rest of the document). To reset your
definition, write
@lilypond[fragment,staffsize=11]{<c' e' g'>}
-Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
+Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
in-line image. It always gets a paragraph of its own.
When using the Texinfo output format, @command{lilypond-book} also
@cindex preview image
@cindex thumbnail
+@node Integrating DocBook and music
+@section Integrating DocBook and music
+
+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
+
+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
+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
+
+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
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="music1.ly" role="printfilename" />
+ </imageobject>
+</mediaobject>
+@end example
+
+Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
+
+@unnumberedsubsec 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:
+
+@example
+<inlinemediaobject>
+ <textobject>
+ <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
+\context Staff \with @{
+ \remove Time_signature_engraver
+ \remove Clef_engraver@}
+ @{ c4( fis) @}
+ </programlisting>
+ </textobject>
+</inlinemediaobject>
+@end example
+
+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
+
+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
-In the following, a ``LilyPond command'' refers to any command described
+In the following, a @q{LilyPond command} refers to any command described
in the previous sections which is handled by @command{lilypond-book} to
produce a music snippet. For simplicity, LilyPond commands are only
-shown in La@TeX{} syntax.
+shown in @LaTeX{} syntax.
Note that the option string is parsed from left to right; if an option
occurs multiple times, the last one is taken.
@item quote
Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
-the output into a quotation block. The value `0.4@dmn{in}' can be
+the output into a quotation block. The value @q{0.4@dmn{in}} can be
controlled with the @code{exampleindent} option.
@item exampleindent
@section Invoking @command{lilypond-book}
@command{lilypond-book} produces a file with one of the following
-extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
-output format. Both @file{.tex} and @file{.texi} files need further
+extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
+output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
processing.
@command{lilypond-book} can also create a PSFONTS file, which is required
-by @command{dvips} to produce Postscript and PDF files. You can call
-this file whatever you want as long as you refer to the same file when
-you call @command{dvips}.
+by @command{dvips} to produce Postscript and PDF files.
To produce PDF output from the lilypond-book file (here called
-@code{yourfile.lytex}), you should do
+@code{yourfile.lytex}) via LaTeX, you should do
@example
lilypond-book --psfonts yourfile.lytex
noteheads. This is normal; if you follow the instructions, they
will be included in the @file{.ps} and @file{.pdf} files.
+To produce a PDF file through PDF(La)TeX, use
+
+@example
+lilypond-book --pdf yourfile.pdftex
+pdflatex yourfile.tex
+@end example
+
+
To produce a Texinfo document (in any output format), follow the normal
procedures for Texinfo (this is, either call @command{texi2dvi} or
@command{makeinfo}, depending on the output format you want to
@table @code
@item -f @var{format}
@itemx --format=@var{format}
-Specify the document type to process: @code{html}, @code{latex}, or
-@code{texi} (the default). If this option is missing,
+Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
@command{lilypond-book} tries to detect the format automatically.
The @code{texi} document type produces a Texinfo file with music
...
@end example
+@itemx --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
+line to the right by the same amount.
+
+
@item -P @var{process}
@itemx --process=@var{command}
Process LilyPond snippets using @var{command}. The default command is
@refbugs
The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
-La@TeX{} commands that change margins and line widths after the preamble
+@LaTeX{} commands that change margins and line widths after the preamble
are ignored.
Only the first @code{\score} of a LilyPond block is processed.
@item
@item @file{.html} @tab HTML
@item @file{.itely} @tab Texinfo
-@item @file{.latex} @tab La@TeX{}
-@item @file{.lytex} @tab La@TeX{}
+@item @file{.latex} @tab @LaTeX{}
+@item @file{.lytex} @tab @LaTeX{}
+@item @file{.lyxml} @tab DocBook
@item @file{.tely} @tab Texinfo
-@item @file{.tex} @tab La@TeX{}
+@item @file{.tex} @tab @LaTeX{}
@item @file{.texi} @tab Texinfo
@item @file{.texinfo} @tab Texinfo
@item @file{.xml} @tab HTML
@end multitable
@end quotation
+
+
+@node Many quotes of a large score
+@section Many quotes of a large score
+
+If you need to quote many fragments of 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
+
+@cindex OpenOffice.org
+
+LilyPond notation can be added to OpenOffice.org with
+@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
+
+
+@node Inserting LilyPond output into other programs
+@section 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
+individually and added to the document; consult the documentation for
+that program. Most programs will be able to insert lilypond output in
+@file{PNG}, @file{EPS}, or @file{PDF} formats.
+
+To reduce the white space around your lilypond score, use
+the following options
+
+@example
+\paper@{
+ indent=0\mm
+ line-width=120\mm
+ oddFooterMarkup=##f
+ oddHeaderMarkup=##f
+ bookTitleMarkup = ##f
+ scoreTitleMarkup = ##f
+@}
+
+@{ c1 @}
+@end example
+
+To produce a useful @file{eps} file, use
+
+@example
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+@end example
+
projects / lilypond.git / blobdiff