@c -*-texinfo-*-
+
@node Introduction
@chapter Introduction
+There are a lot of programs that let you print sheet music with a
+computer. Unfortunately, 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 in a program: we have tuned our algorithms, font-designs, and
+program settings to make the output match that of the old editions
+that we love to see and love to play from.
-LilyPond is a program to print sheet music. If you have used notation
-programs before, then the way to use this program might be surprising
-at first sight. To print music with lilypond, you have to enter
-musical codes in a file. Then you run LilyPond on the file, and the
-music is produced without any user intervention. For example,
-something like this:
-
-@lilypond[fragment,verbatim, relative 1, intertext="produces this"]
-\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
-@end lilypond
-
-@cindex encoding music
-
-Encoding music using letters and digits may appear strange,
-intimidating or even clumsy at first. Nevertheless, when you take the
-effort to learn the codes and the program you will find that it is
-easier than it seems. Entering music can be done quickly, and you
-never have to remember how you made the program do something
-complicated: it's all in the input code, and you only have to read the
-file to see how it works. Moreover, when you use LilyPond, you are
-rewarded with very nicely looking output.
-
-In this chapter, we will explain the reasoning behind this unusual
-design, and how this approach affects you as a user.
@menu
-* Batch processing::
-* Music engraving::
+* Music notation and engraving::
+* Notation and engraving in LilyPond::
+* Typography and program architecture::
* Music representation::
+* Example applications::
* About this manual::
@end menu
-@node Batch processing
-@section Batch processing
+@node Music notation and engraving
+@section Music notation and engraving
+
-@cindex GUI
-@cindex Batch
-@cindex UNIX
-When we started developing LilyPond, we were still studying at the
-university. We were interested in music notation, not as publishers
-or musicians, but as students and scientists. We wanted to figure to
-what extent formatting sheet music could be automated. Back then GUIs
-were not as ubiquitous as they are today, and we were immersed in the
-UNIX operating system, where it is very common to use compilers to
-achieve computing tasks, so our computerized music engraving
-experiment took on the form of a compiler.
+@cindex engraving
+@cindex typography
-@cindex free software
-@cindex sharing software
+@c eerste zin beetje deur in huis
+Making sheet music may seem trivial, ``you print 5 lines, and then put
+in the notes at different heights'', but as you learn more of it, the
+opposite turns out to be true. One has to master two difficult
+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.
-You can freely use, modify and redistribute LilyPond. This choice was
-also motivated by our academic background. In the scientific community
-it has always been a tradition to share knowledge, also if that
-knowledge was packaged as software. One of the most visible groups
-that stimulated this philosophy, was the Free Software Foundation,
-whose popular GNU project aimed to replace closed and proprietary
-computing solutions with free (as in ``Libre'') variants. We jumped on
-that bandwagon, and released LilyPond as free software. That is the
-reason that you can get LilyPond at no cost and without any strings
-attached.
-@node Music engraving
-@section Music engraving
+@lilypondfile[notexidoc]{puer-fragment.ly}
+@center A fragment of neume notation
-@cindex engraving
-@cindex typography
+Common music notation has its roots in the medieval time. In this
+time, monks started to write down hints that indicated how their
+sacred music was sung. These hints, neumes, gradually became simpler,
+and at some point became the note heads. Lines were added to the
+neumes, to indicate a reference pitch, which later became the staff.
+Over many centuries, improvements and extensions were added, while
+other concepts disappeared. For example, the neume notation did not
+have an explicit notion of rhythm, but it did have @emph{custodes},
+symbols at the end of the line to indicate the starting pitch of the
+next line. Mensural notation, a notation where each note head takes a
+fixed amount of time, came into being together with the rise of
+counterpoint in the early renaissance. The graphic language of
+notation is still under development; the innovations of contemporary
+music require still newer and more complex notations.
-Making sheet music may seem trivial at first (``you print 5 lines, and
-then put in the notes at different heights''), @emph{music engraving},
-i.e. professional music typography, is in another ballpark. The term
-`music engraving' derives from the traditional process of music
+
+
+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, mirrored. The plate
+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. A positive image was formed by pressing paper to the
-plate. Stamping and cutting was completely done by hand. Making
+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. As you can imagine this was a highly specialized skill, much
-more so than the traditional process of printing books.
-
+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.
+
+
+@node Notation and engraving in LilyPond
+@section Notation and engraving in LilyPond
+
+Common music notation encompasses such a wide scope of music, and
+therefore inherently is complex: there are many rules, and for every
+rule there are exceptional situations where they do not apply. The
+result is that LilyPond cannot support each and every form of notation
+in existence. Rather, we focus on a specific style and idiom: we take
+inspiration from late-romantic music printed at the beginning of the
+20th century. Most of the contemporary music after that, and most of
+the music going back to 17th century can be written in this
+idiom. That is not a fundamental limit, though. There is support for
+some modern notation like clusters, and older notation, such as white
+mensural and gregorian notation, is being worked on.
+
+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
+
+@item
+Henle (2000)
+@tab
+B@"{a}renreiter (1950)
+@tab
+LilyPond Feta font (2003)
+
+@end multitable
-The following fact illustrates that. In the traditional German
-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 acceptable to be published.
-
-When we wanted to write a computer program to do create music
-typography, we encountered the first problem: there were no sets of
-musical symbols available: either they were not available freely, or
-they didn't look well to our taste. Not let down, we decided to try
-font design ourselves. We created a font of musical symbols, relying
-on nice printouts of hand-engraved music. It was a good decision to
-design our own font. The experience helped develop a typographical
-taste, and it made us appreciate subtle design details. Without that
-experience, we would not have realized how ugly the fonts were that we
-admired at first.
-
-
-@lilypond
-#(define magfact 3.0)
-\score { \notes { as'2 r4 }
- \paper {
- linewidth = -1.
- \translator {
- \ScoreContext
- AccidentalPlacement \override #'right-padding = #3.0
- StaffSymbol \override #'transparent = ##t
- Clef \override #'transparent = ##t
- TimeSignature \override #'transparent = ##t
- Accidental \override #'font-magnification = #magfact
- Rest \override #'font-magnification = #magfact
- NoteHead \override #'font-magnification = #magfact
- Stem \override #'transparent = ##t
- } } }
-@end lilypond
@cindex musical symbols
@cindex font
@cindex blackness
@cindex balance
-The figure above shows a few notable glyphs. For example, the
-half-notehead is not elliptic but slightly diamond shaped. The
-vertical stem of a flat symbol should be slightly brushed,
-i.e. becoming wider at the top. Fine endings, such as the one on the
-bottom of the quarter rest, should not end in sharp points, but rather
-in rounded shapes. Taken together, the blackness of the font must be
-carefully tuned together with the thickness of lines, beams and slurs
-to give a strong yet balanced overall impression.
-
-Producing a strong and balanced look is the real challenge of music
-engraving. It is a recurring theme with many variations. In spacing,
-the balance is in a distribution that reflects the character of the
-music. The spacing should not lead to unnatural clusters of black and
-big gaps with white space. The distances between notes should reflect
-the durations between notes, but 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 both exact,
-mathematical spacing, and with some corrections. Can you spot which is
-which?
-
-@c I can only see the motive printed two times!!! /Mats
+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?
@cindex optical spacing
-@lilypond
+@lilypond[noindent]
\score { \notes {
\property Staff.NoteSpacing \set #'stem-spacing-correction
= #0.6
c'4 e''4 e'4 b'4 |
- b'4 e''4 \stemDown e'4 e''4| \stemBoth
+ \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 |
- b'4 e''4 \stemDown e'4 e''4|
+ \stemDown b'4 e''4 a'4 e''4|
}
- \paper { linewidth = -1. } }
+ \paper { raggedright = ##t } }
@end lilypond
@cindex regular rhythms
@cindex regular spacing
-The fragment that was printed uses only quarter notes: notes that are
-played in a constant rhythm. The spacing should reflect
-that. Unfortunately, the eye deceives us a little: the eye not only
-notices the distance between note heads, but also between consecutive
-stems. The notes of a 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
-downstem/upstems clumps of notes.
+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 engraver 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. is 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. A way to accomplish this, is to store decisions
+in generic variables, and let the user manipulate these variables.
+For example, consider the following fragment of notation:
+
+@lilypond
+\score { \notes \relative c'' {
+\stemUp
+ a4^\f f8
+ }
+\paper { raggedright = ##t }
+ }
+@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:
-We hope that these examples show that music typography is a subtle
-business, and that it requires skill and knowledge to produce good
-engraving. It was our challenge to see if we could put such knowledge
-into a computer program.
+@lilypond
+\score { \notes \relative c'' {
+\stemUp
+ \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
+ a4^\f f8
+ }
+\paper { raggedright = ##t }
+ }
+@end lilypond
+
+This was achieved with the following input statement:
+@example
+ \once \property Voice. DynamicLineSpanner \override #'padding = #4.0
+@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:
+@example
+ \property Score.Stem \override #'thickness = #2.0
+@end example
+
+@lilypond
+\score { \notes \relative c'' {
+ \property Score.Stem \override #'thickness = #2.0
+ \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
+\stemUp
+ a4^\f f8
+ }
+\paper { raggedright = ##t }
+ }
+@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
+@example
+ \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
+ = #`(,gee-whiz-gadget)
+@end example
+
+@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 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.
@node Music representation
@section Music representation
-One of the big questions when making programs, is what kind of input
-the program should expect. Many music notation programs offer a
-graphical interface that shows notation, and allow you to enter the
-music by placing notes on a staff. Although this is a obvious way to
-design a program, from our point of view, it is cheating. After all,
-the core message of a piece of music notation simply is the music
-itself. If you start by offering notation to the user, you have
-already skipped one conversion, even if it is implicit. If we want to
-generate music notation from something else, then the obvious
-candidate for the source is the music itself.
+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. Even if you are more practically
-inclined, you will notice that there exist an enormous number of ways
-to represent music in a computer, and they are much more incompatible
-than the formats for word processors and spreadsheets. Anyone who has
-tried to exchange data files from between different notation programs
-can attest to this.
-
-@cindex music representation
-@cindex music expressions
-@cindex input format
-
-This problem is caused by the two-dimensional nature of music: in
-polyphonic music, notes have time and pitch as their two coordinates,
-and they often are related in both directions. Computer files on the
-other hand are essentially one-dimensional: they are a long stream of
-characters. When you represent music in a file, then you have to
-flatten this two-dimensional information breaking either timing or
-pitch relations, and there is no universal agreement on how to do
-this.
-
-Fortunately, we have a concrete application, so we don't run the risk
-of loosing ourselves in philosophical arguments over the essence of
-music. We want to produce a printed score from a music
-representation, so this gives us a nice guide for designing a format:
-we need a format containing mainly musical elements, such as pitch and
-duration, but also enough information to print a score. Our users
-have to key in the music into the file directly, so the input format
-should have a friendly syntax. Finally, we as programmers and
-scientists want a clean formal definition. After all, producing music
-notation is a difficult problem, and in the scientific world, problems
-can only be solved if they are well-specified. Moreover, formally
-defined formats are easier to write programs for.
-
-These ideas shaped our music representation: it is a compact format
-that can easily be typed by hand. It complex musical constructs from
-simple entities like notes and rests, in much the same way that one
-builds complex formulas from simple expressions such as numbers and
-mathematical operators. The strict separation between musical
-information and typesetting also gives a blueprint of the program:
-first it reads the music representation, then it interprets the
-music---reading it `left-to-right', and translating the musical
-information to a layout specification. When the layout is computed,
-the resulting symbols are written to an output file.
+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, they 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
+work, the program can now be used to perform useful tasks. The
+simplest application is printing notes:
+
+@lilypond[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 } > }
+@end lilypond
+
+Polyphonic notation and piano music can also be printed. The following
+example combines some more exotic constructs:
+
+@lilypondfile{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
+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 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.
+
@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 into typesetting music.
+First time users should start here.
+@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 lookup details.
+@item
+@ifhtml
+The
+@end ifhtml
+@emph{@ref{Literature}}
+chapter lists useful reference books on notation and engraving.
+@item
+@ifhtml
+ The
+ @end ifhtml
+@emph{@ref{Technical manual}}
+@c
+discusses the general design of the program, and how to extend its
+functionality.
+@item
+@ifhtml
+The chapter
+@end ifhtml
+@emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
+programs.
+@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 by using the index, 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
+
+
+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
+@ifhtml
+@uref{../music-glossary.html,separate document}.
+@end ifhtml
+@ifnothtml
+separate document, available in HTML and PDF.
+@end ifnothtml
+@cindex idiom
+@cindex jargon
+@cindex terminology
+@cindex foreign languages
+@cindex language
+
+
+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:
+
+@itemize @bullet
+@item
+Program reference
+@ifhtml
+(available @uref{../lilypond-internals/lilypond-internals.html,here})
+@end ifhtml
+
+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.
+
+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
+ Templates
+@ifhtml
+(available @uref{../../../input/template/out-www/collated-files.html,here})
+@end ifhtml
+
+After you have gone through the tutorial, in theory 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, by copying the template, and adding notes in the
+appropriate places.
+
+@item
+ Various input examples
+@ifhtml
+(available @uref{../../../../input/test/out-www/collated-files.html,here})
+@end ifhtml
+@cindex snippets
-As you will notice in the coming pages the program makes good
-decisions in a lot of cases: what comes out of LilyPond generally
-looks good. The default layout of lilypond even is suitable for
-publication for some specific files. However, some aspects of the
-formatting are not yet very good. For us programmers, this gives
-inspiration for improving the program. However, most users are more
-interested in improving their printouts, and then they have to make
-manual adjustments to the output. Another aspect of our system of
-encoding through ASCII then shows: it can be complicated to fine tune
-the layout of a piece. There is no graphical user interface, where you
-can simply click and drag a symbol. On the other hand, if you have
-written the code for tuning one specific aspect of the layout, then
-you can simply store the file on disk, retrieve it when you need it:
-there is no need to remember how you did it, since it is all in the
-input file.
+These small files show various tips and tricks, and are available as a
+big HTML document, with pictures and explanatory texts included.
-@cindex snippets
-@cindex adjusting output
-Lilypond also comes with a huge collection of snippets that show all
-kinds of tricks. This collection is much needed, because of the way
-LilyPond is structured. It is a large program, but almost all of the
-internal functionality is exported: that is, the variables that are
-internally used for formatting the sheet music are available directly
-to the user. These are variables to control thicknesses, distances,
-and other formatting options. There are a huge number of them, and it
-would be impossible to describe them all in a hand-written
-manual. There is no need to despair, there is an `automatic' manual,
-that lists all of the variables that are available. It is directly
-generated from the definitions that LilyPond itself uses, so it is
-always up to date. If you are reading this from a screen: it is
-available from the web, and is included with most binary
-distributions. If you're reading this from paper, then we advise you
-to use the digital version anyway: the hyperlinks make finding topics
-in the lilypond-internals manual much easier.
+@item
+ The regression test
+@ifhtml
+(available @uref{../../../input/regression/out-www/collated-files.html,here})
+@end ifhtml
+
+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.
+
+@end itemize
+
+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
+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/}.
+
+@cindex adjusting output
@cindex variables
@cindex properties
@cindex lilypond-internals
-@cindex internal documentation
-
-For those who really want to get their hands dirty: it is even
-possible to add your own functionality, by extending LilyPond in the
-built-in scripting language, a dialect of the powerful programming
-language Scheme. There is no real distinction between what a user can
-do and what a programmer is allowed to do.
-
+@cindex internal documentation
@cindex Scheme
@cindex extending lilypond
-
-In summary, this manual does not pretend to be exhaustive, but it is
-merely a guide that tries to explain the most important principles,
-and shows popular input idioms. The rest of the manual is structured
-as follows: it starts with a tutorial that explains how to use
-lilypond. In the tutorial, a number of fragments of increasing
-complexity are shown and explained. Then comes the reference manual,
-which gives more detailed information on all features. If you're new
-to lilypond, then you should start reading the tutorial, and
-experiment for yourself. If you already have some experience, then
-you can simply use the manual as reference: there is an extensive
-index.@footnote{If you are looking for something, and you can't find it
-by using the index, that is considered a bug. In that case, please
-file a bug report}
-
@cindex bugreport
@cindex index
-@cindex tutorial
-@cindex overview of manual
-@cindex idiom
-
+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/}.
+@cindex website
+@cindex URL
projects / lilypond.git / blobdiff