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