Standardize on "Notation Reference: "

[lilypond.git] / Documentation / user / tutorial.itely

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 6dd6725a12ed7a8beecafd59cb5b4b372e354904..446ae6e672a1becbc3dc1794db764762b32fe1e4 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -7,20 +7,46 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@ignore
+
+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
 @ignore
 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
   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.
   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.
   correct Dutch naming, but let's not confuse people with this
   until we get to the Basic notation chapter.

-- Add "Music glossary: @r gloss{foo}" to the _top_ of the relevant
+
+- Add "Music glossary: @rglos{foo}" to the _top_ of the relevant

   portions of the tutorial.
   portions of the tutorial.

+

 @end ignore
 
 
 @end ignore
 
 


@@ -58,7 +84,7 @@ This section gives a basic introduction to working with LilyPond.
 
 The first example demonstrates how to start working with LilyPond.
 To create sheet music, we write a text file that specifies the
 
 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
+notation.  For example, if we write:

 
 @example
 @{
 
 @example
 @{


@@ -67,7 +93,7 @@ notation.  For example, if we write
 @end example
 
 @noindent
 @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]
 
 @c  in this case we don't want verbatim
 @lilypond[quote,ragged-right]


@@ -84,7 +110,7 @@ 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}.}
 
 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
+@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.
 In addition, LilyPond input is @strong{case sensitive}.  @code{
 @{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
 error message.


@@ -94,7 +120,7 @@ error message.
 @subheading Entering music and viewing output
 
 @cindex PDF file
 @subheading Entering music and viewing output
 
 @cindex PDF file

-@cindex Viewing music
+@cindex viewing music

 
 In this section we will explain what commands to run and how to
 view or print the output.
 
 In this section we will explain what commands to run and how to
 view or print the output.


@@ -111,7 +137,7 @@ first.  After this, LilyPond will be much faster!}
 
 If you double click @code{LilyPond.app}, it will open with an
 example file.  Save it, for example, to @file{test.ly} on your
 
 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.
 
 Typeset File}.  The resulting PDF file will be displayed on your
 screen.
 


@@ -119,6 +145,7 @@ 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
 @subsubheading Windows
 
 On Windows, if you double-click in the LilyPond icon on the


@@ -151,23 +178,25 @@ Create a file (such as @file{test.ly}) and enter:
 @}
 @end example
 
 @}
 @end example
 

-To process @file{test.ly}, proceed as follows
+To process @file{test.ly}, proceed as follows:

 
 @example
 lilypond test.ly
 @end example
 
 @noindent
 
 @example
 lilypond test.ly
 @end example
 
 @noindent

-You will see something resembling
+You will see something resembling:

 
 @example
 lilypond test.ly
 
 @example
 lilypond test.ly

-GNU LilyPond 2.10.0
+GNU LilyPond 2.12.0

 Processing `test.ly'
 Parsing...
 Processing `test.ly'
 Parsing...

-Interpreting music... [1]
+Interpreting music...

 Preprocessing graphical objects...
 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
 Layout output to `test.ps'...
 Converting to `test.pdf'...
 @end example


@@ -193,27 +222,30 @@ values are useful.
 
 @subheading Pitches
 
 
 @subheading Pitches
 

-Music glossary: @rglos{interval}, @rglos{fourth}, @rglos{scale},
-@rglos{middle C}
+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.
 
 The easiest way to enter notes is by using @code{\relative} mode.

-In this mode, the @notation{interval} between the previous note and
-the current note is assumed to be within a @notation{fourth}.  We
-begin by entering the most elementary piece of music, a
-@notation{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]
 
 @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 @notation{middle C}.  Each successive note is
   c d e f
   g a b c
 }
 @end lilypond
 
 The initial note is @notation{middle C}.  Each successive note is

-within a fourth of the previous note -- in other words, the first
+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
 @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:
