Documentation/ly2dvi.texi

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