1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
15 This chapter gives a basic introduction to working with LilyPond.
19 * How to write input files::
20 * How to read the manuals::
23 @node Compiling a file
24 @section Compiling a file
36 @subsection Entering input
40 @cindex example, first
41 @cindex case sensitive
43 @qq{Compiling} is the term used for processing an input file
44 in LilyPond format to produce a file which can be printed and
45 (optionally) a MIDI file which can be played. LilyPond input
46 files are simple text files. The first example
47 shows what a simple input file looks like.
49 To create sheet music, we write an input file that specifies the
50 notation. For example, if we write:
59 the result looks like this:
61 @c in this case we don't want verbatim
68 @warning{Notes and lyrics in LilyPond input must always be
69 surrounded by @strong{@{ curly braces @}}. The braces
70 should also be surrounded by a space unless they are at the
71 beginning or end of a line to avoid ambiguities. The braces may
72 be omitted in some examples in this manual, but don't forget them
73 in your own music! For more information about the display of
74 examples in the manual, see @ref{How to read the manuals}.}
76 In addition, LilyPond input is @strong{case sensitive}.
77 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
78 produce an error message.
82 @subheading Entering music and viewing output
87 @cindex running LilyPond under MacOS X
88 @cindex MacOS X, running LilyPond
89 @cindex running LilyPond under Windows
90 @cindex Windows, running LilyPond
91 @cindex running LilyPond under Unix
92 @cindex Unix, running LilyPond
94 In this section we will explain what commands to run and how to
95 view or print the output.
97 Note that there are several other text editors available with
98 better support for LilyPond. For more information, see
99 @rgeneral{Alternate input}.
101 @warning{The first time you ever run LilyPond, it may take a
102 minute or two because all of the system fonts have to be analyzed
103 first. After this, LilyPond will be much faster!}
109 @warning{These instructions assume that you are using the built-in
110 LilyPad editor. If you are using any of the programs described in
111 @rgeneral{Alternate input}, please consult the documentation for
112 those programs if you have any problems compiling a file.}
115 If you double click @command{LilyPond.app}, it will open with an
116 example file. Save it, for example, to @file{test.ly} on your
117 Desktop, and then process it with the menu command
118 @w{@code{Compile > Typeset File}}. The resulting PDF file will be
119 displayed on your screen.
121 For future use of LilyPond, you should begin by selecting @q{New}
122 or @q{Open}. You must save your file before typesetting it. If
123 any errors occur in processing, please see the log window.
129 @warning{These instructions assume that you are using the built-in
130 LilyPad editor. If you are using any of the programs described in
131 @rgeneral{Alternate input}, please consult the documentation for
132 programs if you have any problems compiling a file.}
134 On Windows, if you double-click in the LilyPond icon on the
135 Desktop, it will open a simple text editor with an example file.
136 Save it, for example, to @file{test.ly} on your Desktop and then
137 double-click on the file to process it (the file icon looks like a
138 note). After some seconds, you will get a file @file{test.pdf} on
139 your desktop. Double-click on this PDF file to view the typeset
140 score. An alternative method to process the @file{test.ly} file
141 is to drag and drop it onto the LilyPond icon using your mouse
144 To edit an existing @file{.ly} file, right-click on it and
145 select @qq{Edit source}. To get an empty file to start from, run
146 the editor as described above and use @qq{New} in
147 the @qq{File} menu, or right-click on the desktop and select
148 @qq{New..Text Document}, change its name to a name of your choice
149 and change the file extension to @code{.ly}. Double-click the
150 icon to type in your LilyPond source code as before.
152 Double-clicking the file does not only result in a PDF file, but
153 also produces a @file{.log} file that contains some information on
154 what LilyPond has done to the file. If any errors occur, please
159 @subsection Command-line
161 @warning{These instructions assume that you are using the built-in
162 LilyPad editor. If you are using any of the programs described in
163 @rgeneral{Alternate input}, please consult the documentation for
164 programs if you have any problems compiling a file.}
167 Create a text file called @file{test.ly} and enter:
175 To process @file{test.ly}, proceed as follows:
182 You will see something resembling:
186 GNU LilyPond @version{}
189 Interpreting music...
190 Preprocessing graphical objects...
191 Finding the ideal number of pages...
192 Fitting music on 1 page...
194 Layout output to `test.ps'...
195 Converting to `test.pdf'...
200 @node How to write input files
201 @section How to write input files
207 * Working on input files::
211 @node Simple notation
212 @subsection Simple notation
214 @cindex simple notation
215 @cindex notation, simple
217 LilyPond will add some notation elements automatically. In the
218 next example, we have only specified four pitches, but LilyPond
219 has added a clef, time signature, and rhythms.
221 @lilypond[verbatim,quote]
228 This behavior may be altered, but in most cases these automatic
235 @cindex relative mode
236 @cindex quote, single
238 @cindex accidentals and relative mode
239 @cindex relative mode, and accidentals
246 Music Glossary: @rglos{pitch}, @rglos{interval},
247 @rglos{scale}, @rglos{middle C}, @rglos{octave},
250 The easiest way to enter notes is by using @code{\relative} mode.
251 In this mode, the octave is chosen automatically by assuming the
252 following note is always to be placed closest to the previous
253 note, i.e., it is to be placed in the octave which is within three
254 staff spaces of the previous note. We begin by entering the most
255 elementary piece of music, a @notation{scale}, in which every note
256 is within just one staff space of the previous note.
258 @lilypond[verbatim,quote]
259 % set the starting point to middle C
266 The initial note is @notation{middle C}. Each successive note is
267 placed closest to the previous note -- in other words, the first
268 @code{c} is the closest C to middle C. This is followed by the
269 closest D to the previous note. We can create melodies which have
270 larger intervals, still using only @code{\relative} mode:
272 @lilypond[verbatim,quote]
280 It is not necessary for the first note of the melody to start on
281 the note which specifies the starting pitch. In the previous
282 example, the first note -- the @code{d} -- is the closest D to
285 By adding (or removing) quotes @code{'} or commas @code{,} from
286 the @code{@w{\relative c' @{}} command, we can change the starting
289 @lilypond[verbatim,quote]
290 % one octave above middle C
296 Relative mode can be confusing initially, but is the easiest way
297 to enter most melodies. Let us see how this relative calculation
298 works in practice. Starting from a B, which is on the middle line
299 in a treble clef, you can reach a C, D and E within 3 staff spaces
300 going up, and an A, G and F within 3 staff spaces going down. So
301 if the note following a B is a C, D or E it will be assumed to be
302 above the B, and an A, G or F will be assumed to be below.
304 @lilypond[verbatim,quote]
306 b c % c is 1 staff space up, so is the c above
307 b d % d is 2 up or 5 down, so is the d above
308 b e % e is 3 up or 4 down, so is the e above
309 b a % a is 6 up or 1 down, so is the a below
310 b g % g is 5 up or 2 down, so is the g below
311 b f % f is 4 up or 3 down, so is the f below
315 Exactly the same happens even when any of these notes are
316 sharpened or flattened. @notation{Accidentals} are
317 @strong{totally ignored} in the calculation of relative position.
318 Precisely the same staff space counting is done from a note at any
319 other position on the staff.
321 To add intervals that are larger than three staff spaces, we can
322 raise the @notation{octave} by adding a single quote @code{'} (or
323 apostrophe) to the note name. We can lower the octave by adding a
324 comma @code{,} to the note name.
326 @lilypond[verbatim,quote]
334 To change a note by two (or more!) octaves, we use multiple
335 @code{''} or @code{,,} -- but be careful that you use two single
336 quotes @code{''} and not one double quote @code{"}@tie{}! The
337 initial value in @code{@w{\relative c'}} may also be modified like
339 @c " - keeps quotes in order for context-sensitive editor -td
341 @subheading Durations (rhythms)
343 @cindex note durations
350 @cindex notating durations
352 Music Glossary: @rglos{beam}, @rglos{duration},
353 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
356 The @notation{duration} of a note is specified by a number after
357 the note name: @code{1} for a @notation{whole note}, @code{2} for
358 a @notation{half note}, @code{4} for a @notation{quarter note} and
359 so on. @notation{Beams} are added automatically.
361 If you do not specify a duration, the previous duration is used
362 for the next note. The duration of the first note defaults to a
365 @lilypond[verbatim,quote]
369 a16 a a a a32 a a a a64 a a a a a a a a2
373 To create @notation{dotted notes}, add a dot @code{.} to the
374 duration number. The duration of a dotted note must be stated
375 explicitly (i.e., with a number).
377 @lilypond[verbatim,quote]
388 @cindex notating rests
390 Music Glossary: @rglos{rest}.
392 A @notation{rest} is entered just like a note with the name
395 @lilypond[verbatim,quote]
403 @subheading Time signature
405 @cindex time signature
410 Music Glossary: @rglos{time signature}.
412 The @notation{time signature} can be set with the @code{\time}
415 @lilypond[verbatim,quote]
438 Music Glossary: @rglos{clef}.
440 The @notation{clef} can be set using the @code{\clef} command:
442 @lilypond[verbatim,quote]
456 @subheading All together
458 Here is a small example showing all these elements together:
460 @lilypond[verbatim,quote]
471 Notation Reference: @ruser{Writing pitches},
472 @ruser{Writing rhythms}, @ruser{Writing rests},
473 @ruser{Time signature}, @ruser{Clef}.
476 @node Working on input files
477 @subsection Working on input files
480 @cindex braces, curly
483 @cindex comment, line
484 @cindex block comment
485 @cindex comment, line
486 @cindex case sensitive
487 @cindex whitespace insensitive
492 @funindex %@{ ... %@}
494 LilyPond input files are similar to source files in many common
495 programming languages. They are case sensitive, and white-space
496 is generally ignored. Expressions are formed with curly braces
497 @{ @}, and comments are denoted with @code{%} or
498 @w{@code{%@{ ... %@}}}.
500 If the previous sentences sound like nonsense, don't worry! We'll
501 explain what all these terms mean:
506 @strong{Case sensitive}:
507 it matters whether you enter a letter in lower case (e.g.
508 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
509 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
510 @w{@code{@{ C D E @}}} will produce an error message.
513 @strong{Whitespace insensitive}:
514 it does not matter how many spaces (or tabs or new lines) you add.
515 @w{@code{@{ c d e @}}} means the same thing as
516 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
524 Of course, the previous example is hard to read. A good rule of
525 thumb is to indent code blocks with either a tab or two spaces:
533 However, whitespace @emph{is} required to separate many syntactical
534 elements from others. In other words, whitespace can always be
535 @emph{added}, but it cannot be @emph{eliminated}. As missing
536 whitespace can give rise to strange errors it is advisable to
537 always insert whitespace before and after every syntactic element,
538 for example, before and after every curly brace.
541 @strong{Expressions}:
542 every piece of LilyPond input needs to have @strong{@{ curly
543 braces @}} placed around the input. These braces tell LilyPond
544 that the input is a single music expression, just like parentheses
545 @code{()} in mathematics. The braces should be surrounded by a
546 space unless they are at the beginning or end of a line to avoid
549 A LilyPond command followed by a simple expression in braces (such
550 as @w{@code{\relative @{ @}}}) also counts as a single music
555 @cindex block comment
558 a comment is a remark for the human reader of the music input; it
559 is ignored while parsing, so it has no effect on the printed
560 output. There are two types of comments. The percent symbol
561 @code{%} introduces a line comment; anything after @code{%} on
562 that line is ignored. By convention, a line comment is placed
563 @emph{above} the code it refers to.
567 % this comment refers to the Bs
571 A block comment marks a whole section of music input as a comment.
572 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
573 However, block comments do not @q{nest}. This means that you
574 cannot place a block comment inside another block comment. If you
575 try, the first @code{%@}} will terminate @emph{both} block
576 comments. The following fragment shows possible uses for
580 % notes for twinkle twinkle follow
584 This line, and the notes below are ignored,
585 since they are in a block comment.
594 @node How to read the manuals
595 @section How to read the manuals
601 * Clickable examples::
602 * Keyboard navigation::
603 * Overview of manuals::
607 @node Omitting braces
608 @unnumberedsubsec Omitting braces
611 @cindex how to read the manual
612 @cindex manual, reading
613 @cindex reading the manual
614 @cindex examples, clickable
615 @cindex clickable examples
616 @cindex tips for constructing files
618 @cindex constructing files, tips
619 @cindex files, tips for constructing
621 LilyPond input must be surrounded by @{ @} marks or a
622 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
623 input files}. For the rest of this manual, most examples will
624 omit this. To replicate the examples, you may copy and paste the
625 displayed input, but you @strong{must} add the
626 @code{@w{\relative c'' @{ @}}} like this:
630 ... example goes here...
634 Why omit the braces? Most examples in this manual can be inserted
635 into the middle of a longer piece of music. For these examples,
636 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
637 you should not place a @code{\relative} inside another
638 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
639 around every example, you would not be able to copy a small
640 documentation example and paste it inside a longer piece of your
641 own. Most people want to add material to an existing piece, so we
642 format the manual this way.
645 @node Clickable examples
646 @unnumberedsubsec Clickable examples
648 Many people learn programs by trying and fiddling around with the
649 program. This is also possible with LilyPond. If you click on a
650 picture in the HTML version of this manual, you will see the exact
651 LilyPond input that was used to generate that image. Try it on
657 c-\markup { \bold \huge { Click here. } }
661 By cutting and pasting everything in the @qq{ly snippet} section,
662 you have a starting template for experiments. To see exactly the
663 same output (line-width and all), copy everything from @qq{Start
664 cut-&-pastable section} to the bottom of the file.
667 @node Keyboard navigation
668 @unnumberedsubsec Keyboard navigation
672 @node Overview of manuals
673 @unnumberedsubsec Overview of manuals
675 FIXME: a brief discussion about the rest of the LM, and pointers
676 to specific places. like NR for general reference, AU for
677 suggestions for writing files, etc.