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
52 @qq{Compiling} is the term used for processing an input file in
53 LilyPond format to produce output file(s). Output files are
54 generally PDF (for printing or viewing), MIDI (for playing), and
55 PNG (for online use). LilyPond input files are simple text files.
57 This example shows a simple input file:
60 \version "@w{@version{}}"
66 The graphical output is:
68 @c in this case we don't want verbatim
75 @warning{Notes and lyrics in LilyPond input must always be
76 surrounded by @w{@strong{@{ curly braces @}}}. The braces
77 should also be surrounded by a space unless they are at the
78 beginning or end of a line to avoid ambiguities. They may
79 be omitted in some examples in this manual, but don't forget them
80 in your own music! For more information about the display of
81 examples in the manual, see @ref{How to read the manuals}.}
83 In addition, LilyPond input is @strong{case sensitive}.
84 @w{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}} will
85 produce an error message.
90 @node Producing output
91 @unnumberedsubsubsec Producing output
97 The method of producing output depends on your operating system
98 and the program(s) you use.
103 @ref{MacOS X, @sourceimage{logo-macosx,,,}}
104 @ref{MacOS X, MacOS X} (graphical)
107 @ref{Windows, @sourceimage{logo-windows,,,}}
108 @ref{Windows, Microsoft Windows} (graphical)
111 @ref{Command-line, @sourceimage{logo-linux,,,}
112 @sourceimage{logo-freebsd,,,}
113 @sourceimage{logo-macosx,,,}
114 @sourceimage{logo-windows,,,}
116 @ref{Command-line, All operating systems} (command-line)
120 There are several other text editors available with specific
121 support for LilyPond. For more information, see
122 @rweb{Easier editing}.
124 @warning{The first time you ever run LilyPond, it may take a
125 minute or two because all of the system fonts have to be analyzed
126 first. After this, LilyPond will be much faster!}
132 @cindex running LilyPond under MacOS X
133 @cindex MacOS X, running LilyPond
141 @cindex running LilyPond under Windows
142 @cindex Windows, running LilyPond
148 @subsection Command-line
150 @cindex running LilyPond under Unix
151 @cindex Unix, running LilyPond
155 @node How to write input files
156 @section How to write input files
158 This section introduces some basic LilyPond syntax to help get you
159 started writing input files.
163 * Working on input files::
167 @node Simple notation
168 @subsection Simple notation
170 @cindex simple notation
171 @cindex notation, simple
175 * Durations (rhythms)::
183 LilyPond will add some notation elements automatically. In the
184 next example, we have only specified four pitches, but LilyPond
185 has added a clef, time signature, and rhythms.
187 @lilypond[verbatim,quote]
194 This behavior may be altered, but in most cases these automatic
199 @unnumberedsubsubsec Pitches
202 @cindex relative mode
203 @cindex quote, single
205 @cindex accidentals and relative mode
206 @cindex relative mode, and accidentals
213 Music Glossary: @rglos{pitch}, @rglos{interval},
214 @rglos{scale}, @rglos{middle C}, @rglos{octave},
217 The easiest way to enter notes is by using @code{\relative} mode.
218 In this mode, the octave is chosen automatically by assuming the
219 following note is always to be placed closest to the previous
220 note, i.e., it is to be placed in the octave which is within three
221 staff spaces of the previous note. We begin by entering the most
222 elementary piece of music, a @notation{scale}, in which every note
223 is within just one staff space of the previous note.
225 @lilypond[verbatim,quote]
226 % set the starting point to middle C
233 The initial note is @notation{middle C}. Each successive note is
234 placed closest to the previous note -- in other words, the first
235 @code{c} is the closest C to middle C. This is followed by the
236 closest D to the previous note. We can create melodies which have
237 larger intervals, still using only @code{\relative} mode:
239 @lilypond[verbatim,quote]
247 It is not necessary for the first note of the melody to start on
248 the note which specifies the starting pitch. In the previous
249 example, the first note -- the @code{d} -- is the closest D to
252 By adding (or removing) quotes @code{'} or commas @code{,} from
253 the @q{@w{@code{@bs{}relative c'}}} command, we can change the
256 @lilypond[verbatim,quote]
257 % one octave above middle C
263 Relative mode can be confusing initially, but is the easiest way
264 to enter most melodies. Let us see how this relative calculation
265 works in practice. Starting from a B, which is on the middle line
266 in a treble clef, you can reach a C, D and E within 3 staff spaces
267 going up, and an A, G and F within 3 staff spaces going down. So
268 if the note following a B is a C, D or E it will be assumed to be
269 above the B, and an A, G or F will be assumed to be below.
271 @lilypond[verbatim,quote]
273 b c % c is 1 staff space up, so is the c above
274 b d % d is 2 up or 5 down, so is the d above
275 b e % e is 3 up or 4 down, so is the e above
276 b a % a is 6 up or 1 down, so is the a below
277 b g % g is 5 up or 2 down, so is the g below
278 b f % f is 4 up or 3 down, so is the f below
282 Exactly the same happens even when any of these notes are
283 sharpened or flattened. @notation{Accidentals} are
284 @strong{totally ignored} in the calculation of relative position.
285 Precisely the same staff space counting is done from a note at any
286 other position on the staff.
288 To add intervals that are larger than three staff spaces, we can
289 raise the @notation{octave} by adding a single quote @code{'} (or
290 apostrophe) to the note name. We can lower the octave by adding a
291 comma @code{,} to the note name.
293 @lilypond[verbatim,quote]
301 To change a note by two (or more!) octaves, we use multiple
302 @code{''} or @code{,,} -- but be careful that you use two single
303 quotes @code{''} and not one double quote @code{"}@tie{}!
304 @c " - keeps quotes in order for context-sensitive editor -td
306 @node Durations (rhythms)
307 @unnumberedsubsubsec Durations (rhythms)
309 @cindex note durations
316 @cindex notating durations
318 Music Glossary: @rglos{beam}, @rglos{duration},
319 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
322 The @notation{duration} of a note is specified by a number after
323 the note name: @code{1} for a @notation{whole note}, @code{2} for
324 a @notation{half note}, @code{4} for a @notation{quarter note} and
325 so on. @notation{Beams} are added automatically.
327 If you do not specify a duration, the previous duration is used
328 for the next note. The duration of the first note defaults to a
331 @lilypond[verbatim,quote]
335 a16 a a a a32 a a a a64 a a a a a a a a2
339 To create @notation{dotted notes}, add a dot @code{.} to the
340 duration number. The duration of a dotted note must be stated
341 explicitly (i.e., with a number).
343 @lilypond[verbatim,quote]
351 @unnumberedsubsubsec Rests
354 @cindex notating rests
356 Music Glossary: @rglos{rest}.
358 A @notation{rest} is entered just like a note with the name
361 @lilypond[verbatim,quote]
370 @unnumberedsubsubsec Time signature
372 @cindex time signature
377 Music Glossary: @rglos{time signature}.
379 The @notation{time signature} can be set with the @code{\time}
382 @lilypond[verbatim,quote]
394 @unnumberedsubsubsec Tempo marks
397 @cindex metronome marks
402 Music Glossary: @rglos{tempo indication}, @rglos{metronome}.
404 The @notation{tempo indication} and @notation{metronome mark} can be
405 set with the @code{\tempo} command:
407 @lilypond[verbatim,quote]
416 \tempo "Presto" 4 = 120
423 @unnumberedsubsubsec Clef
434 Music Glossary: @rglos{clef}.
436 The @notation{clef} can be set using the @code{\clef} command:
438 @lilypond[verbatim,quote]
453 @unnumberedsubsubsec All together
455 Here is a small example showing all these elements together:
457 @lilypond[verbatim,quote]
461 \tempo "Andante" 4 = 120
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
491 @cindex version number
496 @funindex %@{ ... %@}
498 LilyPond input files are similar to source files in many common
499 programming languages. They contain a version statement, are case
500 sensitive, and white-space is generally ignored. Expressions are
501 formed with curly braces @w{@code{@{ @}}}, and comments are
502 denoted with @code{%} or @w{@code{%@{ @dots{} %@}}}@tie{}.
504 If the previous sentences sound like nonsense, don't worry! We'll
505 explain what all these terms mean:
510 @strong{Version statement}:
511 Every LilyPond file should contain a version statement. A version
512 statement is a line that describes the version of LilyPond for which
513 the file was written, as in the following example:
516 \version "@w{@version{}}"
519 By convention, the version statement is placed at the top of the
522 The version statement is important for at least two reasons. First,
523 it allows automatic updating of the input file as LilyPond syntax
524 changes. Second, it describes the version of LilyPond needed to
527 If the version statement is omitted from an input file, LilyPond will print
528 a warning during the compilation of the file.
531 @strong{Case sensitive}:
532 it matters whether you enter a letter in lower case (e.g.
533 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
534 Notes are lower case: @w{@samp{@{ c d e @}}} is valid input;
535 @w{@samp{@{ C D E @}}} will produce an error message.
538 @strong{Whitespace insensitive}:
539 it does not matter how many spaces (or tabs or new lines) you add.
540 @w{@samp{@{ c4 d e @}}} means the same thing as
541 @w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:
549 Of course, the previous example is hard to read. A good rule of
550 thumb is to indent code blocks with two spaces:
558 However, whitespace @emph{is} required to separate many
559 syntactical elements from others. In other words, whitespace can
560 always be @emph{added}, but not always @emph{eliminated}. Since
561 missing whitespace can give rise to strange errors, it is
562 advisable to always insert whitespace before and after every
563 syntactic element, for example, before and after every curly
567 @strong{Expressions}:
568 every piece of LilyPond input needs to have
569 @strong{@{@tie{}curly@tie{}braces@tie{}@}} placed around the
570 input. These braces tell LilyPond that the input is a single
571 music expression, just like parentheses @code{()} in mathematics.
572 The braces should be surrounded by a space unless they are at the
573 beginning or end of a line to avoid ambiguities.
575 A LilyPond command followed by a simple expression in braces (such
576 as @q{@w{@code{@bs{}relative c' @{ @dots{} @}}}}) also counts as a
577 single music expression.
581 @cindex block comment
584 a comment is a remark for the human reader of the music input; it
585 is ignored while parsing, so it has no effect on the printed
586 output. There are two types of comments. The percent symbol
587 @code{%} introduces a line comment; anything after @code{%} on
588 that line is ignored. By convention, a line comment is placed
589 @emph{above} the code it refers to.
593 % this comment refers to the Bs
597 A block comment marks a whole section of music input as a comment.
598 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
599 However, block comments do not @q{nest}. This means that you
600 cannot place a block comment inside another block comment. If you
601 try, the first @code{%@}} will terminate @emph{both} block
602 comments. The following fragment shows possible uses for
606 % notes for twinkle twinkle follow
610 This line, and the notes below are ignored,
611 since they are in a block comment.
620 @node Dealing with errors
621 @section Dealing with errors
623 @cindex troubleshooting
625 Sometimes LilyPond doesn't produce the output you expect. This
626 section provides some links to help you solve the problems you
631 * General troubleshooting tips::
632 * Some common errors::
635 @node General troubleshooting tips
636 @subsection General troubleshooting tips
638 Troubleshooting LilyPond problems can be challenging for
639 people who are used to a graphical interface, because invalid
640 input files can be created. When this happens, a logical approach
641 is the best way to identify and solve the problem. Some guidelines
642 to help you learn to do this are provided in @rprogram{Troubleshooting}.
645 @node Some common errors
646 @subsection Some common errors
648 @cindex common errors
649 @cindex errors, common
651 There are a few common errors that are difficult to troubleshoot
652 based simply on the error messages that are displayed. These are
653 described in @rprogram{Common errors}.
657 @node How to read the manuals
658 @section How to read the manuals
660 This section shows how to read the documentation efficiently, and
661 also introduces some useful interactive features available in the
666 * Clickable examples::
667 * Overview of manuals::
671 @node Omitted material
672 @subsection Omitted material
675 @cindex how to read the manual
676 @cindex manual, reading
677 @cindex reading the manual
678 @cindex examples, clickable
679 @cindex clickable examples
680 @cindex tips for constructing files
682 @cindex constructing files, tips
683 @cindex files, tips for constructing
685 LilyPond input must be surrounded by @code{@{ @}} marks or a
686 @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}, as we saw in
687 @ref{Working on input files}. For the rest of this manual, most
688 examples will omit this. To replicate the examples, you may copy
689 and paste the displayed input, but you @strong{must} add the
690 @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} like this:
694 @dots{}example goes here@dots{}
698 Why omit the braces? Most examples in this manual can be inserted
699 into the middle of a longer piece of music. For these examples,
700 it does not make sense to add
701 @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} -- you should not
702 place a @code{\relative} inside another @code{\relative}! If we
703 included @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} around
704 every example, you would not be able to copy a small documentation
705 example and paste it inside a longer piece of your own. Most
706 people want to add material to an existing piece, so we format the
709 Also, remember that every LilyPond file should have a
710 @code{\version} statement. Because the examples in the manuals
711 are snippets, not files, the @code{\version} statement is omitted.
712 But you should make a practice of including them in your files.
714 @node Clickable examples
715 @subsection Clickable examples
717 @warning{This feature is only available in the HTML manuals.}
719 Many people learn programs by trying and fiddling around with the
720 program. This is also possible with LilyPond. If you click on a
721 picture in the HTML version of this manual, you will see the exact
722 LilyPond input that was used to generate that image. Try it on
728 c4-\markup { \bold \huge { Click here. } }
732 By cutting and pasting everything in the @qq{ly snippet} section,
733 you have a starting template for experiments. To see exactly the
734 same output (line-width and all), copy everything from @qq{Start
735 cut-&-pastable section} to the bottom of the file.
741 @n ode Keyboard navigation
742 @s ubsection Keyboard navigation
744 @warning{This features is only available in the HTML manuals.}
746 @c TODO: once this is figured out, insert it here.
748 We are currently working on this feature.
751 @node Overview of manuals
752 @subsection Overview of manuals
754 There is a lot of documentation for LilyPond. New users are
755 sometimes confused about what part(s) they should read, and
756 occasionally skip over reading vital portions.
758 @warning{Please do not skip over important parts of the
759 documentation. You will find it much harder to understand later
765 @strong{Before trying to do @emph{anything}}: read the Learning
766 manual's @ref{Tutorial}, and @ref{Common notation}. If you
767 encounter musical terms which you do not recognize, please look
768 them up in the @rglosnamed{Top, Glossary}.
771 @strong{Before trying to write a complete piece of music}: read
772 the Learning manual's @ref{Fundamental concepts}. After that, you
773 may want to look in relevant sections of the
774 @rusernamed{Top, Notation reference}.
777 @strong{Before trying to change the default output}: read the
778 Learning manual's @ref{Tweaking output}.
781 @strong{Before undertaking a large project}: read the Usage
782 document's @rprogram{Suggestions for writing files}.