]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/introduction.itely
4d5e5600fb385b09f30851922607693bee7762c9
[lilypond.git] / 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: in order to print music you have to enter musical
9 codes in a file.  Then you run the program on the file, and the music
10 is produced without any further intervention.  For example, something
11 like this:
12
13
14 @lilypond[fragment,verbatim, relative 1, intertext="produces this:
15
16 "]
17 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
18 @end lilypond
19
20 @cindex encoding music
21
22 Encoding music using letters and digits may appear strange,
23 intimidating or even clumsy at first. Nevertheless, when you take the
24 effort to learn the codes and the program you will find that it is
25 easier than it seems.  Entering music can be done quickly, and you
26 never have to remember how you made the program do something
27 complicated: it is all in the input code, and you only have to read
28 the file to see how it works. Moreover, you are rewarded with very
29 nicely looking output.
30
31 In this chapter, we will explain the reasoning behind this unusual
32 design, and how this approach affects you as a user.
33
34 @menu
35 * Batch processing::            
36 * Music engraving::             
37 * Music representation::        
38 * Example applications::        
39 * About this manual::           
40 @end menu
41
42 @node Batch processing
43 @section Batch processing
44
45 @cindex GUI
46 @cindex Batch
47 @cindex UNIX
48
49 When we started developing LilyPond, we were still studying at the
50 university.  We were interested in music notation, not as publishers
51 or musicians, but as programmers and scientists. We wanted to figure
52 to what extent formatting sheet music could be automated.  Back then
53 GUIs were not as ubiquitous as they are today, and we were immersed in
54 the UNIX operating system, where it is very common to use compilers to
55 achieve computing tasks. So, our computerized music engraving
56 experiment took on the form of a compiler.
57
58
59 @ignore
60 @cindex free software
61 @cindex sharing software
62
63 You can freely use, modify and redistribute LilyPond. This choice was
64 also motivated by our academic background. In the scientific community
65 it has always been a tradition to share knowledge, also if that
66 knowledge was packaged as software. One of the most visible groups
67 that stimulated this philosophy, was the Free Software Foundation,
68 whose popular GNU project aimed to replace closed and proprietary
69 computing solutions with free (as in ``Libre'') variants. We jumped on
70 that bandwagon, and released LilyPond as free software.  That is the
71 reason that you can get LilyPond at no cost and without any strings
72 attached.
73 @end ignore
74
75
76 @node Music engraving
77 @section Music engraving
78
79
80
81 @cindex engraving
82 @cindex typography
83
84 Making sheet music may seem trivial at first (``you print 5 lines, and
85 then put in the notes at different heights''), @emph{music engraving},
86 i.e. professional music typography, is in another ballpark.  The term
87 `music engraving' derives from the traditional process of music
88 printing.  Only a few decades ago, sheet music was made by cutting and
89 stamping the music into zinc or pewter plates, mirrored. The plate
90 would be inked, and the depressions caused by the cutting and stamping
91 would hold ink.  A positive image was formed by pressing paper to the
92 plate. Stamping and cutting was completely done by hand. Making
93 corrections was cumbersome, so engraving had to be done correctly in
94 one go. As you can imagine this was a highly specialized skill, much
95 more so than the traditional process of printing books.
96 @cindex craftsmanship
97 @cindex master
98 In the traditional German craftsmanship six years of full-time
99 training, more than any other craft, were required before a student
100 could call himself a master of the art. After that many more years of
101 practical experience were needed to become an established music
102 engraver.  Even today, with the use of high-speed computers and
103 advanced software, music requires lots of manual fine tuning before it
104 acceptable to be published.
105
106 When we wanted to write a computer program to do create music
107 typography, we encountered the first problem: there were no sets of
108 musical symbols available: either they were not available freely, or
109 they did not look well to our taste. Not let down, we decided to try
110 font design ourselves. We created a font of musical symbols, relying
111 on nice printouts of hand-engraved music.  The experience helped
112 develop a typographical taste, and it made us appreciate subtle design
113 details. Without that experience, we would not have realized how ugly
114 the fonts were that we admired at first.
115
116
117 @lilypond[noindent]
118 #(define magfact 3.0)
119 \score {  \notes { as'2 r4 }
120           \paper {
121                  raggedright = ##t
122               \translator {
123                   \ScoreContext
124                   AccidentalPlacement \override #'right-padding = #3.0
125                   StaffSymbol \override #'transparent =   ##t
126                   Clef \override #'transparent = ##t
127                   TimeSignature \override #'transparent = ##t
128                   Accidental \override #'font-magnification = #magfact
129                   Rest \override #'font-magnification = #magfact
130                   NoteHead \override #'font-magnification = #magfact
131                   Stem \override #'transparent = ##t
132                   } } }
133 @end lilypond
134
135 @cindex musical symbols
136 @cindex font
137 @cindex blackness
138 @cindex balance
139
140
141 The figure above shows a few notable glyphs.  For example, the
142 vertical stem of a flat symbol should be slightly brushed,
143 i.e. becoming wider at the top. the half-notehead is not elliptic but
144 slightly diamond shaped.  Fine endings, such as the one on the bottom
145 of the quarter rest, should not end in sharp points, but rather in
146 rounded shapes.  Taken together, the blackness of the font must be
147 carefully tuned together with the thickness of lines, beams and slurs
148 to give a strong yet balanced overall impression.
149
150 Producing a strong and balanced look is the real challenge of music
151 engraving. It is a recurring theme with many variations.  In spacing,
152 the balance is in a distribution that reflects the character of the
153 music. The spacing should not lead to unnatural clusters of black and
154 big gaps with white space.  The distances between notes should reflect
155 the durations between notes, but adhering with mathematical precision
156 to the duration will lead to a poor result. Shown here is an example
157 of a motive, printed twice. It is printed using both exact
158 mathematical spacing, and with some corrections. Can you spot which is
159 which?
160
161
162 @cindex optical spacing
163 @lilypond[noindent]
164     \score { \notes {
165       \property Staff.NoteSpacing \set #'stem-spacing-correction
166         = #0.6
167       c'4 e''4 e'4 b'4 |
168        \stemDown b'4 e''4 a'4 e''4| \stemBoth
169       \property Staff.NoteSpacing \override #'stem-spacing-correction
170       = #0.0
171       \property Staff.StaffSpacing \override #'stem-spacing-correction
172       = #0.0
173       c'4 e''4 e'4 b'4 |
174       \stemDown b'4 e''4 a'4 e''4|
175     }
176     \paper { raggedright = ##t } }
177 @end lilypond
178
179 @cindex regular rhythms
180 @cindex regular spacing
181
182 The fragment that was printed uses only quarter notes: notes that are
183 played in a constant rhythm. The spacing should reflect
184 that. Unfortunately, the eye deceives us a little: the eye not only
185 notices the distance between note heads, but also between consecutive
186 stems. As a result, the notes of a up-stem/down-stem combination
187 should be put farther apart, and the notes of a down-up combination
188 should be put closer together, all depending on the combined vertical
189 positions of the notes. The first two measures are printed with this
190 correction, the last two measures without. The notes in the last two
191 measures form downstem/upstems clumps of notes.
192
193 We hope that these examples show that music typography is a subtle
194 business, and that it requires skill and knowledge to produce good
195 engraving.  It was our challenge to see if we could put such knowledge
196 into a computer program.
197
198
199 @node Music representation
200 @section Music representation
201
202
203 One of the big questions when making programs, is what kind of input
204 the program should expect. Many music notation programs offer a
205 graphical interface that shows notation, and allow you to enter the
206 music by placing notes on a staff. From our point of view, this design
207 is a form of cheating. After all, the core message of a piece of music
208 notation simply is the music itself. If you start by offering notation
209 to the user, you have already skipped one conversion, even if it is
210 implicit. If we want to generate music notation from something else,
211 then the obvious candidate for the source is the music itself.
212
213 On paper this theory sounds very good. In practice, it opens a can of
214 worms. What really @emph{is} music? Many philosophical treatises must
215 have been written on the subject.  Instead of losing ourselves in
216 philosophical arguments over the essence of music, we have reversed
217 the question to yield a more practical approach. Our assumption is
218 that the printed score contains all of the music of piece. We build a
219 program that uses some input format to produce such a score. Over the
220 course of time, the program evolves. While this happens, we can remove
221 more and more elements of the input format: as the program improves,
222 it can fill in irrelevant details of the input by itself. At some
223 (hypothetical) point, the program is finished: there is no possibility
224 to remove any more elements from the syntax.  What we have left is by
225 definition exactly the musical meaning of the score.
226
227 There are also more practical concerns.  Our users have to key in the
228 music into the file directly, so the input format should have a
229 friendly syntax. As programmers and scientists, we want a
230 clean formal definition. After all, producing music notation is a
231 difficult problem, and in the scientific world, problems can only be
232 solved if they are well-specified. Moreover, formally defined formats
233 are easier to write programs for.
234
235 These ideas shaped our music representation: it is a compact format
236 that can easily be typed by hand. It complex musical constructs from
237 simple entities like notes and rests, in much the same way that one
238 builds complex formulas from simple expressions such as numbers and
239 mathematical operators.
240
241 @node Example applications
242 @section Example applications
243
244 As programmers and hedonists we enjoy beauty in code, and code that
245 produces beautiful typeset music, but nevertheless this program can
246 applied to do useful things. In this section, we show a few small
247 examples of what is possible.
248
249 The simplest application, is printing just notes.
250
251 @lilypond[relative=1]
252   \time 2/4 c4 c g'4 g a4 a g2  
253 @end lilypond
254
255 To these notes, chord names and lyrics  may be added
256
257 @lilypond[raggedright]
258 \score { <
259   \context ChordNames \chords  { c2 c f2 c }
260   \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
261   \context Lyrics \lyrics  { twin kle twin kle lit tle star } > }
262 @end lilypond
263
264
265 [TODO: need piano and tab example]
266
267 The following example combines some more exotic uses of notation
268
269 @lilypondfile{screech-boink.ly}  
270
271
272
273 @node About this manual
274 @section About this manual
275
276 The manual is divided into the following chapters
277 @itemize @bullet
278 @item The @emph{tutorial}
279 (@ref{Tutorial}) gives a  gentle introduction into typesetting music.
280 First time users should start here. 
281 @item The @emph{notation manual} (@ref{Notation manual}),
282 is a user manual that discusses topics grouped by notation construct.
283 @item The @emph{technical manual} (@ref{Advanced topics})
284 discusses the general design of the program, and how to extend the
285 functionality.
286 @item The chapter
287 on @emph{Invoking} (@ref{Invoking LilyPond}) explains how to run LilyPond and its helper
288 programs.
289 @end itemize
290
291 Once you are experienced, you can simply use the manual as reference:
292 there is an extensive index@footnote{If you are looking for something,
293 and you cannot find it by using the index, that is considered a bug.
294 In that case, please file a bug report}, but the document is also
295 available in
296 @ifnothtml
297 One Big Page,
298 @end ifnothtml 
299 @ifhtml
300 @uref{One Big Page,../lilypond.html}
301 @end ifhtml
302 which is is available for text search using your browser's search
303 facility.
304 @cindex search in manual
305 @cindex using the manual
306
307
308 If you are familiar with music notation, and music terminology
309 (especially if you are a foreigner), then it is advisable to consult
310 the glossary as well. This documents explains many terms, and includes
311 translations to various languages. It is a 
312 @ifhtml
313 @uref{../glossary.html,separate document}
314 @end ifhtml
315 @ifnothtml
316 separate document, and can be printed as well.
317 @end ifnothtml
318 @cindex idiom
319 @cindex jargon
320 @cindex terminology
321 @cindex foreign languages
322 @cindex language
323
324
325 This manual is not complete without a number of other documents. They
326 are not available in print, but should be included with the
327 documentation package for your platform
328
329 @itemize @bullet
330 @item
331 Generated internal documentation.
332 @ifhtml
333 available @uref{../lilypond-internals/lilypond-internals.html,here}
334 @end ifhtml
335
336 Almost all formatting functionality that is used internally, is
337 available directly to the user. For example, all variables that
338 control thicknesses, distances, etc, can be changed in input
339 files. There are a huge number of formatting options, and it would be
340 impossible to describe them all in a hand-written manual. The
341 generated internal documentation is a heavily crosslinked HTML
342 document, produced directly from the formatting definitions used.  It
343 documents the nit-gritty details of each and every LilyPond class, object and
344 function.
345
346 Each section of the reference manual has a @b{See also}
347 subsection, with links (in the HTML document, at least) to the
348 generated documentation.
349
350 @item
351   Templates
352 @ifhtml
353 (available @uref{../../../input/templates/out-www/collated-files.html,here})
354 @end ifhtml
355
356   When you have gone through the tutorial, you theoretically should be
357 able to start writing input files. However, this turns out to be a
358 little intimidating.  To give you a headstart, we have collected a
359 number of often-used formats in example files.  You can take one of
360 these example files, and add notes in the appropriate places to
361 generate output.
362
363 @item
364   Various input examples
365 @ifhtml
366 available @uref{../../../input/test/out-www/collated-files.html,here}
367 @end ifhtml
368 @cindex snippets
369
370 These small files show various applications of lilypond, and are
371 available as a big HTML document, with pictures and explanatory texts
372 included.
373
374
375 @item
376   The regression test
377 @ifhtml
378 available @uref{../../../input/regression/out-www/collated-files.html,here}
379 @end ifhtml
380
381 We strive to test each feature in one test file. This collection of is
382 primarily to help us debug problems, but it can be instructive to see
383 how we excercise the program. The format is like the input examples.
384
385 @end itemize
386
387 The location of the documentation files that are mentioned here can
388 vary from system to system. Throughout this manual, we refer to input
389 files relative to the top-directory of the source archive. For
390 example, @file{input/test/bla.ly} may refer to the file
391 @file{lilypond-1.7.19/input/test/bla.ly}.  On binary packages for the
392 Unix platform, these can typically be found somewhere below
393 @file{/usr/share/doc/lilypond/}. Initialization files, for example
394 @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are usually found
395 in the directory @file{/usr/share/lilypond/}.
396
397 @cindex adjusting output
398 @cindex variables
399 @cindex properties
400 @cindex lilypond-internals
401 @cindex internal documentation
402 @cindex Scheme
403 @cindex extending lilypond
404 @cindex bugreport
405 @cindex index