Doc: Issue 4303: Misleading documentation of barchecks in lyrics

  - Remove the use of barchecks in lyrics in the LM, but retain
    the link to the place where they are mentioned in the NR.

  - Demonstrate the use of barchecks in a simple example of
    music, replacing the example in lyrics.  Note that this will
    produce a warning when compiled.

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index ff5775a6167c33937f3c4c2a855271955628cbcc..bd0475ba82bf7c1ad6ba599a42031e9be0825854 100644 (file)
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -95,10 +95,26 @@ durations that make each measure add up to the correct
 length.  Bar checks also make your input code easier to
 read, since they help to keep things organized.
 
 length.  Bar checks also make your input code easier to
 read, since they help to keep things organized.
 

-@lilypond[verbatim,quote,relative=2]
-g1 | e1 | c2. c'4 | g4 c g e | c4 r r2 |
+@c This example deliberately produces a warning
+@lilypond[verbatim,quote]
+\relative g' {
+  g1 | e1 | c2. c' | g4 c g e | c4 r r2 |
+}

 @end lilypond
 
 @end lilypond
 

+If you compile the code in the example above, you should see a
+warning in the console output:
+
+@example
+warning: barcheck failed at: 1/2
+ g1 | e1 | c2. c'
+                  | g4 c g e | c4 r r2 |
+@end example
+
+Although the missing duration is clear in the musical output in this
+simple example, the warning in the console output is far more
+effective in drawing attention to the missing @code{4} in bar 3.
+

 @seealso
 Notation Reference:
 @ruser{Bar and bar number checks}.
 @seealso
 Notation Reference:
 @ruser{Bar and bar number checks}.


@@ -1026,7 +1042,7 @@ separating each syllable with a space.
     d4 b8 c4 a8 | d4 b8 g4
   }
   \addlyrics {
     d4 b8 c4 a8 | d4 b8 g4
   }
   \addlyrics {

-    Girls and boys come | out to play,
+    Girls and boys come out to play,

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1061,26 +1077,13 @@ shine as bright as day}.  Let's extend it:
     a4 b8 c b a | d4 b8 g4. |
   }
   \addlyrics {
     a4 b8 c b a | d4 b8 g4. |
   }
   \addlyrics {

-    Girls and boys come | out to play,
-    The | moon doth shine as | bright as day; |
+    Girls and boys come out to play,
+    The moon doth shine as bright as day;

   }
 >>
 @end lilypond
 
   }
 >>
 @end lilypond
 

-If you compile the code in the example above, you should see some
-warnings in the console output:
-
-@example
-song.ly:12:29: warning: barcheck failed at: 5/8
-    The | moon doth shine as
-                             | bright as day; |
-song.ly:12:46: warning: barcheck failed at: 3/8
-    The | moon doth shine as | bright as day;
-                                              |
-@end example
-
-This is a good example of the usefulness of bar checks.  Now,
-looking at the music, we see that the extra lyrics do not align
+Looking at the music, we see that the extra lyrics do not align

 properly with the notes.  The word @notation{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
 properly with the notes.  The word @notation{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


@@ -1096,8 +1099,8 @@ to add a slur across them, for details, see @ref{Ties and slurs}:
     a4 b8 c( b) a | d4 b8 g4. |
   }
   \addlyrics {
     a4 b8 c( b) a | d4 b8 g4. |
   }
   \addlyrics {

-    Girls and boys come | out to play,
-    The | moon doth shine as | bright as day; |
+    Girls and boys come out to play,
+    The moon doth shine as bright as day;

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1117,8 +1120,8 @@ manual beams}.
     a4 b8 c([ b]) a | d4 b8 g4. |
   }
   \addlyrics {
     a4 b8 c([ b]) a | d4 b8 g4. |
   }
   \addlyrics {

-    Girls and boys come | out to play,
-    The | moon doth shine as | bright as day; |
+    Girls and boys come out to play,
+    The moon doth shine as bright as day;

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1136,8 +1139,8 @@ that should be included in the melisma:
     a4 b8 c[ b] a | d4 b8 g4. |
   }
   \addlyrics {
     a4 b8 c[ b] a | d4 b8 g4. |
   }
   \addlyrics {

-    Girls and boys come | out to play,
-    The | moon doth shine _ as | bright as day; |
+    Girls and boys come out to play,
+    The moon doth shine _ as bright as day;

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1158,8 +1161,8 @@ first three bars of @notation{Dido's Lament}, from Purcell's
     c4.( bes8 a4. g8 fis4.) g8 | fis1
   }
   \addlyrics {
     c4.( bes8 a4. g8 fis4.) g8 | fis1
   }
   \addlyrics {

-    When I am | laid,
-    am | laid __ in | earth,
+    When I am laid,
+    am laid __ in earth,

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1183,8 +1186,8 @@ far about aligning lyrics to notes.
     d4 d e | c2
   }
   \addlyrics {
     d4 d e | c2
   }
   \addlyrics {

-    A -- | way in a __ | man -- ger,
-    no __ | crib for a | bed, __
+    A -- way in a __ man -- ger,
+    no __ crib for a bed,

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1208,7 +1211,7 @@ Here's an example from Rossini's @notation{Figaro}, where
     c4.~ 8 d b | c8([ d]) b c d b | c8
   }
   \addlyrics {
     c4.~ 8 d b | c8([ d]) b c d b | c8
   }
   \addlyrics {

-    Lar -- go_al fac -- | to -- tum del -- la cit -- | tà
+    Lar -- go_al fac -- to -- tum del -- la cit -- tà

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -1238,7 +1241,7 @@ example from Handel's @notation{Judas Maccabæus}:
     c8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
   }
   \addlyrics {
     c8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
   }
   \addlyrics {

-    Let | flee -- cy flocks the | hills a -- | dorn, __
+    Let flee -- cy flocks the hills a -- dorn, __

   }
   \relative c' {
     \key f \major
   }
   \relative c' {
     \key f \major


@@ -1247,7 +1250,7 @@ example from Handel's @notation{Judas Maccabæus}:
     r8 | r4. r4 c8 | a'8([ g]) f f([ e]) d | e8([ d]) c bes'4
   }
   \addlyrics {
     r8 | r4. r4 c8 | a'8([ g]) f f([ e]) d | e8([ d]) c bes'4
   }
   \addlyrics {

-    Let | flee -- cy flocks the | hills a -- dorn,
+    Let flee -- cy flocks the hills a -- dorn,

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond