Documentation/README.pod

   1 =head1 NAME
   2
   3 LilyPond - a music typesetter
   4
   5 =head1 SYNOPSIS
   6
   7         lilypond [options] [inputfiles]
   8
   9 =head1 DESCRIPTION
  10
  11 LilyPond typesets music. It translates script files (mudela files or
  12 F<*.ly>'s) into TeX input.  Typesetting music is a complex task,
  13 whereas the message that printed music conveys is usually a simple
  14 one. LilyPond is a try at providing a simple interface for setting
  15 music. LilyPond has these features:
  16
  17
  18 =over 5
  19
  20 =item *
  21 ASCII script input, with identifiers (for music reuse),
  22 customizable notenames, customizable fontset
  23
  24 =item *
  25 multiple staffs in one score
  26
  27 =item *
  28 multiple stafftypes (melodic, rhythmic) [broken from  pl28 on]
  29
  30 =item *
  31 beams, slurs, chords, super/subscripts (accents and text),
  32 triplets, general n-plet (triplet, quadruplets, etc.), lyrics
  33
  34 =item *
  35 multiple voices within one staff; beams optionally shared
  36 between voices.
  37
  38 =item *
  39 multiple scores within one input file. Each score is output to
  40 a different file.
  41
  42 =item *
  43 clef changes, meter changes, cadenza-mode, declaring markings
  44 in the music, repeat bars
  45
  46 =back
  47
  48 =head1 DESIGN CONSIDERATIONS
  49
  50 LilyPond was written with some considerations in mind:
  51
  52 =over 5
  53
  54 =item *
  55 Describing a well-defined language for defining music. We call
  56 this language (rather arrogantly) The Musical Definition Language
  57 (mudela for short). LilyPond reads a mudela sourcefile and outputs a
  58 TeX file.  This musical definition language should:
  59
  60 =over 5
  61
  62 =item 1.
  63 define the musical message of the writer as unambigiously as
  64 possible.
  65
  66 =item 2.
  67 be easily readable. (as compared to, say, MusixTeX input)
  68
  69 =item 3.
  70 be writable in ASCII (with a simple texteditor).
  71
  72 =back
  73
  74 At this time, the language isn't yet defined precisely. It is evolving as
  75 LilyPond is getting more complex.
  76
  77 =item *
  78 We want to provide an easy-to-use interface for typesetting music in
  79 its broadest sense. This interface should be intuitive from a musical
  80 point of view. By broadest sense we mean: it is designed for music
  81 printed left to right in staffs, using notes to designate rythm and
  82 pitch.
  83
  84 =item *
  85 LilyPond uses MusiXTeX fonts and TeX for its output. This is not a key
  86 issue: in a future version, LilyPond might bypass TeX, but at the moment
  87 TeX is very convenient for producing output.
  88
  89 =item  *
  90 Generate high-quality output. Ideally it should be of a professional
  91 quality. We'd like to render Herbert Chlapiks words, "Fine music
  92 setting is not possible without a knowledgeable printer,"  untrue.
  93
  94 =item *
  95 LilyPond does not display notes directly, nor will it be rehacked to be
  96 used interactively. LilyPond writes output to a file.  It will not be
  97 extended to play music, or to recognize music.
  98
  99 We're thinking about adding MIDI output, though
 100
 101 =item *
 102 LilyPond is intended to run on Unix platforms, but it should
 103 be portable to any platform which can run TeX and the GNU tools
 104
 105 =item *
 106 LilyPond is free. Commercial windows packages for setting music are
 107 abundant. Free musicprinting software is scarce.
 108
 109 =item *
 110 LilyPond is written in GNU C++. It will not be downgraded/ported to fit
 111 broken systems.
 112
 113 =back
 114
 115
 116
 117 =head1 OPTIONS
 118
 119 =over 5
 120
 121 =item   B<-I,--include>=F<FILE>
 122
 123 add F<FILE> to the search path for input files.
 124
 125 =item   B<-d,--debug>,
 126
 127 debugging. LilyPond will read the file F<.dstreamrc>, which tells for what functions to produce copious debugging output.
 128
 129 =item   B<-w,--warranty>,
 130
 131 Show the warranty with which LilyPond comes. (It comes with B<NO WARRANTY>!)
 132
 133 =item  B<-o,--output=>F<FILE>,
 134
 135 Set the default output file to F<FILE>.
 136
 137 =item   B<-h,--help>,
 138
 139 Show a summary of usage
 140
 141 =item   B<--init, -i>
 142
 143 set init file (default: symbol.ini)
 144
 145 =item B<--include, -I>
 146 add to file search path.
 147
 148 =back
 149
 150 =head1
 151 DISCLAIMER & COPYING POLICY
 152
 153 LilyPond is copyright 1996,97 by its authors. LilyPond is
 154 distributed under the terms of the GNU General Public
 155 License. LilyPond is provided without any warranty what so ever.
 156 LilyPond may be freely distributed.  For further information consult
 157 the GNU General Public License, which is in the file F<COPYING>
 158
 159 =head1 PREREQUISITES
 160
 161 Compilation:
 162
 163 =over 5
 164
 165 =item *
 166  Unix. Any decent Linux distribution is fine. LilyPond is known to run
 167 on Linux, AIX, Digital Unix and Solaris
 168
 169 =item *
 170 GNU C++ v2.7  or better, with libg++. Version 2.7.2 or better recommended.
 171
 172 =item *
 173 GNU make.
 174
 175 =item *
 176 flex (2.5.1 or better)
 177
 178 =item *
 179 Bison or YACC.
 180
 181 =item *
 182 The "Flower" library, which should be available from the same
 183 source you got this from.
 184
 185 =item *
 186 perl.  The Makefile uses perl for trivial operations, and you
 187 could tinker with it to use sed or awk.
 188
 189 =back
 190
 191 LilyPond does use a lot of resources. For operation you need the following:
 192
 193 =over 5
 194
 195 =item *
 196 TeX
 197
 198 =item *
 199 The MusixTeX fonts. (I use version T.59)
 200
 201 =back
 202
 203 =head1 COMPILING
 204
 205 Do:
 206
 207         tar zxf flower-1.11.9.tar.gz
 208         tar zxf lilypond-1.2.13.tar.gz
 209         cd lilypond-1.2.13
 210         configure
 211         make
 212
 213 You might want to edit Variables.make to tailor the compilation flags.
 214 why G++ >= 2.7? LilyPond & flower lib uses:
 215
 216 =over 5
 217
 218 =item *
 219 builtin bool
 220
 221 =item *
 222 typeof
 223
 224 =item *
 225 operator <?, operator >?
 226
 227 =item *
 228 the new for-scope
 229
 230 =item    *
 231 class Rational (libg++)
 232
 233 =item *
 234 named return values
 235
 236 =back
 237
 238 =head1 AUTHORS
 239
 240 =over 5
 241
 242 =item *
 243 Han-Wen Nienhuys <hanwen@stack.nl>, Main author
 244
 245 =item *
 246 Jan Nieuwenhuizen <jan@digicash.com>, Context errors, Lyrics,
 247 bits of FlowerLib, general comments.
 248
 249 =item *
 250 Mats Bengtsson <matsb@s3.kth.se>, bugfixes, testing, general comments.
 251
 252 =back
 253
 254 Your name could be here! If you want to help, then take a look at the
 255 SMALLISH PROJECTS section of in the file F<TODO>. Some do not involve
 256 coding C++
 257
 258 =head1 EXAMPLES
 259
 260 At this time, LilyPond output looks nice, but is not of production
 261 quality. If you're not discouraged; this is what I type in my xterm:
 262
 263         lilypond someinput.ly
 264         tex test
 265         xdvi test&
 266
 267 This is what the output looks like over here:
 268
 269         hw:~/musix/spacer$ lilypond input/maartje.ly
 270         LilyPond 0.0.27/FlowerLib 1.0.23. Compile: Feb  5 1997, 00:28:13 (g++ 2.7.2)
 271         Parsing ... [./init//symbol.ini[./init/dutch.ini][./init/script.ini][./init/table_sixteen.ini]][./input/maartje.ly]
 272         Processing music ... Preprocessing ... Calculating ... Postprocessing ...
 273         output to lelie.out...
 274
 275         hw:~/musix/spacer$ tex test
 276         This is TeX, Version 3.14159 (C version 6.1)
 277         (test.tex
 278         Hyphenation patterns for english, dutch, loaded.
 279         (lilyponddefs.tex) (lelie.uit) [1] [2] )
 280         Output written on test.dvi (2 pages, 8420 bytes).
 281         Transcript written on test.log.
 282
 283         hw:~/musix/spacer$ xdvi test&
 284         [1] 855
 285
 286 Check out F<kortjakje.ly>, it has some comments
 287
 288
 289 =head1 PROBLEMS
 290
 291 If LilyPond bombs out, then please recompile using B<-g>, and send a
 292 copy of the input which causes the error and a gdb stacktrace of the
 293 crash. It also helps if you can print the values of the objects. So if
 294 your trace is
 295
 296         (gdb) backtrace 12
 297         #0  Interval::operator+= (this=0x11fffec60..)
 298             at ../flower/interval.hh:50
 299         #1  0x12005195c in Item::width (this=0x14008a680) at src/item.cc:39
 300         #2  0x12008fdbc in itemlist_width (its=0x11fffed58 ..
 301           :
 302           :
 303
 304 Than it would help if you send a dump of the Interval and the Item
 305 (use: C<print *this> or use LilyPond C<print()> methods).
 306
 307 This is a beta version of LilyPond. Please send your helpful comments
 308 and patches to me (see AUTHORS section)
 309
 310 LilyPond is updated very frequently, the latest version is always available at:
 311 ftp://pcnov095.win.tue.nl/pub/lilypond.
 312
 313
 314 =head1 FILES
 315
 316 =over 5
 317
 318 =item F<symbol.ini>
 319 The initialisation file with symbol tables etc. It
 320 includes files from the directory F<init/>.
 321
 322 =back
 323
 324 =head1 SEE ALSO
 325
 326 There are some documentation files  in the subdirectory F<Documentation/>,
 327 among others: lilygut, lilyinput, error, faq,
 328
 329 =head1  REMARKS
 330
 331 LilyPond has no connection with the music package RoseGarden, other
 332 than the names being similar.
 333
 334
 335 =head1 HISTORY
 336
 337 (for a  detailed changelog, see F<NEWS>)
 338
 339 LilyPond's roots lie in MPP, a preprocessor to the rather arcane
 340 MusiXTeX macro package for TeX. A friend of mine, Jan Nieuwenhuizen
 341 wrote the first 44 versions (0.01 to 0.44), then his program caught my
 342 attention, and I was slowly sucked in to the interesting problem of
 343 easily producing beautifully printed music. I contributed some
 344 code. We soon realised that MPP's design was too fundamentally broken
 345 to be repaired. It was decided to rewrite MPP.  We debated a lot about
 346 the requirements to an inputformat (fall 1995). I sat down and started
 347 with a parser-first, bottom-up rewrite called mpp95 (which totally
 348 failed, obviously).
 349
 350 After long and hard thinking, I came up with an algorithm for the
 351 horizontal spacing of multiple staffs (april 1996) I coded it (and did
 352 not test it). After starting with this fundamental piece, I slowly
 353 added the stages which come before spacing, and after.  A half year
 354 later later, I had a first working version, (october 1996).  I
 355 announced Patchlevel 0.0.7 (or 8) to the mutex list after asking some
 356 technical details on spacing; it was downloaded approximately 4 times.
 357 Then I got the hang of it, and in the subsequent two months, I coded
 358 until it had doubled in size (pl 23).