X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Fcommon-notation.itely;h=7b07c8e959fb6047acbfb238c1cf898e2236cafd;hb=e7aa6c445f463844dbaa52d38ea4aac2882b5601;hp=a7faab25041a6567fa01d35a6bc0e85ba2cd780e;hpb=9158bc17904d4dd930a1f776cfe3226f1ad84092;p=lilypond.git

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index a7faab2504..7b07c8e959 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.19.2"
 
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
@@ -51,7 +51,7 @@ This section introduces common notation that is used for one voice
 on one staff.
 
 @menu
-* Bar checks::
+* Bar lines and bar checks::
 * Accidentals and key signatures::
 * Ties and slurs::
 * Articulation and dynamics::
@@ -60,9 +60,32 @@ on one staff.
 * Advanced rhythmic commands::
 @end menu
 
+@node Bar lines and bar checks
+@subsection Bar lines and bar checks
+
+@menu
+* Bar lines::
+* Bar checks::
+@end menu
+
+@node Bar lines
+@unnumberedsubsubsec Bar lines
+
+
+Single bar lines are automatically placed in the music so
+there is no need to add them manually.  Other types of bar
+lines are added using @code{\bar}, for example
+@code{\bar "||"} for a double bar line, or @code{\bar "|."}
+for an ending bar line.  For a full list of bar lines see
+the @ruser{Bar lines}.
+
+@lilypond[verbatim,quote,relative=2]
+g1 e1 \bar "||" c2. c'4 \bar "|."
+@end lilypond
 
 @node Bar checks
-@subsection Bar checks
+@unnumberedsubsubsec Bar checks
+
 
 Though not strictly necessary, @emph{bar checks} should be
 used in the input code to show where bar lines are expected
@@ -84,11 +107,19 @@ Notation Reference:
 @node Accidentals and key signatures
 @subsection Accidentals and key signatures
 
+@menu
+* Accidentals::
+* Key signatures::
+* Warning key signatures and pitches::
+@end menu
+
 @warning{New users are often confused by these -- please read the
 warning at the bottom of this page, especially if you are not
 familiar with music theory!}
 
-@subheading Accidentals
+@node Accidentals
+@unnumberedsubsubsec Accidentals
+
 
 @cindex accidentals
 @cindex accidentals and key signatures
@@ -120,7 +151,10 @@ cis4 ees fisis, aeses
 @end lilypond
 
 @cindex key signature, setting
-@subheading Key signatures
+
+@node Key signatures
+@unnumberedsubsubsec Key signatures
+
 
 @cindex key signature
 @cindex major
@@ -151,7 +185,9 @@ a1 |
 
 @smallspace
 
-@subheading Warning: key signatures and pitches
+@node Warning key signatures and pitches
+@unnumberedsubsubsec Warning: key signatures and pitches
+
 
 Music Glossary: @rglos{accidental}, @rglos{key signature},
 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
@@ -197,7 +233,7 @@ aes4 c b c
 
 If the above seems confusing, consider this: if you were playing a
 piano, which key would you hit?  If you would press a black key,
-then you @emph{must} add @code{-is} or @code{-es} to the note
+then you @emph{must} add @w{@code{-is}} or @w{@code{-es}} to the note
 name!
 
 Adding all alterations explicitly might require a little more
@@ -228,7 +264,15 @@ Notation Reference:
 @funindex ( ... )
 @funindex \( ... \)
 
-@subheading Ties
+@menu
+* Ties::
+* Slurs::
+* Phrasing slurs::
+* Warnings slurs vs. ties::
+@end menu
+
+@node Ties
+@unnumberedsubsubsec Ties
 
 
 Music Glossary: @rglos{tie}.
@@ -237,10 +281,11 @@ A @notation{tie} is created by appending a tilde @code{~} to the
 first note being tied.
 
 @lilypond[verbatim,quote,relative=2]
-g4~ g c2~ | c4~ c8 a~ a2 |
+g4~ 4 c2~ | 4~ 8 a~ 2 |
 @end lilypond
 
-@subheading Slurs
+@node Slurs
+@unnumberedsubsubsec Slurs
 
 
 Music Glossary: @rglos{slur}.
