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 * How to read the manuals::
26 @node Compiling a file
27 @section Compiling a file
29 This section introduces @qq{compiling}---the processing of
30 LilyPond input files (written by you) to produce output files.
40 @subsection Entering input
44 @cindex example, first
45 @cindex case sensitive
47 @qq{Compiling} is the term used for processing an input file in
48 LilyPond format to produce output file(s). Output files are
49 generally PDF (for printing or viewing), MIDI (for playing), and
50 PNG (for online use). LilyPond input files are simple text files.
52 This example shows a simple input file:
55 \version "@w{@version{}}"
61 The graphical output is:
63 @c in this case we don't want verbatim
70 @warning{Notes and lyrics in LilyPond input must always be
71 surrounded by @w{@strong{@{ curly braces @}}}. The braces
72 should also be surrounded by a space unless they are at the
73 beginning or end of a line to avoid ambiguities. They may
74 be omitted in some examples in this manual, but don't forget them
75 in your own music! For more information about the display of
76 examples in the manual, see @ref{How to read the manuals}.}
78 In addition, LilyPond input is @strong{case sensitive}.
79 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
80 produce an error message.
85 @subheading Producing output
91 The method of producing output depends on your operating system
92 and the program(s) you use.
97 @ref{MacOS X, @sourceimage{logo-macosx,,,}}
98 @ref{MacOS X, MacOS X} (graphical)
101 @ref{Windows, @sourceimage{logo-windows,,,}}
102 @ref{Windows, Microsoft Windows} (graphical)
105 @ref{Command-line, @sourceimage{logo-linux,,,}
106 @sourceimage{logo-freebsd,,,}
107 @sourceimage{logo-macosx,,,}
108 @sourceimage{logo-windows,,,}
110 @ref{Command-line, All operating systems} (command-line)
114 There are several other text editors available with specific
115 support for LilyPond. For more information, see
116 @rweb{Easier editing}.
118 @warning{The first time you ever run LilyPond, it may take a
119 minute or two because all of the system fonts have to be analyzed
120 first. After this, LilyPond will be much faster!}
126 @cindex running LilyPond under MacOS X
127 @cindex MacOS X, running LilyPond
135 @cindex running LilyPond under Windows
136 @cindex Windows, running LilyPond
142 @subsection Command-line
144 @cindex running LilyPond under Unix
145 @cindex Unix, running LilyPond
149 @node How to write input files
150 @section How to write input files
152 This section introduces some basic LilyPond syntax to help get you
153 started writing input files.
157 * Working on input files::
161 @node Simple notation
162 @subsection Simple notation
164 @cindex simple notation
165 @cindex notation, simple
167 LilyPond will add some notation elements automatically. In the
168 next example, we have only specified four pitches, but LilyPond
169 has added a clef, time signature, and rhythms.
171 @lilypond[verbatim,quote]
178 This behavior may be altered, but in most cases these automatic
185 @cindex relative mode
186 @cindex quote, single
188 @cindex accidentals and relative mode
189 @cindex relative mode, and accidentals
196 Music Glossary: @rglos{pitch}, @rglos{interval},
197 @rglos{scale}, @rglos{middle C}, @rglos{octave},
200 The easiest way to enter notes is by using @code{\relative} mode.
201 In this mode, the octave is chosen automatically by assuming the
202 following note is always to be placed closest to the previous
203 note, i.e., it is to be placed in the octave which is within three
204 staff spaces of the previous note. We begin by entering the most
205 elementary piece of music, a @notation{scale}, in which every note
206 is within just one staff space of the previous note.
208 @lilypond[verbatim,quote]
209 % set the starting point to middle C
216 The initial note is @notation{middle C}. Each successive note is
217 placed closest to the previous note -- in other words, the first
218 @code{c} is the closest C to middle C. This is followed by the
219 closest D to the previous note. We can create melodies which have
220 larger intervals, still using only @code{\relative} mode:
222 @lilypond[verbatim,quote]
230 It is not necessary for the first note of the melody to start on
231 the note which specifies the starting pitch. In the previous
232 example, the first note -- the @code{d} -- is the closest D to
235 By adding (or removing) quotes @code{'} or commas @code{,} from
236 the @code{@w{\relative c' @{}} command, we can change the starting
239 @lilypond[verbatim,quote]
240 % one octave above middle C
246 Relative mode can be confusing initially, but is the easiest way
247 to enter most melodies. Let us see how this relative calculation
248 works in practice. Starting from a B, which is on the middle line
249 in a treble clef, you can reach a C, D and E within 3 staff spaces
250 going up, and an A, G and F within 3 staff spaces going down. So
251 if the note following a B is a C, D or E it will be assumed to be
252 above the B, and an A, G or F will be assumed to be below.
254 @lilypond[verbatim,quote]
256 b c % c is 1 staff space up, so is the c above
257 b d % d is 2 up or 5 down, so is the d above
258 b e % e is 3 up or 4 down, so is the e above
259 b a % a is 6 up or 1 down, so is the a below
260 b g % g is 5 up or 2 down, so is the g below
261 b f % f is 4 up or 3 down, so is the f below
265 Exactly the same happens even when any of these notes are
266 sharpened or flattened. @notation{Accidentals} are
267 @strong{totally ignored} in the calculation of relative position.
268 Precisely the same staff space counting is done from a note at any
269 other position on the staff.
271 To add intervals that are larger than three staff spaces, we can
272 raise the @notation{octave} by adding a single quote @code{'} (or
273 apostrophe) to the note name. We can lower the octave by adding a
274 comma @code{,} to the note name.
276 @lilypond[verbatim,quote]
284 To change a note by two (or more!) octaves, we use multiple
285 @code{''} or @code{,,} -- but be careful that you use two single
286 quotes @code{''} and not one double quote @code{"}@tie{}! The
287 initial value in @code{@w{\relative c'}} may also be modified like
289 @c " - keeps quotes in order for context-sensitive editor -td
291 @subheading Durations (rhythms)
293 @cindex note durations
300 @cindex notating durations
302 Music Glossary: @rglos{beam}, @rglos{duration},
303 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
306 The @notation{duration} of a note is specified by a number after
307 the note name: @code{1} for a @notation{whole note}, @code{2} for
308 a @notation{half note}, @code{4} for a @notation{quarter note} and
309 so on. @notation{Beams} are added automatically.
311 If you do not specify a duration, the previous duration is used
312 for the next note. The duration of the first note defaults to a
315 @lilypond[verbatim,quote]
319 a16 a a a a32 a a a a64 a a a a a a a a2
323 To create @notation{dotted notes}, add a dot @code{.} to the
324 duration number. The duration of a dotted note must be stated
325 explicitly (i.e., with a number).
327 @lilypond[verbatim,quote]
338 @cindex notating rests
340 Music Glossary: @rglos{rest}.
342 A @notation{rest} is entered just like a note with the name
345 @lilypond[verbatim,quote]
353 @subheading Time signature
355 @cindex time signature
360 Music Glossary: @rglos{time signature}.
362 The @notation{time signature} can be set with the @code{\time}
365 @lilypond[verbatim,quote]
388 Music Glossary: @rglos{clef}.
390 The @notation{clef} can be set using the @code{\clef} command:
392 @lilypond[verbatim,quote]
406 @subheading All together
408 Here is a small example showing all these elements together:
410 @lilypond[verbatim,quote]
421 Notation Reference: @ruser{Writing pitches},
422 @ruser{Writing rhythms}, @ruser{Writing rests},
423 @ruser{Time signature}, @ruser{Clef}.
426 @node Working on input files
427 @subsection Working on input files
430 @cindex braces, curly
433 @cindex comment, line
434 @cindex block comment
435 @cindex comment, line
436 @cindex case sensitive
437 @cindex whitespace insensitive
441 @cindex version number
446 @funindex %@{ ... %@}
448 LilyPond input files are similar to source files in many common
449 programming languages. They contain a version statement,
450 are case sensitive, and white-space
451 is generally ignored. Expressions are formed with curly braces
452 @{ @}, and comments are denoted with @code{%} or
453 @w{@code{%@{ ... %@}}}.
455 If the previous sentences sound like nonsense, don't worry! We'll
456 explain what all these terms mean:
461 @strong{Version statement}:
462 Every LilyPond file should contain a version statement. A version
463 statement is a line that describes the version of LilyPond for which
464 the file was written, as in the following example:
467 \version "@w{@version{}}"
470 By convention, the version statement is placed at the top of the
473 The version statement is important for at least two reasons. First,
474 it allows automatic updating of the input file as LilyPond syntax
475 changes. Second, it describes the version of LilyPond needed to
478 If the version statement is omitted from an input file, LilyPond will print
479 a warning during the compilation of the file.
482 @strong{Case sensitive}:
483 it matters whether you enter a letter in lower case (e.g.
484 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
485 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
486 @w{@code{@{ C D E @}}} will produce an error message.
489 @strong{Whitespace insensitive}:
490 it does not matter how many spaces (or tabs or new lines) you add.
491 @w{@code{@{ c d e @}}} means the same thing as
492 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
500 Of course, the previous example is hard to read. A good rule of
501 thumb is to indent code blocks with either a tab or two spaces:
509 However, whitespace @emph{is} required to separate many syntactical
510 elements from others. In other words, whitespace can always be
511 @emph{added}, but it cannot be @emph{eliminated}. As missing
512 whitespace can give rise to strange errors it is advisable to
513 always insert whitespace before and after every syntactic element,
514 for example, before and after every curly brace.
517 @strong{Expressions}:
518 every piece of LilyPond input needs to have @strong{@{ curly
519 braces @}} placed around the input. These braces tell LilyPond
520 that the input is a single music expression, just like parentheses
521 @code{()} in mathematics. The braces should be surrounded by a
522 space unless they are at the beginning or end of a line to avoid
525 A LilyPond command followed by a simple expression in braces (such
526 as @w{@code{\relative @{ @}}}) also counts as a single music
531 @cindex block comment
534 a comment is a remark for the human reader of the music input; it
535 is ignored while parsing, so it has no effect on the printed
536 output. There are two types of comments. The percent symbol
537 @code{%} introduces a line comment; anything after @code{%} on
538 that line is ignored. By convention, a line comment is placed
539 @emph{above} the code it refers to.
543 % this comment refers to the Bs
547 A block comment marks a whole section of music input as a comment.
548 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
549 However, block comments do not @q{nest}. This means that you
550 cannot place a block comment inside another block comment. If you
551 try, the first @code{%@}} will terminate @emph{both} block
552 comments. The following fragment shows possible uses for
556 % notes for twinkle twinkle follow
560 This line, and the notes below are ignored,
561 since they are in a block comment.
570 @node How to read the manuals
571 @section How to read the manuals
573 This section shows how to read the documentation efficiently, and
574 also introduces some useful interactive features available in the
579 * Clickable examples::
580 * Keyboard navigation::
581 * Overview of manuals::
585 @node Omitted material
586 @subsection Omitted material
589 @cindex how to read the manual
590 @cindex manual, reading
591 @cindex reading the manual
592 @cindex examples, clickable
593 @cindex clickable examples
594 @cindex tips for constructing files
596 @cindex constructing files, tips
597 @cindex files, tips for constructing
599 LilyPond input must be surrounded by @{ @} marks or a
600 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
601 input files}. For the rest of this manual, most examples will
602 omit this. To replicate the examples, you may copy and paste the
603 displayed input, but you @strong{must} add the
604 @code{@w{\relative c'' @{ @}}} like this:
608 ... example goes here...
612 Why omit the braces? Most examples in this manual can be inserted
613 into the middle of a longer piece of music. For these examples,
614 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
615 you should not place a @code{\relative} inside another
616 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
617 around every example, you would not be able to copy a small
618 documentation example and paste it inside a longer piece of your
619 own. Most people want to add material to an existing piece, so we
620 format the manual this way.
622 Also, remember that every LilyPond file should have a @code{@bs{}version}
623 statement. Because the examples in the manuals are snippets, not files,
624 the @code{@bs{}version} statement is omitted. But you should make a
625 practice of including them in your files.
627 @node Clickable examples
628 @subsection Clickable examples
630 @warning{This feature is only available in the HTML manuals.}
632 Many people learn programs by trying and fiddling around with the
633 program. This is also possible with LilyPond. If you click on a
634 picture in the HTML version of this manual, you will see the exact
635 LilyPond input that was used to generate that image. Try it on
641 c-\markup { \bold \huge { Click here. } }
645 By cutting and pasting everything in the @qq{ly snippet} section,
646 you have a starting template for experiments. To see exactly the
647 same output (line-width and all), copy everything from @qq{Start
648 cut-&-pastable section} to the bottom of the file.
651 @node Keyboard navigation
652 @subsection Keyboard navigation
654 @warning{This features is only available in the HTML manuals.}
656 @c TODO: once this is figured out, insert it here.
658 We are currently working on this feature.
661 @node Overview of manuals
662 @subsection Overview of manuals
664 There is a lot of documentation for LilyPond. New users are
665 sometimes confused about what part(s) they should read, and
666 occasionally skip over reading vital portions.
668 @warning{Please do not skip over important parts of the
669 documentation. You will find it much harder to understand later
675 @strong{Before trying to do @emph{anything}}: read the Learning
676 manual's @ref{Tutorial}, and @ref{Common notation}. If you
677 encounter musical terms which you do not recognize, please look
678 them up in the @rglosnamed{Top, Glossary}.
681 @strong{Before trying to write a complete piece of music}: read
682 the Learning manual's @ref{Fundamental concepts}. After that, you
683 may want to look in relevant sections of the
684 @rusernamed{Top, Notation reference}.
687 @strong{Before trying to change the default output}: read the
688 Learning manual's @ref{Tweaking output}.
691 @strong{Before undertaking a large project}: read Usage document's
692 @rprogram{Suggestions for writing files}.