X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=c4681c27cc11961f7b24fb9ca2618a6d5a735962;hb=b6304f90bdada0051d8b2e28c97549ca8ec58fd9;hp=8549412cd8c38cad440103e8491dc1c4450aa593;hpb=644aaf7fa495930384e446df894b12124b4fd727;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 8549412cd8..c4681c27cc 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,5 +1,5 @@ @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 @@ -8,60 +8,32 @@ @end ignore @ignore -Tutorial guidelines: +Tutorial guidelines: (different from policy.txt!) - unless you have a really good reason, use either - @l ilypond[verbatim,quote,ragged-right] + @lilypond[verbatim,quote,ragged-right] or - @l ilypond[verbatim,quote,ragged-right,fragment,relative=2] - (without spaces) + @lilypond[verbatim,quote,ragged-right,fragment,relative=2] + 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 "aes". I know it's not + +- 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. -@end ignore - +- Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant + portions of the tutorial. -@c old info that will probably be removed. -@c TODO: -@c * more details about running lilypond; error messages, -@c compiling/viewing (emacs?) -@c * where to go from First steps+More basics? - -@c wherever possible, do not include index entries here; the -@c index should point to stuff in the reference manual. -gp +@end ignore -@c Your first LilyPond score in 10 minutes? @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. - -@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 - -@c no verbatim here -@lilypond[quote,ragged-right] -\relative c'' { - c-\markup { \bold \huge { Click here. } } -} -@end lilypond - -By cutting and pasting everything in the @qq{ly snippet} section, -you have a starting template for experiments. If you like -learning in this way, you will probably want to print out or -bookmark the @ruser{Cheat sheet}, which is a table listing of the -most common commands for quick reference. - -@end ifhtml +language and explains how to produce printed music. After this first +contact we will explain how to create beautiful printed music +containing common musical notation. @menu * First steps:: @@ -81,16 +53,20 @@ This section gives a basic introduction to working with LilyPond. * Compiling a file:: * Simple notation:: * Working on text files:: -* How to read the tutorial:: +* How to read the manual:: @end menu @node Compiling a file @subsection Compiling a file -The first example demonstrates how to start working with LilyPond. +@qq{Compiling} is the term used for processing an input text file +in LilyPond format to produce a file which can be printed and +(optionally) a MIDI file which can be played. The first example +shows what a simple input text file looks like. + To create sheet music, we write a text file that specifies the -notation. For example, if we write +notation. For example, if we write: @example @{ @@ -99,7 +75,7 @@ notation. For example, if we write @end example @noindent -the result looks like this +the result looks like this: @c in this case we don't want verbatim @lilypond[quote,ragged-right] @@ -108,41 +84,50 @@ the result looks like this } @end lilypond -@strong{Warning:} Every piece of LilyPond input needs to have -@strong{@{ curly braces @}} placed around the input. The braces +@warning{Notes and lyrics in LilyPond input must always be +surrounded by @strong{@{ curly braces @}}. The braces should also be surrounded by a space unless they are at the -beginning or end of a line to avoid ambiguities. These may be -omitted in some examples in this manual, but don't forget them in -your own music! +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 manual}.} -@cindex Case sensitive +@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 +@{ c d e @}} is valid input; @code{@{ C D E @}} will produce an error message. -@sp 1 +@smallspace @subheading 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. +Note that there are several other text editors available with +better support for LilyPond. For more information, see +@rprogram{Text editor support}. + +@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!} + @subsubheading MacOS X 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 @samp{Compile > +Desktop, and then process it with the menu command @code{Compile > Typeset File}. The resulting PDF file will be displayed on your screen. -Be warned that the first time you ever run LilyPond, it will take -a minute or two because all of the system fonts have to be -analyzed first. - 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. + @subsubheading Windows On Windows, if you double-click in the LilyPond icon on the @@ -156,70 +141,51 @@ 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 +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. +the @qq{File} menu, or right-click on the desktop and select +@qq{New..Text Document}, change its name to a name of your choice +and change the file extension to @code{.ly}. Double-click the +icon to type in your LilyPond source code as before. 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. -Note that there are several other text editors available, with -better support for LilyPond, see @rprogram{Text editor support}, -for more information. - @subsubheading Unix -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}. -The easiest editing environment is @file{LilyPondTool}. See -@rprogram{Text editor support}, for more information.}. In your -text editor, enter the following input and save the file as -@file{test.ly} - -@verbatim -{ +Create a text file called @file{test.ly} and enter: + +@example +@{ c' e' g' e' -} -@end verbatim +@} +@end example -@noindent -To process @file{test.ly}, proceed as follows +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 PDF file -@cindex Viewing music - -@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 such 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 Simple notation @subsection Simple notation @@ -241,24 +207,30 @@ values are useful. @subheading Pitches +Music Glossary: @rglos{pitch}, @rglos{interval}, +@rglos{scale}, @rglos{middle C}, @rglos{octave}, +@rglos{accidental}. + The easiest way to enter notes is by using @code{\relative} mode. -In this mode, the @rglos{interval} between the previous note and -the current note is assumed to be within a @rglos{fourth}. We -begin by entering the most elementary piece of music, a -@rglos{scale}. +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[verbatim,quote,ragged-right] -\relative c' { +\relative c' { % set the starting point to middle C c d e f g a b c } @end lilypond -The initial note is @rglos{middle C}. Each successive note is -within a fourth of the previous note -- in other words, the first -@samp{c} is the closest C to middle C. This is followed by the +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: +larger intervals, still using only @code{\relative} mode: @lilypond[verbatim,quote,ragged-right] \relative c' { @@ -268,13 +240,50 @@ larger intervals: @end lilypond @noindent -As you may notice, this example does not start on middle C. The -first note -- the @samp{d} -- is the closest D to middle C. +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 E it will be assumed to be +above the B, and an A, G or F will be assumed to be below. -To add intervals that are larger than a fourth, we can raise the -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'' { + 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 6 up or 1 down, so is the a below + b g % g is 5 up or 2 down, so is the g below + b f % f is 4 up or 3 down, so is the f below +} +@end lilypond + +Exactly the same happens even when any of these notes are +sharpened or flattened. @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. + +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'' { @@ -289,14 +298,22 @@ To change a note by two (or more!) octaves, we use multiple quotes @code{''} and not one double quote @code{"}@tie{}! The initial value in @code{\relative c'} may also be modified like this. - +@c " - keeps quotes in order for context-sensitive editor -td @subheading Durations (rhythms) -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. -Beams are added automatically. +Music Glossary: @rglos{beam}, @rglos{duration}, +@rglos{whole note}, @rglos{half note}, @rglos{quarter note}, +@rglos{dotted note}. + +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. + +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. @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -306,13 +323,9 @@ Beams are added automatically. } @end lilypond -@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. - -To create @rglos{dotted note}s, add a dot @samp{.} to the duration -number. +To create @notation{dotted notes}, add a dot @code{.} to the +duration number. The duration of a dotted note must be stated +explicitly (i.e., with a number). @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -324,7 +337,10 @@ number. @subheading Rests -A @rglos{rest} is entered just like a note with the name @samp{r}: +Music Glossary: @rglos{rest}. + +A @notation{rest} is entered just like a note with the name +@code{r}: @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -336,7 +352,9 @@ A @rglos{rest} is entered just like a note with the name @samp{r}: @subheading Time signature -The @rglos{time signature}) can be set with the @code{\time} +Music Glossary: @rglos{time signature}. + +The @notation{time signature} can be set with the @code{\time} command: @lilypond[verbatim,quote,ragged-right] @@ -353,7 +371,9 @@ command: @subheading Clef -The @rglos{clef} can be set using the @code{\clef} command: +Music Glossary: @rglos{clef}. + +The @notation{clef} can be set using the @code{\clef} command: @lilypond[verbatim,quote,ragged-right] \relative c' { @@ -382,19 +402,12 @@ Here is a small example showing all these elements together: } @end lilypond + @seealso -@quotation -@table @asis -@item Entering pitches and durations -see @ruser{Pitches}, and @ruser{Durations}. -@item Rests -see @ruser{Rests}. -@item Time signatures and other timing commands -see @ruser{Time signature}. -@item Clefs -see @ruser{Clef}. -@end table -@end quotation + +Notation Reference: @ruser{Writing pitches}, +@ruser{Writing rhythms}, @ruser{Writing rests}, +@ruser{Time signature}, @ruser{Clef}. @node Working on text files @@ -402,27 +415,33 @@ see @ruser{Clef}. 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 +is generally ignored. Expressions are formed with curly braces @{ @}, and comments are denoted with @code{%} or @code{%@{ ... %@}}. -If the previous sentence sounds like nonsense, don't worry! We'll +If the previous sentences sound like nonsense, don't worry! We'll explain what all these terms mean: @itemize -@cindex Case sensitive -@item @strong{Case sensitive}: -it matters whether you enter a letter in lower case (i.e. @code{a, -b, s, t}) or upper case (i.e. @code{A, B, S, T}). Notes are +@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. -@item @strong{Whitespace insensitive}: +@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 @example @{ c d e -@} @end example +@tie{} @tie{} d e @}} and: + +@example +@{ c d + e @} +@end example @noindent Of course, the previous example is hard to read. A good rule of @@ -434,61 +453,70 @@ thumb is to indent code blocks with either a tab or two spaces: @} @end example -@item @strong{Expressions:} -Every piece of LilyPond input needs to have @strong{@{ curly +@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 parenthesis -@samp{()} in mathematics. The braces should be surrounded by a +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. +A LilyPond command followed by a simple expression in braces (such +as @code{\relative @{ @}}) also counts as a single music +expression. @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 +@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 -@samp{%} introduces a line comment; anything after @samp{%} 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 +@code{%} introduces a line comment; anything after @code{%} on +that line is ignored. By convention, a line comment is placed +@emph{above} the code it refers to. + +@example +a4 a a a +% this comment refers to the Bs +b2 b +@end example + +A block comment marks a whole section of music input as a comment. +Anything that is enclosed in @code{%@{} and @code{%@}} is ignored. +However, block comments do not @q{nest}. This means that you +cannot place a block comment inside another block comment. If you +try, the first @code{%@}} will terminate @emph{both} block +comments. The following fragment shows possible uses for +comments: @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. + This line, and the notes below + are ignored, since they are in a + block comment. - g g f f e e d d c2 + g g f f e e d d c2 %@} @end example @end itemize -There are more tips for constructing input files in -@ruser{Suggestions for writing LilyPond files}. - -@node How to read the tutorial -@subsection How to read the tutorial - -As we saw in @ruser{Working on text files}, LilyPond input must be -surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}. -For the rest of this manual, most examples will omit this. +@node How to read the manual +@subsection How to read the manual -If you are reading the HTML documentation and wish to see the -exact exact LilyPond code that was used to create the example, -simply click on the picture. If you are not reading the HTML -version, you could copy and paste the displayed input, but you -@strong{must} add the @code{\relative c'' @{ @}} like this: +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'' @{ @@ -500,9 +528,40 @@ 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}, so you would not be able to copy a small +@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. +own. Most people want to add material to an existing piece, so we +format the manual this way. + + +@subheading Clickable examples + +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: + +@c no verbatim here +@lilypond[quote,ragged-right] +\relative c'' { + c-\markup { \bold \huge { Click here. } } +} +@end lilypond + +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. + +@seealso + + +There are more tips for constructing input files in +@ref{Suggestions for writing LilyPond files}. But it might be +best to read through the rest of the tutorial first. + @node Single staff notation @@ -512,59 +571,30 @@ This section introduces common notation that is used for one voice on one staff. @menu -* Relative note names:: * Accidentals and key signatures:: * Ties and slurs:: * Articulation and dynamics:: +* Adding text:: * Automatic and manual beams:: * Advanced rhythmic commands:: @end menu -@node Relative note names -@subsection Relative note names - -As we saw in @ruser{Simple notation}, LilyPond calculates the -pitch of each note relative to the previous one@footnote{There is -another mode of entering pitches, @ruser{Absolute note names}, but -in practice relative mode is much easier and safer to use.}. If -no extra octave marks (@code{'} and @code{,}) are added, it -assumes that each pitch is within a fourth of the previous note. - -LilyPond examines pitches based on the note names -- in other -words, an augmented fourth is @emph{not} the same as a diminished -fifth. If we begin at a C, then an F-sharp will be placed a -higher than the C, while a G-flat will be placed lower than the C. - -@lilypond[verbatim,quote,ragged-right,fragment,relative=2] -c2 fis -c2 ges -@end lilypond - -@seealso -@quotation -@table @asis -@item Relative octaves -see @ruser{Relative octaves}. -@item Octave check -see @ruser{Octave check}. -@end table -@end quotation - - - @node Accidentals and key signatures @subsection Accidentals and key signatures @subheading Accidentals -A @rglos{sharp} pitch is made by adding @samp{is} to the name, and -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. To use other names for accidentals, see @ruser{Note -names in other languages}.} +Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp}, +@rglos{double flat}, @rglos{accidental}. + +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 is 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[verbatim,quote,ragged-right,fragment,relative=2] cis1 ees fisis, aeses @@ -573,8 +603,11 @@ cis1 ees fisis, aeses @cindex key signature, setting @subheading Key signatures -The key signature is set with the command @code{\key} followed by -a pitch and @code{\major} or @code{\minor}. +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}. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] \key d \major @@ -583,27 +616,32 @@ a1 a @end lilypond -@sp 1 +@smallspace @subheading Warning: key signatures and pitches -To determine whether to print an accidental, LilyPond examines the -pitches and the key signature. The key signature only affects the -@emph{printed} accidentals, not the actual pitches! This is a -feature that often causes confusion to newcomers, so let us -explain it in more detail. +Music Glossary: @rglos{accidental}, @rglos{key signature}, +@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp}, +@rglos{transposition}. -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 @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. +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. -In this example +LilyPond makes a sharp distinction between musical content and +layout. The alteration (@notation{flat}, @notation{natural sign} 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 @@ -611,11 +649,11 @@ d cis fis @end lilypond @noindent -No note has a printed accidental, but you must still add the -@samp{is} to @code{cis} and @code{fis}. +No note has a printed accidental, but you must still add +@code{is} and type @code{cis} and @code{fis} in the input file. -The code @samp{e} does not mean @qq{print a black dot just below -the first line of the staff.} Rather, it means: @qq{there is a +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: @@ -625,20 +663,19 @@ e @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 @ruser{Automatic accidentals}, for some examples -how accidentals can be printed according to different rules. +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}. @seealso -@quotation -@table @asis -@item Accidentals -see @ruser{Accidentals}, and @ruser{Automatic accidentals}. -@item Key signature -see @ruser{Key signature}. -@end table -@end quotation + +Notation Reference: @ruser{Note names in other languages}, +@ruser{Accidentals}, @ruser{Automatic accidentals}, +@ruser{Key signature}. + +Music Glossary: @rglos{Pitch names}. @node Ties and slurs @@ -646,8 +683,11 @@ see @ruser{Key signature}. @cindex ties @subheading Ties -A @rglos{tie} is created by appending a tilde @samp{~} to the -first note being tied + +Music Glossary: @rglos{tie}. + +A @notation{tie} is created by appending a tilde @code{~} to the +first note being tied. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] g4~ g c2~ @@ -657,9 +697,11 @@ c4 ~ c8 a8 ~ a2 @cindex slurs @subheading Slurs -A @rglos{slur} is a curve drawn across many notes. The starting -note and ending note are marked with @samp{(} and @samp{)} -respectively. +Music Glossary: @rglos{slur}. + +A @notation{slur} is a curve drawn across many notes. The +starting note and ending note are marked with @code{(} and +@code{)} respectively. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] d4( c16) cis( d e c cis d) e( d4) @@ -669,41 +711,38 @@ d4( c16) cis( d e c cis d) e( d4) @cindex phrasing slurs @subheading Phrasing slurs -Slurs to indicate longer phrasing can be entered with @code{\(} -and @code{\)}. You can have both legato slurs and phrasing slurs -at the same time, but you cannot have simultaneous slurs or -simultaneous phrasing slurs. +Music Glossary: @rglos{slurs}, @rglos{phrasing}. + +Slurs to indicate longer @notation{phrasing} can be entered with +@code{\(} and @code{\)}. You can have both @notation{slurs} +and phrasing slurs at the same time, but you cannot have +simultaneous slurs or simultaneous phrasing slurs. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8(\( ais b c) cis2 b'2 a4 cis,\) @end lilypond -@sp 1 +@smallspace @cindex slurs versus ties @subheading Warnings: slurs vs. ties -A slur looks like a @rglos{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 -articulations of notes, and can be used on larger groups of notes. -Slurs and ties can be nested. +Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}. + +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 @seealso -@quotation -@table @asis -@item Ties -see @ruser{Ties}. -@item Slurs -see @ruser{Slurs}. -@item Phrasing slurs -see @ruser{Phrasing slurs}. -@end table -@end quotation + +Notation Reference: @ruser{Ties}, @ruser{Slurs}, +@ruser{Phrasing slurs}. @node Articulation and dynamics @@ -714,8 +753,10 @@ see @ruser{Phrasing slurs}. @cindex staccato @subheading Articulations -Common @rglos{articulation}s can be added to a note using a dash -@samp{-} and a single character: +Music Glossary: @rglos{articulation}. + +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-_ @@ -723,26 +764,34 @@ c-. c-- c-> c-^ c-+ c-_ @cindex fingering @subheading Fingerings -Similarly, fingering indications can be added to a note using a -dash (@samp{-}) and the digit to be printed: + +Music Glossary: @rglos{fingering}. + + +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. -However, in most cases it is best to let LilyPond determine the -articulation directions. +you can specify a direction by replacing the dash (@code{-}) with +@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[verbatim,quote,ragged-right,fragment,relative=2] c_-^1 d^. f^4_2-> e^-_+ @end lilypond @subheading Dynamics -Dynamic signs are made by adding the markings (with a backslash) -to the note + +Music Glossary: @rglos{dynamics}, @rglos{crescendo}, +@rglos{decrescendo}. + +@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 @@ -752,32 +801,52 @@ c\ff c\mf c\p c\pp @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{\>}. The next dynamics sign, for +example @code{\f}, will end the (de)crescendo, or the command +@code{\!} can be used: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2\< c2\ff\> c2 c2\! @end lilypond @seealso -@quotation -@table @asis -@item Articulations -see @ruser{Articulations}. -@item Fingering -see @ruser{Fingering instructions}. -@item Dynamics -see @ruser{Dynamics}. -@end table -@end quotation + +Notation Reference: @ruser{Articulations and ornamentations}, +@ruser{Fingering instructions}, @ruser{Dynamics}. + + +@node Adding text +@subsection Adding text + +Text may be added to your scores: + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +c1^"espr" a_"legato" +@end lilypond + +Extra formatting may be added with the @code{\markup} command: + +@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 + + +@seealso + +Notation Reference: @ruser{Writing text}. @node Automatic and manual beams @subsection Automatic and manual beams +Music Glossary: @rglos{beam}. + @cindex beams, by hand -All @rglos{beam}s are drawn automatically: +All @notation{beams} are drawn automatically: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8 ais d ees r d c16 b a8 @@ -785,33 +854,29 @@ a8 ais d ees r d c16 b a8 @noindent If you do not like the automatic beams, they may be overridden -manually. Mark the first note to be beamed with @samp{[} and the -last one with @samp{]}. +manually. Mark the first note to be beamed with @code{[} and the +last one with @code{]}. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8[ ais] d[ ees r d] a b @end lilypond @seealso -@quotation -@table @asis -@item Automatic beams -see @ruser{Automatic beams}. -@item Manual beams -see @ruser{Manual beams}. -@end table -@end quotation + +Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}. @node Advanced rhythmic commands @subsection Advanced rhythmic commands @cindex pickup -@cindex anacruse +@cindex anacrusis @cindex partial measure @subheading Partial measure -A pickup (or @rglos{anacrusis}) is entered with the keyword +Music Glossary: @rglos{anacrusis}. + +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. @@ -824,11 +889,13 @@ f8 c2 d @cindex triplets @subheading Tuplets -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 +Music Glossary: @rglos{note value}, @rglos{triplet}. + +@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 } @@ -842,9 +909,12 @@ fraction @cindex appoggiatura @subheading Grace notes -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} +Music Glossary: @rglos{grace notes}, @rglos{acciaccatura}, +@rglos{appoggiatura}. + +@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}: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2 \grace { a32[ b] } c2 @@ -853,16 +923,9 @@ c2 \acciaccatura b16 c2 @end lilypond @seealso -@quotation -@table @asis -@item Grace notes -see @ruser{Grace notes}, -@item Tuplets -see @ruser{Tuplets}, -@item Pickups -see @ruser{Partial measures}. -@end table -@end quotation + +Notation Reference: @ruser{Grace notes}, @ruser{Tuplets}, +@ruser{Upbeats}. @node Multiple notes at once @@ -879,7 +942,7 @@ than one voice on the same staff. @menu * Music expressions explained:: * Multiple staves:: -* Piano staves:: +* Staff groups:: * Combining notes into chords:: * Single staff polyphony:: @end menu @@ -889,15 +952,15 @@ than one voice on the same staff. @subsection Music expressions explained In LilyPond input files, music is represented by @emph{music -expressions}. A single note is a music expression, although it is -not valid input all on its own. +expressions}. A single note is a music expression: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] a4 @end lilypond -Enclosing a group of notes in braces creates a new music -expression: +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 } @@ -911,12 +974,42 @@ one). The result is another music expression: { { a4 g } f g } @end lilypond +@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 they can contain other expressions, so you can +make arbitrarily complex and large expressions. For example, + +@example +1 + +1 + 2 + +(1 + 2) * 3 + +((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. + + @subheading Simultaneous music expressions: multiple staves -This technique is useful for 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 +Music Glossary: @rglos{polyphony}. + +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 @@ -937,17 +1030,18 @@ 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. -@strong{Warning}: each note is relative to the previous note in +@c FIXME: number of backslashes?! works in html but not pdf. +@warning{each note is relative to the previous note in the input, not relative to the @code{c''} in the initial -@code{\relative} command. +@code{\\relative} command.} @subheading Simultaneous music expressions: single staff 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. +the beginning of the first expression. If 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'' { @@ -956,42 +1050,14 @@ staff. } @end lilypond -@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 -1 - -1 + 2 - -(1 + 2) * 3 - -((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 @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. - - @node Multiple staves @subsection Multiple staves -As we saw in @ruser{Music expressions explained}, LilyPond input -files are constructed out of music expressions. 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. +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. 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 @@ -1022,16 +1088,17 @@ 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. -Time signatures entered in one staff affects all other -staves@footnote{This behavior may be changed if desired; see -@ruser{Polymetric notation}, for details.}. On the other hand, the -key signature of one staff does @emph{not} affect other staves. +Time signatures entered in one staff affects all other staves by +default. On the other hand, the key signature of one staff does +@emph{not} affect other staves. This different default behaviour +is because scores with transposing instruments are more common +than polyrhythmic scores. @lilypond[verbatim,quote,ragged-right] \relative c'' { << - \new Staff { \clef treble \time 3/4 c } - \new Staff { \clef bass \key d \major c,, } + \new Staff { \clef treble \key d \major \time 3/4 c } + \new Staff { \clef bass c,, } >> } @end lilypond @@ -1039,14 +1106,19 @@ key signature of one staff does @emph{not} affect other staves. -@node Piano staves -@subsection Piano staves +@node Staff groups +@subsection Staff groups -@cindex staff switch, manual -@cindex cross staff voice, manual -Piano music is typeset in two staves connected by a brace. +@cindex piano staff +@cindex choir staff +@cindex grand staff + +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 -@ruser{Multiple staves}, but now this entire expression is +@ref{Multiple staves}. However, now this entire expression is inserted inside a @code{PianoStaff}: @example @@ -1056,7 +1128,7 @@ inserted inside a @code{PianoStaff}: >> @end example -Here is a small example +Here is a small example: @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -1067,32 +1139,47 @@ Here is a small example } @end lilypond +Other staff groupings are introduced with +@code{\new GrandStaff,} suitable for orchestral +scores, and @code{\new ChoirStaff,} suitable for +vocal scores. These staff groups each form another +type of context, one that generates the brace at the +left end of every system and also controls the extent +of bar lines. + @seealso -@quotation -See @ruser{Piano music}. -@end quotation + +Notation Reference: @ruser{Piano music}, +@ruser{Displaying staves}. @node Combining notes into chords @subsection Combining notes into chords @cindex chords -Chords can be made by surrounding pitches with single angle -brackets. Angle brackets are the symbols @samp{<} and @samp{>}. -@lilypond[quote,fragment,verbatim,relative=2,fragment] +Music Glossary: @rglos{chord}. + +We saw earlier how notes can be combined into @notation{chords} by +indicating they are simultaneous by enclosing them in double angle +brackets. However, the normal way of indicating a chord is to +surround the pitches with @emph{single} angle brackets. Note that +all the notes in a chord must have the same duration, and that the +duration is placed after the closing bracket. + +@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 +Think of chords as almost equivalent to single notes: +almost everything you can attach to a single note can be attached +to a chord, and everything must go @emph{outside} the angle +brackets. For example, you can combine markings like beams and +ties with chords. They must be placed outside the angle brackets. -@lilypond[quote,fragment,verbatim,relative=2,fragment] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] r4 8[ ]~ 2 -@end lilypond - -@lilypond[quote,fragment,verbatim,relative=2,fragment] -r4 8\>( 4 \!) +r4 8( \> 4 \!) @end lilypond @@ -1121,8 +1208,8 @@ separating the voices with @code{\\} 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 (@samp{s}) instead of a normal -rest (@samp{r}), +same example with a spacer rest (@code{s}) instead of a normal +rest (@code{r}), @lilypond[verbatim,quote,ragged-right,fragment,relative=2] << @@ -1134,7 +1221,7 @@ rest (@samp{r}), @noindent 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 } \\ @@ -1149,9 +1236,8 @@ Again, these expressions can be nested arbitrarily. @end lilypond @seealso -@quotation -See @ruser{Basic polyphony}. -@end quotation + +Notation Reference: @ruser{Simultaneous notes}. @node Songs @@ -1160,130 +1246,242 @@ See @ruser{Basic polyphony}. This section introduces vocal music and simple song sheets. @menu -* Printing lyrics:: -* A lead sheet:: +* Setting simple songs:: +* Aligning lyrics to a melody:: +* Lyrics to multiple staves:: @end menu -@node Printing lyrics -@subsection Printing lyrics +@node Setting simple songs +@subsection Setting simple songs -@cindex Lyrics -@cindex Songs -Consider a simple melody: +@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'' { - a4 e c8 e r4 - b2 c4( d) + \key g \major + \time 6/8 + d4 b8 c4 a8 d4 b8 g4 } @end lilypond -The lyrics can be set to these notes, combining both with the -@code{\addlyrics} keyword. Lyrics are entered by separating each -syllable with a space. +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'' { - a4 e c8 e r4 - b2 c4( d) + \key g \major + \time 6/8 + d4 b8 c4 a8 d4 b8 g4 + } + \addlyrics { + Girls and boys come out to play, } - \addlyrics { One day this shall be free } >> @end lilypond +Note the curly brackets delimiting both the music and the lyrics, +and the double 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 + +Music Glossary: @rglos{melisma}, @rglos{extender line}. + @cindex melisma @cindex extender line -This melody ends on a @rglos{melisma}, a single syllable -(@q{free}) sung to more than one note. This is indicated with an -@emph{extender line}. It is entered as two underscores @code{__}: +@cindex hyphens +@cindex underscore + +The next line in the nursery rhyme is @q{The moon doth shine as +bright as day}. Let's extend it: @lilypond[verbatim,quote,ragged-right] << \relative c'' { - a4 e c8 e r4 - b2 c4( d) + \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; } - \addlyrics { One day this shall be free __ } >> @end lilypond -Similarly, hyphens between words can be entered as two dashes, -resulting in a centered hyphen between two syllables +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}): -@c no ragged-right here because otherwise the hypens get lost. -@lilypond[quote,verbatim] +@lilypond[verbatim,quote,ragged-right] << - \relative c' { - \time 2/4 - f4 f c c + \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 { A -- le -- gri -- a } ->> + \addlyrics { + Girls and boys come out to play, + The moon doth shine as bright as day; + } +>> @end lilypond -@seealso -@quotation -More options, such as putting multiple stanzas below a melody, are -discussed in @ruser{Vocal music}. -@end quotation - +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}). -@node A lead sheet -@subsection A lead sheet - -@cindex Lead sheets -@cindex chords -@cindex chord names - -In popular music it is common to denote accompaniment with chord -names. Such chords can be entered like notes, +As an alternative to using slurs, the melismata may be indicated +in just the lyrics by using an underscore, @code{_}, for each +note that should be included in the melisma: @lilypond[verbatim,quote,ragged-right] -\chordmode { c2 f4. g8 } +<< + \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 -Now each pitch is read as the root of a chord instead of a note. -This mode is switched on with @code{\chordmode}. Other chords can -be created by adding modifiers after a colon. The following -example shows a few common modifiers: +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: @lilypond[verbatim,quote,ragged-right] -\chordmode { c2 f4:m g4:maj7 gis1:dim7 } +<< + \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 -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: +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. -@lilypond[verbatim,quote,ragged-right] -\chords { c2 f4.:m g4.:maj7 gis8:dim7 } +@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 -@cindex lead sheet -When put together, chord names, lyrics and a melody form a lead -sheet, +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] << - \chords { c2 g:sus4 f e } + { + \time 6/8 + \partial 8 + } \relative c'' { - a4 e c8 e r4 - b2 c4( d) + \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, } - \addlyrics { One day this shall be free __ } >> @end lilypond +@noindent +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 in @ref{Organizing pieces with variables}. @seealso -@quotation -A complete list of modifiers and other options for layout can be -found in @ruser{Chords}. -@end quotation + +Notation Reference: @ruser{Vocal music}. + @node Final touches @@ -1294,15 +1492,91 @@ add the final touches to simple pieces, and provides an introduction to the rest of the manual. @menu +* Organizing pieces with variables:: * Version number:: * Adding titles:: * Absolute note names:: -* Organizing pieces with identifiers:: * After the tutorial:: -* How to read the manual:: @end menu +@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). + +@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 +The name of a variable must have alphabetic characters only, no +numbers, underscores, or dashes. + +Variables must be defined @emph{before} the main music +expression, but may be used as many times as required anywhere after +they have been defined. They may even be used in a later definition +of another variable, giving a way of shortening the input if a +section of music is repeated many times. + +@lilypond[verbatim,quote,ragged-right] +tripletA = \times 2/3 { c,8 e g } +barA = { \tripletA \tripletA \tripletA \tripletA } + +\relative c'' { + \barA \barA +} +@end lilypond + +Variables may be used for many other types of objects in +the input. For example, + +@example +width = 4.5\cm +name = "Wendy" +aFivePaper = \paper @{ paperheight = 21.0 \cm @} +@end example + +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 Version number @subsection Version number @@ -1311,17 +1585,17 @@ The @code{\version} statement records the version of LilyPond that was used to write the file: @example -\version "2.11.23" +\version "2.11.38" @end example @noindent -by convention, this is placed at the top of your LilyPond 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} (see @rprogram{Updating files with -convert-ly}), and it uses @code{\version} to determine what rules -to apply. +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 @@ -1330,10 +1604,10 @@ to apply. 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 @ruser{Version number}. +underneath the @ref{Version number}. @example -\version "2.11.23" +\version "2.11.38" \header @{ title = "Symphony" composer = "Me" @@ -1363,7 +1637,7 @@ absolute values. A @code{c'} will always mean middle C, a @code{g,} will always mean the note on the bottom staff of the bass clef. -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] { \clef bass c' b g, g, @@ -1373,7 +1647,7 @@ bass clef. Here is a four-octave scale: -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] { \clef bass c, d, e, f, @@ -1391,7 +1665,7 @@ Here is a four-octave scale: As you can see, writing a melody in the treble clef involves a lot of quote @code{'} marks. Consider this fragment from Mozart: -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] { \key a \major \time 6/8 @@ -1400,11 +1674,11 @@ of quote @code{'} marks. Consider this fragment from Mozart: } @end lilypond -All these quotes makes the input less readable and it is a source +All these quotes makes the input less readable and they are a source of errors. With @code{\relative}, the previous example is much -easier to read: +easier to read and type: -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] \relative c'' { \key a \major \time 6/8 @@ -1424,80 +1698,20 @@ intervals, and is extremely useful for computer-generated LilyPond files. -@node Organizing pieces with identifiers -@subsection Organizing pieces with identifiers - -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{identifiers}. - -With identifiers (also known as variables or macros), we can break -up complex music expressions. An identifier 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). -Identifiers must be defined @emph{before} the main music -expression. - -@lilypond[quote,verbatim,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 -The name of an identifier must have alphabetic characters only: no -numbers, underscores, or dashes. - -It is possible to use variables for many other types of objects in -the input. For example, - -@example -width = 4.5\cm -name = "Wendy" -aFivePaper = \paper @{ paperheight = 21.0 \cm @} -@end example - -Depending on its contents, the identifier 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 @subsection After the tutorial +FIXME: rewrite slightly after the rest of the LM has been +stabilized. Translators, ignore this section for now. + After finishing the tutorial, you should probably try writing a -piece or two. Start with one of the @ruser{Templates}, and add -notes. If you need any notation that was not covered in the -tutorial, look at the Notation Reference, starting with -@ruser{Basic notation}. If you want to write for an instrument +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 +@ruser{Musical notation}. If you want to write for an instrument ensemble that is not covered in the templates, take a look at -@ruser{Extending the templates}. +@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 @@ -1507,28 +1721,5 @@ 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 -As we saw in @ruser{How to read the tutorial}, many examples in -the tutorial omitted a @code{\relative c'' @{ ... @}} around the -printed example. - -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 -@ruser{About this manual}.