+closest D to the previous note.  We can create melodies which
+have larger intervals:

 
 @lilypond[verbatim,quote,ragged-right]
 \relative c' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c' {


@@ -223,13 +255,50 @@ larger intervals:
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-As you may notice, this example does not start on middle C.  The
-first note -- the @code{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

 
 

-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.
+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.
+
+@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
+
+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'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -248,13 +317,13 @@ this.
 
 @subheading Durations (rhythms)
 
 
 @subheading Durations (rhythms)
 

-Music glossary: @rglos{duration}, @rglos{whole note},
+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
 @rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
 
 The @notation{duration} of a note is specified by a number after

-the note name.  @samp{1} for a @notation{whole note}, @samp{2} for
-a @notation{half note}, @samp{4} for a @notation{quarter note} and
-so on.  Beams are added automatically.
+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[verbatim,quote,ragged-right]
 \relative c'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -269,7 +338,7 @@ 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 @notation{dotted notes}, add a dot @samp{.} to the duration
+To create @notation{dotted notes}, add a dot @code{.} to the duration

 number.
 
 @lilypond[verbatim,quote,ragged-right]
 number.
 
 @lilypond[verbatim,quote,ragged-right]


@@ -284,7 +353,7 @@ number.
 
 Music glossary: @rglos{rest}.
 
 
 Music glossary: @rglos{rest}.
 

-A @notation{rest} is entered just like a note with the name @samp{r}:
+A @notation{rest} is entered just like a note with the name @code{r}:

 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -298,7 +367,7 @@ A @notation{rest} is entered just like a note with the name @samp{r}:
 
 Music glossary: @rglos{time signature}.
 
 
 Music glossary: @rglos{time signature}.
 

-The @notation{time signature}) can be set with the @code{\time}
+The @notation{time signature} can be set with the @code{\time}

 command:
 
 @lilypond[verbatim,quote,ragged-right]
 command:
 
 @lilypond[verbatim,quote,ragged-right]


@@ -349,11 +418,11 @@ Here is a small example showing all these elements together:
 
 @seealso
 
 
 @seealso
 

-User manual: @ruser{Writing pitches}, @ruser{Writing rhythms},
+Notation Reference: @ruser{Writing pitches}, @ruser{Writing rhythms},

 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
 
 
 @ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
 
 

-@c  KURTIS: update stuff below this line with the style above.
+@c HERE's where I started

 
 @node Working on text files
 @subsection Working on text files
 
 @node Working on text files
 @subsection Working on text files


@@ -364,22 +433,24 @@ is generally equivalent.  Expressions are formed with curly braces
 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
 %@}}.
 
 @{ @}, 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
 
 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.
 
 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{}
 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
+@tie{} @tie{} d e @}} and:

 
 @example
 @{ c                        d
 
 @example
 @{ c                        d


@@ -396,11 +467,12 @@ thumb is to indent code blocks with either a tab or two spaces:
 @}
 @end example
 
 @}
 @end example
 

-@item @strong{Expressions:}
+@item
+@strong{Expressions:}

 Every piece of LilyPond input needs to have @strong{@{ curly
 braces @}} placed around the input.  These braces tell LilyPond
 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.
 
 space unless they are at the beginning or end of a line to avoid
 ambiguities.
 


@@ -410,15 +482,16 @@ single music expression.
 @cindex comments
 @cindex line comment
 @cindex block comment
 @cindex comments
 @cindex line comment
 @cindex block comment

-@item @strong{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
 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
+@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
 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
+fragment shows possible uses for comments:

 
 @example
 % notes for twinkle twinkle follow
 
 @example
 % notes for twinkle twinkle follow


@@ -436,18 +509,18 @@ fragment shows possible uses for comments
 @end itemize
 
 There are more tips for constructing input files in
 @end itemize
 
 There are more tips for constructing input files in

-@ruser{Suggestions for writing LilyPond files}.
+@ref{Suggestions for writing LilyPond files}.

 
 
 @node How to read the tutorial
 @subsection How to read the tutorial
 
 
 
 @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.  To
-replicate the examples, you may 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'' @{
 
 @example
 \relative c'' @{


@@ -472,7 +545,7 @@ 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
 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
+this image:

 
 @c no verbatim here
 @lilypond[quote,ragged-right]
 
 @c no verbatim here
 @lilypond[quote,ragged-right]


@@ -494,59 +567,30 @@ This section introduces common notation that is used for one voice
 on one staff.
 
 @menu
 on one staff.
 
 @menu

-* Relative note names::         

 * Accidentals and key signatures::  
 * Ties and slurs::              
 * Articulation and dynamics::   
 * Accidentals and key signatures::  
 * Ties and slurs::              
 * Articulation and dynamics::   

+* Adding text::                 

 * Automatic and manual beams::  
 * Advanced rhythmic commands::  
 @end menu
 
 
 * 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, @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
 
 @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
+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
 naming conventions in Nordic and Germanic languages, like German

-and Dutch.  To use other names for accidentals, see @ruser{Note
-names in other languages}.}
+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
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 cis1 ees fisis, aeses


@@ -555,8 +599,10 @@ cis1 ees fisis, aeses
 @cindex key signature, setting
 @subheading Key signatures
 
 @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
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \key d \major


@@ -569,23 +615,27 @@ a
 
 @subheading Warning: key signatures and pitches
 
 
 @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}.
+
+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 makes a sharp distinction between musical content and
 
 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
+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.
 
 automatically, and you must enter what you want to hear.
 

-In this example
+In this example:

 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \key d \major
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \key d \major


@@ -594,10 +644,10 @@ d cis fis
 
 @noindent
 No note has a printed accidental, but you must still add the
 
 @noindent
 No note has a printed accidental, but you must still add the

-@samp{is} to @code{cis} and @code{fis}.
+@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
+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:
 
 note with pitch E-natural.}  In the key of A-flat major, it
 @emph{does} get an accidental:
 


