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 * ASCII script input, with identifiers (for music reuse),
  21 customizable notenames, customizable fontset
  22
  23 =item *
  24 multiple staffs in one score
  25
  26 =item *
  27 multiple stafftypes (melodic, rhythmic)
  28
  29 =item *
  30 beams, slurs, chords, super/subscripts (accents and text),
  31 triplets, clef changes, meter changes, general n-plet (triplet,
  32 quadruplets, etc.)
  33
  34 =item *
  35 multiple scores within one input file. Each score is output to
  36 a different file.
  37
  38 =back
  39
  40 =head1 DESIGN CONSIDERATIONS
  41
  42 LilyPond was written with some
  43 considerations in mind:
  44
  45 =over 5
  46
  47 =item *
  48 Describing a well-defined language for defining music. We call this
  49 language (rather arrogantly) The Musical Definition Language (mudela
  50 for short). LilyPond reads a mudela sourcefile
  51 and outputs a TeX file.  This musical definition language should:
  52
  53 =over 5
  54
  55 =item 1
  56 define the musical message of the writer as unambigiously as
  57 possible.
  58
  59 =item 2
  60 be easily readable. (as compared to, say, MusixTeX input)
  61
  62 =item 3
  63 be writable in ASCII (with a simple texteditor).
  64
  65 =back
  66
  67 At this time, the language isn't yet defined precisely. It is evolving as
  68 LilyPond is getting more complex.
  69
  70 =item *
  71 We want to provide an easy-to-use interface for typesetting music in
  72 its broadest sense. This interface should be intuitive from a musical
  73 point of view. By broadest sense we mean: it is designed for music
  74 printed left to right in staffs, using notes to designate rythm and
  75 pitch.
  76
  77 =item *
  78 LilyPond uses MusiXTeX fonts and TeX for its output. This is not a key
  79 issue: in a future version, LilyPond might bypass TeX, but at the moment
  80 TeX is very convenient for producing output.
  81
  82 =item  *
  83  Generate high-quality output. Ideally it should be of a professional
  84 quality. We'd like to render Herbert Chlapiks words, "Fine music
  85 setting is not possible without a knowledgeable printer,"  untrue.
  86
  87 =item *
  88 LilyPond does not display notes directly, nor will it be rehacked to be
  89 used interactively. LilyPond writes output to a file.  It will not be
  90 extended to play music, or to recognize music.
  91
  92 We're thinking about adding MIDI output, though
  93
  94 =item *
  95 LilyPond is intended to run on Unix platforms, but it should
  96 be portable to any platform which can run TeX and the GNU tools
  97
  98 =item *
  99 LilyPond is free. Commercial windows packages for setting music are
 100 abundant. Free musicprinting software is scarce.
 101
 102 =item *
 103 LilyPond is written in GNU C++. It will not be downgraded/ported to fit
 104 broken systems.
 105
 106 =back
 107
 108
 109
 110 =head1 OPTIONS
 111
 112 =over 5
 113
 114 =item   B<-d,--debug>,
 115
 116 debugging. LilyPond will read the file F<.dstreamrc>, which tells for what functions to produce copious debugging output.
 117
 118 =item   B<-w,--warranty>,
 119
 120 warranty
 121
 122 =item  B<-o,--output>,
 123
 124 default output file
 125
 126 =item   B<-h,--help>,
 127
 128 help
 129
 130 =back
 131
 132 =head1
 133 DISCLAIMER & COPYING POLICY
 134
 135 LilyPond is copyright 1996,97 by its authors. LilyPond is
 136 distributed under the terms of the GNU General Public
 137 License. LilyPond is provided without any warranty what so ever.
 138 LilyPond may be freely distributed.  For further information consult
 139 the GNU General Public License, which is in the file F<COPYING>
 140
 141 =head1 PREREQUISITES
 142
 143 Compilation:
 144
 145 =over 5
 146
 147 =item *
 148  Unix. Any decent Linux distribution is fine. LilyPond is known to run
 149 on Linux and Solaris
 150
 151 =item *
 152  GNU C++ v2.7  or better (with libg++ )
 153
 154 =item *
 155  GNU make.
 156
 157 =item *
 158  flex (2.5.1 or better)
 159
 160 =item *
 161 bison/yacc
 162
 163 =item *
 164 The "flower" library,
 165 which should be available from the
 166 same source you got this from.
 167
 168 =item *
 169 perl
 170
 171 =back
 172
 173
 174 The Makefile uses  perl for trivial operations,  and you could  tinker
 175 with it to use sed or awk.
 176
 177 Operation:
 178
 179 =over 5
 180
 181 =item * TeX
 182
 183 =item * the MusixTeX fonts
 184
 185 =back
 186
 187 =head1 COMPILING
 188
 189 Do:
 190
 191         tar zxf flower-1.11.9.tar.gz
 192         mv flower-1.11.9 flower
 193         cd flower; make; cd ..
 194         tar zxf lilypond-1.2.13.tar.gz
 195         cd lilypond-1.2.13
 196         make
 197
 198 You might want to edit Variables.make to tailor the compilation flags.
 199 why G++ >= 2.7? LilyPond & flower lib uses:
 200
 201 =over 5
 202
 203 =item *
 204 builtin bool
 205
 206 =item *
 207 typeof
 208
 209 =item    *
 210 operator <?, operator >?
 211
 212 =item    *
 213 the new for-scope
 214
 215 =item    *
 216 class Rational (libg++)
 217
 218 =item    *
 219 named return values
 220
 221 =back
 222
 223 =head1 AUTHORS
 224
 225 =over 5
 226
 227 =item *
 228 Han-Wen Nienhuys <hanwen@stack.nl>, Main author
 229
 230 =item *
 231 Jan Nieuwenhuizen <jan@digicash.com>, bits of FlowerLib, general comments.
 232
 233 =item *
 234 Mats Bengtsson <matsb@s3.kth.se>, bugfixes, testing.
 235
 236 =back
 237
 238 Your name could be here! If you want to help, then take a look at the
 239 SMALLISH PROJECTS section of LilyPond. Some do not involve coding C++
 240
 241 =head1 EXAMPLES
 242
 243 At this time, LilyPond is only suited for Quick & Dirty jobs (the
 244 output quality still is too low). If you're not discouraged; this is
 245 what I type in my xterm:
 246
 247         lilypond someinput.ly
 248         tex test
 249         xdvi test&
 250
 251 This is what the output looks like over here:
 252
 253         hw:~/musix/spacer$ lilypond maartje.ly
 254         LilyPond 0.0.17/FlowerLib 1.0.14. Compile: Dec 17 1996, 11:33:54 (g++ 2.7.2)
 255         Parsing ... [symbol.ini][maartje.ly]
 256         Processing ... Calculating ... Postprocessing ...
 257         output to lelie.uit...
 258
 259         hw:~/musix/spacer$ tex test
 260         This is TeX, Version 3.14159 (C version 6.1)
 261         (test.tex
 262         Hyphenation patterns for english, dutch, loaded.
 263         (lilyponddefs.tex) (lelie.uit) [1] [2] )
 264         Output written on test.dvi (2 pages, 8072 bytes).
 265         Transcript written on test.log.
 266
 267         hw:~/musix/spacer$ xdvi test&
 268         [1] 1468
 269
 270 Check out kortjakje.ly, it has some comments
 271
 272
 273 =head1 PROBLEMS
 274
 275 If LilyPond bombs out, then please recompile using B<-g>, and send a
 276 copy of the input which causes the error and a gdb stacktrace of the
 277 crash. It also helps if you can print the values of the objects. So if
 278 you trace is
 279
 280         (gdb) backtrace 12
 281         #0  Interval::operator+= (this=0x11fffec60..)
 282             at ../flower/interval.hh:50
 283         #1  0x12005195c in Item::width (this=0x14008a680) at src/item.cc:39
 284         #2  0x12008fdbc in itemlist_width (its=0x11fffed58 ..
 285           :
 286           :
 287
 288 Than it would help if you send a dump of the Interval and the Item
 289 (use: 'print *this' or use LilyPond print() methods).
 290
 291 This is a beta version of LilyPond. Please send your helpful comments
 292 and patches to me (see AUTHORS section)
 293
 294 LilyPond is updated very frequently, the latest version is always available at:
 295
 296 F<ftp://pcnov095.win.tue.nl/pub/lilypond>
 297
 298
 299 =head1 FILES
 300
 301 F<symbol.ini> The initialisation file with symbol tables etc. It
 302 includes files from the directory F<init/>.
 303
 304 =head1 SEE ALSO
 305
 306 lilygut(1), lilyinput(1)
 307
 308 =head1 REMARKS
 309
 310 LilyPond has no connection with the music package RoseGarden, other
 311 than the names being similar.