@c -*-texinfo-*-

@node ly2dvi
@chapter ly2dvi

@file{ly2dvi} is a Python script that creates a nicely titled 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

@c ly2dvi needs at least one FILE, can't act as filter yet
@example
        ly2dvi [@var{OPTION}]@dots{} @var{FILE}@dots{}
@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 usage 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, using dvips.
@item --preview
    Also generate a picture of the first system of the score.
@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 subtitle.
@item composer
    Name of the composer, right flushed below the subtitle.
@item meter
    Meter string, left flushed below the poet.
@item opus
    Name of the opus, right flushed below the 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 copyright
    A text to print in the footer of the first page. Default is to 
    print the standard footer also on the first page.
@item footer
    A text to print in the footer of all but the last page.
@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 a @code{\paper}
section of 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 latexpackages
    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 textheight
    The vertical extension of the music on the page. It is normally 
    calculated automatically, based on the paper size.

@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.

@item pagenumber
   If set to @code{no}, no page numbers will be printed.


  
  @item fontenc
     The font encoding, should be set identical to the @code{font-encoding}
     property in the score.
@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-lilypond@@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)

