[lilypond.git] / Documentation / faq.texi

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

@node Top, , , (dir)
@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, ,,top
@section Miscellaneous

[FIXME: rewrite FAQ, include general questions] 

@subsubsection HELP! I'm stuck!

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

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

@subsubsection I've got a simple question, but this FAQ doesn't help!

Please have a look in the searchable mail achives of
@uref{http://www.mail-archive.com/gnu-music-discuss@@gnu.org/,
gnu-music-discuss} and
@uref{http://www.mail-archive.com/help-gnu-music@@gnu.org/, help-gnu-music}.
Your question may well have been answered before.

@node Installing,, ,top
@section Installing


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

The NT 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?).

@subsubsection Where is guile-config

Old 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 


@subsubsection Is there an emacs mode?

Yes.  It is included with the source archive as @file{lilypond-mode.el}.
If you have an RPM it is in @file{/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,, ,top
@section Documentation

@subsubsection What a sober website/manual you have there!

LilyPond development is moving fast, so the documentation will often be out
of date.  But don't hesitate to point out inaccuracies. Whip up your
mail reader and write to the mailing list.

@subsubsection Please take me off your mailing list, I get  so much mail!

Don't ask Han-wen, don't ask David. Instead, read about
@uref{../../index.html#mailing-lists,  the mailing lists} here.



@node Language- mudela,, ,top
@section Language: mudela

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

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, so you
have to enter C-sharp twice.

@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 -,, ,top
@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 fret diagrams?

No. 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 question goes.

@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 @code{staffSpace} property for setting the
size of the staff, and @code{fontSize} for setting the size of the
glyphs.

@subsubsection Do you support Gregorian chant notation?

No.


@subsubsection Do you support grace notes?

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

@node How do I -,, ,top
@section How do I ....

@subsubsection How do I change the page layout?

The height and width of the music on each page is set 
using the paper variables @code{textheight} and @code{linewidth} in
the input file. 
If you want to change the placement of the page number or the 
layout of the title, you could run @code{lilypond infile.ly} and 
include the generated @file{infile.tex} file in your own LaTeX 
wrapper file. The easiest way is to start from the ly2dvi default
layout, using the following steps (assuming that the input file 
is @file{infile.ly}:

@itemize @bullet

  @item @code{ly2dvi -kK infile.ly}

  @item Edit the generated LaTeX file @file{infile_lyN.tex} (@code{N} is 
  some number) to get the desired layout. Some aspects are determined in 
  the file titledefs.tex. 

  @item Run @code{latex infile_lyN.tex}

  @item If you update the Mudela file, run @code{lilypond infile.ly}
        and then @code{latex infile_lyN.tex}.
@end itemize
Another alternative is to use @command{mudela-book}, where smaller or
larger music examples can be included in a LaTeX or Texinfo file.

@subsubsection The tagline is visible in the .dvi file but is not printed on paper.

The default page size is A4. If you use letter sized papers, 
add the following at the top of your Mudela file.
@example
\paper@{
  papersize="letter";
@}
\include "paper20.ly"
@end example 
(Note that setting the papersize in the ordinary paper section inside
a score declaration will not have the desired effect.)
The default paper size can be set globally for the installation
in the file @file{declarations.ly}.

@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 change the tagline 'Lily was here'?

In the @code{\header} field, add a @code{tagline} entry, e.g.
@example 

tagline="Typeset by GNU LilyPond"
 
@end example 

@subsubsection Can I make blank manuscript paper with LilyPond?

Theoretically, yes but it is easier to do with (La)TeX. This LaTeX file
will do the trick for you:


@example
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% notepaper.tex
% Mats Bengtsson, 18/5 2000
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[a4paper]@{article@}

\usepackage@{ifthen@}
\usepackage[noheadfoot,hmargin=15mm,vmargin=20mm]@{geometry@}

\pagestyle@{empty@}

\newcounter@{staffnumber@}
\newlength@{\interstaffline@}

\newcommand@{\drawline@}@{\hbox@{\rule@{\textwidth@}@{0.5pt@}@}
  \nointerlineskip\vskip\interstaffline\nointerlineskip@}

\newcommand@{\printstaff@}@{\vfill
  \vbox@{\drawline\drawline\drawline\drawline\drawline@}
  \vfill@}

\begin@{document@}
\typeout@{@}\typeout@{@}
\typein[\staffsize]@{Type in the staff size (20pt is a common value):@}
\setlength@{\interstaffline@}@{\staffsize@}
\setlength@{\interstaffline@}@{.25\interstaffline@}
\typeout@{@}
\typein[\num]@{Type in the number of staffs:@}
\setcounter@{staffnumber@}@{\num@}

\mbox@{@} % To get a starting point for the \vfill
\whiledo@{\value@{staffnumber@}>0@}@{%
  \printstaff \addtocounter@{staffnumber@}@{-1@}@}

\end@{document@}
@end  example


@node Development,, ,top
@section Development

@subsubsection Could you implement feature XXXX? It is really easy, just extend the syntax to allow YYYY!

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?

Yes, we do frequent releases, you are welcome to send in a patch or do
suggestions.  Join the list @email{gnu-music-discuss@@gnu.org} to
participate.


@subsubsection Is there a GUI frontend?  Should I start building one?

Matthew Hiller has extended Midiscore and Koobase to handle mudela, He
is now working on @uref{http://denemo.sourceforge.net/,Denemo}, a GTK
based notation program. This is the most advanced LilyPond front-end
currently available.

Chris Cannam is working a rewrite of Rosegarden.  The new design should
be more modular, and could conceivably be used to output
mudela. However, the not much seems to have happened the past year. See
@uref{http://www.all-day-breakfast.com/rosegarden/development.html}.

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

Please use the diff command to generate a patch, and don't send complete
files, even if the diff is larger than the whole file.

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


@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 for
our needs.

@subsubsection How do I inspect @code{String}s and @code{SCM} values in GDB?

Use the following command definitions, which can be put in 
the file ~/.gdbinit.

@example
define printstr
    print $arg0->ch_C()
end

define printscm
    call gh_display($arg0)
    call gh_newline()
end
@end example

@subsubsection GDB crashes when I debug!

Upgrade/downgrade to 4.17.

@node Running,, ,top
@section Running

@subsubsection LilyPond takes ages to run, what am I doing wrong?

LilyPond uses a lot CPU time, and insane amounts of memory. The amount
of memory it requires is proportional to the size of the score, in other
words. For a moderately complex piano scores of 5 pages, the footprint
can easily become 20 megs. (Our favorite test is the coriolan:
approx. 100 megs for a 50 page orchestral score). If your system has not
got enough memory, it can easily start swapping.

A part of the memory is used as temporary storage, and is reclaimed
through GUILE's garbage collection.  A way to trade in CPU time for
storage is by decreasing the environment variable
@var{GUILE_MAX_SEGMENT_SIZE} (default 8388608, which is 8 megs).


@subsubsection Correcting errors is so tedious. Is there a better way?

As of 1.3.73, lilypond provides support for the xdvi @code{src:}
special. This can be used with Xdvik (22.16 or better) and xdvi (22.28
or better) to go to the place in the input that corresponds to a symbol
in the output: click on the note, and your editor jumps to the place
where it was defined

lilypond:

Decide if you want column positioning, and edit @file{lily.scm}
according to the comments at the function @code{define-origin}.

emacs:

Put this in @file{~/.emacs}:
@example
(server-start)
@end example

For column positioning, apply
@uref{http://www.cs.uu.nl/~hanwen/software/emacsclient-column, this
patch} to @code{emacsclient.c} and @code{server.el}. Stick the compiled
emacsclient into a bin directory, and put @code{server.el} into a elisp
directory (eg. @file{~/usr/share/emacs/}). Add the following to your
@file{.emacs} init file, before invoking server-start.
@example
(setq load-path (cons (concat (getenv "HOME") "/usr/share/emacs")
 load-path))
@end example

Xdvik:

Warning: @uref{Xdvik,ftp://ftp.cs.uu.nl/pub/tex-archive/dviware/xdvik/},
which is shipped with most TeX distributions, doesn't work very well for
src specials. You're better off using plain xdvi.
@example
        xdvi -srcmode -srcvisibility output.dvi
@end example

Click control-mouse button 2 for making emacs jump to the appropriate place.

For column positioning you must install
@uref{http://www.cs.uu.nl/~hanwen/software/xdvik-src, this patch} to
make Xdvik emit column numbers. Add the command line option
@code{-srceditorcommand "emacsclient --no-wait +%l:%c %f"}

Xdvi

@uref{Xdvi,ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz} has
better support for src specials. Apply
@uref{http://www.cs.uu.nl/~hanwen/software/xdvi-src, this patch}. Before
starting, set the environment variable @code{XEDITOR} to
@code{"emacsclient --no-wait +%d %s"}.  When viewing,
control-mousebutton 1 will take you to the correct
line/column. Control-mousebutton 2 will show all clickable boxes.

dvips:

dvips will complain about the specials, but the complaints are harmless.


@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 not used often, and therefore likely to exhibit
bugs.  For creating nice looking ps output, use TeX and @code{dvips}.

  
@subsubsection The beams and slurs are gone when using the XDvi magnifying glass!?

Various dynamic symbols, such as beams, crescendi, slurs are done in
PostScript.  XDvi doesn't show PostScript in the magnifying glass.
Complain to the XDvi maintainers.


@subsubsection Beams, slurs and crescendi are not displayed at all!

See previous answer.  XDvi uses GhostScript for displaying PostScript,
check that you have GhostScript installed.  If you use a different
DVI viewer, check if it will display embedded PostScript.  Don't worry,
the symbols should appear on the printout.

@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,, ,top
@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>:

@quotation

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.  
@end quotation

Werner Lemberg @email{wl@@gnu.org} writes:

@quotation

Typesetting [at least in Austria or Germany, but not in France] [..]
isn't copyrighted -- typesetting is a handcraft, not an
art.

What's copyrighted in an Urtext edition is the editor's comment or
the revision remarks, cadenzas added by the editor, etc.

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.

@end  quotation


Glen Prideaux, @email{glenprideaux@@MailAndNews.com}:

@quotation
One has to be careful. In Australia typesetting IS covered by copyright, but
only for 25 years (as opposed to 50 years from the death of the
author/composer/artist for virtually any other copyright). If the
typesetting originates in a country that does not protect typesetting then
there may indeed be no copyright protection available to control the use of
mudela files.
@end quotation

Juergen Reuter @email{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.

Benjy (benjy@@indiansprings.org)

@quotation
(In the UK, the typesetting of a piece of music goes out of copyright 25 year\s
after it is published.  Maybe you can tell me what copyright law says in othe\r
countries.)
@end quotation

The US has had several schemes over the last century meaning that
anything published after January 1, 1923 and before 1964 requires that
you put in some work to determine its status. However, anything
published before 1923 is fair game in the US. See
@uref{http://www.loc.gov/copyright/circs/circ22.html} for the whole
twisted tale.


@node Windows32,, ,top
@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