X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fintroduction.itely;h=302074d56d7f72de2094d49b69c91c333928f023;hb=723545fd108d20edfb41c01b14df5962192cc226;hp=fe805695e8d31b71c2a597d56a4ea405d6275961;hpb=a33acad610030d8f3b90fc1d784d8a7b6679a902;p=lilypond.git diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index fe805695e8..302074d56d 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -1,332 +1,596 @@ @c -*-texinfo-*- + @node Introduction @chapter Introduction - -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 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 try to explain what we are trying to do with -LilyPond, how this lead to its current form, and how this approach -affects you as a user. +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. @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 with developing LilyPond, we were interested in music -notation, not as publishers or musicians, but as students and -scientists. We wanted tried to figure to what extent formatting sheet -music could be automated. This was when we were still studying at the -university. 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 free software -@cindex sharing software +@cindex engraving +@cindex typography -One other decision was also motivated by our academic background. In -the scientific community it has always been a tradition to share -knowledge, and, to a lesser extent, the software you wrote. One of the -most visible groups that stimulated this philosopy, was the Free -Software Foundation, whose GNU project aimed to replace closed and -proprietary computing solutions with free (as in ``Libre'') -variants. We jumped on that bandwagon, and that is the reason that you -can still get LilyPond at no cost without any strings attached. +@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. -@node Music engraving -@section Music engraving +@lilypondfile[notexidoc]{puer-fragment.ly} +@center A fragment of neume notation -@cindex engraving -@cindex typography -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 -printing. Only a few decades ago, sheet music was made by cutting and -stamping the music mirrored into zinc or pewter plates. 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, and making -corrections was cumbersome, so engraving had to be correct in one -go. As you can imagine this was a highly specialized skill, much more -so than the traditional process of printing books. +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. -@cindex craftmanship -@cindex master -In fact, in the traditional German craftmanship six years of full-time -training 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, in the -era of high-speed computers, 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. That was the reason for us to -create a font of musical symbols, relying mostly on nice printouts of -hand-engraved music. It was a good decision to design our own -font. The experience helps develop a typographical taste, and it makes -one appreciate subtle design details. Without that experience, we -would not have realized how ugly the fonts were that we admired at -first. +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. + + +@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 + +@end html + +@tab +@iftex +@image{baer-flat-bw,4cm} +@end iftex +@html + +@end html + +@tab +@iftex +@image{lily-flat-bw,4cm} +@end iftex +@html + +@end html + +@item +Henle (2000) +@tab +B@"{a}renreiter (1950) +@tab +LilyPond Feta font (2003) + +@end multitable -@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 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. One of these -variations is choosing spacing. 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 four times. It is printed using both -exact, mathematical spacing, and with some corrections. Can you spot -which is which? +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 b'4 e''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 | - b'4 e''4 b'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 regular 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. Depending on the different vertical positions, the notes of a -upstem-downstem combination should be put farther apart, and the notes -of a down-up combination should be put closer together. 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: + +@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 -We hope that these examples serve to 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. +@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 first questions that pop up when you design such a program, -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, this 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 perhaps is -implicit. If we want to generate music notation from something else, -then the obvious candidate for the source should be the music itself. - -Of course, 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 an enormous number of -different ways to represent music in a computer exist, and they are -much more incompatible than the formats for wordprocessors 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 - -The cause of this problem is that music is inherently two-dimensional: -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. - -Luckily, our application has guided us a little with the design of the -format: we want to produce a printed score from a music -representation. A music representation is about @emph{music}, so it -should be free from notation as much as possible: the format is about -pitches and durations, not about symbols and offsets. Since LilyPond -is a compiler, the input format is its user interface, and users have -to key in the music into the file directly, requiring that the input -format has a friendly syntax. We, as programmers and scientists want a -clean formal definition. After all, producing music notation is a -difficult problem, and in the scientific world, difficult problems -always must be well-specified. Moreover, formally defined formats are -easier to write programs for. Finally, enough information should be -present to be able to produce a printed score. - -These ideas shaped our music representation which elegantly builds -complex musical constructs from simple entities like notes and rests, -in much the same way that one builds complex formulae 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. +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, 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 +These small files show various tips and tricks, and are available as a +big HTML document, with pictures and explanatory texts included. -As you will notice in the coming pages, and the examples, in a lot of -case, the program makes good decisions, and what comes out of lilypond -generally looks good. For some specific examples, the default layout -of lilypond even is suitable for publication. However, some aspects of -the formatting are not yet very good. This gives us programmers -inspiration for improving the program. However, most users are more -interested in making their printouts look good, 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. It's all in -the input file. Lilypond also comes with a huge collection of snippets -that show all kinds of tricks. -@cindex snippets -@cindex adjusting output +@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 -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 to determine formatting of 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 `automatic' manual, that -lists all of the variables, symbol types, etc. 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. +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 short, 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 of 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 something, and you can't find it by -using the index, that is considered a bug. In that case, please file -a bugreport} - @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