=head1 NAME
-FAQ - LilyPond FAQs
+FAQ - GNU LilyPond FAQs
=head1 DESCRIPTION
-Some questions that have been answered before.
+Some questions that have been answered before. (note: relative paths
+are meant to be relative to the source directory)
+
+=head2 Installing
+
+Q: Wow, the webpages look really neat, but if I install the .exe file
+on my windows 3.11 machine, it doesn't work.
+
+A: The DOS port is done with the cygnus W32 port of the GNU utils. It
+does I<not> work with windows 3.x; you need NT or w95 (this is not a
+recommendation, btw. We recommend you use Unix, in particular, use
+GNU/Linux)
+
+Q: I get all kinds of errors while compiling F<parser.cc>
+
+A: LilyPond uses features of bison version 1.25. Please confirm that
+you are using a version 1.25 or better, that is B<GNU> bison
+B<1.25>. Don't forget to do "make clean" after installing it. Don't
+forget to remove the stale F<bison.simple> as well.
+
+If the problem persists, then please mail me.
+
+Q: Some of your neat scripts fail, what directories do you use:
+
+A: [This only applies if you don't do C<make install>, and develop out
+of the source directory] I have a directory which contains all music
+related stuff,
+
+ ~/something/
+
+which contains:
+
+ lilypond/ # the directory as unpacked from the tarball
+ releases/ # directory for .tar.gz releases
+ patches/ # directory for patches between different releases
+ test/ # create tarballs and do diffs from this directory
+
+~/something/lilypond/bin is in the PATH, and contains symlinks to the
+compiled executables. For some of the scripts to work, you have to set
+
+ LILYPOND_SOURCEDIR=/home/myself/something/lilypond
+
+in the environment.
+
+If you don't use patches, you'd probably want to symlink
+
+ lilypond -> lilypond-x.y.z
+
+=head2 Language: mudela
+
+Q: Why can't you type C<#c> in stead of C<cis> ?
+
+A: We think that C<#c> looks as if you are entering the symbols to
+print (which you are not; remember, you're entering the musical
+content in Mudela)
+
+We're not sure on leaving out this feature. If you think this is a
+good idea, please let us know.
+
+
+Q: Why do I have to type the accidentals to the note if I specified them?
+
+A: Take this example
+
+ cis cis
+
+Independently of how it was written and what the current key was, you
+would say that you are playing and reading "two C-sharp" notes. We
+have tried to make the language somewhat context-free. Of course
+sheet music is not context-free. Unfortunately, sheet music is also 2
+dimensional, and ASCII is not.
+
+Technically it would be feasible to have the Interpreting phase do
+tricky things to add (or leave out) the accidentals, but we think that
+it is impractical: it hampers the readability and portability of your
+source, since you need LilyPond to fill in the details and actually
+make sense of it.
+
+
+Q: What is C<cis> anyway
+
+A: C<cis> is the dutch naming for C-sharp. The notes are named
+a, b,.., g. The suffix -is means sharp, and -es flat. This system is
+common in a number of languages (such as swedish, dutch, german.)
+Certain other languages (such as English, French and Italian) just add
+the word for "sharp" to the notename.
+
+We chose the Dutch system, because we're dutch. You are free to chose
+whatever names you like; they are user definable.
+
+Q: I can type
+
+ <a c> <e g>
+
+to make a few chords, but why do I have to type
+
+
+ < { a~ e } { c ~ g } >
+
+instead of
+
+ <a~ c~> <e g>
+
+to generate ties between the chords?
+
+A: When you type
+
+ <a c> <e g>
+
+this is shorthand for
+
+ < { a } { c } > < { e } { g } >
+
+Ties have to be confined to `voices', and the a and the e are in
+different {} blocks, so they are in different voices. You should view
+the desired construct as a "generalised chord" (two voices stacked
+vertically). It might help you visualise this by using the following
+formatting:
+
+ < { a ~ e }
+ { c ~ g }
+ >
+
+Q: and where do the beams come into this picture?
+
+A: Beams are voicegroup-wide, and may be entered in any part of the
+voicegroup:
+
+ < { [a ~ e] } { c ~ g } >
+ < { [a ~ e } { c ~ g] } >
+ < { [a ~ e] } { [c ~ g] } >
+
+These all give the same result.
Q: Why are [] around the notes, and () inbetween?
a()a()a
-Q: I want a DOS/NT/W95 port.
+Q: I want to insert some TeX commands
-A0: Reconsider. Try Linux. It's fun!
+A: You shouldn't: it's against LilyPond philosophy to have typesetting
+commands in the mudela source. Moreover, this would be difficult. The
+manner in which Request (the basic building blocks of mudela) are
+translated into printable items is complex: it is not always possible
+to associate one Request with one Item or Spanner.
-A1: Currently (patchlevel 27), LilyPond (and flowerLib) compiles, links
-and runs on windhoos-nt, using the cygnus gnu port (release b17.1).
-I (JCN) only had to make a minor workaround for missing library calls.
-Have a look at http://www.cygnus.com/gnu-win32. To make LilyPond type
-make $OS. (I am not promising to maintain this platform, it is just that
-when having to use doze, i-m sometimes too lazy to reboot.)
+As a further notice, we want to move away from TeX (and perhaps
+output PostScript or render to an X window too), so using TeX will
+make sources non-portable at some time.
-A2: I haven't had time to find a GCC crosscompiler (*with* g++, mind you) to
-DOS/win (in rpm, please :).
+=head2 Do you support ...
+Q: Do you support pop songs (chords, single staff, lyrics)?
-Q: Why GPL?
+A: Yes, see the F<twinkle-pop> example.
-A: Yes.
+Q: Do you support guitar chord diagrams?
+
+A: No, not yet. We ourselves don't play guitar, and don't know the
+fine points of this notation. We would welcome anyone who could give
+this a try.
+
+Q: Do you support TAB notation?
+
+A: No. The same as for the previous question goes, but TAB is a lot
+more work than diagrams (TAB needs modification of Parser, Lexer,
+Staff, Notehead, Stem code and all the code that creates these graphic
+elements.)
+
+Q: Do you support multiple staff-sizes?
+
+A: Yes and no. At this time you can choose between 11, 13, 16, 19,
+20, 23 and 20 pt staff-size. The sizes can't be changed per staff
+(yet). Look at F<standchen.ly> for an example.
+
+
+=head2 How do I ....
+
+Q: How do I change the TeX layout?
+
+A: See F<lilyponddefs.tex>, it has some comments.
+
+Q: How do I place lyrics under I<each> of the staves in a score, as in
+choral music. I can work out how to put lyrics for each line all under
+the top line, or at the bottom but not between!
+
+A: You change the order lyrics and staves. You have to name all
+staves (lyric and melodic), otherwise they will end up in the same
+staff/lyricline
+
+
+ \score {
+ < \melodic \type Staff = "treble" \trebleMelody
+ \lyric \type Lyrics = "tlyrics" \trebtext
+ \type Staff = "bass" \melodic \bassMelody
+ \lyric \type Lyrics = "blyrics" \basstext
+ >
+ \paper { }
+ }
+
+
+Q: How do I put more than one marking on a note.
+
+A: You can stack them
+
+ c4^"a"^"b"
+
+or use spacing-notes to put markings at different horizontal positions
+
+ < c1
+ { s4\ff s4^"text" s4-\marcato s4 }
+ >
-Q: Why shouldn't I put all commands (\clef, \meter) inside the music?
+Q: How do I get bar numbers?
-A: You should do what you like, but at some time we will enable
-quoting of music ("Stichnoten"). Besides if you are going to type an
-orchestral score, then you'd probably want to enter most of the meter,
-repeat commands only once.
+A: See F<init/engraver.ly>. You have to uncomment some entries. To
+do this `portably' you should redefine some engravers in your own
+source files. Check out F<init/rhythm.ly>.
+=head2 Development
Q: Could you implement feature XXXX? It is really easy, just extend
the syntax to allow YYYY!
A: If it is reasonable, I'll add XXXX to the TODO list. In general
finding a cute syntax (such as YYYY) isn't very hard. The complicated
-issue how to adapt the internals to do XXXX. The parser is really a
+issue how to adapt the internals to do XXXX. The parser is really a
simple front end to the complicated internals.
+
+Q: Can I join in on LilyPond development? How do I do this?
+
+A: LilyPond development is open for anyone who wants to join. We try
+to use a Bazaar style development model for LilyPond, see
+http://locke.ccil.org/~esr/writings/cathedral.html. This means:
+frequent releases, everyone can send in a patch or do suggestions and
+all development discussions are public.
+
+To be precise, discussions take place on the gnu-music-discuss mailing
+list, which is open for subscription to everyone.
+
+
+Q: I want to implement XXXX! Should I do this?
+
+A: There might be better ways of doing XXXX, so it's a good thing to
+ask about this before you start hacking. If you want to keep in touch
+with current developments, you should subscribe to the mailing list
+(see the "links" section of the documentation).
+
+
+Q: I want to implement XXXX! How should I do this?
+
+A: Your best bet of getting me to include code, is to present it as a
+"fait accompli", ie., to send me a patch.
+
+
+Q: I made some code, how do I get you to include it?
+
+A: Send in a patch:
+
+ diff -urN old-file new-file > patch
+
+or
+
+ diff -urN old-directory/ new-directory/ > patch
+
+Alternatively, you can use F<bin/make-patch.py>. Don't forget to put
+in your name and e-mail address.
+
+Q: How do I learn the C++ code?
+
+A: The entry point is in C<main()>. Good luck. :-)
+
+Seriously, read, reread and reread internals and CodingStyle, and
+just start anywhere.
+
+Anywhere? Well, most of the comment doco are in the header files, so
+your best bet would be C<less lily/include/*.hh>. Some of the most
+important data-structures are to be found in:
+
+ - *request.hh
+ - engraver.hh
+ - performer.hh
+ - translator.hh
+ - score-elem.hh
+ - music.hh
+ - music-list.hh
+ - music-iterator.hh
+ - item.hh
+ - spanner.hh
+
+
+Q: Why GPL?
+
+A: Yes.
+
+
+Q: Your make system does not adhere to GNU coding standards, could you
+please fix it?
+
+A: No. We have evaluated the standard GNU combination for compiling
+programs (autoconf, automake, libtool) and found to be inadequate in
+several respects. More detailed argumentation is included with
+LilyPond (see F<automake.urgh>)
+
+Q: Why do I need g++ >= 2.7?
+
+A: By using g++, GNU LilyPond is portable to all platforms which support
+g++ (there are quite a few). Not having to support other compilers
+saves us a I<lot> of trouble.
+
+=head2 Running
+
+Q: There are lots of warning messages for the printing, all
+beginning with:
+
+ dvilj4l: warning: Invalid keyword or value in \special -
+
+A: You should use dvips and ghostscript to print it: the slurs and
+beams are PS C<\special> commands
+
+
+Q: My symbols are all messed up after I upgraded, and I get
+dvi-checksum errors!
+
+A: We mucked with the fonts in the upgrade. Remove I<all> previous
+fonts, including the .pk and .tfm fonts in F</var/lib/texmf>. A
+script automating this has been included, see F<bin/clean-fonts.sh>
+
+Q: I don't get midi-output, even if I use B<-M>!
+
+A: Your \score should include a \midi block, eg.
+
+ \score {
+ \melodic { c4 c g g }
+ \paper {}
+ \midi {
+ \output "myfile.mid";
+ \tempo 4=70;
+ }
+ }
+
+The B<-M> option was added to LilyPond because processing the \paper
+block is so slow.
+
+Q: A lot of musical stuff doesn't make it to the MIDI file (dynamics,
+articulation, etc).
+
+A: The MIDI output was originally put in as a proof that MIDI could be
+done, and as a method of proof"reading" the input. The MIDI support
+is by no means finished.
+
+Q: I get
+
+ can't load library 'libflower.so'
+
+A: You are using the dynamically compiled Flower library. Please set
+LD_LIBRARY_PATH to a directory containing F<libflower.so>
+
+=head2 DOZE
+
+Q: I downloaded the W95 port, and it doesn't match the website!
+
+A: The website is usually made from the latest snapshots. The W95
+binaries are only made every once in a while. They can lag several
+versions behind the latest version.
+
+Q: I want a DOS/NT/W95 port.
+
+A.0: Reconsider. Try Linux. It's fun!
+
+A.1: Currently (0.0.27), GNU LilyPond (and flowerLib) compiles,
+links and runs on Windows-nt, using Cygnus' gnu port (release b17.1).
+I (JCN) only had to make a minor workaround for missing library calls.
+Have a look at http://www.cygnus.com/gnu-win32. To make GNU LilyPond
+type C<make>. (I am not promising to maintain this platform, it is just
+that when forced into doze, i'm sometimes too lazy to reboot.)
+
+A.2: I haven't had time to find a Linux GCC crosscompiler (I<with> g++
+and libg++, mind you) to DOS/Windows (in rpm, please :-)
+
+A.3: If you are knowledgeable enough to make w32 compiles from time to
+time, please do so! We want to keep away from w32 as far as possible.
+
+Q: I just love to blindly run the (sometimes bit stale) .exe's you distribute.
+Why do i need cygwin.dll?
+
+A: It's all in this cut-n-paste:
+
+Minimalist GNU-Win32 Readme
+version 0.1.3
+March 20, 1997
+Colin Peters <colin@bird.fu.is.saga-u.ac.jp>
+
+[...]
+
+0.3 Fixes and Improvements
+
+[...]
+In the "coming soon" category I have a version of the GNU Standard C++
+library ported to Mingw32. This means you can use iostreams, complex
+numbers and all those neat STL (Standard Template Library) things
+without needing the Cygwin DLL. I hope to put this port up for
+downloading soon (along with the source of course).
+
+[...]
+
+3.2 C++ Support
+
+To add C++ Support to the above the following extra files are required:
+
+In C:\cygnus\H-i386-cygwin32\lib\gcc-lib\i386-cygwin32\cygnus-2.7.2-
+961023:
+ cc1plus.exe
+
+Note that this does not include support for the standard C++ libraries
+(only the C run time libraries) or for iostreams. That support is still
+only available with the Cygwin32 API.
+