Documentation/lilypond.pod

   1 =head1 NAME
   2
   3 lilypond - the GNU music typesetter
   4
   5 =head1 SYNOPSIS
   6
   7         lilypond [options] [inputfiles]
   8
   9 =head1 DESCRIPTION
  10
  11 Technically GNU LilyPond is a preprocessor which generates TeX
  12 (or LaTeX) output which contains information to typeset a musical
  13 score. Practically it is a typesetter, which only uses TeX as an
  14 output medium. (this is handy because there exist music fonts for TeX)
  15
  16 As a bonus, you can also output a MIDI file of what you typed.
  17
  18 It translates script files (mudela files or F<*.ly>'s) into TeX input.
  19 Typesetting music is a complex task, whereas the message that printed
  20 music conveys is usually a simple one. GNU LilyPond is a try at providing
  21 a simple interface for setting music.
  22
  23 =head1 OPTIONS
  24
  25 =over 5
  26
  27 =item B<-I,--include>=F<FILE>,
  28
  29 add F<FILE> to the search path for input files.
  30
  31
  32 =item B<-M,--midi>
  33
  34 do midi output only
  35
  36 =item B<-d,--debug>,
  37
  38 Turn debugging info. GNU LilyPond will read the file F<.dstreamrc>, which
  39 tells for what functions and classes may produce copious debugging
  40 output.
  41
  42 =item B<-w,--warranty>,
  43
  44 Show the warranty with which GNU LilyPond comes. (It comes with B<NO
  45 WARRANTY>!)
  46
  47 =item B<-o,--output=>F<FILE>,
  48
  49 Set the default output file to F<FILE>.
  50
  51 =item B<-h,--help>,
  52
  53 Show a summary of usage
  54
  55 =item B<-i,--init=>F<FILE>
  56
  57 set init file to F<FILE> (default: F<symbol.ini>)
  58
  59 =item B<--include, -I>=F<DIRECTORY>
  60
  61 add F<DIRECTORY> to the search path for input files.
  62
  63 =back
  64
  65 =head1 FEATURES
  66
  67 This is an overview of the features that GNU LilyPond supports. For
  68 details on how to use them, you should consult mudela(5)
  69
  70 =over 5
  71
  72 =item *
  73
  74 ASCII script input, with identifiers (for music reuse),
  75 customizable notenames, customizable fontset
  76
  77 =item *
  78
  79 MIDI output lets you check if you have entered the correct notes.
  80
  81 =item *
  82
  83 MIDI to Mudela conversion through the mi2mu program.
  84
  85 =item *
  86
  87 Multiple staffs in one score. Each staff can have a different meters.
  88
  89 =item *
  90
  91 multiple stafftypes (melodic, rhythmic) [broken from  pl28 on]
  92
  93 =item *
  94
  95 beams, slurs, ties, chords, super/subscripts (accents and text),
  96 triplets, general n-plet (triplet, quadruplets, etc.), lyrics,
  97 transposition dynamics (both absolute and hairpin style)
  98
  99 =item *
 100
 101 multiple voices within one staff; beams optionally shared
 102 between voices. Up to four voices is handled cleanly.
 103
 104 =item *
 105
 106 multiple scores within one input file. Each score is output to
 107 a different file.
 108
 109 =item *
 110
 111 clef changes, meter changes, cadenza-mode, key changes, repeat bars
 112
 113 =back
 114
 115 =head1 DISCLAIMER & COPYING POLICY
 116
 117 GNU LilyPond is copyright 1996,97 by its authors. GNU LilyPond is
 118 distributed under the terms of the GNU General Public
 119 License. GNU LilyPond is provided without any warranty what so ever.
 120 GNU LilyPond may be freely distributed.  For further information consult
 121 the GNU General Public License, which is in the file F<COPYING>
 122
 123 =head1 AUTHORS
 124
 125 Please consult the documentation file AUTHORS for more detailed
 126 information, and small contributions.
 127
 128 =over 4
 129
 130 =item *
 131
 132 Han-Wen Nienhuys <hanwen@stack.nl>, http://www.stack.nl/~hanwen
 133
 134 Main author
 135
 136 =item *
 137
 138 Jan Nieuwenhuizen <jan@digicash.com>,  http://www.digicash.com/~jan.
 139
 140 Context errors, Lyrics, mi2mu, MIDI stuff, make structure, bits of
 141 FlowerLib, general comments, Mudela design.
 142
 143 =back
 144
 145 Your name could be here! If you want to help, then take a look at the
 146 SMALLISH PROJECTS section of in the file F<TODO>. Some do not involve
 147 coding C++
 148
 149 =head1 EXAMPLES
 150
 151 At this time, GNU LilyPond output looks nice, but is not of production
 152 quality. If you're not discouraged; this is what I type in my xterm:
 153
 154         lilypond someinput.ly
 155         tex lelie.tex
 156         xdvi test&
 157
 158 This is what the output looks like over here:
 159
 160         hw:~/musix/spacer$ GNU LilyPond 0.0.60 #8/FlowerLib 1.1.14 #2
 161         Parsing ... [./input/kortjakje.ly[lots of stuff]]
 162         Setting up requests...Processing requests ...[8][16][24][25]
 163         Preprocessing elements...
 164         Calculating column positions ... [3][7][12][16][20][25]
 165         Postprocessing elements...
 166         TeX output to lelie.tex ...
 167
 168         hw:~/musix/spacer$ tex lelie
 169         This is TeX, Version 3.14159 (C version 6.1)
 170         (lelie.tex
 171         Hyphenation patterns for english, dutch, german, loaded.
 172         (/home/hw/lib/texmf/tex/lilypond/lilyponddefs.tex) [1] )
 173         Output written on lelie.dvi (1 page, 8944 bytes).
 174         Transcript written on lelie.log.
 175
 176         hw:~/musix/spacer$ xdvi lelie&
 177         [1] 855
 178
 179 Check out the input files, some of them have comments
 180
 181
 182 =head1 PROBLEMS
 183
 184
 185 There is an extensive list of todoes and bugs. See F<TODO>. In
 186 general, try to find out
 187
 188 =over 4
 189
 190 =item *
 191
 192 if the bug has been fixed in a newer release.
 193
 194 =item *
 195
 196 if the bug has been found earlier, consult F<TODO>
 197
 198 =item *
 199
 200 where the bug comes from: if GNU LilyPond bombs out, then please
 201 recompile using with debugging info turned on, and send a copy of the
 202 input which causes the error and a gdb stacktrace of the crash. It
 203 also helps if you can print the values of the objects. So if your
 204 trace is
 205
 206         (gdb) backtrace 12
 207         #0  Interval::operator+= (this=0x11fffec60..)
 208             at ../flower/interval.hh:50
 209         #1  0x12005195c in Item::width (this=0x14008a680) at src/item.cc:39
 210         #2  0x12008fdbc in itemlist_width (its=0x11fffed58 ..
 211           :
 212           :
 213
 214 Than it would help if you send a dump of the Interval and the Item
 215 (use: C<print *this> or use GNU LilyPond C<print()> methods).
 216
 217 =back
 218
 219 Bug reports should be directed to
 220 bug-gnu-music@vuse.vanderbilt.edu. In any case, they should contain a
 221 description of the problem, an small input file which reproduces it
 222 (if applicable), lilypond version and a description of the platform.
 223
 224
 225 =head1 FILES
 226
 227 =over 5
 228
 229 =item F<symbol.ini>
 230
 231 The initialisation file with symbol tables etc. It
 232 includes files from the directory F<init/>.
 233
 234 =back
 235
 236 =head1 ENVIRONMENT
 237
 238 B<LILYINCLUDE> an (one) additional directory for finding lilypond data.
 239
 240 =head1 BUGS
 241
 242 =head1 SEE ALSO
 243
 244 =over 4
 245
 246 =item lilygut
 247
 248 On technical details of LilyPond
 249
 250 =item mudela(5)
 251
 252 On the input format
 253
 254 =item MANIFESTO
 255
 256 Goals of the GNU LilyPond project.
 257
 258 =item FAQ
 259
 260 The GNU LilyPond FAQ list
 261
 262 =item http://
 263
 264 The GNU Music project. GNU LilyPond is part of the GNU Music
 265 project. For more information on the GNU Music project,
 266
 267 =item http://www.stack.nl/~hanwen/lilypond/index.html
 268
 269 GNU LilyPond has her own webpage at
 270 This webpage contains
 271 the MIDI, GIF and PS files for some standard music files. It also has
 272 the complete LilyPond documentation
 273
 274
 275 =back
 276
 277 GNU LilyPond is
 278 updated very frequently, the latest version is always available at:
 279 ftp://pcnov095.win.tue.nl/pub/lilypond.
 280
 281 For programs which part of the GNU music project, the following mailing list
 282 have been setup:
 283
 284
 285 =over 4
 286
 287 =item info-gnu-music@vuse.vanderbilt.edu
 288
 289 For information on the GNU Music project, to subscribe: send mail with
 290 subject "subscribe" to info-gnu-music-request@vuse.vanderbilt.edu
 291
 292 =item help-gnu-music@vuse.vanderbilt.edu
 293
 294 For help with programs from the GNU music project. To subscribe: send
 295 mail with subject "subscribe" to
 296 help-gnu-music-request@vuse.vanderbilt.edu
 297
 298 =item bug-gnu-music@vuse.vanderbilt.edu
 299
 300 If you have bugreports, you should send them to this list. If you want
 301 to read all bugreports, you should subscribe to this list.  To
 302 subscribe: send mail with subject "subscribe" to
 303 bug-gnu-music-request@vuse.vanderbilt.edu
 304
 305 =item gnu-music-discuss@vuse.vanderbilt.edu,
 306
 307 For discussions concerning the GNU Music project, to subscribe: send
 308 mail with subject "subscribe" to
 309 gnu-music-discuss-request@vuse.vanderbilt.edu,
 310
 311 =back
 312
 313 =head1  REMARKS
 314
 315 GNU LilyPond has no connection with the music package Rosegarden, other
 316 than the names being similar :-)
 317
 318 =head1 HISTORY
 319
 320 (for a  detailed changelog, see F<NEWS>)
 321
 322 GNU LilyPond's roots lie in MPP, a preprocessor to the rather arcane
 323 MusiXTeX macro package for TeX. A friend of mine, Jan Nieuwenhuizen
 324 wrote the first 44 versions (0.01 to 0.44), then his program caught my
 325 attention, and I was slowly sucked in to the interesting problem of
 326 easily producing beautifully printed music. I contributed some
 327 code. We soon realised that MPP's design was too fundamentally broken
 328 to be repaired. It was decided to rewrite MPP.  We debated a lot about
 329 the requirements to an inputformat (fall 1995). I sat down and started
 330 with a parser-first, bottom-up rewrite called mpp95 (which totally
 331 failed, obviously).
 332
 333 After long and hard thinking, I came up with an algorithm for the
 334 horizontal spacing of multiple staffs (april 1996) I coded it (and did
 335 not test it). After starting with this fundamental piece, I slowly
 336 added the stages which come before spacing, and after.  A half year
 337 later, I had a first working version, (october 1996).  I announced
 338 Patchlevel 0.0.7 (or 8) to the mutex list after asking some technical
 339 details on spacing; it was downloaded approximately 4 times.  Then I
 340 got the hang of it, and in the subsequent two months, I coded until it
 341 had doubled in size (pl 23).