-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-learning.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.11.38"
@node Introduction
@chapter Introduction
-There are a lot of programs that let you print sheet music with a
-computer, but most of them do not do good job. Most computer
-printouts have a bland, mechanical look, and are unpleasant to play
-from. If you agree with us on that, then you will like LilyPond: we
-have tried to capture the original look of hand-engraved music. We
-have tuned our algorithms, font-designs, and program settings to make
-the program produce prints that match the quality of the old editions
-we love to see and love to play from.
-
@menu
-* Notation in LilyPond ::
-* Engraving in LilyPond::
-* Typography and program architecture::
+* Engraving::
+* Automated engraving::
+* What symbols to engrave?::
* Music representation::
* Example applications::
* About this manual::
@end menu
-@node Notation in LilyPond
-@section Notation in LilyPond
+@node Engraving
+@section 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
-@cindex engraving
-@cindex typography
+@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
-Printing sheet music consists of two non-trivial tasks. First, one has
-to master music notation: the science of knowing which symbols to use
-for what. Second, one has to master music engraving: the art of
-placing symbols such that the result looks pleasing.
-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 (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
-monstruous counterpoint for large orchestras.
+@cindex musical symbols
+@cindex font
+@cindex blackness
+@cindex balance
-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 make a strict
-distinction between notation, @emph{what} symbols to use, and
-engraving, @emph{where} to put them. Anything related to the second
-question is considered ``engraving'' (i.e. typography).
-
-For tackling the first problem, notation, we have broken up the
-problem into digestible (and programmable) chunks: every type of
-symbol is handled by a separate program module, a so-called plug-in.
-Each plug-in are completely modular and independent, so each can be
-developed and improved separately. When put together, the plug-ins
-can solve the music notation program in cooperation. People that put
-graphics to musical ideas are called copyists or engravers, so by
-analogy, each plug-in is also called @code{engraver}.
-
-In the following example, we see how we start out with a note head
-engraver.
-
-@lilypond[notexidoc]
-\include "engraver-example.lyinc"
-
-\score { \topVoice
+@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 {
- \translator { \VoiceContext
- \remove "Stem_engraver"
- \remove "Phrasing_slur_engraver"
- \remove "Slur_engraver"
- \remove "Script_engraver"
- \remove "Beam_engraver"
- \remove "Auto_beam_engraver"
-
- }
- \translator { \StaffContext
- \remove "Accidental_engraver"
- \remove "Key_engraver"
- \remove "Clef_engraver"
- \remove "Bar_engraver"
- \remove "Time_signature_engraver"
- \remove "Staff_symbol_engraver"
- \consists "Pitch_squash_engraver"
- }
-
-}
+ ragged-right = ##t
+ indent = #0.0
}
-@end lilypond
-Then a @code{Staff_symbol_engraver} adds the staff:
+music = {
+ c'4 e''4 e'4 b'4 |
+ \stemDown
+ b'8[ e'' a' e'']
+ \stemNeutral
+ e'8[ e'8 e'8 e'8]
+}
-@lilypond[notexidoc]
-\include "engraver-example.lyinc"
+\score
+{
+ \music
+ \layout {
+ \context {
+ \Staff
+ \override NoteSpacing #'stem-spacing-correction = #0.6
+ }
+ }
+}
+@end lilypond
-\score { \topVoice
+@lilypond
\paper {
- \translator { \VoiceContext
- \remove "Stem_engraver"
- \remove "Phrasing_slur_engraver"
- \remove "Slur_engraver"
- \remove "Script_engraver"
- \remove "Beam_engraver"
- \remove "Auto_beam_engraver"
-
- }
- \translator { \StaffContext
- \remove "Accidental_engraver"
- \remove "Key_engraver"
- \remove "Clef_engraver"
- \remove "Bar_engraver"
- \consists "Pitch_squash_engraver"
- \remove "Time_signature_engraver"
- }
-
-}
+ 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
- The @code{Clef_engraver} defines a reference point for the staff:
+@cindex regular rhythms
+@cindex regular spacing
-@lilypond[notexidoc]
-\include "engraver-example.lyinc"
+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.
-\score { \topVoice
-\paper {
- \translator { \VoiceContext
- \remove "Stem_engraver"
- \remove "Phrasing_slur_engraver"
- \remove "Slur_engraver"
- \remove "Script_engraver"
- \remove "Beam_engraver"
- \remove "Auto_beam_engraver"
- }
- \translator { \StaffContext
- \remove "Accidental_engraver"
- \remove "Key_engraver"
- \remove "Bar_engraver"
- \remove "Time_signature_engraver"
- }
-
-}
+@cindex typography
+
+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
+@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 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
+
+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 {
+ \stemDown <e g b>4_>-\arpeggio
+ \override Arpeggio #'direction = #RIGHT
+ \stemUp <e g b>4^>-\arpeggio
}
@end lilypond
-And the @code{Stem_engraver} adds stems:
-
-@lilypond[notexidoc]
-\include "engraver-example.lyinc"
+@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
-\score { \topVoice
-\paper {
- \translator { \VoiceContext
- \remove "Phrasing_slur_engraver"
- \remove "Slur_engraver"
- \remove "Script_engraver"
- \remove "Beam_engraver"
- \remove "Auto_beam_engraver"
- }
- \translator { \StaffContext
- \remove "Accidental_engraver"
- \remove "Key_engraver"
- \remove "Bar_engraver"
- \remove "Time_signature_engraver"
- }
-}
+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 ly:text-interface::print)
+ (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")))))))))
+
+\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>
+ \once \override NoteHead #'style = #'cross
+ <d f g>
+ \applyOutput #'Voice #mc-squared
+ <d f g>
+ <<
+ { d8[ es-( fis^^ g] fis2-) }
+ \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
+ >>
}
@end lilypond
-The @code{Stem_engraver} is notified of any note head coming along.
-Every time one (or more, for a chord) note heads is seen, a stem
-object is created, and attached 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[notexidoc]
-\include "engraver-example.lyinc"
+@node What symbols to engrave?
+@section What symbols to engrave?
-\score { \topVoice }
-@end lilypond
+@cindex engraving
+@cindex typography
+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.
-This system works well for monophonic music, but what about
-polyphony? In polyphonic notation, many voices can share a staff.
+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.
-@lilypond[notexidoc]
-\include "engraver-example.lyinc"
-\score { \context Staff << \topVoice \\ \botVoice >> }
-@end lilypond
+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"
-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 head, stems, slurs, etc. go
-into a group called ``Voice context,'' while the engravers for key,
-accidental, bar, etc. go into a group called ``Staff context.'' In the
-case of polyphony, a single Staff context contains more than one Voice
-context. In polyphonic notation, many voices can share a staff:
-Similarly, more Staff contexts can be put into a single Score context.
-
-@lilypond[notexidoc]
-\include "engraver-example.lyinc"
\score {
-<< \new Staff << \topVoice \\ \botVoice >>
-\new Staff << \pah \\ \hoom >>
- >>
+ \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"
-@node Engraving in LilyPond
-@section Engraving in LilyPond
-
-
-The term music engraving derives from the traditional process of music
-printing. Only a few decades ago, sheet music was made by cutting and
-stamping the music into zinc or pewter plates, in mirror image. The plate
-would be inked, and the depressions caused by the cutting and stamping
-would hold ink. An image was formed by pressing paper to the
-plate. The stamping and cutting was completely done by hand. Making
-corrections was cumbersome, so engraving had to be done correctly in
-one go. Of course, this was a highly specialized skill, much more so
-than the traditional process of printing books.
-@cindex craftsmanship
-@cindex master
-In the traditional German system of craftsmanship six years of full-time
-training, more than any other craft, were required before a student
-could call himself a master of the art. After that many more years of
-practical experience were needed to become an established music
-engraver. Even today, with the use of high-speed computers and
-advanced software, music requires lots of manual fine tuning before it
-is acceptable for publication.
-
-
-Sheet music is performance material: everything is done to aid the
-musician in letting him perform better. Music often is far away from
-its reader---it might be on a music stand. To make it clearly
-readable, traditionally printed sheet music always uses bold symbols,
-on heavy staff lines, and is printed on large sheets of paper. This
-``strong'' look is also present in the horizontal spacing. To
-minimize the number of page breaks, (hand-engraved) sheet music is
-spaced very tightly. Yet, by a careful distribution of white space,
-the feeling of balance is retained, and a clutter of symbols is
-avoided.
-
-
-We have used these observations in designing LilyPond. The images
-below show the flat symbol. On the left, a scan from a Henle edition,
-which was made by a computer, and in the center is the flat from a
-hand engraved B@"{a}renreiter edition of the same music. The left scan
-illustrates typical flaws of computer print: the symbol is much
-lighter, the staff lines are thinner, and the glyph has a straight
-layout with sharp corners. By contrast, the B@"{a}renreiter has a bold
-and almost voluptuous rounded look. Our flat symbol is designed
-after, among others, this one. It is tuned it to harmonize with the
-thickness of our staff lines, which are also much thicker than Henle's
-lines.
-
-@multitable @columnfractions .1 .3 .3 .3
-@item @tab
-@iftex
-@image{henle-flat-bw,4cm}
-@end iftex
-@html
-<img src=henle-flat-bw.png>
-@end html
-
-@tab
-@iftex
-@image{baer-flat-bw,4cm}
-@end iftex
-@html
-<img src=baer-flat-bw.png>
-@end html
-
-@tab
-@iftex
-@image{lily-flat-bw,4cm}
-@end iftex
-@html
-<img src=lily-flat-bw.png>
-@end html
+\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
-@item @tab
-Henle (2000)
-@tab
-B@"{a}renreiter (1950)
-@tab
-LilyPond Feta font (2003)
+@noindent
+the @code{Clef_engraver} defines a reference point for the staff
-@end multitable
+@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
-@cindex musical symbols
-@cindex font
-@cindex blackness
-@cindex balance
+@noindent
+and the @code{Stem_engraver} adds stems.
-In spacing, the distribution of space should reflect the durations
-between notes. However, adhering with mathematical precision to the
-duration will lead to a poor result. Shown here is an example of a
-motive, printed twice. It is printed using exact mathematical spacing,
-and with some corrections. Can you spot which fragment is which?
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
-@cindex optical spacing
-@lilypond[noindent]
- \score { \notes {
- \property Staff.NoteSpacing \set #'stem-spacing-correction
- = #0.6
- c'4 e''4 e'4 b'4 |
- \stemDown b'4 e''4 a'4 e''4| \stemBoth
- \bar "||"
- \property Staff.NoteSpacing \override #'stem-spacing-correction
- = #0.0
- \property Staff.StaffSpacing \override #'stem-spacing-correction
- = #0.0
- c'4 e''4 e'4 b'4 |
- \stemDown b'4 e''4 a'4 e''4|
+\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"
}
- \paper { raggedright = ##t } }
+ }
+}
@end lilypond
-@cindex regular rhythms
-@cindex regular spacing
+@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.
-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-stems clumps of notes.
-
-@node Typography and program architecture
-@section Typography and program architecture
-
-Producing good engraving requires skill and knowledge. 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. Master engravers must learn all these details from
-experience or from other engravers, which is why it takes so long to
-become a master. 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 typographical knowledge into a computer program.
-It is not possible to come up with a definitive 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 90 or 95 % of the cases are
-handled.
-
-This has an important implication for the design of the program: at
-any time, almost every piece of formatting code must be considered as
-temporary. When the need arises, it is to be replaced a solution that
-will cover even more cases. A ``plug-in'' architecture is a clean
-way to accomplish this. This is 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. For
-testing, it is plugged in, but for production use, the old solution is
-used. The new module can be perfected separately until it is better
-than the existing solution, at which point it replaces the old one.
-
-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. To accomplish this we store decisions in generic
-variables, and let the user manipulate thosed. For example, consider
-the following fragment of notation:
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+\score { \topVoice }
+@end lilypond
-@lilypond
-\score { \notes \relative c'' {
-\stemUp
- a4_\f f,8
- }
-\paper { raggedright = ##t }
- }
+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
-@noindent
-The position of the forte symbol is slightly awkward, because it is
-next to the low note, whereas dynamics should be below notes in
-general. This may be remedied by inserting extra space between the
-high note and the `f', as shown in this example:
+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.
-@lilypond
-\score { \notes \relative c'' {
-\stemUp
- \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
- a4_\f f,8
- }
-\paper { raggedright = ##t }
- }
+@seealso
+
+Internals Reference: @internalsref{Contexts}.
+
+@lilypond[quote,ragged-right]
+\include "engraver-example.ily"
+\score {
+ <<
+ \new Staff << \topVoice \\ \botVoice >>
+ \new Staff << \pah \\ \hoom >>
+ >>
+}
@end lilypond
-This was achieved with the following input statement:
+@node Music representation
+@section Music representation
+
+Ideally, the input format for any high-level formatting system is an
+abstract description of the content. In this case, that would be the
+music itself. This poses a formidable problem: how can we define what
+music really is? Instead of trying to find an answer, we have reversed
+the question. We write a program capable of producing sheet music,
+and adjust the format to be as lean as possible. When the format can
+no longer be trimmed down, by definition we are left with content
+itself. Our program serves as a formal definition of a music
+document.
+
+The syntax is also the user-interface for LilyPond, hence it is easy
+to type
+
@example
- \once \property Voice. DynamicLineSpanner \override #'padding = #4.0
+@{
+ c'4 d'8
+@}
@end example
-It increases the amount of space (@code{padding}) between the note and
-the dynamic symbol to 4.0 (which is measured in staff space, so 4.0
-equals the height of a staff). The keyword @code{\once} indicates that
-this is a tweak: it is only done one time.
-
-Both design aspects, a plug-in architecture, and formatting variables,
-are built on top of GUILE, an interpreter for the programming language
-Scheme, which is a member of the LISP family. Variables are stored as
-Scheme objects, and attached to graphical objects such as note heads
-and stems. The variables are a means to adjust formatting details in
-individual cases, but they are used in a more general manner.
-
-Consider the case of a publisher that is not satisfied with the in the
-default layout, and wants heavier stems. Normally, they are @code{1.3}
-times the thickness of staff lines, but suppose that their editions
-require them to be twice the thickness of the staff lines. The same
-mechanism can be used to adjust a setting globally. By issuing the
-following command, the entire piece is now formatted with thicker stems:
+
+@noindent
+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]
+c4
+@end lilypond
+
+@noindent
+Chords can be constructed with @code{<<} and @code{>>} enclosing the notes
+
+@c < > is not a music expression,
+@c so we use <<>> iso. <> to drive home the point of
+@c expressions. Don't change this back --hwn.
@example
- \property Score.Stem \override #'thickness = #3.0
+<<c4 d4 e4>>
@end example
-@lilypond
-\score { \notes \relative c'' {
- \property Score.Stem \override #'thickness = #3.0
- \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
-\stemUp
- a4_\f f,8
- }
-\paper { raggedright = ##t }
- }
+@lilypond[quote,fragment,relative=1]
+\new Voice { <<c4 d4 e>> }
@end lilypond
@noindent
-In effect, by setting these variables, users can define their own
-layout styles.
-
-``Plug-ins'' are also implemented using Scheme. A formatting
-``plug-in'' takes the form of a function written in Scheme (or a C++
-function made available as a Scheme function), and it is also stored
-in a variable. For example, the placement of the forte symbol in the
-example above is calculated by the function
-@code{Side_position_interface::aligned_side}. If we want to replace
-this function by a more advanced one, we could issue
+This expression is put in sequence by enclosing it in curly braces
+@code{@{@tie{}@dots{}@tie{}@}}
+
@example
- \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
- = #(list gee-whiz-gadget)
+@{ f4 <<c4 d4 e4>> @}
@end example
+@lilypond[quote,relative=1,fragment]
+{ f4 <<c d e4>> }
+@end lilypond
+
@noindent
-Now, the formatting process will trigger a call to our new
-@code{gee-whiz-gadget} function when the position of the f symbol has
-to be determined.
+The above is also an expression, and so it may be combined
+again with another simultaneous expression (a half note) using <<,
+@code{\\}, and >>
-The full scope of this functionality certainly is intimidating, but
-there is no need to fear: normally, it is not necessary to define
-style-sheets or rewrite formatting functions. In fact, LilyPond gets a
-lot of formatting right automatically, so adjusting individual layout
-situations is not needed often at all.
+@example
+<< g2 \\ @{ f4 <<c4 d4 e4>> @} >>
+@end example
+@lilypond[quote,fragment,relative=2]
+\new Voice { << g2 \\ { f4 <<c d e>> } >> }
+@end lilypond
-@node Music representation
-@section Music representation
+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.
-Our premise is that LilyPond is a system that does music formatting
-completely automatically. Under this assumption, the output does not
-have to be touched up. Consequently, an interactive display of the
-output, where it is possible to reposition notation elements, is
-superfluous. This implies that the program should be a batch program:
-the input is entered in a file, which then is @emph{compiled}, i.e.
-put through the program. The final output is produced as a file ready
-to view or print. The compiler fills in all the details of the
-notation, those details should be left out of the input file. In other
-words, the input should mirror the content as closely as possible. In
-the case of music notation the content is the music itself, so that is
-what the input should consist of.
-
-On paper this theory sounds very good. In practice, it opens a can of
-worms. What really @emph{is} music? Many philosophical treatises must
-have been written on the subject. Instead of losing ourselves in
-philosophical arguments over the essence of music, we have reversed
-the question to yield a more practical approach. Our assumption is
-that the printed score contains all of the music of piece. We build a
-program that uses some input format to produce such a score. Over the
-course of time, the program evolves. While this happens, we can remove
-more and more elements of the input format: as the program improves,
-it can fill in irrelevant details of the input by itself. At some
-(hypothetical) point, the program is finished: there is no possibility
-to remove any more elements from the syntax. What we have left is by
-definition exactly the musical meaning of the score.
-
-There are also more practical concerns. Our users have to key in the
-music into the file directly, so the input format should have a
-friendly syntax: a quarter note C is entered as @code{c4}, the code
-@code{r8.} signifies a dotted eighth rest.
-
-Notes and rests form the simplest musical expressions in the input
-syntax. More complex constructs are produced by combining them into
-compound structures. This is done in much the same way that complex
-mathematical formulas are built from simple expressions such as
-numbers and operators.
-
-In effect, the input format is a language, and the rules of that
-language can be specified succinctly with a so-called context-free
-grammar. The grammar formally specificies what types of input form
-valid `sentences'. Reading such languages, and splitting them into
-grammatical structures is a problem with standard solutions.
-Moreover, rigid definitions make the format easier to understand: a
-concise formal definition permits a simple informal description.
-
-The user-interface of LilyPond is its syntax. That part is what users
-see most. As a results, some users think that music representation is
-a very important or interesting problem. In reality, less than 10% of
-the source code of the program handles reading and representing the
-input, and they form the easy bits of the program. In our opinion,
-producing music notation, and formatting it prettily are much more
-interesting and important than music representation: solving
-these problems takes up most of the bulk of the code, and they are the
-most difficult things to get right.
@node Example applications
@section Example applications
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
+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:
+simplest application is printing notes.
-@lilypond[relative=1]
- \time 2/4 c4 c g'4 g a4 a g2
+@lilypond[quote,relative=1]
+{
+ \time 2/4
+ c4 c g'4 g a4 a g2
+}
@end lilypond
-By adding chord names and lyrics we obtain a lead sheet:
-
-@lilypond[raggedright]
-\score { <<
- \context ChordNames \chords { c2 c f2 c }
- \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
- \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } >> }
+@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'4 g a4 a g2 }
+ \new Lyrics \lyricmode { twin4 kle twin kle lit tle star2 }
+>>
@end lilypond
-Polyphonic notation and piano music can also be printed. The following
-example combines some more exotic constructs:
+Polyphonic notation and piano music can also be printed. The following
+example combines some more exotic constructs.
-@lilypondfile{screech-boink.ly}
+@lilypondfile[quote,ragged-right]{screech-boink.ly}
The fragments shown above have all been written by hand, but that is
-not a requirement. Since the formatting engine is mostly automatic, it
+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
+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 plain text,
-and can therefore be easily embedded in other text-based formats, such
-as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
-special program, the input fragments can be replaced by music images in
-the resulting PostScript or HTML output files. This makes it easy to
-mix music and text in documents.
+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 this manual
@section About this manual
-The manual is divided into the following chapters:
-@itemize @bullet
-@item
-@ifhtml The
-@end ifhtml
-@emph{@ref{Tutorial}}
-gives a gentle introduction to typesetting music.
-First time users should start here.
+FIXME: needs almost-complete rewrite. -gp
+
+There are four manuals about LilyPond: the @emph{Learning Manual},
+the @emph{Notation Reference}, the @emph{Application Usage}, and the
+@emph{Internals Reference}.
+
+
+@subheading Learning Manual (LM)
+
+This book explains how to begin learning LilyPond, as well as explaining
+some key concepts in easy terms. It is recommended to read these
+chapters in a linear fashion.
+
+@itemize
+
@item
@ifhtml
The
@end ifhtml
-@emph{@ref{Notation manual}}
-discusses topics grouped by notation construct. Once you master the
-basics, this is the place to look up details.
+@emph{@ref{Tutorial}},
+gives a gentle introduction to typesetting music. First time
+users should start here.
+
@item
-@ifhtml
-The
-@end ifhtml
-@emph{@ref{Literature list}}
- contains a set of useful reference books, for those who wish to know
- more on notation and engraving.
+@emph{@ref{Fundamental concepts}},
+explains some general concepts about the LilyPond file format. If
+you are not certain where to place a command, read this chapter!
+
@item
-@ifhtml
- The
- @end ifhtml
-@emph{@ref{Technical manual}}
-@c
-discusses the general design of the program, and how to extend its
-functionality.
+@emph{@ref{Working on LilyPond projects}},
+discusses practical uses of LilyPond and how to avoid some common
+problems.
+
@item
-@ifhtml
-The chapter
-@end ifhtml
-@emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
-programs.
+@emph{@ref{Tweaking output}},
+shows how to change the default engraving that LilyPond
+produces.
+
+@end itemize
+
+
+@subheading Notation Reference (NR)
+
+This book explains all the LilyPond commands which produce notation. It
+assumes that readers are familiar with the concepts in the Learning
+manual.
+
+All of this needs to be rewritten after GDP, anyway.
+
+@ignore
+
+@itemize
@item
-@ifhtml
-The
-@end ifhtml
-@emph{@ref{lilypond-book manual}}
-explains the details behind creating documents with in-line music
-examples (like this manual).
+@emph{@r ef{Basic notation}},
+discusses topics grouped by notation construct. This section gives
+details about basic notation that will be useful in almost any
+notation project.
+@item
+@emph{@r ef{Instrument-specific notation}},
+discusses topics grouped by notation construct. This section gives
+details about special notation that will only be useful for particular
+instrument (or vocal) groups.
@item
-@ifhtml
-The chapter
-@end ifhtml
-@emph{@ref{Converting from other formats}}
-explains how to run the conversion programs. These programs
-are supplied with the LilyPond package, and convert a variety of music
-formats to the @code{.ly} format. In addition, this section explains
-how to upgrade input files from previous versions of LilyPond.
+@emph{@r ef{Advanced notation}},
+discusses topics grouped by notation construct. This section gives
+details about complicated or unusual notation.
+
+@item
+@emph{@r ef{Changing defaults}},
+explains how to fine tune layout.
+
+@item
+@emph{@r ef{Non-musical notation}},
+discusses non-musical output such as titles, multiple movements,
+and how to select which MIDI instruments to use.
+
+@item
+@emph{@r ef{Spacing issues}},
+discusses issues which affect the global output, such as selecting
+paper size or specifying page breaks.
+
+@item
+@emph{@r ef{Interfaces for programmers}},
+explains how to create music functions.
@end itemize
-Once you are an experienced user, you can use the manual as reference:
-there is an extensive index@footnote{If you are looking for something,
-and you cannot find it in the manual, that is considered a bug. In
-that case, please file a bug report.}, but the document is also
-available in
-@ifnothtml
-a big HTML page,
-@end ifnothtml
-@ifhtml
-@uref{../lilypond.html, a big HTML page}
-@end ifhtml
-which can be searched easily using the search facility of a web
-browser.
-@cindex search in manual
-@cindex using the manual
+@subsubheading Appendices
-If you are not familiar with music notation or music terminology
-(especially if you are a non-native English speaker), then it is
-advisable to consult the glossary as well. The glossary explains
-musical terms, and includes translations to various languages. It is a
+This book contains useful reference charts.
+
+@itemize
+@item
@ifhtml
-@uref{../music-glossary.html,separate document}.
+The
@end ifhtml
-@ifnothtml
-separate document, available in HTML and PDF.
-@end ifnothtml
-@cindex idiom
-@cindex jargon
-@cindex terminology
-@cindex foreign languages
-@cindex language
+@emph{@r ef{Literature list}},
+contains a set of useful reference books for those who wish to know
+more on notation and engraving.
+@item
+The
+@emph{@r ef{Scheme tutorial}},
+presents a short introduction to Scheme, the programming
+language that music functions use.
-This manual is not complete without a number of other documents. They
-are not available in print, but should be included with the
-documentation package for your platform:
+@item
+@emph{@r ef{Notation manual tables}},
+are a set of tables showing the chord names, MIDI instruments,
+a list of color names, and the Feta font.
-@itemize @bullet
@item
-Program reference
-@ifhtml
-(available @uref{../lilypond-internals/lilypond-internals.html,here})
-@end ifhtml
+@emph{@r ef{Templates}},
+of LilyPond pieces. Just cut and paste a
+template into a file, add notes, and you're done!
-The program reference is a set of heavily crosslinked HTML pages,
-which documents the nit-gritty details of each and every LilyPond
-class, object and function. It is produced directly from the
-formatting definitions used.
+@item
+The
+@emph{@r ef{Cheat sheet}},
+is a handy reference of the most common LilyPond commands.
-Almost all formatting functionality that is used internally, is
-available directly to the user. For example, all variables that
-control thicknesses, distances, etc, can be changed in input
-files. There are a huge number of formatting options, and all of them
-are described in the generated documentation. Each section of the
-notation manual has a @b{See also} subsection, which refers to the
-the generated documentation. In the HTML document, these subsections
-have clickable links.
+@item
+The
+@emph{@r ef{LilyPond command index}},
+is an index of all LilyPond @code{\commands}.
@item
- Templates
-@ifhtml
-(available @uref{../../../input/template/out-www/collated-files.html,here})
-@end ifhtml
+The
+@emph{@r ef{LilyPond index}},
+is a complete index.
+
+@end itemize
+
+@end ignore
+
+
+@subheading Program usage
-After you have gone through the tutorial, you should be able to write
-input files. In practice, writing files from scratch turns out to be
-intimidating. To give you a headstart, we have collected a number of
-often-used formats in example files. These files can be used as a
-start: simply copy the template, and add notes in the appropriate
-places.
+This book explains how to execute the program and how to integrate
+LilyPond notation with other programs.
+
+@itemize
@item
- Various input examples
-@ifhtml
-(available @uref{../../../../input/test/out-www/collated-files.html,here})
-@end ifhtml
-@cindex snippets
+@emph{@rprogram{Install}},
+explains how to install LilyPond (including compilation if desired).
+
+@item
+@emph{@rprogram{Setup}},
+describes how to configure your computer for optimum LilyPond usage,
+such as using special environments for certain text editors.
+
+@item
+@emph{@rprogram{Running LilyPond}},
+shows how to run LilyPond and its helper programs. In addition, this
+section explains how to upgrade input files from previous versions of
+LilyPond.
+
+@item
+@emph{@rprogram{lilypond-book}},
+explains the details behind creating
+documents with in-line music examples, like this manual.
+
+@item
+@emph{@rprogram{Converting from other formats}},
+explains how to run the conversion programs. These programs are
+supplied with the LilyPond package, and convert a variety of music
+formats to the @code{.ly} format.
+
+@end itemize
+
+
+
+@subsubheading Other information
-These small files show various tips and tricks, and are available as a
-big HTML document, with pictures and explanatory texts included.
+There are a number of other places which may be very valuable.
+@itemize
+@cindex idiom
+@cindex jargon
+@cindex terminology
+@cindex foreign languages
+@cindex language
+@item
+@ifnottex
+The @ref{Top,Music glossary,,music-glossary}, explains musical terms and
+includes translations to various languages. It is also available in
+PDF.
+@end ifnottex
+@iftex
+The music glossary explains musical terms, and includes translations
+to various languages. It is a separate document, available in HTML
+and PDF.
+@end iftex
+If you are not familiar with music notation or music terminology
+(especially if you are a non-native English speaker), it is highly
+advisable to consult the glossary.
+@cindex snippets
+@cindex LSR
@item
- The regression tests
+The
@ifhtml
-(available @uref{../../../input/regression/out-www/collated-files.html,here})
+@uref{source/input/lsr/lilypond-snippets/index.html,Snippets}
@end ifhtml
+@ifnothtml
+Snippets
+@end ifnothtml
+are a great collection of short examples which demonstrate tricks, tips,
+and special features of LilyPond. Most of these snippets can also be
+found in the @uref{http://lsr.dsi.unimi.it/,LilyPond Snippet
+Repository}. This website also has a searchable LilyPond manual.
+
-This collection of files tests each notation and engraving feature of
-LilyPond in one file. The collection is primarily there to help us
-debug problems, but it can be instructive to see how we excercise the
-program. The format is like the tips and tricks document.
+@item
+The
+@iftex
+Internals Reference
+@end iftex
+@ifnottex
+@ref{Top,Internals Reference,,lilypond-internals}
+@end ifnottex
+is a set of heavily cross linked HTML pages, which document the
+nitty-gritty details of each and every LilyPond class, object, and
+function. It is produced directly from the formatting definitions used.
+
+Almost all formatting functionality that is used internally, is
+available directly to the user. For example, all variables that control
+thickness values, distances, etc., can be changed in input files. There
+are a huge number of formatting options, and all of them are described
+in this document. Each section of the notation manual has a @b{See
+also} subsection, which refers to the generated documentation. In the
+HTML document, these subsections have clickable links.
@end itemize
+Once you are an experienced user, you can use the manual as reference:
+there is an extensive index@footnote{If you are looking for something,
+and you cannot find it in the manual, that is considered a bug. In
+that case, please file a bug report.}, but the document is also
+available in
+@iftex
+a big HTML page,
+@end iftex
+@ifhtml
+@uref{source/Documentation/user/lilypond-big-page.html, one big page},
+@end ifhtml
+which can be searched easily using the search facility of a web
+browser.
+
+
In all HTML documents that have music fragments embedded, the LilyPond
input that was used to produce that image can be viewed by clicking
the image.
-The location of the documentation files that are mentioned here can
-vary from system to system. On occasion, this manual refers to
+The location of the documentation files that are mentioned here can vary
+from system to system. On occasion, this manual refers to
initialization and example files. Throughout this manual, we refer to
-input files relative to the top-directory of the source archive. For
-example, @file{input/test/bla.ly} may refer to the file
-@file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
-Unix platform, the documentation and examples can typically be found
-somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
-for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
-usually found in the directory @file{/usr/share/lilypond/}.
+input files relative to the top-directory of the source archive. For
+example, @file{input/@/lsr/@/dirname/@/bla@/.ly} may refer to the file
+@file{lilypond@/2.x.y/@/input/@/lsr/@/dirname/@/bla@/.ly}. On binary
+packages for the UNIX platform, the documentation and examples can
+typically be found somewhere below
+@file{/usr/@/share/@/doc/@/lilypond/}. Initialization files, for
+example @file{scm/@/lily@/.scm}, or @file{ly/@/engraver@/-init@/.ly},
+are usually found in the directory @file{/usr/@/share/@/lilypond/}.
@cindex adjusting output
@cindex variables
@cindex lilypond-internals
@cindex internal documentation
@cindex Scheme
-@cindex extending lilypond
-@cindex bugreport
+@cindex extending LilyPond
@cindex index
Finally, this and all other manuals, are available online both as PDF
files and HTML from the web site, which can be found at
-@uref{http://www.lilypond.org/}.
+@uref{http://@/www@/.lilypond@/.org/}.
+
-@cindex website
-@cindex URL
projects / lilypond.git / blobdiff