Documentation/faq.pod

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