release: 1.2.6

[lilypond.git] / Documentation / faq.texi

\input texinfo @c -*-texinfo-*-
@setfilename faq.info
@settitle FAQ - GNU LilyPond FAQs

@node Top, , Windows32, (dir)
@top
@menu
* FAQ - GNU LilyPond FAQs::       FAQ - GNU LilyPond FAQs
@end menu



@node FAQ - GNU LilyPond FAQs, Miscellaneous, , Top
@menu
* Miscellaneous::                 Miscellaneous
* Installing::                    Installing
* Documentation::                 Documentation
* Language- mudela::              Language- mudela
* Do you support -::              Do you support -
* How do I -::                    How do I -
* Development::                   Development
* Running::                       Running
* Copyright::                     Copyright
* Windows32::                     Windows32
@end menu
@chapter FAQ - GNU LilyPond FAQs


@node Miscellaneous, Installing, FAQ - GNU LilyPond FAQs, FAQ - GNU LilyPond FAQs
@section Miscellaneous

@subsubsection HELP! I'm stuck!

Please read this document carefully.  If you are still at loss,
send your subsubsections to the @strong{mailing list}, and not to authors
directly.

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

@node Installing, Documentation, Miscellaneous, FAQ - GNU LilyPond FAQs
@section Installing

@subsubsection 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 @emph{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}.

@subsubsection Where is guile-config

RedHat RPMS don't include guile-config.  You need guile-config as it
was produced during the RPM build run.  Build the RPM from source
(@file{.src.rpm}), and use the guile-config that is in
@file{/usr/src/redhat/BUILD/guile-1.3/guile-config/}.

@subsubsection 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 @strong{GNU} bison
@strong{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.

@subsubsection 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:
@example 

    autoconf
    configure
 
@end example 

You might need to create some extra "out" directories.  Do this with
@example 

    make out-wwws
 
@end example 

@subsubsection 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
@example 

    ~/usr/
 
@end example 

which looks like @file{/usr/}
@example 

    bin/
    share
    lib/
    share/
    src/

    etc....
 
@end example 


)       

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

@subsubsection 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.

@subsubsection 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.

@node Documentation, Language- mudela, Installing, FAQ - GNU LilyPond FAQs
@section Documentation

@subsubsection 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.

@node Language- mudela, Do you support -, Documentation, FAQ - GNU LilyPond FAQs
@section Language: mudela

@subsubsection 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)

@subsubsection Why do I have to type the accidentals to the note if I specified them?

Take this example
@example 

    cis cis
 
@end example 

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.

@subsubsection 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.

@subsubsection 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
@example 

    a()a()a
 
@end example 

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

@node Do you support -, How do I -, Language- mudela, FAQ - GNU LilyPond FAQs
@section Do you support ...

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

Yes, see the @file{twinkle-pop} example.

@subsubsection Do you support guitar chord diagrams?

No. Go ahead and send a patch.

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.

@subsubsection Do you support TAB notation?

No. The same as for the previous subsubsection 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.)

@subsubsection Do you support multiple staff-sizes?

Yes.  At this time you can choose between 11, 13, 16, 19, 20, 23 and
20 pt staff-size.  Use the staffLineLeading property for setting the
size of the staff, and fontSize for setting the size of the glyphs.

@subsubsection Do you support Gregorian chant notation?

No.  Go ahead.

@subsubsection Do you support grace notes?

Yes. See @file{input/test/grace.ly}

@node How do I -, Development, Do you support -, FAQ - GNU LilyPond FAQs
@section How do I ....

@subsubsection How do I change the TeX layout?

See @file{lilyponddefs.tex}, it has some comments.  Or use @file{ly2dvi}.

