Documentation/faq.pod

   1 =head1 NAME
   2
   3 FAQ - GNU LilyPond FAQs
   4
   5 =head1 DESCRIPTION
   6
   7 Some questions that have been answered before. (note: relative paths
   8 are meant to be relative to the source directory)
   9
  10 =head2 Installing
  11
  12 Q: Wow, the webpages look really neat, but if I install the .exe file
  13 on my windows 3.11 machine, it doesn't work.
  14
  15 A: The DOS port is done with the cygnus W32 port of the GNU utils. It
  16 does I<not> work with windows 3.x; you need NT or w95 (this is not a
  17 recommendation, btw.  We recommend you use Unix, in particular, use
  18 GNU/Linux)
  19
  20 Q: I get all kinds of errors while  compiling F<parser.cc>
  21
  22 A: LilyPond uses features of bison version 1.25. Please confirm that
  23 you are using a version 1.25 or better, that is B<GNU> bison
  24 B<1.25>. Don't forget to do "make clean" after installing it. Don't
  25 forget to remove the stale F<bison.simple> as well.
  26
  27 If the problem persists, then please mail me.
  28
  29 Q: I upgraded by applying a patch, and now my configure/build breaks.
  30
  31 A: Patches don't include automatically generated files, i.e. F<configure>
  32    and files generated by F<configure>.  Regenerate them yourself:
  33
  34     autoconf
  35     configure
  36
  37 You might need to create some extra "out" directories.  Do this
  38 with
  39
  40         make outdirs
  41
  42 Q: Some of your neat scripts fail, what directories do you use:
  43
  44 A: [This only applies if you don't do C<make install>, and develop out
  45 of the source directory] I have a directory which contains all music
  46 related stuff,
  47
  48         ~/something/
  49
  50 which contains:
  51
  52           lilypond/     # the directory as unpacked from the tarball
  53           releases/     # directory for .tar.gz releases
  54           patches/      # directory for patches between different releases
  55           test/         # create tarballs and do diffs from this directory
  56
  57 ~/something/lilypond/bin is in the PATH, and contains symlinks to the
  58 compiled executables.  For some of the scripts to work, you have to set
  59
  60         LILYPOND_SOURCEDIR=/home/myself/something/lilypond
  61
  62 in the environment.
  63
  64 If you don't use patches, you'd probably want to symlink
  65
  66         lilypond -> lilypond-x.y.z
  67
  68 =head2 Language: mudela
  69
  70 Q: Why can't you type C<#c> in stead of C<cis> ?
  71
  72 A: We think that C<#c> looks as if you are entering the symbols to
  73 print (which you are not; remember, you're entering the musical
  74 content in Mudela)
  75
  76 We're not sure on leaving out this feature. If you think this is a
  77 good idea, please let us know.
  78
  79
  80 Q: Why do I have to type the accidentals to the note if I specified them?
  81
  82 A: Take this example
  83
  84         cis cis
  85
  86 Independently of how it was written and what the current key was, you
  87 would say that you are playing and reading "two C-sharp" notes.  We
  88 have tried to make the language somewhat context-free.  Of course
  89 sheet music is not context-free.  Unfortunately, sheet music is also 2
  90 dimensional, and ASCII is not.
  91
  92 Technically it would be feasible to have the Interpreting phase do
  93 tricky things to add (or leave out) the accidentals, but we think that
  94 it is impractical: it hampers the readability and portability of your
  95 source, since you need LilyPond to fill in the details and actually
  96 make sense of it.
  97
  98
  99 Q: What is C<cis> anyway
 100
 101 A: C<cis> is the dutch naming for C-sharp. The notes are named
 102 a, b,.., g. The suffix -is means sharp, and -es flat. This system is
 103 common in a number of languages (such as swedish, dutch, german.)
 104 Certain other languages (such as English, French and Italian) just add
 105 the word for "sharp" to the notename.
 106
 107 We chose the Dutch system, because we're dutch. You are free to chose
 108 whatever names you like; they are user definable.
 109
 110 Q: I can type
 111
 112         <a c> <e g>
 113
 114 to make a few chords, but why do I have to type
 115
 116
 117         < { a~ e } { c ~ g } >
 118
 119 instead of
 120
 121         <a~ c~> <e g>
 122
 123 to generate ties between the chords?
 124
 125 A: When you type
 126
 127         <a c> <e g>
 128
 129 this is shorthand for
 130
 131         < { a } { c } > < { e } { g } >
 132
 133 Ties have to be confined to `voices', and the a and the e are in
 134 different {} blocks, so they are in different voices. You should view
 135 the desired construct as a "generalised chord" (two voices stacked
 136 vertically). It might help you visualise this by using the following
 137 formatting:
 138
 139         < { a ~ e }
 140           { c ~ g }
 141         >
 142
 143 Q: and where do the beams come into this picture?
 144
 145 A: Beams are voicegroup-wide, and may be entered in any part of the
 146 voicegroup:
 147
 148         < { [a ~ e] } { c ~ g } >
 149         < { [a ~ e } { c ~ g] } >
 150         < { [a ~ e] } { [c ~ g] } >
 151
 152 These all give the same result.
 153
 154 Q: Why are [] around the notes, and () inbetween?
 155
 156 A: [] designate beams, a note can only be in one beam at the same
 157 time. () is a slur, which connects notes.  You need to be able to
 158 specify
 159
 160         a()a()a
 161
 162
 163 Q: I want to insert some TeX commands
 164
 165 A: You shouldn't: it's against LilyPond philosophy to have typesetting
 166 commands in the mudela source. Moreover, this would be difficult. The
 167 manner in which Request (the basic building blocks of mudela) are
 168 translated into printable items is complex: it is not always possible
 169 to associate one Request with one Item or Spanner.
 170
 171 As a further notice, we want to move away from TeX (and perhaps
 172 output PostScript or render to an X window too), so  using TeX will
 173 make sources non-portable at some time.
 174
 175 =head2 Do you support ...
 176
 177 Q: Do you support pop songs (chords, single staff, lyrics)?
 178
 179 A: Yes, see the F<twinkle-pop> example.
 180
 181 Q: Do you support guitar chord diagrams?
 182
 183 A: No, not yet. We ourselves don't play guitar, and don't know the
 184 fine points of this notation.  We would welcome anyone who could give
 185 this a try.
 186
 187 Q: Do you support TAB notation?
 188
 189 A: No. The same as for the previous question goes, but TAB is a lot
 190 more work than diagrams (TAB needs modification of Parser, Lexer,
 191 Staff, Notehead, Stem code and all the code that creates these graphic
 192 elements.)
 193
 194 Q: Do you support multiple staff-sizes?
 195
 196 A: Yes and no.  At this time you can choose between 11, 13, 16, 19,
 197 20, 23 and 20 pt staff-size.  The sizes can't be changed per staff
 198 (yet).  Look at F<standchen.ly> for an example.
 199
 200
 201 =head2 How do I ....
 202
 203 Q: How do I change the TeX layout?
 204
 205 A: See F<lilyponddefs.tex>, it has some comments.
 206
 207 Q: How do I place lyrics under I<each> of the staves in a score, as in
 208 choral music. I can work out how to put lyrics for each line all under
 209 the top line, or at the bottom but not between!
 210
 211 A: You change the order lyrics and staves.  You have to name all
 212 staves (lyric and melodic), otherwise they will end up in the same
 213 staff/lyricline
 214
 215
 216         \score {
 217                 < \melodic \type Staff = "treble" \trebleMelody
 218                   \lyric \type Lyrics = "tlyrics" \trebtext
 219                   \type Staff = "bass" \melodic \bassMelody
 220                   \lyric \type Lyrics = "blyrics" \basstext
 221                 >
 222                 \paper {  }
 223         }
 224
 225
 226 Q: How do I put more than one marking on a note.
 227
 228 A: You can stack them
 229
 230         c4^"a"^"b"
 231
 232 or use spacing-notes to put markings at different horizontal positions
 233
 234         < c1
 235           { s4\ff s4^"text" s4-\marcato s4 }
 236         >
 237
 238
 239 Q: How do I get bar numbers?
 240
 241 A: See F<init/engraver.ly>.  You have to uncomment some entries.  To
 242 do this  `portably' you should redefine some engravers in your own
 243 source files.  Check out F<init/rhythm.ly>.
 244
 245 =head2 Development
 246
 247 Q: Could you implement feature XXXX? It is really easy, just extend
 248 the syntax to allow YYYY!
 249
 250 A: If it is reasonable, I'll add XXXX to the TODO list. In general
 251 finding a cute syntax (such as YYYY) isn't very hard. The complicated
 252 issue how to adapt the internals to do XXXX. The parser is really a
 253 simple front end to the complicated internals.
 254
 255 Q: Can I join in on LilyPond development?  How do I do this?
 256
 257 A: LilyPond development is open for anyone who wants to join.  We try
 258 to use a Bazaar style development model for LilyPond, see
 259 http://locke.ccil.org/~esr/writings/cathedral.html.  This means:
 260 frequent releases, everyone can send in a patch or do suggestions and
 261 all development discussions are public.
 262
 263 To be precise, discussions take place on the gnu-music-discuss mailing
 264 list, which is open for subscription to everyone.
 265
 266
 267 Q: I want to implement XXXX!  Should I do this?
 268
 269 A: There might be better ways of doing XXXX, so it's a good thing to
 270 ask about this before you start hacking.  If you want to keep in touch
 271 with current developments, you should subscribe to the mailing list
 272 (see the "links" section of the documentation).
 273
 274
 275 Q: I want to implement XXXX!  How should I do this?
 276
 277 A: Your best bet of getting me to include code, is to present it as a
 278 "fait accompli", ie., to send me a patch.
 279
 280
 281 Q: I made some code, how do I get you to include it?
 282
 283 A: Send in a patch:
 284
 285         diff -urN old-file new-file > patch
 286
 287 or
 288
 289         diff -urN old-directory/ new-directory/ > patch
 290
 291 Alternatively, you can use F<bin/make-patch.py>.  Don't forget to put
 292 in your name and e-mail address.
 293
 294 Q: How do I learn the C++ code?
 295
 296 A: The entry point is in C<main()>. Good luck. :-)
 297
 298 Seriously, read, reread and reread internals and CodingStyle, and
 299 just start anywhere.
 300
 301 Anywhere? Well, most of the comment doco are in the header files, so
 302 your best bet would be C<less lily/include/*.hh>. Some of the most
 303 important data-structures are to be found in:
 304
 305         - *request.hh
 306         - engraver.hh
 307         - performer.hh
 308         - translator.hh
 309         - score-elem.hh
 310         - music.hh
 311         - music-list.hh
 312         - music-iterator.hh
 313         - item.hh
 314         - spanner.hh
 315
 316
 317 Q: Why GPL?
 318
 319 A: Yes.
 320
 321
 322 Q: Your make system does not adhere to GNU coding standards, could you
 323 please fix it?
 324
 325 A: No.  We have evaluated the standard GNU combination for compiling
 326 programs (autoconf, automake, libtool) and found to be inadequate in
 327 several respects.  More detailed argumentation is included with
 328 LilyPond (see F<automake.urgh>)
 329
 330 Q: Why do I need g++ >= 2.7?
 331
 332 A: By using g++, GNU LilyPond is portable to all platforms which support
 333 g++ (there are quite a few). Not having to support other compilers
 334 saves us a I<lot> of trouble.
 335
 336 =head2 Running
 337
 338 Q: There are lots of warning messages for the printing, all
 339 beginning with:
 340
 341         dvilj4l: warning: Invalid keyword or value in \special -
 342
 343 A: You should use dvips and ghostscript to print it: the slurs and
 344 beams are PS C<\special> commands
 345
 346
 347 Q: My symbols are all messed up after I upgraded, and I get
 348 dvi-checksum errors!
 349
 350 A: We mucked with the fonts in the upgrade.  Remove I<all> previous
 351 fonts, including the .pk and .tfm fonts in F</var/lib/texmf>.  A
 352 script automating this has been included, see F<bin/clean-fonts.sh>
 353
 354 Q: I don't get midi-output, even if I use B<-M>!
 355
 356 A: Your \score should include a \midi block, eg.
 357
 358         \score {
 359                 \melodic { c4 c g g }
 360                 \paper {}
 361                 \midi {
 362                         \output "myfile.mid";
 363                         \tempo 4=70;
 364                 }
 365         }
 366
 367 The B<-M> option was added to LilyPond because processing the \paper
 368 block is so slow.
 369
 370 Q: A lot of musical stuff doesn't make it to the MIDI file (dynamics,
 371 articulation, etc).
 372
 373 A: The MIDI output was originally put in as a proof that MIDI could be
 374 done, and as a method of proof"reading" the input.  The MIDI support
 375 is by no means finished.
 376
 377 Q: I get
 378
 379         can't load library 'libflower.so'
 380
 381 A: You are using the dynamically compiled Flower library. Please set
 382 LD_LIBRARY_PATH to a directory containing F<libflower.so>
 383
 384 =head2 DOZE
 385
 386 Q: I downloaded the W95 port, and it doesn't match the website!
 387
 388 A: The website is usually made from the latest snapshots.  The W95
 389 binaries are only made every once in a while.  They can lag several
 390 versions behind the latest version.
 391
 392 Q: I want a DOS/NT/W95 port.
 393
 394 A.0: Reconsider.  Try Linux.  It's fun!
 395
 396 A.1: Currently (0.0.27), GNU LilyPond (and flowerLib) compiles,
 397 links and runs on Windows-nt, using Cygnus' gnu port (release b17.1).
 398 I (JCN) only had to make a minor workaround for missing library calls.
 399 Have a look at http://www.cygnus.com/gnu-win32.  To make GNU LilyPond
 400 type C<make>. (I am not promising to maintain this platform, it is just
 401 that when forced into doze, i'm sometimes too lazy to reboot.)
 402
 403 A.2: I haven't had time to find a Linux GCC crosscompiler (I<with> g++
 404 and libg++, mind you) to DOS/Windows (in rpm, please :-)
 405
 406 A.3: If you are knowledgeable enough to make w32 compiles from time to
 407 time, please do so!  We want to keep away from w32 as far as possible.
 408
 409 Q: I just love to blindly run the (sometimes bit stale) .exe's you distribute.
 410 Why do i need cygwin.dll?
 411
 412 A: It's all in this cut-n-paste:
 413
 414 Minimalist GNU-Win32 Readme
 415 version 0.1.3
 416 March 20, 1997
 417 Colin Peters <colin@bird.fu.is.saga-u.ac.jp>
 418
 419 [...]
 420
 421 0.3 Fixes and Improvements
 422
 423 [...]
 424 In the "coming soon" category I have a version of the GNU Standard C++
 425 library ported to Mingw32. This means you can use iostreams, complex
 426 numbers and all those neat STL (Standard Template Library) things
 427 without needing the Cygwin DLL. I hope to put this port up for
 428 downloading soon (along with the source of course).
 429
 430 [...]
 431
 432 3.2 C++ Support
 433
 434 To add C++ Support to the above the following extra files are required:
 435
 436 In C:\cygnus\H-i386-cygwin32\lib\gcc-lib\i386-cygwin32\cygnus-2.7.2-
 437 961023:
 438         cc1plus.exe
 439
 440 Note that this does not include support for the standard C++ libraries
 441 (only the C run time libraries) or for iostreams. That support is still
 442 only available with the Cygwin32 API.
 443