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. For details, see the Contributors'
8 Guide, node Updating translation committishes..
11 @include included/generating-output.itexi
18 This chapter gives a basic introduction to working with LilyPond.
22 * How to write input files::
23 * Dealing with errors::
24 * How to read the manuals::
27 @node Compiling a file
28 @section Compiling a file
30 This section introduces @qq{compiling}---the processing of
31 LilyPond input files (written by you) to produce output files.
41 @subsection Entering input
45 @cindex example, first
46 @cindex case sensitive
48 @qq{Compiling} is the term used for processing an input file in
49 LilyPond format to produce output file(s). Output files are
50 generally PDF (for printing or viewing), MIDI (for playing), and
51 PNG (for online use). LilyPond input files are simple text files.
53 This example shows a simple input file:
56 \version "@w{@version{}}"
62 The graphical output is:
64 @c in this case we don't want verbatim
71 @warning{Notes and lyrics in LilyPond input must always be
72 surrounded by @w{@strong{@{ curly braces @}}}. The braces
73 should also be surrounded by a space unless they are at the
74 beginning or end of a line to avoid ambiguities. They may
75 be omitted in some examples in this manual, but don't forget them
76 in your own music! For more information about the display of
77 examples in the manual, see @ref{How to read the manuals}.}
79 In addition, LilyPond input is @strong{case sensitive}.
80 @w{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}} will
81 produce an error message.
86 @subheading Producing output
92 The method of producing output depends on your operating system
93 and the program(s) you use.
98 @ref{MacOS X, @sourceimage{logo-macosx,,,}}
99 @ref{MacOS X, MacOS X} (graphical)
102 @ref{Windows, @sourceimage{logo-windows,,,}}
103 @ref{Windows, Microsoft Windows} (graphical)
106 @ref{Command-line, @sourceimage{logo-linux,,,}
107 @sourceimage{logo-freebsd,,,}
108 @sourceimage{logo-macosx,,,}
109 @sourceimage{logo-windows,,,}
111 @ref{Command-line, All operating systems} (command-line)
115 There are several other text editors available with specific
116 support for LilyPond. For more information, see
117 @rweb{Easier editing}.
119 @warning{The first time you ever run LilyPond, it may take a
120 minute or two because all of the system fonts have to be analyzed
121 first. After this, LilyPond will be much faster!}
127 @cindex running LilyPond under MacOS X
128 @cindex MacOS X, running LilyPond
136 @cindex running LilyPond under Windows
137 @cindex Windows, running LilyPond
143 @subsection Command-line
145 @cindex running LilyPond under Unix
146 @cindex Unix, running LilyPond
150 @node How to write input files
151 @section How to write input files
153 This section introduces some basic LilyPond syntax to help get you
154 started writing input files.
158 * Working on input files::
162 @node Simple notation
163 @subsection Simple notation
165 @cindex simple notation
166 @cindex notation, simple
168 LilyPond will add some notation elements automatically. In the
169 next example, we have only specified four pitches, but LilyPond
170 has added a clef, time signature, and rhythms.
172 @lilypond[verbatim,quote]
179 This behavior may be altered, but in most cases these automatic
186 @cindex relative mode
187 @cindex quote, single
189 @cindex accidentals and relative mode
190 @cindex relative mode, and accidentals
197 Music Glossary: @rglos{pitch}, @rglos{interval},
198 @rglos{scale}, @rglos{middle C}, @rglos{octave},
201 The easiest way to enter notes is by using @code{\relative} mode.
202 In this mode, the octave is chosen automatically by assuming the
203 following note is always to be placed closest to the previous
204 note, i.e., it is to be placed in the octave which is within three
205 staff spaces of the previous note. We begin by entering the most
206 elementary piece of music, a @notation{scale}, in which every note
207 is within just one staff space of the previous note.
209 @lilypond[verbatim,quote]
210 % set the starting point to middle C
217 The initial note is @notation{middle C}. Each successive note is
218 placed closest to the previous note -- in other words, the first
219 @code{c} is the closest C to middle C. This is followed by the
220 closest D to the previous note. We can create melodies which have
221 larger intervals, still using only @code{\relative} mode:
223 @lilypond[verbatim,quote]
231 It is not necessary for the first note of the melody to start on
232 the note which specifies the starting pitch. In the previous
233 example, the first note -- the @code{d} -- is the closest D to
236 By adding (or removing) quotes @code{'} or commas @code{,} from
237 the @q{@w{@code{@bs{}relative c'}}} command, we can change the
240 @lilypond[verbatim,quote]
241 % one octave above middle C
247 Relative mode can be confusing initially, but is the easiest way
248 to enter most melodies. Let us see how this relative calculation
249 works in practice. Starting from a B, which is on the middle line
250 in a treble clef, you can reach a C, D and E within 3 staff spaces
251 going up, and an A, G and F within 3 staff spaces going down. So
252 if the note following a B is a C, D or E it will be assumed to be
253 above the B, and an A, G or F will be assumed to be below.
255 @lilypond[verbatim,quote]
257 b c % c is 1 staff space up, so is the c above
258 b d % d is 2 up or 5 down, so is the d above
259 b e % e is 3 up or 4 down, so is the e above
260 b a % a is 6 up or 1 down, so is the a below
261 b g % g is 5 up or 2 down, so is the g below
262 b f % f is 4 up or 3 down, so is the f below
266 Exactly the same happens even when any of these notes are
267 sharpened or flattened. @notation{Accidentals} are
268 @strong{totally ignored} in the calculation of relative position.
269 Precisely the same staff space counting is done from a note at any
270 other position on the staff.
272 To add intervals that are larger than three staff spaces, we can
273 raise the @notation{octave} by adding a single quote @code{'} (or
274 apostrophe) to the note name. We can lower the octave by adding a
275 comma @code{,} to the note name.
277 @lilypond[verbatim,quote]
285 To change a note by two (or more!) octaves, we use multiple
286 @code{''} or @code{,,} -- but be careful that you use two single
287 quotes @code{''} and not one double quote @code{"}@tie{}!
288 @c " - keeps quotes in order for context-sensitive editor -td
290 @subheading Durations (rhythms)
292 @cindex note durations
299 @cindex notating durations
301 Music Glossary: @rglos{beam}, @rglos{duration},
302 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
305 The @notation{duration} of a note is specified by a number after
306 the note name: @code{1} for a @notation{whole note}, @code{2} for
307 a @notation{half note}, @code{4} for a @notation{quarter note} and
308 so on. @notation{Beams} are added automatically.
310 If you do not specify a duration, the previous duration is used
311 for the next note. The duration of the first note defaults to a
314 @lilypond[verbatim,quote]
318 a16 a a a a32 a a a a64 a a a a a a a a2
322 To create @notation{dotted notes}, add a dot @code{.} to the
323 duration number. The duration of a dotted note must be stated
324 explicitly (i.e., with a number).
326 @lilypond[verbatim,quote]
337 @cindex notating rests
339 Music Glossary: @rglos{rest}.
341 A @notation{rest} is entered just like a note with the name
344 @lilypond[verbatim,quote]
352 @subheading Time signature
354 @cindex time signature
359 Music Glossary: @rglos{time signature}.
361 The @notation{time signature} can be set with the @code{\time}
364 @lilypond[verbatim,quote]
375 @subheading Tempo marks
378 @cindex metronome marks
383 Music Glossary: @rglos{tempo indication}, @rglos{metronome}.
385 The @notation{tempo indication} and @notation{metronome mark} can be
386 set with the @code{\tempo} command:
388 @lilypond[verbatim,quote]
397 \tempo "Presto" 4 = 120
414 Music Glossary: @rglos{clef}.
416 The @notation{clef} can be set using the @code{\clef} command:
418 @lilypond[verbatim,quote]
432 @subheading All together
434 Here is a small example showing all these elements together:
436 @lilypond[verbatim,quote]
440 \tempo "Andante" 4 = 120
450 Notation Reference: @ruser{Writing pitches},
451 @ruser{Writing rhythms}, @ruser{Writing rests},
452 @ruser{Time signature}, @ruser{Clef}.
455 @node Working on input files
456 @subsection Working on input files
459 @cindex braces, curly
462 @cindex comment, line
463 @cindex block comment
464 @cindex comment, line
465 @cindex case sensitive
466 @cindex whitespace insensitive
470 @cindex version number
475 @funindex %@{ ... %@}
477 LilyPond input files are similar to source files in many common
478 programming languages. They contain a version statement, are case
479 sensitive, and white-space is generally ignored. Expressions are
480 formed with curly braces @w{@code{@{ @}}}, and comments are
481 denoted with @code{%} or @w{@code{%@{ @dots{} %@}}}@tie{}.
483 If the previous sentences sound like nonsense, don't worry! We'll
484 explain what all these terms mean:
489 @strong{Version statement}:
490 Every LilyPond file should contain a version statement. A version
491 statement is a line that describes the version of LilyPond for which
492 the file was written, as in the following example:
495 \version "@w{@version{}}"
498 By convention, the version statement is placed at the top of the
501 The version statement is important for at least two reasons. First,
502 it allows automatic updating of the input file as LilyPond syntax
503 changes. Second, it describes the version of LilyPond needed to
506 If the version statement is omitted from an input file, LilyPond will print
507 a warning during the compilation of the file.
510 @strong{Case sensitive}:
511 it matters whether you enter a letter in lower case (e.g.
512 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
513 Notes are lower case: @w{@samp{@{ c d e @}}} is valid input;
514 @w{@samp{@{ C D E @}}} will produce an error message.
517 @strong{Whitespace insensitive}:
518 it does not matter how many spaces (or tabs or new lines) you add.
519 @w{@samp{@{ c4 d e @}}} means the same thing as
520 @w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:
528 Of course, the previous example is hard to read. A good rule of
529 thumb is to indent code blocks with two spaces:
537 However, whitespace @emph{is} required to separate many
538 syntactical elements from others. In other words, whitespace can
539 always be @emph{added}, but not always @emph{eliminated}. Since
540 missing whitespace can give rise to strange errors, it is
541 advisable to always insert whitespace before and after every
542 syntactic element, for example, before and after every curly
546 @strong{Expressions}:
547 every piece of LilyPond input needs to have
548 @strong{@{@tie{}curly@tie{}braces@tie{}@}} placed around the
549 input. These braces tell LilyPond that the input is a single
550 music expression, just like parentheses @code{()} in mathematics.
551 The braces should be surrounded by a space unless they are at the
552 beginning or end of a line to avoid ambiguities.
554 A LilyPond command followed by a simple expression in braces (such
555 as @q{@w{@code{@bs{}relative c' @{ @dots{} @}}}}) also counts as a
556 single music expression.
560 @cindex block comment
563 a comment is a remark for the human reader of the music input; it
564 is ignored while parsing, so it has no effect on the printed
565 output. There are two types of comments. The percent symbol
566 @code{%} introduces a line comment; anything after @code{%} on
567 that line is ignored. By convention, a line comment is placed
568 @emph{above} the code it refers to.
572 % this comment refers to the Bs
576 A block comment marks a whole section of music input as a comment.
577 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
578 However, block comments do not @q{nest}. This means that you
579 cannot place a block comment inside another block comment. If you
580 try, the first @code{%@}} will terminate @emph{both} block
581 comments. The following fragment shows possible uses for
585 % notes for twinkle twinkle follow
589 This line, and the notes below are ignored,
590 since they are in a block comment.
599 @node Dealing with errors
600 @section Dealing with errors
602 @cindex troubleshooting
604 Sometimes LilyPond doesn't produce the output you expect. This
605 section provides some links to help you solve the problems you
610 * General troubleshooting tips::
611 * Some common errors::
614 @node General troubleshooting tips
615 @subsection General troubleshooting tips
617 Troubleshooting LilyPond problems can be challenging for
618 people who are used to a graphical interface, because invalid
619 input files can be created. When this happens, a logical approach
620 is the best way to identify and solve the problem. Some guidelines
621 to help you learn to do this are provided in @rprogram{Troubleshooting}.
624 @node Some common errors
625 @subsection Some common errors
627 @cindex common errors
628 @cindex errors, common
630 There are a few common errors that are difficult to troubleshoot
631 based simply on the error messages that are displayed. These are
632 described in @rprogram{Common errors}.
636 @node How to read the manuals
637 @section How to read the manuals
639 This section shows how to read the documentation efficiently, and
640 also introduces some useful interactive features available in the
645 * Clickable examples::
646 * Overview of manuals::
650 @node Omitted material
651 @subsection Omitted material
654 @cindex how to read the manual
655 @cindex manual, reading
656 @cindex reading the manual
657 @cindex examples, clickable
658 @cindex clickable examples
659 @cindex tips for constructing files
661 @cindex constructing files, tips
662 @cindex files, tips for constructing
664 LilyPond input must be surrounded by @code{@{ @}} marks or a
665 @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}, as we saw in
666 @ref{Working on input files}. For the rest of this manual, most
667 examples will omit this. To replicate the examples, you may copy
668 and paste the displayed input, but you @strong{must} add the
669 @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} like this:
673 @dots{}example goes here@dots{}
677 Why omit the braces? Most examples in this manual can be inserted
678 into the middle of a longer piece of music. For these examples,
679 it does not make sense to add
680 @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} -- you should not
681 place a @code{\relative} inside another @code{\relative}! If we
682 included @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} around
683 every example, you would not be able to copy a small documentation
684 example and paste it inside a longer piece of your own. Most
685 people want to add material to an existing piece, so we format the
688 Also, remember that every LilyPond file should have a
689 @code{\version} statement. Because the examples in the manuals
690 are snippets, not files, the @code{\version} statement is omitted.
691 But you should make a practice of including them in your files.
693 @node Clickable examples
694 @subsection Clickable examples
696 @warning{This feature is only available in the HTML manuals.}
698 Many people learn programs by trying and fiddling around with the
699 program. This is also possible with LilyPond. If you click on a
700 picture in the HTML version of this manual, you will see the exact
701 LilyPond input that was used to generate that image. Try it on
707 c4-\markup { \bold \huge { Click here. } }
711 By cutting and pasting everything in the @qq{ly snippet} section,
712 you have a starting template for experiments. To see exactly the
713 same output (line-width and all), copy everything from @qq{Start
714 cut-&-pastable section} to the bottom of the file.
720 @n ode Keyboard navigation
721 @s ubsection Keyboard navigation
723 @warning{This features is only available in the HTML manuals.}
725 @c TODO: once this is figured out, insert it here.
727 We are currently working on this feature.
730 @node Overview of manuals
731 @subsection Overview of manuals
733 There is a lot of documentation for LilyPond. New users are
734 sometimes confused about what part(s) they should read, and
735 occasionally skip over reading vital portions.
737 @warning{Please do not skip over important parts of the
738 documentation. You will find it much harder to understand later
744 @strong{Before trying to do @emph{anything}}: read the Learning
745 manual's @ref{Tutorial}, and @ref{Common notation}. If you
746 encounter musical terms which you do not recognize, please look
747 them up in the @rglosnamed{Top, Glossary}.
750 @strong{Before trying to write a complete piece of music}: read
751 the Learning manual's @ref{Fundamental concepts}. After that, you
752 may want to look in relevant sections of the
753 @rusernamed{Top, Notation reference}.
756 @strong{Before trying to change the default output}: read the
757 Learning manual's @ref{Tweaking output}.
760 @strong{Before undertaking a large project}: read the Usage
761 document's @rprogram{Suggestions for writing files}.