@@ -607,20 +657,18 @@ e
 @end lilypond
 
 Adding all alterations explicitly might require a little more
 @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
 
 @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{Accidentals},
+@ruser{Automatic accidentals}, @ruser{Key signature}.
+
+Music glossary: @rglos{Pitch names}.

 
 
 @node Ties and slurs
 
 
 @node Ties and slurs


@@ -628,8 +676,11 @@ see @ruser{Key signature}.
 
 @cindex ties
 @subheading Ties
 
 @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~
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 g4~ g c2~


@@ -639,8 +690,10 @@ c4 ~ c8 a8 ~ a2
 @cindex slurs
 @subheading Slurs
 
 @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{)}
+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]
 respectively.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]


@@ -651,10 +704,12 @@ d4( c16) cis( d e c cis d) e( d4)
 @cindex phrasing slurs
 @subheading Phrasing slurs
 
 @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{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[verbatim,quote,ragged-right,fragment,relative=2]
 a8(\( ais b c) cis2 b'2 a4 cis,\)
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a8(\( ais b c) cis2 b'2 a4 cis,\)


@@ -665,27 +720,22 @@ a8(\( ais b c) cis2 b'2 a4 cis,\)
 @cindex slurs versus ties
 @subheading Warnings: slurs vs. ties
 
 @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
 
 @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
 
 
 @node Articulation and dynamics


@@ -696,8 +746,10 @@ see @ruser{Phrasing slurs}.
 @cindex staccato
 @subheading Articulations
 
 @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-_
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c-. c-- c-> c-^ c-+ c-_


@@ -705,15 +757,18 @@ c-. c-- c-> c-^ c-+ c-_
 
 @cindex fingering
 @subheading Fingerings
 
 @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
 
 @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{_}
+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.
 (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.


@@ -723,8 +778,12 @@ c_-^1 d^. f^4_2-> e^-_+
 @end lilypond
 
 @subheading Dynamics
 @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
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c\ff c\mf c\p c\pp


@@ -734,32 +793,54 @@ c\ff c\mf c\p c\pp
 @cindex decrescendo
 @cindex crescendo
 
 @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[verbatim,quote,ragged-right,fragment,relative=2]
 c2\< c2\ff\> c2 c2\!
 @end lilypond
 
 @seealso
 
 @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},
+@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
 
 
 
 @node Automatic and manual beams
 @subsection Automatic and manual beams
 

+Music glossary: @rglos{beam}.
+

 @cindex beams, by hand
 @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
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a8 ais d ees r d c16 b a8


@@ -767,33 +848,29 @@ a8 ais d ees r d c16 b a8
 
 @noindent
 If you do not like the automatic beams, they may be overridden
 
 @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
 
 @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
 
 
 @node Advanced rhythmic commands
 @subsection Advanced rhythmic commands
 
 @cindex pickup

-@cindex anacruse
+@cindex anacrusis

 @cindex partial measure
 @subheading Partial measure
 
 @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.
 
 @code{\partial}.  It is followed by a duration: @code{\partial 4}
 is a quarter note pickup and @code{\partial 8} an eighth note.
 


@@ -806,11 +883,13 @@ f8 c2 d
 @cindex triplets
 @subheading Tuplets
 
 @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 }
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \times 2/3 { f8 g a }


@@ -824,9 +903,11 @@ fraction
 @cindex appoggiatura
 @subheading Grace notes
 
 @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[verbatim,quote,ragged-right,fragment,relative=2]
 c2 \grace { a32[ b] } c2
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c2 \grace { a32[ b] } c2


@@ -835,16 +916,9 @@ c2 \acciaccatura b16 c2
 @end lilypond
 
 @seealso
 @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
 
 
 @node Multiple notes at once


@@ -895,10 +969,12 @@ one).  The result is another music expression:
 
 @subheading Simultaneous music expressions: multiple staves
 
 
 @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
 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


@@ -960,7 +1036,7 @@ arbitrarily complex and large expressions.  For 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
 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.
+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.
 Like mathematical expressions, music expressions can be nested
 arbitrarily deep, which is necessary for complex music like
 polyphonic scores.


@@ -969,11 +1045,11 @@ polyphonic scores.
 @node Multiple staves
 @subsection Multiple staves
 
 @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
 
 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


@@ -1005,9 +1081,10 @@ 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
 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.
+staves@footnote{This behavior may be changed if desired; for
+details, see @ruser{Polymetric notation}.}.  On the other hand,
+the key signature of one staff does @emph{not} affect other
+staves.

 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -1026,9 +1103,13 @@ key signature of one staff does @emph{not} affect other staves.
 
 @cindex staff switch, manual
 @cindex cross staff voice, manual
 
 @cindex staff switch, manual
 @cindex cross staff voice, manual

-Piano music is typeset in two staves connected by a brace.
+
+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
 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
 inserted inside a @code{PianoStaff}:
 
 @example


@@ -1038,7 +1119,7 @@ inserted inside a @code{PianoStaff}:
 >>
 @end example
 
 >>
 @end example
 

-Here is a small example
+Here is a small example:

 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -1050,30 +1131,33 @@ Here is a small example
 @end lilypond
 
 @seealso
 @end lilypond
 
 @seealso

-@quotation
-See @ruser{Piano music}.
-@end quotation
+
+Notation Reference: @ruser{Piano music}.

 
 
 @node Combining notes into chords
 @subsection Combining notes into chords
 
 @cindex chords
 
 
 @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}.
+
+@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 <c e g>4 <c f a>2
 @end lilypond
 
 You can combine markings like beams and ties with chords.  They
 r4 <c e g>4 <c f a>2
 @end lilypond
 
 You can combine markings like beams and ties with chords.  They

-must be placed outside the angle brackets
+must be placed outside the angle brackets.

 
 

-@lilypond[quote,fragment,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]

 r4 <c e g>8[ <c f a>]~ <c f a>2
 @end lilypond
 
 r4 <c e g>8[ <c f a>]~ <c f a>2
 @end lilypond
 

-@lilypond[quote,fragment,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]

 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
 @end lilypond
 
 r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
 @end lilypond
 


@@ -1103,8 +1187,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
 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]
 <<
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 <<


