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