Documentation/user/introduction.itely

   1 @c -*-texinfo-*-
   2
   3 @node Introduction
   4 @chapter Introduction
   5
   6 LilyPond is a program to print sheet music. If you have used such
   7 programs before, then the way to use this program might be surprising
   8 at first sight. To print music with lilypond, you have to enter
   9 musical codes in a file. Then you run LilyPond on the file, and the
  10 music is produced without any user intervention. For example,
  11 something like this:
  12
  13 @lilypond[fragment,verbatim, relative 1, intertext="produces this"]
  14 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
  15 @end lilypond
  16
  17 We can very well imagine that encoding music using letters may appear
  18 strange, intimidating or even clumsy at first. Nevertheless, when you
  19 take the effort to learn the codes and the program you will find that
  20 it is not so difficult as it seems, entering music can be done
  21 quickly, and you never have to remember how you made the program do
  22 something complicated: it's all in the input code, and you only have
  23 read the file to see how it works. Moreover, when you use LilyPond,
  24 you are rewarded with very nicely looking output.
  25
  26 This form of computing (produce the output in one go, without user
  27 intervention), is called @emph{batch} computing, and the program that
  28 is used is normally called a @emph{compiler}. In contrast, it is now
  29 fashionable to produce interactive programs that rely on a Graphical
  30 User Interface (GUI).
  31
  32 When we started with developing LilyPond in a time that were studying
  33 at the university. Back then GUIs were not as ubiquitous as they are
  34 today, and we were immersed in the UNIX operating system, where it is
  35 very common to use compilers to achieve computing tasks, so our
  36 computerized music engraving experiment took on the form of a
  37 compiler.
  38
  39 One other decision was also motivated by our academic background. In
  40 the scientific community it has always been a tradition to share
  41 knowledge, and to a lesser extent, to share the software you
  42 wrote. One of the most visible groups that stimulated this philosopy,
  43 was the Free Software Foundation, whose GNU project aimed to replace
  44 the closed and proprietary computing solutions with free (as in
  45 "Libre") variants. We jumped on that bandwagon, and that is the reason
  46 that you can still get LilyPond at no cost, and with no strings
  47 attached.
  48
  49 When we started, we were interested in music notation, not as
  50 publishers or musicians, but as students and scientists. We wanted
  51 tried to figure to what extent formatting sheet music could be
  52 automated.  Making sheet music may seem trivial at first (``you print
  53 5 lines, and then put in the notes at different heights''),
  54 @emph{music engraving}, i.e. professional music typography, is in
  55 another ballpark.
  56
  57 The term music engraving derives from the traditional process of music
  58 printing.  A few decades ago, sheet music was made by cutting and
  59 stamping the music mirrored into zinc or pewter plates. The plate
  60 would be inked, and the depressions caused by the cutting and stamping
  61 would hold ink thus forming an positive image. Stamping and cutting
  62 was completely done by hand, and making corrections was cumbersome, so
  63 engraving had to be correct in one go. As you can imagine this was a
  64 highly specialized skill, much more so than the traditional process of
  65 printing books.
  66
  67 In fact, the traditional german craftmanship required six years of
  68 full-time training, before a student could call himself a master of
  69 the art. After that many more years of practical experience were
  70 needed to become an established music engraver.  Even today, in the
  71 era of high-speed computers, music requires lots of manual fine tuning
  72 before it acceptable to be published.
  73
  74 The first step of making music prints is to have the symbols
  75 available.  Unfortunately, most of the knowledge about music engraving
  76 has not been laid down in an easily accessible form, so when we wanted
  77 to write a computer program to do create music typography, we
  78 encountered the first problem: there were no sets of musical symbols
  79 available: either they were not available freely, or they didn't look
  80 well to our subtle tastes. That was the reason for us to create a font
  81 of musical symbols, relying mostly on nice printouts of hand-engraved
  82 music.
  83
  84 @lilypond
  85 #(define magfact 2.0)
  86 \score {  \notes { as'2 r4 }
  87           \paper {
  88               linewidth = -1.
  89               \translator {
  90                   \ScoreContext
  91                   AccidentalPlacement \override #'right-padding = #3.0
  92                   StaffSymbol \override #'transparent =   ##t
  93                   Clef \override #'transparent = ##t
  94                   TimeSignature \override #'transparent = ##t
  95                   Accidental \override #'font-magnification = #magfact
  96                   Rest \override #'font-magnification = #magfact
  97                   NoteHead \override #'font-magnification = #magfact
  98                   Stem \override #'transparent = ##t
  99                   } } }
 100 @end lilypond
 101
 102 In the figure above, a few notable glyphs are shown. For example, the
 103 half-notehead is not elliptic but slightly diamond shaped.  The stem
 104 of a flat symbol should be slightly brushed, i.e. becoming wider at
 105 the top. Fine endings, such as the one on the bottom of the quarter
 106 rest, should not end in sharp points, but rather in rounded shapes.
 107 The blackness of the font must be carefully tuned to the thickness of
 108 lines, beams and slurs to give a strong yet balanced overall
 109 impression.
 110
 111 It was a good decision to design our own font. The experience helps
 112 develop a typographical taste, and it makes one appreciate subtle
 113 design details. Without that experience, we would not have realized
 114 how ugly the fonts were that we admired at first.
 115
 116 Producing a strong and balanced look is the real challenge of music
 117 engraving. It is a recurring theme with many variations. One of these
 118 variations is choosing spacing. The distances between notes should
 119 reflect the durations between notes, but adhering with mathematical
 120 precision to the duration will lead to a poor result. Shown here is an
 121 example of a motive, printed four times. It is printed using both
 122 exact, mathematical spacing, and with some corrections. Can you spot
 123 which is which?
 124
 125 @lilypond
 126     \score { \notes {
 127       \property Staff.NoteSpacing \set #'stem-spacing-correction
 128         = #0.6
 129       c'4 e''4 e'4 b'4 |
 130       c'4 e''4 e'4 b'4 |
 131       \property Staff.NoteSpacing \override #'stem-spacing-correction
 132       = #0.0
 133       \property Staff.StaffSpacing \override #'stem-spacing-correction
 134       = #0.0
 135       c'4 e''4 e'4 b'4 |
 136       c'4 e''4 e'4 b'4 |
 137     }
 138     \paper { linewidth = -1. } }
 139 @end lilypond
 140
 141 The fragment that was printed uses only quarter notes: notes that are
 142 played in a constant regular rhythm. The spacing should reflect
 143 that. Unfortunately, the eye deceives us a little: the eye not only
 144 notices the distance between note heads, but also between consecutive
 145 stems. Depending on the different vertical positions, the notes of a
 146 upstem-downstem should be put farther apart, and the notes of a
 147 down-up combination should be put closer. The first two measures are
 148 printed with this correction, the last two measures without. The notes
 149 in the last two measures form downstem/upstems clumps of notes.
 150
 151 We hope that these examples serve to show that music typography is a
 152 subtle business, and that it requires skill and knowledge to produce
 153 good engraving---skill and knowledge most people lack.  It was our
 154 challenge to see if we could put such knowledge into a computer
 155 program.
 156
 157 One of the first questions that pop up when you design such a program,
 158 is what kind of input the program should expect. Many music notation
 159 programs offer a graphical interface that shows notation, and allows
 160 you to enter the music by placing notes on a staff. Although this is a
 161 obvious way to design a program, from our point of view, this is
 162 cheating. After all, the core message of a piece of music notation
 163 simply is the music itself. If you start by offering music notation to
 164 the user, you have already skipped one conversion, even if it perhaps
 165 is implicit. If we want to generate music notation, then the obvious
 166 candidate for the source format should be the music itself.
 167
 168 Of course, on paper this theory sounds very good. In practice, it
 169 opens a can of worms. What really @emph{is} music? Many philosophical
 170 treatises must have been written on the subject. Even if you're more
 171 practically inclined, you will notice that an enormous number of
 172 different ways to represent music in a computer exist, and they are
 173 much more incompatible than the formats for wordprocessors and
 174 spreadsheets.  Anyone who has tried to exchange data files from
 175 between different computer programs can attest to this.
 176
 177 The cause of this problem is that music is inherently two-dimensional:
 178 in polyphonic music, notes have time and pitch as their two
 179 coordinates, and they often are related in both directions. Computer
 180 files on the other hand are essentially one-dimensional: they are a
 181 long stream of characters. When you represent music in a file, then
 182 you have to flatten this two-dimensional information breaking the
 183 timing or the pitch, relations, and there is no universal agreement on
 184 how to do this.
 185
 186 It might seem that when designing a music representation, we have
 187 myriad of choices.  Luckily, we have some requirements that shaped the
 188 input format into what it is now.  A music representation is about
 189 @emph{music}, so it should be free from notation as much as possible:
 190 the format is about pitches and durations, not about symbols and
 191 offsets. Since LilyPond is a compiler, the input format is its user
 192 interface, and users have to key in the music into the file directly,
 193 requiring that the input format has a friendly syntax. We, as
 194 programmers and scientists also like the format to have a clean formal
 195 definition. After all, producing music notation is a difficult
 196 problem, and in the scientific world, difficult problems always must
 197 be well-specified. Moreover, formally defined formats are easier to
 198 write programs for. Finally, enough information should be present to
 199 be able to produce a printed score.
 200
 201 These ideas shaped music representation elegantly builds complex
 202 musical constructs from simple entities like notes and rests, in much
 203 the same way that one builds complex formulae from simple expressions
 204 such as numbers and mathematical operators.
 205
 206 The strict separation between musical information and typesetting also
 207 gives a blueprint of the program: first it reads the music
 208 representation, then it interprets the music---reading it
 209 `left-to-right', and translating the musical information to a layout
 210 specification. When the layout is computed, the resulting symbols are
 211 written to an output file.
 212
 213 Much more could be said about the inner working of the program, but we
 214 will leave it at this. Those who are interested can inspect the source
 215 code, which is available freely, or inquire on the development mailing
 216 list.
 217
 218 We hope that you understand where LilyPond came from, and what we
 219 tried to achieve. The rest of this manual less philosophical: it
 220 instructs you how use the input language to print beautiful music.
 221
 222
 223
 224
 225
 226 @ignore
 227
 228
 229
 230 Nowadays, we still don't know everything about music notation, and we
 231 are still trying to use
 232
 233
 234 LilyPond is a free program that produces high quality sheet music.
 235
 236 The features that set LilyPond apart from other music printing
 237 programs are
 238
 239 @itemize
 240 @item Freely available under terms of the GNU GPL
 241 @item Carefully designed music font
 242 @item Lots of music formatting knowledge
 243 @item Sophisticated formatting functions
 244 @item Output is  configurable using Scheme
 245 @item Highly modular design
 246 @item Semantic input format
 247 *@item Input can be generated, inspected and modified via builtin Scheme
 248  interpreter.
 249 @item Runs on both Unix and MS Windows
 250 @item Multiple output formats
 251 @item Easily embed musical fragments in LaTeX, Texinfo and HTML documents.
 252 @item Works as a compiler: edit input in your favorite text editor
 253 @end itemize
 254
 255 If you need to print out existing arrangements, composition, new
 256 editions, or musical excercises, then LilyPond will suit you.
 257 LilyPond is not interactive, and is probably not suited for creating
 258 new compositions.
 259
 260 @menu
 261 * Why LilyPond::
 262 * The Feta Font::
 263 * Engraving::
 264 * Semantic input format::
 265 * A programming approach::
 266 * About this manual::
 267 * Bug reports::
 268 * Web site::
 269 @end menu
 270
 271
 272 @node Why LilyPond
 273 @section Why LilyPond
 274
 275 LilyPond originally started out as an interesting hobby
 276 project. Intrigued by music notation we set out to write a program to
 277 produce high-quality music printouts, with minimal user intervention.
 278
 279 Engraving, the art of printing music is a very complex craftmanship,
 280 that tries to make a typographically beautiful rendering of a piece of
 281 music.  The purpose of nicely engraved music is to ease the way music
 282 is read.  The typographical decisions have underlying logic, and to us
 283 scientists, this begs the question: what is this logic, and can we
 284 cast this logic into the more concrete form a computer program.
 285
 286 LilyPond is our concrete answer to this question, but besides being an
 287 interesting hobby project, it also allows people that don't know much
 288 about notation and engraving to print fine sheet music.
 289
 290 With LilyPond, we hope to give back a little to the Free Software
 291 Community that gave us so much, and if possible, give people the
 292 opportunity to publish sheet music with high quality layout.  In our
 293 utopic vision, some day LilyPond will help create more beautiful music.
 294
 295 @end ignore