Documentation/user/ly2dvi.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename ly2dvi.info
   3 @settitle ly2dvi
   4
   5 @chapter Ly2dvi
   6
   7 @section DESCRIPTION
   8 ly2dvi is a Python script which creates input file for La@TeX{},
   9 based on information from the output files from LilyPond.
  10 The script handles multiple files. If a lilypond file name is
  11 specified LilyPond is run to make an output (@TeX{}) file.
  12
  13 One or more La@TeX{} files are created, based on information found
  14 in the output (@TeX{}) files, and latex is finally run to create
  15 one or more DVI files.
  16
  17 The majority of this utility came from a bourne script written by Jan
  18 Arne Fagertun name @file{ly2dvi}.
  19
  20 @section SYNOPSIS
  21
  22         ly2dvi [options] inputfile[.ly] [....]
  23
  24
  25 @section OPTIONS
  26
  27 @table @samp
  28 @item -D,--debug
  29     Set debug mode. There are two levels - in level one some debug
  30     info is written, in level two the command @strong{set -x} is run, which
  31     echoes every command in the ly2dvi script.
  32 @item -F,--headers=
  33     Name of additional La@TeX{} headers file. This is included in the
  34     tex file at the end of the headers, last line before @code{\begin@{document@}}
  35 @item -H,--Heigth=
  36     Set paper heigth (points). Used together with width and La@TeX{} name of
  37     papersize in case of papersize unknown to ly2dvi.
  38 @item -K,--keeplilypond
  39     Keep LilyPond output after the run.
  40 @item -L,--landscape
  41     Set landscape orientation - portrait is the default.
  42     Use together with @code{dvips -t landscape} if you run dvips
  43     separately.
  44 @item -N,--nonumber
  45     Switch off page numbering.
  46 @item -O,--orientation=
  47     Set orientation landscape - obsolete, use @strong{-L} instead.
  48 @item -P,--postscript
  49     In addition to the DVI file, also Generate a postsript file.
  50 @item -W,--Width=
  51     Set paper width (points). Used together with heigth and La@TeX{} name of
  52     papersize in case of papersize unknown to ly2dvi.
  53 @item -d,--dependencies
  54     Tell lilypond to make dependencies file.
  55 @item -h,--help
  56     Print help.
  57 @item -k,--keeply2dvi
  58     Keep the La@TeX{} file after the run.
  59 @item -l,--language=
  60     Specify La@TeX{} language.
  61     (@strong{-l norsk} produces @code{\usepackage[norsk]@{babel@}}).
  62 @item -o,--output=
  63     Set output directory.
  64 @item -p,--papersize=
  65     Specify papersize.
  66     (@strong{-p a4} produces @code{\usepackage[a4paper]@{article@}})
  67 @item -s,--separate
  68     Normally all output files are included into one La@TeX{} file.
  69     With this switch all files are run separately, to produce one
  70     DVI file for each.
  71 @end table
  72
  73
  74 @section Features
  75
  76 ly2dvi responds to several parameters specified in the lilypond
  77 file. They are overridden by corresponding command line options.
  78
  79 @table @samp
  80 @item language="";
  81     Specify La@TeX{} language
  82 @item latexheaders="";
  83     Specify additional La@TeX{} headers file
  84 @item orientation="";
  85     Set orientation.
  86 @item paperlinewidth="";
  87     Specify the width (pt, mm or cm) of the printed lines.
  88 @item papersize="";
  89     Specify name of papersize.
  90 @end table
  91
  92 @section Environment
  93
  94 @table @samp
  95 @item LILYPONDPREFIX
  96     Sets the root directory of the LilyPond installation
  97 @item LILYINCLUDE
  98     Additional directories for input files.
  99 @item TMP
 100     Temporary directory name. Default is /tmp
 101 @end table
 102
 103 @section Files
 104
 105 @file{titledefs.tex} is inspected for definitions used to extract
 106 additional text definitions from the lilypond file. In the current
 107 version the following are defined:
 108
 109 @table @samp
 110 @item title
 111     The title of the music. Centered on top of the first page.
 112 @item subtitle
 113     Subtitle, centered below the title.
 114 @item poet
 115     Name of the poet, leftflushed below the below subtitle.
 116 @item composer
 117     Name of the composer, rightflushed below the subtitle.
 118 @item metre
 119     Meter string, leftflushed below the below poet.
 120 @item opus
 121     Name of the opus, rightflushed below the below composer.
 122 @item arranger
 123     Name of the arranger, rightflushed below the opus.
 124 @item instrument
 125     Name of the instrument, centered below the arranger
 126 @item piece
 127     Name of the piece, leftflushed below the instrument
 128 @end table
 129
 130 @file{$LILYPONDPREFIX/share/.lilyrc $HOME/.lilyrc ./.lilyrc} are files
 131 to set up default running conditions.  On Windows OS initialization
 132 files are named @file{_lilyrc}. The file syntax is as follows:
 133
 134 @example
 135 VARIABLE-NAME=VALUE
 136 @end example
 137
 138
 139 Where @strong{VARIABLE-NAME} is the name of the variable documented below
 140 and @strong{VALUE} is either a string, a 1, or a 0.  All files are parsed,
 141 in the shown sequence. In the current version the following are
 142 allowed:
 143
 144 @table @samp
 145 @item DEBUG=value
 146 This turns off (default) or on the debug capabilities.  Possible
 147 values are 0 (off) and 1 (on).
 148 @item DEPENDENCIES=value
 149 This turns off (default) or on the ability to generate a Makefile
 150 dependency list.  Possible values are 0 (off) and 1 (on).
 151 @item KEEPLILYPOND=value
 152 This turns off (default) or on the ability to keep the log file
 153 associated with the LilyPond job.  Possible values are 0 (off) and 1
 154 (on).
 155 @item KEEPLY2DVI=value
 156 This turns off (default) or on the ability to keep the temporary files
 157 that are generated by the ly2dvi job.  Possible values are 0 (off) and
 158 1 (on)
 159 @item LANGUAGE=value
 160 Specify La@TeX{} language.  Possible value is a valid La@TeX{} language.
 161 @item LATEXHF=value
 162 Specify additional La@TeX{} headers file.  Possible value is a file
 163 specification.
 164 @item LILYINCLUDE=value
 165 Additional directories for input files.  Possible value is a delimited
 166 directory path list.
 167 @item LILYPONDPREFIX=value
 168 This defines the LilyPond root directory.  Possible value is a valid
 169 directory specification to the LilyPond distribution location.
 170 @item NONUMBER=value
 171 This turns off (default) or on the page numbering capability.
 172 Possible values are 0 (page numbering enabled) and 1 (page numbering
 173 disabled).
 174 @item ORIENTATION=value
 175 This sets the image orientation.  Possible values are
 176 portrait (default) and landscape.
 177 @item OUTPUTDIR=value
 178 This defines the directory where the resultant files will be
 179 generated.  Possible value is a valid directory specification.
 180 Default is the current working directory.
 181 @item PAPERSIZE=value
 182 This defines the papersize the image will be sized to fit.  Possible
 183 values are a0, a1, a2, a3, a4 (default), a5, a6, a7, a8, a9, a10, b0,
 184 b1, b2, b3, b4, b5, archA, archB, archC, archD, archE, flsa, flse,
 185 halfletter, ledger, legal, letter, or note.
 186 @item PHEIGHT=value
 187 Specify paperheight (points - an inch is 72.27, a cm is 28.453 points).
 188 @item POSTSCRIPT=value
 189 This turns off (default) or on the capability of additionally
 190 generating a postscript file.  Possible values are 0 (off) and 1 (on).
 191 @item PWIDTH=value
 192 Specify paperwidth (points - an inch is 72.27, a cm is 28.453 points).
 193 @item SEPARATE=value
 194 This turns off (default) or on the capability of generating multiple
 195 dvi and postscript files from multiple source files.  The default is
 196 to generate a concatenation of the source files.  Possible values are
 197 0 (single file) and 1 (separate files).
 198 @item TMP=value
 199 This defines the emporary directory.  Actually this is not used at the
 200 present.  Possible value is a valid directory specification that is
 201 writable to the user.
 202 @end table
 203
 204 @section Initialization Sequence
 205 The initialization process reads inputs for several sources.  Below is
 206 a list of priorities for lowest to hightest proirity.
 207
 208 @itemize @bullet
 209 @item  Program's defaults
 210 @item  Values found in LilyPond output file
 211 @item  Environment variables
 212 @item  $LILYPONDPREFIX/share/lilypond/.lilyrc
 213 @item  $HOME/.lilyrc
 214 @item  ./.lilyrc
 215 @item  command line options
 216 @end itemize
 217
 218 Note that this differs slightly from the original bourne shell
 219 version.
 220
 221 @section See Also
 222
 223 lilypond(1), tex(1), latex(1)
 224
 225 @section Bugs
 226
 227 If you have found a bug, you should send a bugreport.
 228
 229 @itemize @bullet
 230 @item Send a copy of the input which causes the error.
 231 @item Send a description of the platform you use.
 232 @item Send a description of the LilyPond and ly2dvi version you use.
 233 @item Send a description of the bug itself.
 234 @item Send it to @email{bug-gnu-music@@gnu.org} (you don't have to subscribe
 235     to this mailinglist).
 236 @end itemize
 237
 238 @section Remarks
 239
 240 Many papersizes are now supported. Information on other sizes
 241 (La@TeX{} names, horizontal and vertical sizes) should be mailed to
 242 the author or to the mailing list.
 243
 244 Supported papersizes are:
 245
 246 a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, archA, archB, archC, archD,
 247 archE, b0, b1, b2, b3, b4, b5, flsa, flse, halfletter, ledger, legal,
 248 letter, note
 249
 250 @section Authors
 251 Python Version author:
 252 @email{daboys@@austin.rr.com, Jeffrey B. Reed},
 253 @uref{http://home.austin.rr.com/jbr/jeff/lilypond/}
 254
 255 Original bourne shell version author:
 256 @email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun},
 257 @uref{http://www.termo.unit.no/mtf/people/janaf/}
 258