@@ -1116,7 +1200,7 @@ rest (@samp{r}),
 @noindent
 Again, these expressions can be nested arbitrarily.
 
 @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 } \\
 <<
   \new Staff <<
     { a4 g2 f4~ f4 } \\


@@ -1131,9 +1215,8 @@ Again, these expressions can be nested arbitrarily.
 @end lilypond
 
 @seealso
 @end lilypond
 
 @seealso

-@quotation
-See @ruser{Basic polyphony}.
-@end quotation
+
+Notation Reference: @ruser{Simultaneous notes}.

 
 
 @node Songs
 
 
 @node Songs


@@ -1151,33 +1234,36 @@ This section introduces vocal music and simple song sheets.
 @node Setting simple songs
 @subsection Setting simple songs
 
 @node Setting simple songs
 @subsection Setting simple songs
 

-@cindex Lyrics
-@cindex Songs
+@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]
 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'' {
+\relative c'' {

   \key g \major
   \time 6/8
   d4 b8 c4 a8 d4 b8 g4
   \key g \major
   \time 6/8
   d4 b8 c4 a8 d4 b8 g4

- }
+}

 @end lilypond
 
 @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]
 <<
 
 @lilypond[verbatim,quote,ragged-right]
 <<

- \relative c'' {
-  \key g \major
-  \time 6/8
-  d4 b8 c4 a8 d4 b8 g4
- }
- \addlyrics {
-  Girls and boys come out to play,
- }
+  \relative c'' {
+    \key g \major
+    \time 6/8
+    d4 b8 c4 a8 d4 b8 g4
+  }
+  \addlyrics {
+    Girls and boys come out to play,
+  }

 >>
 @end lilypond
 
 >>
 @end lilypond
 


