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