[lilypond.git] / Documentation / faq.pod

=head1 NAME

FAQ - GNU LilyPond FAQs

=head1 DESCRIPTION

Some questions that have been answered before. (note: relative paths
are meant to be relative to the source directory)

=head2 Installing

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: [] designate beams, a note can only be in one beam at the same
time. () is a slur, which connects notes.  You need to be able to 
specify

        a()a()a


Q: I want to insert some TeX commands

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.

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.

=head2 Do you support ...

Q: Do you support pop songs (chords, single staff, lyrics)?

A: Yes, see the F<twinkle-pop> example.

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 16 or 20 pt
staff-size (you can have other sizes, but you need to tinker with the
fonts to get those).  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 }
        >



=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
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: 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 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.