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.
20 * How to write input files::
21 * How to read the manuals::
24 @node Compiling a file
25 @section Compiling a file
37 @subsection Entering input
41 @cindex example, first
42 @cindex case sensitive
44 @qq{Compiling} is the term used for processing an input file
45 in LilyPond format to produce a file which can be printed and
46 (optionally) a MIDI file which can be played. LilyPond input
47 files are simple text files. The first example
48 shows what a simple input file looks like.
50 To create sheet music, we write an input file that specifies the
51 notation. For example, if we write:
60 the result looks like this:
62 @c in this case we don't want verbatim
69 @warning{Notes and lyrics in LilyPond input must always be
70 surrounded by @strong{@{ curly braces @}}. The braces
71 should also be surrounded by a space unless they are at the
72 beginning or end of a line to avoid ambiguities. The braces may
73 be omitted in some examples in this manual, but don't forget them
74 in your own music! For more information about the display of
75 examples in the manual, see @ref{How to read the manuals}.}
77 In addition, LilyPond input is @strong{case sensitive}.
78 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
79 produce an error message.
83 @subheading Entering music and viewing output
88 @cindex running LilyPond under MacOS X
89 @cindex MacOS X, running LilyPond
90 @cindex running LilyPond under Windows
91 @cindex Windows, running LilyPond
92 @cindex running LilyPond under Unix
93 @cindex Unix, running LilyPond
95 In this section we will explain what commands to run and how to
96 view or print the output.
98 Note that there are several other text editors available with
99 better support for LilyPond. For more information, see
100 @ref{Advanced editors}.
102 @warning{The first time you ever run LilyPond, it may take a
103 minute or two because all of the system fonts have to be analyzed
104 first. After this, LilyPond will be much faster!}
110 If you double click @command{LilyPond.app}, it will open with an
111 example file. Save it, for example, to @file{test.ly} on your
112 Desktop, and then process it with the menu command
113 @w{@code{Compile > Typeset File}}. The resulting PDF file will be
114 displayed on your screen.
116 For future use of LilyPond, you should begin by selecting @q{New}
117 or @q{Open}. You must save your file before typesetting it. If
118 any errors occur in processing, please see the log window.
124 On Windows, if you double-click in the LilyPond icon on the
125 Desktop, it will open a simple text editor with an example file.
126 Save it, for example, to @file{test.ly} on your Desktop and then
127 double-click on the file to process it (the file icon looks like a
128 note). After some seconds, you will get a file @file{test.pdf} on
129 your desktop. Double-click on this PDF file to view the typeset
130 score. An alternative method to process the @file{test.ly} file
131 is to drag and drop it onto the LilyPond icon using your mouse
134 To edit an existing @file{.ly} file, right-click on it and
135 select @qq{Edit source}. To get an empty file to start from, run
136 the editor as described above and use @qq{New} in
137 the @qq{File} menu, or right-click on the desktop and select
138 @qq{New..Text Document}, change its name to a name of your choice
139 and change the file extension to @code{.ly}. Double-click the
140 icon to type in your LilyPond source code as before.
142 Double-clicking the file does not only result in a PDF file, but
143 also produces a @file{.log} file that contains some information on
144 what LilyPond has done to the file. If any errors occur, please
149 @subsection Command-line
151 Create a text file called @file{test.ly} and enter:
159 To process @file{test.ly}, proceed as follows:
166 You will see something resembling:
170 GNU LilyPond @version{}
173 Interpreting music...
174 Preprocessing graphical objects...
175 Finding the ideal number of pages...
176 Fitting music on 1 page...
178 Layout output to `test.ps'...
179 Converting to `test.pdf'...
184 @node Advanced editors
185 @section Advanced editors
205 @subsection LilyPondTool
213 Available on: Windows, MacOS X, Unix
219 Available on: Windows, MacOS X, Unix
224 @node How to write input files
225 @section How to write input files
231 * Working on input files::
235 @node Simple notation
236 @subsection Simple notation
238 @cindex simple notation
239 @cindex notation, simple
241 LilyPond will add some notation elements automatically. In the
242 next example, we have only specified four pitches, but LilyPond
243 has added a clef, time signature, and rhythms.
245 @lilypond[verbatim,quote]
252 This behavior may be altered, but in most cases these automatic
259 @cindex relative mode
260 @cindex quote, single
262 @cindex accidentals and relative mode
263 @cindex relative mode, and accidentals
270 Music Glossary: @rglos{pitch}, @rglos{interval},
271 @rglos{scale}, @rglos{middle C}, @rglos{octave},
274 The easiest way to enter notes is by using @code{\relative} mode.
275 In this mode, the octave is chosen automatically by assuming the
276 following note is always to be placed closest to the previous
277 note, i.e., it is to be placed in the octave which is within three
278 staff spaces of the previous note. We begin by entering the most
279 elementary piece of music, a @notation{scale}, in which every note
280 is within just one staff space of the previous note.
282 @lilypond[verbatim,quote]
283 % set the starting point to middle C
290 The initial note is @notation{middle C}. Each successive note is
291 placed closest to the previous note -- in other words, the first
292 @code{c} is the closest C to middle C. This is followed by the
293 closest D to the previous note. We can create melodies which have
294 larger intervals, still using only @code{\relative} mode:
296 @lilypond[verbatim,quote]
304 It is not necessary for the first note of the melody to start on
305 the note which specifies the starting pitch. In the previous
306 example, the first note -- the @code{d} -- is the closest D to
309 By adding (or removing) quotes @code{'} or commas @code{,} from
310 the @code{@w{\relative c' @{}} command, we can change the starting
313 @lilypond[verbatim,quote]
314 % one octave above middle C
320 Relative mode can be confusing initially, but is the easiest way
321 to enter most melodies. Let us see how this relative calculation
322 works in practice. Starting from a B, which is on the middle line
323 in a treble clef, you can reach a C, D and E within 3 staff spaces
324 going up, and an A, G and F within 3 staff spaces going down. So
325 if the note following a B is a C, D or E it will be assumed to be
326 above the B, and an A, G or F will be assumed to be below.
328 @lilypond[verbatim,quote]
330 b c % c is 1 staff space up, so is the c above
331 b d % d is 2 up or 5 down, so is the d above
332 b e % e is 3 up or 4 down, so is the e above
333 b a % a is 6 up or 1 down, so is the a below
334 b g % g is 5 up or 2 down, so is the g below
335 b f % f is 4 up or 3 down, so is the f below
339 Exactly the same happens even when any of these notes are
340 sharpened or flattened. @notation{Accidentals} are
341 @strong{totally ignored} in the calculation of relative position.
342 Precisely the same staff space counting is done from a note at any
343 other position on the staff.
345 To add intervals that are larger than three staff spaces, we can
346 raise the @notation{octave} by adding a single quote @code{'} (or
347 apostrophe) to the note name. We can lower the octave by adding a
348 comma @code{,} to the note name.
350 @lilypond[verbatim,quote]
358 To change a note by two (or more!) octaves, we use multiple
359 @code{''} or @code{,,} -- but be careful that you use two single
360 quotes @code{''} and not one double quote @code{"}@tie{}! The
361 initial value in @code{@w{\relative c'}} may also be modified like
363 @c " - keeps quotes in order for context-sensitive editor -td
365 @subheading Durations (rhythms)
367 @cindex note durations
374 @cindex notating durations
376 Music Glossary: @rglos{beam}, @rglos{duration},
377 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
380 The @notation{duration} of a note is specified by a number after
381 the note name: @code{1} for a @notation{whole note}, @code{2} for
382 a @notation{half note}, @code{4} for a @notation{quarter note} and
383 so on. @notation{Beams} are added automatically.
385 If you do not specify a duration, the previous duration is used
386 for the next note. The duration of the first note defaults to a
389 @lilypond[verbatim,quote]
393 a16 a a a a32 a a a a64 a a a a a a a a2
397 To create @notation{dotted notes}, add a dot @code{.} to the
398 duration number. The duration of a dotted note must be stated
399 explicitly (i.e., with a number).
401 @lilypond[verbatim,quote]
412 @cindex notating rests
414 Music Glossary: @rglos{rest}.
416 A @notation{rest} is entered just like a note with the name
419 @lilypond[verbatim,quote]
427 @subheading Time signature
429 @cindex time signature
434 Music Glossary: @rglos{time signature}.
436 The @notation{time signature} can be set with the @code{\time}
439 @lilypond[verbatim,quote]
462 Music Glossary: @rglos{clef}.
464 The @notation{clef} can be set using the @code{\clef} command:
466 @lilypond[verbatim,quote]
480 @subheading All together
482 Here is a small example showing all these elements together:
484 @lilypond[verbatim,quote]
495 Notation Reference: @ruser{Writing pitches},
496 @ruser{Writing rhythms}, @ruser{Writing rests},
497 @ruser{Time signature}, @ruser{Clef}.
500 @node Working on input files
501 @subsection Working on input files
504 @cindex braces, curly
507 @cindex comment, line
508 @cindex block comment
509 @cindex comment, line
510 @cindex case sensitive
511 @cindex whitespace insensitive
516 @funindex %@{ ... %@}
518 LilyPond input files are similar to source files in many common
519 programming languages. They are case sensitive, and white-space
520 is generally ignored. Expressions are formed with curly braces
521 @{ @}, and comments are denoted with @code{%} or
522 @w{@code{%@{ ... %@}}}.
524 If the previous sentences sound like nonsense, don't worry! We'll
525 explain what all these terms mean:
530 @strong{Case sensitive}:
531 it matters whether you enter a letter in lower case (e.g.
532 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
533 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
534 @w{@code{@{ C D E @}}} will produce an error message.
537 @strong{Whitespace insensitive}:
538 it does not matter how many spaces (or tabs or new lines) you add.
539 @w{@code{@{ c d e @}}} means the same thing as
540 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
548 Of course, the previous example is hard to read. A good rule of
549 thumb is to indent code blocks with either a tab or two spaces:
557 However, whitespace @emph{is} required to separate many syntactical
558 elements from others. In other words, whitespace can always be
559 @emph{added}, but it cannot be @emph{eliminated}. As missing
560 whitespace can give rise to strange errors it is advisable to
561 always insert whitespace before and after every syntactic element,
562 for example, before and after every curly brace.
565 @strong{Expressions}:
566 every piece of LilyPond input needs to have @strong{@{ curly
567 braces @}} placed around the input. These braces tell LilyPond
568 that the input is a single music expression, just like parentheses
569 @code{()} in mathematics. The braces should be surrounded by a
570 space unless they are at the beginning or end of a line to avoid
573 A LilyPond command followed by a simple expression in braces (such
574 as @w{@code{\relative @{ @}}}) also counts as a single music
579 @cindex block comment
582 a comment is a remark for the human reader of the music input; it
583 is ignored while parsing, so it has no effect on the printed
584 output. There are two types of comments. The percent symbol
585 @code{%} introduces a line comment; anything after @code{%} on
586 that line is ignored. By convention, a line comment is placed
587 @emph{above} the code it refers to.
591 % this comment refers to the Bs
595 A block comment marks a whole section of music input as a comment.
596 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
597 However, block comments do not @q{nest}. This means that you
598 cannot place a block comment inside another block comment. If you
599 try, the first @code{%@}} will terminate @emph{both} block
600 comments. The following fragment shows possible uses for
604 % notes for twinkle twinkle follow
608 This line, and the notes below are ignored,
609 since they are in a block comment.
618 @node How to read the manuals
619 @section How to read the manuals
625 * Clickable examples::
626 * Keyboard navigation::
627 * Overview of manuals::
631 @node Omitting braces
632 @unnumberedsubsec Omitting braces
635 @cindex how to read the manual
636 @cindex manual, reading
637 @cindex reading the manual
638 @cindex examples, clickable
639 @cindex clickable examples
640 @cindex tips for constructing files
642 @cindex constructing files, tips
643 @cindex files, tips for constructing
645 LilyPond input must be surrounded by @{ @} marks or a
646 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
647 input files}. For the rest of this manual, most examples will
648 omit this. To replicate the examples, you may copy and paste the
649 displayed input, but you @strong{must} add the
650 @code{@w{\relative c'' @{ @}}} like this:
654 ... example goes here...
658 Why omit the braces? Most examples in this manual can be inserted
659 into the middle of a longer piece of music. For these examples,
660 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
661 you should not place a @code{\relative} inside another
662 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
663 around every example, you would not be able to copy a small
664 documentation example and paste it inside a longer piece of your
665 own. Most people want to add material to an existing piece, so we
666 format the manual this way.
669 @node Clickable examples
670 @unnumberedsubsec Clickable examples
672 Many people learn programs by trying and fiddling around with the
673 program. This is also possible with LilyPond. If you click on a
674 picture in the HTML version of this manual, you will see the exact
675 LilyPond input that was used to generate that image. Try it on
681 c-\markup { \bold \huge { Click here. } }
685 By cutting and pasting everything in the @qq{ly snippet} section,
686 you have a starting template for experiments. To see exactly the
687 same output (line-width and all), copy everything from @qq{Start
688 cut-&-pastable section} to the bottom of the file.
691 @node Keyboard navigation
692 @unnumberedsubsec Keyboard navigation
696 @node Overview of manuals
697 @unnumberedsubsec Overview of manuals
699 FIXME: a brief discussion about the rest of the LM, and pointers
700 to specific places. like NR for general reference, AU for
701 suggestions for writing files, etc.