-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 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-stems clumps of notes.
-
-@node Computerized typography
-@section Computerized typography
-
-Producing good engraving requires skill and knowledge. It was our
-challenge to see if we could put such typographical knowledge into a
-computer program. Capturing that knowledge has two aspects: first, it
-has to be acquired. Then, it has to be encoded in data-structures and
-algorithms. As the previous examples show, there is a lot of subtlety
-involved in music engraving, and unfortunately, only a small fraction
-of these details are documented.
-
-One reason for the time that it takes to become a master engraver, is
-that all these details must be learned either from experience or from
-other engravers: as an engraver gets older and wiser, he will be able
-to produce better and more complex pieces. A similar situation is
-present when putting typography into computer programs. It is not
-possible to come up with a final solution for a problem at the first
-try. Instead, we start out with simple solution that might cover 75%
-of the cases, and gradually refine that solution over the course of
-months or years, so that 90 or 95 % of the cases are handled.
-
-This has an important implication for the design of the
-program. During development, almost every piece of formatting code
-must be considered as temporary. When the need arises, is to be
-replaced a solution that will cover even more cases. A clean way to
-accomplish this, is a ``plug-in'' architecture: an architecture where
-new pieces of code can be inserted in the program dynamically. In
-such a program, a new solution can be developed along-side the
-existing code. It can be perfected separately until it is better than
-the existing solution, at which point, the new solution is switched on
-by default, and the old one is removed.
-
-Until that time, users must have a way to deal with imperfections:
-these 25%, 10% or 5% of the cases that are not handled
-automatically. In these cases, a user must be able to override
-formatting decisions. A way to accomplish this, is to store decisions
-in generic variables, and let the user manipulate these variables.
-For example, consider the following fragment of notation.
-
-@lilypond
-\score { \notes {
- g'4-\f g4
- }
-\paper { raggedright = ##t }
- }
+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 than with studying
+the looks of piece of music; nitpicking about typographical details
+may seem academical. 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, 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.
+@c he/she
+
+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, 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 his 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 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.
+
+
+
+
+@node Automated engraving
+@section Automated engraving
+
+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 ultimately. 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
+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 @bullet
+@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 do not match well with how music
+notation works.
+@end itemize
+
+These problems have been addressed by integrating the GUILE
+interpreter for the Scheme programming language and rewriting parts of
+LilyPond in Scheme. The new, flexible formatting 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 arpeggio. In the first chord, the graphical objects
+have all directions down (or left). The second chord has all
+directions up (right).
+
+@lilypond[quote,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 the
+variables of graphical objects.
+
+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[quote,raggedright]
+fragment = \notes {
+ \clef bass f8 as8
+ c'4-~ c'16 as g f e16 g bes c' des'4
+}
+\score {
+ <<
+ \new Staff \fragment
+ \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)
+ } \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 behavior. In the
+following example, the rule which note head objects use to produce
+their symbol is changed during the music fragment.
+
+@lilypond[quote,raggedright]
+#(define (mc-squared grob orig current)
+ (let ((interfaces (ly:grob-property grob 'interfaces))
+ (pos (ly:grob-property grob 'staff-position)))
+ (if (and (memq 'note-head-interface interfaces)
+ (memq pos '(-2 -3 -5)))
+ (begin
+ (ly:grob-set-property! grob 'print-function brew-new-markup-stencil)
+ (ly:grob-set-property! grob 'font-family 'roman)
+ (ly:grob-set-property!
+ grob 'text
+ (make-raise-markup
+ -0.5
+ (case pos
+ ((-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
+
+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
+who 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[quote,raggedright]
+\include "engraver-example.lyinc"
+
+\score {
+ \topVoice
+ \paper {
+ \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"
+ }
+ }
+}