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 GNU LilyPond which converts music definition files into visual or
  12 audio output: it can produce formatted sheet music in TeX and
  13 and mechanical perfomances to MIDI files.
  14
  15 =head1 OPTIONS
  16
  17 =over 5
  18
  19 =item B<-I,--include>=F<FILE>,
  20
  21 add F<FILE> to the search path for input files.
  22
  23
  24 =item B<-M,--midi>
  25
  26 do midi output only
  27
  28 =item B<-d,--debug>,
  29
  30 Turn debugging info. GNU LilyPond will read the file F<.dstreamrc>, which
  31 tells for what functions and classes may produce copious debugging
  32 output.
  33
  34 =item B<-w,--warranty>,
  35
  36 Show the warranty with which GNU LilyPond comes. (It comes with B<NO
  37 WARRANTY>!)
  38
  39 =item B<-o,--output=>F<FILE>,
  40
  41 Set the default output file to F<FILE>.
  42
  43 =item B<-h,--help>,
  44
  45 Show a summary of usage
  46
  47 =item B<-i,--init=>F<FILE>
  48
  49 set init file to F<FILE> (default: F<symbol.ini>)
  50
  51 =item B<--include, -I>=F<DIRECTORY>
  52
  53 add F<DIRECTORY> to the search path for input files.
  54
  55 =back
  56
  57 =head1 FEATURES
  58
  59 This is an overview of the features that GNU LilyPond supports. For
  60 details on how to use them, you should consult mudela(5)
  61
  62 =over 5
  63
  64 =item *
  65
  66 ASCII script input, with identifiers (for music reuse),
  67 customizable notenames, customizable fontset
  68
  69 =item *
  70
  71 MIDI output lets you check if you have entered the correct notes.
  72
  73 =item *
  74
  75 MIDI to Mudela conversion through the mi2mu program.
  76
  77 =item *
  78
  79 Multiple staffs in one score. Each staff can have a different meters.
  80
  81 =item *
  82
  83 beams, slurs, ties, chords, super/subscripts (accents and text),
  84 triplets, general n-plet (triplet, quadruplets, etc.), lyrics,
  85 transposition dynamics (both absolute and hairpin style)
  86
  87 =item *
  88
  89 multiple voices within one staff; beams optionally shared
  90 between voices. Up to four voices is handled cleanly.
  91
  92 =item *
  93
  94 multiple scores within one input file. Each score is output to
  95 a different file.
  96
  97 =item *
  98
  99 clef changes, meter changes, cadenza-mode, key changes, repeat bars
 100
 101 =back
 102
 103 =head1 DISCLAIMER & COPYING POLICY
 104
 105 GNU LilyPond is copyright 1996,97 by its authors. GNU LilyPond is
 106 distributed under the terms of the GNU General Public
 107 License. GNU LilyPond is provided without any warranty what so ever.
 108 GNU LilyPond may be freely distributed.  For further information consult
 109 the GNU General Public License, which is in the file F<COPYING>
 110
 111 =head1 AUTHORS
 112
 113 Please consult the documentation file AUTHORS for more detailed
 114 information, and small contributions.
 115
 116 =over 4
 117
 118 =item *
 119
 120 Han-Wen Nienhuys <hanwen@stack.nl>, http://www.stack.nl/~hanwen
 121
 122 =item *
 123
 124 Jan Nieuwenhuizen <jan@digicash.com>,  http://www.digicash.com/~jan.
 125
 126 =back
 127
 128
 129 =head1 PROBLEMS
 130
 131
 132 There is an extensive list of todoes and bugs. See F<TODO>. In
 133 general, try to find out
 134
 135 =over 4
 136
 137 =item *
 138
 139 if the bug has been fixed in a newer release.
 140
 141 =item *
 142
 143 if the bug has been found earlier, consult F<TODO> and F<BUGS>
 144
 145 =back
 146
 147 If you have found a bug, then you should send a bugreport.
 148
 149         - send a copy of the input which causes the error
 150         - send a description of the platform you use
 151         - send a description of the LilyPond version you use (with
 152         compile/config options please)
 153         - send a description of the bug itself.
 154         - send it to bug-gnu-music@vuse.vanderbilt.edu
 155
 156 It does help if you can find out where the bug comes from: if GNU
 157 LilyPond bombs out, then please recompile using with debugging info
 158 turned on, and send gdb stacktrace of the crash. It also helps if you
 159 can print the values of the objects. So if your trace is
 160
 161         received SIGSEGV
 162         (gdb) backtrace 12
 163         #0  Interval::operator+= (this=0x11fffec60..)
 164             at ../flower/interval.hh:50
 165         #1  0x12005195c in Item::width (this=0x14008a680) at src/item.cc:39
 166         #2  0x12008fdbc in itemlist_width (its=0x11fffed58 ..
 167           :
 168           :
 169
 170 Than it would help if you send a dump of the Interval and the Item
 171 (use: C<print *this> or use LilyPond C<print()> methods).
 172
 173
 174 =head1 FILES
 175
 176 =over 5
 177
 178 =item F<symbol.ini>
 179
 180 The initialisation file with symbol tables etc. It
 181 includes files from the directory F<init/>.
 182
 183 =back
 184
 185 =head1 ENVIRONMENT
 186
 187 B<LILYINCLUDE> an (one) additional directory for finding lilypond data.
 188
 189 =head1 BUGS
 190
 191 =head1 SEE ALSO
 192
 193 =over 4
 194
 195 =item lilygut
 196
 197 On technical details of LilyPond
 198
 199 =item mudela(5)
 200
 201 On the input format
 202
 203 =item MANIFESTO
 204
 205 Goals of the GNU LilyPond project.
 206
 207 =item FAQ
 208
 209 The GNU LilyPond FAQ list
 210
 211 =item http://
 212
 213 The GNU Music project. GNU LilyPond is part of the GNU Music
 214 project. For more information on the GNU Music project,
 215
 216 =item http://www.stack.nl/~hanwen/lilypond/index.html
 217
 218 GNU LilyPond has her own webpage.  This webpage contains the MIDI, GIF
 219 and PS files for some standard music files. It also has the complete
 220 LilyPond documentation
 221
 222
 223 =back
 224
 225 GNU LilyPond is
 226 updated very frequently, the latest version is always available at:
 227 ftp://pcnov095.win.tue.nl/pub/lilypond.
 228
 229 For programs which are part of the GNU music project, the following
 230 mailing list have been setup:
 231
 232
 233 =over 4
 234
 235 =item info-gnu-music@vuse.vanderbilt.edu
 236
 237 For information on the GNU Music project, to subscribe: send mail with
 238 subject "subscribe" to info-gnu-music-request@vuse.vanderbilt.edu
 239
 240 =item help-gnu-music@vuse.vanderbilt.edu
 241
 242 For help with programs from the GNU music project. To subscribe: send
 243 mail with subject "subscribe" to
 244 help-gnu-music-request@vuse.vanderbilt.edu
 245
 246 =item bug-gnu-music@vuse.vanderbilt.edu
 247
 248 If you have bugreports, you should send them to this list. If you want
 249 to read all bugreports, you should subscribe to this list.  To
 250 subscribe: send mail with subject "subscribe" to
 251 bug-gnu-music-request@vuse.vanderbilt.edu
 252
 253 =item gnu-music-discuss@vuse.vanderbilt.edu,
 254
 255 For discussions concerning the GNU Music project, to subscribe: send
 256 mail with subject "subscribe" to
 257 gnu-music-discuss-request@vuse.vanderbilt.edu,
 258
 259
 260 =back
 261
 262 Announces of new versions will be sent to info-gnu-music and
 263 gnu-music-discuss.
 264
 265 =head1  REMARKS
 266
 267 GNU LilyPond has no connection with the music package Rosegarden, other
 268 than the names being similar :-)
 269
 270 =head1 HISTORY
 271
 272 (for a  detailed changelog, see F<NEWS>)
 273
 274 GNU LilyPond's roots lie in MPP, a preprocessor to the rather arcane
 275 MusiXTeX macro package for TeX. A friend of mine, Jan Nieuwenhuizen
 276 wrote the first 44 versions (0.01 to 0.44), then his program caught my
 277 attention, and I was slowly sucked in to the interesting problem of
 278 easily producing beautifully printed music. I contributed some
 279 code. We soon realised that MPP's design was too fundamentally broken
 280 to be repaired, so it was decided to rewrite MPP.  We debated a lot about
 281 the requirements to an inputformat (fall 1995). I sat down and started
 282 with a parser-first, bottom-up rewrite called mpp95 (which totally
 283 failed, obviously).
 284
 285 After long and hard thinking, I came up with an algorithm for the
 286 horizontal spacing of multiple staffs (april 1996) I coded it (and did
 287 not test it). After starting with this fundamental piece, I slowly
 288 added the stages which come before spacing, and after.  A half year
 289 later, I had a first working version, (october 1996).  I announced
 290 Patchlevel 0.0.7 (or 8) to the mutex list after asking some technical
 291 details on spacing; it was downloaded approximately 4 times.  Then I
 292 got the hang of it, and in the subsequent two months, I coded until it
 293 had doubled in size (pl 23).
 294
 295 The first large scale release (0.1) was planned after approximately 80
 296 patchlevels on August 1, 1997.