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