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
@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
\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
@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.
@item texidoc
(Only for Texinfo output.) If @command{lilypond} is called with the
@option{--header=@/texidoc} option, and the file to be processed is
-called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
+called @file{foo.ly}, it creates a file @file{foo.texidoc} if there
is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
option makes @command{lilypond-book} include such files, adding its
contents as a documentation block right before the music snippet.
-Assuming the file @file{foo@/.ly} contains
+Assuming the file @file{foo.ly} contains
@example
\header @{
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
+@code{@@documentlanguage @var{LANG}} and @file{foo.ly} header
contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
is called with @option{--header=@/texidoc@var{LANG}}, then
-@file{foo@/.texidoc@var{LANG}} will be included instead of
-@file{foo@/.texidoc}.
+@file{foo.texidoc@var{LANG}} will be included instead of
+@file{foo.texidoc}.
@item lilyquote
(Only for Texinfo output.) This option is similar to quote, but only
(Only for Texinfo output.) This option works similarly to
@code{texidoc} option: if @command{lilypond} is called with the
@option{--header=@/doctitle} option, and the file to be processed is
-called @file{foo@/.ly} and contains a @code{doctitle} field in the
-@code{\header}, it creates a file @file{foo@/.doctitle}. When
-@code{doctitle} option is used, the contents of @file{foo@/.doctitle},
+called @file{foo.ly} and contains a @code{doctitle} field in the
+@code{\header}, it creates a file @file{foo.doctitle}. When
+@code{doctitle} option is used, the contents of @file{foo.doctitle},
which should be a single line of @var{text}, is inserted in the
Texinfo document as @code{@@lydoctitle @var{text}}.
@code{@@lydoctitle} should be a macro defined in the Texinfo document.
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
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
-@rprogram{lilypond-book}.
+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