@c -*-texinfo-*-

@node ly2dvi
@chapter ly2dvi

@file{ly2dvi} is a Python script that creates a nicely title output file
from an input file for La@TeX{}. It can create a DVI or PS file. It
works by running LilyPond on the input files, creating a La@TeX{}
wrapper around the output, and running La@TeX{} (and optionally
@code{dvips}).

@unnumberedsubsec Invoking ly2dvi

@example
ly2dvi @var{[OPTIONS]} ... @var{[FILE]}...
@end example

@unnumberedsec Options

@table @code
@item -k,--keep
    Keep the temporary directory including LilyPond and ly2dvi output
files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
@item -d,--dependencies
    Write makefile dependencies for every input file.
@item -h,--help
    Print help.
@item -I,--include=@var{DIR}
    Add @var{DIR} to LilyPond's include path.
@item -m,--no-paper
    Produce MIDI output only.
@item --no-lily
    Do not run LilyPond; useful for debugging ly2dvi.
@item -o,--output=@var{FILE}
    Generate output to @var{FILE}.  The extension of @var{FILE} is ignored.
@item -P,--postscript
    Also generate PostScript output.
@item -s,--set=@var{KEY}=@var{VAL}
    Add @var{KEY}= @var{VAL} to the settings, overriding those specified
in the files. Possible keys: @code{language}, @code{latexheaders},
@code{latexpackages}, @code{latexoptions}, @code{papersize},
@code{pagenumber}, @code{linewidth}, @code{orientation},
@code{textheight}.
@item -v,--version
Show version information 
@item -V,--verbose
Be verbose
@item -w,--warranty
Show the warranty with which GNU LilyPond comes. (It comes with 
@strong{NO WARRANTY}!)
@end table

@unnumberedsubsec Titling layout

Ly2dvi extracts the following header fields from the LY files to
generate titling:

@table @code
@item title
    The title of the music. Centered on top of the first page.
@item subtitle
    Subtitle, centered below the title.
@item poet
    Name of the poet, left flushed below the below subtitle.
@item composer
    Name of the composer, right flushed below the subtitle.
@item metre
    Meter string, left flushed below the below poet.
@item opus
    Name of the opus, right flushed below the below composer.
@item arranger
    Name of the arranger, right flushed below the opus.
@item instrument
    Name of the instrument, centered below the arranger
@item piece
    Name of the piece, left flushed below the instrument
@item head
    A text to print in the header of all pages. It is not called
@code{header}, because @code{\header} is a reserved word in LilyPond.
@item footer
    A text to print in the footer of all pages
@item tagline
    Line to print at the bottom of last page. The default text is ``Lily
was here, @var{version-number}''.
@end table


@cindex header
@cindex footer
@cindex page layout
@cindex titles



@unnumberedsubsec Additional parameters

Ly2dvi responds to several parameters specified in the LilyPond
file. They can be overridden by supplying a @code{--set} command line
option.

@table @code
@item language
    Specify La@TeX{} language: the @code{babel} package will be
included.  Default: unset.

        Read from the @code{\header} block.

@item latexheaders
    Specify additional La@TeX{} headers file.

        Normally read from the @code{\header} block. Default value: empty

@item latexheaders
    Specify additional La@TeX{} packages file. This works cumulative,
so you can add multiple packages using multiple @code{-s=latexpackages} options.
       Normally read from the @code{\header} block. Default value:
@code{geometry}.

@item latexoptions
    Specify additional options for the La@TeX{} @code{\documentclass}. You can put any valid value here. This was designed to allow ly2dvi to produce output for double-sided paper, with balanced margins and pagenumbers on alternating sides. To achieve this specify @code{twoside}

@item orientation
    Set orientation. Choices are @code{portrait} or @code{landscape}. Is
read from the @code{\paper} block, if set.
        
@item linewidth
        The music line width. It is normally read from the @code{\paper}
block.

@item papersize
   The paper size (as a name, e.g. @code{a4}). It is normally read from
the @code{\paper} block.
@end table

@unnumberedsubsec Environment variables

@table @code
@item LANG
selects the language for the warning messages of Ly2dvi and LilyPond.
@end table

@unnumberedsubsec  Bugs

Cannot generate @TeX{} or @code{PostScript} only.  Send bugreports to to
@email{bug-gnu-music@@gnu.org}.

@unnumberedsubsec  Authors

@email{hanwen@@cs.uu.nl,Han-Wen Nienhuys}.

Earlier incarnations of ly2dvi were written by
@email{daboys@@austin.rr.com, Jeffrey B. Reed} (Python version), and
@email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun} (Bourne
shell version)