X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Flilypond-book.itely;h=31590d91dd101a0045ca0580aebddc4bfc9edf42;hb=55cdf3441eca8d6489c486767cf8013b08e8b32e;hp=44b2dc0a265bfdea9608448476b8918a9b790ca2;hpb=7eb9c626943a47141ec2cc5fad7723f69e04bbd2;p=lilypond.git diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely index 44b2dc0a26..31590d91dd 100644 --- a/Documentation/usage/lilypond-book.itely +++ b/Documentation/usage/lilypond-book.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.13.36" +@c \version "2.14.0" @c Note: keep this node named so that `info lilypond-book' brings you here. @node lilypond-book @@ -100,7 +100,7 @@ Larger examples can be put into a separate file, and introduced with \lilypondfile[quote,noindent]{screech-boink.ly} -(If needed, replace @file{screech@/-boink@/.ly} by any @file{@/.ly} file +(If needed, replace @file{screech-boink.ly} by any @file{.ly} file you put in the same directory as this file.) \end{document} @@ -109,7 +109,7 @@ you put in the same directory as this file.) @subheading Processing -Save the code above to a file called @file{lilybook@/.lytex}, then in a +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 @@ -128,7 +128,7 @@ xpdf lilybook 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 @@ -159,6 +159,20 @@ Larger examples can be put into a separate file, and introduced with @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 @@ -186,27 +200,44 @@ See @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. @@ -383,33 +414,47 @@ Texinfo is the standard format for documentation of the GNU project. An 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 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 +file (with extension @file{.texi}) containing @code{@@image} tags for HTML, Info and printed output. @command{lilypond-book} generates images of the music in EPS and PDF formats for use in the printed output, and in PNG format for use in HTML and Info output. @@ -447,8 +492,51 @@ in-line image. It always gets a paragraph of its own. @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{} command, where you can directly enter short lilypond code + +@item +the @code{...} environment, where you can directly enter longer +lilypond code + +@item +the @code{...} command to insert a lilypond file + +@item +the @code{...} 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 + + YOUR LILYPOND CODE + + + + +@var{filename} + +@var{filename} +@end example + +For example, you can write @example \key c \minor c4 es g2 @@ -476,6 +564,9 @@ To include separate files, say @var{filename} @end example +@code{} uses the same syntax as @code{}, 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}. @@ -503,11 +594,11 @@ inline or not inline. The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are chosen to allow DocBook editors format the content gracefully. The DocBook files to be processed with -@command{lilypond-book} should have the extension @file{@/.lyxml}. +@command{lilypond-book} should have the extension @file{.lyxml}. @subheading Including a LilyPond file -This is the most simple case. We must use the @file{@/.ly} extension for +This is the most simple case. We must use the @file{.ly} extension for the included file, and insert it as a standard @code{imageobject}, with the following structure: @@ -547,8 +638,8 @@ the @code{programlisting} inside. @subheading Processing the DocBook document -Running @command{lilypond-book} on our @file{@/.lyxml} file will create a -valid DocBook document to be further processed with @file{@/.xml} +Running @command{lilypond-book} on our @file{.lyxml} file will create a +valid DocBook document to be further processed with @file{.xml} extension. If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically. For HTML (HTML Help, @@ -601,6 +692,14 @@ If no @code{line-width} option is given, @command{lilypond-book} tries 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. @@ -691,7 +790,7 @@ will be printed with a verbatim block like 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} +contain a tree of @file{.mo} message catalogs with @code{lilypond-doc} as a domain. @item addversion @@ -701,12 +800,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 @{ @@ -716,7 +815,7 @@ Assuming the file @file{foo@/.ly} contains @end example @noindent -and we have this in our Texinfo document @file{test@/.texinfo} +and we have this in our Texinfo document @file{test.texinfo} @example @@lilypondfile[texidoc]@{foo.ly@} @@ -731,14 +830,14 @@ lilypond-book --pdf --process="lilypond \ @end example Most LilyPond test documents (in the @file{input} directory of the -distribution) are small @file{@/.ly} files which look exactly like this. +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 @@ -751,9 +850,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. @@ -777,9 +876,9 @@ directory part of the file path is stripped. @section Invoking @command{lilypond-book} @command{lilypond-book} produces a file with one of the following -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. +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. @subheading Format-specific instructions @@ -817,13 +916,13 @@ ps2pdf yourfile.ps @end example @noindent -The @file{@/.dvi} file created by this process will not contain +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. +will be included in the @file{.ps} and @file{.pdf} files. 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 @@ -880,7 +979,7 @@ 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. +@command{latex} with the same @option{-I @var{dir}} options. @item -o @var{dir} @itemx --output=@var{dir} @@ -905,7 +1004,7 @@ 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} +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. @@ -931,17 +1030,21 @@ line to the right by the same amount. @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 @@ -991,7 +1094,7 @@ selects the output format based on the input filename's extension. 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}.