patch::: 1.1.0.uu2.jcn1: fixjes

[lilypond.git] / Documentation / faq.yo

article(FAQ - GNU LilyPond FAQs)()()()

DEFINEMACRO(question)(1)(subsect(ARG1))

sect(Miscellaneous)

question(HELP! I'm stuck!)

Please read this document carefully.  If you are still at loss,
send your questions to the bf(mailing list), and not to authors
directly.

Note: relative paths are meant to be relative to the source directory

sect(Installing)

question(If I install the .exe file on my DOS/windows 3.11 machine, it
doesn't work.)

The DOS port is done with the cygnus gnu/windows32 port of the GNU utils.
It does em(not) work with windows 3.x; you need Windows-NT (95/98?).  This
is not a recommendation, however.  We recommend you use Unix, in
particular, use GNU/Linux.  For further information see file(README-W32).

question(I get all kinds of errors while  compiling file(parser.cc))

LilyPond uses features of bison version 1.25. Please confirm that
you are using a version 1.25 or better, that is bf(GNU) bison
bf(1.25). Don't forget to do "make clean" after installing it. Don't
forget to remove the stale file(bison.simple) as well.

If the problem persists, then please send a bug report to the mailing list.

question(I upgraded by applying a patch, and now my configure/build breaks.)

Patches don't include automatically generated files, i.e. 
file(configure) and files generated by file(configure).  Regenerate them 
yourself:
verb(
    autoconf
    configure
)
You might need to create some extra "out" directories.  Do this with
verb(
    make outdirs
)
question(Some of your neat scripts fail, what directories do you use:)

[This only applies if you don't do code(make install), and develop out
of the source directory]

I have a directory which contains all our development projects
verb(
    ~/usr/
)

which looks like file(/usr/)
verb(
    bin/
    share
    lib/
    share/
    src/

    etc....
)

The directory  file(~/usr/src/) contains something like
includefile(../stepmake/Documentation/layout.yo)
)       

~/usr/src/bin is in the PATH, and contains symbolic links to the
compiled executables.

question(Is there an emacs mode?)

Yes.  It is included with the source archive as mudela-mode.el.  If
you have an rpm it is in /usr/doc/lilypond-X/.  You have to install it
yourself.

question(How do i create the file(.tfm) files?)

You don't.  The file(.tfm) files should be generated automatically by
Metafont when you run TeX().  Check your TeX() installation, or ask
your local TeX() guru.  The supplied file(.afm) files are intended to
be used by LilyPond, not by any other programs.


sect(Documentation)

question(Why is the documentation/website/etc. so lousy?)

LilyPond development is moving quite fast, documentation will often
lag a bit behind.  We must always make a choice between writing more
doco, writing more code and answering email.

If you think you can make a correction, or devised a solution that 
should be documented, please do so and send in a patch.

sect(Language: mudela)

question(Why can't you type code(#c) in stead of code(cis) ?)

We think that code(#c) looks as if you are entering the symbols to
print (which you are not; remember, you're entering the musical
content in Mudela)


question(Why do I have to type the accidentals to the note if I specified them?)

Take this example
verb(
    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.


question(What is code(cis) anyway)

code(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.


question(Why are [] around the notes, and () inbetween?)

[] 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
verb(
    a()a()a
)

question(I want to insert some TeX commands.)

You shouldn't: it's against LilyPond philosophy to have typesetting
commands in the mudela source. Moreover, this would be difficult.
LilyPond uses TeX like a glorified output engine: the output consists
of (x,y) positions and symbols.  You can only sensibly do TeX stuff in
the symbol string.  You can access the symbol string easily for some
symbols (notably lyrics and code(^"text") commands).


sect(Do you support ...)

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

Yes, see the file(twinkle-pop) example.


question(Do you support guitar chord diagrams?)

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.

question(Do you support TAB notation?)

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.)

question(Do you support multiple staff-sizes?)

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 file(standchen.ly) for an example.


question(Do you support Gregorian chant notation?)

No.  There is no reason why LilyPond can't be extended to do so, but
we haven't done it yet (and there are currently no plans to do it).


sect(How do I ....)

question(How do I change the TeX layout?)

See file(lilyponddefs.tex), it has some comments.  Or use file(ly2dvi).

question(How do I place lyrics under em(each) of the staves in a
score, as 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!)

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
verb(   
        \score {
                < \melodic \type Staff = "treble" \trebleMelody
                  \lyric \type Lyrics = "tlyrics" \trebtext
                  \type Staff = "bass" \melodic \bassMelody        
                  \lyric \type Lyrics = "blyrics" \basstext      
                >
                \paper {  }
        }
)

question(How do I put more than one marking on a note.)

You can stack them 
verb(
        c4^"a"^"b"
)
or use spacing-notes to put markings at different horizontal positions 
verb(
        < c1
          { s4\ff s4^"text" s4-\marcato s4 }
        >
)
This also works for crescendi, eg,
verb(
        < c1
          { s4\< s2 \! s4 }
        >
)


question(How do I get bar numbers?)

See file(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 file(init/rhythm.ly).


sect(Development)

question(Could you implement feature XXXX? It is really easy, just extend
the syntax to allow YYYY!)

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. 


question(Can I join in on LilyPond development?  How do I do this?)

LilyPond development is open for anyone who wants to join.  We try
to use a Bazaar style development model for LilyPond, see
lurl(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.


question(I want to implement XXXX!  Should I do this?)

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).


question(Is there a GUI frontend?  Should I start building one?)

LilyPond currently has no graphical interface.  The authors seriously
doubt if a simple-minded approach (dragging and dropping notes) is any
easier or quicker to use than mudela.  But for composing a graphical
environment probably is indispensable.

In any case email(Derek Wyatt)(wyatt@scar.utoronto.edu) is working on
GTK based editor, but that is still in an embryonal stage (see
lurl(http://harmonia.scar.utoronto.ca).  There is also a GUI package
RoseGarden that could be extended to output mudela.

If you want to work on this, please send e-mail to the mailing list
email(gnu-misc-discuss@gnu.org).


question(I want to implement XXXX!  How should I do this?)

Your best bet of getting us to include code, is to present it as a
"fait accompli", i.e., to send a patch to the mailing list.


question(I made some code, how do I get you to include it?)

Send in a patch:
verb(
        diff -urN old-file new-file > patch
)
or 
verb(
        diff -urN old-directory/ new-directory/ > patch 
)
Alternatively, you can use issue the command
verb(
        make diff
)

Don't forget to put your name and e-mail address
in the file(AUTHORS.pod) file, or you won't get credits :-]


question(How do I learn the C++ code?)

The entry point is in code(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 code(less lily/include/*.hh). Some of the most
important data-structures are to be found in:
verb(
        - *request.hh
        - engraver.hh
        - performer.hh
        - translator.hh
        - score-elem.hh
        - music.hh
        - music-list.hh
        - music-iterator.hh
        - item.hh
        - spanner.hh
)

question(Why GPL?)

Yes.


question(Your make system does not adhere to GNU coding standards, could you
please fix it?)

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's generic make package code(StepMake) 
(see file(stepmake-x.x.x/Documentation/automake.urgh))

LilyPond already compiles into a different directory ((the different
directory is called out/, there is one in every source directory).
make distclean essentially reduces to file(rm -f out/*) in every directory


question(gdb crashes when I debug!)

Upgrade to 4.17.

question(Why do I need g++ >= 2.7?)

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 em(lot) of trouble. 


sect(Running)


question(I use dvilj4, and there are lots of warning messages for the
printing)

You should use dvips and ghostscript to print the code(dvi) output:
the slurs and beams are PS code(\special) commands.


question(My symbols are all messed up after I upgraded, I get the
wrong symbols and dvi-checksum errors!)

We obviously mucked with the fonts in the upgrade.  Remove em(all)
previous fonts, including the file(.pk) and file(.tfm) fonts in
file(/var/lib/texmf).  A script automating this has been included, see
file(bin/clean-fonts.sh).


question(The beams and slurs are gone if use the XDvi magnifying glass!?)

The beams and slurs are done in PostScript.  XDvi doesn't show
PostScript in the magnifying glass.  Complain to the XDvi maintainers.


question(I don't get midi-output, even if I use bf(-M)!)

Your \score should include a \midi block, eg.
verb(
        \score {
                \melodic { c4 c g g }
                \paper {}       
                \midi {
                        \output "myfile.mid";
                        \tempo 4=70;
                }
        }
)
The bf(-M) option was added to LilyPond because processing the \paper
block is so slow.

question(A lot of musical stuff doesn't make it to the MIDI file, eg.
dynamics, articulation, etc.)

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.  Patches appreciated.

sect(Windows32)

question(I downloaded the windows32 port, and it doesn't match the website!)

The website is usually made from the latest snapshots.  Binary releases,
in particular the windows32 binaries, are only made every once in a while.
They may lag several versions behind the latest version. 

question(But i want a native DOS/Windows-NT/95 port)

Reconsider.  Try Linux.  It's fun!