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 @w{@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.
83 @subheading Viewing output
85 @c TODO: move index entries
89 @cindex running LilyPond under MacOS X
90 @cindex MacOS X, running LilyPond
91 @cindex running LilyPond under Windows
92 @cindex Windows, running LilyPond
93 @cindex running LilyPond under Unix
94 @cindex Unix, running LilyPond
96 Producing output depends on your operating system and the
102 @ref{MacOS X, @sourceimage{logo-macosx,,,}}
103 @ref{MacOS X, MacOS X} (graphical)
106 @ref{Windows, @sourceimage{logo-windows,,,}}
107 @ref{Windows, Microsoft Windows} (graphical)
110 @ref{Command-line, @sourceimage{logo-linux,,,}
111 @sourceimage{logo-freebsd,,,}
112 @sourceimage{logo-macosx,,,}
113 @sourceimage{logo-windows,,,}
115 @ref{Command-line, All operating systems} (command-line)
119 There are several other text editors available with better support
120 for LilyPond. For more information, see
121 @rgeneral{Alternate input}.
123 @warning{The first time you ever run LilyPond, it may take a
124 minute or two because all of the system fonts have to be analyzed
125 first. After this, LilyPond will be much faster!}
131 @warning{These instructions assume that you are using the built-in
132 LilyPad editor. If you are using any of the programs described in
133 @rgeneral{Alternate input}, please consult the documentation for
134 those programs if you have any problems compiling a file.}
137 If you double click @command{LilyPond.app}, it will open with an
138 example file. Save it, for example, to @file{test.ly} on your
139 Desktop, and then process it with the menu command
140 @w{@code{Compile > Typeset File}}. The resulting PDF file will be
141 displayed on your screen.
143 For future use of LilyPond, you should begin by selecting @q{New}
144 or @q{Open}. You must save your file before typesetting it. If
145 any errors occur in processing, please see the log window.
147 @c FIXME: add screenshots
152 @warning{These instructions assume that you are using the built-in
153 LilyPad editor. If you are using any of the programs described in
154 @rgeneral{Alternate input}, please consult the documentation for
155 those programs if you have any problems compiling a file.}
157 On Windows, if you double-click in the LilyPond icon on the
158 Desktop, it will open a simple text editor with an example file.
159 Save it, for example, to @file{test.ly} on your Desktop and then
160 double-click on the file to process it (the file icon looks like a
161 note). After some seconds, you will get a file @file{test.pdf} on
162 your desktop. Double-click on this PDF file to view the typeset
163 score. An alternative method to process the @file{test.ly} file
164 is to drag and drop it onto the LilyPond icon using your mouse
167 To edit an existing @file{.ly} file, right-click on it and
168 select @qq{Edit source}. To get an empty file to start from, run
169 the editor as described above and use @qq{New} in
170 the @qq{File} menu, or right-click on the desktop and select
171 @qq{New..Text Document}, change its name to a name of your choice
172 and change the file extension to @code{.ly}. Double-click the
173 icon to type in your LilyPond source code as before.
175 Double-clicking the file does not only result in a PDF file, but
176 also produces a @file{.log} file that contains some information on
177 what LilyPond has done to the file. If any errors occur, please
180 @c FIXME: add screenshots
184 @subsection Command-line
186 @warning{These instructions assume that you are using commond unix
187 command-line programs. If you are using any of the programs
188 described in @rgeneral{Alternate input}, please consult the
189 documentation for those programs if you have any problems
193 Create a text file called @file{test.ly} and enter:
201 To process @file{test.ly}, proceed as follows:
208 You will see something resembling:
212 GNU LilyPond @version{}
215 Interpreting music...
216 Preprocessing graphical objects...
217 Finding the ideal number of pages...
218 Fitting music on 1 page...
220 Layout output to `test.ps'...
221 Converting to `test.pdf'...
224 You may view or print the resulting @file{text.pdf}.
227 @node How to write input files
228 @section How to write input files
234 * Working on input files::
238 @node Simple notation
239 @subsection Simple notation
241 @cindex simple notation
242 @cindex notation, simple
244 LilyPond will add some notation elements automatically. In the
245 next example, we have only specified four pitches, but LilyPond
246 has added a clef, time signature, and rhythms.
248 @lilypond[verbatim,quote]
255 This behavior may be altered, but in most cases these automatic
262 @cindex relative mode
263 @cindex quote, single
265 @cindex accidentals and relative mode
266 @cindex relative mode, and accidentals
273 Music Glossary: @rglos{pitch}, @rglos{interval},
274 @rglos{scale}, @rglos{middle C}, @rglos{octave},
277 The easiest way to enter notes is by using @code{\relative} mode.
278 In this mode, the octave is chosen automatically by assuming the
279 following note is always to be placed closest to the previous
280 note, i.e., it is to be placed in the octave which is within three
281 staff spaces of the previous note. We begin by entering the most
282 elementary piece of music, a @notation{scale}, in which every note
283 is within just one staff space of the previous note.
285 @lilypond[verbatim,quote]
286 % set the starting point to middle C
293 The initial note is @notation{middle C}. Each successive note is
294 placed closest to the previous note -- in other words, the first
295 @code{c} is the closest C to middle C. This is followed by the
296 closest D to the previous note. We can create melodies which have
297 larger intervals, still using only @code{\relative} mode:
299 @lilypond[verbatim,quote]
307 It is not necessary for the first note of the melody to start on
308 the note which specifies the starting pitch. In the previous
309 example, the first note -- the @code{d} -- is the closest D to
312 By adding (or removing) quotes @code{'} or commas @code{,} from
313 the @code{@w{\relative c' @{}} command, we can change the starting
316 @lilypond[verbatim,quote]
317 % one octave above middle C
323 Relative mode can be confusing initially, but is the easiest way
324 to enter most melodies. Let us see how this relative calculation
325 works in practice. Starting from a B, which is on the middle line
326 in a treble clef, you can reach a C, D and E within 3 staff spaces
327 going up, and an A, G and F within 3 staff spaces going down. So
328 if the note following a B is a C, D or E it will be assumed to be
329 above the B, and an A, G or F will be assumed to be below.
331 @lilypond[verbatim,quote]
333 b c % c is 1 staff space up, so is the c above
334 b d % d is 2 up or 5 down, so is the d above
335 b e % e is 3 up or 4 down, so is the e above
336 b a % a is 6 up or 1 down, so is the a below
337 b g % g is 5 up or 2 down, so is the g below
338 b f % f is 4 up or 3 down, so is the f below
342 Exactly the same happens even when any of these notes are
343 sharpened or flattened. @notation{Accidentals} are
344 @strong{totally ignored} in the calculation of relative position.
345 Precisely the same staff space counting is done from a note at any
346 other position on the staff.
348 To add intervals that are larger than three staff spaces, we can
349 raise the @notation{octave} by adding a single quote @code{'} (or
350 apostrophe) to the note name. We can lower the octave by adding a
351 comma @code{,} to the note name.
353 @lilypond[verbatim,quote]
361 To change a note by two (or more!) octaves, we use multiple
362 @code{''} or @code{,,} -- but be careful that you use two single
363 quotes @code{''} and not one double quote @code{"}@tie{}! The
364 initial value in @code{@w{\relative c'}} may also be modified like
366 @c " - keeps quotes in order for context-sensitive editor -td
368 @subheading Durations (rhythms)
370 @cindex note durations
377 @cindex notating durations
379 Music Glossary: @rglos{beam}, @rglos{duration},
380 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
383 The @notation{duration} of a note is specified by a number after
384 the note name: @code{1} for a @notation{whole note}, @code{2} for
385 a @notation{half note}, @code{4} for a @notation{quarter note} and
386 so on. @notation{Beams} are added automatically.
388 If you do not specify a duration, the previous duration is used
389 for the next note. The duration of the first note defaults to a
392 @lilypond[verbatim,quote]
396 a16 a a a a32 a a a a64 a a a a a a a a2
400 To create @notation{dotted notes}, add a dot @code{.} to the
401 duration number. The duration of a dotted note must be stated
402 explicitly (i.e., with a number).
404 @lilypond[verbatim,quote]
415 @cindex notating rests
417 Music Glossary: @rglos{rest}.
419 A @notation{rest} is entered just like a note with the name
422 @lilypond[verbatim,quote]
430 @subheading Time signature
432 @cindex time signature
437 Music Glossary: @rglos{time signature}.
439 The @notation{time signature} can be set with the @code{\time}
442 @lilypond[verbatim,quote]
465 Music Glossary: @rglos{clef}.
467 The @notation{clef} can be set using the @code{\clef} command:
469 @lilypond[verbatim,quote]
483 @subheading All together
485 Here is a small example showing all these elements together:
487 @lilypond[verbatim,quote]
498 Notation Reference: @ruser{Writing pitches},
499 @ruser{Writing rhythms}, @ruser{Writing rests},
500 @ruser{Time signature}, @ruser{Clef}.
503 @node Working on input files
504 @subsection Working on input files
507 @cindex braces, curly
510 @cindex comment, line
511 @cindex block comment
512 @cindex comment, line
513 @cindex case sensitive
514 @cindex whitespace insensitive
519 @funindex %@{ ... %@}
521 LilyPond input files are similar to source files in many common
522 programming languages. They are case sensitive, and white-space
523 is generally ignored. Expressions are formed with curly braces
524 @{ @}, and comments are denoted with @code{%} or
525 @w{@code{%@{ ... %@}}}.
527 If the previous sentences sound like nonsense, don't worry! We'll
528 explain what all these terms mean:
533 @strong{Case sensitive}:
534 it matters whether you enter a letter in lower case (e.g.
535 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
536 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
537 @w{@code{@{ C D E @}}} will produce an error message.
540 @strong{Whitespace insensitive}:
541 it does not matter how many spaces (or tabs or new lines) you add.
542 @w{@code{@{ c d e @}}} means the same thing as
543 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
551 Of course, the previous example is hard to read. A good rule of
552 thumb is to indent code blocks with either a tab or two spaces:
560 However, whitespace @emph{is} required to separate many syntactical
561 elements from others. In other words, whitespace can always be
562 @emph{added}, but it cannot be @emph{eliminated}. As missing
563 whitespace can give rise to strange errors it is advisable to
564 always insert whitespace before and after every syntactic element,
565 for example, before and after every curly brace.
568 @strong{Expressions}:
569 every piece of LilyPond input needs to have @strong{@{ curly
570 braces @}} placed around the input. These braces tell LilyPond
571 that the input is a single music expression, just like parentheses
572 @code{()} in mathematics. The braces should be surrounded by a
573 space unless they are at the beginning or end of a line to avoid
576 A LilyPond command followed by a simple expression in braces (such
577 as @w{@code{\relative @{ @}}}) also counts as a single music
582 @cindex block comment
585 a comment is a remark for the human reader of the music input; it
586 is ignored while parsing, so it has no effect on the printed
587 output. There are two types of comments. The percent symbol
588 @code{%} introduces a line comment; anything after @code{%} on
589 that line is ignored. By convention, a line comment is placed
590 @emph{above} the code it refers to.
594 % this comment refers to the Bs
598 A block comment marks a whole section of music input as a comment.
599 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
600 However, block comments do not @q{nest}. This means that you
601 cannot place a block comment inside another block comment. If you
602 try, the first @code{%@}} will terminate @emph{both} block
603 comments. The following fragment shows possible uses for
607 % notes for twinkle twinkle follow
611 This line, and the notes below are ignored,
612 since they are in a block comment.
621 @node How to read the manuals
622 @section How to read the manuals
628 * Clickable examples::
629 * Keyboard navigation::
630 * Overview of manuals::
634 @node Omitting braces
635 @subsection Omitting braces
638 @cindex how to read the manual
639 @cindex manual, reading
640 @cindex reading the manual
641 @cindex examples, clickable
642 @cindex clickable examples
643 @cindex tips for constructing files
645 @cindex constructing files, tips
646 @cindex files, tips for constructing
648 LilyPond input must be surrounded by @{ @} marks or a
649 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
650 input files}. For the rest of this manual, most examples will
651 omit this. To replicate the examples, you may copy and paste the
652 displayed input, but you @strong{must} add the
653 @code{@w{\relative c'' @{ @}}} like this:
657 ... example goes here...
661 Why omit the braces? Most examples in this manual can be inserted
662 into the middle of a longer piece of music. For these examples,
663 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
664 you should not place a @code{\relative} inside another
665 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
666 around every example, you would not be able to copy a small
667 documentation example and paste it inside a longer piece of your
668 own. Most people want to add material to an existing piece, so we
669 format the manual this way.
672 @node Clickable examples
673 @subsection Clickable examples
675 @warning{This features is only available in the HTML manuals.}
677 Many people learn programs by trying and fiddling around with the
678 program. This is also possible with LilyPond. If you click on a
679 picture in the HTML version of this manual, you will see the exact
680 LilyPond input that was used to generate that image. Try it on
686 c-\markup { \bold \huge { Click here. } }
690 By cutting and pasting everything in the @qq{ly snippet} section,
691 you have a starting template for experiments. To see exactly the
692 same output (line-width and all), copy everything from @qq{Start
693 cut-&-pastable section} to the bottom of the file.
696 @node Keyboard navigation
697 @subsection Keyboard navigation
699 @warning{This features is only available in the HTML manuals.}
701 @c TODO: once this is figured out, insert it here.
703 We are currently working on this feature.
706 @node Overview of manuals
707 @subsection Overview of manuals
709 There is a lot of documentation for LilyPond. New users are
710 sometimes confused about what part(s) they should read, and
711 occasionally skip over reading vital portions.
713 @warning{Please do not skip over important parts of the
714 documentation. You will find it much harder to understand later
720 @strong{Before trying to do @emph{anything}}: read the Learning
721 manual's @ref{Introduction}, and @ref{Common notation}. If you
722 encounter musical terms which you do not recognize, please look
723 them up in the @rglosnamed{Top, Glossary}.
726 @strong{Before trying to write a complete piece of music}: read
727 the Learning manual's @ref{Fundamental concepts}. After that, you
728 may want to look in relevant sections of the
729 @rusernamed{Top, Notation reference}.
732 @strong{Before trying to change the default output}: read the
733 Learning manual's @ref{Tweaking output}.
736 @strong{Before undertaking a large project}: read Usage document's
737 @rprogram{Suggestions for writing files}.