X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=9d166bb43d631f64301dd762cb20ee7e30817a6e;hb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;hp=cfbae202ec7978384293bde034fb830758e1e5c3;hpb=4799b41d843d95ede966cf96bc8fa98f1c9c5f60;p=lilypond.git
diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index cfbae202ec..9d166bb43d 100644
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -7,7 +7,7 @@
version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.12.0"
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node LilyPond-book
@@ -24,10 +24,13 @@ program extracts snippets of music from your document, runs
substituted for the music. The line width and font size definitions for
the music are adjusted to match the layout of your document.
-This is a separate program from @command{lilypond} itself, and is run on
-the command-line; for more information, see @ref{Command-line usage}.
+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 @ref{Setup for MacOS X}.
-This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
+This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
+documents.
@cindex texinfo
@cindex latex
@@ -42,12 +45,12 @@ 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::
-* 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::
+* Alternate methods of mixing text and music::
@end menu
@@ -162,10 +165,10 @@ Larger examples can be put into a separate file, and introduced with
Here we explain how to integrate LilyPond with various output formats.
@menu
-* LaTeX::
-* Texinfo::
-* HTML::
-* DocBook::
+* LaTeX::
+* Texinfo::
+* HTML::
+* DocBook::
@end menu
@node LaTeX
@@ -202,8 +205,10 @@ or
\lilypond@{ YOUR LILYPOND CODE @}
@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
@@ -250,13 +255,13 @@ use the @code{line-width} music fragment option.
Each snippet will call the following macros if they have been defined by
the user:
-@itemize bullet
+@itemize @bullet
@item @code{\preLilyPondExample} called before the music,
@item @code{\postLilyPondExample} called after the music,
@item @code{\betweenLilyPondSystem[1]} is called between systems if
-@code{lilypond-book} has split the snippet into several postscript
+@code{lilypond-book} has split the snippet into several PostScript
files. It must be defined as taking one parameter and will be
passed the number of files already included in this snippet.
The default is to simply insert a @code{\linebreak}.
@@ -301,7 +306,7 @@ output.
In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
inclusion of other systems is terminated once the required number of
-systems are included. Since @code{\betweenLilypondSystem} is first
+systems are included. Since @code{\betweenLilyPondSystem} is first
called @emph{after} the first system, including only the first system
is trivial.
@@ -354,6 +359,7 @@ and then saying only how many systems you want before each fragment,
\begin@{lilypond@}...\end@{lilypond@}
@end example
+
@seealso
There are specific @command{lilypond-book} command line options and
other details to know when processing @LaTeX{} documents, see
@@ -389,6 +395,9 @@ or
@@lilypondfile[options,go,here]@{@var{filename}@}
@end example
+Additionally, @code{@@lilypondversion} displays the current version
+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
HTML, Info and printed output. @command{lilypond-book} generates images
@@ -435,7 +444,6 @@ Music is entered using
\key c \minor c4 es g2
@end example
-
@noindent
@command{lilypond-book} then produces an HTML file with appropriate image
tags for the music fragments:
@@ -451,12 +459,17 @@ are separated by a colon from the music, for example
Some music in a line of text.
@end example
+
To include separate files, say
@example
@var{filename}
@end example
+Additionally, @code{} displays the current version
+of lilypond.
+
+
@cindex titling in HTML
@cindex preview image
@cindex thumbnail
@@ -493,8 +506,8 @@ the following structure:
@end example
-Note that you can use mediaobject or inlinemediaobject as the outermost
-element as you wish.
+Note that you can use @code{mediaobject} or @code{inlinemediaobject}
+as the outermost element as you wish.
@subheading Including LilyPond code
@@ -508,7 +521,7 @@ structure:
\context Staff \with @{
\remove Time_signature_engraver
- \remove Clef_engraver@}
+ \remove Clef_engraver@}
@{ c4( fis) @}
@@ -556,10 +569,10 @@ 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.
-@c does this option still exist in lilypond? -jm
-@item packed
-Produce lines with packed spacing, i.e., @code{packed = ##t} is added
-to the LilyPond snippet.
+@item noragged-right
+For single-line snippets, allow the staff length to be stretched to
+equal that of the line width, i.e., @code{ragged-right = ##f} is
+added to the LilyPond snippet.
@item line-width
@itemx line-width=@var{size}\@var{unit}
@@ -576,7 +589,7 @@ guess a default for @code{lilypond} environments which don't use the
@code{ragged-right} option.
@item notime
-Do not print the time signature, and turns off the timing (key signature,
+Do not print the time signature, and turns off the timing (time signature,
bar lines) in the score.
@item fragment
@@ -618,6 +631,10 @@ Set the amount by which the @code{quote} option indents a music snippet.
Use relative octave mode. By default, notes are specified relative to
middle@tie{}C. The optional integer argument specifies the octave of
the starting note, where the default @code{1} is middle C.
+@code{relative} option only works when @code{fragment} option is set,
+so @code{fragment} is automatically implied by @code{relative},
+regardless of the presence of any @code{(no)fragment} option in the
+source.
@end table
LilyPond also uses @command{lilypond-book} to produce its own
@@ -638,7 +655,7 @@ source file contain a comment containing @samp{begin verbatim} (without
quotes), quoting the source in the verbatim block will start after the
last occurrence of such a comment; similarly, quoting the source verbatim
will stop just before the first occurrence of a comment containing
-@samp{end verbatim}, it there is any. In the following source file
+@samp{end verbatim}, if there is any. In the following source file
example, the music will be interpreted in relative mode, but the
verbatim quote will not show the @code{relative} block, i.e.
@@ -657,6 +674,13 @@ will be printed with a verbatim block like
f2 e
@end example
+@noindent
+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}
+as a domain.
+
@item addversion
(Only for Texinfo output.) Prepend line @code{\version
@@w@{"@@version@{@}"@}} to @code{verbatim} output.
@@ -689,13 +713,20 @@ and we have this in our Texinfo document @file{test.texinfo}
the following command line gives the expected result
@example
-lilypond-book --process="lilypond --format=tex --tex \
- --header=texidoc test.texinfo
+lilypond-book --pdf --process="lilypond \
+ -dbackend=eps --header=texidoc" test.texinfo
@end example
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
+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
@@ -703,6 +734,23 @@ the music snippet (and the optional verbatim block implied by
useful if you want to @code{quote} the music snippet but not the
@code{texidoc} documentation block.
+@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},
+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.
+The same remark about @code{texidoc} processing with localized
+languages also applies to @code{doctitle}.
+
+@item nogettext
+(Only for Texinfo output.) Do not translate comments and variable
+names in the snippet quoted verbatim.
+
@item printfilename
If a LilyPond input file is included with @code{\lilypondfile}, print
the file name right before the music snippet. For HTML output, this
@@ -711,7 +759,7 @@ directory part of the file path is stripped.
@item fontload
This option includes fonts in all of the generated EPS-files for this
-snippet. This should be used if the snippet uses any font that LaTeX
+snippet. This should be used if the snippet uses any font that @LaTeX{}
cannot find on its own.
@end table
@@ -867,20 +915,20 @@ 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.
-The width of a tightly clipped systems can vary, due to notation
+The width of a tightly clipped system can vary, due to notation
elements that stick into the left margin, such as bar numbers and
-instrument names. This option will shorten each line and move each
+instrument names. This option will shorten each line and move each
line to the right by the same amount.
-@item -P @var{process}
+@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.
@item --pdf
-Create PDF files for use with PDFLaTeX.
+Create PDF files for use with PDF@LaTeX{}.
@item -V
@itemx --verbose
@@ -930,7 +978,7 @@ 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
-@command{lilypond-book} running, otherwise the will exit with an error
+@command{lilypond-book} running, otherwise it will exit with an error
message like @qq{Output would overwrite input file}.
@@ -941,20 +989,20 @@ 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::
+* 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
-@subsection Many quotes from a large score
+@unnumberedsubsec Many quotes from a large score
If you need to quote many fragments from a large score, you can also use
-the clip systems feature, see @ruser{Extracting fragments of notation}.
+the clip systems feature, see @ruser{Extracting fragments of music}.
@node Inserting LilyPond output into OpenOffice.org
-@subsection Inserting LilyPond output into OpenOffice.org
+@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
@cindex OpenOffice.org
@@ -963,7 +1011,7 @@ LilyPond notation can be added to OpenOffice.org with
@node Inserting LilyPond output into other programs
-@subsection Inserting LilyPond output into other programs
+@unnumberedsubsec Inserting LilyPond output into other programs
To insert LilyPond output in other programs, use @code{lilypond}
instead of @code{lilypond-book}. Each example must be created
@@ -987,9 +1035,12 @@ the following options
@{ c1 @}
@end example
-To produce a useful EPS file, use
+To produce a useful @file{EPS} file, use
@example
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+
+@file{PNG}:
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
@end example