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 titled 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 usage 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, using dvips.
  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 subtitle.
  66 @item composer
  67     Name of the composer, right flushed below the subtitle.
  68 @item meter
  69     Meter string, left flushed below the poet.
  70 @item opus
  71     Name of the opus, right flushed below the 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 copyright
  82     A text to print in the footer of the first page. Default is to
  83     print the standard footer also on the first page.
  84 @item footer
  85     A text to print in the footer of all but the last page.
  86 @item tagline
  87     Line to print at the bottom of last page. The default text is ``Lily
  88 was here, @var{version-number}''.
  89 @end table
  90
  91
  92 @cindex header
  93 @cindex footer
  94 @cindex page layout
  95 @cindex titles
  96
  97
  98
  99 @unnumberedsubsec Additional parameters
 100
 101 Ly2dvi responds to several parameters specified in a @code{\paper}
 102 section of the LilyPond file. They can be overridden by supplying a
 103 @code{--set} command line option.
 104
 105 @table @code
 106 @item language
 107     Specify La@TeX{} language: the @code{babel} package will be
 108 included.  Default: unset.
 109
 110         Read from the @code{\header} block.
 111
 112 @item latexheaders
 113     Specify additional La@TeX{} headers file.
 114
 115         Normally read from the @code{\header} block. Default value: empty
 116
 117 @item latexpackages
 118     Specify additional La@TeX{} packages file. This works cumulative,
 119 so you can add multiple packages using multiple @code{-s=latexpackages} options.
 120        Normally read from the @code{\header} block. Default value:
 121 @code{geometry}.
 122
 123 @item latexoptions
 124     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}
 125
 126 @item orientation
 127     Set orientation. Choices are @code{portrait} or @code{landscape}. Is
 128 read from the @code{\paper} block, if set.
 129
 130 @item textheight
 131     The vertical extension of the music on the page. It is normally
 132     calculated automatically, based on the paper size.
 133
 134 @item linewidth
 135         The music line width. It is normally read from the @code{\paper}
 136 block.
 137
 138 @item papersize
 139    The paper size (as a name, e.g. @code{a4}). It is normally read from
 140 the @code{\paper} block.
 141 @end table
 142
 143 @unnumberedsubsec Environment variables
 144
 145 @table @code
 146 @item LANG
 147 selects the language for the warning messages of Ly2dvi and LilyPond.
 148 @end table
 149
 150 @unnumberedsubsec  Bugs
 151
 152 Cannot generate @TeX{} or @code{PostScript} only.  Send bugreports to to
 153 @email{bug-gnu-music@@gnu.org}.
 154
 155 @unnumberedsubsec  Authors
 156
 157 @email{hanwen@@cs.uu.nl,Han-Wen Nienhuys}.
 158
 159 Earlier incarnations of ly2dvi were written by
 160 @email{daboys@@austin.rr.com, Jeffrey B. Reed} (Python version), and
 161 @email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun} (Bourne
 162 shell version)
 163