X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=8abed05d52980a6eaf60dc012c514000a855ae6c;hb=37ca1f80bf5401accd17056938f4f7b2c147ddb2;hp=6a39f0788fb00ebe349fbbc3ff1ee8f9b2a04c99;hpb=e5751bd57f29c80d7c1ce3a323d6e5a3925cebcb;p=lilypond.git diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index 6a39f0788f..8abed05d52 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.38" @c Note: keep this node named so that `info lilypond-book' brings you here. @node LilyPond-book @@ -105,9 +106,10 @@ directory as this file.) 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 @example lilypond-book --output=out --pdf lilybook.lytex -@emph{lilypond-book (GNU LilyPond) 2.11.37} +@emph{lilypond-book (GNU LilyPond) @version{} } @emph{Reading lilybook.lytex...} @emph{..lots of stuff deleted..} @emph{Compiling lilybook.tex...} @@ -290,11 +292,11 @@ kpsewhich feta20.tex @end ignore -@commonprop +@snippets 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 @@ -554,6 +556,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 @@ -616,6 +623,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 @@ -634,8 +645,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. @@ -655,6 +666,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 @@ -690,6 +705,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 @@ -697,10 +719,24 @@ 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 @@ -718,9 +754,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{} @@ -750,18 +783,18 @@ 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 @noindent The @file{.dvi} file created by this process will not contain -noteheads. This is normal; if you follow the instructions, they + 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. @@ -791,15 +824,14 @@ 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}. +@ref{Filename extensions}. Currently, @code{texi} is the same as +@code{texi-html}. @c This complicated detail is not implemented, comment it out -jm @ignore The @code{texi} document type produces a Texinfo file with music fragments in the printed output only. For getting images in the HTML version, the format @code{texi-html} must be used instead. - -[Note: currently, @code{texi} is the same as @code{texi-html}.] @end ignore @item -F @var{filter} @@ -817,13 +849,17 @@ Print a short help message. @item -I @var{dir} @itemx --include=@var{dir} -Add @var{dir} to the include path. +Add @var{dir} to the include path. @command{lilypond-book} also looks +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. @item -o @var{dir} @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}. @@ -833,8 +869,30 @@ 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. @@ -850,9 +908,8 @@ 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. -@itemx --psfonts -Extract all PostScript fonts into @file{@var{file}.psfonts} for dvips. -This is necessary for @command{dvips -h @var{file}.psfonts}. +@item --pdf +Create PDF files for use with PDFLaTeX. @item -V @itemx --verbose @@ -863,7 +920,7 @@ Be verbose. Print version information. @end table -@refbugs +@knownissues The Texinfo command @code{@@pagesizes} is not interpreted. Similarly, @LaTeX{} commands that change margins and line widths after the preamble @@ -922,7 +979,7 @@ the automated method with @command{lilypond-book}. @subsection 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 @@ -940,10 +997,10 @@ LilyPond notation can be added to OpenOffice.org with 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 @@ -963,5 +1020,8 @@ To produce a useful EPS file, use @example lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly + +PNG: +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly @end example