@@ -1188,6 +1274,8 @@ show that the music and lyrics are to occur at the same time.
 @node Aligning lyrics to a melody
 @subsection Aligning lyrics to a melody
 
 @node Aligning lyrics to a melody
 @subsection Aligning lyrics to a melody
 

+Music glossary: @rglos{melisma}, @rglos{extender line}.
+

 @cindex melisma
 @cindex extender line
 @cindex hyphens
 @cindex melisma
 @cindex extender line
 @cindex hyphens


@@ -1198,38 +1286,38 @@ bright as day}.  Let's extend it:
 
 @lilypond[verbatim,quote,ragged-right]
 <<
 
 @lilypond[verbatim,quote,ragged-right]
 <<

- \relative c'' {
-  \key g \major
-  \time 6/8
-  d4 b8 c4 a8 d4 b8 g4 
-  g8 a4 b8 c b a d4 b8 g4.
- }
- \addlyrics {
-  Girls and boys come out to play,
-  The moon doth shine as bright as day;
- }
+  \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
 
 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
 >>
 @end lilypond
 
 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 @rglos{melisma}, a single syllable sung to more than one
+called a @notation{melisma}, a single syllable sung to more than one

 note.  There are several ways to spread a syllable over multiple
 notes, the simplest being to add a slur across them (see @ref{Ties
 and slurs}):
 
 @lilypond[verbatim,quote,ragged-right]
 <<
 note.  There are several ways to spread a syllable over multiple
 notes, the simplest being to add a slur across them (see @ref{Ties
 and slurs}):
 
 @lilypond[verbatim,quote,ragged-right]
 <<

- \relative c'' {
-  \key g \major
-  \time 6/8
-  d4 b8 c4 a8 d4 b8 g4 
-  g8 a4 b8 c([ b)] a d4 b8 g4.
- }
- \addlyrics {
-  Girls and boys come out to play,
-  The moon doth shine as bright as day;
- }
+  \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
 
 >> 
 @end lilypond
 


