version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.12.0"
+@c \version "2.13.4"
@node Music engraving
@chapter Music engraving
-insert essay here.
+This section covers the overall goals and architecture of
+LilyPond.
-TODO: add extra chapter for computer aesthetics?
+@menu
+* Engraving::
+* Automated engraving::
+* What symbols to engrave?::
+* Music representation::
+* Example applications::
+@end menu
+
+
+@node Engraving
+@unnumberedsec Engraving
+
+@cindex engraving
+@cindex typography, music
+@cindex music typography
+@cindex plate engraving
+@cindex music engraving
+
+The art of music typography is called @emph{(plate) engraving}. The term
+derives from the traditional process of music printing. Just a few
+decades ago, sheet music was made by cutting and stamping the music into
+a zinc or pewter plate 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 done completely by hand. Making a correction was cumbersome,
+so the engraving had to be nearly perfect in one go. Engraving was a
+highly specialized skill; a craftsman had to complete around five years
+of training before earning the title of master engraver, and another
+five years of experience were necessary to become truly skilled.
+
+@quotation
+@iftex
+@image{pictures/hader-slaan,,7cm}
+@end iftex
+@ifnottex
+@sourceimage{hader-slaan,,,jpg}
+@end ifnottex
+@end quotation
+
+Nowadays, all newly printed music is produced with computers. This has
+obvious advantages: prints are cheaper to make, editorial work can be
+delivered by email, and the original data can be easily stored.
+Unfortunately, computer-generated scores rarely match the quality of
+hand-engraved scores. Instead, computer printouts have a bland,
+mechanical look, which makes them unpleasant to play from.
+
+From the beginning, we designed LilyPond to mimic the beauty of
+traditional music engraving. Along the way, we have learned a great deal
+about the work that goes into a well-engraved score. Below we describe
+several of those aspects that we have tried to imitate in LilyPond.
+
+@menu
+* Music Fonts::
+* Optical Spacing::
+* Ledger Lines::
+* Slurs::
+* Why work so hard?::
+@end menu
+
+@node Music Fonts
+@unnumberedsubsec Music Fonts
+
+The images below illustrate the difference between traditional engraving
+and typical computer output. The left picture shows a scan of a flat
+symbol from a hand-engraved Bärenreiter edition, while the right picture
+depicts a symbol from an edition of the same music published in 2000.
+Although both images are printed in the shame shade of ink, the earlier
+version looks darker: the staff lines are heavier, and the Bärenreiter
+flat has a bold, almost voluptuous rounded look. The right scan, on the
+other hand, has thinner lines and a straight layout with sharp corners.
+
+@multitable @columnfractions .25 .25 .25 .25
+@item @tab
+@ifnotinfo
+@iftex
+@image{pictures/baer-flat-gray,,4cm}
+@end iftex
+@ifnottex
+@image{pictures/baer-flat-gray,,,png}
+@end ifnottex
+
+@tab
+@iftex
+@image{pictures/henle-flat-gray,,4cm}
+@end iftex
+@ifnottex
+@image{pictures/henle-flat-gray,,,png}
+@end ifnottex
+
+@end ifnotinfo
+@ifinfo
+@image{lilypond/pictures/henle-flat-bw,,,,png}
+@image{lilypond/pictures/baer-flat-bw,,,,png}
+@image{lilypond/pictures/lily-flat-bw,,,,png}
+@end ifinfo
+
+
+@item @tab
+Bärenreiter (1950)
+@tab
+Henle (2000)
+
+@end multitable
+
+@cindex musical symbols
+@cindex font
+@cindex blackness
+@cindex balance
+
+When we wanted to write a computer program to create music typography,
+there were no musical fonts freely available that could match the
+elegance of our favorite scores. Not let down, 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.
+
+Below is a sample of two music fonts: the upper set is the default font
+in the Sibelius software (the @emph{Opus} font), and the lower set is
+our own LilyPond font.
+
+@quotation
+@iftex
+@image{pictures/pdf/OpusAndFeta,,,}
+@end iftex
+@ifnottex
+@sourceimage{OpusAndFeta,,,png}
+@end ifnottex
+@end quotation
+
+The LilyPond symbols are heavier and their weight is more consistent,
+which makes them easier to read. Fine endings, such as the one on the
+bottom of the quarter rest, should not end in sharp points, but rather
+in rounded shapes. This is because sharp corners of the punching dies
+are fragile and quickly wear out when stamping in metal. 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.
+
+Also, notice that our half-notehead is not elliptic but slightly diamond
+shaped. The vertical stem of a flat symbol is slightly brushed, becoming
+wider at the top. The sharp and the natural are easier to distinguish
+from a distance because their angled lines have different slopes and the
+vertical strokes are heavier.
+
+@node Optical Spacing
+@unnumberedsubsec Optical Spacing
+
+In spacing, the distribution of space should reflect the durations
+between notes. However, many modern scores adhere to the
+durations with mathematical precision, which leads to poor
+results. In the next example a motive is printed twice: the first time
+using exact mathematical spacing, and the second with corrections.
+Which do you prefer?
+
+@cindex optical spacing
+
+@lilypond
+\paper {
+ ragged-right = ##t
+ indent = #0.0
+}
+
+music = {
+ c'4 e''4 e'4 b'4 |
+ \stemDown
+ b'8[ e'' a' e'']
+ \stemNeutral
+ e'8[ e'8 e'8 e'8]
+}
+\score
+{
+ \music
+ \layout {
+ \context {
+ \Staff
+ \override NoteSpacing #'stem-spacing-correction = #0.0
+ \override NoteSpacing #'same-direction-correction = #0.0
+ \override StaffSpacing #'stem-spacing-correction = #0.0
+ }
+ }
+}
+@end lilypond
+
+@lilypond
+\paper {
+ ragged-right = ##t
+ indent = #0.0
+}
+
+music = {
+ c'4 e''4 e'4 b'4 |
+ \stemDown
+ b'8[ e'' a' e'']
+ \stemNeutral
+ e'8[ e'8 e'8 e'8]
+}
+
+\score
+{
+ \music
+ \layout {
+ \context {
+ \Staff
+ \override NoteSpacing #'stem-spacing-correction = #0.6
+ }
+ }
+}
+@end lilypond
+
+@cindex regular rhythms
+@cindex regular spacing
+@cindex spacing, regular
+
+Each bar in the fragment only uses 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-stem/@/up-stem combination should be put
+closer together, all depending on the combined vertical positions
+of the notes. The upper two measures are printed with this
+correction, the lower two measures, however, form down-stem/@/up-stem
+clumps of notes. A master engraver would adjust the spacing as needed to
+please the eye.
+
+Another example of optical spacing is the visual interplay between the
+stems and the bar lines. When an up-stem precedes the bar line, a little
+more space is needed to keep it from feeling crowded:
+
+@lilypond
+\paper {
+ ragged-right = ##t
+}
+
+\score {
+ {
+ c''8 c'' c'' c'' c'' c'' c'' c'' \break
+ a' a' a' a' a' a' a' a'
+ }
+ \layout {
+ \context {
+ \Staff
+ \remove "Time_signature_engraver"
+ \override NoteSpacing #'stem-spacing-correction = #0.7
+ }
+ }
+}
+@end lilypond
+
+@node Ledger Lines
+@unnumberedsubsec Ledger Lines
+
+@ifnotinfo
+@iftex
+@image{pictures/baer-ledger,4cm}
+@end iftex
+@ifnottex
+@image{pictures/baer-ledger,,,png}
+@end ifnottex
+@end ifnotinfo
+@ifinfo
+@image{lilypond/pictures/baer-ledger,,,,png}
+@end ifinfo
+
+@node Slurs
+@unnumberedsubsec Slurs
+
+@node Why work so hard?
+@unnumberedsubsec Why work so hard?
+
+Musicians are usually more absorbed with performing than with
+studying the looks of a piece of music, so nitpicking
+typographical details may seem academic. But it is not. 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, and they become like a labyrinth. A distinct visual
+signature helps to keep musicians from losing their place on the
+page when they look away or have a lapse in concentration.
+
+Similarly, the strong visual look of bold symbols on heavy staff
+lines stands out better when the music is far away from the
+reader: for example, if it is on a music stand. A careful
+distribution of white space allows music to be set very tightly
+without crowding symbols together. The result minimizes the
+number of page turns, which is a great advantage.
+
+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 her task. For performance material like sheet
+music, this is of double importance: musicians have a limited
+amount of attention. The less attention they need for reading,
+the more they can focus on playing the music. In other words,
+better typography translates to better performances.
+
+These examples demonstrate that music typography is an art that is
+subtle and complex, and that producing 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.
+
+
+@node Automated engraving
+@unnumberedsec Automated engraving
+
+@cindex engraving, automated
+@cindex automated engraving
+
+@menu
+* Beauty contests::
+* Notation benchmarking::
+* Flexible architecture::
+@end menu
+
+@node Beauty contests
+@unnumberedsubsec Beauty contests
+
+@node Notation benchmarking
+@unnumberedsubsec Notation benchmarking
+
+Bärenreiter:
+
+@ifnotinfo
+@iftex
+@image{pictures/baer-sarabande,16cm}
+@end iftex
+@ifnottex
+@image{pictures/baer-sarabande,,,png}
+@end ifnottex
+@end ifnotinfo
+@ifinfo
+@image{lilypond/pictures/baer-sarabande,,,,png}
+@end ifinfo
+
+LilyPond 1.4:
+
+@ifnotinfo
+@iftex
+@image{pictures/lily14-sarabande,16cm}
+@end iftex
+@ifnottex
+@image{pictures/lily14-sarabande,,,png}
+@end ifnottex
+@end ifnotinfo
+@ifinfo
+@image{lilypond/pictures/lily14-sarabande,,,,png}
+@end ifinfo
+
+LilyPond @version{}:
+
+@lilypond[relative=0,staffsize=19,line-width=16\cm]
+{
+ \clef "bass"
+ \key d \minor
+ \time 3/4
+ \mergeDifferentlyDottedOn
+ << {d8. e16 e4. d16 e} \\ {d4 a2} >>
+ <f' a, d,>4. e8 d c
+ bes g' f e16( f g a bes d,)
+ cis4. b8 a g
+ << {d'8. e16 e4. d16 e} \\ {<f, a>4 a2} >>
+}
+@end lilypond
+
+[LilyPond snippet above not finished]
+
+[a few bars of LilyPond vs. Finale can go here]
+
+@node Flexible architecture
+@unnumberedsubsec Flexible architecture
+
+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?
+
+The answer is: we cannot. Typography relies on human judgment of
+appearance, so people cannot be replaced completely. However,
+much of the dull work can be automated. If LilyPond solves most
+of the common situations correctly, 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 things automatically, so manual
+overrides are less and less necessary.
+
+When we started, we wrote the LilyPond program entirely in the C++
+programming language; the program's functionality was set in stone
+by the developers. That proved to be unsatisfactory for a number
+of reasons:
+
+@itemize
+
+@item When LilyPond makes mistakes, users need to override
+formatting decisions. Therefore, the user must have access to the
+formatting engine. Hence, rules and settings cannot be fixed by
+us at compile-time but must be accessible for users at run-time.
+
+@item Engraving is a matter of visual judgment, 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 cannot readily be applied to
+formatting music notation.
+
+@end itemize
+
+@cindex Scheme programming language
+
+These problems have been addressed by integrating an interpreter
+for the Scheme programming language and rewriting parts of
+LilyPond in Scheme. The current formatting architecture is built
+around the notion of graphical objects, described by Scheme
+variables and functions. This architecture encompasses formatting
+rules, typographical style and individual formatting decisions.
+The user has direct access to most of these controls.
+
+Scheme variables control layout decisions. For example, many
+graphical 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 arpeggios. In the first chord, the
+graphical objects have all directions down (or left). The second
+chord has all directions up (right).
+
+@lilypond[quote,ragged-right]
+\new Score \with {
+ \override SpacingSpanner #'spacing-increment = #3
+ \override TimeSignature #'transparent = ##t
+} \relative c' {
+ \stemDown <e g b>4_>-\arpeggio
+ \override Arpeggio #'direction = #RIGHT
+ \stemUp <e g b>4^>-\arpeggio
+}
+@end lilypond
+@cindex score formatting
+@cindex formatting a score
+@cindex formatting rules
+
+@noindent
+The process of formatting a score consists of reading and writing
+the variables of graphical objects. Some variables have a preset
+value. For example, the thickness of many lines -- a
+characteristic of typographical style -- is a variable with a
+preset value. You are free to alter this value, giving your score
+a different typographical impression.
+
+@lilypond[quote,ragged-right]
+fragment = {
+ \clef bass f8 as8
+ c'4-~ c'16 as g f e16 g bes c' des'4
+}
+<<
+ \new Staff \fragment
+ \new Staff \with {
+ \override Beam #'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)
+ }
+ \fragment
+>>
+@end lilypond
+
+Formatting rules are also preset variables: each object has
+variables containing procedures. These procedures perform the
+actual formatting, and by substituting different ones, we can
+change the appearance of objects. In the following example, the
+rule governing which note head objects are used to produce the
+note head symbol is changed during the music fragment.
+
+@lilypond[quote,ragged-right]
+#(set-global-staff-size 30)
+
+#(define (mc-squared grob orig current)
+ (let* ((interfaces (ly:grob-interfaces grob))
+ (pos (ly:grob-property grob 'staff-position)))
+ (if (memq 'note-head-interface interfaces)
+ (begin
+ (ly:grob-set-property! grob 'stencil
+ (grob-interpret-markup grob
+ (make-lower-markup 0.5
+ (case pos
+ ((-5) "m")
+ ((-3) "c ")
+ ((-2) (make-smaller-markup (make-bold-markup "2")))
+ (else "bla")))))))))
+
+\new Voice \relative c' {
+ \stemUp
+ \set autoBeaming = ##f
+ \time 2/4
+ <d f g>4
+ \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
+ \once \override NoteHead #'font-size = #-7
+ \once \override NoteHead #'font-family = #'sans
+ \once \override NoteHead #'font-series = #'bold
+ <d f g>4
+ \once \override NoteHead #'style = #'cross
+ <d f g>4
+ \applyOutput #'Voice #mc-squared
+ <d f g>4
+ <<
+ { d8[ es-( fis^^ g] fis2-) }
+ \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
+ >>
+}
+@end lilypond
+
+
+@node What symbols to engrave?
+@unnumberedsec What symbols to engrave?
+
+@cindex engraving
+@cindex typography
+@cindex engraver
+@cindex plug-in
+
+The formatting process 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 evolve to express the innovations of contemporary notation.
+Hence, common music notation encompasses some 500 years of music.
+Its applications range from monophonic melodies to monstrous
+counterpoints for a large orchestra.
+
+How can we get a grip on such a seven-headed beast, and force it
+into the confines of a computer program? Our solution is to break
+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. Such plug-ins are called
+@code{engraver}s, by analogy with craftsmen who translate musical
+ideas to graphic symbols.
+
+In the following example, we start out with a plug-in for note
+heads, the @code{Note_heads_engraver}.
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+
+\score {
+ \topVoice
+ \layout {
+ \context {
+ \Voice
+ \remove "Stem_engraver"
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+ }
+ \context {
+ \Staff
+ \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
+
+@noindent
+Then a @code{Staff_symbol_engraver} adds the staff,
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+
+\score {
+ \topVoice
+ \layout {
+ \context {
+ \Voice
+ \remove "Stem_engraver"
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+ }
+ \context {
+ \Staff
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Clef_engraver"
+ \remove "Bar_engraver"
+ \consists "Pitch_squash_engraver"
+ \remove "Time_signature_engraver"
+ }
+ }
+}
+@end lilypond
+
+@noindent
+the @code{Clef_engraver} defines a reference point for the staff,
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+
+\score {
+ \topVoice
+ \layout {
+ \context {
+ \Voice
+ \remove "Stem_engraver"
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+ }
+ \context {
+ \Staff
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Bar_engraver"
+ \remove "Time_signature_engraver"
+ }
+ }
+}
+@end lilypond
+
+@noindent
+and the @code{Stem_engraver} adds stems.
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+
+\score {
+ \topVoice
+ \layout {
+ \context {
+ \Voice
+ \remove "Phrasing_slur_engraver"
+ \remove "Slur_engraver"
+ \remove "Script_engraver"
+ \remove "Beam_engraver"
+ \remove "Auto_beam_engraver"
+ }
+ \context {
+ \Staff
+ \remove "Accidental_engraver"
+ \remove "Key_engraver"
+ \remove "Bar_engraver"
+ \remove "Time_signature_engraver"
+ }
+ }
+}
+@end lilypond
+
+@noindent
+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. By adding
+engravers for beams, slurs, accents, accidentals, bar lines, time
+signature, and key signature, we get a complete piece of notation.
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+\score { \topVoice }
+@end lilypond
+
+@cindex polyphony
+@cindex engraving multiple voices
+@cindex contexts
+
+This system works well for monophonic music, but what about
+polyphony? In polyphonic notation, many voices can share a staff.
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+\new 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 @q{Voice context,} while the
+engravers for key, accidental, bar, etc., go into a group called
+@q{Staff context.} In the case of polyphony, a single Staff
+context contains more than one Voice context. Similarly, multiple
+Staff contexts can be put into a single Score context. The Score
+context is the top level notation context.
+
+
+@seealso
+Internals Reference: @rinternals{Contexts}.
+
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+\score {
+ <<
+ \new Staff << \topVoice \\ \botVoice >>
+ \new Staff << \pah \\ \hoom >>
+ >>
+}
+@end lilypond
+
+
+@node Music representation
+@unnumberedsec Music representation
+
+@cindex syntax
+@cindex recursive structures
+
+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
+easy to type:
+
+@example
+@{
+ c'4 d'8
+@}
+@end example
+
+@noindent
+to create a quarter note on middle C (C1) and an eighth note on
+the D above middle C (D1).
+
+@lilypond[quote]
+{
+ 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[quote,verbatim,fragment,relative=1]
+f4
+@end lilypond
+
+@noindent
+Simultaneous notes can be constructed by enclosing them with
+@code{<<} and @code{>>}:
+
+@example
+<<c4 d4 e4>>
+@end example
+
+@lilypond[quote,fragment,relative=1]
+\new Voice { <<c4 d4 e>> }
+@end lilypond
+
+@noindent
+This expression is put in sequence by enclosing it in curly braces
+@code{@{@tie{}@dots{}@tie{}@}}:
+
+@example
+@{ f4 <<c4 d4 e4>> @}
+@end example
+
+@lilypond[quote,relative=1,fragment]
+{ f4 <<c d e4>> }
+@end lilypond
+
+@noindent
+The above is also an expression, and so it may be combined again
+with another simultaneous expression (a half note) using
+@code{<<}, @code{\\}, and @code{>>}:
+
+@example
+<< g2 \\ @{ f4 <<c4 d4 e4>> @} >>
+@end example
+
+@lilypond[quote,fragment,relative=2]
+\new Voice { << g2 \\ { f4 <<c d e>> } >> }
+@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 the 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, while 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 source code.
+
+
+@node Example applications
+@unnumberedsec Example applications
+
+@cindex simple examples
+@cindex examples, simple
+
+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[quote,relative=1]
+{
+ \time 2/4
+ c4 c g'4 g a4 a g2
+}
+@end lilypond
+
+@noindent
+By adding chord names and lyrics we obtain a lead sheet.
+
+@lilypond[quote,ragged-right]
+<<
+ \chords { c2 c f2 c }
+ \new Staff
+ \relative c' {
+ \time 2/4
+ c4 c g' g a a g2
+ }
+ \addlyrics { twin -- kle twin -- kle lit -- tle star }
+>>
+@end lilypond
+
+Polyphonic notation and piano music can also be printed. The
+following example combines some more exotic constructs.
+
+@lilypond[quote]
+\header {
+ title = "Screech and boink"
+ subtitle = "Random complex notation"
+ composer = "Han-Wen Nienhuys"
+}
+
+\score {
+ \context PianoStaff <<
+ \new Staff = "up" {
+ \time 4/8
+ \key c \minor
+ << {
+ \revert Stem #'direction
+ \change Staff = down
+ \set subdivideBeams = ##t
+ g16.[
+ \change Staff = up
+ c'''32
+ \change Staff = down
+ g32
+ \change Staff = up
+ c'''32
+ \change Staff = down
+ g16]
+ \change Staff = up
+ \stemUp
+ \set followVoice = ##t
+ c'''32([ b''16 a''16 gis''16 g''32)]
+ } \\ {
+ s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
+ } \\ {
+ s4 \autoBeamOff d''8.. f''32
+ } \\ {
+ s4 es''4
+ } >>
+ }
+
+ \new Staff = "down" {
+ \clef bass
+ \key c \minor
+ \set subdivideBeams = ##f
+ \override Stem #'french-beaming = ##t
+ \override Beam #'beam-thickness = #0.3
+ \override Stem #'thickness = #4.0
+ g'16[ b16 fis16 g16]
+ << \makeClusters {
+ as16 <as b>
+ <g b>
+ <g cis>
+ } \\ {
+ \override Staff.Arpeggio #'arpeggio-direction =#down
+ <cis, e, gis, b, cis>4\arpeggio
+ }
+ >> }
+ >>
+ \midi {
+ \context {
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 60 8)
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ \consists Horizontal_bracket_engraver
+ }
+ }
+}
+@end lilypond
+
+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.
+
+This manual also shows an application: the input format is text,
+and can therefore be easily embedded in other text-based formats
+such as @LaTeX{}, 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 PDF or HTML output files. This
+makes it easy to mix music and text in documents.
+
+
+TODO: add extra chapter for computer aesthetics?
projects / lilypond.git / blobdiff