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
* 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}
\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
@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
@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.
@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{}
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 Sharing the table of contents
+@section Sharing the table of contents
+
+These functions already exist in the OrchestralLily package:
+
+@example
+@url{http://repo.or.cz/w/orchestrallily.git}
+@end example
+
+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
+
+@subsubheading Importing the ToC into LaTeX
+
+In LaTeX, the header should include:
+
+@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
+
+@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%
+@}%
+
+
+\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
+
+
@node Alternate methods of mixing text and music
@section Alternative methods of mixing text and music
projects / lilypond.git / blobdiff