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
  24 =head1 OPTIONS
  25
  26 =over 5
  27
  28 =item B<-I,--include>=F<FILE>,
  29
  30 add F<FILE> to the search path for input files.
  31
  32
  33 =item B<-M,--midi>
  34
  35 do midi output only
  36
  37 =item B<-d,--debug>,
  38
  39 Turn debugging info. GNU LilyPond will read the file F<.dstreamrc>, which
  40 tells for what functions and classes may produce copious debugging
  41 output.
  42
  43 =item B<-w,--warranty>,
  44
  45 Show the warranty with which GNU LilyPond comes. (It comes with B<NO
  46 WARRANTY>!)
  47
  48 =item B<-o,--output=>F<FILE>,
  49
  50 Set the default output file to F<FILE>.
  51
  52 =item B<-h,--help>,
  53
  54 Show a summary of usage
  55
  56 =item B<-i,--init=>F<FILE>
  57
  58 set init file to F<FILE> (default: F<symbol.ini>)
  59
  60 =item B<--include, -I>=F<DIRECTORY>
  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, chords, super/subscripts (accents and text), triplets,
  96 general n-plet (triplet, quadruplets, etc.), lyrics, transposition
  97 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 At this time, GNU LilyPond output looks nice, but is not of production
 152 quality. If you're not discouraged; this is what I type in my xterm:
 153
 154         lilypond someinput.ly
 155         tex lelie.tex
 156         xdvi test&
 157
 158 This is what the output looks like over here:
 159
 160         hw:~/musix/spacer$ GNU LilyPond 0.0.60 #8/FlowerLib 1.1.14 #2
 161         Parsing ... [./input/kortjakje.ly[lots of stuff]]
 162         Setting up requests...Processing requests ...[8][16][24][25]
 163         Preprocessing elements...
 164         Calculating column positions ... [3][7][12][16][20][25]
 165         Postprocessing elements...
 166         TeX output to lelie.tex ...
 167
 168         hw:~/musix/spacer$ tex lelie
 169         This is TeX, Version 3.14159 (C version 6.1)
 170         (lelie.tex
 171         Hyphenation patterns for english, dutch, german, loaded.
 172         (/home/hw/lib/texmf/tex/lilypond/lilyponddefs.tex) [1] )
 173         Output written on lelie.dvi (1 page, 8944 bytes).
 174         Transcript written on lelie.log.
 175
 176         hw:~/musix/spacer$ xdvi lelie&
 177         [1] 855
 178
 179 Check out the input files, some of them have comments
 180
 181
 182 =head1 PROBLEMS
 183
 184 If GNU LilyPond bombs out, then please recompile using with debugging info
 185 turned on, and send a copy of the input which causes the error and a
 186 gdb stacktrace of the crash. It also helps if you can print the values
 187 of the objects. So if your trace is
 188
 189         (gdb) backtrace 12
 190         #0  Interval::operator+= (this=0x11fffec60..)
 191             at ../flower/interval.hh:50
 192         #1  0x12005195c in Item::width (this=0x14008a680) at src/item.cc:39
 193         #2  0x12008fdbc in itemlist_width (its=0x11fffed58 ..
 194           :
 195           :
 196
 197 Than it would help if you send a dump of the Interval and the Item
 198 (use: C<print *this> or use GNU LilyPond C<print()> methods).
 199
 200 This is a beta version of GNU LilyPond. Please send your helpful comments
 201 and patches to me (see AUTHORS section)
 202
 203 GNU LilyPond is updated very frequently, the latest version is always available at:
 204 ftp://pcnov095.win.tue.nl/pub/lilypond.
 205
 206
 207 =head1 FILES
 208
 209 =over 5
 210
 211 =item F<symbol.ini>
 212
 213 The initialisation file with symbol tables etc. It
 214 includes files from the directory F<init/>.
 215
 216 =back
 217
 218 =head1 ENVIRONMENT
 219
 220 B<LILYINCLUDE> an (one) additional directory for finding lilypond data.
 221
 222 =head1 SEE ALSO
 223
 224 =over 4
 225
 226 =item lilygut(?)
 227
 228 On technical details of LilyPond
 229
 230 =item mudela(5)
 231
 232 On the input format
 233
 234 =item MANIFESTO
 235
 236 Goals of the GNU LilyPond project.
 237
 238 =item The GNU LilyPond FAQ list
 239
 240 =back
 241
 242 GNU LilyPond has her own webpage at
 243 http://www.stack.nl/~hanwen/lilypond/index.html. This webpage contains
 244 the MIDI, GIF and PS files for some standard music files. It also has
 245 the complete LilyPond documentation
 246
 247 A mailing list for GNU LilyPond has been setup, it's at
 248 lilypond@gnu.ai.mit.edu. To subscribe, send mail to
 249 lilypond-request@gnu.ai.mit.edu.
 250
 251 For discussions concerning the GNU Music project,
 252 gnu-music-discuss@vanderbilt. .edu
 253
 254 =head1  REMARKS
 255
 256 GNU LilyPond has no connection with the music package Rosegarden, other
 257 than the names being similar :-)
 258
 259 =head1 HISTORY
 260
 261 (for a  detailed changelog, see F<NEWS>)
 262
 263 GNU LilyPond's roots lie in MPP, a preprocessor to the rather arcane
 264 MusiXTeX macro package for TeX. A friend of mine, Jan Nieuwenhuizen
 265 wrote the first 44 versions (0.01 to 0.44), then his program caught my
 266 attention, and I was slowly sucked in to the interesting problem of
 267 easily producing beautifully printed music. I contributed some
 268 code. We soon realised that MPP's design was too fundamentally broken
 269 to be repaired. It was decided to rewrite MPP.  We debated a lot about
 270 the requirements to an inputformat (fall 1995). I sat down and started
 271 with a parser-first, bottom-up rewrite called mpp95 (which totally
 272 failed, obviously).
 273
 274 After long and hard thinking, I came up with an algorithm for the
 275 horizontal spacing of multiple staffs (april 1996) I coded it (and did
 276 not test it). After starting with this fundamental piece, I slowly
 277 added the stages which come before spacing, and after.  A half year
 278 later later, I had a first working version, (october 1996).  I
 279 announced Patchlevel 0.0.7 (or 8) to the mutex list after asking some
 280 technical details on spacing; it was downloaded approximately 4 times.
 281 Then I got the hang of it, and in the subsequent two months, I coded
 282 until it had doubled in size (pl 23).