printed with this correction, the last two measures without. The notes
in the last two measures form downstem/upstems clumps of notes.
-Experts have the knowledge to make such adjustments themselves by
-hand. For a skilled engraver, a computer drawing program is sufficient
-to produce excellent music typography. However, laypeople don't have
-the knowledge to think of such details. For a musician, the interface
-of a program should be familiar. This is a place where there is a
-choice of two paradigms: most musicians are familiar with notation,
-and with music. Most graphically oriented programs offer an interface
-that shows notation, and allow you to enter the music by placing notes
-on a staff.
-
-
-Interactive programs always have to load and save their data from
-files on the disk. In a program that deals with music notation, the
-notation always has to converted to some kind of representation of the
-music inside.
-
-[todo]
-
-
-When we view the problem of making beautiful sheet music for a given
-piece of music as a scientific puzzle, then we can only solve that
-puzzle if it is well-stated. Hence, when we design an input format, we
-want it to be neatly defined and have precise semantics. Such formats
-also have the advantage of being easier to write code for.
-
-
-Many music encodings exist today but most of the encodings have not
-been tailored either for human use, or for processing it with a
-computer. By its nature, LilyPond input has both features: it is
-concise, suitable for human input, and it can be processed
-automatically: it may be converted into MIDI or into print.
-
-
-However, one big problem with music, is that there are no standards
-for encoding music. Sure, you can record performances using MIDI, but
-that offers far too little information for adequate musicological
-purposes. With LilyPond we've taken a reverse approach: we have tried
-to come up with musical format that can cater virtually all music as
-long as it can be notated.
-
-LilyPond input focuses on musical concepts such as pitch, duration and
-music expressions. Musical data is rhythmic, and implies an ordering
-of events. This ordering is used to create compound musical concepts:
-Large musical structures are built recursively from smaller
-expressions: a sequence of music expressions forms a new, longer and
-bigger music expression. In this sense, the input is recursive. It
-shares this property with very music encodings. The recursive nature
-will appeal to the more hackerish musician.
+We hope that these examples serve to show that music typography is a
+subtle business, and that it requires skill and knowledge to produce
+good engraving---skill and knowledge most people lack. It was our
+challenge to see if we could put such knowledge into a computer
+program.
+
+One of the first questions that pop up when you design such a program,
+is what kind of input the program should expect. Many music notation
+programs offer a graphical interface that shows notation, and allows
+you to enter the music by placing notes on a staff. Although this is a
+obvious way to design a program, from our point of view, this is
+cheating. After all, the core message of a piece of music notation
+simply is the music itself. If you start by offering music notation to
+the user, you have already skipped one conversion, even if it perhaps
+is implicit. If we want to generate music notation, then the obvious
+candidate for the source format should be the music itself.
+
+Of course, on paper this theory sounds very good. In practice, it
+opens a can of worms. What really @emph{is} music? Many philosophical
+treatises must have been written on the subject. Even if you're more
+practically inclined, you will notice that an enormous number of
+different ways to represent music in a computer exist, and they are
+much more incompatible than the formats for wordprocessors and
+spreadsheets. Anyone who has tried to exchange data files from
+between different computer programs can attest to this.
+
+The cause of this problem is that music is inherently two-dimensional:
+in polyphonic music, notes have time and pitch as their two
+coordinates, and they often are related in both directions. Computer
+files on the other hand are essentially one-dimensional: they are a
+long stream of characters. When you represent music in a file, then
+you have to flatten this two-dimensional information breaking the
+timing or the pitch, relations, and there is no universal agreement on
+how to do this.
+
+It might seem that when designing a music representation, we have
+myriad of choices. Luckily, we have some requirements that shaped the
+input format into what it is now. A music representation is about
+@emph{music}, so it should be free from notation as much as possible:
+the format is about pitches and durations, not about symbols and
+offsets. Since LilyPond is a compiler, the input format is its user
+interface, and users have to key in the music into the file directly,
+requiring that the input format has a friendly syntax. We, as
+programmers and scientists also like the format to have a clean formal
+definition. After all, producing music notation is a difficult
+problem, and in the scientific world, difficult problems always must
+be well-specified. Moreover, formally defined formats are easier to
+write programs for. Finally, enough information should be present to
+be able to produce a printed score.
+
+These ideas shaped music representation elegantly builds complex
+musical constructs from simple entities like notes and rests, in much
+the same way that one builds complex formulae from simple expressions
+such as numbers and mathematical operators.
+
+The strict separation between musical information and typesetting also
+gives a blueprint of the program: first it reads the music
+representation, then it interprets the music---reading it
+`left-to-right', and translating the musical information to a layout
+specification. When the layout is computed, the resulting symbols are
+written to an output file.
+
+Much more could be said about the inner working of the program, but we
+will leave it at this. Those who are interested can inspect the source
+code, which is available freely, or inquire on the development mailing
+list.
+
+We hope that you understand where LilyPond came from, and what we
+tried to achieve. The rest of this manual less philosophical: it
+instructs you how use the input language to print beautiful music.
+
should mention many more people, these are from AUTHORS
@end ignore
+We always maintain that wrote this program to satisfy our curiosity,
+to have fun together, to help people, but ultimately, LilyPond is a
+way to express our deep love for music. May it help you create lots of
+beautiful music!
Han-Wen and Jan
@menu
* First steps:: Music language of LilyPond
* Running LilyPond:: Printing music
+* More basics::
* Printing lyrics::
* A melody with chords ::
* More stanzas::
@separate
+@node Running LilyPond
+@section Running LilyPond
+
+In the last section, we explained what kind of things you could enter
+in a lilypond file. In this section we explain how to run LilyPond,
+and how view or print the output. If you have not used LilyPond
+before, want to test your setup of LilyPond, or try to run an example
+file yourself, then read this section. The instructions that follow
+are for running LilyPond on Unix-like systems. Some additional
+instructions for running LilyPond on Windows are given at the end of
+this section.
+
+You begin with opening a terminal window, and start up a text editor.
+For example, open an xterm and execute @code{joe}. In your text editor,
+enter the following input, and save the file as @file{test.ly}:
+
+@quotation
+@example
+\score @{
+ \notes @{ c'4 e' g' @}
+@}
+@end example
+@end quotation
+
+@cindex ly2dvi
+
+@c now this is weird, running ly2dvi to run LilyPond
+@c (therefore name change proposal)
+
+LilyPond is the program that computes the sheet music. All other
+things, such as adding titles, page breaking and other page layout,
+are done by a small wrapper program called
+@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
+then adds the titling and page layout instructions. To process
+@file{test.ly} with ly2dvi, proceed as follows:
+
+@quotation
+@example
+ly2dvi -P test.ly
+@end example
+@end quotation
+
+You will see the following on your screen:
+
+@quotation
+@example
+GNU LilyPond 1.4.0
+Now processing: `/home/fred/ly/test.ly'
+Parsing...
+Interpreting music...[1]
+ @emph{ ... more interesting stuff ... }
+PS output to `test.ps'...
+DVI output to `test.dvi'...
+@end example
+@end quotation
+@cindex DVI file
+@cindex Viewing music
+@cindex xdvi
+
+The results of the ly2dvi run are two files, @file{test.dvi} and
+@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
+You can view the PS file using the program ghostview. If a version of
+ghostview is installed on your system, one of these commands will
+produce a window with some music notation on your screen:
+@c eeek
+@quotation
+@example
+ gv test.ps
+ ghostview test.ps
+ ggv test.ps
+ kghostview test.ps
+@end example
+@end quotation
+If you are satisfied with the looks of the music displayed on your
+screen, you can print the PS file by clicking File/Print inside
+ghostview.
+
+The DVI file (@file{test.dvi}) contains the same sheet music in a
+different format. DVI files are more easily processed by the computer,
+so viewing them usually is quicker. Execute @code{xdvi test.dvi}
+to view the DVI file.
+
+If your DVI viewer does not have a "Print" button, you can print the
+file by executing @code{lpr test.ps}.
+
+@c volgende alinea schrappen?
+
+If you can't get the examples to print, then you should look into
+installing and configuring ghostscript. Refer to GhostScript's website
+at @uref{http://www.ghostscript.com}.
+
+@cindex GhostScript
+@cindex @code{lpr}
+@cindex Printing output
+@cindex PostScript
+
+@unnumberedsubsec Windows users
+Windows users start the terminal by clicking on the LilyPond or Cygwin
+icon. Notepad is sufficient for editing the LilyPond file. Viewing
+the PS file can be done with:
+@quotation
+@example
+@code{gsview32 test.ps}
+@end example
+@end quotation
+You can also print from the command line by executing:
+@quotation
+@example
+@code{gsview32 /s test.ps}
+@end example
+@end quotation
+
+
@strong{SUMMARY}
+To run LilyPond, enter a file, and run the command @code{ly2dvi} on
+that file. The resulting files are either DVI or PostScript, and can
+be viewed with @code{xdvi} (unix) and ghostview (unix and windows)
+respectively. The following table summarizes the constructs that were
+discussed in the previous two sections.
+
@multitable @columnfractions .3 .3 .4
@item @b{Syntax}
@end multitable
-@c maybe legend here?
-
+@node More basics
+@section More basics
We continue with the introduction of the remaining musical constructs.
-
-Normal rests are entered just like notes with the name ``@code{r}'':
+Normal rests are entered just like notes, but use the name
+``@code{r}'':
@quotation
@example
@strong{SUMMARY}
+The following table summarizes the syntax learned in this section.
+
@multitable @columnfractions .3 .3 .4
@item @b{Syntax}
polyphonic music, and integrating text and music.
-@node Running LilyPond
-@section Running LilyPond
-
-In the last section, we explained what kind of things you could enter
-in a lilypond file. In this section we explain how to run LilyPond,
-and how view or print the output. If you have not used LilyPond
-before, want to test your setup of LilyPond, or try to run an example
-file yourself, then read this section. The instructions that follow
-are for running LilyPond on Unix-like systems. Some additional
-instructions for running LilyPond on Windows are given at the end of
-this section.
-
-You begin with opening a terminal window, and start up a text editor.
-For example, open an xterm and execute @code{joe}. In your text editor,
-enter the following input, and save the file as @file{test.ly}:
-
-@quotation
-@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
-@end example
-@end quotation
-
-@cindex ly2dvi
-
-@c now this is weird, running ly2dvi to run LilyPond
-@c (therefore name change proposal)
-
-LilyPond is the program that computes the sheet music. All other
-things, such as adding titles, page breaking and other page layout,
-are done by a small wrapper program called
-@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
-then adds the titling and page layout instructions. To process
-@file{test.ly} with ly2dvi, proceed as follows:
-
-@quotation
-@example
-ly2dvi -P test.ly
-@end example
-@end quotation
-
-You will see the following on your screen:
-
-@quotation
-@example
-GNU LilyPond 1.4.0
-Now processing: `/home/fred/ly/test.ly'
-Parsing...
-Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PS output to `test.ps'...
-DVI output to `test.dvi'...
-@end example
-@end quotation
-@cindex DVI file
-@cindex Viewing music
-@cindex xdvi
-
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
-You can view the PS file using the program ghostview. If a version of
-ghostview is installed on your system, one of these commands will
-produce a window with some music notation on your screen:
-@c eeek
-@quotation
-@example
- gv test.ps
- ghostview test.ps
- ggv test.ps
- kghostview test.ps
-@end example
-@end quotation
-If you are satisfied with the looks of the music displayed on your
-screen, you can print the PS file by clicking File/Print inside
-ghostview.
-
-The DVI file (@file{test.dvi}) contains the same sheet music in a
-different format. DVI files are more easily processed by the computer,
-so viewing them usually is quicker. Execute @code{xdvi test.dvi}
-to view the DVI file.
-
-If your DVI viewer does not have a "Print" button, you can print the
-file by executing @code{lpr test.ps}.
-
-@c volgende alinea schrappen?
-
-If you can't get the examples to print, then you should look into
-installing and configuring ghostscript. Refer to GhostScript's website
-at @uref{http://www.ghostscript.com}.
-
-@cindex GhostScript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-
-@unnumberedsubsec Windows users
-Windows users start the terminal by clicking on the LilyPond or Cygwin
-icon. Notepad is sufficient for editing the LilyPond file. Viewing
-the PS file can be done with:
-@quotation
-@example
-@code{gsview32 test.ps}
-@end example
-@end quotation
-You can also print from the command line by executing:
-@quotation
-@example
-@code{gsview32 /s test.ps}
-@end example
-@end quotation