From 0f823f818e9a3d4bf7d999bfdf8c8ac335aeeea3 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Sat, 1 Aug 2009 16:06:07 -0700 Subject: [PATCH] Doc: move LM essay to essay. --- Documentation/essay/engraving.itely | 791 ++++++++++++++++++++- Documentation/learning/introduction.itely | 793 ---------------------- 2 files changed, 789 insertions(+), 795 deletions(-) diff --git a/Documentation/essay/engraving.itely b/Documentation/essay/engraving.itely index 0b22182290..f169326f44 100644 --- a/Documentation/essay/engraving.itely +++ b/Documentation/essay/engraving.itely @@ -12,7 +12,794 @@ @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, 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 this one, among others. 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, however, form +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 +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 + +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 4_>-\arpeggio + \override Arpeggio #'direction = #RIGHT + \stemUp 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 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 + 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 + 4 + \once \override NoteHead #'style = #'cross + 4 + \applyOutput #'Voice #mc-squared + 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 +<> +@end example + +@lilypond[quote,fragment,relative=1] +\new Voice { <> } +@end lilypond + +@noindent +This expression is put in sequence by enclosing it in curly braces +@code{@{@tie{}@dots{}@tie{}@}}: + +@example +@{ f4 <> @} +@end example + +@lilypond[quote,relative=1,fragment] +{ f4 <> } +@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 <> @} >> +@end example + +@lilypond[quote,fragment,relative=2] +\new Voice { << g2 \\ { 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 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 #'thickness = #0.3 + \override Stem #'thickness = #4.0 + g'16[ b16 fis16 g16] + << \makeClusters { + as16 + + + } \\ { + \override Staff.Arpeggio #'arpeggio-direction =#down + 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? diff --git a/Documentation/learning/introduction.itely b/Documentation/learning/introduction.itely index 5ced19393a..a37dc2597b 100644 --- a/Documentation/learning/introduction.itely +++ b/Documentation/learning/introduction.itely @@ -16,803 +16,10 @@ This chapter introduces readers to LilyPond and the 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, 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, 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 this one, among others. 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, however, form -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 -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 -@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 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 4_>-\arpeggio - \override Arpeggio #'direction = #RIGHT - \stemUp 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 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 - 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 - 4 - \once \override NoteHead #'style = #'cross - 4 - \applyOutput #'Voice #mc-squared - 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, 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 -@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 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 -<> -@end example - -@lilypond[quote,fragment,relative=1] -\new Voice { <> } -@end lilypond - -@noindent -This expression is put in sequence by enclosing it in curly braces -@code{@{@tie{}@dots{}@tie{}@}}: - -@example -@{ f4 <> @} -@end example - -@lilypond[quote,relative=1,fragment] -{ f4 <> } -@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 <> @} >> -@end example - -@lilypond[quote,fragment,relative=2] -\new Voice { << g2 \\ { 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 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 -@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 - - - } \\ { - \override Staff.Arpeggio #'arpeggio-direction =#down - 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 -- 2.39.2