subsubsection(How do I place lyrics under @emph{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
@example 
        
        \score @{
                < \melodic \type Staff = "treble" \trebleMelody
                  \lyric \type Lyrics = "tlyrics" \trebtext
                  \type Staff = "bass" \melodic \bassMelody        
                  \lyric \type Lyrics = "blyrics" \basstext      
                >
                \paper @{  @}
        @}
 
@end example 

@subsubsection How do I put more than one marking on a note.

You can stack them 
@example 

        c4^"a"^"b"
 
@end example 

or use spacing-notes to put markings at different horizontal positions 
@example 

        < c1
          @{ s4\ff s4^"text" s4-\marcato s4 @}
        >
 
@end example 

This also works for crescendi, eg,
@example 

        < c1
          @{ s4\< s2 \! s4 @}
        >
 
@end example 

@subsubsection How do I combine multiple pieces into one document

There are several solutions:

@itemize @bullet
@item  
@example 

        ly2dvi foo.ly bar.ly
 
@end example 
 
produces one combined @file{foo.dvi}
@item  make a toplevel @file{.ly} file that contains al pieces:
@example 

        % booklet.ly
        \input "piece-1.ly"
        \input "piece-2.ly"
        \input "piece-3.ly"
 
@end example 
 
@item  make a hybrid TeX/LilyPond @file{.doc} document (see the
     @file{Documentation/tex} directory).
@end itemize

For the first two solutions, you will need to move @code{\header} info 
in each individual piece from toplevel into the @code{\paper} block.

There are several examples in the @file{mutopia} directory.

@subsubsection How do I get bar numbers?

See @file{input/test/bar-scripts.ly}.

@subsubsection How do I change the tagline 'Lily was here'

In the @code{\header} field, add a @code{tagline} entry, eg
@example 

tagline="Typeset by GNU LilyPond"
 
@end example 

to get a bit less frivolous tagging.

@node Development, Running, How do I -, FAQ - GNU LilyPond FAQs
@section Development

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

@subsubsection 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
@uref{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.

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

@subsubsection 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 effort practically died. (see
@uref{http://harmonia.scar.utoronto.ca}.

Matthew Hiller is working on extending Midiscore and Koobase to handle
mudela.  Check out @uref{http://zoo.cs.yale.edu/~meh25/}.

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-music-discuss@@gnu.org}.


@subsubsection 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.

@subsubsection I made some code, how do I get you to include it?

Send in a patch:
@example 

        diff -urN old-file new-file > patch
 
@end example 

or 
@example 

        diff -urN old-directory/ new-directory/ > patch 
 
@end example 

Alternatively, you can use issue the command
@example 

        make diff
 
@end example 

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

@emph{Please} always send a @strong{-u} diff, even if it is larger than the
whole file.

@subsubsection 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}.

You should also have a look using Javadoc like tools.  Try
DOC++, @uref{http://www.imaginator.com/doc++}

@subsubsection Why GPL?

No comment.


@subsubsection 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

@subsubsection gdb crashes when I debug!

Upgrade to 4.17.

@subsubsection Why do I need g++ >= 2.8 / EGCS-1.1 ?

Supporting more compilers than EGCS/G++ 2.8 is unlikely to make
LilyPond run on more platforms.  It would give us an enormous headache
in detecting and catering for every variant of every compiler: not
having to support other compilers saves us a @emph{lot} of trouble.

@node Running, Copyright, Development, FAQ - GNU LilyPond FAQs
@section Running

@subsubsection 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.


subsubsection(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 @emph{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{buildscripts/clean-fonts.sh}.

@subsubsection all the pk and tfm fonts are created in the directory where the mudela file is, not in "/var/spool/texmf" where I think they should be.

Mats Bengtsson <mats.bengtsson@@s3.kth.se> writes:

The simple solution used by Anthony Fok in the Debian distribution of
Lilypond is to link the mf/ directory to
/usr/lib/texmf/fonts/source/public/lilypond Depending on what
distribution of teTeX and Linux you have installed, there might also
be other places like /usr/local/lib/texmf/fonts/source/public/lilypond
or /var/spool/texmf//fonts/source/public/lilypond

Wherever you put it, don't forget to run mktexlsr (or texhash for
older installations) afterwards, so that TeX will find the files.
Also, don't forget to remove all old .tfm and .*pk files when the font
is updated (as it will be in version 1.1.40, for example).

@subsubsection Are there scalable versions of the font?

Yes, they are type-3 fonts.  In the @file{mf/} 
subdirectory, issue:
@example 

        make pfa
 
@end example 
 in the mf/ subdirectory.  This will also  make @file{mfplain} for metapost.
The @file{pfa}s will be in the subdirectory @file{out/}.

@subsubsection How does PS output work?

@itemize @bullet
 @item 
Generate the PostScript Type-3 fonts. 
@item 
Run lilypond with option @code{-f ps}:
@example 

    lilypond -fps foo.ly
 
@end example 

@item  To view the @file{.ps} output with GhostView, set GS_FONTPATH to the 
directory containing the @file{pfa}s.  In the source tree, this is @file{mf/out/}.

i.e. do something like:
@example 

   export GS_FONTPATH=$HOME/usr/src/lilypond/mf/out
   gv foo.ps &
 
@end example 

@end itemize

Direct PS output is still experimental.  For creating nice looking ps 
output, use TeX and @code{dvips}.

  
@subsubsection 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.

@subsubsection I don't get midi-output, even if I use @strong{-M}!

Your \score should include a \midi block, eg.
@example 

        \score @{
                \melodic @{ c4 c g g @}
                \paper @{@}     
                \midi @{
                        output = "myfile.midi";
                        \tempo 4=70;
                @}
        @}
 
@end example 

The @strong{-M} option was added to LilyPond because processing the \paper
block is so slow.

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

@node Copyright, Windows32, Running, FAQ - GNU LilyPond FAQs
@section Copyright

@subsubsection What is Urtext?  Critical Edition?

Werner Lemberg:

It may be translated best as `that what the composer intended to tell
the reader'

Peter Chubb <peterc@@aurema.com> writes:

An Urtext is a reconstruction of the earliest form of a text,
including mistakes the original author wrote.  Where there is no
available facsimile of the original, creating this can involve some
inspired detective work (in comparing various later editions and
trying to deduce what the original form was).  As far as copyright
goes, my guess is that, for works that are otherwise out of copyright,
an Urtext is copyright to the person who reconstructed it, as a
derived work from the editions s/he consulted.  If the edition is
created directly from a facsimile, as would be the case for most
Urtext editions of music, then the amount of new (copyright) material
is minimal.

A critical edition is an edition that is designed for critical
study of a text.  It'll usually have lots of footnotes, alternative
readings, possible realisations of bass parts and harmonies, etc.  It
aims to elucidate the author's original intentions, as opposed to
reproduce exactly what was written.  The critical apparatus will be
copyright to its author.

A playing edition is one that has been edited for modern usage.
It'll have fewer or no alternative readings, it'll be in modern
notation, it may have additional editorial marks (phrase marks, slurs,
etc.) will often have a fully realised basso continuo part (if oone
was present in the original) and may have had key changes, time
signature changes, time compression (original in 4/1, playing edition
in 4/4, for example, with all semibreves replaced with crotchets)
Copyright is in the arranger/editor.

subsubsection(How does copyright for sheet music work? Can I enter and spread my newly bought Bach urtext?) 

Silas S. Brown <ssb22@@hermes.cam.ac.uk>:

There are several aspects to sheet music copyright:

1.  The music itself - copyright for the composer's life plus 70 years (so
not applicable to Bach).

2.  If the music is an arrangement, then the arranger holds copyright on
that arrangement.  However, you can produce your own arrangement using
that arrangement as a reference point.  Obviously your arrangement must be
sufficently different to be called your own arrangement - you need to do
more than change one note!

3.  In some countries, the same applies for editions.  This could be
relevant to the Bach example.  If a modern person has edited the music,
then they hold the copyright on the edition.  This does not stop you from
removing the editorial features - remove all editorial slurs, phrasemarks,
ornaments etc and only leave those that you know to be original.  You can
then add some of your own if you want to be your own editor.

4.  If there are lyrics, then the lyricist also holds copyright.  This
does not stop you from using the music without the lyrics if it is
otherwise out of copyright.

5.  The copyright of the printed page is held by the publisher for 30
years after printing (25 in some countries).  This stops you from
photocopying (unless it's "fair use" eg. you're partially sighted and need
to enlarge the music) or otherwise reproducing the typesetting that is
used on it.  But the copyright is only held over the typesetting work, not
the music itself.  Since Mudela specifies the notes, independently of any
typesetting work that went into your reference copy, you are not
duplicating any of the publisher's work.

6.  If you want to violate copyright, there are two main cases where you
may do so: fair use, and with permission.  The former is rather fuzzily
defined, but it includes such things as including small extracts of a
score in a critique, and making a large print or Braille copy for a blind
or partially-sighted performer (many people argue that in this case it
should always be kept with the original copy and/or destroyed after it is
no longer needed).  The latter is obvious: You can always write to the
composer, arranger, editor, lyricist or publisher in subsubsection and ask if
you can do whatever it is you're trying to do.  Some will respond more
readily than others, but anything that they say will override any copying 
restrictions imposed on you.

References - best one I know is the UK-based Performing Right Society,
@uref{http://www.prs.co.uk/} (especially "membership") and their links to other
international equivalents.  


Juergen Reuter <reuterj@@ira.uka.de>:

[More information can be had at: ]

@uref{http://lcweb.loc.gov/copyright/}
(USA copyright law)

@uref{http://fairuse.stanford.edu/}
(meta site about copyright with many links to other resources)

@uref{http://host.mpa.org/crc.html}
(copyright from the viewpoint of the USA music publishers' association)

@uref{http://www.wipo.int}
(World Intellectual Property Organization (a UNO agency); with
information about international copyright)

John Sankey:

See @uref{http://www.geocities.com/Vienna/Studio/1714/harpsichord.html}
for a summary of copyright relative to old music, also for the
expert forum for such subsubsections.

Werner Lemberg <sx0005@@sx2.HRZ.Uni-Dortmund.DE>:

This is not correct.  Urtext editions per se are @emph{not} copyrighted
-- if you print exactly what the composer has written, how can there
some copyright be added?  Copyrighted are usually only the `Critical
notes', the foreword, and the cadenzas some editors have added.

This means that the `Photocopying forbidden' sign in many scores is
not always correct for e.g. J.S. Bach -- you are allowed to copy the
pages which don't contain editorial stuff which is probably
copyrighted.

A very unfortunate situation for the publishers.


@node Windows32, Top, Copyright, FAQ - GNU LilyPond FAQs
@section Windows32

@subsubsection 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. 

@subsubsection But i want a native DOS/Windows-NT/95 port

Reconsider.  Try Linux.  It's fun!

@bye