Documentation/programs.texi

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