X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=446ae6e672a1becbc3dc1794db764762b32fe1e4;hb=e0178d3266687ced7da5602419c10e8e11791f98;hp=c54307dba0434ce293428af498eadbf366741bf2;hpb=413c0559bfe38fc321ca40115d3ec6cb7872bd01;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index c54307dba0..446ae6e672 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,59 +8,54 @@ @end ignore @ignore -Tutorial guidelines: + +Tutorial Specification: + +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. + +@end ignore + +@ignore +Tutorial guidelines: (different from policy.txt!) - unless you have a really good reason, use either - @l ilypond[quote,ragged-right,verbatim] + @lilypond[verbatim,quote,ragged-right] or - @l ilypond[quote,ragged-right,verbatim,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 - correct Dutch naming, but let's not confuse people with this until - we get to the Basic notation chapter. -@end ignore +- 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. +- 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 -@ref{Cheat sheet}, which is a table listing of the most common -commands for quick reference. -@end ifhtml +language and how to produce printed music. After this first +contact we will explain how to create common musical notation. @menu * First steps:: @@ -87,9 +82,9 @@ This section gives a basic introduction to working with LilyPond. @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 +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 @{ @@ -98,7 +93,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] @@ -107,148 +102,152 @@ 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 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! +@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 @strong{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. -@sp 1 +@smallspace @subheading Entering music and viewing output -In this section we will explain what commands to run -and how to view or print the output. +@cindex PDF file +@cindex viewing music -@subsubheading MacOS X +In this section we will explain what commands to run and how to +view or print the output. -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 > Typeset File}. -The resulting PDF file will be displayed on your screen. +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 -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. +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. 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. +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 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 +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. +is to drag and drop it onto the LilyPond icon using your mouse +pointer. -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. +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. -Note that there are several other text editors available, with better -support for LilyPond, see @ref{Editor support}, for more information. +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. @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 -@ref{Editor support}, for more information.}. In your -text editor, enter the following input and save the file as -@file{test.ly} - -@verbatim -{ +Create a file (such as @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 -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. +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. -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] { c' e' g' e' } @end lilypond @noindent -This behavior may be altered, but in most cases these automatic values -are useful. +This behavior may be altered, but in most cases these automatic +values are useful. @subheading Pitches -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}. +Music glossary: @rglos{pitch}, @rglos{interval}, +@rglos{scale}, @rglos{middle C}, @rglos{octave}, +@rglos{accidental}. -@lilypond[quote,ragged-right,verbatim] -\relative c' { +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[verbatim,quote,ragged-right] +\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 closest -D to the previous note. We can create melodies which have larger intervals: +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: -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c' { d f a g c b f d @@ -256,14 +255,52 @@ D to the previous note. We can create melodies which have 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 F 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 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 -@lilypond[quote,ragged-right,verbatim] +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. + +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' @@ -271,20 +308,24 @@ lower the octave by adding a comma @code{,} to the note name. @end lilypond @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. +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. @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. -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { a1 a2 a4 a8 a @@ -294,11 +335,13 @@ automatically. @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. +for the next note. The duration of the first note defaults to a +quarter. -To create @rglos{dotted notes}, add a dot @samp{.} to the duration number. +To create @notation{dotted notes}, add a dot @code{.} to the duration +number. -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { a a a4. a8 a8. a16 a a8. a8 a4. @@ -308,9 +351,11 @@ To create @rglos{dotted notes}, add a dot @samp{.} to the duration number. @subheading Rests -A @rglos{rest} is entered just like a note with the name @samp{r}: +Music glossary: @rglos{rest}. -@lilypond[quote,ragged-right,verbatim] +A @notation{rest} is entered just like a note with the name @code{r}: + +@lilypond[verbatim,quote,ragged-right] \relative c'' { a r r2 r8 a r4 r4. r8 @@ -320,9 +365,12 @@ 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} command: +Music glossary: @rglos{time signature}. + +The @notation{time signature} can be set with the @code{\time} +command: -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { \time 3/4 a4 a a @@ -336,9 +384,11 @@ The @rglos{time signature}) can be set with the @code{\time} command: @subheading Clef -The @rglos{clef} can be set using the @code{\clef} command: +Music glossary: @rglos{clef}. -@lilypond[quote,ragged-right,verbatim] +The @notation{clef} can be set using the @code{\clef} command: + +@lilypond[verbatim,quote,ragged-right] \relative c' { \clef treble c1 @@ -356,7 +406,7 @@ The @rglos{clef} can be set using the @code{\clef} command: Here is a small example showing all these elements together: -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c, { \time 3/4 \clef bass @@ -365,93 +415,94 @@ Here is a small example showing all these elements together: } @end lilypond -@moreinfo -@quotation -@table @asis -@item Entering pitches and durations -see @ref{Pitches}, and @ref{Durations}. -@item Rests -see @ref{Rests}. -@item Time signatures and other timing commands -see @ref{Time signature}. -@item Clefs -see @ref{Clef}. -@end table -@end quotation +@seealso + +Notation Reference: @ruser{Writing pitches}, @ruser{Writing rhythms}, +@ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}. + + +@c HERE's where I started @node Working on text files @subsection Working on text files -LilyPond input files are treated like files in most programming languages: -they are case sensitive, white-space insensitive, expressions are -formed with curly braces @{ @}, and comments are denoted with @code{%} or -@code{%@{ ... %@}}. +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 sentence sounds like nonsense, don't worry! We'll explain -what all these terms mean: +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 lower case: @code{@{ c d e @}} -is valid input; @code{@{ C D E @}} will produce an error message. - -@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 +@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}: +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 @} +@{ c d + e @} @end example @noindent -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: +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: + @example @{ c d e @} @end example -@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 space unless they are at the beginning or end of a -line to avoid ambiguities. +@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. +A function (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 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. The following fragment shows possible uses for comments +@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: @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 @@ -464,15 +515,12 @@ There are more tips for constructing input files in @node How to read the tutorial @subsection How to read the tutorial -As we saw in @ref{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. - -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'' @{ @@ -480,13 +528,36 @@ copy and paste the displayed input, but you @strong{must} add the @} @end example -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 documentation example and paste it inside a longer piece -of your own. +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. + + +@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. @node Single staff notation @@ -496,132 +567,108 @@ 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 @ref{Simple notation}, LilyPond calculates the pitch of -each note relative to the previous one@footnote{There is another mode of -entering pitches, @ref{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[quote,ragged-right,verbatim,fragment,relative=2] -c2 fis -c2 ges -@end lilypond - -@moreinfo -@quotation -@table @asis -@item Relative octaves -see @ref{Relative octaves}. -@item Octave check -see @ref{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 -@ref{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 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,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] cis1 ees fisis, aeses @end lilypond @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}. -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +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 a1 \key c \minor 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 effects -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. - -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. +Music glossary: @rglos{accidental}, @rglos{key signature}, +@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp}, +@rglos{transposition}. -In this example +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[quote,ragged-right,verbatim,fragment,relative=2] +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 @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 the +@code{is} to @code{cis} and @code{fis}. -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 note with -pitch E-natural.} In the key of A-flat major, it @emph{does} get an -accidental: +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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] \key aes \major 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 -@ref{Automatic accidentals}, for some examples how accidentals can be printed -according to different rules. +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}. + +@seealso + +Notation Reference: @ruser{Accidentals}, +@ruser{Automatic accidentals}, @ruser{Key signature}. -@moreinfo -@quotation -@table @asis -@item Accidentals -see @ref{Accidentals}, and @ref{Automatic accidentals}. -@item Key signature -see @ref{Key signature}. -@end table -@end quotation +Music glossary: @rglos{Pitch names}. @node Ties and slurs @@ -629,10 +676,13 @@ see @ref{Key signature}. @cindex ties @subheading Ties -A @rglos{tie} is created by appending a tilde @samp{~} to the first -note being tied -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +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~ c4 ~ c8 a8 ~ a2 @end lilypond @@ -640,10 +690,13 @@ 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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] d4( c16) cis( d e c cis d) e( d4) @end lilypond @@ -651,42 +704,38 @@ d4( c16) cis( d e c cis d) e( d4) @cindex phrasing slurs @subheading Phrasing slurs -@cindex 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{phrasing}, @rglos{legato}. + +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. -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +@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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2~( c8 fis fis4 ~ fis2 g2) @end lilypond -@moreinfo -@quotation -@table @asis -@item Ties -see @ref{Ties}. -@item Slurs -see @ref{Slurs}. -@item Phrasing slurs -see @ref{Phrasing slurs}. -@end table -@end quotation +@seealso + +Notation Reference: @ruser{Ties}, @ruser{Slurs}, +@ruser{Phrasing slurs}. @node Articulation and dynamics @@ -697,36 +746,46 @@ see @ref{Phrasing slurs}. @cindex staccato @subheading Articulations -Common @rglos{articulations} 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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c-. c-- c-> c-^ c-+ c-_ @end lilypond @cindex fingering @subheading Fingerings -Similarly, fingering indications can be added to a note using a dash -(@samp{-}) and the digit to be printed: -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +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. +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[quote,ragged-right,verbatim,fragment,relative=2] +@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 -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +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 @end lilypond @@ -734,70 +793,88 @@ 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{\>}. An ending dynamic, for +example @code{\f}, will finish the (de)crescendo, or the command +@code{\!} can be used: -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2\< c2\ff\> c2 c2\! @end lilypond -@moreinfo -@quotation -@table @asis -@item Articulations -see @ref{Articulations}. -@item Fingering -see @ref{Fingering instructions}. -@item Dynamics -see @ref{Dynamics}. -@end table -@end quotation +@seealso + +Notation Reference: @ruser{Articulations}, +@ruser{Fingering instructions}, @ruser{Dynamics}. + +Music glossary: @rglos{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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8 ais d ees r d c16 b a8 @end lilypond @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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8[ ais] d[ ees r d] a b @end lilypond -@moreinfo -@quotation -@table @asis -@item Automatic beams -see @ref{Automatic beams}. -@item Manual beams -see @ref{Manual beams}. -@end table -@end quotation +@seealso + +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 -@code{\partial}. It is followed by a duration: @code{\partial 4} is -a quarter note pickup and @code{\partial 8} an eighth note. +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. -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] \partial 8 f8 c2 d @end lilypond @@ -806,12 +883,15 @@ 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}. -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +@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] } @@ -823,46 +903,41 @@ of music is multiplied by the fraction. Triplets make notes occupy @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{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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2 \grace { a32[ b] } c2 c2 \appoggiatura b16 c2 c2 \acciaccatura b16 c2 @end lilypond -@moreinfo -@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 Multiple notes at once @section Multiple notes at once -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 section introduces having more than one note at the same +time: multiple instruments, multiple staves for a single +instrument (i.e. piano), and chords. -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. +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. @menu * Music expressions explained:: * Multiple staves:: * Piano staves:: -* Single staff polyphony:: * Combining notes into chords:: +* Single staff polyphony:: @end menu @@ -870,38 +945,42 @@ 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[quote,ragged-right,verbatim,fragment,relative=2] +@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[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] { a4 g4 } @end lilypond -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: +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: -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] { { a4 g } f g } @end lilypond @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 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: +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 +notes) are combined simultaneously: -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { << { a4 g } @@ -911,23 +990,24 @@ containing two separate notes) are combined simultaneously: } @end lilypond -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. +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. -@strong{Warning}: each note is relative to the -previous note in the input, not relative to the @code{c''} in the -initial @code{\relative} command. +@warning{each note is relative to the previous note in +the input, not relative to the @code{c''} in the initial +@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. +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[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { c2 <> << { e f } { c <> } >> @@ -938,10 +1018,10 @@ simultaneous expression, there is more than one staff. @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, +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 @@ -953,28 +1033,30 @@ you can make arbitrarily complex and large expressions. For example, ((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. +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 Multiple staves @subsection Multiple staves -As we saw in @ref{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 -@code{Staff} elements are then combined in parallel with @code{<<} and -@code{>>}: +@code{Staff} elements are then combined in parallel with @code{<<} +and @code{>>}: -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { << \new Staff { \clef treble c } @@ -983,27 +1065,28 @@ staff is marked by adding @code{\new Staff} before it. These } @end lilypond -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. +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. 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. +and @code{Voice} handle melodic notation, while @code{Lyrics} sets +lyric texts and @code{ChordNames} prints chord names. 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. +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, but +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@footnote{This behavior may be changed if desired; see -@ref{Changing defaults}, for details.}. +staves. -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { << \new Staff { \clef treble \time 3/4 c } @@ -1020,9 +1103,14 @@ staves@footnote{This behavior may be changed if desired; see @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{Multiple staves}, -but now this entire expression is inserted inside a @code{PianoStaff}: + +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 \new PianoStaff << @@ -1031,9 +1119,9 @@ but now this entire expression is inserted inside a @code{PianoStaff}: >> @end example -Here is a small example +Here is a small example: -@lilypond[quote,ragged-right,verbatim] +@lilypond[verbatim,quote,ragged-right] \relative c'' { \new PianoStaff << \new Staff { \time 2/4 c4 e g g, } @@ -1042,10 +1130,36 @@ Here is a small example } @end lilypond -@moreinfo -@quotation -See @ref{Piano music}. -@end quotation +@seealso + +Notation Reference: @ruser{Piano music}. + + +@node Combining notes into chords +@subsection Combining notes into chords + +@cindex chords + +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 + +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] +r4 8\>( 4 \!) +@end lilypond @node Single staff polyphony @@ -1054,28 +1168,29 @@ See @ref{Piano music}. @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. +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{\\} +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,ragged-right,verbatim,fragment,relative=2] +@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 (@samp{s}) instead of a normal rest (@samp{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,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,ragged-right,fragment,relative=2] << { a4 g2 f4~ f4 } \\ { s4 g4 f2 f4 } @@ -1085,7 +1200,7 @@ spacer rest (@samp{s}) instead of a normal 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 } \\ @@ -1099,33 +1214,9 @@ Again, these expressions can be nested arbitrarily. >> @end lilypond -@moreinfo -@quotation -See @ref{Basic polyphony}. -@end quotation - +@seealso -@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] -r4 4 2 -@end lilypond - -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] -r4 8[ ]~ 2 -@end lilypond - -@lilypond[quote,fragment,verbatim,relative=2,fragment] -r4 8\>( 4 \!) -@end lilypond +Notation Reference: @ruser{Simultaneous notes}. @node Songs @@ -1134,144 +1225,234 @@ r4 8\>( 4 \!) 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 + +Music glossary: @rglos{lyrics}. -@cindex Lyrics -@cindex Songs -Consider a simple melody: +Here is the start of the melody to a nursery +rhyme, @qq{Girls and boys come out to play}: -@lilypond[quote,ragged-right,verbatim] +@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[quote,ragged-right,verbatim] +@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 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[quote,ragged-right,verbatim] +@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 -@moreinfo -@quotation -More options, such as putting multiple stanzas below a melody, are -discussed in @ref{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}). +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: -@node A lead sheet -@subsection A lead sheet +@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 -@cindex Lead sheets -@cindex chords -@cindex chord names +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. -In popular music it is common to denote accompaniment with chord names. -Such chords can be entered like notes, +@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 -@lilypond[quote,ragged-right,verbatim] -\chordmode { c2 f4. g8 } +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 -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: -@lilypond[quote,verbatim,ragged-right] -\chordmode { c2 f4:m g4:maj7 gis1:dim7 } -@end lilypond +@seealso -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: +Notation Reference: @ruser{Vocal music}. -@lilypond[quote,verbatim,ragged-right] -\chords { c2 f4.:m g4.:maj7 gis8:dim7 } -@end lilypond -@cindex lead sheet -When put together, chord names, lyrics and a melody form -a lead sheet, +@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[quote,verbatim,ragged-right] +@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 +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 -@moreinfo -@quotation -A complete list of modifiers and other options for layout can be found -in @ref{Chords}. -@end quotation +Notation Reference: @ruser{Vocal music}. @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. +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 identifiers:: +* Organizing pieces with variables:: * After the tutorial:: * How to read the manual:: @end menu @@ -1281,32 +1462,33 @@ of the manual. @subsection Version number @cindex versioning -The @code{\version} statement marks for which version of LilyPond the file -was written. To mark a file for version 2.10.1, place +The @code{\version} statement records the version of LilyPond that +was used to write the file: @example -\version "2.11.15" +\version "2.11.23" @end example @noindent -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 @ref{Updating files with convert-ly}), and it uses -@code{\version} to determine what rules to apply. +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}. +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 -\version "2.11.15" +\version "2.11.23" \header @{ title = "Symphony" composer = "Me" @@ -1318,24 +1500,25 @@ the @ref{Version number}. @} @end example -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}. +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}. @node Absolute note names @subsection Absolute note names -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. +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. +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[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] { \clef bass c' b g, g, @@ -1345,7 +1528,7 @@ always mean the note on the bottom staff of the bass clef. Here is a four-octave scale: -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] { \clef bass c, d, e, f, @@ -1360,10 +1543,10 @@ Here is a four-octave scale: } @end lilypond -As you can see, writing a melody in the treble clef involves a lot of -quote ' marks. Consider this fragment from Mozart: +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 @@ -1372,11 +1555,11 @@ quote ' marks. Consider this fragment from Mozart: } @end lilypond -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: +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,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] \relative c'' { \key a \major \time 6/8 @@ -1385,25 +1568,29 @@ to read: } @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. +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. -However, absolute mode is useful for music which has large intervals, and -is extremely useful for computer-generated LilyPond files. +However, absolute mode is useful for music which has large +intervals, and is extremely useful for computer-generated LilyPond +files. -@node Organizing pieces with identifiers -@subsection Organizing pieces with identifiers +@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{identifiers}. +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 identifiers (also known as variables or macros), we can break up -complex music expressions. An identifier is assigned as follows +With variables (also known as identifiers or macros), we can break +up complex music expressions. A variable is assigned as +follows: @example namedMusic = @{ @dots{} @} @@ -1411,10 +1598,11 @@ namedMusic = @{ @dots{} @} 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. +(@code{\namedMusic}, just like a normal LilyPond command). +Variables must be defined @emph{before} the main music +expression. -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote,ragged-right] violin = \new Staff { \relative c'' { a4 b c b }} @@ -1431,11 +1619,11 @@ cello = \new Staff { \relative c { @end lilypond @noindent -The name of an identifier must have alphabetic characters only: no +The name of a variable 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, +It is possible to use variables for many other types of objects in +the input. For example, @example width = 4.5\cm @@ -1443,7 +1631,7 @@ name = "Wendy" aFivePaper = \paper @{ paperheight = 21.0 \cm @} @end example -Depending on its contents, the identifier can be used in different +Depending on its contents, the variable can be used in different places. The following example uses the above variables: @example @@ -1459,39 +1647,43 @@ places. The following example uses the above variables: @subsection After the tutorial After finishing the tutorial, you should probably try writing a -piece or two. Start with one of the @ref{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 templates, -take a look at @ref{Extending the templates}. +@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 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. +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 -As we saw in @ref{How to read the tutorial}, many examples in the -tutorial omitted a @code{\relative c'' @{ ... @}} around the printed -example. +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 in 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{@{ @}}. +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. +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}.