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. They 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 Double-click the @command{LilyPond.app}, an example file will open.
194 @sourceimage{Learning_Win7_Welcome_File_Whole,,,}
196 From the menus that appear alonbg the top of the example file,
197 select @w{@code{File > Save as}}. Do not use the @w{@code{File > Save}}
198 for the example file as this will not work until you have given it a
199 valid Lilypong file name.
201 @sourceimage{Learning_Win7_Save_Menu,,,}
203 Choose a name for your file, for example @file{test.ly}.
205 @sourceimage{Learning_Win7_Save_File_With_Name,,,}
207 Depending on what you prefer, to compile your file either:
209 Drag-and-drop the file directly onto the LilyPond icon.
211 @sourceimage{Learning_Win7_Open_Dragndrop,,,}
213 Right-click on the file and from the pop-up context menu choose
214 @w{@code{Open with > LilyPond}}.
216 @sourceimage{Learning_Win7_Open_Context_Menu,,,}
218 Or simply double-click the @file{test.ly}.
220 During the compilation of the @file{test.ly} file, a command window
221 will, very briefly open and then close. Three additional files will
222 have been created during this process.
224 @sourceimage{Learning_Win7_All_Files_Created,,,}
226 The PDF file contains the engraved @file{test.ly} file.
228 @sourceimage{Learning_Win7_Pdf_Output,,,}
230 To create a new file, begin by selecting @w{@code{File > New}} from
231 within any previously created file.
233 @sourceimage{Learning_Win7_New_Menu,,,}
235 or @w{@code{File > Open}} to open and edit any files you have saved
238 @sourceimage{Learning_Win7_Open_Menu,,,}
240 You must save any new edits you make before you compile it and if the
241 PDF file is not created, check the log file that will have been created
242 during the compilation attempt, for any errors.
244 @sourceimage{Learning_Win7_Log_File,,,}
246 This log file is overwritten each time you compile your lilypond file.
248 The PS file is used internally by LilyPond to create the PDF file and
249 can be ignored. It also gets overwritten each time you compile your
252 If you are viewing your file in a PDF viewer, then you must close the
253 PDF if you wish to make a new compilation as it may fail to create
254 the new PDF while it is still being viewed.
257 @subsection Command-line
259 @warning{These instructions assume that you are using commond unix
260 command-line programs. If you are using any of the programs
261 described in @rweb{Alternate input}, please consult the
262 documentation for those programs if you have any problems
266 Create a text file called @file{test.ly} and enter:
274 To process @file{test.ly}, proceed as follows:
281 You will see something resembling:
285 GNU LilyPond @version{}
288 Interpreting music...
289 Preprocessing graphical objects...
290 Finding the ideal number of pages...
291 Fitting music on 1 page...
293 Layout output to `test.ps'...
294 Converting to `test.pdf'...
297 You may view or print the resulting @file{text.pdf}.
300 @node How to write input files
301 @section How to write input files
307 * Working on input files::
311 @node Simple notation
312 @subsection Simple notation
314 @cindex simple notation
315 @cindex notation, simple
317 LilyPond will add some notation elements automatically. In the
318 next example, we have only specified four pitches, but LilyPond
319 has added a clef, time signature, and rhythms.
321 @lilypond[verbatim,quote]
328 This behavior may be altered, but in most cases these automatic
335 @cindex relative mode
336 @cindex quote, single
338 @cindex accidentals and relative mode
339 @cindex relative mode, and accidentals
346 Music Glossary: @rglos{pitch}, @rglos{interval},
347 @rglos{scale}, @rglos{middle C}, @rglos{octave},
350 The easiest way to enter notes is by using @code{\relative} mode.
351 In this mode, the octave is chosen automatically by assuming the
352 following note is always to be placed closest to the previous
353 note, i.e., it is to be placed in the octave which is within three
354 staff spaces of the previous note. We begin by entering the most
355 elementary piece of music, a @notation{scale}, in which every note
356 is within just one staff space of the previous note.
358 @lilypond[verbatim,quote]
359 % set the starting point to middle C
366 The initial note is @notation{middle C}. Each successive note is
367 placed closest to the previous note -- in other words, the first
368 @code{c} is the closest C to middle C. This is followed by the
369 closest D to the previous note. We can create melodies which have
370 larger intervals, still using only @code{\relative} mode:
372 @lilypond[verbatim,quote]
380 It is not necessary for the first note of the melody to start on
381 the note which specifies the starting pitch. In the previous
382 example, the first note -- the @code{d} -- is the closest D to
385 By adding (or removing) quotes @code{'} or commas @code{,} from
386 the @code{@w{\relative c' @{}} command, we can change the starting
389 @lilypond[verbatim,quote]
390 % one octave above middle C
396 Relative mode can be confusing initially, but is the easiest way
397 to enter most melodies. Let us see how this relative calculation
398 works in practice. Starting from a B, which is on the middle line
399 in a treble clef, you can reach a C, D and E within 3 staff spaces
400 going up, and an A, G and F within 3 staff spaces going down. So
401 if the note following a B is a C, D or E it will be assumed to be
402 above the B, and an A, G or F will be assumed to be below.
404 @lilypond[verbatim,quote]
406 b c % c is 1 staff space up, so is the c above
407 b d % d is 2 up or 5 down, so is the d above
408 b e % e is 3 up or 4 down, so is the e above
409 b a % a is 6 up or 1 down, so is the a below
410 b g % g is 5 up or 2 down, so is the g below
411 b f % f is 4 up or 3 down, so is the f below
415 Exactly the same happens even when any of these notes are
416 sharpened or flattened. @notation{Accidentals} are
417 @strong{totally ignored} in the calculation of relative position.
418 Precisely the same staff space counting is done from a note at any
419 other position on the staff.
421 To add intervals that are larger than three staff spaces, we can
422 raise the @notation{octave} by adding a single quote @code{'} (or
423 apostrophe) to the note name. We can lower the octave by adding a
424 comma @code{,} to the note name.
426 @lilypond[verbatim,quote]
434 To change a note by two (or more!) octaves, we use multiple
435 @code{''} or @code{,,} -- but be careful that you use two single
436 quotes @code{''} and not one double quote @code{"}@tie{}! The
437 initial value in @code{@w{\relative c'}} may also be modified like
439 @c " - keeps quotes in order for context-sensitive editor -td
441 @subheading Durations (rhythms)
443 @cindex note durations
450 @cindex notating durations
452 Music Glossary: @rglos{beam}, @rglos{duration},
453 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
456 The @notation{duration} of a note is specified by a number after
457 the note name: @code{1} for a @notation{whole note}, @code{2} for
458 a @notation{half note}, @code{4} for a @notation{quarter note} and
459 so on. @notation{Beams} are added automatically.
461 If you do not specify a duration, the previous duration is used
462 for the next note. The duration of the first note defaults to a
465 @lilypond[verbatim,quote]
469 a16 a a a a32 a a a a64 a a a a a a a a2
473 To create @notation{dotted notes}, add a dot @code{.} to the
474 duration number. The duration of a dotted note must be stated
475 explicitly (i.e., with a number).
477 @lilypond[verbatim,quote]
488 @cindex notating rests
490 Music Glossary: @rglos{rest}.
492 A @notation{rest} is entered just like a note with the name
495 @lilypond[verbatim,quote]
503 @subheading Time signature
505 @cindex time signature
510 Music Glossary: @rglos{time signature}.
512 The @notation{time signature} can be set with the @code{\time}
515 @lilypond[verbatim,quote]
538 Music Glossary: @rglos{clef}.
540 The @notation{clef} can be set using the @code{\clef} command:
542 @lilypond[verbatim,quote]
556 @subheading All together
558 Here is a small example showing all these elements together:
560 @lilypond[verbatim,quote]
571 Notation Reference: @ruser{Writing pitches},
572 @ruser{Writing rhythms}, @ruser{Writing rests},
573 @ruser{Time signature}, @ruser{Clef}.
576 @node Working on input files
577 @subsection Working on input files
580 @cindex braces, curly
583 @cindex comment, line
584 @cindex block comment
585 @cindex comment, line
586 @cindex case sensitive
587 @cindex whitespace insensitive
592 @funindex %@{ ... %@}
594 LilyPond input files are similar to source files in many common
595 programming languages. They are case sensitive, and white-space
596 is generally ignored. Expressions are formed with curly braces
597 @{ @}, and comments are denoted with @code{%} or
598 @w{@code{%@{ ... %@}}}.
600 If the previous sentences sound like nonsense, don't worry! We'll
601 explain what all these terms mean:
606 @strong{Case sensitive}:
607 it matters whether you enter a letter in lower case (e.g.
608 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
609 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
610 @w{@code{@{ C D E @}}} will produce an error message.
613 @strong{Whitespace insensitive}:
614 it does not matter how many spaces (or tabs or new lines) you add.
615 @w{@code{@{ c d e @}}} means the same thing as
616 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
624 Of course, the previous example is hard to read. A good rule of
625 thumb is to indent code blocks with either a tab or two spaces:
633 However, whitespace @emph{is} required to separate many syntactical
634 elements from others. In other words, whitespace can always be
635 @emph{added}, but it cannot be @emph{eliminated}. As missing
636 whitespace can give rise to strange errors it is advisable to
637 always insert whitespace before and after every syntactic element,
638 for example, before and after every curly brace.
641 @strong{Expressions}:
642 every piece of LilyPond input needs to have @strong{@{ curly
643 braces @}} placed around the input. These braces tell LilyPond
644 that the input is a single music expression, just like parentheses
645 @code{()} in mathematics. The braces should be surrounded by a
646 space unless they are at the beginning or end of a line to avoid
649 A LilyPond command followed by a simple expression in braces (such
650 as @w{@code{\relative @{ @}}}) also counts as a single music
655 @cindex block comment
658 a comment is a remark for the human reader of the music input; it
659 is ignored while parsing, so it has no effect on the printed
660 output. There are two types of comments. The percent symbol
661 @code{%} introduces a line comment; anything after @code{%} on
662 that line is ignored. By convention, a line comment is placed
663 @emph{above} the code it refers to.
667 % this comment refers to the Bs
671 A block comment marks a whole section of music input as a comment.
672 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
673 However, block comments do not @q{nest}. This means that you
674 cannot place a block comment inside another block comment. If you
675 try, the first @code{%@}} will terminate @emph{both} block
676 comments. The following fragment shows possible uses for
680 % notes for twinkle twinkle follow
684 This line, and the notes below are ignored,
685 since they are in a block comment.
694 @node How to read the manuals
695 @section How to read the manuals
701 * Clickable examples::
702 * Keyboard navigation::
703 * Overview of manuals::
707 @node Omitting braces
708 @subsection Omitting braces
711 @cindex how to read the manual
712 @cindex manual, reading
713 @cindex reading the manual
714 @cindex examples, clickable
715 @cindex clickable examples
716 @cindex tips for constructing files
718 @cindex constructing files, tips
719 @cindex files, tips for constructing
721 LilyPond input must be surrounded by @{ @} marks or a
722 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
723 input files}. For the rest of this manual, most examples will
724 omit this. To replicate the examples, you may copy and paste the
725 displayed input, but you @strong{must} add the
726 @code{@w{\relative c'' @{ @}}} like this:
730 ... example goes here...
734 Why omit the braces? Most examples in this manual can be inserted
735 into the middle of a longer piece of music. For these examples,
736 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
737 you should not place a @code{\relative} inside another
738 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
739 around every example, you would not be able to copy a small
740 documentation example and paste it inside a longer piece of your
741 own. Most people want to add material to an existing piece, so we
742 format the manual this way.
745 @node Clickable examples
746 @subsection Clickable examples
748 @warning{This features is only available in the HTML manuals.}
750 Many people learn programs by trying and fiddling around with the
751 program. This is also possible with LilyPond. If you click on a
752 picture in the HTML version of this manual, you will see the exact
753 LilyPond input that was used to generate that image. Try it on
759 c-\markup { \bold \huge { Click here. } }
763 By cutting and pasting everything in the @qq{ly snippet} section,
764 you have a starting template for experiments. To see exactly the
765 same output (line-width and all), copy everything from @qq{Start
766 cut-&-pastable section} to the bottom of the file.
769 @node Keyboard navigation
770 @subsection Keyboard navigation
772 @warning{This features is only available in the HTML manuals.}
774 @c TODO: once this is figured out, insert it here.
776 We are currently working on this feature.
779 @node Overview of manuals
780 @subsection Overview of manuals
782 There is a lot of documentation for LilyPond. New users are
783 sometimes confused about what part(s) they should read, and
784 occasionally skip over reading vital portions.
786 @warning{Please do not skip over important parts of the
787 documentation. You will find it much harder to understand later
793 @strong{Before trying to do @emph{anything}}: read the Learning
794 manual's @ref{Tutorial}, and @ref{Common notation}. If you
795 encounter musical terms which you do not recognize, please look
796 them up in the @rglosnamed{Top, Glossary}.
799 @strong{Before trying to write a complete piece of music}: read
800 the Learning manual's @ref{Fundamental concepts}. After that, you
801 may want to look in relevant sections of the
802 @rusernamed{Top, Notation reference}.
805 @strong{Before trying to change the default output}: read the
806 Learning manual's @ref{Tweaking output}.
809 @strong{Before undertaking a large project}: read Usage document's
810 @rprogram{Suggestions for writing files}.