--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+ Translation of GIT committish: f77212d801fa4603bf596a19cecf5a068f1d9d85
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
+@end ignore
+
+@c \version "2.13.36"
+
+@c Note: keep this node named so that `info lilypond-book' brings you here.
+@node lilypond-book
+@chapter A @command{lilypond-book} használata
+@translationof lilypond-book
+
+Amennyiben egy dokumentumba kottapéldákat szeretnénk beszúrni, megtehetjük,
+hogy azok képeit egyesével létrehozzuk a LilyPond segítségével PostScript
+vagy PNG formátumban, és mint bármilyen más képeket, beillesztjük azokat egy
+@LaTeX{} vagy HTML dokumentumba.
+
+A @command{lilypond-book} ennek a folyamatnak az automatizálására szolgál:
+ez a program kiszedi a LilyPond kódrészleteket egy dokumentumból, lefordítja
+őket a @command{lilypond} segítségével, és az így kapott képeket beilleszti
+az eredeti kódrészletek helyére. A kottakép méretei igazodnak a dokumentum
+elrendezéséhez.
+
+A @command{lilypond-book} egy különálló parancssori program; a parancssoros
+programok futtatásának módját a @ref{Parancssori használat} írja le bővebben.
+
+A @command{lilypond-book} jelenleg a @LaTeX{}, HTML, Texinfo és DocBook
+formátumokat támogatja.
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex texi
+@cindex html
+@cindex docbook
+@cindex dokumentumok, kottapéldák
+@cindex HTML, kottapéldák
+@cindex Texinfo, kottapéldák
+@cindex DocBook, kottapéldák
+@cindex @LaTeX{}, kottapéldák
+
+@menu
+* Egy kottapéldákat tartalmazó dokumentum::
+* Zene és szöveg integrációja::
+* Kottapéldák paraméterei::
+* A lilypond-book futtatása::
+* Fájlkiterjesztések::
+* lilypond-book sablonok::
+* Közös tartalomjegyzék::
+* További módszerek zene és szöveg kombinálására::
+@end menu
+
+
+@node Egy kottapéldákat tartalmazó dokumentum
+@section Egy kottapéldákat tartalmazó dokumentum
+@translationof An example of a musicological document
+
+@cindex zenetudomány
+Bizonyos dokumentumok kottapéldákat tartalmaznak. Ezek között vannak
+zenetudományi értekezések, énekeskönyvek, vagy ehhez hasonló kézikönyvek.
+Ezeket úgy is el lehet készíteni, hogy a szövegbe beillesztjük a kottaábrákat.
+Azonban ahhoz, hogy ne kelljen minden egyes kottarészlet szedését külön
+elvégezni, a HTML, @LaTeX{}, Texinfo és DocBook formátumú dokumentumok esetén
+mód nyílik ennek automatizálására.
+
+Egy @code{lilypond-book} nevű parancsfájl a LilyPond nyelvén írt
+kódrészleteket szépen formázott kottapéldákká alakítja át. Íme egy rövid,
+magyarázatokkal ellátott @LaTeX{} példa.
+
+@subheading Bemenet
+
+@quotation
+@verbatim
+\documentclass[a4paper]{article}
+
+\begin{document}
+
+A \verb+lilypond-book+ segítségével feldolgozott dokumentumok
+kottapéldákat tartalmazhatnak. Például:
+
+\begin{lilypond}
+\relative c' {
+ c2 e2 \times 2/3 { f8 a b } a2 e4
+}
+\end{lilypond}
+
+A beállításokat szögletes zárójelbe kell tenni:
+
+\begin{lilypond}[fragment,quote,staffsize=26,verbatim]
+ c'4 f16
+\end{lilypond}
+
+A nagyobb kottapéldákat ki lehet emelni külön fájlba, majd beilleszteni
+őket a \verb+\lilypondfile+ paranccsal:
+
+\lilypondfile[quote,noindent]{screech-boink.ly}
+
+\end{document}
+@end verbatim
+@end quotation
+
+@subheading Feldolgozás
+
+A fenti dokumentumot egy @file{lilybook.lytex} nevű fájlba mentve futtassuk le
+a következő parancsokat:
+
+@c keep space after @version{} so TeX doesn't choke
+@example
+lilypond-book --output=out --pdf lilybook.lytex
+@emph{lilypond-book (GNU LilyPond) @version{} }
+@emph{Reading lilybook.lytex...}
+@emph{...}
+@emph{Compiling lilybook.tex...}
+cd out
+pdflatex lilybook
+@emph{...}
+xpdf lilybook
+@emph{(az @command{xpdf} helyére értelemszerűen tetszőleges PDF-nézegető
+kerülhet)}
+@end example
+
+A @command{lilypond-book} és a @command{latex} rengeteg ideiglenes fájlt
+hoznak létre. Annak érdekében, hogy ezek külön alkönyvtárba kerüljenek, a
+@code{--output=@var{alkönyvtár}} opciót kell megadni.
+
+Lent látható a fenti @LaTeX{} példa kimenete.@footnote{Ezt a dokumentumot a
+Texinfo generálta, így apró eltérések lehetnek.} Ezzel elsajátítottuk a
+lilypond-book használatának alapjait.
+
+@page
+
+@subheading Kimenet
+
+A @command{lilypond-book} segítségével feldolgozott dokumentumok
+kottapéldákat tartalmazhatnak. Például:
+
+@lilypond
+\relative c' {
+ c2 e2 \times 2/3 { f8 a b } a2 e4
+}
+@end lilypond
+
+A beállításokat szögletes zárójelbe kell tenni:
+
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
+
+A nagyobb kottapéldákat ki lehet emelni külön fájlba, majd beilleszteni
+őket a @code{\lilypondfile} paranccsal:
+
+@lilypondfile[quote,noindent]{screech-boink.ly}
+
+
+@page
+
+@node Integrating music and text
+@section Integrating music and text
+
+Here we explain how to integrate LilyPond with various output formats.
+
+@menu
+* LaTeX::
+* Texinfo::
+* HTML::
+* DocBook::
+@end menu
+
+@node LaTeX
+@subsection @LaTeX{}
+
+@LaTeX{} is the de-facto standard for publishing layouts in the exact
+sciences. It is built on top of the @TeX{} typesetting engine,
+providing the best typography available anywhere.
+
+See
+@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
+@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
+to use @LaTeX{}.
+
+Music is entered using
+
+@example
+\begin@{lilypond@}[options,go,here]
+ YOUR LILYPOND CODE
+\end@{lilypond@}
+@end example
+
+@noindent
+or
+
+@example
+\lilypondfile[options,go,here]@{@var{filename}@}
+@end example
+
+@noindent
+or
+
+@example
+\lilypond[options,go,here]@{ 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{}.
+
+We show some examples here. The @code{lilypond} environment
+
+@example
+\begin@{lilypond@}[quote,fragment,staffsize=26]
+ c' d' e' f' g'2 g'2
+\end@{lilypond@}
+@end example
+
+@noindent
+produces
+
+@lilypond[quote,fragment,staffsize=26]
+c' d' e' f' g'2 g'2
+@end lilypond
+
+The short version
+
+@example
+\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
+@end example
+
+@noindent
+produces
+
+@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
+
+@noindent
+Currently, you cannot include @code{@{} or @code{@}} within
+@code{\lilypond@{@}}, so this command is only useful with the
+@code{fragment} option.
+
+The default line width of the music will be adjusted by examining the
+commands in the document preamble, the part of the document before
+@code{\begin@{document@}}. The @command{lilypond-book} command sends
+these to @LaTeX{} to find out how wide the text is. The line width for
+the music fragments is then adjusted to the text width. Note that this
+heuristic algorithm can fail easily; in such cases it is necessary to
+use the @code{line-width} music fragment option.
+
+@cindex titling and lilypond-book
+@cindex \header in @LaTeX{} documents
+
+Each snippet will call the following macros if they have been defined by
+the user:
+
+@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
+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}.
+@end itemize
+
+@ignore
+Broken stuff. :(
+
+@cindex Latex, feta symbols
+@cindex fetachar
+
+To include feta symbols (such as flat, segno, etc) in a LaTeX
+document, use @code{\input@{titledefs@}}
+
+@example
+\documentclass[a4paper]@{article@}
+
+\input@{titledefs@}
+
+\begin@{document@}
+
+\fetachar\fetasharp
+
+\end@{document@}
+@end example
+
+The font symbol names are defined in the file feta20.tex; to find
+the location of this file, use the command
+
+@example
+kpsewhich feta20.tex
+@end example
+
+@end ignore
+
+@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
+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
+called @emph{after} the first system, including only the first system
+is trivial.
+
+@example
+\def\betweenLilyPondSystem#1@{\endinput@}
+
+\begin@{lilypond@}[fragment]
+ c'1\( e'( c'~ \break c' d) e f\)
+\end@{lilypond@}
+@end example
+
+If a greater number of systems is requested, a @TeX{} conditional must
+be used before the @code{\endinput}. In this example, replace @q{2} by
+the number of systems you want in the output.
+
+@example
+\def\betweenLilyPondSystem#1@{
+ \ifnum#1<2\else\expandafter\endinput\fi
+@}
+@end example
+
+@noindent
+(Since @code{\endinput} immediately stops the processing of the current
+input file we need @code{\expandafter} to delay the call of @code{\endinput}
+after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
+balanced.)
+
+Remember that the definition of @code{\betweenLilyPondSystem} is
+effective until @TeX{} quits the current group (such as the @LaTeX{}
+environment) or is overridden by another definition (which is, in
+most cases, for the rest of the document). To reset your
+definition, write
+
+@example
+\let\betweenLilyPondSystem\undefined
+@end example
+
+@noindent
+in your @LaTeX{} source.
+
+This may be simplified by defining a @TeX{} macro
+
+@example
+\def\onlyFirstNSystems#1@{
+ \def\betweenLilyPondSystem##1@{%
+ \ifnum##1<#1\else\expandafter\endinput\fi@}
+@}
+@end example
+
+@noindent
+and then saying only how many systems you want before each fragment,
+
+@example
+\onlyFirstNSystems@{3@}
+\begin@{lilypond@}...\end@{lilypond@}
+\onlyFirstNSystems@{1@}
+\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
+@ref{Invoking lilypond-book}.
+
+
+@node Texinfo
+@subsection Texinfo
+
+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
+
+@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}@}
+@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
+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.
+
+We show two simple examples here. A @code{lilypond} environment
+
+@example
+@@lilypond[fragment]
+c' d' e' f' g'2 g'
+@@end lilypond
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment]
+c' d' e' f' g'2 g'
+@end lilypond
+
+The short version
+
+@example
+@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment,staffsize=11]{<c' e' g'>}
+
+Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
+in-line image. It always gets a paragraph of its own.
+
+
+@node HTML
+@subsection HTML
+
+Music is entered using
+
+@example
+<lilypond fragment relative=2>
+\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:
+
+@lilypond[fragment,relative=2]
+\key c \minor c4 es g2
+@end lilypond
+
+For inline pictures, use @code{<lilypond ... />}, where the options
+are separated by a colon from the music, for example
+
+@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.
+
+
+@cindex titling in HTML
+@cindex preview image
+@cindex thumbnail
+
+@node DocBook
+@subsection DocBook
+
+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
+standard DocBook elements.
+
+@subheading Common conventions
+
+For inserting all type of snippets we use the @code{mediaobject} and
+@code{inlinemediaobject} element, so our snippets can be formatted
+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}.
+
+@subheading Including a LilyPond file
+
+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:
+
+@example
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="music1.ly" role="printfilename" />
+ </imageobject>
+</mediaobject>
+@end example
+
+Note that you can use @code{mediaobject} or @code{inlinemediaobject}
+as the outermost element as you wish.
+
+@subheading Including LilyPond code
+
+Including LilyPond code is possible by using a @code{programlisting},
+where the language is set to @code{lilypond} with the following
+structure:
+
+@example
+<inlinemediaobject>
+ <textobject>
+ <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
+\context Staff \with @{
+ \remove Time_signature_engraver
+ \remove Clef_engraver@}
+ @{ c4( fis) @}
+ </programlisting>
+ </textobject>
+</inlinemediaobject>
+@end example
+
+As you can see, the outermost element is a @code{mediaobject} or
+@code{inlinemediaobject}, and there is a @code{textobject} containing
+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}
+extension. If you use
+@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
+PDF file from this document automatically. For HTML (HTML Help,
+JavaHelp etc.) generation you can use the official DocBook XSL
+stylesheets, however, it is possible that you have to make some
+customization for it.
+
+
+@node Music fragment options
+@section Music fragment options
+
+In the following, a @q{LilyPond command} refers to any command described
+in the previous sections which is handled by @command{lilypond-book} to
+produce a music snippet. For simplicity, LilyPond commands are only
+shown in @LaTeX{} syntax.
+
+Note that the option string is parsed from left to right; if an option
+occurs multiple times, the last one is taken.
+
+The following options are available for LilyPond commands:
+
+@table @code
+@item staffsize=@var{ht}
+Set staff size to @var{ht}, which is measured in points.
+
+@item ragged-right
+Produce ragged-right lines with natural spacing, i.e.,
+@code{ragged-right = ##t} is added to the LilyPond snippet. This is the
+default for the @code{\lilypond@{@}} command if no @code{line-width}
+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.
+
+@item line-width
+@itemx line-width=@var{size}\@var{unit}
+Set line width to @var{size}, using @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 output (this is, the staff
+length of the music snippet), not the text layout.
+
+If used without an argument, set line width to a default value (as
+computed with a heuristic algorithm).
+
+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 notime
+Do not print the time signature, and turns off the timing (time signature,
+bar lines) in the score.
+
+@item fragment
+Make @command{lilypond-book} add some boilerplate code so that you can
+simply enter, say,
+
+@example
+c'4
+@end example
+
+@noindent
+without @code{\layout}, @code{\score}, etc.
+
+@item nofragment
+Do not add additional code to complete LilyPond code in music snippets.
+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:
+@code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
+LilyPond, not the text layout.
+
+@item noindent
+Set indentation of the first music system to zero. This option affects
+LilyPond, not the text layout. Since no indentation is the default,
+@code{noindent} is redundant normally.
+
+@item quote
+Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
+the output into a quotation block. The value @q{0.4@dmn{in}} can be
+controlled with the @code{exampleindent} option.
+
+@item exampleindent
+Set the amount by which the @code{quote} option indents a music snippet.
+
+@item relative
+@itemx relative=@var{n}
+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
+documentation. To do that, some more obscure music fragment options are
+available.
+
+@table @code
+@item verbatim
+The argument of a LilyPond command is copied to the output file and
+enclosed in a verbatim block, followed by any text given with the
+@code{intertext} option (not implemented yet); then the actual music is
+displayed. This option does not work well with @code{\lilypond@{@}} if
+it is part of a paragraph.
+
+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 occurrence of such a comment; similarly, quoting the source verbatim
+will stop just before the first occurrence of a comment containing
+@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.
+
+@example
+\relative c' @{ % begin verbatim
+ c4 e2 g4
+ f2 e % end verbatim
+@}
+@end example
+
+@noindent
+will be printed with a verbatim block like
+
+@example
+ c4 e2 g4
+ 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.
+
+@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
+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
+
+@example
+\header @{
+ texidoc = "This file demonstrates a single note."
+@}
+@{ c'4 @}
+@end example
+
+@noindent
+and we have this in our Texinfo document @file{test.texinfo}
+
+@example
+@@lilypondfile[texidoc]@{foo.ly@}
+@end example
+
+@noindent
+the following command line gives the expected result
+
+@example
+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
+@code{verbatim} option) is put into a quotation block. This option is
+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
+is a link. Only the base name of the file is printed, i.e. the
+directory part of the file path is stripped.
+
+@end table
+
+
+@node Invoking lilypond-book
+@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.
+
+@subheading Format-specific instructions
+
+@subsubheading @LaTeX{}
+
+There are two ways of processing your @LaTeX{} document for printing or
+publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
+PostScript file with @LaTeX{} via a DVI to PostScript translator like
+@command{dvips}. The first way is simpler and recommended@footnote{Note
+that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
+@LaTeX{} document, that is why we explain the two ways.}, and whichever
+way you use, you can easily convert between PostScript and PDF with
+tools, like @command{ps2pdf} and @command{pdf2ps} included in
+Ghostscript package.
+
+To produce a PDF file through PDF@LaTeX{}, use
+
+@example
+lilypond-book --pdf yourfile.lytex
+pdflatex yourfile.tex
+@end example
+
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
+should do
+
+@example
+lilypond-book yourfile.lytex
+latex yourfile.tex
+dvips -Ppdf yourfile.dvi
+ps2pdf yourfile.ps
+@end example
+
+@noindent
+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} 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.
+
+@subsubheading Texinfo
+
+To produce a Texinfo document (in any output format), follow the normal
+procedures for Texinfo; this is, either call @command{texi2pdf} or
+@command{texi2dvi} or @command{makeinfo}, depending on the output format
+you want to create.
+@ifinfo
+@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
+an Info File, , , texinfo, GNU Texinfo}.
+@end ifinfo
+@ifnotinfo
+See the documentation of Texinfo for further details.
+@end ifnotinfo
+
+
+@subheading Command line options
+
+@command{lilypond-book} accepts the following command line options:
+
+@table @code
+@item -f @var{format}
+@itemx --format=@var{format}
+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
+@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.
+@end ignore
+
+@item -F @var{filter}
+@itemx --filter=@var{filter}
+Pipe snippets through @var{filter}. @code{lilypond-book} will
+not --filter and --process at the same time. For example,
+
+@example
+lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
+@end example
+
+@item -h
+@itemx --help
+Print a short help message.
+
+@item -I @var{dir}
+@itemx --include=@var{dir}
+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
+@option{--output} command line option, and change to that directory
+before running @command{latex} or @command{makeinfo}.
+
+@example
+lilypond-book --output=out yourfile.lytex
+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 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 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{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 PDF@LaTeX{}.
+
+@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.
+
+@item -V
+@itemx --verbose
+Be verbose.
+
+@item -v
+@itemx --version
+Print version information.
+@end table
+
+@knownissues
+
+The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
+@LaTeX{} commands that change margins and line widths after the preamble
+are ignored.
+
+Only the first @code{\score} of a LilyPond block is processed.
+
+
+@node Filename extensions
+@section Filename extensions
+
+You can use any filename extension for the input file, but if you do not
+use the recommended extension for a particular format you may need to
+manually specify the output format; for details, see @ref{Invoking
+lilypond-book}. Otherwise, @command{lilypond-book} automatically
+selects the output format based on the input filename's extension.
+
+@quotation
+@multitable @columnfractions .2 .5
+@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{}
+@item @file{.lyxml} @tab DocBook
+@item @file{.tely} @tab Texinfo
+@item @file{.tex} @tab @LaTeX{}
+@item @file{.texi} @tab Texinfo
+@item @file{.texinfo} @tab Texinfo
+@item @file{.xml} @tab HTML
+@end multitable
+@end quotation
+
+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 it will exit with an error
+message like @qq{Output would overwrite input file}.
+
+
+@node lilypond-book templates
+@section lilypond-book templates
+
+These templates are for use with @code{lilypond-book}. If you're not familiar
+with this program, please refer to
+@ref{lilypond-book}.
+
+@subsection LaTeX
+
+You can include LilyPond fragments in a LaTeX document.
+
+@example
+\documentclass[]@{article@}
+
+\begin@{document@}
+
+Normal LaTeX text.
+
+\begin@{lilypond@}
+\relative c'' @{
+ a4 b c d
+@}
+\end@{lilypond@}
+
+More LaTeX text, and options in square brackets.
+
+\begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
+d4 c b a
+\end@{lilypond@}
+\end@{document@}
+@end example
+
+@subsection Texinfo
+
+You can include LilyPond fragments in Texinfo; in fact, this entire manual
+is written in Texinfo.
+
+@example
+\input texinfo @c -*-texinfo-*-
+@@node Top
+@@top
+
+Texinfo text
+
+@@lilypond
+\relative c' @{
+ a4 b c d
+@}
+@@end lilypond
+
+More Texinfo text, and options in brackets.
+
+@@lilypond[verbatim,fragment,ragged-right]
+d4 c b a
+@@end lilypond
+
+@@bye
+@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
+\documentclass{article}
+\usepackage{ifxetex}
+\ifxetex
+%xetex specific stuff
+\usepackage{xunicode,fontspec,xltxtra}
+\setmainfont[Numbers=OldStyle]{Times New Roman}
+\setsansfont{Arial}
+\else
+%This can be empty if you are not going to use pdftex
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{mathptmx}%Times
+\usepackage{helvet}%Helvetica
+\fi
+%Here you can insert all packages that pdftex also understands
+\usepackage[ngerman,finnish,english]{babel}
+\usepackage{graphicx}
+
+\begin{document}
+\title{A short document with LilyPond and xelatex}
+\maketitle
+
+Normal \textbf{font} commands inside the \emph{text} work,
+because they \textsf{are supported by \LaTeX{} and XeteX.}
+If you want to use specific commands like \verb+\XeTeX+, you
+should include them again in a \verb+\ifxetex+ environment.
+You can use this to print the \ifxetex \XeTeX{} command \else
+XeTeX command \fi which is not known to normal \LaTeX .
+
+In normal text you can easily use LilyPond commands, like this:
+
+\begin{lilypond}
+{a2 b c'8 c' c' c'}
+\end{lilypond}
+
+\noindent
+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
+lilypond-book.
+
+\selectlanguage{ngerman}
+Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
+anderen
+seltsamen Zeichen: __ ______, wenn sie von der Schriftart
+unterst__tzt werden.
+\end{document}
+@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
+
+Other means of mixing text and music (without
+@command{lilypond-book}) are discussed in
+@ref{LilyPond output in other programs}.
+
+
projects / lilypond.git / commitdiff