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 mudela 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     (@strong{-L} produces @code{\usepackage[landscape]@{article@}})
  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 @section Features
  74
  75 ly2dvi responds to several parameters specified in the mudela
  76 file. They are overridden by corresponding command line options.
  77
  78 @table @samp
  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 @section Environment
  92
  93 @table @samp
  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 @section Files
 103
 104 @file{titledefs.tex} is inspected for definitions used to extract
 105 additional text definitions from the mudela file. In the current
 106 version the following are defined:
 107
 108 @table @samp
 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 @samp
 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 @section 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 @itemize @bullet
 208 @item  Program's defaults
 209 @item  Values found in LilyPond output file
 210 @item  Environment variables
 211 @item  $LILYPONDPREFIX/share/lilypond/.lilyrc
 212 @item  $HOME/.lilyrc
 213 @item  ./.lilyrc
 214 @item  command line options
 215 @end itemize
 216
 217 Note that this differs slightly from the original bourne shell
 218 version.
 219
 220 @section See Also
 221
 222 lilypond(1), tex(1), latex(1)
 223
 224 @section Bugs
 225
 226 If you have found a bug, you should send a bugreport.
 227
 228 @itemize @bullet
 229 @item Send a copy of the input which causes the error.
 230 @item Send a description of the platform you use.
 231 @item Send a description of the LilyPond and ly2dvi version you use.
 232 @item Send a description of the bug itself.
 233 @item Send it to @email{bug-gnu-music@@gnu.org} (you don't have to subscribe
 234     to this mailinglist).
 235 @end itemize
 236
 237 @section Remarks
 238
 239 Many papersizes are now supported. Information on other sizes
 240 (La@TeX{} names, horizontal and vertical sizes) should be mailed to
 241 the author or to the mailing list.
 242
 243 Supported papersizes are:
 244
 245 a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, archA, archB, archC, archD,
 246 archE, b0, b1, b2, b3, b4, b5, flsa, flse, halfletter, ledger, legal,
 247 letter, note
 248
 249 @section Authors
 250 Python Version author:
 251 @email{daboys@@austin.rr.com, Jeffrey B. Reed},
 252 @uref{http://home.austin.rr.com/jbr/jeff/lilypond/}
 253
 254 Original bourne shell version author:
 255 @email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun},
 256 @uref{http://www.termo.unit.no/mtf/people/janaf/}
 257