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