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