Documentation/user/ly2dvi.itexi

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