@@ -1238,11 +1326,11 @@ Here we have also used manual beaming (the square brackets @code{[
 (see @ref{Automatic and manual beams}).
 
 If a syllable extends over several notes or a single very long
 (see @ref{Automatic and manual beams}).
 
 If a syllable extends over several notes or a single very long

-note an @emph{extender line} is usually drawn from the syllable
+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:
 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]
 <<
   \relative c'' {
 @lilypond[verbatim,quote,ragged-right]
 <<
   \relative c'' {


@@ -1267,7 +1355,7 @@ far about aligning lyrics to notes.
 
 @c no ragged-right here because otherwise the hyphens get lost,
 @c but the example is long enough to avoid looking strange.
 
 @c no ragged-right here because otherwise the hyphens get lost,
 @c but the example is long enough to avoid looking strange.

-@lilypond[quote,verbatim]
+@lilypond[verbatim,quote]

 <<
   \relative c' {
     \key g \major
 <<
   \relative c' {
     \key g \major


@@ -1293,7 +1381,7 @@ quotes.  Here's an example from Rossini's Figaro, where
 
 @c no ragged-right here because otherwise the hyphens get lost,
 @c but the example is long enough to avoid looking strange.
 
 @c no ragged-right here because otherwise the hyphens get lost,
 @c but the example is long enough to avoid looking strange.

-@lilypond[quote,verbatim]
+@lilypond[verbatim,quote]

 <<
   \relative c' {
     \clef bass
 <<
   \relative c' {
     \clef bass


@@ -1309,13 +1397,9 @@ quotes.  Here's an example from Rossini's Figaro, where
 
 
 @seealso
 
 
 @seealso

-@quotation
-More options, such as inserting explicit rhythms into lyrics,
-inserting lyric ties (e.g., between @q{go al}) above, 
-alternative ways of handling melismata,
-and adding extra verses,
-are discussed in @ruser{Vocal music}.
-@end quotation
+
+Notation Reference: @ruser{Vocal music}.
+

 
 @node Lyrics to multiple staves
 @subsection Lyrics to multiple staves
 
 @node Lyrics to multiple staves
 @subsection Lyrics to multiple staves


@@ -1330,13 +1414,15 @@ example from Handel's Judas Maccabæus:
     \time 6/8
     \partial 8
   }
     \time 6/8
     \partial 8
   }

-  \relative c'' { \key f \major
+  \relative c'' {
+    \key f \major

     c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
   }
   \addlyrics {
     Let flee -- cy flocks the hills a -- dorn, __
   }
     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
+  \relative c' {
+    \key f \major

     r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
   }
   \addlyrics {
     r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
   }
   \addlyrics {


@@ -1351,11 +1437,8 @@ from the notes and lyrics with variables.  These are
 discussed later (see @ref{Organizing pieces with variables}).
 
 @seealso
 discussed later (see @ref{Organizing pieces with variables}).
 
 @seealso

-@quotation
-More options, such as putting multiple stanzas below the score,
-setting choral music, and lyrics to divided voices, 
-are discussed in @ruser{Vocal music}.
-@end quotation
+
+Notation Reference: @ruser{Vocal music}.

 
 
 @node Final touches
 
 
 @node Final touches


@@ -1387,13 +1470,13 @@ was used to write the file:
 @end example
 
 @noindent
 @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
 
 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
 
 
 @node Adding titles


@@ -1402,7 +1485,7 @@ 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
 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"
 
 @example
 \version "2.11.23"


@@ -1435,7 +1518,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.
 
 @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,
 {
   \clef bass
   c' b g, g,


@@ -1445,7 +1528,7 @@ bass clef.
 
 Here is a four-octave scale:
 
 
 Here is a four-octave scale:
 

-@lilypond[quote,verbatim,ragged-right]
+@lilypond[verbatim,quote,ragged-right]

 {
   \clef bass
   c, d, e, f,
 {
   \clef bass
   c, d, e, f,


@@ -1463,7 +1546,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:
 
 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
 {
   \key a \major
   \time 6/8


@@ -1476,7 +1559,7 @@ 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:
 
 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
 \relative c'' {
   \key a \major
   \time 6/8


@@ -1505,9 +1588,9 @@ polyphonic music with many staves, the input files can become very
 confusing.  We can reduce this confusion by using
 @emph{variables}.
 
 confusing.  We can reduce this confusion by using
 @emph{variables}.
 

-With variables (also known as variables or macros), we can break
-up complex music expressions.  An variable 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{} @}
 
 @example
 namedMusic = @{ @dots{} @}


@@ -1519,7 +1602,7 @@ later by placing a backslash in front of the name
 Variables must be defined @emph{before} the main music
 expression.
 
 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
 }}
 violin = \new Staff { \relative c'' {
   a4 b c b
 }}


@@ -1536,7 +1619,7 @@ cello = \new Staff { \relative c {
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-The name of an variable 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
 numbers, underscores, or dashes.
 
 It is possible to use variables for many other types of objects in


@@ -1564,12 +1647,12 @@ places.  The following example uses the above variables:
 @subsection After the tutorial
 
 After finishing the tutorial, you should probably try writing a
 @subsection After the tutorial
 
 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
+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
 tutorial, look at the Notation Reference, starting with

-@ruser{Basic notation}.  If you want to write for an instrument
+@ruser{Musical notation}.  If you want to write for an instrument

 ensemble that is not covered in the templates, take a look at
 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
 
 Once you have written a few short pieces, read the rest of the
 Learning Manual (chapters 3-5).  There's nothing wrong with


@@ -1582,9 +1665,9 @@ you have more experience.
 @node How to read the manual
 @subsection How to read the manual
 
 @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.
+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'' @{
 
 In the rest of the manual, we are much more lax about the printed
 examples: sometimes they may have omitted a @code{\relative c'' @{


@@ -1602,5 +1685,5 @@ display the exact input that LilyPond used to generate this
 manual.
 
 For information about the structure of the rest of the manual, see
 manual.
 
 For information about the structure of the rest of the manual, see

-@ruser{About this manual}.
+@ref{About this manual}.