@@ -253,7 +298,9 @@ starting note and ending note are marked with @code{(} and
 d4( c16) cis( d e c cis d) e( d4)
 @end lilypond
 
-@subheading Phrasing slurs
+@node Phrasing slurs
+@unnumberedsubsubsec Phrasing slurs
+
 
 Music Glossary: @rglos{slur}, @rglos{phrasing}.
 
@@ -269,7 +316,10 @@ g4\( g8( a) b( c) b4\)
 @smallspace
 
 @cindex slurs versus ties
-@subheading Warnings: slurs vs. ties
+
+@node Warnings slurs vs. ties
+@unnumberedsubsubsec Warnings: slurs vs. ties
+
 
 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
 
@@ -280,7 +330,7 @@ indicate the @notation{articulation} of notes, and can be used on
 larger groups of notes.  Slurs and ties can be nested.
 
 @lilypond[verbatim,quote,relative=2]
-c4~( c8 d~ d4 e)
+c4~( c8 d~ 4 e)
 @end lilypond
 
 
@@ -294,8 +344,15 @@ Notation Reference:
 @node Articulation and dynamics
 @subsection Articulation and dynamics
 
+@menu
+* Articulations::
+* Fingerings::
+* Dynamics::
+@end menu
+
+@node Articulations
+@unnumberedsubsubsec Articulations
 
-@subheading Articulations
 
 @cindex articulation
 @cindex accent
@@ -307,11 +364,13 @@ Common @notation{articulations} can be added to a note using a
 dash @code{-} and a single character:
 
 @lilypond[verbatim,quote,relative=2]
-c4-^ c-+ c-- c-|
+c4-^ c-+ c-- c-!
 c4-> c-. c2-_
 @end lilypond
 
-@subheading Fingerings
+@node Fingerings
+@unnumberedsubsubsec Fingerings
+
 
 @cindex fingering
 
@@ -337,7 +396,9 @@ to let LilyPond determine the articulation directions.
 c4_-^1 d^. f^4_2-> e^-_+
 @end lilypond
 
-@subheading Dynamics
+@node Dynamics
+@unnumberedsubsubsec Dynamics
+
 
 @cindex dynamics
 @cindex decrescendo
@@ -471,7 +532,15 @@ Notation Reference:
 @node Advanced rhythmic commands
 @subsection Advanced rhythmic commands
 
-@subheading Partial measure
+@menu
+* Partial measure::
+* Tuplets::
+* Grace notes::
+@end menu
+
+@node Partial measure
+@unnumberedsubsubsec Partial measure
+
 
 @cindex pickup
 @cindex anacrusis
@@ -491,30 +560,35 @@ is a quarter note pickup and @code{\partial 8} an eighth note.
 c2 d |
 @end lilypond
 
-@subheading Tuplets
+@node Tuplets
+@unnumberedsubsubsec Tuplets
+
 
 @cindex tuplets
 @cindex triplets
 
-@funindex \times
-@funindex times
+@funindex \tuplet
+@funindex tuplet
 
 Music Glossary: @rglos{note value}, @rglos{triplet}.
 
-@notation{Tuplets} are made with the @code{\times} keyword.  It
+@notation{Tuplets} are made with the @code{\tuplet} 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
+fraction is the number of tuplet notes over the number 
+of notes normally filling the same duration.
+For triplets, there are three notes instead of two, so
+@notation{triplets} have 3/2 as their fraction.
 
 @lilypond[verbatim,quote,relative=2]
-\times 2/3 { f8 g a }
-\times 2/3 { c8 r c }
-\times 2/3 { f,8 g16[ a g a] }
-\times 2/3 { d4 a8 }
+\tuplet 3/2 { f8 g a }
+\tuplet 3/2 { c8 r c }
+\tuplet 3/2 { f,8 g16[ a g a] }
+\tuplet 3/2 { d4 a8 }
 @end lilypond
 
-@subheading Grace notes
+@node Grace notes
+@unnumberedsubsubsec Grace notes
+
 
 @cindex grace notes
 @cindex acciaccatura
@@ -535,7 +609,7 @@ although they can also be created by prefixing a music expression
 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
 
 @lilypond[verbatim,quote,relative=2]
-c2 \grace { a32[ b] } c2 |
+c2 \grace { a32 b } c2 |
 c2 \appoggiatura b16 c2 |
 c2 \acciaccatura b16 c2 |
 @end lilypond
@@ -576,6 +650,12 @@ than one voice on the same staff.
 @cindex compound music expression
 @cindex music expression, compound
 
+@menu
+* Analogy mathematical expressions::
+* Simultaneous music expressions multiple staves::
+* Simultaneous music expressions single staff::
+@end menu
+
 In LilyPond input files, music is represented by @emph{music
 expressions}.  A single note is a music expression:
 
@@ -599,7 +679,9 @@ one).  The result is another music expression:
 { { a4 g } f4 g }
 @end lilypond
 
-@subheading Analogy: mathematical expressions
+@node Analogy mathematical expressions
+@unnumberedsubsubsec Analogy: mathematical expressions
+
 
 This mechanism is similar to mathematical formulas: a big formula
 is created by composing small formulas.  Such formulas are called
@@ -625,7 +707,9 @@ arbitrarily deep, which is necessary for complex music like
 polyphonic scores.
 
 
-@subheading Simultaneous music expressions: multiple staves
+@node Simultaneous music expressions multiple staves
+@unnumberedsubsubsec Simultaneous music expressions: multiple staves
+
 
 @cindex multiple staves
 @cindex staves, multiple
@@ -668,12 +752,14 @@ 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.
 
