-@c -*- coding: latin-1; mode: texinfo; -*-
+c -*- coding: utf-8; mode: texinfo; -*-
@ignore
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 La@TeX{}, HTML, Texinfo or DocBook documents.
@menu
-* An example of a musicological document::
-* Integrating LaTeX and music::
-* Integrating Texinfo and music::
-* Integrating HTML and music::
-* Music fragment options::
-* Invoking lilypond-book::
-* Filename extensions::
+* 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
@cindex La@TeX{}, 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, La@TeX{}, 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
@quotation
@verbatim
\documentclass[a4paper]{article}
+
\begin{document}
Documents for @command{lilypond-book} may freely mix music and text.
@example
cd input/tutorial
mkdir -p out/
-lilypond-book --output=out --psfonts=psfonts lilybook.tex
+lilypond-book --output=out --psfonts lilybook.tex
@emph{lilypond-book (GNU LilyPond) 2.6.0}
@emph{Reading lilybook.tex...}
@emph{..lots of stuff deleted..}
To convert the file into a PDF document, run the following commands
@example
-dvips -Ppdf -h psfonts lilybook
+dvips -o -Ppdf -h lilybook.psfonts lilybook
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
the files in a separate subdirectory @file{dir}.
+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
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
-@cindex @code{texi}
+@funindex texi
@cindex html
+@cindex docbook
@cindex documents, adding music to
@code{\lilypond@{@}}, so this command is only useful with the
@code{fragment} option.
-The default linewidth of the music will be adjusted by examining the
+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
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{linewidth} music fragment option.
+use the @code{line-width} music fragment option.
@cindex titling and lilypond-book
-@cindex @code{\header} in La@TeX{} documents
+@funindex \header in La@TeX{} documents
Each snippet will call the following macros if they have been defined by
the user:
@code{\betweenLilyPondSystem[1]} is called between systems if
@code{lilypond-book} has split the snippet into several postscript
files. It must be defined as taking one parameter and will be
-passed the number of files already included in this snippet.
+passed the number of files already included in this snippet.
+The default is to simply insert a @code{\linebreak}.
+
+@ignore
+Broken stuff. :(
+
@cindex Latex, feta symbols
@cindex fetachar
The font symbol names are defined in the file feta20.tex; to find
the location of this file, use the command
-@ignore
-** AARGH. the titledefs and feta20.tex files will not be found
- now that the lilypond-profile isn't used anymore!!! /Mats
-@end ignore
-
@example
kpsewhich feta20.tex
@end example
+@end ignore
+
@cindex outline fonts
@cindex type1 fonts
@cindex dvips
command line:
@example
--Ppdf -h psfonts
+-o -Ppdf -h @var{file}.psfonts
@end example
@noindent
-where the @command{psfonts} file is obtained from
-@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).
+where the @var{file}@command{psfonts} file is obtained from
+@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
+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
+Sometimes it is useful to display music elements (such as ties and slurs)
+as if they continued after the end of the fragment. This can be done by
+breaking the staff and suppressing inclusion of the rest of the lilypond
+output.
+
+In La@TeX{}, 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
+is trivial.
+
+@example
+\def\betweenLilyPondSystem#1@{\endinput@}
+
+\begin[fragment]@{lilypond@}
+ c'1\( e'( c'~ \break c' d) e f\)
+\end@{lilypond@}
+@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,
+
+@example
+\def\betweenLilyPondSystem#1@{
+ \ifnum##1<2\else\endinput\fi
+@}
+@end example
+
+Remember that the definition of @code{\betweenLilyPondSystem} is
+effective until @TeX{} quits the current group (such as the La@TeX{}
+environment) or is overridden by another definition (which is, in
+most cases, for the rest of the document). To reset your
+definition, write
+
+@example
+\let\betweenLilyPondSystem\undefined
+@end example
+
+@noindent
+in your LaTeX source.
+
+This may be simplified by defining a @TeX{} macro
+
+@example
+\def\onlyFirstNSystems#1@{
+ \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
+@}
+@end example
+
+@noindent
+and then saying only how many systems you want before each fragment,
+
+@example
+\onlyFirstNSystems@{3@}
+\begin@{lilypond@}...\end@{lilypond@}
+\onlyFirstNSystems@{1@}
+\begin@{lilypond@}...\end@{lilypond@}
+@end example
+
@node Integrating Texinfo and music
@section Integrating Texinfo and music
@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
@item staffsize=@var{ht}
Set staff size to @var{ht}, which is measured in points.
-@item raggedright
-Produce ragged-right lines with natural spacing (i.e., @code{raggedright
+@item ragged-right
+Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
= ##t} is added to the LilyPond snippet). This is the default for the
-@code{\lilypond@{@}} command if no @code{linewidth} option is present.
+@code{\lilypond@{@}} command if no @code{line-width} option is present.
It is also the default for the @code{lilypond} environment if the
@code{fragment} option is set, and no line width is explicitly
specified.
Produce lines with packed spacing (i.e., @code{packed = ##t} is added
to the LilyPond snippet).
-@item linewidth
-@itemx linewidth=@var{size}\@var{unit}
+@item line-width
+@itemx line-width=@var{size}\@var{unit}
Set line width to @var{size}, using @var{unit} as units. @var{unit} is
one of the following strings: @code{cm}, @code{mm}, @code{in}, or
@code{pt}. This option affects LilyPond output (this is, the staff
If used without an argument, set line width to a default value (as
computed with a heuristic algorithm).
-If no @code{linewidth} option is given, @command{lilypond-book} tries to
+If no @code{line-width} option is given, @command{lilypond-book} tries to
guess a default for @code{lilypond} environments which don't use the
-@code{raggedright} option.
+@code{ragged-right} option.
@item notime
-Do not print the time signature.
+Do not print the time signature, and turns off the timing (key signature,
+bar lines) in the score.
@item fragment
Make @command{lilypond-book} add some boilerplate code so that you can
@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=tempfonts.ps yourfile.lytex
+lilypond-book --psfonts yourfile.lytex
latex yourfile.tex
-dvips -h tempfonts.ps -Ppdf yourfile.dvi
+dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
ps2pdf yourfile.ps
@end example
+The @file{.dvi} file created by this process will not contain
+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
@code{lilypond}. @code{lilypond-book} will not --filter and --process
at the same time.
-@itemx --psfonts=FILE
-extract all PostScript fonts into FILE for LaTeX. This is necessary
-for @command{dvips -h FILE}.
+@itemx --psfonts
+extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
+This is necessary for @command{dvips -h @var{file}.psfonts}.
@item -V
@itemx --verbose
Only the first @code{\score} of a LilyPond block is processed.
-@c CHECKME--FIXME
-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}.
-
@node Filename extensions
@section Filename extensions
@item @file{.itely} @tab Texinfo
@item @file{.latex} @tab La@TeX{}
@item @file{.lytex} @tab La@TeX{}
+@item @file{.lyxml} @tab DocBook
@item @file{.tely} @tab Texinfo
@item @file{.tex} @tab La@TeX{}
@item @file{.texi} @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 @ref{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 -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+@end example
+
projects / lilypond.git / blobdiff