Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.14.0"
@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
\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
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
+remedy this, use the @option{--output=@var{dir}} option. It will create
the files in a separate subdirectory @file{dir}.
Finally the result of the @LaTeX{} example shown above.@footnote{This
@lilypondfile[quote,noindent]{screech-boink.ly}
+If a @code{tagline} is required, either default or custom, then the
+entire snippet must be enclosed in a @code{\book @{ @}} construct.
+
+@lilypond[papersize=a8,verbatim]
+\book{
+ \header{
+ title = "A scale in LilyPond"
+ }
+
+ \relative c' {
+ c d e f g a b c
+ }
+}
+@end lilypond
@page
@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
to use @LaTeX{}.
-Music is entered using
+@code{lilypond-book} provides the following commands and environments to include
+music in @LaTeX{} files:
+
+@itemize
+
+@item
+the @code{\lilypond@{...@}} command, where you can directly enter short
+lilypond code
+
+@item
+the @code{\begin@{lilypond@}...\end@{lilypond@}} environment, where you
+can directly enter longer lilypond code
+
+@item
+the @code{\lilypondfile@{...@}} command to insert a lilypond file
+
+@item
+the @code{\musicxmlfile@{...@}} command to insert a MusicXML file, which
+will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands:
@example
\begin@{lilypond@}[options,go,here]
YOUR LILYPOND CODE
\end@{lilypond@}
-@end example
-@noindent
-or
+\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@example
\lilypondfile[options,go,here]@{@var{filename}@}
+
+\musicxmlfile[options,go,here]@{@var{filename}@}
@end example
-@noindent
-or
-@example
-\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
+@noindent
Additionally, @code{\lilypondversion} displays the current version
of lilypond.
@example
\def\betweenLilyPondSystem#1@{
- \ifnum##1<2\else\expandafter\endinput\fi
+ \ifnum#1<2\else\expandafter\endinput\fi
@}
@end example
example of a Texinfo document is this manual. The HTML, PDF, and Info
versions of the manual are made from the Texinfo document.
-In the input file, music is specified with
+@code{lilypond-book} provides the following commands and environments to include
+music into Texinfo files:
+
+@itemize
+
+@item
+the @code{@@lilypond@{...@}} command, where you can directly enter short
+lilypond code
+
+@item
+the @code{@@lilypond...@@end lilypond} environment, where you can directly
+enter longer lilypond code
+
+@item
+the @code{@@lilypondfile@{...@}} command to insert a lilypond file
+
+@item
+the @code{@@musicxmlfile@{...@}} command to insert a MusicXML file, which
+will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands
@example
@@lilypond[options,go,here]
YOUR LILYPOND CODE
@@end lilypond
-@end example
-@noindent
-or
-
-@example
@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
-@noindent
-or
-
-@example
@@lilypondfile[options,go,here]@{@var{filename}@}
+
+@@musicxmlfile[options,go,here]@{@var{filename}@}
@end example
Additionally, @code{@@lilypondversion} displays the current version
@node HTML
@subsection HTML
-Music is entered using
+@code{lilypond-book} provides the following commands and environments to include
+music in HTML files:
+
+@itemize
+
+@item
+the @code{<lilypond .... />} command, where you can directly enter short lilypond code
+
+@item
+the @code{<lilyond>...</lilypond>} environment, where you can directly enter longer
+lilypond code
+@item
+the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file
+
+@item
+the @code{<musicxmlfile>...</musicxmlfile>} command to insert a MusicXML file, which
+will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands:
+
+\begin@{lilypond@}[options,go,here]
+ YOUR LILYPOND CODE
+\end@{lilypond@}
+
+\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+
+\lilypondfile[options,go,here]@{@var{filename}@}
+
+\musicxmlfile[options,go,here]@{@var{filename}@}
+@example
+<lilypond options go here>
+ YOUR LILYPOND CODE
+</lilypond>
+
+<lilypond options go here: YOUR LILYPOND CODE />
+
+<lilypondfile options go here>@var{filename}</lilypondfile>
+
+<musicxmlfile options go here>@var{filename}</musicxmlfile>
+@end example
+
+For example, you can write
@example
<lilypond fragment relative=2>
\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
+@code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but simply
+references a MusicXML file rather than a LilyPond file.
+
+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.
@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{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.
+@code{ragged-right = ##t} is added to the LilyPond snippet. Single-line
+snippets will always be typeset by default as ragged-right, unless
+@code{noragged-right} is explicitly given.
@item noragged-right
For single-line snippets, allow the staff length to be stretched to
guess a default for @code{lilypond} environments which don't use the
@code{ragged-right} option.
+@item papersize=@var{string}
+Where @var{string} is a paper size defined in @file{scm/paper.scm} i.e.
+@code{a5}, @code{quarto}, @code{11x17} etc.
+
+Values not defined in @file{scm/paper.scm} will be ignored, a warning
+will be posted and the snippet will be printed using the default
+@code{a4} size.
+
@item notime
Do not print the time signature, and turns off the timing (time signature,
bar lines) in the score.
@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.
+contents as a documentation block right before the music snippet (but
+outside the @code{example} environment generated by a @code{quote}
+option).
-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}.
-
-@item lilyquote
-(Only for Texinfo output.) This option is similar to quote, but only
-the music snippet (and the optional verbatim block implied by
-@code{verbatim} option) is put into a quotation block. This option is
-useful if you want to @code{quote} the music snippet but not the
-@code{texidoc} documentation block.
+@file{foo.texidoc@var{LANG}} will be included instead of
+@file{foo.texidoc}.
@item doctitle
(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.
Running @command{dvips} may produce some warnings about fonts; these
are harmless and may be ignored. If you are running @command{latex} in
-twocolumn mode, remember to add @code{-t landscape} to the
+twocolumn mode, remember to add @option{-t landscape} to the
@command{dvips} options.
@subsubheading Texinfo
for already compiled snippets in the include path, and does not write
them back to the output directory, so in some cases it is necessary to
invoke further processing commands such as @command{makeinfo} or
-@command{latex} with the same @code{-I @var{dir}} options.
+@command{latex} with the same @option{-I @var{dir}} options.
@item -o @var{dir}
@itemx --output=@var{dir}
LilyPond Info documentation without images.
@itemx --lily-output-dir=@var{dir}
-Write lily-XXX files to directory @var{dir}, link into @code{--output}
+Write lily-XXX files to directory @var{dir}, link into @option{--output}
directory. Use this option to save building time for documents in
different directories which share a lot of identical snippets.
@item -P @var{command}
@itemx --process=@var{command}
Process LilyPond snippets using @var{command}. The default command is
-@code{lilypond}. @code{lilypond-book} will not @code{--filter} and
-@code{--process} at the same time.
+@code{lilypond}. @code{lilypond-book} will not @option{--filter} and
+@option{--process} at the same time.
@item --pdf
Create PDF files for use with PDF@LaTeX{}.
+@item --redirect-lilypond-output
+By default, output is displayed on the terminal. This option redirects
+all output to log files in the same directory as the source files.
+
@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.
+and only if directories implied by @option{--output-dir} and
+@option{--lily-output-dir} options are different.
@item -V
@itemx --verbose
If you use the same filename extension for the input file than the
extension @command{lilypond-book} uses for the output file, and if the
input file is in the same directory as @command{lilypond-book} working
-directory, you must use @code{--output} option to make
+directory, you must use @option{--output} option to make
@command{lilypond-book} running, otherwise it will exit with an error
message like @qq{Output would overwrite input file}.
@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