documentation.
@menu
+* Background::
* About the documentation::
@end menu
+@node Background
+@section Background
+
+This section covers the overall goals and architecture of
+LilyPond.
+
+@menu
+* Engraving::
+* Automated engraving::
+* What symbols to engrave?::
+* Music representation::
+* Example applications::
+@end menu
+
+
+@node Engraving
+@unnumberedsubsec 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, 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 a correction was cumbersome, if possible at all,
+so the engraving had to be 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.
+
+Nowadays, all newly printed music is produced with computers.
+This has obvious advantages; prints are cheaper to make, and
+editorial work can be delivered by email. 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.
+
+
+@c introduce illustrating aspects of engraving, font...
+The images below illustrate the difference between traditional
+engraving and typical computer output, and the third picture shows
+how LilyPond mimics the traditional look. The left picture shows
+a scan of a flat symbol from an edition published in 2000. The
+center depicts a symbol from a hand-engraved Bärenreiter edition
+of the same music. The left scan illustrates typical flaws of
+computer print: the staff lines are thin, the weight of the flat
+symbol matches the light lines and it has a straight layout with
+sharp corners. By contrast, the Bärenreiter flat has a bold,
+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 lines in the computer edition.
+
+@multitable @columnfractions .125 .25 .25 .25 .125
+@item @tab
+@ifnotinfo
+@iftex
+@image{henle-flat-gray,,4cm}
+@end iftex
+@ifnottex
+@image{henle-flat-gray,,,png}
+@end ifnottex
+
+@tab
+@iftex
+@image{baer-flat-gray,,4cm}
+@end iftex
+@ifnottex
+@image{baer-flat-gray,,,png}
+@end ifnottex
+
+@tab
+@iftex
+@image{lily-flat-bw,,4cm}
+@end iftex
+@ifnottex
+@image{lily-flat-bw,,,png}
+@end ifnottex
+@end ifnotinfo
+@ifinfo
+@image{lilypond/henle-flat-bw,,,,png} @image{lilypond/baer-flat-bw,,,,png}
+@image{lilypond/lily-flat-bw,,,,png}
+@end ifinfo
+
+@item @tab
+Henle (2000)
+@tab
+Bärenreiter (1950)
+@tab
+LilyPond Feta font (2003)
+
+@end multitable
+
+
+@cindex musical symbols
+@cindex font
+@cindex blackness
+@cindex balance
+
+@c introduce illustrating aspects of engraving, 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: once
+using exact mathematical spacing, and once with corrections. Can
+you spot which fragment is which?
+
+@cindex optical spacing
+@c file spacing-optical.
+@c need to include it here, because we want two images.
+@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
+
+@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
+
+@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 without, forming
+down-stem/@/up-stem clumps of notes.
+
+
+Musicians are usually more absorbed with performing than with
+studying the looks of a piece of music, so 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, and they become like a labyrinth. If a musician
+looks away once or has a lapse in concentration, the lines might
+lose their place on the page.
+
+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 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 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
+@unnumberedsubsec Automated engraving
+
+@cindex engraving, automated
+@cindex 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 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 do not match well with how
+music notation works.
+
+@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 #'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 which note head objects are used to produce their 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 = #ly: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?
+@unnumberedsubsec 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, it encompasses some 500 years of music. Its applications
+range from monophonic melodies to monstrous counterpoints 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? 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 see how 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
+@unnumberedsubsec 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 C1 (middle C) and an eighth note D1 (D
+above middle C).
+
+@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 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
+@unnumberedsubsec 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 #'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.
+
+
@node About the documentation
@section About the documentation
projects / lilypond.git / blobdiff