@c -*-texinfo-*-
+
@node Introduction
@chapter Introduction
-LilyPond is a program to print sheet music. If you have used notation
-programs before, then the way to use this program might be surprising
-at first sight: in order to print music you have to enter musical
-codes in a file. Then you run the program on the file, and the music
-is produced without any further intervention. For example, something
-like this:
+[TODO: should have introduction of introduction]
+
+The art of music typography is called @emph{(plate) engraving}. The
+term derives from the traditional process of music printing. Only a
+few decades ago, sheet music was made by cutting and stamping the
+music into zinc or pewter plates in mirror image. The plate would be
+inked, and the depressions caused by the cutting and stamping would
+hold ink. An image was formed by pressing paper to the plate. The
+stamping and cutting was completely done by hand. Making corrections
+was cumbersome, so engraving had to be done correctly in one go. Of
+course, this was a highly specialized skill, and a craftsman had to
+complete around 10 years of practical training before he could be a
+master engraver.
+
+
+Nowadays, all newly printed music is produced on computers. This has
+obvious advantages: prints are cheaper to make, and editorial work can
+be done over e-mail. Unfortunately, the pervasive use of computers has
+also decreased the graphical quality of scores. Computer printouts
+have a bland, mechanical look, which makes them unpleasant to play
+from.
+
+The images below illustrate the difference between traditional
+engraving and typical computer output, and the third picture shows how
+LilyPond mimicks the traditional look. The left picture shows a scan
+of a flat symbol from a Henle edition published in 2000. In the center
+show symbol from a hand engraved B@"{a}renreiter edition of the same
+music. The left scan illustrates typical flaws of computer print: the
+staff line are thin, the weight of the symbol matches the light lines,
+and the glyph has a straight layout with sharp corners. By contrast,
+the B@"{a}renreiter has a bold and almost voluptuous rounded look.
+Our flat symbol is designed after, among others, this one. It is
+rounded, and its weight harmonizes with the thickness of our staff
+lines, which are also much thicker than Henle's lines.
+
+@multitable @columnfractions .1 .3 .3 .3
+@item @tab
+@ifnotinfo
+@iftex
+@image{henle-flat-bw,4cm}
+@end iftex
+@ifnottex
+@image{henle-flat-bw,,,png}
+@end ifnottex
+
+@tab
+@iftex
+@image{baer-flat-bw,4cm}
+@end iftex
+@ifnottex
+@image{baer-flat-bw,,,png}
+@end ifnottex
+
+@tab
+@iftex
+@image{lily-flat-bw,4cm}
+@end iftex
+@ifnottex
+@image{lily-flat-bw,,,png}
+@end ifnottex
+@end ifnotinfo
+@ifinfo
+@c workaround for makeinfo-4.6: line breaks and multi-column cookies
+@image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png} @image{lily-flat-bw,,,png}
+@end ifinfo
+
+@item @tab
+Henle (2000)
+@tab
+B@"{a}renreiter (1950)
+@tab
+LilyPond Feta font (2003)
+
+@end multitable
+
+
+@cindex musical symbols
+@cindex font
+@cindex blackness
+@cindex balance
-@lilypond[fragment,verbatim, relative 1, intertext="produces this
+In spacing, the distribution of space should reflect the durations
+between notes. However, many modern scores adhere to the durations
+with mathematical precision, and that leads to a poor result. In the
+next example, a motive is printed twice. It is printed using exact
+mathematical spacing, and with some corrections. Can you spot which
+fragment is which?
-"]
-\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+@cindex optical spacing
+@lilypond[noindent]
+ \score { \notes {
+ \override Staff.NoteSpacing #'stem-spacing-correction
+ = #0.6
+ c'4 e''4 e'4 b'4 |
+ \stemDown b'4 e''4 a'4 e''4| \stemBoth
+ \bar "||"
+ \override Staff.NoteSpacing #'stem-spacing-correction
+ = #0.0
+ \override Staff.StaffSpacing #'stem-spacing-correction
+ = #0.0
+ c'4 e''4 e'4 b'4 |
+ \stemDown b'4 e''4 a'4 e''4|
+ }
+ \paper { raggedright = ##t } }
@end lilypond
-@cindex encoding music
+@cindex regular rhythms
+@cindex regular spacing
+
+The fragment only uses quarter notes: notes that are played in a
+constant rhythm. The spacing should reflect that. Unfortunately, the
+eye deceives us a little: not only does it notice the distance between
+note heads, it also takes into account the distance between
+consecutive stems. As a result, the notes of an up-stem/down-stem
+combination should be put farther apart, and the notes of a down-up
+combination should be put closer together, all depending on the
+combined vertical positions of the notes. The first two measures are
+printed with this correction, the last two measures without. The notes
+in the last two measures form down-stem/up-stem clumps of notes.
+
+@cindex typography
+
+Musicians are usually more absorbed with performing the music than
+with studying its looks, so this nitpicking about typographical
+details may seem academical. That is not justified. In larger pieces
+with monotonous rhythms, spacing corrections lead to subtle variations
+in the layout of every line, giving each one a distinct visual
+signature. Without this signature, all lines would look the same, they
+become like a labyrinth. If the musician looks away once or has a
+lapse in his concentration, he will be lost on the page.
+
+Similarly, the strong visual look of bold symbols on heavy staff lines
+stands out better when music is far away from reader, for example, if
+it is on a music stand. A careful distribution of white space allows
+music to be set very tightly without cluttering symbols together. The
+result minimizes the number of page turns,
+
+This is a common characteristic of typography. Layout should be
+pretty, not only for its own sake, but especially because it helps the
+reader in his task. For performance material like sheet music, this is
+doubly important: musicians have a limited amount of attention. The
+less attention they need for reading, the more they can focus on
+playing itself. In other words, better typography translates to better
+performances.
+
+Hopefully, these examples also demonstrate that music typography is an
+art that is subtle and complex, and to produce it requires
+considerable expertise, which musicians usually do not have. LilyPond
+is our effort to bring the graphical excellence of hand-engraved music
+to the computer age, and make it available to normal musicians. We
+have tuned our algorithms, font-designs, and program settings to
+produce prints that match the quality of the old editions we love to
+see and love to play from.
-Encoding music using letters and digits may appear strange,
-intimidating or even clumsy at first. Nevertheless, when you take the
-effort to learn the codes and the program you will find that it is
-easier than it seems. Entering music can be done quickly, and you
-never have to remember how you made the program do something
-complicated: it is all in the input code, and you only have to read
-the file to see how it works. Moreover, you are rewarded with very
-nicely looking output.
-In this chapter, we will explain the reasoning behind this unusual
-design, and how this approach affects you as a user.
@menu
-* Batch processing::
-* Music engraving::
+* Automated engraving::
+* What symbols to engrave?::
* Music representation::
* Example applications::
* About this manual::
@end menu
-@node Batch processing
-@section Batch processing
+@node Automated engraving
+@section Automated engraving
-@cindex GUI
-@cindex Batch
-@cindex UNIX
+How do we go about implementing typography? If craftsmen need over
+ten years to become true masters, how could we simple hackers ever
+write a program to take over their jobs?
-When we started developing LilyPond, we were still studying at the
-university. We were interested in music notation, not as publishers
-or musicians, but as programmers and scientists. We wanted to figure
-to what extent formatting sheet music could be automated. Back then
-GUIs were not as ubiquitous as they are today, and we were immersed in
-the UNIX operating system, where it is very common to use compilers to
-achieve computing tasks. So, our computerized music engraving
-experiment took on the form of a compiler.
+The answer is: we cannot. Typography relies on human judgement of
+appearance, so people cannot be replaced ultimately. However, much of
+the dull work can be automated. If LilyPond solves most of the common
+situations correctly, then this will be a huge improvement over
+existing software. The remaining cases can be tuned by hand. Over the
+course of years, the software can be refined to do more and more
+automatically, so manual overrides are less and less necessary.
+When we started, we wrote the program in C++. With this design, the
+program functionality was set in stone stone by us developers. That
+proved to be unsatisfactory:
-@ignore
-@cindex free software
-@cindex sharing software
-You can freely use, modify and redistribute LilyPond. This choice was
-also motivated by our academic background. In the scientific community
-it has always been a tradition to share knowledge, also if that
-knowledge was packaged as software. One of the most visible groups
-that stimulated this philosophy, was the Free Software Foundation,
-whose popular GNU project aimed to replace closed and proprietary
-computing solutions with free (as in ``Libre'') variants. We jumped on
-that bandwagon, and released LilyPond as free software. That is the
-reason that you can get LilyPond at no cost and without any strings
-attached.
-@end ignore
+@itemize @bullet
+@item When LilyPond makes mistakes,
+ users need to override formatting decisions. Therefore, the user
+must access to the formatting engine. Hence, rules and settings cannot
+be fixed by us at compile time, but they must be accessible for users
+at run-time.
+
+@item Engraving is a matter of visual judgement, and therefore a matter of
+taste. As knowledgeable as we are, users can disagree with our
+personal decisions. Therefore, the definitions of typographical style
+must also be accessible to the user.
+
+@item Finally, we continually refine the formatting algorithms, so we
+need a flexible approach to rules. The C++ language forces a certain
+method of grouping rules that do not match well with how music
+notation works.
+@end itemize
-@node Music engraving
-@section Music engraving
+The formatting architecture of LilyPond addresses these needs. It is
+built around the notion graphical objects, carrying variables. The
+architecture encompasses formatting rules, typographical style and
+individual formatting decisions.
+
+Variables control layout decisions. For example, many objects have a
+direction variable that encodes the choice between up and down (or
+left and right). Here you see two chords, with accents and
+arpeggio. In the first chord, the objects have all directions down (or
+left). The second chord has all directions up (right).
+
+@lilypond[raggedright,relative=1]
+\new Score \with {
+ \override SpacingSpanner #'spacing-increment = #3
+ \override TimeSignature #'transparent = ##t
+} {
+ \stemDown
+ <e g b>4_>-\arpeggio
+
+ \override Arpeggio #'direction = #RIGHT
+ \stemUp
+ <e g b>4^>-\arpeggio
+}
+@end lilypond
+The process of formatting a score consists of reading and
+writing object variables.
+Some variables have a preset value. For example, the thickness of many
+lines ---a characteristic of typographical style--are preset
+variables. Changing them gives a different typographical impression:
+
+@lilypond[]
+frag= \notes {
+ \clef bass f8 as8
+ c'4-~ c'16 as g f e16 g bes c' des'4
+ }
+\paper { raggedright = ##t }
+
+\score {
+<< \new Staff \frag
+ \new Staff \with {
+ \override Beam #'thickness = #0.3
+ \override Stem #'thickness = #0.5
+ \override Bar #'thickness = #3.6
+ \override Tie #'thickness = #2.2
+ \override StaffSymbol #'thickness = #3.0
+ \override Tie #'extra-offset = #'(0 . 0.3)
+ } \frag
+ >>
+}
+@end lilypond
+
+Formatting rules are also preset variables: each object has variables
+containing procedures. These procedure perform the actual formatting,
+and by substituting different ones, we can change behavior. In the
+following example, the rule that note head objects use to produce
+their symbol is changed during the music fragment:
+
+
+@lilypond[raggedright]
+#(define (mc-squared gr org cur)
+ (let*
+ ((ifs (ly:grob-property gr 'interfaces))
+ (sp (ly:grob-property gr 'staff-position)) )
+ (if (and (memq 'note-head-interface ifs)
+ (memq sp '(-2 -3 -5)))
+ (begin
+ (ly:grob-set-property! gr 'print-function brew-new-markup-stencil)
+ (ly:grob-set-property! gr 'font-family 'roman)
+ (ly:grob-set-property!
+ gr 'text
+ (make-raise-markup -0.5
+ (case sp
+ ((-5) (make-simple-markup "m"))
+ ((-3) (make-simple-markup "c "))
+ ((-2) (make-smaller-markup (make-bold-markup "2")))
+ (else (make-simple-markup "bla"))
+ ))))
+ )))
+
+\score {
+ \notes \context Voice \relative c'
+ {
+ \stemUp
+ \set autoBeaming = ##f
+ \time 2/4
+ { <d f g>4
+ \once \override NoteHead #'print-function
+ = #Note_head::brew_ez_stencil
+ <d f g>
+ \once \override NoteHead #'style
+ = #'cross
+ <d f g>
+ \applyoutput #mc-squared
+ <d f g>
+ << { d8[ es-( fis^^ g] fis2-) }
+ \repeat unfold 5 { \applyoutput #mc-squared s8 } >>
+
+ }
+
+ }
+}
+@end lilypond
+
+
+
+@node What symbols to engrave?
+@section What symbols to engrave?
@cindex engraving
@cindex typography
-Making sheet music may seem trivial at first (``you print 5 lines, and
-then put in the notes at different heights''), @emph{music engraving},
-i.e. professional music typography, is in another ballpark. The term
-`music engraving' derives from the traditional process of music
-printing. Only a few decades ago, sheet music was made by cutting and
-stamping the music into zinc or pewter plates, mirrored. The plate
-would be inked, and the depressions caused by the cutting and stamping
-would hold ink. A positive image was formed by pressing paper to the
-plate. Stamping and cutting was completely done by hand. Making
-corrections was cumbersome, so engraving had to be done correctly in
-one go. As you can imagine this was a highly specialized skill, much
-more so than the traditional process of printing books.
-@cindex craftsmanship
-@cindex master
-In the traditional German craftsmanship six years of full-time
-training, more than any other craft, were required before a student
-could call himself a master of the art. After that many more years of
-practical experience were needed to become an established music
-engraver. Even today, with the use of high-speed computers and
-advanced software, music requires lots of manual fine tuning before it
-acceptable to be published.
-
-When we wanted to write a computer program to do create music
-typography, we encountered the first problem: there were no sets of
-musical symbols available: either they were not available freely, or
-they did not look well to our taste. Not let down, we decided to try
-font design ourselves. We created a font of musical symbols, relying
-on nice printouts of hand-engraved music. The experience helped
-develop a typographical taste, and it made us appreciate subtle design
-details. Without that experience, we would not have realized how ugly
-the fonts were that we admired at first.
-
+The formatting process in LilyPond decides where to place
+symbols. However, this can only be done once it is decided @emph{what}
+symbols should be printed, in other words what notation to use.
+
+Common music notation is a system of recording music that has evolved
+over the past 1000 years. The form that is now in common use, dates
+from the early renaissance. Although, the basic form (i.e. note heads on a
+5-line staff) has not changed, the details still change to express the
+innovations of contemporary notation. Hence, it encompasses some 500
+years of music. Its applications range from monophonic melodies to
+monstrous counterpoint for large orchestras.
+
+How can we get a grip on such a many-headed beast, and force it into
+the confines of a computer program? We have broken up the problem of
+notation (as opposed to engraving, i.e. typography) into digestible
+and programmable chunks: every type of symbol is handled by a separate
+module, a so-called plug-in. Each plug-in is completely modular and
+independent, so each can be developed and improved separately. People
+that translate musical ideas to graphic symbols are called copyists or
+engravers, so by analogy, each plug-in is called @code{engraver}.
+
+In the following example, we see how we start out with a plug-in for
+note heads, the @code{Note_heads_engraver}.
+
+@lilypond[]
+\include "engraver-example.lyinc"
+
+\score { \topVoice
+\paper {
+ \translator { \VoiceContext
+ \remove "Stem_engraver"
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+
+ }
+ \translator { \StaffContext
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Clef_engraver"
+ \remove "Bar_engraver"
+ \remove "Time_signature_engraver"
+ \remove "Staff_symbol_engraver"
+ \consists "Pitch_squash_engraver"
+ }
+
+}
+}
+@end lilypond
-@lilypond[noindent]
-#(define magfact 3.0)
-\score { \notes { as'2 r4 }
- \paper {
- raggedright = ##t
- \translator {
- \ScoreContext
- AccidentalPlacement \override #'right-padding = #3.0
- StaffSymbol \override #'transparent = ##t
- Clef \override #'transparent = ##t
- TimeSignature \override #'transparent = ##t
- Accidental \override #'font-magnification = #magfact
- Rest \override #'font-magnification = #magfact
- NoteHead \override #'font-magnification = #magfact
- Stem \override #'transparent = ##t
- } } }
+Then a @code{Staff_symbol_engraver} adds the staff:
+
+@lilypond[]
+\include "engraver-example.lyinc"
+
+\score { \topVoice
+\paper {
+ \translator { \VoiceContext
+ \remove "Stem_engraver"
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+
+ }
+ \translator { \StaffContext
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Clef_engraver"
+ \remove "Bar_engraver"
+ \consists "Pitch_squash_engraver"
+ \remove "Time_signature_engraver"
+ }
+
+}
+}
@end lilypond
-@cindex musical symbols
-@cindex font
-@cindex blackness
-@cindex balance
+ The @code{Clef_engraver} defines a reference point for the staff:
+
+@lilypond[]
+\include "engraver-example.lyinc"
+
+\score { \topVoice
+\paper {
+ \translator { \VoiceContext
+ \remove "Stem_engraver"
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+ }
+ \translator { \StaffContext
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Bar_engraver"
+ \remove "Time_signature_engraver"
+ }
+
+}
+}
+@end lilypond
+And the @code{Stem_engraver} adds stems:
+
+@lilypond[]
+\include "engraver-example.lyinc"
+
+\score { \topVoice
+\paper {
+ \translator { \VoiceContext
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+ }
+ \translator { \StaffContext
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Bar_engraver"
+ \remove "Time_signature_engraver"
+ }
+}
+}
+@end lilypond
-The figure above shows a few notable glyphs. For example, the
-vertical stem of a flat symbol should be slightly brushed,
-i.e. becoming wider at the top. the half-notehead is not elliptic but
-slightly diamond shaped. Fine endings, such as the one on the bottom
-of the quarter rest, should not end in sharp points, but rather in
-rounded shapes. Taken together, the blackness of the font must be
-carefully tuned together with the thickness of lines, beams and slurs
-to give a strong yet balanced overall impression.
+The @code{Stem_engraver} is notified of any note head coming along.
+Every time one (or more, for a chord) note head is seen, a stem
+object is created and connected to the note head.
-Producing a strong and balanced look is the real challenge of music
-engraving. It is a recurring theme with many variations. In spacing,
-the balance is in a distribution that reflects the character of the
-music. The spacing should not lead to unnatural clusters of black and
-big gaps with white space. The distances between notes should reflect
-the durations between notes, but adhering with mathematical precision
-to the duration will lead to a poor result. Shown here is an example
-of a motive, printed twice. It is printed using both exact
-mathematical spacing, and with some corrections. Can you spot which is
-which?
+By adding engravers for beams, slurs, accents, accidentals, bar lines,
+time signature, and key signature, we get a complete piece of
+notation.
+@lilypond[]
+\include "engraver-example.lyinc"
-@cindex optical spacing
-@lilypond[noindent]
- \score { \notes {
- \property Staff.NoteSpacing \set #'stem-spacing-correction
- = #0.6
- c'4 e''4 e'4 b'4 |
- \stemDown b'4 e''4 a'4 e''4| \stemBoth
- \property Staff.NoteSpacing \override #'stem-spacing-correction
- = #0.0
- \property Staff.StaffSpacing \override #'stem-spacing-correction
- = #0.0
- c'4 e''4 e'4 b'4 |
- \stemDown b'4 e''4 a'4 e''4|
- }
- \paper { raggedright = ##t } }
+\score { \topVoice }
@end lilypond
-@cindex regular rhythms
-@cindex regular spacing
-The fragment that was printed uses only quarter notes: notes that are
-played in a constant rhythm. The spacing should reflect
-that. Unfortunately, the eye deceives us a little: the eye not only
-notices the distance between note heads, but also between consecutive
-stems. As a result, the notes of a up-stem/down-stem combination
-should be put farther apart, and the notes of a down-up combination
-should be put closer together, all depending on the combined vertical
-positions of the notes. The first two measures are printed with this
-correction, the last two measures without. The notes in the last two
-measures form downstem/upstems clumps of notes.
-We hope that these examples show that music typography is a subtle
-business, and that it requires skill and knowledge to produce good
-engraving. It was our challenge to see if we could put such knowledge
-into a computer program.
+This system works well for monophonic music, but what about
+polyphony? In polyphonic notation, many voices can share a staff.
+@lilypond[]
+\include "engraver-example.lyinc"
+\score { \context Staff << \topVoice \\ \botVoice >> }
+@end lilypond
+
+In this situation, the accidentals and staff are shared, but the
+stems, slurs, beams, etc. are private to each voice. Hence, engravers
+should be grouped. The engravers for note heads, stems, slurs, etc. go
+into a group called ``Voice context,'' while the engravers for key,
+accidental, bar, etc. go into a group called ``Staff context.'' In the
+case of polyphony, a single Staff context contains more than one Voice
+context. In polyphonic notation, many voices can share a staff:
+Similarly, more Staff contexts can be put into a single Score context.
+
+@lilypond[]
+\include "engraver-example.lyinc"
+\score {
+<< \new Staff << \topVoice \\ \botVoice >>
+\new Staff << \pah \\ \hoom >>
+ >>
+}
+@end lilypond
@node Music representation
@section Music representation
+Ideally, the input format for any high-level formatting system is an
+abstract description of the content. In this case, that would be the
+music itself. This poses a formidable problem: how can we define what
+music really is? Instead of trying to find an answer, we have reversed
+the question. We write a program capable of producing sheet music,
+and adjust the format to be as lean as possible. When the format can
+no longer be trimmed down, by definition we are left with content
+itself. Our program serves as a formal definition of a music
+document.
+
+
+The syntax is also the user-interface for LilyPond, hence it is easily typable, e.g.,
+@example
+ c'4 d'8
+@end example
+Are a quarter note C (the middle C) and eighth note D1 (the D above
+middle C), as in this example:
+
+@lilypond[fragment]
+ c'4 d'8
+@end lilypond
+
+On a microscopic scale, such syntax is easy to use. On a larger scale,
+syntax also needs structure. How else can you enter complex pieces
+like symphonies and operas? The structure is formed by the concept of
+music expressions: by combining small fragments of music into larger
+ones, more complex music can be expressed. For example,
+
+@lilypond[verbatim,fragment,relative=1]
+c4
+@end lilypond
+
+Combine this simultaneously with two other notes by enclosing in << and >>.
+
+
+@lilypond[verbatim,fragment,relative=1]
+ <<c4 d4 e4>>
+@end lilypond
+
+
+
+This expression is put in sequence by enclosing it in braces, i.e.,
+
+@verbatim
+ { <<c4 d4 e4>> f4 }
+@end verbatim
+
+@lilypond[relative=1]
+ \new Voice { <<c4 d4 e4>> f4 }
+@end lilypond
+
+The above is another expression, and therefore, it many combined again
+with a simultaneous expression (in this case, a half note).
+
+@verbatim
+ << { <<c4 d4 e4>> f4 } g2 >>
+@end verbatim
+@lilypond[fragment,relative=1]
+<< g2 \\ { <c d e>4 f4 } >>
+@end lilypond
+
+
+Such recursive structures can be specified neatly and formally in a
+context-free grammar. The parsing code is also generated from this
+grammar. In other words, the syntax of LilyPond is clearly and
+unambiguously defined.
+
+User-interfaces and syntax are what people see and deal with
+most. They are partly a matter of taste, and also subject of much
+discussion. Although discussions on taste do have their merit, they
+are not very productive. In the larger picture of LilyPond, the
+importance of input syntax is small: inventing neat syntax is easy,
+writing decent formatting code is much harder. This is also
+illustrated by the line-counts for the respective components: parsing
+and representation take up less than 10% of the code.
-One of the big questions when making programs, is what kind of input
-the program should expect. Many music notation programs offer a
-graphical interface that shows notation, and allow you to enter the
-music by placing notes on a staff. From our point of view, this design
-is a form of cheating. After all, the core message of a piece of music
-notation simply is the music itself. If you start by offering notation
-to the user, you have already skipped one conversion, even if it is
-implicit. If we want to generate music notation from something else,
-then the obvious candidate for the source is the music itself.
-
-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. Instead of losing ourselves in
-philosophical arguments over the essence of music, we have reversed
-the question to yield a more practical approach. Our assumption is
-that the printed score contains all of the music of piece. We build a
-program that uses some input format to produce such a score. Over the
-course of time, the program evolves. While this happens, we can remove
-more and more elements of the input format: as the program improves,
-it can fill in irrelevant details of the input by itself. At some
-(hypothetical) point, the program is finished: there is no possibility
-to remove any more elements from the syntax. What we have left is by
-definition exactly the musical meaning of the score.
-
-There are also more practical concerns. Our users have to key in the
-music into the file directly, so the input format should have a
-friendly syntax. As programmers and scientists, we want a
-clean formal definition. After all, producing music notation is a
-difficult problem, and in the scientific world, problems can only be
-solved if they are well-specified. Moreover, formally defined formats
-are easier to write programs for.
-
-These ideas shaped our music representation: it is a compact format
-that can easily be typed by hand. It complex musical constructs from
-simple entities like notes and rests, in much the same way that one
-builds complex formulas from simple expressions such as numbers and
-mathematical operators.
@node Example applications
@section Example applications
-As programmers and hedonists we enjoy beauty in code, and code that
-produces beautiful typeset music, but nevertheless this program can
-applied to do useful things. In this section, we show a few small
-examples of what is possible.
-
-The simplest application, is printing just notes.
+We have written LilyPond as an experiment of how to condense the art
+of music engraving into a computer program. Thanks to all that hard
+work, the program can now be used to perform useful tasks. The
+simplest application is printing notes:
@lilypond[relative=1]
\time 2/4 c4 c g'4 g a4 a g2
@end lilypond
-To these notes, chord names and lyrics may be added
+By adding chord names and lyrics we obtain a lead sheet:
@lilypond[raggedright]
-\score { <
+\score { <<
\context ChordNames \chords { c2 c f2 c }
- \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
- \context Lyrics \lyrics { twin kle twin kle lit tle star } > }
+ \new Staff \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
+ \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } >> }
@end lilypond
+Polyphonic notation and piano music can also be printed. The following
+example combines some more exotic constructs:
-[TODO: need piano and tab example]
+@lilypondfile{screech-boink.ly}
-The following example combines some more exotic uses of notation
+The fragments shown above have all been written by hand, but that is
+not a requirement. Since the formatting engine is mostly automatic, it
+can serve as an output means for other programs that manipulate
+music. For example, it can also be used to convert databases of
+musical fragments to images for use on websites and multimedia
+presentations.
-@lilypondfile{screech-boink.ly}
+This manual also shows an application: the input format is plain text,
+and can therefore be easily embedded in other text-based formats, such
+as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
+special program, the input fragments can be replaced by music images in
+the resulting PostScript or HTML output files. This makes it easy to
+mix music and text in documents.
@node About this manual
@section About this manual
-The manual is divided into the following chapters
+The manual is divided into the following chapters:
@itemize @bullet
-@item The @emph{tutorial}
-(@ref{Tutorial}) gives a gentle introduction into typesetting music.
+@item
+@ifhtml The
+@end ifhtml
+@emph{@ref{Tutorial}}
+gives a gentle introduction to typesetting music.
First time users should start here.
-@item The @emph{notation manual} (@ref{Notation manual}),
-is a user manual that discusses topics grouped by notation construct.
-@item The @emph{technical manual} (@ref{Advanced topics})
-discusses the general design of the program, and how to extend the
+@item
+@ifhtml
+The
+@end ifhtml
+@emph{@ref{Notation manual}}
+discusses topics grouped by notation construct. Once you master the
+basics, this is the place to look up details.
+@item
+@ifhtml
+The
+@end ifhtml
+@emph{@ref{Literature list}}
+ contains a set of useful reference books, for those who wish to know
+ more on notation and engraving.
+@item
+@ifhtml
+ The
+ @end ifhtml
+@emph{@ref{Technical manual}}
+@c
+discusses the general design of the program, and how to extend its
functionality.
-@item The chapter
-on @emph{Invoking} (@ref{Invoking LilyPond}) explains how to run LilyPond and its helper
+@item
+@ifhtml
+The chapter
+@end ifhtml
+@emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
programs.
+
+@item
+@ifhtml
+The
+@end ifhtml
+@emph{@ref{lilypond-book manual}}
+explains the details behind creating documents with in-line music
+examples (like this manual).
+
+
+@item
+@ifhtml
+The chapter
+@end ifhtml
+@emph{@ref{Converting from other formats}}
+explains how to run the conversion programs. These programs
+are supplied with the LilyPond package, and convert a variety of music
+formats to the @code{.ly} format. In addition, this section explains
+how to upgrade input files from previous versions of LilyPond.
+
@end itemize
-Once you are experienced, you can simply use the manual as reference:
+Once you are an experienced user, you can use the manual as reference:
there is an extensive index@footnote{If you are looking for something,
-and you cannot find it by using the index, that is considered a bug.
-In that case, please file a bug report}, but the document is also
+and you cannot find it in the manual, that is considered a bug. In
+that case, please file a bug report.}, but the document is also
available in
@ifnothtml
-One Big Page,
+a big HTML page,
@end ifnothtml
@ifhtml
-@uref{One Big Page,../lilypond.html}
+@uref{../lilypond.html, a big HTML page}
@end ifhtml
-which is is available for text search using your browser's search
-facility.
+which can be searched easily using the search facility of a web
+browser.
@cindex search in manual
@cindex using the manual
-If you are familiar with music notation, and music terminology
-(especially if you are a foreigner), then it is advisable to consult
-the glossary as well. This documents explains many terms, and includes
-translations to various languages. It is a
+If you are not familiar with music notation or music terminology
+(especially if you are a non-native English speaker), then it is
+advisable to consult the glossary as well. The glossary explains
+musical terms, and includes translations to various languages. It is a
@ifhtml
-@uref{../glossary.html,separate document}
+@uref{../music-glossary.html,separate document}.
@end ifhtml
@ifnothtml
-separate document, and can be printed as well.
+separate document, available in HTML and PDF.
@end ifnothtml
@cindex idiom
@cindex jargon
This manual is not complete without a number of other documents. They
are not available in print, but should be included with the
-documentation package for your platform
+documentation package for your platform:
@itemize @bullet
@item
-Generated internal documentation.
+Program reference
@ifhtml
-available @uref{../lilypond-internals/lilypond-internals.html,here}
+(available @uref{../lilypond-internals/lilypond-internals.html,here})
@end ifhtml
+The program reference is a set of heavily cross linked HTML pages,
+which documents the nit-gritty details of each and every LilyPond
+class, object and function. It is produced directly from the
+formatting definitions used.
+
Almost all formatting functionality that is used internally, is
available directly to the user. For example, all variables that
control thicknesses, distances, etc, can be changed in input
-files. There are a huge number of formatting options, and it would be
-impossible to describe them all in a hand-written manual. The
-generated internal documentation is a heavily crosslinked HTML
-document, produced directly from the formatting definitions used. It
-documents the nit-gritty details of each and every LilyPond class, object and
-function.
-
-Each section of the reference manual has a @b{See also}
-subsection, with links (in the HTML document, at least) to the
-generated documentation.
+files. There are a huge number of formatting options, and all of them
+are described in the generated documentation. Each section of the
+notation manual has a @b{See also} subsection, which refers to the
+the generated documentation. In the HTML document, these subsections
+have clickable links.
@item
Templates
@ifhtml
-(available @uref{../../../input/templates/out-www/collated-files.html,here})
+(available @uref{../../../input/template/out-www/collated-files.html,here})
@end ifhtml
- When you have gone through the tutorial, you theoretically should be
-able to start writing input files. However, this turns out to be a
-little intimidating. To give you a headstart, we have collected a
-number of often-used formats in example files. You can take one of
-these example files, and add notes in the appropriate places to
-generate output.
+After you have gone through the tutorial, you should be able to write
+input files. In practice, writing files from scratch turns out to be
+intimidating. To give you a head start, we have collected a number of
+often-used formats in example files. These files can be used as a
+start: simply copy the template, and add notes in the appropriate
+places.
@item
Various input examples
@ifhtml
-available @uref{../../../input/test/out-www/collated-files.html,here}
+(available @uref{../../../../input/test/out-www/collated-files.html,here})
@end ifhtml
@cindex snippets
-These small files show various applications of lilypond, and are
-available as a big HTML document, with pictures and explanatory texts
-included.
+These small files show various tips and tricks, and are available as a
+big HTML document, with pictures and explanatory texts included.
@item
- The regression test
+ The regression tests
@ifhtml
-available @uref{../../../input/regression/out-www/collated-files.html,here}
+(available @uref{../../../input/regression/out-www/collated-files.html,here})
@end ifhtml
-We strive to test each feature in one test file. This collection of is
-primarily to help us debug problems, but it can be instructive to see
-how we excercise the program. The format is like the input examples.
+This collection of files tests each notation and engraving feature of
+LilyPond in one file. The collection is primarily there to help us
+debug problems, but it can be instructive to see how we exercise the
+program. The format is like the tips and tricks document.
@end itemize
+
+In all HTML documents that have music fragments embedded, the LilyPond
+input that was used to produce that image can be viewed by clicking
+the image.
+
The location of the documentation files that are mentioned here can
-vary from system to system. Throughout this manual, we refer to input
-files relative to the top-directory of the source archive. For
+vary from system to system. On occasion, this manual refers to
+initialization and example files. Throughout this manual, we refer to
+input files relative to the top-directory of the source archive. For
example, @file{input/test/bla.ly} may refer to the file
@file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
-Unix platform, these can typically be found somewhere below
-@file{/usr/share/doc/lilypond/}. Initialization files, for example
-@file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are usually found
-in the directory @file{/usr/share/lilypond/}.
+Unix platform, the documentation and examples can typically be found
+somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
+for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
+usually found in the directory @file{/usr/share/lilypond/}.
@cindex adjusting output
@cindex variables
@cindex internal documentation
@cindex Scheme
@cindex extending lilypond
-@cindex bugreport
+@cindex bug report
@cindex index
+
+Finally, this and all other manuals, are available online both as PDF
+files and HTML from the web site, which can be found at
+@uref{http://www.lilypond.org/}.
+
+@cindex website
+@cindex URL