X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Flilypond-book.itely;h=d41d70ed07702db998566c549032bf4d8641cd9c;hb=4e71964c781e1d86d53d50f746e67575cfe0c358;hp=4e2aa4c5cdda3065cf632c015df77ea221fbdf28;hpb=2cb02ca327fbbde256ae6712d1e968b9da5d492e;p=lilypond.git

diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely
index 4e2aa4c5cd..d41d70ed07 100644
--- a/Documentation/usage/lilypond-book.itely
+++ b/Documentation/usage/lilypond-book.itely
@@ -4,10 +4,11 @@
     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
@@ -51,6 +52,7 @@ documents.
 * Invoking lilypond-book::
 * Filename extensions::
 * lilypond-book templates::
+* Sharing the table of contents::
 * Alternate methods of mixing text and music::
 @end menu
 
@@ -83,13 +85,13 @@ For example,
 
 \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}
 
@@ -98,8 +100,8 @@ Larger examples can be put into a separate file, and introduced with
 
 \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
@@ -142,7 +144,7 @@ For example,
 
 @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
 
@@ -187,7 +189,7 @@ to use @LaTeX{}.
 Music is entered using
 
 @example
-\begin[options,go,here]@{lilypond@}
+\begin@{lilypond@}[options,go,here]
   YOUR LILYPOND CODE
 \end@{lilypond@}
 @end example
@@ -214,7 +216,7 @@ 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
@@ -314,7 +316,7 @@ is trivial.
 @example
 \def\betweenLilyPondSystem#1@{\endinput@}
 
-\begin[fragment]@{lilypond@}
+\begin@{lilypond@}[fragment]
   c'1\( e'( c'~ \break c' d) e f\)
 \end@{lilypond@}
 @end example
@@ -325,7 +327,7 @@ the number of systems you want in the output.
 
 @example
 \def\betweenLilyPondSystem#1@{
-    \ifnum##1<2\else\expandafter\endinput\fi
+    \ifnum#1<2\else\expandafter\endinput\fi
 @}
 @end example
 
@@ -452,6 +454,7 @@ Music is entered using
 \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:
@@ -467,13 +470,15 @@ are separated by a colon from the music, for example
 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.
 
@@ -487,7 +492,7 @@ 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
@@ -617,7 +622,7 @@ Since this is the default, @code{nofragment} is redundant normally.
 
 @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.
 
@@ -696,12 +701,12 @@ as a domain.
 @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 @{
@@ -729,11 +734,11 @@ Most LilyPond test documents (in the @file{input} directory of the
 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
@@ -746,9 +751,9 @@ useful if you want to @code{quote} the music snippet but not the
 (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.
@@ -846,7 +851,7 @@ See the documentation of Texinfo for further details.
 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
@@ -914,7 +919,7 @@ useful if your document is processed with @command{xelatex}, for
 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.
 
@@ -970,6 +975,7 @@ selects the output format based on the input filename's extension.
 @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{}
@@ -1010,16 +1016,14 @@ Normal LaTeX text.
 
 \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
@@ -1030,16 +1034,19 @@ You can include LilyPond fragments in Texinfo; in fact, this entire manual
 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
@@ -1049,6 +1056,38 @@ 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
@@ -1092,7 +1131,7 @@ and so on.
 
 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}
@@ -1104,6 +1143,112 @@ unterst__tzt werden.
 @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