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 @rweb{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 Lilypond
132 application. If you are using any of the programs described in
133 @rweb{Alternate input}, please consult the documentation for
134 those programs if you have any problems.}
136 Double click the @command{LilyPond.app}, an example file will open.
138 @sourceimage{Learning_Macos_welcome,,,}
140 From the menus along the top left of your screen, select
141 @w{@code{File > Save}}.
143 @sourceimage{Learning_Macos_Save_menu,,,}
145 Choose a name for your file, for example @file{test.ly}.
147 @sourceimage{Learning_Macos_Save_file_with_name,,,}
149 From the same menus, select
150 @w{@code{Compile > Tyepset}}.
152 @sourceimage{Learning_Macos_Typeset_menu,,,}
154 A new window will open showing a progress log of the compilation
155 of the file you have just saved.
157 @sourceimage{Learning_Macos_Compiling_log,,,}
159 Once the compilation has finished, a PDF file will be created with
160 the same name as the original file and will be automatically
161 opened in the default PDF viewer and displayed on your screen.
163 @sourceimage{Learning_Macos_pdf_output,,,}
165 To create new files for Lilypond, begin by selecting
166 @w{@code{File > New}}
168 @sourceimage{Learning_Macos_New_menu,,,}
170 or @w{@code{File > Open}} to open and edit existing files you have
173 @sourceimage{Learning_Macos_Open_menu,,,}
175 You must save any new edits you make to your file before you
176 @w{@code{Compile > Tyepset}} and if the PDF file is not displayed
177 check the window with the progress log for any errors.
179 If you are not using the defualt Preview PDF viewer that comes
180 with the Mac Operating system and you have the PDF file generated
181 from a previous compilation open, then any further compilations
182 may fail to generate an update PDF until you close the original.
187 @warning{These instructions assume that you are using the built-in
188 LilyPad editor. If you are using any of the programs described in
189 @rweb{Alternate input}, please consult the documentation for
190 those programs if you have any problems compiling a file.}
192 On Windows, if you double-click in the LilyPond icon on the
193 Desktop, it will open a simple text editor with an example file.
194 Save it, for example, to @file{test.ly} on your Desktop and then
195 double-click on the file to process it (the file icon looks like a
196 note). After some seconds, you will get a file @file{test.pdf} on
197 your desktop. Double-click on this PDF file to view the typeset
198 score. An alternative method to process the @file{test.ly} file
199 is to drag and drop it onto the LilyPond icon using your mouse
202 To edit an existing @file{.ly} file, right-click on it and
203 select @qq{Edit source}. To get an empty file to start from, run
204 the editor as described above and use @qq{New} in
205 the @qq{File} menu, or right-click on the desktop and select
206 @qq{New..Text Document}, change its name to a name of your choice
207 and change the file extension to @code{.ly}. Double-click the
208 icon to type in your LilyPond source code as before.
210 Double-clicking the file does not only result in a PDF file, but
211 also produces a @file{.log} file that contains some information on
212 what LilyPond has done to the file. If any errors occur, please
215 @c FIXME: add screenshots
219 @subsection Command-line
221 @warning{These instructions assume that you are using commond unix
222 command-line programs. If you are using any of the programs
223 described in @rweb{Alternate input}, please consult the
224 documentation for those programs if you have any problems
228 Create a text file called @file{test.ly} and enter:
236 To process @file{test.ly}, proceed as follows:
243 You will see something resembling:
247 GNU LilyPond @version{}
250 Interpreting music...
251 Preprocessing graphical objects...
252 Finding the ideal number of pages...
253 Fitting music on 1 page...
255 Layout output to `test.ps'...
256 Converting to `test.pdf'...
259 You may view or print the resulting @file{text.pdf}.
262 @node How to write input files
263 @section How to write input files
269 * Working on input files::
273 @node Simple notation
274 @subsection Simple notation
276 @cindex simple notation
277 @cindex notation, simple
279 LilyPond will add some notation elements automatically. In the
280 next example, we have only specified four pitches, but LilyPond
281 has added a clef, time signature, and rhythms.
283 @lilypond[verbatim,quote]
290 This behavior may be altered, but in most cases these automatic
297 @cindex relative mode
298 @cindex quote, single
300 @cindex accidentals and relative mode
301 @cindex relative mode, and accidentals
308 Music Glossary: @rglos{pitch}, @rglos{interval},
309 @rglos{scale}, @rglos{middle C}, @rglos{octave},
312 The easiest way to enter notes is by using @code{\relative} mode.
313 In this mode, the octave is chosen automatically by assuming the
314 following note is always to be placed closest to the previous
315 note, i.e., it is to be placed in the octave which is within three
316 staff spaces of the previous note. We begin by entering the most
317 elementary piece of music, a @notation{scale}, in which every note
318 is within just one staff space of the previous note.
320 @lilypond[verbatim,quote]
321 % set the starting point to middle C
328 The initial note is @notation{middle C}. Each successive note is
329 placed closest to the previous note -- in other words, the first
330 @code{c} is the closest C to middle C. This is followed by the
331 closest D to the previous note. We can create melodies which have
332 larger intervals, still using only @code{\relative} mode:
334 @lilypond[verbatim,quote]
342 It is not necessary for the first note of the melody to start on
343 the note which specifies the starting pitch. In the previous
344 example, the first note -- the @code{d} -- is the closest D to
347 By adding (or removing) quotes @code{'} or commas @code{,} from
348 the @code{@w{\relative c' @{}} command, we can change the starting
351 @lilypond[verbatim,quote]
352 % one octave above middle C
358 Relative mode can be confusing initially, but is the easiest way
359 to enter most melodies. Let us see how this relative calculation
360 works in practice. Starting from a B, which is on the middle line
361 in a treble clef, you can reach a C, D and E within 3 staff spaces
362 going up, and an A, G and F within 3 staff spaces going down. So
363 if the note following a B is a C, D or E it will be assumed to be
364 above the B, and an A, G or F will be assumed to be below.
366 @lilypond[verbatim,quote]
368 b c % c is 1 staff space up, so is the c above
369 b d % d is 2 up or 5 down, so is the d above
370 b e % e is 3 up or 4 down, so is the e above
371 b a % a is 6 up or 1 down, so is the a below
372 b g % g is 5 up or 2 down, so is the g below
373 b f % f is 4 up or 3 down, so is the f below
377 Exactly the same happens even when any of these notes are
378 sharpened or flattened. @notation{Accidentals} are
379 @strong{totally ignored} in the calculation of relative position.
380 Precisely the same staff space counting is done from a note at any
381 other position on the staff.
383 To add intervals that are larger than three staff spaces, we can
384 raise the @notation{octave} by adding a single quote @code{'} (or
385 apostrophe) to the note name. We can lower the octave by adding a
386 comma @code{,} to the note name.
388 @lilypond[verbatim,quote]
396 To change a note by two (or more!) octaves, we use multiple
397 @code{''} or @code{,,} -- but be careful that you use two single
398 quotes @code{''} and not one double quote @code{"}@tie{}! The
399 initial value in @code{@w{\relative c'}} may also be modified like
401 @c " - keeps quotes in order for context-sensitive editor -td
403 @subheading Durations (rhythms)
405 @cindex note durations
412 @cindex notating durations
414 Music Glossary: @rglos{beam}, @rglos{duration},
415 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
418 The @notation{duration} of a note is specified by a number after
419 the note name: @code{1} for a @notation{whole note}, @code{2} for
420 a @notation{half note}, @code{4} for a @notation{quarter note} and
421 so on. @notation{Beams} are added automatically.
423 If you do not specify a duration, the previous duration is used
424 for the next note. The duration of the first note defaults to a
427 @lilypond[verbatim,quote]
431 a16 a a a a32 a a a a64 a a a a a a a a2
435 To create @notation{dotted notes}, add a dot @code{.} to the
436 duration number. The duration of a dotted note must be stated
437 explicitly (i.e., with a number).
439 @lilypond[verbatim,quote]
450 @cindex notating rests
452 Music Glossary: @rglos{rest}.
454 A @notation{rest} is entered just like a note with the name
457 @lilypond[verbatim,quote]
465 @subheading Time signature
467 @cindex time signature
472 Music Glossary: @rglos{time signature}.
474 The @notation{time signature} can be set with the @code{\time}
477 @lilypond[verbatim,quote]
500 Music Glossary: @rglos{clef}.
502 The @notation{clef} can be set using the @code{\clef} command:
504 @lilypond[verbatim,quote]
518 @subheading All together
520 Here is a small example showing all these elements together:
522 @lilypond[verbatim,quote]
533 Notation Reference: @ruser{Writing pitches},
534 @ruser{Writing rhythms}, @ruser{Writing rests},
535 @ruser{Time signature}, @ruser{Clef}.
538 @node Working on input files
539 @subsection Working on input files
542 @cindex braces, curly
545 @cindex comment, line
546 @cindex block comment
547 @cindex comment, line
548 @cindex case sensitive
549 @cindex whitespace insensitive
554 @funindex %@{ ... %@}
556 LilyPond input files are similar to source files in many common
557 programming languages. They are case sensitive, and white-space
558 is generally ignored. Expressions are formed with curly braces
559 @{ @}, and comments are denoted with @code{%} or
560 @w{@code{%@{ ... %@}}}.
562 If the previous sentences sound like nonsense, don't worry! We'll
563 explain what all these terms mean:
568 @strong{Case sensitive}:
569 it matters whether you enter a letter in lower case (e.g.
570 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
571 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
572 @w{@code{@{ C D E @}}} will produce an error message.
575 @strong{Whitespace insensitive}:
576 it does not matter how many spaces (or tabs or new lines) you add.
577 @w{@code{@{ c d e @}}} means the same thing as
578 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
586 Of course, the previous example is hard to read. A good rule of
587 thumb is to indent code blocks with either a tab or two spaces:
595 However, whitespace @emph{is} required to separate many syntactical
596 elements from others. In other words, whitespace can always be
597 @emph{added}, but it cannot be @emph{eliminated}. As missing
598 whitespace can give rise to strange errors it is advisable to
599 always insert whitespace before and after every syntactic element,
600 for example, before and after every curly brace.
603 @strong{Expressions}:
604 every piece of LilyPond input needs to have @strong{@{ curly
605 braces @}} placed around the input. These braces tell LilyPond
606 that the input is a single music expression, just like parentheses
607 @code{()} in mathematics. The braces should be surrounded by a
608 space unless they are at the beginning or end of a line to avoid
611 A LilyPond command followed by a simple expression in braces (such
612 as @w{@code{\relative @{ @}}}) also counts as a single music
617 @cindex block comment
620 a comment is a remark for the human reader of the music input; it
621 is ignored while parsing, so it has no effect on the printed
622 output. There are two types of comments. The percent symbol
623 @code{%} introduces a line comment; anything after @code{%} on
624 that line is ignored. By convention, a line comment is placed
625 @emph{above} the code it refers to.
629 % this comment refers to the Bs
633 A block comment marks a whole section of music input as a comment.
634 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
635 However, block comments do not @q{nest}. This means that you
636 cannot place a block comment inside another block comment. If you
637 try, the first @code{%@}} will terminate @emph{both} block
638 comments. The following fragment shows possible uses for
642 % notes for twinkle twinkle follow
646 This line, and the notes below are ignored,
647 since they are in a block comment.
656 @node How to read the manuals
657 @section How to read the manuals
663 * Clickable examples::
664 * Keyboard navigation::
665 * Overview of manuals::
669 @node Omitting braces
670 @subsection Omitting braces
673 @cindex how to read the manual
674 @cindex manual, reading
675 @cindex reading the manual
676 @cindex examples, clickable
677 @cindex clickable examples
678 @cindex tips for constructing files
680 @cindex constructing files, tips
681 @cindex files, tips for constructing
683 LilyPond input must be surrounded by @{ @} marks or a
684 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
685 input files}. For the rest of this manual, most examples will
686 omit this. To replicate the examples, you may copy and paste the
687 displayed input, but you @strong{must} add the
688 @code{@w{\relative c'' @{ @}}} like this:
692 ... example goes here...
696 Why omit the braces? Most examples in this manual can be inserted
697 into the middle of a longer piece of music. For these examples,
698 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
699 you should not place a @code{\relative} inside another
700 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
701 around every example, you would not be able to copy a small
702 documentation example and paste it inside a longer piece of your
703 own. Most people want to add material to an existing piece, so we
704 format the manual this way.
707 @node Clickable examples
708 @subsection Clickable examples
710 @warning{This features is only available in the HTML manuals.}
712 Many people learn programs by trying and fiddling around with the
713 program. This is also possible with LilyPond. If you click on a
714 picture in the HTML version of this manual, you will see the exact
715 LilyPond input that was used to generate that image. Try it on
721 c-\markup { \bold \huge { Click here. } }
725 By cutting and pasting everything in the @qq{ly snippet} section,
726 you have a starting template for experiments. To see exactly the
727 same output (line-width and all), copy everything from @qq{Start
728 cut-&-pastable section} to the bottom of the file.
731 @node Keyboard navigation
732 @subsection Keyboard navigation
734 @warning{This features is only available in the HTML manuals.}
736 @c TODO: once this is figured out, insert it here.
738 We are currently working on this feature.
741 @node Overview of manuals
742 @subsection Overview of manuals
744 There is a lot of documentation for LilyPond. New users are
745 sometimes confused about what part(s) they should read, and
746 occasionally skip over reading vital portions.
748 @warning{Please do not skip over important parts of the
749 documentation. You will find it much harder to understand later
755 @strong{Before trying to do @emph{anything}}: read the Learning
756 manual's @ref{Tutorial}, and @ref{Common notation}. If you
757 encounter musical terms which you do not recognize, please look
758 them up in the @rglosnamed{Top, Glossary}.
761 @strong{Before trying to write a complete piece of music}: read
762 the Learning manual's @ref{Fundamental concepts}. After that, you
763 may want to look in relevant sections of the
764 @rusernamed{Top, Notation reference}.
767 @strong{Before trying to change the default output}: read the
768 Learning manual's @ref{Tweaking output}.
771 @strong{Before undertaking a large project}: read Usage document's
772 @rprogram{Suggestions for writing files}.