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
 152 =head1 PROBLEMS
 153
 154
 155 There is an extensive list of todoes and bugs. See F<TODO>. In
 156 general, try to find out
 157
 158 =over 4
 159
 160 =item *
 161
 162 if the bug has been fixed in a newer release.
 163
 164 =item *
 165
 166 if the bug has been found earlier, consult F<TODO>
 167
 168 =item *
 169
 170 where the bug comes from: if GNU LilyPond bombs out, then please
 171 recompile using with debugging info turned on, and send a copy of the
 172 input which causes the error and a gdb stacktrace of the crash. It
 173 also helps if you can print the values of the objects. So if your
 174 trace is
 175
 176         (gdb) backtrace 12
 177         #0  Interval::operator+= (this=0x11fffec60..)
 178             at ../flower/interval.hh:50
 179         #1  0x12005195c in Item::width (this=0x14008a680) at src/item.cc:39
 180         #2  0x12008fdbc in itemlist_width (its=0x11fffed58 ..
 181           :
 182           :
 183
 184 Than it would help if you send a dump of the Interval and the Item
 185 (use: C<print *this> or use LilyPond C<print()> methods).
 186
 187 =back
 188
 189 Bug reports should be directed to:
 190 bug-gnu-music@vuse.vanderbilt.edu. In any case, they should contain a
 191 description of the problem, a small input file which reproduces it (if
 192 applicable), the lilypond version and a description of the platform.
 193
 194
 195 =head1 FILES
 196
 197 =over 5
 198
 199 =item F<symbol.ini>
 200
 201 The initialisation file with symbol tables etc. It
 202 includes files from the directory F<init/>.
 203
 204 =back
 205
 206 =head1 ENVIRONMENT
 207
 208 B<LILYINCLUDE> an (one) additional directory for finding lilypond data.
 209
 210 =head1 BUGS
 211
 212 =head1 SEE ALSO
 213
 214 =over 4
 215
 216 =item lilygut
 217
 218 On technical details of LilyPond
 219
 220 =item mudela(5)
 221
 222 On the input format
 223
 224 =item MANIFESTO
 225
 226 Goals of the GNU LilyPond project.
 227
 228 =item FAQ
 229
 230 The GNU LilyPond FAQ list
 231
 232 =item http://
 233
 234 The GNU Music project. GNU LilyPond is part of the GNU Music
 235 project. For more information on the GNU Music project,
 236
 237 =item http://www.stack.nl/~hanwen/lilypond/index.html
 238
 239 GNU LilyPond has her own webpage.  This webpage contains the MIDI, GIF
 240 and PS files for some standard music files. It also has the complete
 241 LilyPond documentation
 242
 243
 244 =back
 245
 246 GNU LilyPond is
 247 updated very frequently, the latest version is always available at:
 248 ftp://pcnov095.win.tue.nl/pub/lilypond.
 249
 250 For programs which part of the GNU music project, the following mailing list
 251 have been setup:
 252
 253
 254 =over 4
 255
 256 =item info-gnu-music@vuse.vanderbilt.edu
 257
 258 For information on the GNU Music project, to subscribe: send mail with
 259 subject "subscribe" to info-gnu-music-request@vuse.vanderbilt.edu
 260
 261 =item help-gnu-music@vuse.vanderbilt.edu
 262
 263 For help with programs from the GNU music project. To subscribe: send
 264 mail with subject "subscribe" to
 265 help-gnu-music-request@vuse.vanderbilt.edu
 266
 267 =item bug-gnu-music@vuse.vanderbilt.edu
 268
 269 If you have bugreports, you should send them to this list. If you want
 270 to read all bugreports, you should subscribe to this list.  To
 271 subscribe: send mail with subject "subscribe" to
 272 bug-gnu-music-request@vuse.vanderbilt.edu
 273
 274 =item gnu-music-discuss@vuse.vanderbilt.edu,
 275
 276 For discussions concerning the GNU Music project, to subscribe: send
 277 mail with subject "subscribe" to
 278 gnu-music-discuss-request@vuse.vanderbilt.edu,
 279
 280
 281 =back
 282
 283 Announces of new versions will be sent to info-gnu-music and
 284 gnu-music-discuss.
 285
 286 =head1  REMARKS
 287
 288 GNU LilyPond has no connection with the music package Rosegarden, other
 289 than the names being similar :-)
 290
 291 =head1 HISTORY
 292
 293 (for a  detailed changelog, see F<NEWS>)
 294
 295 GNU LilyPond's roots lie in MPP, a preprocessor to the rather arcane
 296 MusiXTeX macro package for TeX. A friend of mine, Jan Nieuwenhuizen
 297 wrote the first 44 versions (0.01 to 0.44), then his program caught my
 298 attention, and I was slowly sucked in to the interesting problem of
 299 easily producing beautifully printed music. I contributed some
 300 code. We soon realised that MPP's design was too fundamentally broken
 301 to be repaired. It was decided to rewrite MPP.  We debated a lot about
 302 the requirements to an inputformat (fall 1995). I sat down and started
 303 with a parser-first, bottom-up rewrite called mpp95 (which totally
 304 failed, obviously).
 305
 306 After long and hard thinking, I came up with an algorithm for the
 307 horizontal spacing of multiple staffs (april 1996) I coded it (and did
 308 not test it). After starting with this fundamental piece, I slowly
 309 added the stages which come before spacing, and after.  A half year
 310 later, I had a first working version, (october 1996).  I announced
 311 Patchlevel 0.0.7 (or 8) to the mutex list after asking some technical
 312 details on spacing; it was downloaded approximately 4 times.  Then I
 313 got the hang of it, and in the subsequent two months, I coded until it
 314 had doubled in size (pl 23).