+@c -*-texinfo-*-
+
@node Introduction
@chapter Introduction
-LilyPond is a free program that produces high quality sheet music.
-
-The features that set LilyPond apart from other music printing
-programs are
-
-@itemize
-@item Freely available under terms of the GNU GPL
-@item Carefully designed music font
-@item Lots of music formatting knowledge
-@item Sophisticated formatting functions
-@item Output is configurable using Scheme
-@item Highly modular design
-@item Semantic input format
-@item Input can be generated, inspected and modified via builtin Scheme
- interpreter.
-@item Runs on both Unix and MS Windows
-@item Multiple output formats
-@item Easily embed musical fragments in LaTeX, Texinfo and HTML documents.
-@item Works as a compiler: edit input in your favorite text editor
-@end itemize
-
-If you need to print out existing arrangements, composition, new
-editions, or musical excercises, then LilyPond will suit you.
-LilyPond is not interactive, and is probably not suited for creating
-new compositions.
-
-@menu
-* Why LilyPond::
-* The Feta Font::
-* Engraving::
-* Semantic input format::
-* A programming approach::
-* About this manual::
-* Bug reports::
-* Web site::
-@end menu
-
-@node Why LilyPond
-@section Why LilyPond
-
-LilyPond originally started out as an interesting hobby
-project. Intrigued by music notation we set out to write a program to
-produce high-quality music printouts, with minimal user intervention.
-
-Engraving, the art of printing music is a very complex craftmanship,
-that tries to make a typographically beautiful rendering of a piece of
-music. The purpose of nicely engraved music is to ease the way music
-is read. The typographical decisions have underlying logic, and to us
-scientists, this begs the question: what is this logic, and can we
-cast this logic into the more concrete form a computer program.
-
-LilyPond is our concrete answer to this question, but besides being an
-interesting hobby project, it also allows people that don't know much
-about notation and engraving to print fine sheet music.
-
-With LilyPond, we hope to give back a little to the Free Software
-Community that gave us so much, and if possible, give people the
-opportunity to publish sheet music with high quality layout. In our
-utopic vision, some day LilyPond will help create more beautiful music.
-
-@node The Feta Font
-@section The Feta Font
-
-Most of the rules concerning music symbols have not been explicitly
-laid down, so we have imitated the looks of symbols in beautiful hand
-engraved music. The starting point was to have a strong, bold look,
-with rounded symbol shapes, just like traditional engraving.
+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:
-@iftex
- {\font\fet=feta20 at 100pt
- \fet\fetaquartrest\hskip 1cm\fetahalfhead\hskip 1cm\fetaflat}
-@end iftex
-
-In the figure above, a few notable glyphs are shown. For example, in
-most music the half-notehead is not elliptic but 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.
-
-Finally, the blackness of the font is carefully tuned to give a strong
-and dark visual impression. Many computer music fonts are rather
-light, leading to anemic look when they are printed.
+@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
-Although such details are not directly visible to the untrained eye,
-careful attention to such details gives lilypond output a more
-balanced appearance. We believe that the Feta font is among the most
-elegant music font designs available today.
+@cindex encoding music
-The Feta font was implemented in the font design system METAFONT. The
-source code includes numerous comments on the specific design
-considerations of each glyph. PostScript Type1 versions of the font
-are also available.
+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.
-@node Engraving
-@section Engraving
+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 representation::
+* About this manual::
+@end menu
-Music engraving used to be a craft requiring many years of training.
-In the old days, 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
-thus forming an positive image.
+@node Batch processing
+@section Batch processing
+
+@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 free software
+@cindex sharing software
+
+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
+
+
+
+@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 into zinc or pewter plates, mirrored. 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
+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.
+
+@cindex craftsmanship
+@cindex master
+
+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.
-Of all craftmanships, engraving was the most difficult to learn trade;
-completing the basic training took as long as six years.
-Unfortunately, little of this knowledge comes to us as explicitly
-formulated rules.
-The only books that specifically deal with music typography are the
-books by Ross, Wanske and Hader @cite{hader48,ross,wanske}, and we
-have found that are often lacking in detail. Of course, in order to
-accurately computerize a process, one has to have a very detailed
-description of what must be done.
+@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
+
+@cindex optical spacing
@lilypond
\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
\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 |
+ c'4 e''4 e'4 b'4 |
+ \stemDown b'4 e''4 a'4 e''4|
}
\paper { linewidth = -1. } }
@end lilypond
-@node Semantic input format
-@section Semantic input format
-
-One the key points of LilyPond, is that the input is musical: what you
-put into the program are musical concepts, such as pitches, durations,
-voices, etc. The program then interprets these concepts, and produces
-graphic output: glyphs, curves, offsets. In this way the program
-tries to act like an engraver.
-
-
-If you only want to print music, this might not interest you so much,
-except for the fact that it means you don't have to worry much about
-formatting details.
-
-
-Many music encodings exist today @cite{selfridge-field97:beyond-midi},
-but most of the encodings have not been tailored either for human use,
-or for processing it with a computer. By its nature, LilyPond input
-has both features: it is concise, suitable for human input, and it can
-be processed automatically: it may be converted into MIDI or into print.
-
-
-However, one big problem with music, is that there are no standards
-for encoding music. Sure, you can record performances using MIDI, but
-that offers far too little information for adequate musicological
-purposes. With LilyPond we've taken a reverse approach: we have tried
-to come up with musical format that can cater virtually all music as
-long as it can be notated.
-
-LilyPond input focuses on musical concepts such as pitch, duration and
-music expressions. Musical data is rhythmic, and implies an ordering
-of events. This ordering is used to create compound musical concepts:
-Large musical structures are built recursively from smaller
-expressions: a sequence of music expressions forms a new, longer and
-bigger music expression. In this sense, the input is recursive. It
-shares this property with very music encodings. The recursive nature
-will appeal to the more hackerish musician.
-
-
-@node A programming approach
-@section A programming approach
-
-blabla
-
-@node About this manual
+@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.
+
+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.
+
+
+@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.
+
+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.
+
+
+@node About this manual
@section About this manual
-blabla
-
-
-@node Bug reports
-@section Bug reports
-
-@cindex bugs
-@cindex reporting bugs
-
-
-Since there is no finder's fee which doubles every year, there is no
-need to wait for the prize money to grow. So send a bug report today!
-
-LilyPond development moves quickly, so if you have a problem, it is
-wise to check if it has been fixed in a newer release. If you think
-you found a bug, please send in a bugreport. When you send us a
-bugreport, we have to diagnose the problem and if possible, duplicate
-it. To make this possible, it is important that you include the
-following information in your report:
-
-@itemize @bullet
-
-@item A sample input which causes the error. Please have mercy on the
-developers, send a @emph{small} sample file.
-
-@item The version number of lilypond.
-
-@item A description of the platform you use (i.e., operating system,
-system libraries, whether you downloaded a binary release)
-
-@item If necessary, send a description of the bug itself. If you
-include output a ly2dvi run, please use @code{--verbose} option of
-ly2dvi.
-
-@end itemize
-You can send the report to @email{bug-lilypond@@gnu.org}. This is a
-mailinglist, but you don't have to be subscribed to it to post.
+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.
+
+@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.
+
+@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 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
-@node Web site
-@section Web site
-If you are reading this manual in print, it is possible that the
-website contains updates to the manual. You can find the lilypond
-website at @uref{http://www.lilypond.org/}.
projects / lilypond.git / blobdiff