Documentation/user/ly2dvi.itexi

   1 @c -*-texinfo-*-
   2
   3 @node ly2dvi
   4 @chapter ly2dvi
   5
   6 @file{ly2dvi} is a Python script that creates a nicely title output file
   7 from an input file for La@TeX{}. It can create a DVI or PS file. It
   8 works by running LilyPond on the input files, creating a La@TeX{}
   9 wrapper around the output, and running La@TeX{} (and optionally
  10 @code{dvips}).
  11
  12 @unnumberedsubsec Invoking ly2dvi
  13
  14 @c ly2dvi needs at least one FILE, can't act as filter yet
  15 @example
  16         ly2dvi [@var{OPTION}]@dots{} @var{FILE}@dots{}
  17 @end example
  18
  19 @unnumberedsec Options
  20
  21 @table @code
  22 @item -k,--keep
  23     Keep the temporary directory including LilyPond and ly2dvi output
  24 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
  25 @item -d,--dependencies
  26     Write makefile dependencies for every input file.
  27 @item -h,--help
  28     Print help.
  29 @item -I,--include=@var{DIR}
  30     Add @var{DIR} to LilyPond's include path.
  31 @item -m,--no-paper
  32     Produce MIDI output only.
  33 @item --no-lily
  34     Do not run LilyPond; useful for debugging ly2dvi.
  35 @item -o,--output=@var{FILE}
  36     Generate output to @var{FILE}.  The extension of @var{FILE} is ignored.
  37 @item -P,--postscript
  38     Also generate PostScript output.
  39 @item -s,--set=@var{KEY}=@var{VAL}
  40     Add @var{KEY}= @var{VAL} to the settings, overriding those specified
  41 in the files. Possible keys: @code{language}, @code{latexheaders},
  42 @code{latexpackages}, @code{latexoptions}, @code{papersize},
  43 @code{pagenumber}, @code{linewidth}, @code{orientation},
  44 @code{textheight}.
  45 @item -v,--version
  46 Show version information
  47 @item -V,--verbose
  48 Be verbose
  49 @item -w,--warranty
  50 Show the warranty with which GNU LilyPond comes. (It comes with
  51 @strong{NO WARRANTY}!)
  52 @end table
  53
  54 @unnumberedsubsec Titling layout
  55
  56 Ly2dvi extracts the following header fields from the LY files to
  57 generate titling:
  58
  59 @table @code
  60 @item title
  61     The title of the music. Centered on top of the first page.
  62 @item subtitle
  63     Subtitle, centered below the title.
  64 @item poet
  65     Name of the poet, left flushed below the below subtitle.
  66 @item composer
  67     Name of the composer, right flushed below the subtitle.
  68 @item metre
  69     Meter string, left flushed below the below poet.
  70 @item opus
  71     Name of the opus, right flushed below the below composer.
  72 @item arranger
  73     Name of the arranger, right flushed below the opus.
  74 @item instrument
  75     Name of the instrument, centered below the arranger
  76 @item piece
  77     Name of the piece, left flushed below the instrument
  78 @item head
  79     A text to print in the header of all pages. It is not called
  80 @code{header}, because @code{\header} is a reserved word in LilyPond.
  81 @item footer
  82     A text to print in the footer of all pages
  83 @item tagline
  84     Line to print at the bottom of last page. The default text is ``Lily
  85 was here, @var{version-number}''.
  86 @end table
  87
  88
  89 @cindex header
  90 @cindex footer
  91 @cindex page layout
  92 @cindex titles
  93
  94
  95
  96 @unnumberedsubsec Additional parameters
  97
  98 Ly2dvi responds to several parameters specified in the LilyPond
  99 file. They can be overridden by supplying a @code{--set} command line
 100 option.
 101
 102 @table @code
 103 @item language
 104     Specify La@TeX{} language: the @code{babel} package will be
 105 included.  Default: unset.
 106
 107         Read from the @code{\header} block.
 108
 109 @item latexheaders
 110     Specify additional La@TeX{} headers file.
 111
 112         Normally read from the @code{\header} block. Default value: empty
 113
 114 @item latexheaders
 115     Specify additional La@TeX{} packages file. This works cumulative,
 116 so you can add multiple packages using multiple @code{-s=latexpackages} options.
 117        Normally read from the @code{\header} block. Default value:
 118 @code{geometry}.
 119
 120 @item latexoptions
 121     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}
 122
 123 @item orientation
 124     Set orientation. Choices are @code{portrait} or @code{landscape}. Is
 125 read from the @code{\paper} block, if set.
 126
 127 @item linewidth
 128         The music line width. It is normally read from the @code{\paper}
 129 block.
 130
 131 @item papersize
 132    The paper size (as a name, e.g. @code{a4}). It is normally read from
 133 the @code{\paper} block.
 134 @end table
 135
 136 @unnumberedsubsec Environment variables
 137
 138 @table @code
 139 @item LANG
 140 selects the language for the warning messages of Ly2dvi and LilyPond.
 141 @end table
 142
 143 @unnumberedsubsec  Bugs
 144
 145 Cannot generate @TeX{} or @code{PostScript} only.  Send bugreports to to
 146 @email{bug-gnu-music@@gnu.org}.
 147
 148 @unnumberedsubsec  Authors
 149
 150 @email{hanwen@@cs.uu.nl,Han-Wen Nienhuys}.
 151
 152 Earlier incarnations of ly2dvi were written by
 153 @email{daboys@@austin.rr.com, Jeffrey B. Reed} (Python version), and
 154 @email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun} (Bourne
 155 shell version)
 156