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
26 This section introduces @qq{compiling}---the processing of
27 LilyPond input files (written by you) to produce output files.
37 @subsection Entering input
41 @cindex example, first
42 @cindex case sensitive
44 @qq{Compiling} is the term used for processing an input file in
45 LilyPond format to produce output file(s). Output files are
46 generally PDF (for printing or viewing), MIDI (for playing), and
47 PNG (for online use). LilyPond input files are simple text files.
49 This example shows a simple input file:
57 The graphical output is:
59 @c in this case we don't want verbatim
66 @warning{Notes and lyrics in LilyPond input must always be
67 surrounded by @w{@strong{@{ curly braces @}}}. The braces
68 should also be surrounded by a space unless they are at the
69 beginning or end of a line to avoid ambiguities. They may
70 be omitted in some examples in this manual, but don't forget them
71 in your own music! For more information about the display of
72 examples in the manual, see @ref{How to read the manuals}.}
74 In addition, LilyPond input is @strong{case sensitive}.
75 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
76 produce an error message.
81 @subheading Producing output
83 @c TODO: move index entries
87 @cindex running LilyPond under MacOS X
88 @cindex MacOS X, running LilyPond
89 @cindex running LilyPond under Windows
90 @cindex Windows, running LilyPond
91 @cindex running LilyPond under Unix
92 @cindex Unix, running LilyPond
94 The method of producing output depends on your operating system
95 and the program(s) you use.
100 @ref{MacOS X, @sourceimage{logo-macosx,,,}}
101 @ref{MacOS X, MacOS X} (graphical)
104 @ref{Windows, @sourceimage{logo-windows,,,}}
105 @ref{Windows, Microsoft Windows} (graphical)
108 @ref{Command-line, @sourceimage{logo-linux,,,}
109 @sourceimage{logo-freebsd,,,}
110 @sourceimage{logo-macosx,,,}
111 @sourceimage{logo-windows,,,}
113 @ref{Command-line, All operating systems} (command-line)
117 There are several other text editors available with specific
118 support for LilyPond. For more information, see
119 @rweb{Alternate input}.
121 @warning{The first time you ever run LilyPond, it may take a
122 minute or two because all of the system fonts have to be analyzed
123 first. After this, LilyPond will be much faster!}
129 @warning{These instructions assume that you are using the LilyPond
130 application. If you are using any of the programs described in
131 @rweb{Alternate input}, please consult the documentation for
132 those programs if you have any problems.}
135 @subsubheading Step 1. Create your @file{.ly} file
137 Double click the @command{LilyPond.app}, an example file will open.
139 @sourceimage{Learning_Macos_welcome,,,}
141 From the menus along the top left of your screen, select
142 @w{@code{File > Save}}.
144 @sourceimage{Learning_Macos_Save_menu,,,}
146 Choose a name for your file, for example @file{test.ly}.
148 @sourceimage{Learning_Macos_Save_file_with_name,,,}
151 @subsubheading Step 2. Compile (with LilyPad)
153 From the same menus, select
154 @w{@code{Compile > Tyepset}}.
156 @sourceimage{Learning_Macos_Typeset_menu,,,}
158 A new window will open showing a progress log of the compilation
159 of the file you have just saved.
161 @sourceimage{Learning_Macos_Compiling_log,,,}
164 @subsubheading Step 3. View output
166 Once the compilation has finished, a PDF file will be created with
167 the same name as the original file and will be automatically
168 opened in the default PDF viewer and displayed on your screen.
170 @sourceimage{Learning_Macos_pdf_output,,,}
173 @subsubheading Other commands
175 To create new files for LilyPond, begin by selecting
176 @w{@code{File > New}}
178 @sourceimage{Learning_Macos_New_menu,,,}
180 or @w{@code{File > Open}} to open and edit existing files you have
183 @sourceimage{Learning_Macos_Open_menu,,,}
185 You must save any new edits you make to your file before you
186 @w{@code{Compile > Tyepset}} and if the PDF file is not displayed
187 check the window with the progress log for any errors.
189 If you are not using the defualt Preview PDF viewer that comes
190 with the Mac Operating system and you have the PDF file generated
191 from a previous compilation open, then any further compilations
192 may fail to generate an update PDF until you close the original.
198 @warning{These instructions assume that you are using the built-in
199 LilyPad editor. If you are using any of the programs described in
200 @rweb{Alternate input}, please consult the documentation for
201 those programs if you have any problems compiling a file.}
204 @subsubheading Step 1. Create your @file{.ly} file
206 Double-click the @command{LilyPond.app}, an example file will open.
208 @sourceimage{Learning_Win7_Welcome_File_Whole,,,}
210 From the menus that appear alonbg the top of the example file,
211 select @w{@code{File > Save as}}. Do not use the @w{@code{File > Save}}
212 for the example file as this will not work until you have given it a
213 valid Lilypong file name.
215 @sourceimage{Learning_Win7_Save_Menu,,,}
217 Choose a name for your file, for example @file{test.ly}.
219 @sourceimage{Learning_Win7_Save_File_With_Name,,,}
222 @subsubheading Step 2a. Compile (with drag-and-drop)
224 Depending on what you prefer, to compile your file either:
226 Drag-and-drop the file directly onto the LilyPond icon.
228 @sourceimage{Learning_Win7_Open_Dragndrop,,,}
230 Right-click on the file and from the pop-up context menu choose
231 @w{@code{Open with > LilyPond}}.
233 @sourceimage{Learning_Win7_Open_Context_Menu,,,}
236 @subsubheading Step 2b. Compile (with double-clicking)
238 Or simply double-click the @file{test.ly}.
241 @subsubheading Step 3. View output
243 During the compilation of the @file{test.ly} file, a command window
244 will, very briefly open and then close. Three additional files will
245 have been created during this process.
247 @sourceimage{Learning_Win7_All_Files_Created,,,}
249 The PDF file contains the engraved @file{test.ly} file.
251 @sourceimage{Learning_Win7_Pdf_Output,,,}
254 @subsubheading Other commands
256 To create a new file, begin by selecting @w{@code{File > New}} from
257 within any previously created file.
259 @sourceimage{Learning_Win7_New_Menu,,,}
262 or @w{@code{File > Open}} to open and edit any files you have saved
265 @sourceimage{Learning_Win7_Open_Menu,,,}
267 You must save any new edits you make before you compile it and if the
268 PDF file is not created, check the log file that will have been created
269 during the compilation attempt, for any errors.
271 @sourceimage{Learning_Win7_Log_File,,,}
273 This log file is overwritten each time you compile your LilyPond file.
275 The PS file is used internally by LilyPond to create the PDF file and
276 can be ignored. It also gets overwritten each time you compile your
279 If you are viewing your file in a PDF viewer, then you must close the
280 PDF if you wish to make a new compilation as it may fail to create
281 the new PDF while it is still being viewed.
285 @subsection Command-line
287 @warning{These instructions assume that you are familiar with
288 command-line programs. If you are using any of the programs
289 described in @rweb{Alternate input}, please consult the
290 documentation for those programs if you have any problems
294 @subsubheading Step 1. Create your @file{.ly} file
296 Create a text file called @file{test.ly} and enter:
305 @subsubheading Step 2. Compile (with command-line)
307 To process @file{test.ly}, proceed as follows:
314 You will see something resembling:
318 GNU LilyPond @version{}
321 Interpreting music...
322 Preprocessing graphical objects...
323 Finding the ideal number of pages...
324 Fitting music on 1 page...
326 Layout output to `test.ps'...
327 Converting to `test.pdf'...
330 @subsubheading Step 3. View output
332 You may view or print the resulting @file{text.pdf}.
335 @node How to write input files
336 @section How to write input files
338 This section introduces some basic LilyPond syntax to help get you
339 started writing input files.
343 * Working on input files::
347 @node Simple notation
348 @subsection Simple notation
350 @cindex simple notation
351 @cindex notation, simple
353 LilyPond will add some notation elements automatically. In the
354 next example, we have only specified four pitches, but LilyPond
355 has added a clef, time signature, and rhythms.
357 @lilypond[verbatim,quote]
364 This behavior may be altered, but in most cases these automatic
371 @cindex relative mode
372 @cindex quote, single
374 @cindex accidentals and relative mode
375 @cindex relative mode, and accidentals
382 Music Glossary: @rglos{pitch}, @rglos{interval},
383 @rglos{scale}, @rglos{middle C}, @rglos{octave},
386 The easiest way to enter notes is by using @code{\relative} mode.
387 In this mode, the octave is chosen automatically by assuming the
388 following note is always to be placed closest to the previous
389 note, i.e., it is to be placed in the octave which is within three
390 staff spaces of the previous note. We begin by entering the most
391 elementary piece of music, a @notation{scale}, in which every note
392 is within just one staff space of the previous note.
394 @lilypond[verbatim,quote]
395 % set the starting point to middle C
402 The initial note is @notation{middle C}. Each successive note is
403 placed closest to the previous note -- in other words, the first
404 @code{c} is the closest C to middle C. This is followed by the
405 closest D to the previous note. We can create melodies which have
406 larger intervals, still using only @code{\relative} mode:
408 @lilypond[verbatim,quote]
416 It is not necessary for the first note of the melody to start on
417 the note which specifies the starting pitch. In the previous
418 example, the first note -- the @code{d} -- is the closest D to
421 By adding (or removing) quotes @code{'} or commas @code{,} from
422 the @code{@w{\relative c' @{}} command, we can change the starting
425 @lilypond[verbatim,quote]
426 % one octave above middle C
432 Relative mode can be confusing initially, but is the easiest way
433 to enter most melodies. Let us see how this relative calculation
434 works in practice. Starting from a B, which is on the middle line
435 in a treble clef, you can reach a C, D and E within 3 staff spaces
436 going up, and an A, G and F within 3 staff spaces going down. So
437 if the note following a B is a C, D or E it will be assumed to be
438 above the B, and an A, G or F will be assumed to be below.
440 @lilypond[verbatim,quote]
442 b c % c is 1 staff space up, so is the c above
443 b d % d is 2 up or 5 down, so is the d above
444 b e % e is 3 up or 4 down, so is the e above
445 b a % a is 6 up or 1 down, so is the a below
446 b g % g is 5 up or 2 down, so is the g below
447 b f % f is 4 up or 3 down, so is the f below
451 Exactly the same happens even when any of these notes are
452 sharpened or flattened. @notation{Accidentals} are
453 @strong{totally ignored} in the calculation of relative position.
454 Precisely the same staff space counting is done from a note at any
455 other position on the staff.
457 To add intervals that are larger than three staff spaces, we can
458 raise the @notation{octave} by adding a single quote @code{'} (or
459 apostrophe) to the note name. We can lower the octave by adding a
460 comma @code{,} to the note name.
462 @lilypond[verbatim,quote]
470 To change a note by two (or more!) octaves, we use multiple
471 @code{''} or @code{,,} -- but be careful that you use two single
472 quotes @code{''} and not one double quote @code{"}@tie{}! The
473 initial value in @code{@w{\relative c'}} may also be modified like
475 @c " - keeps quotes in order for context-sensitive editor -td
477 @subheading Durations (rhythms)
479 @cindex note durations
486 @cindex notating durations
488 Music Glossary: @rglos{beam}, @rglos{duration},
489 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
492 The @notation{duration} of a note is specified by a number after
493 the note name: @code{1} for a @notation{whole note}, @code{2} for
494 a @notation{half note}, @code{4} for a @notation{quarter note} and
495 so on. @notation{Beams} are added automatically.
497 If you do not specify a duration, the previous duration is used
498 for the next note. The duration of the first note defaults to a
501 @lilypond[verbatim,quote]
505 a16 a a a a32 a a a a64 a a a a a a a a2
509 To create @notation{dotted notes}, add a dot @code{.} to the
510 duration number. The duration of a dotted note must be stated
511 explicitly (i.e., with a number).
513 @lilypond[verbatim,quote]
524 @cindex notating rests
526 Music Glossary: @rglos{rest}.
528 A @notation{rest} is entered just like a note with the name
531 @lilypond[verbatim,quote]
539 @subheading Time signature
541 @cindex time signature
546 Music Glossary: @rglos{time signature}.
548 The @notation{time signature} can be set with the @code{\time}
551 @lilypond[verbatim,quote]
574 Music Glossary: @rglos{clef}.
576 The @notation{clef} can be set using the @code{\clef} command:
578 @lilypond[verbatim,quote]
592 @subheading All together
594 Here is a small example showing all these elements together:
596 @lilypond[verbatim,quote]
607 Notation Reference: @ruser{Writing pitches},
608 @ruser{Writing rhythms}, @ruser{Writing rests},
609 @ruser{Time signature}, @ruser{Clef}.
612 @node Working on input files
613 @subsection Working on input files
616 @cindex braces, curly
619 @cindex comment, line
620 @cindex block comment
621 @cindex comment, line
622 @cindex case sensitive
623 @cindex whitespace insensitive
628 @funindex %@{ ... %@}
630 LilyPond input files are similar to source files in many common
631 programming languages. They are case sensitive, and white-space
632 is generally ignored. Expressions are formed with curly braces
633 @{ @}, and comments are denoted with @code{%} or
634 @w{@code{%@{ ... %@}}}.
636 If the previous sentences sound like nonsense, don't worry! We'll
637 explain what all these terms mean:
642 @strong{Case sensitive}:
643 it matters whether you enter a letter in lower case (e.g.
644 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
645 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
646 @w{@code{@{ C D E @}}} will produce an error message.
649 @strong{Whitespace insensitive}:
650 it does not matter how many spaces (or tabs or new lines) you add.
651 @w{@code{@{ c d e @}}} means the same thing as
652 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
660 Of course, the previous example is hard to read. A good rule of
661 thumb is to indent code blocks with either a tab or two spaces:
669 However, whitespace @emph{is} required to separate many syntactical
670 elements from others. In other words, whitespace can always be
671 @emph{added}, but it cannot be @emph{eliminated}. As missing
672 whitespace can give rise to strange errors it is advisable to
673 always insert whitespace before and after every syntactic element,
674 for example, before and after every curly brace.
677 @strong{Expressions}:
678 every piece of LilyPond input needs to have @strong{@{ curly
679 braces @}} placed around the input. These braces tell LilyPond
680 that the input is a single music expression, just like parentheses
681 @code{()} in mathematics. The braces should be surrounded by a
682 space unless they are at the beginning or end of a line to avoid
685 A LilyPond command followed by a simple expression in braces (such
686 as @w{@code{\relative @{ @}}}) also counts as a single music
691 @cindex block comment
694 a comment is a remark for the human reader of the music input; it
695 is ignored while parsing, so it has no effect on the printed
696 output. There are two types of comments. The percent symbol
697 @code{%} introduces a line comment; anything after @code{%} on
698 that line is ignored. By convention, a line comment is placed
699 @emph{above} the code it refers to.
703 % this comment refers to the Bs
707 A block comment marks a whole section of music input as a comment.
708 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
709 However, block comments do not @q{nest}. This means that you
710 cannot place a block comment inside another block comment. If you
711 try, the first @code{%@}} will terminate @emph{both} block
712 comments. The following fragment shows possible uses for
716 % notes for twinkle twinkle follow
720 This line, and the notes below are ignored,
721 since they are in a block comment.
730 @node How to read the manuals
731 @section How to read the manuals
733 This section shows how to read the documentation efficiently, and
734 also introduces some useful interactive features available in the
739 * Clickable examples::
740 * Keyboard navigation::
741 * Overview of manuals::
745 @node Omitting braces
746 @subsection Omitting braces
749 @cindex how to read the manual
750 @cindex manual, reading
751 @cindex reading the manual
752 @cindex examples, clickable
753 @cindex clickable examples
754 @cindex tips for constructing files
756 @cindex constructing files, tips
757 @cindex files, tips for constructing
759 LilyPond input must be surrounded by @{ @} marks or a
760 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
761 input files}. For the rest of this manual, most examples will
762 omit this. To replicate the examples, you may copy and paste the
763 displayed input, but you @strong{must} add the
764 @code{@w{\relative c'' @{ @}}} like this:
768 ... example goes here...
772 Why omit the braces? Most examples in this manual can be inserted
773 into the middle of a longer piece of music. For these examples,
774 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
775 you should not place a @code{\relative} inside another
776 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
777 around every example, you would not be able to copy a small
778 documentation example and paste it inside a longer piece of your
779 own. Most people want to add material to an existing piece, so we
780 format the manual this way.
783 @node Clickable examples
784 @subsection Clickable examples
786 @warning{This features is only available in the HTML manuals.}
788 Many people learn programs by trying and fiddling around with the
789 program. This is also possible with LilyPond. If you click on a
790 picture in the HTML version of this manual, you will see the exact
791 LilyPond input that was used to generate that image. Try it on
797 c-\markup { \bold \huge { Click here. } }
801 By cutting and pasting everything in the @qq{ly snippet} section,
802 you have a starting template for experiments. To see exactly the
803 same output (line-width and all), copy everything from @qq{Start
804 cut-&-pastable section} to the bottom of the file.
807 @node Keyboard navigation
808 @subsection Keyboard navigation
810 @warning{This features is only available in the HTML manuals.}
812 @c TODO: once this is figured out, insert it here.
814 We are currently working on this feature.
817 @node Overview of manuals
818 @subsection Overview of manuals
820 There is a lot of documentation for LilyPond. New users are
821 sometimes confused about what part(s) they should read, and
822 occasionally skip over reading vital portions.
824 @warning{Please do not skip over important parts of the
825 documentation. You will find it much harder to understand later
831 @strong{Before trying to do @emph{anything}}: read the Learning
832 manual's @ref{Tutorial}, and @ref{Common notation}. If you
833 encounter musical terms which you do not recognize, please look
834 them up in the @rglosnamed{Top, Glossary}.
837 @strong{Before trying to write a complete piece of music}: read
838 the Learning manual's @ref{Fundamental concepts}. After that, you
839 may want to look in relevant sections of the
840 @rusernamed{Top, Notation reference}.
843 @strong{Before trying to change the default output}: read the
844 Learning manual's @ref{Tweaking output}.
847 @strong{Before undertaking a large project}: read Usage document's
848 @rprogram{Suggestions for writing files}.