X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=7fc46d3f1500d25410de85ab8abf1a3f37eea469;hb=5c14a087ca6cbd665fd631452b7b1283ba0387c3;hp=6196811450f89f01f214d47fa620cd06ef2d0b39;hpb=d81263b12c659e40221a2fd1ef6de67c2854d64f;p=lilypond.git diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index 6196811450..7fc46d3f15 100644 --- a/Documentation/user/lilypond-book.itely +++ b/Documentation/user/lilypond-book.itely @@ -7,6 +7,7 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.61" @c Note: keep this node named so that `info lilypond-book' brings you here. @node LilyPond-book @@ -23,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 @@ -255,7 +259,7 @@ the user: @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}. @@ -295,7 +299,7 @@ kpsewhich feta20.tex Sometimes it is useful to display music elements (such as ties and slurs) as if they continued after the end of the fragment. This can be done by -breaking the staff and suppressing inclusion of the rest of the lilypond +breaking the staff and suppressing inclusion of the rest of the LilyPond output. In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that @@ -492,8 +496,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 @@ -555,6 +559,11 @@ 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. +@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. + @c does this option still exist in lilypond? -jm @item packed Produce lines with packed spacing, i.e., @code{packed = ##t} is added @@ -575,7 +584,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 @@ -617,6 +626,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 @@ -635,8 +648,8 @@ If @code{verbatim} is used in a @code{lilypondfile} command, it is possible to enclose verbatim only a part of the source file. If the source file contain a comment containing @samp{begin verbatim} (without quotes), quoting the source in the verbatim block will start after the -last occurence of such a comment; similarly, quoting the source verbatim -will stop just before the first occurence of a comment containing +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 example, the music will be interpreted in relative mode, but the verbatim quote will not show the @code{relative} block, i.e. @@ -656,6 +669,10 @@ will be printed with a verbatim block like f2 e @end example +@item addversion +(Only for Texinfo output.) Prepend line @code{\version +@@w@{"@@version@{@}"@}} to @code{verbatim} output. + @item texidoc (Only for Texinfo output.) If @command{lilypond} is called with the @option{--header=@/texidoc} option, and the file to be processed is @@ -691,6 +708,13 @@ lilypond-book --process="lilypond --format=tex --tex \ 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 @@ -698,14 +722,28 @@ 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 printfilename If a LilyPond input file is included with @code{\lilypondfile}, print -the file name right before the music snippet. For HTML output, this is -a link. +the file name right before the music snippet. For HTML output, this +is a link. Only the base name of the file is printed, i.e. the +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 @@ -719,9 +757,6 @@ 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. -@command{lilypond-book} can also create a @file{.psfonts} file, which is -required by @command{dvips} to produce PostScript and PDF files. - @subheading Format-specific instructions @subsubheading @LaTeX{} @@ -751,9 +786,9 @@ To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you should do @example -lilypond-book --psfonts yourfile.lytex +lilypond-book yourfile.lytex latex yourfile.tex -dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi +dvips -Ppdf yourfile.dvi ps2pdf yourfile.ps @end example @@ -762,7 +797,7 @@ 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. -Running @command{dvips} will produce some warnings about fonts; these +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 @command{dvips} options. @@ -827,7 +862,7 @@ invoke further processing commands such as @command{makeinfo} or @itemx --output=@var{dir} Place generated files in directory @var{dir}. Running @command{lilypond-book} generates lots of small files that LilyPond will -process. To avoid all that garbage in the source directory use the +process. To avoid all that garbage in the source directory, use the @option{--output} command line option, and change to that directory before running @command{latex} or @command{makeinfo}. @@ -837,29 +872,47 @@ cd out ... @end example +@itemx --skip-lily-check +Do not fail if no lilypond output is found. It is used for LilyPond +Info documentation without images. + +@itemx --skip-png-check +Do not fail if no PNG images are found for EPS files. It is used for +LilyPond Info documentation without images. + +@itemx --lily-output-dir=@var{dir} +Write lily-XXX files to directory @var{dir}, link into @code{--output} +directory. Use this option to save building time for documents in +different directories which share a lot of identical snippets. + +@itemx --info-images-dir=@var{dir} +Format Texinfo output so that Info will look for images of music in +@var{dir}. + +@itemx --latex-program=@var{prog} +Run executable @command{prog} instead of @command{latex}. This is +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 milimeters, +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 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. - -@itemx --psfonts -Extract all PostScript fonts into @file{@var{file}.psfonts} for dvips. -This is necessary for @command{dvips -h @var{file}.psfonts}. +Create PDF files for use with PDF@LaTeX{}. @item -V @itemx --verbose @@ -926,14 +979,14 @@ the automated method with @command{lilypond-book}. @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 @@ -942,15 +995,15 @@ 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 individually and added to the document; consult the documentation for -that program. Most programs will be able to insert lilypond output in +that program. Most programs will be able to insert LilyPond output in @file{PNG}, @file{EPS}, or @file{PDF} formats. -To reduce the white space around your lilypond score, use +To reduce the white space around your LilyPond score, use the following options @example @@ -966,9 +1019,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