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:
52 \version "@w{@version{}}"
58 The graphical output is:
60 @c in this case we don't want verbatim
67 @warning{Notes and lyrics in LilyPond input must always be
68 surrounded by @w{@strong{@{ curly braces @}}}. The braces
69 should also be surrounded by a space unless they are at the
70 beginning or end of a line to avoid ambiguities. They may
71 be omitted in some examples in this manual, but don't forget them
72 in your own music! For more information about the display of
73 examples in the manual, see @ref{How to read the manuals}.}
75 In addition, LilyPond input is @strong{case sensitive}.
76 @w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
77 produce an error message.
82 @subheading Producing output
88 The method of producing output depends on your operating system
89 and the program(s) you use.
94 @ref{MacOS X, @sourceimage{logo-macosx,,,}}
95 @ref{MacOS X, MacOS X} (graphical)
98 @ref{Windows, @sourceimage{logo-windows,,,}}
99 @ref{Windows, Microsoft Windows} (graphical)
102 @ref{Command-line, @sourceimage{logo-linux,,,}
103 @sourceimage{logo-freebsd,,,}
104 @sourceimage{logo-macosx,,,}
105 @sourceimage{logo-windows,,,}
107 @ref{Command-line, All operating systems} (command-line)
111 There are several other text editors available with specific
112 support for LilyPond. For more information, see
113 @rweb{Alternate input}.
115 @warning{The first time you ever run LilyPond, it may take a
116 minute or two because all of the system fonts have to be analyzed
117 first. After this, LilyPond will be much faster!}
119 @cindex running LilyPond under MacOS X
120 @cindex MacOS X, running LilyPond
125 @warning{These instructions assume that you are using the LilyPond
126 application. If you are using any of the programs described in
127 @rweb{Alternate input}, please consult the documentation for
128 those programs if you have any problems.}
131 @subsubheading Step 1. Create your @file{.ly} file
133 Double click the @command{LilyPond.app}, an example file will open.
135 @sourceimage{Learning_Macos_welcome,,,}
137 From the menus along the top left of your screen, select
138 @w{@code{File > Save}}.
140 @sourceimage{Learning_Macos_Save_menu,,,}
142 Choose a name for your file, for example @file{test.ly}.
144 @sourceimage{Learning_Macos_Save_file_with_name,,,}
147 @subsubheading Step 2. Compile (with LilyPad)
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,,,}
160 @subsubheading Step 3. View output
162 Once the compilation has finished, a PDF file will be created with
163 the same name as the original file and will be automatically
164 opened in the default PDF viewer and displayed on your screen.
166 @sourceimage{Learning_Macos_pdf_output,,,}
169 @subsubheading Other commands
171 To create new files for LilyPond, begin by selecting
172 @w{@code{File > New}}
174 @sourceimage{Learning_Macos_New_menu,,,}
176 or @w{@code{File > Open}} to open and edit existing files you have
179 @sourceimage{Learning_Macos_Open_menu,,,}
181 You must save any new edits you make to your file before you
182 @w{@code{Compile > Tyepset}} and if the PDF file is not displayed
183 check the window with the progress log for any errors.
185 If you are not using the defualt Preview PDF viewer that comes
186 with the Mac Operating system and you have the PDF file generated
187 from a previous compilation open, then any further compilations
188 may fail to generate an update PDF until you close the original.
190 @cindex running LilyPond under Windows
191 @cindex Windows, running LilyPond
196 @warning{These instructions assume that you are using the built-in
197 LilyPad editor. If you are using any of the programs described in
198 @rweb{Alternate input}, please consult the documentation for
199 those programs if you have any problems compiling a file.}
202 @subsubheading Step 1. Create your @file{.ly} file
204 Double-click the @command{LilyPond.app}, an example file will open.
206 @sourceimage{Learning_Win7_Welcome_File_Whole,,,}
208 From the menus that appear alonbg the top of the example file,
209 select @w{@code{File > Save as}}. Do not use the @w{@code{File > Save}}
210 for the example file as this will not work until you have given it a
211 valid Lilypong file name.
213 @sourceimage{Learning_Win7_Save_Menu,,,}
215 Choose a name for your file, for example @file{test.ly}.
217 @sourceimage{Learning_Win7_Save_File_With_Name,,,}
220 @subsubheading Step 2a. Compile (with drag-and-drop)
222 Depending on what you prefer, to compile your file either:
224 Drag-and-drop the file directly onto the LilyPond icon.
226 @sourceimage{Learning_Win7_Open_Dragndrop,,,}
228 Right-click on the file and from the pop-up context menu choose
229 @w{@code{Open with > LilyPond}}.
231 @sourceimage{Learning_Win7_Open_Context_Menu,,,}
234 @subsubheading Step 2b. Compile (with double-clicking)
236 Or simply double-click the @file{test.ly}.
239 @subsubheading Step 3. View output
241 During the compilation of the @file{test.ly} file, a command window
242 will, very briefly open and then close. Three additional files will
243 have been created during this process.
245 @sourceimage{Learning_Win7_All_Files_Created,,,}
247 The PDF file contains the engraved @file{test.ly} file.
249 @sourceimage{Learning_Win7_Pdf_Output,,,}
252 @subsubheading Other commands
254 To create a new file, begin by selecting @w{@code{File > New}} from
255 within any previously created file.
257 @sourceimage{Learning_Win7_New_Menu,,,}
260 or @w{@code{File > Open}} to open and edit any files you have saved
263 @sourceimage{Learning_Win7_Open_Menu,,,}
265 You must save any new edits you make before you compile it and if the
266 PDF file is not created, check the log file that will have been created
267 during the compilation attempt, for any errors.
269 @sourceimage{Learning_Win7_Log_File,,,}
271 This log file is overwritten each time you compile your LilyPond file.
273 The PS file is used internally by LilyPond to create the PDF file and
274 can be ignored. It also gets overwritten each time you compile your
277 If you are viewing your file in a PDF viewer, then you must close the
278 PDF if you wish to make a new compilation as it may fail to create
279 the new PDF while it is still being viewed.
281 @cindex running LilyPond under Unix
282 @cindex Unix, running LilyPond
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:
299 \version "@w{@version{}}"
306 @subsubheading Step 2. Compile (with command-line)
308 To process @file{test.ly}, type the following at the command prompt:
315 You will see something resembling:
318 GNU LilyPond @version{}
321 Interpreting music...
322 Preprocessing graphical objects...
323 Solving 1 page-breaking chunks...[1: 1 pages]
325 Layout output to `test.ps'...
326 Converting to `./test.pdf'...
329 @subsubheading Step 3. View output
331 You may view or print the resulting @file{text.pdf}.
334 @node How to write input files
335 @section How to write input files
337 This section introduces some basic LilyPond syntax to help get you
338 started writing input files.
342 * Working on input files::
346 @node Simple notation
347 @subsection Simple notation
349 @cindex simple notation
350 @cindex notation, simple
352 LilyPond will add some notation elements automatically. In the
353 next example, we have only specified four pitches, but LilyPond
354 has added a clef, time signature, and rhythms.
356 @lilypond[verbatim,quote]
363 This behavior may be altered, but in most cases these automatic
370 @cindex relative mode
371 @cindex quote, single
373 @cindex accidentals and relative mode
374 @cindex relative mode, and accidentals
381 Music Glossary: @rglos{pitch}, @rglos{interval},
382 @rglos{scale}, @rglos{middle C}, @rglos{octave},
385 The easiest way to enter notes is by using @code{\relative} mode.
386 In this mode, the octave is chosen automatically by assuming the
387 following note is always to be placed closest to the previous
388 note, i.e., it is to be placed in the octave which is within three
389 staff spaces of the previous note. We begin by entering the most
390 elementary piece of music, a @notation{scale}, in which every note
391 is within just one staff space of the previous note.
393 @lilypond[verbatim,quote]
394 % set the starting point to middle C
401 The initial note is @notation{middle C}. Each successive note is
402 placed closest to the previous note -- in other words, the first
403 @code{c} is the closest C to middle C. This is followed by the
404 closest D to the previous note. We can create melodies which have
405 larger intervals, still using only @code{\relative} mode:
407 @lilypond[verbatim,quote]
415 It is not necessary for the first note of the melody to start on
416 the note which specifies the starting pitch. In the previous
417 example, the first note -- the @code{d} -- is the closest D to
420 By adding (or removing) quotes @code{'} or commas @code{,} from
421 the @code{@w{\relative c' @{}} command, we can change the starting
424 @lilypond[verbatim,quote]
425 % one octave above middle C
431 Relative mode can be confusing initially, but is the easiest way
432 to enter most melodies. Let us see how this relative calculation
433 works in practice. Starting from a B, which is on the middle line
434 in a treble clef, you can reach a C, D and E within 3 staff spaces
435 going up, and an A, G and F within 3 staff spaces going down. So
436 if the note following a B is a C, D or E it will be assumed to be
437 above the B, and an A, G or F will be assumed to be below.
439 @lilypond[verbatim,quote]
441 b c % c is 1 staff space up, so is the c above
442 b d % d is 2 up or 5 down, so is the d above
443 b e % e is 3 up or 4 down, so is the e above
444 b a % a is 6 up or 1 down, so is the a below
445 b g % g is 5 up or 2 down, so is the g below
446 b f % f is 4 up or 3 down, so is the f below
450 Exactly the same happens even when any of these notes are
451 sharpened or flattened. @notation{Accidentals} are
452 @strong{totally ignored} in the calculation of relative position.
453 Precisely the same staff space counting is done from a note at any
454 other position on the staff.
456 To add intervals that are larger than three staff spaces, we can
457 raise the @notation{octave} by adding a single quote @code{'} (or
458 apostrophe) to the note name. We can lower the octave by adding a
459 comma @code{,} to the note name.
461 @lilypond[verbatim,quote]
469 To change a note by two (or more!) octaves, we use multiple
470 @code{''} or @code{,,} -- but be careful that you use two single
471 quotes @code{''} and not one double quote @code{"}@tie{}! The
472 initial value in @code{@w{\relative c'}} may also be modified like
474 @c " - keeps quotes in order for context-sensitive editor -td
476 @subheading Durations (rhythms)
478 @cindex note durations
485 @cindex notating durations
487 Music Glossary: @rglos{beam}, @rglos{duration},
488 @rglos{whole note}, @rglos{half note}, @rglos{quarter note},
491 The @notation{duration} of a note is specified by a number after
492 the note name: @code{1} for a @notation{whole note}, @code{2} for
493 a @notation{half note}, @code{4} for a @notation{quarter note} and
494 so on. @notation{Beams} are added automatically.
496 If you do not specify a duration, the previous duration is used
497 for the next note. The duration of the first note defaults to a
500 @lilypond[verbatim,quote]
504 a16 a a a a32 a a a a64 a a a a a a a a2
508 To create @notation{dotted notes}, add a dot @code{.} to the
509 duration number. The duration of a dotted note must be stated
510 explicitly (i.e., with a number).
512 @lilypond[verbatim,quote]
523 @cindex notating rests
525 Music Glossary: @rglos{rest}.
527 A @notation{rest} is entered just like a note with the name
530 @lilypond[verbatim,quote]
538 @subheading Time signature
540 @cindex time signature
545 Music Glossary: @rglos{time signature}.
547 The @notation{time signature} can be set with the @code{\time}
550 @lilypond[verbatim,quote]
573 Music Glossary: @rglos{clef}.
575 The @notation{clef} can be set using the @code{\clef} command:
577 @lilypond[verbatim,quote]
591 @subheading All together
593 Here is a small example showing all these elements together:
595 @lilypond[verbatim,quote]
606 Notation Reference: @ruser{Writing pitches},
607 @ruser{Writing rhythms}, @ruser{Writing rests},
608 @ruser{Time signature}, @ruser{Clef}.
611 @node Working on input files
612 @subsection Working on input files
615 @cindex braces, curly
618 @cindex comment, line
619 @cindex block comment
620 @cindex comment, line
621 @cindex case sensitive
622 @cindex whitespace insensitive
626 @cindex version number
631 @funindex %@{ ... %@}
633 LilyPond input files are similar to source files in many common
634 programming languages. They contain a version statement,
635 are case sensitive, and white-space
636 is generally ignored. Expressions are formed with curly braces
637 @{ @}, and comments are denoted with @code{%} or
638 @w{@code{%@{ ... %@}}}.
640 If the previous sentences sound like nonsense, don't worry! We'll
641 explain what all these terms mean:
646 @strong{Version statement}:
647 Every LilyPond file should contain a version statement. A version
648 statement is a line that describes the version of LilyPond for which
649 the file was written, as in the following example:
652 \version "@w{@version{}}"
655 By convention, the version statement is placed at the top of the
658 The version statement is important for at least two reasons. First,
659 it allows automatic updating of the input file as LilyPond syntax
660 changes. Second, it describes the version of LilyPond needed to
663 If the version statement is omitted from an input file, LilyPond will print
664 a warning during the compilation of the file.
667 @strong{Case sensitive}:
668 it matters whether you enter a letter in lower case (e.g.
669 @w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
670 Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
671 @w{@code{@{ C D E @}}} will produce an error message.
674 @strong{Whitespace insensitive}:
675 it does not matter how many spaces (or tabs or new lines) you add.
676 @w{@code{@{ c d e @}}} means the same thing as
677 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
685 Of course, the previous example is hard to read. A good rule of
686 thumb is to indent code blocks with either a tab or two spaces:
694 However, whitespace @emph{is} required to separate many syntactical
695 elements from others. In other words, whitespace can always be
696 @emph{added}, but it cannot be @emph{eliminated}. As missing
697 whitespace can give rise to strange errors it is advisable to
698 always insert whitespace before and after every syntactic element,
699 for example, before and after every curly brace.
702 @strong{Expressions}:
703 every piece of LilyPond input needs to have @strong{@{ curly
704 braces @}} placed around the input. These braces tell LilyPond
705 that the input is a single music expression, just like parentheses
706 @code{()} in mathematics. The braces should be surrounded by a
707 space unless they are at the beginning or end of a line to avoid
710 A LilyPond command followed by a simple expression in braces (such
711 as @w{@code{\relative @{ @}}}) also counts as a single music
716 @cindex block comment
719 a comment is a remark for the human reader of the music input; it
720 is ignored while parsing, so it has no effect on the printed
721 output. There are two types of comments. The percent symbol
722 @code{%} introduces a line comment; anything after @code{%} on
723 that line is ignored. By convention, a line comment is placed
724 @emph{above} the code it refers to.
728 % this comment refers to the Bs
732 A block comment marks a whole section of music input as a comment.
733 Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
734 However, block comments do not @q{nest}. This means that you
735 cannot place a block comment inside another block comment. If you
736 try, the first @code{%@}} will terminate @emph{both} block
737 comments. The following fragment shows possible uses for
741 % notes for twinkle twinkle follow
745 This line, and the notes below are ignored,
746 since they are in a block comment.
755 @node How to read the manuals
756 @section How to read the manuals
758 This section shows how to read the documentation efficiently, and
759 also introduces some useful interactive features available in the
764 * Clickable examples::
765 * Keyboard navigation::
766 * Overview of manuals::
770 @node Omitted material
771 @subsection Omitted material
774 @cindex how to read the manual
775 @cindex manual, reading
776 @cindex reading the manual
777 @cindex examples, clickable
778 @cindex clickable examples
779 @cindex tips for constructing files
781 @cindex constructing files, tips
782 @cindex files, tips for constructing
784 LilyPond input must be surrounded by @{ @} marks or a
785 @code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
786 input files}. For the rest of this manual, most examples will
787 omit this. To replicate the examples, you may copy and paste the
788 displayed input, but you @strong{must} add the
789 @code{@w{\relative c'' @{ @}}} like this:
793 ... example goes here...
797 Why omit the braces? Most examples in this manual can be inserted
798 into the middle of a longer piece of music. For these examples,
799 it does not make sense to add @code{@w{\relative c'' @{ @}}} --
800 you should not place a @code{\relative} inside another
801 @code{\relative}! If we included @code{@w{\relative c'' @{ @}}}
802 around every example, you would not be able to copy a small
803 documentation example and paste it inside a longer piece of your
804 own. Most people want to add material to an existing piece, so we
805 format the manual this way.
807 Also, remember that every LilyPond file should have a @code{@bs{}version}
808 statement. Because the examples in the manuals are snippets, not files,
809 the @code{@bs{}version} statement is omitted. But you should make a
810 practice of including them in your files.
812 @node Clickable examples
813 @subsection Clickable examples
815 @warning{This features is only available in the HTML manuals.}
817 Many people learn programs by trying and fiddling around with the
818 program. This is also possible with LilyPond. If you click on a
819 picture in the HTML version of this manual, you will see the exact
820 LilyPond input that was used to generate that image. Try it on
826 c-\markup { \bold \huge { Click here. } }
830 By cutting and pasting everything in the @qq{ly snippet} section,
831 you have a starting template for experiments. To see exactly the
832 same output (line-width and all), copy everything from @qq{Start
833 cut-&-pastable section} to the bottom of the file.
836 @node Keyboard navigation
837 @subsection Keyboard navigation
839 @warning{This features is only available in the HTML manuals.}
841 @c TODO: once this is figured out, insert it here.
843 We are currently working on this feature.
846 @node Overview of manuals
847 @subsection Overview of manuals
849 There is a lot of documentation for LilyPond. New users are
850 sometimes confused about what part(s) they should read, and
851 occasionally skip over reading vital portions.
853 @warning{Please do not skip over important parts of the
854 documentation. You will find it much harder to understand later
860 @strong{Before trying to do @emph{anything}}: read the Learning
861 manual's @ref{Tutorial}, and @ref{Common notation}. If you
862 encounter musical terms which you do not recognize, please look
863 them up in the @rglosnamed{Top, Glossary}.
866 @strong{Before trying to write a complete piece of music}: read
867 the Learning manual's @ref{Fundamental concepts}. After that, you
868 may want to look in relevant sections of the
869 @rusernamed{Top, Notation reference}.
872 @strong{Before trying to change the default output}: read the
873 Learning manual's @ref{Tweaking output}.
876 @strong{Before undertaking a large project}: read Usage document's
877 @rprogram{Suggestions for writing files}.