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.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.13.36"
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node lilypond-book
This is a separate program from @command{lilypond} itself, and is run
on the command line; for more information, see @ref{Command-line
usage}. If you have MacOS 10.3 or 10.4 and you have trouble running
-@code{lilypond-book}, see @rgeneral{MacOS X}.
+@code{lilypond-book}, see @rweb{MacOS X}.
This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
documents.
@cindex @LaTeX{}, music in
@menu
-* An example of a musicological document::
-* Integrating music and text::
-* Music fragment options::
-* Invoking lilypond-book::
-* Filename extensions::
-* lilypond-book templates::
-* Alternate methods of mixing text and music::
+* An example of a musicological document::
+* Integrating music and text::
+* Music fragment options::
+* Invoking lilypond-book::
+* Filename extensions::
+* lilypond-book templates::
+* Sharing the table of contents::
+* Alternate methods of mixing text and music::
@end menu
\begin{lilypond}
\relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
+ c2 e2 \times 2/3 { f8 a b } a2 e4
}
\end{lilypond}
Options are put in brackets.
-\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
+\begin{lilypond}[fragment,quote,staffsize=26,verbatim]
c'4 f16
\end{lilypond}
\lilypondfile[quote,noindent]{screech-boink.ly}
-(If needed, replace screech-boink.ly by any .ly file you put in the same
-directory as this file.)
+(If needed, replace @file{screech@/-boink@/.ly} by any @file{@/.ly} file
+you put in the same directory as this file.)
\end{document}
@end verbatim
@subheading Processing
-Save the code above to a file called @file{lilybook.lytex}, then in a
+Save the code above to a file called @file{lilybook@/.lytex}, then in a
terminal run
@c keep space after @version{} so TeX doesn't choke
@lilypond
\relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
+ c2 e2 \times 2/3 { f8 a b } a2 e4
}
@end lilypond
Here we explain how to integrate LilyPond with various output formats.
@menu
-* LaTeX::
-* Texinfo::
-* HTML::
-* DocBook::
+* LaTeX::
+* Texinfo::
+* HTML::
+* DocBook::
@end menu
@node LaTeX
Music is entered using
@example
-\begin[options,go,here]@{lilypond@}
+\begin@{lilypond@}[options,go,here]
YOUR LILYPOND CODE
\end@{lilypond@}
@end example
Additionally, @code{\lilypondversion} displays the current version
of lilypond.
Running @command{lilypond-book} yields a file that can be further
-processed with @LaTeX{}.
+processed with @LaTeX{}.
We show some examples here. The @code{lilypond} environment
@example
-\begin[quote,fragment,staffsize=26]@{lilypond@}
+\begin@{lilypond@}[quote,fragment,staffsize=26]
c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example
@example
\def\betweenLilyPondSystem#1@{\endinput@}
-\begin[fragment]@{lilypond@}
+\begin@{lilypond@}[fragment]
c'1\( e'( c'~ \break c' d) e f\)
\end@{lilypond@}
@end example
@example
\def\betweenLilyPondSystem#1@{
- \ifnum##1<2\else\expandafter\endinput\fi
+ \ifnum#1<2\else\expandafter\endinput\fi
@}
@end example
of lilypond.
When @command{lilypond-book} is run on it, this results in a Texinfo
-file (with extension @file{.texi}) containing @code{@@image} tags for
+file (with extension @file{@/.texi}) containing @code{@@image} tags for
HTML, Info and printed output. @command{lilypond-book} generates images
of the music in EPS and PDF formats for use in the printed output, and
in PNG format for use in HTML and Info output.
\key c \minor c4 es g2
</lilypond>
@end example
+
@noindent
@command{lilypond-book} then produces an HTML file with appropriate image
tags for the music fragments:
Some music in <lilypond relative=2: a b c/> a line of text.
@end example
-
To include separate files, say
@example
<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
@end example
+For a list of options to use with the @code{lilypond} or
+@code{lilypondfile} tags, see @ref{Music fragment options}.
+
Additionally, @code{<lilypondversion/>} displays the current version
of lilypond.
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
+etc. So we don't use custom tags, only specify a convention based on the
standard DocBook elements.
@subheading Common conventions
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}.
+@command{lilypond-book} should have the extension @file{@/.lyxml}.
@subheading Including a LilyPond file
-This is the most simple case. We must use the @file{.ly} extension for
+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:
@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}
+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,
@item indent=@var{size}\@var{unit}
Set indentation of the first music system to @var{size}, using
-@var{unit} as units. @var{unit} is one of the following strings:
+@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, not the text layout.
If you would like to translate comments and variable names in verbatim
output but not in the sources, you may set the environment variable
@code{LYDOC_LOCALEDIR} to a directory path; the directory should
-contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
+contain a tree of @file{@/.mo} message catalogs with @code{lilypond-doc}
as a domain.
@item addversion
@end example
@noindent
-and we have this in our Texinfo document @file{test.texinfo}
+and we have this in our Texinfo document @file{test@/.texinfo}
@example
@@lilypondfile[texidoc]@{foo.ly@}
@end example
Most LilyPond test documents (in the @file{input} directory of the
-distribution) are small @file{.ly} files which look exactly like this.
+distribution) are small @file{@/.ly} files which look exactly like this.
For localization purpose, if the Texinfo document contains
@code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
@section Invoking @command{lilypond-book}
@command{lilypond-book} produces a file with one of the following
-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.
+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.
@subheading Format-specific instructions
To produce a PDF file through PDF@LaTeX{}, use
@example
-lilypond-book --pdf yourfile.pdftex
+lilypond-book --pdf yourfile.lytex
pdflatex yourfile.tex
@end example
@end example
@noindent
-The @file{.dvi} file created by this process will not contain
+The @file{@/.dvi} file created by this process will not contain
note heads. This is normal; if you follow the instructions, they
-will be included in the @file{.ps} and @file{.pdf} files.
+will be included in the @file{@/.ps} and @file{@/.pdf} files.
Running @command{dvips} may produce some warnings about fonts; these
are harmless and may be ignored. If you are running @command{latex} in
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, see
-@ref{Filename extensions}. Currently, @code{texi} is the same as
+@ref{Filename extensions}. Currently, @code{texi} is the same as
@code{texi-html}.
@c This complicated detail is not implemented, comment it out -jm
example.
@itemx --left-padding=@var{amount}
-Pad EPS boxes by this much. @var{amount} is measured in millimeters,
+Pad EPS boxes by this much. @var{amount} is measured in millimeters,
and is 3.0 by default. This option should be used if the lines of
music stick out of the right margin.
instrument names. This option will shorten each line and move each
line to the right by the same amount.
-
@item -P @var{command}
@itemx --process=@var{command}
Process LilyPond snippets using @var{command}. The default command is
@item --pdf
Create PDF files for use with PDF@LaTeX{}.
+@itemx --use-source-file-names
+Write snippet output files with the same base name as their source file.
+This option works only for snippets included with @code{lilypondfile}
+and only if directories implied by @code{--output-dir} and
+@code{--lily-output-dir} options are different.
+
@item -V
@itemx --verbose
Be verbose.
@item @strong{extension} @tab @strong{output format}
@item
@item @file{.html} @tab HTML
+@item @file{.htmly} @tab HTML
@item @file{.itely} @tab Texinfo
@item @file{.latex} @tab @LaTeX{}
@item @file{.lytex} @tab @LaTeX{}
@section lilypond-book templates
These templates are for use with @code{lilypond-book}. If you're not familiar
-with this program, please refer to
+with this program, please refer to
@ref{lilypond-book}.
@subsection LaTeX
\begin@{lilypond@}
\relative c'' @{
-a4 b c d
+ a4 b c d
@}
\end@{lilypond@}
-More LaTeX text.
+More LaTeX text, and options in square brackets.
-\begin@{lilypond@}
-\relative c'' @{
+\begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
d4 c b a
-@}
\end@{lilypond@}
\end@{document@}
@end example
is written in Texinfo.
@example
-\input texinfo
+\input texinfo @c -*-texinfo-*-
@@node Top
+@@top
Texinfo text
-@@lilypond[verbatim,fragment,ragged-right]
-a4 b c d
+@@lilypond
+\relative c' @{
+ a4 b c d
+@}
@@end lilypond
-More Texinfo text
+More Texinfo text, and options in brackets.
@@lilypond[verbatim,fragment,ragged-right]
d4 c b a
@end example
+@subsection html
+
+@example
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!-- header_tag -->
+<HTML>
+<body>
+
+<p>
+Documents for lilypond-book may freely mix music and text. For
+example,
+<lilypond>
+\relative c'' @{
+ a4 b c d
+@}
+</lilypond>
+</p>
+
+<p>
+Another bit of lilypond, this time with options:
+
+<lilypond fragment quote staffsize=26 verbatim>
+a4 b c d
+</lilypond>
+</p>
+
+</body>
+</html>
+
+
+@end example
+
@subsection xelatex
@verbatim
The fonts of snippets set with LilyPond will have to be set from
inside
-of the snippet. For this you should read the AU on how to use
+of the snippet. For this you should read the AU on how to use
lilypond-book.
\selectlanguage{ngerman}
@end verbatim
-@node Alternate methods of mixing text and music
-@section Alternative methods of mixing text and music
-
-This section shows methods to integrate text and music, different than
-the automated method with @command{lilypond-book}.
-
-@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
-@unnumberedsubsec Many quotes from a large score
+@node Sharing the table of contents
+@section Sharing the table of contents
-If you need to quote many fragments from a large score, you can also use
-the clip systems feature, see @ruser{Extracting fragments of music}.
+These functions already exist in the OrchestralLily package:
+@example
+@url{http://repo.or.cz/w/orchestrallily.git}
+@end example
-@node Inserting LilyPond output into OpenOffice.org
-@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
-
-@cindex OpenOffice.org
+For greater flexibility in text handling, some users prefer to
+export the table of contents from lilypond and read it into
+@LaTeX{}.
+
+@subsubheading Exporting the ToC from LilyPond
+
+This assumes that your score has multiple movements in the same lilypond
+output file.
+
+@smallexample
+#(define (oly:create-toc-file layout pages)
+ (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
+ (if (not (null? label-table))
+ (let* ((format-line (lambda (toc-item)
+ (let* ((label (car toc-item))
+ (text (caddr toc-item))
+ (label-page (and (list? label-table)
+ (assoc label label-table)))
+ (page (and label-page (cdr label-page))))
+ (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
+ (formatted-toc-items (map format-line (toc-items)))
+ (whole-string (string-join formatted-toc-items ",\n"))
+ (output-name (ly:parser-output-name parser))
+ (outfilename (format "~a.toc" output-name))
+ (outfile (open-output-file outfilename)))
+ (if (output-port? outfile)
+ (display whole-string outfile)
+ (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
+ (close-output-port outfile)))))
+
+\paper @{
+ #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
+@}
+@end smallexample
-LilyPond notation can be added to OpenOffice.org with
-@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
+@subsubheading Importing the ToC into LaTeX
+In LaTeX, the header should include:
-@node Inserting LilyPond output into other programs
-@unnumberedsubsec Inserting LilyPond output into other programs
+@c no, this doesn't require the smallexample, but since the other
+@c two blocks on this page use it, I figured I might as well
+@c user it here as well, for consistency. -gp
+@smallexample
+\usepackage@{pdfpages@}
+\includescore@{nameofthescore@}
+@end smallexample
-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.
+@noindent
+where @code{\includescore} is defined as:
+
+@smallexample
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \includescore@{PossibleExtension@}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Read in the TOC entries for a PDF file from the corresponding .toc file.
+% This requires some heave latex tweaking, since reading in things from a file
+% and inserting it into the arguments of a macro is not (easily) possible
+
+% Solution by Patrick Fimml on #latex on April 18, 2009:
+% \readfile@{filename@}@{\variable@}
+% reads in the contents of the file into \variable (undefined if file
+% doesn't exist)
+\newread\readfile@@f
+\def\readfile@@line#1@{%
+@{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
+\edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
+\ifeof\readfile@@f\else%
+\readfile@@line@{#1@}%
+\fi%
+@}
+\def\readfile#1#2@{%
+\openin\readfile@@f=#1 %
+\ifeof\readfile@@f%
+\typeout@{No TOC file #1 available!@}%
+\else%
+\gdef#2@{@}%
+\readfile@@line@{#2@}%
+\fi
+\closein\readfile@@f%
+@}%
-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
+\newcommand@{\includescore@}[1]@{
+\def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
+\let\oly@@addtotoc\undefined
+\readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
+\ifx\oly@@addtotoc\undefined
+\includepdf[pages=-]@{\oly@@fname@}
+\else
+\edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
+@{\oly@@fname@}@}\includeit
+\fi
@}
+@end smallexample
-@{ c1 @}
-@end example
-To produce a useful @file{EPS} file, use
+@node Alternate methods of mixing text and music
+@section Alternative methods of mixing text and music
-@example
-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+Other means of mixing text and music (without
+@command{lilypond-book}) are discussed in
+@ref{LilyPond output in other programs}.
-@file{PNG}:
-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
-@end example
projects / lilypond.git / blobdiff