-@warning{each note is relative to the previous note in
-the input, not relative to the @code{c''} in the initial
+@warning{each note is relative to the previous note in the input,
+only the first is relative to the @code{c''} in the initial
 @code{@bs{}relative} command.}
 
 
-@subheading Simultaneous music expressions: single staff
+@node Simultaneous music expressions single staff
+@unnumberedsubsubsec Simultaneous music expressions: single staff
+
 
 To determine the number of staves in a piece, LilyPond looks at
 the beginning of the first expression.  If there is a single note,
@@ -758,9 +844,6 @@ than polyrhythmic scores.
 }
 @end lilypond
 
-
-
-
 @node Staff groups
 @subsection Staff groups
 
@@ -776,7 +859,10 @@ than polyrhythmic scores.
 @funindex GrandStaff
 @funindex ChoirStaff
 
-Music Glossary: @rglos{brace}.
+Music Glossary:
+@rglos{brace},
+@rglos{staff},
+@rglos{system}.
 
 Piano music is typeset in two staves connected by a
 @notation{brace}.
@@ -846,7 +932,8 @@ ties with chords.  They must be placed outside the angle brackets.
 
 @lilypond[verbatim,quote,relative=2]
 r4 <c e g>~ <c f a>2 |
-<c e g>8[ <c f a> <c e g> <c f a>] <c e g>\>[ <c f a> <c f a> <c e g>]\! |
+<c e g>8[ <c f a> <c e g> <c f a>]
+  <c e g>8\>[ <c f a> <c f a> <c e g>]\! |
 r4 <c e g>8.\p <c f a>16( <c e g>4-. <c f a>) |
 @end lilypond
 
@@ -933,12 +1020,7 @@ separating each syllable with a space.
 >>
 @end lilypond
 
-@warning{It is essential that the final syllable is separated from
-the terminating curly bracket by a space or a newline, or it will be
-assumed to be part of the syllable, giving rise to an obscure
-error, see @rprogram{Apparent error in ../ly/init.ly}.}
-
-Note the double angle brackets @w{@code{<< ... >>}} around the
+Note the double angle brackets @w{@code{<<@dots{}>>}} around the
 whole piece to show that the music and lyrics are to occur at the
 same time.
 
@@ -1112,7 +1194,7 @@ Here's an example from Rossini's @notation{Figaro}, where
     \clef "bass"
     \key c \major
     \time 6/8
-    c4.~ c8 d b | c8([ d]) b c d b | c8
+    c4.~ 8 d b | c8([ d]) b c d b | c8
   }
   \addlyrics {
     Lar -- go_al fac -- | to -- tum del -- la cit -- | tà
@@ -1142,7 +1224,7 @@ example from Handel's @notation{Judas Maccabæus}:
     \key f \major
     \time 6/8
     \partial 8
-    c8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ c4
+    c8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
   }
   \addlyrics {
     Let | flee -- cy flocks the | hills a -- | dorn, __
@@ -1249,7 +1331,7 @@ of another variable, giving a way of shortening the input if a
 section of music is repeated many times.
 
 @lilypond[verbatim,quote]
-tripletA = \times 2/3 { c,8 e g }
+tripletA = \tuplet 3/2 { c,8 e g }
 barA = { \tripletA \tripletA \tripletA \tripletA }
 
 \relative c'' {
@@ -1312,7 +1394,7 @@ underneath the version number.
 
 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}.
+@ruser{Creating titles headers and footers}.
 
 
 @node Absolute note names
@@ -1326,14 +1408,13 @@ above the music.  More information on titling can be found in
 @cindex 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.
+This is usually the fastest way to enter most music.  Without
+@code{\relative}, pitches are interpreted in 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.
+In this mode, LilyPond treats all pitches as absolute values.  A
+@code{c'} will always mean middle C, a @code{b} will always mean
+the note one step below middle C, and a @code{g,} will always mean
+the note on the bottom staff of the bass clef.
 
 @lilypond[verbatim,quote]
 {
@@ -1393,9 +1474,25 @@ to find.
 
 However, absolute mode is useful for music which has large
 intervals, and is extremely useful for computer-generated LilyPond
-files.
+files.  When cutting and pasting melody fragments, absolute mode
+preserves the original octave.
 
+Sometimes music is arranged in more complex ways.  If you are
+using @code{\relative} inside of @code{\relative}, the outer and
+inner relative sections are independent:
 
+@lilypond[verbatim,quote]
+\relative c { c'4 \relative c'' { f g } c }
+@end lilypond
+
+@funindex \absolute
+If you are using absolute music inside of relative, you'll need to
+mark the absolute music explicitly with @code{\absolute} to stop
+it from becoming part of the relative music:
+
+@lilypond[verbatim,quote]
+\relative c { c'4 \absolute { f'' g'' } c }
+@end lilypond
 
 @node After the tutorial
 @subsection After the tutorial