Documentation/user/ly2dvi.itexi

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