Misc minor updates.

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

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 266e89236686162056735199f1464a459e3412eb..3e76b025e2d9b40a18a8ed617e734912dfa5e81c 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -472,13 +472,22 @@ 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.  However, block comments do not @q{nest}.
-This means that you cannot place a block comment inside another 
-block comment.  If you try, the first @code{%@}} will terminate 
-@emph{both} block comments.  The following
-fragment shows possible uses for comments:
+that line is ignored.  By convention, a line comment is placed
+@emph{above} the code it refers to.
+
+@example
+a4 a a a
+% this comment refers to the Bs
+b2 b
+@end example
+
+A block comment marks a whole section of music input as a comment.
+Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
+However, block comments do not @q{nest}.  This means that you
+cannot place a block comment inside another block comment.  If you
+try, the first @code{%@}} will terminate @emph{both} block
+comments.  The following fragment shows possible uses for
+comments:
 
 @example
 % notes for twinkle twinkle follow
@@ -1133,7 +1142,7 @@ scores, and @code{\new ChoirStaff,} suitable for
 vocal scores.  These staff groups each form another
 type of context, one that generates the brace at the
 left end of every system and also controls the extent
-of barlines.
+of bar lines.
 
 @seealso