X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=d1b5eb467ce88abdbc56e770421370dd92925f59;hb=e0178d3266687ced7da5602419c10e8e11791f98;hp=f5a3d076b511120b32c3b4777f0ecd09fc7cf707;hpb=38cb4178d57c3d964f5e4187be34d7372b4a646b;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index f5a3d076b5..446ae6e672 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,1164 +1,1206 @@ @c -*- coding: utf-8; mode: texinfo; -*- -@c This file is part of lilypond.tely +@c This file is part of lilypond-learning.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH -@c TODO: -@c * more details about running lilypond; error messages, -@c compiling/viewing (emacs?) -@c * where to go from First steps+More basics? + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore -@c wherever possible, do not include index entries here; the -@c index should point to stuff in the reference manual. -gp +@ignore -@c Your first LilyPond score in 10 minutes? +Tutorial Specification: -@node Tutorial -@chapter Tutorial +The LM is written in a tutorial style which introduces the +most important concepts, structure and syntax of the +elements of a LilyPond score in a carefully graded sequence +of steps. Explanations of all musical concepts used in the +Manual can be found in the Music Glossary, and readers are +assumed to have no prior knowledge of LilyPond. The +objective is to take readers to a level where the Notation +Reference can be understood and employed to both adapt the +templates in the Appendix to their needs and to begin to +construct their own. Commonly used tweaks are introduced +and explained. Examples are provided throughout which, +while being focussed on the topic being introduced, are long +enough to seem real in order to retain the readers' +interest. Each example builds on the previous material, and +comments are used liberally. Every new aspect is thoroughly +explained before it is used. -This tutorial starts with an introduction to the LilyPond music -language and how to produce printed music. After this first contact we -will explain how to create common musical notation. +@end ignore -@ifhtml -Many people learn programs by trying and fiddling around with the -program. This is also possible with LilyPond. If you click on a -picture in the HTML version of this manual, you will see the exact -LilyPond input that was used to generate that image. -Try it on this image +@ignore +Tutorial guidelines: (different from policy.txt!) +- unless you have a really good reason, use either + @lilypond[verbatim,quote,ragged-right] + or + @lilypond[verbatim,quote,ragged-right,fragment,relative=2] -@lilypond[fragment,quote,ragged-right,relative=2] -c-\markup { \bold \huge { Click here. } } -@end lilypond -@end ifhtml + Don't use any other relative=X commands (make it a non-fragment + example), and don't use fragment without relative=2. + +- use "aes" and "ees" instead of "as" and "es". I know it's not + correct Dutch naming, but let's not confuse people with this + until we get to the Basic notation chapter. -By cutting and pasting the full input into a test file, you have a -starting template for experiments. If you like learning in this way, -you will probably want to print out or bookmark -@ifhtml -the -@end ifhtml -@ref{Cheat sheet}, which is a table listing of the most common -commands for quick reference. +- Add "Music glossary: @rglos{foo}" to the _top_ of the relevant + portions of the tutorial. + +@end ignore + + +@node Tutorial +@chapter Tutorial + +This tutorial starts with an introduction to the LilyPond music +language and how to produce printed music. After this first +contact we will explain how to create common musical notation. @menu * First steps:: -* Second steps:: -* More about pitches:: -* Entering ties:: -* Automatic and manual beams:: -* Octave entry:: -* Music expressions explained:: -* More staves:: -* Adding articulation marks to notes:: -* Combining notes into chords:: -* Advanced rhythmic commands:: -* Commenting input files:: -* Printing lyrics:: -* A lead sheet:: -* Adding titles:: -* Single staff polyphony:: -* Piano staves:: -* Organizing larger pieces:: -* An orchestral part:: -* After the tutorial:: +* Single staff notation:: +* Multiple notes at once:: +* Songs:: +* Final touches:: @end menu @node First steps @section First steps -The first example demonstrates how to enter the most elementary piece -of music, a @rglos{scale}. A @rglos{note} can be entered by typing its -name, from @samp{a} through @samp{g}. So, if you enter +This section gives a basic introduction to working with LilyPond. + +@menu +* Compiling a file:: +* Simple notation:: +* Working on text files:: +* How to read the tutorial:: +@end menu + + +@node Compiling a file +@subsection Compiling a file + +The first example demonstrates how to start working with LilyPond. +To create sheet music, we write a text file that specifies the +notation. For example, if we write: @example @{ -c' d' e' f' g' a' b' c'' + c' e' g' e' @} @end example @noindent -the result looks like this +the result looks like this: -@lilypond[quote] +@c in this case we don't want verbatim +@lilypond[quote,ragged-right] { -c' d' e' f' g' a' b' c'' + c' e' g' e' } @end lilypond -@emph{Warning:} Every piece of LilyPond input needs to have -@{curly braces@} placed around the input. Don't forget them! +@warning{Every piece of LilyPond input needs to have +@strong{@{ curly braces @}} placed around the input. The braces +should also be surrounded by a space unless they are at the +beginning or end of a line to avoid ambiguities. The braces may +be omitted in some examples in this manual, but don't forget them +in your own music! For more information about the display of +examples in the manual, see @ref{How to read the tutorial}.} -@cindex Case sensitive -In addition, LilyPond input is case sensitive. @code{ @{ c d e @} } is -valid input; @code{ @{ C D E @} } will produce an error message. +@cindex case sensitive +In addition, LilyPond input is @strong{case sensitive}. @code{ +@{ c d e @}} is valid input; @code{@{ C D E @}} will produce an +error message. +@smallspace +@subheading Entering music and viewing output -@unnumberedsubsec Entering music and viewing output +@cindex PDF file +@cindex viewing music -In this section we will explain what commands to run -and how to view or print the output. +In this section we will explain what commands to run and how to +view or print the output. -@unnumberedsubsec MacOS X +Note that there are several other text editors available with +better support for LilyPond. For more information, see +@rprogram{Text editor support}. -If you double click LilyPond.app, it will open with an example -file. Save it, for example, to @file{test.ly} on your Desktop, and -then process it with the menu command @samp{Compile > Typeset File}. -The resulting PDF file will be displayed on your screen. +@warning{the first time you ever run LilyPond, it may take a +minute or two because all of the system fonts have to be analyzed +first. After this, LilyPond will be much faster!} -Be warned that the first time you ever run lilypond -will take a minute or two, because -all of the system fonts have to be analyzed first. +@subsubheading MacOS X -For future use of LilyPond, you should begin by selecting "New" -or "Open". +If you double click @code{LilyPond.app}, it will open with an +example file. Save it, for example, to @file{test.ly} on your +Desktop, and then process it with the menu command @code{Compile > +Typeset File}. The resulting PDF file will be displayed on your +screen. -@unnumberedsubsec Windows +For future use of LilyPond, you should begin by selecting @q{New} +or @q{Open}. You must save your file before typesetting it. If +any errors occur in processing, please see the log window. -On Windows, start up a text-editor@footnote{Any simple or -programmer-oriented editor will do, for example Notepad. Do not use a -word processor, since these insert formatting codes that will confuse -LilyPond.} and enter -@verbatim -{ c' e' g' c'' } -@end verbatim +@subsubheading Windows -Save it on the desktop as @file{test.ly} and make sure that it is not -called @file{test.ly.TXT}. Double clicking @file{test.ly} will process -the file and show the resulting PDF file. +On Windows, if you double-click in the LilyPond icon on the +Desktop, it will open a simple text editor with an example file. +Save it, for example, to @file{test.ly} on your Desktop and then +double-click on the file to process it (the file icon looks like a +note). After some seconds, you will get a file @file{test.pdf} on +your desktop. Double-click on this PDF file to view the typeset +score. An alternative method to process the @file{test.ly} file +is to drag and drop it onto the LilyPond icon using your mouse +pointer. +To edit an existing @file{.ly} file, right-click on it and +select @qq{Edit source}. To get an empty file to start from, run +the editor as described above and use @qq{New} in +the @qq{File} menu. -@unnumberedsubsec Unix +Double-clicking the file does not only result in a PDF file, but +also produces a @file{.log} file that contains some information on +what LilyPond has done to the file. If any errors occur, please +examine this file. -Begin by opening a terminal window and starting a text editor. For -example, you could open an xterm and execute -@code{joe}@footnote{There are macro files for VIM addicts, and there -is a @code{LilyPond-mode} for Emacs addicts. If they have not been -installed already, refer to the file @file{INSTALL.txt}.}. In your -text editor, enter the following input and save the file as -@file{test.ly} +@subsubheading Unix -@verbatim -{ c' e' g' c'' } -@end verbatim +Create a file (such as @file{test.ly}) and enter: -@noindent -To process @file{test.ly}, proceed as follows +@example +@{ + c' e' g' e' +@} +@end example + +To process @file{test.ly}, proceed as follows: @example lilypond test.ly @end example @noindent -You will see something resembling +You will see something resembling: @example lilypond test.ly -GNU LilyPond 2.10.0 +GNU LilyPond 2.12.0 Processing `test.ly' Parsing... -Interpreting music... [1] +Interpreting music... Preprocessing graphical objects... -Calculating line breaks... [2] +Finding the ideal number of pages... +Fitting music on 1 page... +Drawing systems... Layout output to `test.ps'... Converting to `test.pdf'... @end example -@cindex DVI file -@cindex Viewing music -@cindex xdvi -@noindent -The result is the file @file{test.pdf} which you can print or view -with the standard facilities of your operating system.@footnote{If -your system does not have any tools installed, you can try -@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely -available package for viewing and printing PDF and PostScript files.} - -@node Second steps -@section Second steps +@node Simple notation +@subsection Simple notation -@emph{Remember:} Every piece of LilyPond input needs to -have @{curly braces@} placed -around the input. For the rest of this manual, most examples will -omit these braces, but don't forget them in your own music! +LilyPond will add some notation elements automatically. In the +next example, we have only specified four pitches, but LilyPond +has added a clef, time signature, and rhythms. -@c will be removed once the tutorial either explains \relative or -@c examples are fixed so they don't use it. -gp -In addition, many examples use @code{relative} mode. This is explained -in @ref{Octave entry}; for now simply be aware that some examples -should be placed inside @code{\relative @{ @emph{...music...} @}}. -Many example have also been compressed horizontally to save -space, using @code{\paper @{ ragged-right = ##t @}}. +@lilypond[verbatim,quote,ragged-right] +{ + c' e' g' e' +} +@end lilypond -@cindex Case sensitive -Finally, LilyPond input is case sensitive. @code{ @{ c d e @} } is -valid input; @code{ @{ C D E @} } will produce an error message. +@noindent +This behavior may be altered, but in most cases these automatic +values are useful. -@c End of latest re-write. Since I have no life, I may do more -@c work on this, but I'd really like to have a Doc Helper take -@c over this task. -gp +@subheading Pitches -The @rglos{duration} of a note is specified by a number after the note -name. @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note}, -@samp{4} for a @rglos{quarter note} and so on +Music glossary: @rglos{pitch}, @rglos{interval}, +@rglos{scale}, @rglos{middle C}, @rglos{octave}, +@rglos{accidental}. -@example -a1 a2 a4 a16 a32 -@end example +The easiest way to enter notes is by using @code{\relative} mode. +In this mode, the octave is chosen automatically by assuming the +following note is always to be placed closest to the previous note, +i.e., it is to be placed in the octave which is within three +staff spaces of the previous note. We begin by entering the most +elementary piece of music, a @notation{scale}, in which every note +is within just one staff space of the previous note. -@lilypond[fragment,quote,notime,relative=2] -\set Staff.autoBeaming = ##f -{ a1 a2 a4 a16 a32 s16_" " } +@lilypond[verbatim,quote,ragged-right] +\relative c' { % set the starting point to middle C + c d e f + g a b c +} @end lilypond -If you do not specify a duration, the duration last entered is used -for the next notes. The duration of the first note in input defaults -to a quarter +The initial note is @notation{middle C}. Each successive note is +placed closest to the previous note -- in other words, the first +@code{c} is the closest C to middle C. This is followed by the +closest D to the previous note. We can create melodies which +have larger intervals: -@example -a a8 a a2 a -@end example +@lilypond[verbatim,quote,ragged-right] +\relative c' { + d f a g + c b f d +} +@end lilypond -@lilypond[fragment,quote,notime,relative=2] -{ a a8 a a2 a s16_" " } +@noindent +It is not necessary for the first note of the melody to start on +the note which specifies the starting pitch. In the previous +example, the first note -- the @code{d} -- is the closest D to +middle C. + +By adding (or removing) quotes @code{'} or commas @code{,} from +the @code{\relative c' @{} command, we can change the starting +octave: + +@lilypond[verbatim,quote,ragged-right] +\relative c'' { % one octave above middle C + e c a c +} @end lilypond +Relative mode can be confusing initially, but is the easiest way +to enter most melodies. Let us see how this relative calculation +works in practice. Starting from a B, which is on the middle line +in a treble clef, you can reach a C, D and E within 3 staff spaces +going up, and an A, G and F within 3 staff spaces going down. So +if the note following a B is a C, D or F it will be assumed to be +above the B, and an A, G or F will be assumed to be below. -A @rglos{rest} is entered just like a note, but with the name @samp{r} +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + b c % c is 1 staff space up, so is the c above + b d % d is 2 up or 5 down, so is the d above + b e % e is 3 up or 4 down, so is the e above + b a % a is 4 up or 3 down, so is the a below + b g % g is 5 up or 2 down, so is the g below + b f % f is 6 up or 1 down, so is the f below +} +@end lilypond -@example -r2 r4 r8 r16 -@end example +Exactly the same happens even when any of these notes are +sharpened or flatted. @notation{Accidentals} are @strong{totally +ignored} in the calculation of relative position. Precisely the +same staff space counting is done from a note at any other +position on the staff. -@lilypond[fragment,quote,notime] -r2 r4 r8 r16 s16_" " +To add intervals that are larger than three staff spaces, we can +raise the @notation{octave} by adding a single quote @code{'} (or +apostrophe) to the note name. We can lower the octave by adding a +comma @code{,} to the note name. + +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + a a, c' f, + g g'' a,, f' +} @end lilypond -Add a dot @samp{.} after the duration to get a @rglos{dotted note} +@noindent +To change a note by two (or more!) octaves, we use multiple +@code{''} or @code{,,} -- but be careful that you use two single +quotes @code{''} and not one double quote @code{"}@tie{}! The +initial value in @code{\relative c'} may also be modified like +this. -@example -a2. a4 a8. a16 -@end example -@lilypond[fragment,quote,notime,relative=1] -{ a2. a4 a8. a16 s16_" " } -@end lilypond +@subheading Durations (rhythms) -The (or @rglos{time signature}) can be set with the @code{\time} -command +Music glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note}, +@rglos{half note}, @rglos{quarter note}, @rglos{dotted note}. -@example -\time 3/4 -\time 6/8 -\time 4/4 -@end example +The @notation{duration} of a note is specified by a number after +the note name. @code{1} for a @notation{whole note}, @code{2} for +a @notation{half note}, @code{4} for a @notation{quarter note} and +so on. @notation{Beams} are added automatically. -@c A clef here may lead to confusion, remove it. -@lilypond[fragment,quote] -\override Staff.Clef #'transparent = ##t -\time 3/4 -s4_" " -\time 6/8 -s4_" " -\time 4/4 -s16_" " +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + a1 + a2 a4 a8 a + a16 a a a a32 a a a a64 a a a a a a a a2 +} @end lilypond -The @rglos{clef} can be set using the @code{\clef} command +@noindent +If you do not specify a duration, the previous duration is used +for the next note. The duration of the first note defaults to a +quarter. -@example -\clef treble -\clef bass -\clef alto -\clef tenor -@end example +To create @notation{dotted notes}, add a dot @code{.} to the duration +number. -@lilypond[fragment,quote,notime] -\clef treble -s4_" " -\clef bass -s4_" " -\clef alto -s4_" " -\clef tenor -s16_" " +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + a a a4. a8 + a8. a16 a a8. a8 a4. +} @end lilypond -Remember to enclose the notes and commands in curly braces -@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output. -@lilypond[fragment,quote,noindent,verbatim] -\time 3/4 -\clef bass -c2 e4 g2. -f4 e d c2 r4 -@end lilypond +@subheading Rests -For more information on - -@quotation -@table @asis -@item Entering pitches and durations -see -@ref{Pitches}, and @ref{Durations}. -@item Clefs -see @ref{Clef}. -@item Rests -see @ref{Rests}. -@item Time signatures and other timing commands -see @ref{Time signature}. -@end table -@end quotation - - -@node More about pitches -@section More about pitches - -A @rglos{sharp} pitch is made by adding @samp{is} to -the name, a @rglos{flat} pitch by adding @samp{es}. As -you might expect, a @rglos{double sharp} or @rglos{double flat} is -made by adding @samp{isis} or @samp{eses}@footnote{This syntax -derived from note naming conventions in Nordic and Germanic languages, -like German and Dutch.} +Music glossary: @rglos{rest}. -@example -cis1 ees fisis aeses -@end example +A @notation{rest} is entered just like a note with the name @code{r}: -@lilypond[fragment,quote,notime] -\set Score.timing = ##f -\transpose c c' { cis1 ees fisis aeses s16_" " } +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + a r r2 + r8 a r4 r4. r8 +} @end lilypond -@cindex key signature, setting -The key signature is set with the command @code{\key}, followed by -a pitch and @code{\major} or @code{\minor} -@example -\key d \major -g1 -\key c \minor -g -@end example +@subheading Time signature -@lilypond[fragment,quote,notime,fragment] -\key d \major -g'1 -\key c \minor -g' +Music glossary: @rglos{time signature}. + +The @notation{time signature} can be set with the @code{\time} +command: + +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + \time 3/4 + a4 a a + \time 6/8 + a4. a + \time 4/4 + a4 a a a +} @end lilypond -@noindent -Key signatures together with the pitches (including alterations) are -used to determine when to print accidentals. This is a -feature that often causes confusion to newcomers, so let us explain it -in more detail. +@subheading Clef -LilyPond makes a sharp distinction between musical content and -layout. The alteration (flat, natural or sharp) of a note is part of -the pitch, and is therefore musical content. Whether an accidental (a -flat, natural or sharp @emph{sign}) is printed in front of the -corresponding note is a question of layout. Layout is something that -follows rules, so accidentals are printed automatically according to -those rules. The pitches in your music are works of art, so they will -not be added automatically, and you must enter what you want to hear. +Music glossary: @rglos{clef}. -In this example +The @notation{clef} can be set using the @code{\clef} command: -@lilypond[quote,notime,fragment] -\key d \major -d' cis' fis' +@lilypond[verbatim,quote,ragged-right] +\relative c' { + \clef treble + c1 + \clef alto + c1 + \clef tenor + c1 + \clef bass + c1 +} @end lilypond -@noindent -no note has an explicit accidental, but you still must enter -@example -\key d \major -d cis fis -@end example +@subheading All together -@noindent -The code @samp{d} does not mean `print a black dot just below the -staff.' Rather, it means: `a note with pitch D-natural.' In the key -of A-flat major, it does get an accidental +Here is a small example showing all these elements together: -@lilypond[quote,notime,fragment,relative=1,verbatim] -\key as \major -d +@lilypond[verbatim,quote,ragged-right] +\relative c, { + \time 3/4 + \clef bass + c2 e8 c' g'2. + f4 e d c4 c, r4 +} @end lilypond -Adding all alterations explicitly might require a little more effort -when typing, but the advantage is that transposing is easier, and -accidentals can be printed according to different conventions. See -@ref{Automatic accidentals}, for some examples how accidentals can be printed -according to different rules. - - -For more information on -@quotation -@table @asis -@item Accidentals -see @ref{Automatic accidentals}. +@seealso -@item Key signature -see @ref{Key signature}. -@end table -@end quotation +Notation Reference: @ruser{Writing pitches}, @ruser{Writing rhythms}, +@ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}. -@node Entering ties -@section Entering ties -@cindex tie -A @rglos{tie} is created by appending a tilde @samp{~} to the first -note being tied +@c HERE's where I started -@lilypond[quote,notime,fragment,verbatim,relative=3] -g4~ g a2~ a4 -@end lilypond +@node Working on text files +@subsection Working on text files -For more information on Ties see @ref{Ties}. +LilyPond input files are similar to source files in many common +programming languages. They are case sensitive, and white-space +is generally equivalent. Expressions are formed with curly braces +@{ @}, and comments are denoted with @code{%} or @code{%@{ ... +%@}}. +If the previous sentences sound like nonsense, don't worry! We'll +explain what all these terms mean: +@itemize -@node Automatic and manual beams -@section Automatic and manual beams +@cindex case sensitive +@item +@strong{Case sensitive}: +it matters whether you enter a letter in lower case (e.g. @code{a, +b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are +lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}} +will produce an error message. -@cindex beams, by hand -All @rglos{beam}s are drawn automatically +@item +@strong{Whitespace insensitive}: +it does not matter how many spaces (or new lines) you add. +@code{@{ c d e @}} means the same thing as @code{@{ c @tie{} +@tie{} @tie{} d e @}} and: -@lilypond[quote,fragment,relative=2,verbatim] -a8 ais d es r d -@end lilypond +@example +@{ c d + e @} +@end example @noindent -If you do not like where beams are put, they can be entered by -hand. Mark the first note to be beamed with @samp{[} and the last one -with @samp{]}. +Of course, the previous example is hard to read. A good rule of +thumb is to indent code blocks with either a tab or two spaces: -@lilypond[quote,fragment,relative=2,verbatim] -a8[ ais] d[ es r d] -@end lilypond +@example +@{ + c d e +@} +@end example -For more information on beams, see @ref{Manual beams}. +@item +@strong{Expressions:} +Every piece of LilyPond input needs to have @strong{@{ curly +braces @}} placed around the input. These braces tell LilyPond +that the input is a single music expression, just like parentheses +@code{()} in mathematics. The braces should be surrounded by a +space unless they are at the beginning or end of a line to avoid +ambiguities. +A function (such as @code{\relative @{ @}}) also counts as a +single music expression. -Here are key signatures, accidentals and ties in action +@cindex comments +@cindex line comment +@cindex block comment +@item +@strong{Comments}: +A comment is a remark for the human reader of the music input; it +is ignored while parsing, so it has no effect on the printed +output. There are two types of comments. The percent symbol +@code{%} introduces a line comment; anything after @code{%} on +that line is ignored. A block comment marks a whole section of +music input as a comment. Anything that is enclosed in @code{%@{} +and @code{%@}} is ignored. (Comments do not nest.) The following +fragment shows possible uses for comments: -@lilypond[fragment,quote,noindent,line-width=50\staff-space,verbatim] -\relative c'' { - \time 4/4 - \key g \minor - \clef treble - r4 r8 a8 gis4 b - a8 d4.~ d e,8 - fis4 fis8 fis8 eis4 a8 gis~ - gis2 r2 -} -@end lilypond +@example +% notes for twinkle twinkle follow + c4 c g' g a a g2 + +%@{ + This line, and the notes below + are ignored, since they are in a + block comment. -@cindex accidentals + g g f f e e d d c2 +%@} +@end example +@end itemize -@noindent -There are some interesting points to note in this example. Bar lines -and beams are drawn automatically. Line breaks are calculated -automatically; it does not matter where the line breaks are in the -source file. Finally, the order in which time, key, and clef changes -are entered is not relevant: in the printout, these are ordered -according to standard notation conventions. +There are more tips for constructing input files in +@ref{Suggestions for writing LilyPond files}. +@node How to read the tutorial +@subsection How to read the tutorial -@node Octave entry -@section Octave entry +LilyPond input must be surrounded by @{ @} marks or a +@code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text +files}. For the rest of this manual, most examples will omit +this. To replicate the examples, you may copy and paste the +displayed input but you @strong{must} add the @code{\relative c'' +@{ @}} like this: +@example +\relative c'' @{ + ... example goes here... +@} +@end example -@c Tim wants to move this quotes example just before the: quotes-do not-work -@c score, but we'd need to remove quotes from the other two (key and -@c tie) examples... +Why omit the braces? Most examples in this manual can be inserted +into the middle of a longer piece of music. For these examples, +it does not make sense to add @code{\relative c'' @{ @}} -- you +should not place a @code{\relative} inside another +@code{\relative}! If we included @code{\relative c'' @{ @}} +around every example, you would not be able to copy a small +documentation example and paste it inside a longer piece of your +own. Most people want to add material to an existing piece, so we +format the manual this way. -@c better to have this just before the `octaves are bad' snipped -@c but we'd need to remove the ', from \key and tie -To raise a note by an octave, add a high quote @code{'} (apostrophe) to -the note name, to lower a note one octave, add a `low quote' @code{,} -(comma). Middle C is @code{c'} -@lilypond[quote,notime,fragment,verbatim] -c'4 c'' c''' \clef bass c c, -@end lilypond +@subheading Clickable examples -An example of the use of quotes is in the following Mozart fragment +Many people learn programs by trying and fiddling around with the +program. This is also possible with LilyPond. If you click on a +picture in the HTML version of this manual, you will see the exact +LilyPond input that was used to generate that image. Try it on +this image: -@lilypond[quote,ragged-right,fragment,verbatim] -\key a \major -\time 6/8 -cis''8. d''16 cis''8 e''4 e''8 -b'8. cis''16 b'8 d''4 d''8 +@c no verbatim here +@lilypond[quote,ragged-right] +\relative c'' { + c-\markup { \bold \huge { Click here. } } +} @end lilypond -@noindent -This example shows that music in a high register needs lots of quotes. -This makes the input less readable, and it is a source of errors. The -solution is to use `relative octave' mode. This is the -most convenient way to copy existing music. +By cutting and pasting everything in the @qq{ly snippet} section, +you have a starting template for experiments. To see exactly the +same output (line-width and all), copy everything from @qq{Start +cut-&-pastable section} to the bottom of the file. -In relative mode, a note without octavation quotes (i.e., the @code{'} -or @code{,} after a note) is chosen so that it is closest to the -previous one. For example, @samp{c f} goes up while @samp{c g} goes -down. -To use relative mode, add @code{\relative} before the piece of -music. The first note is taken relative to the middle C -@c no , for this sentence -(i.e., @code{c'}) +@node Single staff notation +@section Single staff notation +This section introduces common notation that is used for one voice +on one staff. +@menu +* Accidentals and key signatures:: +* Ties and slurs:: +* Articulation and dynamics:: +* Adding text:: +* Automatic and manual beams:: +* Advanced rhythmic commands:: +@end menu -@lilypond[quote,notime,fragment,verbatim] -\relative { - c' f c g c -} -@end lilypond +@node Accidentals and key signatures +@subsection Accidentals and key signatures -Since most music has small intervals, pieces can be written almost -without octavation quotes in relative mode. The previous example is -entered as +@subheading Accidentals -@lilypond[quote,ragged-right,verbatim] -\relative { - \key a \major - \time 6/8 - cis'8. d16 cis8 e4 e8 - b8. cis16 b8 d4 d8 -} -@end lilypond +Music glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp}, +@rglos{double flat}, @rglos{accidental}. -@c needed better, maybe even redundant explanation -@c added another example below. -@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep. -@c in eerste instantie drong het `relative' niet door zonder extra uitleg. -Larger intervals are made by adding octavation quotes. +A @notation{sharp} pitch is made by adding @code{is} to the name, and +a @notation{flat} pitch by adding @code{es}. As you might expect, a +@notation{double sharp} or @notation{double flat} is made by adding +@code{isis} or @code{eses}. This syntax derived from note +naming conventions in Nordic and Germanic languages, like German +and Dutch. To use other names for @notation{accidentals}, see +@ruser{Note names in other languages}. -@lilypond[quote,notime,verbatim,fragment] -\relative c { - c'' f, f c' c g' c, -} +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +cis1 ees fisis, aeses @end lilypond -In summary, quotes or commas no longer determine the absolute height -of a note in @code{\relative} mode. Rather, the height of a note is -relative to the previous one, and changing the octave of a single note -shifts all following notes an octave up or down. +@cindex key signature, setting +@subheading Key signatures -For more information on relative octaves see @ref{Relative octaves}, -and @ref{Octave check}. +Music glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}. +The @notation{key signature} is set with the command @code{\key} +followed by a pitch and @code{\major} or @code{\minor}. -@node Music expressions explained -@section Music expressions explained +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +\key d \major +a1 +\key c \minor +a +@end lilypond +@smallspace -In input files, music is represent by so-called @emph{music -expression}s. We have already seen some in the previous examples; -a single note is a music expression +@subheading Warning: key signatures and pitches -@lilypond[fragment,quote,verbatim,relative=3] -a4 -@end lilypond +Music glossary: @rglos{accidental}, @rglos{key signature}, +@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp}, +@rglos{transposition}. -Enclosing a group of notes in braces creates a new music -expression +To determine whether to print an @notation{accidental}, LilyPond +examines the pitches and the @notation{key signature}. The key +signature only affects the @emph{printed} accidentals, not the note's +@notation{pitch}! This is a feature that often causes confusion to +newcomers, so let us explain it in more detail. -@lilypond[fragment,quote,verbatim,relative=3] -{ a4 g4 } +LilyPond makes a sharp distinction between musical content and +layout. The alteration (@notation{flat}, @notation{natural} or +@notation{sharp}) of a note is part of the pitch, and is therefore +musical content. Whether an accidental (a @emph{printed} flat, natural +or sharp sign) is printed in front of the corresponding note is a +question of layout. Layout is something that follows rules, so +accidentals are printed automatically according to those rules. The +pitches in your music are works of art, so they will not be added +automatically, and you must enter what you want to hear. + +In this example: + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +\key d \major +d cis fis @end lilypond -Putting a bunch of music expressions (e.g., notes) in braces, means that -they should be played in sequence. The result again is a music -expression, which can be grouped with other expressions sequentially. -Here, the expression from the previous example is combined with two -notes +@noindent +No note has a printed accidental, but you must still add the +@code{is} to @code{cis} and @code{fis}. -@lilypond[fragment,quote,verbatim,relative=3] -{ { a4 g } f g } +The code @code{e} does not mean @qq{print a black dot just below +the first line of the staff.} Rather, it means @qq{there is a +note with pitch E-natural.} In the key of A-flat major, it +@emph{does} get an accidental: + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +\key aes \major +e @end lilypond -This technique is useful for non-monophonic music. To enter music -with more voices or more staves, we also combine expressions in -parallel. Two voices that should play at the same time, are entered -as a simultaneous combination of two sequences. A `simultaneous' -music expression is formed by enclosing expressions in @code{<<} and -@code{>>}. In the following example, three sequences (all containing -two separate notes) are combined simultaneously +Adding all alterations explicitly might require a little more +effort when typing, but the advantage is that +@notation{transposing} is easier, and accidentals can be printed +according to different conventions. For some examples how +accidentals can be printed according to different rules, see +@ruser{Automatic accidentals}. -@lilypond[fragment,quote,verbatim,relative=3] -<< - { a4 g } - { f e } - { d b } ->> -@end lilypond +@seealso -This mechanism is similar to mathematical -formulas: a big formula is created by composing small formulas. Such -formulas are called expressions, and their definition is recursive, so -you can make arbitrarily complex and large expressions. For example, +Notation Reference: @ruser{Accidentals}, +@ruser{Automatic accidentals}, @ruser{Key signature}. -@example -1 +Music glossary: @rglos{Pitch names}. -1 + 2 -(1 + 2) * 3 +@node Ties and slurs +@subsection Ties and slurs -((1 + 2) * 3) / (4 * 5) -@end example +@cindex ties +@subheading Ties -@cindex expression -@cindex music expression -This is a sequence of expressions, where each expression is contained -in the next (larger) one. The simplest expressions are numbers, and larger -ones are made by combining expressions with operators (like @samp{+}, -@samp{*} and @samp{/}) and parentheses. Like mathematical expressions, -music expressions can be nested arbitrarily deep, which is necessary -for complex music like polyphonic scores. - -Note that this example only has one staff, whereas -the previous example had three separate staves. That is because this -example begins with a single note. To determine the number of staves, -LilyPond looks at the first element. If it is a single note, there is one -staff; if there is a simultaneous expression, there is more than one staff. - -@lilypond[fragment,quote,verbatim,relative=2] -{ - c <> - << { e f } { c <> } >> -} -@end lilypond +Music glossary: @rglos{tie}. -Music files with deep nesting can be confusing to enter and -maintain. One convention that helps against this confusion is -indenting. When entering a file with deep nesting of braces and -angles, it is customary to use an indent that indicates the nesting -level. Formatting music like this eases reading and helps you insert -the right number of closing braces at the end of an expression. For -example, +A @notation{tie} is created by appending a tilde @code{~} to the +first note being tied. -@example -<< - @{ - @dots{} - @} - @{ - @dots{} - @} ->> -@end example +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +g4~ g c2~ +c4 ~ c8 a8 ~ a2 +@end lilypond -Some editors have special support for entering LilyPond, and can help -indenting source files. See @ref{Editor support} for more information. +@cindex slurs +@subheading Slurs -@node More staves -@section More staves +Music glossary: @rglos{slur}. -To print more than one staff, each piece of music that makes up a -staff is marked by adding @code{\new Staff} before it. These -@code{Staff} elements are then combined in parallel with @code{<<} and -@code{>>}, as demonstrated here +A @notation{slur} is a curve drawn across many notes. The starting +note and ending note are marked with @code{(} and @code{)} +respectively. -@lilypond[quote,fragment,verbatim] -<< - \new Staff { \clef treble c'' } - \new Staff { \clef bass c } ->> +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +d4( c16) cis( d e c cis d) e( d4) @end lilypond +@cindex slurs, phrasing +@cindex phrasing slurs +@subheading Phrasing slurs -The command @code{\new} introduces a `notation context.' A notation -context is an environment in which musical events (like notes or -@code{\clef} commands) are interpreted. For simple pieces, such -notation contexts are created automatically. For more complex pieces, it -is best to mark contexts explicitly. This ensures that each fragment -gets its own stave. +Music glossary: @rglos{phrasing}, @rglos{legato}. -There are several types of contexts. @code{Staff}, @code{Voice} and -@code{Score} handle melodic notation, while @code{Lyrics} sets lyric -texts and @code{ChordNames} prints chord names. +Slurs to indicate longer @notation{phrasing} can be entered with +@code{\(} and @code{\)}. You can have both @notation{legato} slurs and +phrasing slurs at the same time, but you cannot have simultaneous legato +slurs or simultaneous phrasing slurs. -In terms of syntax, prepending @code{\new} to a music expression -creates a bigger music expression. In this way it resembles the minus -sign in mathematics. The formula @math{(4+5)} is an expression, so -@math{-(4+5)} is a bigger expression. +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +a8(\( ais b c) cis2 b'2 a4 cis,\) +@end lilypond -We can now typeset a melody with two staves +@smallspace -@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together) +@cindex slurs versus ties +@subheading Warnings: slurs vs. ties -@lilypond[fragment,quote,verbatim,ragged-right] -\relative << - \new Staff { - \time 3/4 - \clef treble +Music glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}. - e'2 d4 c2 b4 a8[ a] - b[ b] g[ g] a2. - } - \new Staff { - \clef bass - c,,2 e4 g2. - f4 e d c2. - } ->> +A @notation{slur} looks like a @notation{tie}, but it has a different +meaning. A tie simply makes the first note longer, and can only be +used on pairs of notes with the same pitch. Slurs indicate the +@notation{articulation} of notes, and can be used on larger groups of +notes. Slurs and ties can be nested. + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c2~( c8 fis fis4 ~ fis2 g2) @end lilypond -For more information on contexts see the description in -@ref{Interpretation contexts}. +@seealso +Notation Reference: @ruser{Ties}, @ruser{Slurs}, +@ruser{Phrasing slurs}. -@node Adding articulation marks to notes -@section Adding articulation marks to notes +@node Articulation and dynamics +@subsection Articulation and dynamics @cindex articulation @cindex accents @cindex staccato +@subheading Articulations -Common accents can be added to a note using a dash (@samp{-}) and a -single character +Music glossary: @rglos{articulation}. -@lilypond[fragment,quote,verbatim,relative=2] -c-. c-- c-> c-^ c-+ c-_ +Common @notation{articulations} can be added to a note using a +dash @code{-} and a single character: + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c-. c-- c-> c-^ c-+ c-_ @end lilypond @cindex fingering -Similarly, fingering indications can be added to a note using a dash -(@samp{-}) and the digit to be printed +@subheading Fingerings + +Music glossary: @rglos{fingering}. -@lilypond[fragment,quote,verbatim,relative=2] +Similarly, @notation{fingering} indications can be added to a note using +a dash (@code{-}) and the digit to be printed: + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c-3 e-5 b-2 a-1 @end lilypond -Articulations and fingerings are usually placed automatically, but you -can specify a direction using @samp{^} (up) or @samp{_} (down). You can -also use multiple articulations on the same note. In most cases, however, -it is best to let LilyPond determine the articulation directions. +Articulations and fingerings are usually placed automatically, but +you can specify a direction using @code{^} (up) or @code{_} +(down). You can also use multiple articulations on the same note. +However, in most cases it is best to let LilyPond determine the +articulation directions. -@lilypond[fragment,quote,verbatim,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c_-^1 d^. f^4_2-> e^-_+ @end lilypond -Dynamic signs are made by adding the markings (with a backslash) to -the note +@subheading Dynamics + +Music glossary: @rglos{dynamics}, @rglos{crescendo}, +@rglos{decrescendo}. -@lilypond[fragment,quote,verbatim,relative=2] -c\ff c\mf +@notation{Dynamic} signs are made by adding the markings (with a +backslash) to the note: + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c\ff c\mf c\p c\pp @end lilypond @cindex dynamics @cindex decrescendo @cindex crescendo -Crescendi and decrescendi are started with the commands @code{\<} and -@code{\>}. An ending dynamic, for example @code{\f}, will finish the -(de)crescendo, or the command @code{\!} can be used +@notation{Crescendi} and @notation{decrescendi} are started with +the commands @code{\<} and @code{\>}. An ending dynamic, for +example @code{\f}, will finish the (de)crescendo, or the command +@code{\!} can be used: -@lilypond[fragment,quote,verbatim,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2\< c2\ff\> c2 c2\! @end lilypond +@seealso +Notation Reference: @ruser{Articulations}, +@ruser{Fingering instructions}, @ruser{Dynamics}. -@cindex slur +Music glossary: @rglos{Dynamics}. -A @rglos{slur} is a curve drawn across many notes, and indicates -legato articulation. The starting note and ending note are marked -with @samp{(} and @samp{)}, respectively -@lilypond[fragment,quote,fragment,relative=2,verbatim] -d4( c16) cis( d e c cis d) e( d4) -@end lilypond +@node Adding text +@subsection Adding text -@cindex slurs versus ties -A slur looks like a @rglos{tie}, but it has a different meaning. A -tie simply makes the first note sound longer, and can only be used on -pairs of notes with the same pitch. Slurs indicate the articulations -of notes, and can be used on larger groups of notes. Slurs and ties -can be nested +Text may be added to your scores: -@lilypond[quote,fragment,relative=2] -c2~( c8 fis fis4 ~ fis2 g2) +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c1^"espr" a_"legato" @end lilypond -@cindex phrasing slurs -Slurs to indicate phrasing can be entered with @code{\(} and -@code{\)}, so you can have both legato slurs and phrasing slurs at the -same time. You cannot have simultaneous slurs or simultaneous -phrasing slurs. +Extra formatting may be added with the @code{\markup} command: -@lilypond[quote,fragment,relative=2,verbatim] -a8(\( ais b c) cis2 b'2 a4 cis, c\) +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c1^\markup{ \bold espr} +a1_\markup{ + \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p +} @end lilypond -For more information on +@seealso -@quotation -@table @asis -@item Fingering -see @ref{Fingering instructions}. -@item Articulations -see @ref{Articulations}. -@item Slurs -see @ref{Slurs}. -@item Phrasing slurs -see @ref{Phrasing slurs}. -@item Dynamics -see @ref{Dynamics}. -@end table -@end quotation +Notation Reference: @ruser{Writing text}. -@node Combining notes into chords -@section Combining notes into chords +@node Automatic and manual beams +@subsection Automatic and manual beams -@cindex chords -Chords can be made by surrounding pitches with angle brackets. -Angle brackets are the symbols @samp{<} and @samp{>}. +Music glossary: @rglos{beam}. -@lilypond[quote,relative=1,fragment,verbatim] -r4 4 8 -@end lilypond +@cindex beams, by hand +All @notation{beams} are drawn automatically: +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +a8 ais d ees r d c16 b a8 +@end lilypond -You can combine markings like beams and ties with chords. They must -be placed outside the angled brackets +@noindent +If you do not like the automatic beams, they may be overridden +manually. Mark the first note to be beamed with @code{[} and the +last one with @code{]}. -@lilypond[quote,relative=1,fragment,verbatim] -r4 8[ ]~ +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +a8[ ais] d[ ees r d] a b @end lilypond -@example -r4 8\>( \!) -@end example +@seealso -@lilypond[quote,relative=1,fragment] -\slurUp -r4 8\>( \!) -@end lilypond +Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}. @node Advanced rhythmic commands -@section Advanced rhythmic commands +@subsection Advanced rhythmic commands @cindex pickup -@cindex anacruse +@cindex anacrusis @cindex partial measure -A pickup is entered with the keyword @code{\partial}. It -is followed by a duration: @code{\partial 4} is a quarter note upstep -and @code{\partial 8} an eighth note +@subheading Partial measure + +Music glossary: @rglos{anacrusis}. -@lilypond[quote,relative=2,verbatim,fragment] +A pickup (or @notation{anacrusis}) is entered with the keyword +@code{\partial}. It is followed by a duration: @code{\partial 4} +is a quarter note pickup and @code{\partial 8} an eighth note. + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] \partial 8 -f8 c2 d e +f8 c2 d @end lilypond @cindex tuplets @cindex triplets -Tuplets are made with the @code{\times} keyword. It takes two -arguments: a fraction and a piece of music. The duration of the piece -of music is multiplied by the fraction. Triplets make notes occupy -2/3 of their notated duration, so a triplet has 2/3 as its fraction +@subheading Tuplets + +Music glossary: @rglos{note value}, @rglos{triplet}. -@lilypond[quote,relative=1,verbatim,fragment] +@notation{Tuplets} are made with the @code{\times} keyword. It +takes two arguments: a fraction and a piece of music. The +duration of the piece of music is multiplied by the fraction. +Triplets make notes occupy 2/3 of their notated duration, so a +@notation{triplet} has 2/3 as its fraction + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] \times 2/3 { f8 g a } \times 2/3 { c r c } +\times 2/3 { f,8 g16[ a g a] } +\times 2/3 { d4 a8 } @end lilypond @cindex grace notes @cindex acciaccatura -Grace notes are also made by prefixing a music expression with the -keyword @code{\appoggiatura} or @code{\acciaccatura} @cindex appoggiatura -@cindex acciaccatura +@subheading Grace notes -@lilypond[quote,relative=2,verbatim,fragment] -c4 \appoggiatura b16 c4 -c4 \acciaccatura b16 c4 -@end lilypond +Music glossary: @rglos{grace notes}, @rglos{appoggiatura}. -@noindent +@notation{Grace notes} are created with the @code{\grace} command, +although they can also be created by prefixing a music expression +with the keyword @code{\appoggiatura} or @code{\acciaccatura}: -For more information on +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c2 \grace { a32[ b] } c2 +c2 \appoggiatura b16 c2 +c2 \acciaccatura b16 c2 +@end lilypond -@quotation -@table @asis -@item Grace notes -see @ref{Grace notes}, -@item Tuplets -see @ref{Tuplets}, -@item Pickups -see @ref{Partial measures}. -@end table -@end quotation +@seealso +Notation Reference: @ruser{Grace notes}, @ruser{Tuplets}, +@ruser{Upbeats}. -@node Commenting input files -@section Commenting input files -@cindex comments -@cindex line comment -@cindex block comment -A comment is a remark for the human reader of the music input; it is -ignored while parsing, so it has no effect on the printed output. -There are two types of comments. The percent symbol @samp{%} -introduces a line comment; after @code{%} the rest of the line is -ignored. A block comment marks a whole section of music -input. Anything that is enclosed in @code{%@{} and @code{%@}} is -ignored. The following fragment shows possible uses for comments +@node Multiple notes at once +@section Multiple notes at once -@example -% notes for twinkle twinkle follow - c4 c g' g a a g2 +This section introduces having more than one note at the same +time: multiple instruments, multiple staves for a single +instrument (i.e. piano), and chords. -%@{ - This line, and the notes below - are ignored, since they are in a - block comment. +Polyphony in music refers to having more than one voice occurring +in a piece of music. Polyphony in LilyPond refers to having more +than one voice on the same staff. - g g f f e e d d c2 -%@} -@end example +@menu +* Music expressions explained:: +* Multiple staves:: +* Piano staves:: +* Combining notes into chords:: +* Single staff polyphony:: +@end menu -@c TODO post-2.6 reorg -@c This is good info, but I wouldn't call it a comment. IMO it should -@c be moved somewhere else. -@cindex versioning +@node Music expressions explained +@subsection Music expressions explained -There is a special statement that is a kind of comment. The @code{\version} -statement marks for which version of LilyPond the file was written. -To mark a file for version 2.10.1, use +In LilyPond input files, music is represented by @emph{music +expressions}. A single note is a music expression: -@example -\version "2.10.1" -@end example +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +a4 +@end lilypond -@noindent -These annotations make future upgrades of LilyPond go more -smoothly. Changes in the syntax are handled with a special program, -@file{convert-ly} (see @ref{Updating files with convert-ly}), and it uses -@code{\version} to determine what rules to apply. +Enclosing a note in braces creates a @emph{compound music +expression}. Here we have created a compound music expression +with two notes: +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +{ a4 g4 } +@end lilypond -@node Printing lyrics -@section Printing lyrics -@cindex lyrics +Putting a group of music expressions (e.g. notes) in braces means +that they are in sequence (i.e. each one follows the previous +one). The result is another music expression: -@c TODO: (c) status of the Queen fragment. +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +{ { a4 g } f g } +@end lilypond -@cindex Lyrics -@cindex Songs -Lyrics are entered by separating each syllable with a space +@subheading Simultaneous music expressions: multiple staves -@example -I want to break free -@end example +Music glossary: @rglos{polyphony}. -Consider the melody +This technique is useful for @notation{polyphonic} music. To +enter music with more voices or more staves, we combine +expressions in parallel. To indicate that two voices should play +at the same time, simply enter a simultaneous combination of music +expressions. A @q{simultaneous} music expression is formed by +enclosing expressions inside @code{<<} and @code{>>}. In the +following example, three sequences (all containing two separate +notes) are combined simultaneously: -@lilypond[quote,verbatim,fragment,ragged-right] -\relative { - r4 c \times 2/3 { f g g } - \times 2/3 { g4( a2) } +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + << + { a4 g } + { f e } + { d b } + >> } @end lilypond -The lyrics can be set to these notes, combining both with the -@code{\addlyrics} keyword +Note that we have indented each level of the input with a +different amount of space. LilyPond does not care how much (or +little) space there is at the beginning of a line, but indenting +LilyPond code like this makes it much easier for humans to read. -@lilypond[quote,verbatim,fragment,ragged-right] -<< - \relative { - r4 c \times 2/3 { f g g } - \times 2/3 { g4( a2) } - } - \addlyrics { I want to break free } ->> -@end lilypond +@warning{each note is relative to the previous note in +the input, not relative to the @code{c''} in the initial +@code{\\relative} command.} -@cindex melisma -@cindex extender line -@c synonyms? -This melody ends on a @rglos{melisma}, a single syllable (`free') -sung to more than one note. This is indicated with an @emph{extender -line}. It is entered as two underscores, i.e., -@example -@{ I want to break free __ @} -@end example +@subheading Simultaneous music expressions: single staff -@lilypond[fragment,quote,ragged-right] -<< - \relative { - r4 c \times 2/3 { f g g } - \times 2/3 { g4( a2) } - } - \addlyrics { I want to break free __ } ->> +To determine the number of staves in a piece, LilyPond looks at +the first expression. If it is a single note, there is one staff; +if there is a simultaneous expression, there is more than one +staff. + +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + c2 <> + << { e f } { c <> } >> +} @end lilypond -Similarly, hyphens between words can be entered as two dashes, -resulting in a centered hyphen between two syllables +@cindex expression +@cindex music expression +@subheading Analogy: mathematical expressions + +This mechanism is similar to mathematical formulas: a big formula +is created by composing small formulas. Such formulas are called +expressions, and their definition is recursive so you can make +arbitrarily complex and large expressions. For example, @example -A -- le gri -- a -@end example +1 -@c no ragged-right here, because otherwise the hypens get lost. -@lilypond[fragment,quote] -<< - \relative { - \time 2/4 - f4 f c' c - } - \addlyrics { A -- le gri -- a } ->> -@end lilypond +1 + 2 + +(1 + 2) * 3 -More options, like putting multiple lines of lyrics below a melody are -discussed in @ref{Vocal music}. +((1 + 2) * 3) / (4 * 5) +@end example +This is a sequence of expressions, where each expression is +contained in the next (larger) one. The simplest expressions are +numbers, and larger ones are made by combining expressions with +operators (like @code{+}, @code{*} and @code{/}) and parentheses. +Like mathematical expressions, music expressions can be nested +arbitrarily deep, which is necessary for complex music like +polyphonic scores. -@node A lead sheet -@section A lead sheet -@cindex Lead sheets -@cindex chords -@cindex chord names +@node Multiple staves +@subsection Multiple staves -@c TODO: revise this, \chords { } is shorter and more intuitive. +LilyPond input files are constructed out of music expressions, as +we saw in @ref{Music expressions explained}. If the score begins +with simultaneous music expressions, LilyPond creates multiples +staves. However, it is easier to see what happens if we create +each staff explicitly. -In popular music, it is common to denote accompaniment with chord names. -Such chords can be entered like notes, +To print more than one staff, each piece of music that makes up a +staff is marked by adding @code{\new Staff} before it. These +@code{Staff} elements are then combined in parallel with @code{<<} +and @code{>>}: -@lilypond[quote,verbatim,ragged-right] -\chordmode { c2 f4. g8 } +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + << + \new Staff { \clef treble c } + \new Staff { \clef bass c,, } + >> +} @end lilypond -@noindent -Now each pitch is read as the root of a chord instead of a note. -This mode is switched on with @code{\chordmode} +The command @code{\new} introduces a @q{notation context.} A +notation context is an environment in which musical events (like +notes or @code{\clef} commands) are interpreted. For simple +pieces, such notation contexts are created automatically. For +more complex pieces, it is best to mark contexts explicitly. -Other chords can be created by adding modifiers after a colon. The -following example shows a few common modifiers +There are several types of contexts. @code{Score}, @code{Staff}, +and @code{Voice} handle melodic notation, while @code{Lyrics} sets +lyric texts and @code{ChordNames} prints chord names. -@lilypond[quote,verbatim,ragged-right] -\chordmode { c2 f4:m g4:maj7 gis1:dim7 } -@end lilypond +In terms of syntax, prepending @code{\new} to a music expression +creates a bigger music expression. In this way it resembles the +minus sign in mathematics. The formula @math{(4+5)} is an +expression, so @math{-(4+5)} is a bigger expression. -For lead sheets, chords are not printed on staves, but as names on a -line for themselves. This is achieved by using @code{\chords} instead -of @code{\chordmode}. This uses the same syntax as @code{\chordmode}, -but renders the notes in a @code{ChordNames} context, with the -following result. +Time signatures entered in one staff affects all other +staves@footnote{This behavior may be changed if desired; for +details, see @ruser{Polymetric notation}.}. On the other hand, +the key signature of one staff does @emph{not} affect other +staves. -@lilypond[quote,verbatim,ragged-right] -\chords { c2 f4.:m g4.:maj7 gis8:dim7 } +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + << + \new Staff { \clef treble \time 3/4 c } + \new Staff { \clef bass \key d \major c,, } + >> +} @end lilypond -@cindex lead sheet -When put together, chord names, lyrics and a melody form -a lead sheet, for example, + + + +@node Piano staves +@subsection Piano staves + +@cindex staff switch, manual +@cindex cross staff voice, manual + +Music glossary: @rglos{brace}. + +Piano music is typeset in two staves connected by a +@notation{brace}. +Printing such a staff is similar to the polyphonic example in +@ref{Multiple staves}. However, now this entire expression is +inserted inside a @code{PianoStaff}: @example -<< - \chords @{ @emph{chords} @} - @emph{the melody} - \addlyrics @{ @emph{the text} @} +\new PianoStaff << + \new Staff @dots{} + \new Staff @dots{} >> -@} @end example -@lilypond[quote,ragged-right] -<< - \chords { r2 c:sus4 f } - \relative { - r4 c' \times 2/3 { f g g } - \times 2/3 { g4( a2) } - } - \addlyrics { I want to break free __ } ->> +Here is a small example: + +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + \new PianoStaff << + \new Staff { \time 2/4 c4 e g g, } + \new Staff { \clef bass c,, c' e c } + >> +} @end lilypond -A complete list of modifiers and other options for layout can be found -in @ref{Chords}. +@seealso +Notation Reference: @ruser{Piano music}. -@node Adding titles -@section Adding titles -Bibliographic information is entered in a separate block, the -@code{\header} block. The name of the piece, its composer, etc., are -entered as an assignment, within @code{\header -@{@tie{}@dots{}@tie{}@}}. The @code{\header} block is usually put at -the top of the file. For example, +@node Combining notes into chords +@subsection Combining notes into chords -@example -\header @{ - title = "Miniature" - composer = "Igor Stravinsky" -@} +@cindex chords -@{ @dots{} @} -@end example +Music glossary: @rglos{chord}. + +@notation{Chords} can be made by surrounding pitches with single +angle brackets. Angle brackets are the symbols @code{<} and +@code{>}. + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +r4 4 2 +@end lilypond + +You can combine markings like beams and ties with chords. They +must be placed outside the angle brackets. +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +r4 8[ ]~ 2 +@end lilypond -When the file is processed, the title and composer are printed above -the music. More information on titling can be found in @ref{Creating -titles}. +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +r4 8\>( 4 \!) +@end lilypond @node Single staff polyphony -@section Single staff polyphony +@subsection Single staff polyphony @cindex polyphony @cindex multiple voices @cindex voices, more -- on a staff -When different melodic lines are combined on a single staff they are -printed as polyphonic voices; each voice has its own stems, slurs and -beams, and the top voice has the stems up, while the bottom voice has -them down. - -Entering such parts is done by entering each voice as a sequence (with -@code{@{...@}}), and combining these simultaneously, separating the -voices with @code{\\} - -@lilypond[quote,verbatim,relative=2,fragment] -<< { a4 g2 f4~ f4 } \\ - { r4 g4 f2 f4 } >> +When different melodic lines are combined on a single staff they +are printed as polyphonic voices; each voice has its own stems, +slurs and beams, and the top voice has the stems up, while the +bottom voice has them down. + +Entering such parts is done by entering each voice as a sequence +(with @code{@{...@}}) and combining these simultaneously, +separating the voices with @code{\\} + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +<< + { a4 g2 f4~ f4 } \\ + { r4 g4 f2 f4 } +>> @end lilypond -For polyphonic music typesetting, spacer rests can also be convenient; -these are rests that do not print. They are useful for filling up -voices that temporarily do not play. Here is the same example with a -spacer rest (@code{s}) instead of a normal rest (@code{r}), +For polyphonic music typesetting, spacer rests can also be +convenient; these are rests that do not print. They are useful +for filling up voices that temporarily do not play. Here is the +same example with a spacer rest (@code{s}) instead of a normal +rest (@code{r}), -@lilypond[quote,verbatim,relative=2,fragment] -<< { a4 g2 f4~ f4 } \\ - { s4 g4 f2 f4 } >> +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +<< + { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } +>> @end lilypond @noindent -Again, these expressions can be nested arbitrarily +Again, these expressions can be nested arbitrarily. -@lilypond[quote,fragment,verbatim,relative=2,fragment] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] << \new Staff << { a4 g2 f4~ f4 } \\ @@ -1172,244 +1214,476 @@ Again, these expressions can be nested arbitrarily >> @end lilypond -More features of polyphonic typesetting are described in this manual -in section @ref{Basic polyphony}. +@seealso +Notation Reference: @ruser{Simultaneous notes}. -@node Piano staves -@section Piano staves -@cindex staff switch, manual -@cindex cross staff voice, manual -Piano music is typeset in two staves connected by a brace. Printing -such a staff is similar to the polyphonic example in @ref{More staves}, +@node Songs +@section Songs -@example -<< \new Staff @{ @dots{} @} - \new Staff @{ @dots{} @} >> -@end example +This section introduces vocal music and simple song sheets. -@noindent -but now this entire expression must be interpreted as a -@code{PianoStaff} +@menu +* Setting simple songs:: +* Aligning lyrics to a melody:: +* Lyrics to multiple staves:: +@end menu -@example -\new PianoStaff << \new Staff @dots{} >> -@end example -Here is a small example +@node Setting simple songs +@subsection Setting simple songs -@lilypond[quote,verbatim,relative=1,fragment] -\new PianoStaff << - \new Staff { \time 2/4 c4 c g' g } - \new Staff { \clef bass c,, c' e c } +@cindex lyrics +@cindex songs + +Music glossary: @rglos{lyrics}. + +Here is the start of the melody to a nursery +rhyme, @qq{Girls and boys come out to play}: + +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + \key g \major + \time 6/8 + d4 b8 c4 a8 d4 b8 g4 +} +@end lilypond + +The @notation{lyrics} can be set to these notes, combining both +with the @code{\addlyrics} keyword. Lyrics are entered by +separating each syllable with a space. + +@lilypond[verbatim,quote,ragged-right] +<< + \relative c'' { + \key g \major + \time 6/8 + d4 b8 c4 a8 d4 b8 g4 + } + \addlyrics { + Girls and boys come out to play, + } >> @end lilypond -More information on formatting piano music is given in @ref{Piano music}. +Note the curly brackets delimiting both the music and the lyrics, +and the angle brackets @code{<< ... >>} around the whole piece to +show that the music and lyrics are to occur at the same time. +@node Aligning lyrics to a melody +@subsection Aligning lyrics to a melody -@node Organizing larger pieces -@section Organizing larger pieces +Music glossary: @rglos{melisma}, @rglos{extender line}. -When all of the elements discussed earlier are combined to produce -larger files, the @code{\score} blocks get a lot bigger because the -music expressions are longer, and, in the case of polyphonic music, -more deeply nested. Such large expressions can become unwieldy. +@cindex melisma +@cindex extender line +@cindex hyphens +@cindex underscore -By using variables, also known as identifiers, it is possible to break -up complex music expressions. An identifier is assigned as follows +The next line in the nursery rhyme is @q{The moon doth shine as +bright as day}. Let's extend it: -@example -namedMusic = @{ @dots{} @} -@end example +@lilypond[verbatim,quote,ragged-right] +<< + \relative c'' { + \key g \major + \time 6/8 + d4 b8 c4 a8 d4 b8 g4 + g8 a4 b8 c b a d4 b8 g4. + } + \addlyrics { + Girls and boys come out to play, + The moon doth shine as bright as day; + } +>> +@end lilypond -@noindent -The contents of the music expression @code{namedMusic}, can be used -later by preceding the name with a backslash, i.e., @code{\namedMusic}. -In the next example, a two-note motive is repeated two times by using -variable substitution - -@lilypond[quote,ragged-right,verbatim,nofragment] -seufzer = { - e'4( dis'4) -} -{ \seufzer \seufzer } +We see the extra lyrics do not align properly with the notes. The +word @q{shine} should be sung on two notes, not one. This is +called a @notation{melisma}, a single syllable sung to more than one +note. There are several ways to spread a syllable over multiple +notes, the simplest being to add a slur across them (see @ref{Ties +and slurs}): + +@lilypond[verbatim,quote,ragged-right] +<< + \relative c'' { + \key g \major + \time 6/8 + d4 b8 c4 a8 d4 b8 g4 + g8 a4 b8 c([ b)] a d4 b8 g4. + } + \addlyrics { + Girls and boys come out to play, + The moon doth shine as bright as day; + } +>> @end lilypond -The name of an identifier should have alphabetic characters only: no -numbers, underscores, or dashes. The assignment should be outside of -running music. +Here we have also used manual beaming (the square brackets @code{[ +]} ) to generate the beaming which is customarily used with lyrics +(see @ref{Automatic and manual beams}). -It is possible to use variables for many other types of objects in the -input. For example, +If a syllable extends over several notes or a single very long +note an @notation{extender line} is usually drawn from the syllable +extending under all the notes for that syllable. It is entered as +two underscores @code{__}. Here is an example from the first +three bars of Dido's Lament, from Purcell's Dido and Æneas: -@example -width = 4.5\cm -name = "Wendy" -aFivePaper = \paper @{ paperheight = 21.0 \cm @} -@end example +@lilypond[verbatim,quote,ragged-right] +<< + \relative c'' { + \key g \minor + \time 3/2 + g2 a bes bes( a) + b c4.( bes8 a4. g8 fis4.) g8 fis1 + } + \addlyrics { + When I am laid, + am laid __ in earth, + } +>> +@end lilypond -Depending on its contents, the identifier can be used in different -places. The following example uses the above variables +None of the examples so far have involved words containing more +than one syllable. Such words are usually split one syllable to a +note, with hyphens between syllables. Such hyphens are entered as +two dashes, resulting in a centered hyphen between the syllables. +Here is an example showing this and everything we have learned so +far about aligning lyrics to notes. -@example -\paper @{ - \aFivePaper - line-width = \width -@} -@{ c4^\name @} -@end example +@c no ragged-right here because otherwise the hyphens get lost, +@c but the example is long enough to avoid looking strange. +@lilypond[verbatim,quote] +<< + \relative c' { + \key g \major + \time 3/4 + \partial 4 + d4 g4 g a8( b) g4 g4 + b8( c) d4 d e4 c2 + } + \addlyrics { + A -- way in a __ man -- ger, + no __ crib for a bed, __ + } +>> +@end lilypond + +Some lyrics, especially those in Italian, require the opposite: +setting more than one syllable to a single note. This is +achieved by linking the syllables together with a single +underscore @code{_} (with no spaces), or enclosing them in +quotes. Here's an example from Rossini's Figaro, where +@q{al} has to be sung on the same note as the @q{go} of +@q{Largo} in Figaro's aria @q{Largo al factotum}: + +@c no ragged-right here because otherwise the hyphens get lost, +@c but the example is long enough to avoid looking strange. +@lilypond[verbatim,quote] +<< + \relative c' { + \clef bass + \key c \major + \time 6/8 + c4.~ c8 d b c([ d)] b c d b c + } + \addlyrics { + Lar -- go_al fac -- to -- tum del -- la cit -- tà + } +>> +@end lilypond + + +@seealso + +Notation Reference: @ruser{Vocal music}. + + +@node Lyrics to multiple staves +@subsection Lyrics to multiple staves + +The simple approach using @code{\addlyrics} can be used for +placing lyrics under more than one staff. Here is an +example from Handel's Judas Maccabæus: + +@lilypond[verbatim,quote,ragged-right] +<< + { + \time 6/8 + \partial 8 + } + \relative c'' { + \key f \major + c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4 + } + \addlyrics { + Let flee -- cy flocks the hills a -- dorn, __ + } + \relative c' { + \key f \major + r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4 + } + \addlyrics { + Let flee -- cy flocks the hills a -- dorn, + } +>> +@end lilypond + +but scores any more complex than this simple example are +better produced by separating out the staff structure +from the notes and lyrics with variables. These are +discussed later (see @ref{Organizing pieces with variables}). + +@seealso + +Notation Reference: @ruser{Vocal music}. -More information on the possible uses of identifiers is given in the -technical manual, in @ref{Input variables and Scheme}. -@c fixme: the ref is too technical. +@node Final touches +@section Final touches + +This is the final section of the tutorial; it demonstrates how to +add the final touches to simple pieces, and provides an +introduction to the rest of the manual. + +@menu +* Version number:: +* Adding titles:: +* Absolute note names:: +* Organizing pieces with variables:: +* After the tutorial:: +* How to read the manual:: +@end menu -@node An orchestral part -@section An orchestral part -In orchestral music, all notes are printed twice. Once in a part for -the musicians, and once in a full score for the conductor. Identifiers can -be used to avoid double work. The music is entered once, and stored in -a variable. The contents of that variable is then used to generate -both the part and the full score. +@node Version number +@subsection Version number -It is convenient to define the notes in a special file. For example, -suppose that the file @file{horn-music.ly} contains the following part -of a horn/@/bassoon duo +@cindex versioning +The @code{\version} statement records the version of LilyPond that +was used to write the file: @example -hornNotes = \relative c @{ - \time 2/4 - r4 f8 a cis4 f e d -@} +\version "2.11.23" @end example @noindent -Then, an individual part is made by putting the following in a file +By convention, this is placed at the top of your LilyPond file. + +These annotations make future upgrades of LilyPond go more +smoothly. Changes in the syntax are handled with a special +program, @file{convert-ly}, and it uses @code{\version} to +determine what rules to apply. For details, see +@rprogram{Updating files with convert-ly}. + + +@node Adding titles +@subsection Adding titles + +The title, composer, opus number, and similar information are +entered in the @code{\header} block. This exists outside of the +main music expression; the @code{\header} block is usually placed +underneath the @ref{Version number}. @example -\include "horn-music.ly" +\version "2.11.23" \header @{ - instrument = "Horn in F" + title = "Symphony" + composer = "Me" + opus = "Op. 9" @} @{ - \transpose f c' \hornNotes + @dots{} music @dots{} @} @end example -The line +When the file is processed, the title and composer are printed +above the music. More information on titling can be found in +@ruser{Creating titles}. -@example -\include "horn-music.ly" -@end example -@noindent -substitutes the contents of @file{horn-music.ly} at this position in -the file, so @code{hornNotes} is defined afterwards. The command -@code{\transpose f@tie{}c'} indicates that the argument, being -@code{\hornNotes}, should be transposed by a fifth upwards. Sounding -@samp{f} is denoted by notated @code{c'}, which corresponds with the -tuning of a normal French Horn in@tie{}F. The transposition can be seen -in the following output +@node Absolute note names +@subsection Absolute note names -@lilypond[quote,ragged-right] -\transpose f c' \relative c { - \time 2/4 - r4 f8 a cis4 f e d +So far we have always used @code{\relative} to define pitches. +This is the easiest way to enter most music, but another way of +defining pitches exists: absolute mode. + +If you omit the @code{\relative}, LilyPond treats all pitches as +absolute values. A @code{c'} will always mean middle C, a +@code{b} will always mean the note one step below middle C, and a +@code{g,} will always mean the note on the bottom staff of the +bass clef. + +@lilypond[verbatim,quote,ragged-right] +{ + \clef bass + c' b g, g, + g, f, f c' } @end lilypond -In ensemble pieces, one of the voices often does not play for many -measures. This is denoted by a special rest, the multi-measure -rest. It is entered with a capital @samp{R} followed by a duration -(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note, -etc.). By multiplying the -duration, longer rests can be constructed. For example, this rest -takes 3@tie{}measures in 2/4 time +Here is a four-octave scale: -@example -R2*3 -@end example +@lilypond[verbatim,quote,ragged-right] +{ + \clef bass + c, d, e, f, + g, a, b, c + d e f g + a b c' d' + \clef treble + e' f' g' a' + b' c'' d'' e'' + f'' g'' a'' b'' + c'''1 +} +@end lilypond -When printing the part, multi-rests -must be condensed. This is done by setting a run-time variable +As you can see, writing a melody in the treble clef involves a lot +of quote @code{'} marks. Consider this fragment from Mozart: -@example -\set Score.skipBars = ##t -@end example +@lilypond[verbatim,quote,ragged-right] +{ + \key a \major + \time 6/8 + cis''8. d''16 cis''8 e''4 e''8 + b'8. cis''16 b'8 d''4 d''8 +} +@end lilypond -@noindent -This command sets the property @code{skipBars} in the -@code{Score} context to true (@code{##t}). Prepending the rest and -this option to the music above, leads to the following result +All these quotes makes the input less readable and it is a source +of errors. With @code{\relative}, the previous example is much +easier to read: -@lilypond[quote,ragged-right] -\transpose f c' \relative c { - \time 2/4 - \set Score.skipBars = ##t - R2*3 - r4 f8 a cis4 f e d +@lilypond[verbatim,quote,ragged-right] +\relative c'' { + \key a \major + \time 6/8 + cis8. d16 cis8 e4 e8 + b8. cis16 b8 d4 d8 } @end lilypond +If you make a mistake with an octave mark (@code{'} or @code{,}) +while working in @code{\relative} mode, it is very obvious -- many +notes will be in the wrong octave. When working in absolute mode, +a single mistake will not be as visible, and will not be as easy +to find. -The score is made by combining all of the music together. Assuming -that the other voice is in @code{bassoonNotes} in the file -@file{bassoon-music.ly}, a score is made with +However, absolute mode is useful for music which has large +intervals, and is extremely useful for computer-generated LilyPond +files. -@example -\include "bassoon-music.ly" -\include "horn-music.ly" -<< - \new Staff \hornNotes - \new Staff \bassoonNotes ->> +@node Organizing pieces with variables +@subsection Organizing pieces with variables + +When all of the elements discussed earlier are combined to produce +larger files, the music expressions get a lot bigger. In +polyphonic music with many staves, the input files can become very +confusing. We can reduce this confusion by using +@emph{variables}. + +With variables (also known as identifiers or macros), we can break +up complex music expressions. A variable is assigned as +follows: + +@example +namedMusic = @{ @dots{} @} @end example +The contents of the music expression @code{namedMusic} can be used +later by placing a backslash in front of the name +(@code{\namedMusic}, just like a normal LilyPond command). +Variables must be defined @emph{before} the main music +expression. + +@lilypond[verbatim,quote,ragged-right] +violin = \new Staff { \relative c'' { + a4 b c b +}} +cello = \new Staff { \relative c { + \clef bass + e2 d +}} +{ + << + \violin + \cello + >> +} +@end lilypond + @noindent -leading to +The name of a variable must have alphabetic characters only, no +numbers, underscores, or dashes. -@lilypond[quote,ragged-right] -\relative c << - \new Staff { - \time 2/4 R2*3 - r4 f8 a cis4 f e d - } - \new Staff { - \clef bass - r4 d,8 f | gis4 c | b bes | - a8 e f4 | g d | gis f - } ->> -@end lilypond +It is possible to use variables for many other types of objects in +the input. For example, -More in-depth information on preparing parts and scores can be found -in the notation manual; see @ref{Orchestral music}. +@example +width = 4.5\cm +name = "Wendy" +aFivePaper = \paper @{ paperheight = 21.0 \cm @} +@end example -Setting run-time variables (`properties') is discussed in -@ref{Changing context properties on the fly}. +Depending on its contents, the variable can be used in different +places. The following example uses the above variables: + +@example +\paper @{ + \aFivePaper + line-width = \width +@} +@{ c4^\name @} +@end example @node After the tutorial -@section After the tutorial +@subsection After the tutorial After finishing the tutorial, you should probably try writing a -piece or two. Start with one of the @ref{Example templates} and -add notes. If you need any notation that was not covered in the +piece or two. Start by adding notes to one of the @ref{Templates}. +If you need any notation that was not covered in the tutorial, look at the Notation Reference, starting with -@ref{Basic notation}. If you want to write for an instrument -ensemble which is not covered in the @ref{Example templates}, -take a look at @ref{Extending the templates}. - -Once you have written a few short pieces, read the rest of -the Learning Manual (chapters 3-5). There's nothing wrong -with reading them now, of course! However, the rest of the -Learning Manual assumes that you are familiar with -LilyPond input. You may wish to skim these chapters right -now, and come back to them after you have more experience. - +@ruser{Musical notation}. If you want to write for an instrument +ensemble that is not covered in the templates, take a look at +@ref{Extending the templates}. + +Once you have written a few short pieces, read the rest of the +Learning Manual (chapters 3-5). There's nothing wrong with +reading it now, of course! However, the rest of the Learning +Manual assumes that you are familiar with LilyPond input. You may +wish to skim these chapters right now, and come back to them after +you have more experience. + + +@node How to read the manual +@subsection How to read the manual + +Many examples in the tutorial omitted a @code{\relative c'' @{ +... @}} around the printed example, as we saw in +@ref{How to read the tutorial}. + +In the rest of the manual, we are much more lax about the printed +examples: sometimes they may have omitted a @code{\relative c'' @{ +... @}}, but other times a different initial pitch may be used +(such as @code{c'} or @code{c,,}), and in some cases the whole +example is in absolute note mode! However, ambiguities like this +only exist where the pitches are not important. In any example +where the pitch matters, we have explicitly stated +@code{\relative} or absolute-mode @code{@{ @}}. + +If you are still confused about the exact LilyPond input that was +used in an example, read the HTML version (if you are not already +doing so) and click on the picture of the music. This will +display the exact input that LilyPond used to generate this +manual. + +For information about the structure of the rest of the manual, see +@ref{About this manual}.