Doc-de: update macros.itely and nitpicks

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

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index a08e4799f01fb5a3d38ef0fcacf2635a3d3cdb83..f5c20df99596a69f176c9bff63a8d43a6b426417 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.61"
+@c \version "2.12.0"
 
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
@@ -460,7 +460,6 @@ Here is a small example showing all these elements together:
 
 
 @seealso
-
 Notation Reference: @ruser{Writing pitches},
 @ruser{Writing rhythms}, @ruser{Writing rests},
 @ruser{Time signature}, @ruser{Clef}.
@@ -504,7 +503,7 @@ Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
 
 @item
 @strong{Whitespace insensitive}:
-it does not matter how many spaces (or new lines) you add.
+it does not matter how many spaces (or tabs or new lines) you add.
 @w{@code{@{ c d e @}}} means the same thing as
 @w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
 
@@ -523,6 +522,13 @@ thumb is to indent code blocks with either a tab or two spaces:
 @}
 @end example
 
+However, whitespace @emph{is} required to separate many syntactical
+elements from others.  In other words, whitespace can always be
+@emph{added}, but it cannot be @emph{eliminated}.  As missing
+whitespace can give rise to strange errors it is advisable to
+always insert whitespace before and after every syntactic element,
+for example, before and after every curly brace.
+
 @item
 @strong{Expressions}:
 every piece of LilyPond input needs to have @strong{@{ curly
@@ -634,14 +640,13 @@ 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.
 
-@seealso
 
+@seealso
 There are more tips for constructing input files in
 @ref{Suggestions for writing LilyPond input files}.  But it might be
 best to read through the rest of the tutorial first.
 
 
-
 @node Single staff notation
 @section Single staff notation
 
@@ -775,8 +780,8 @@ according to different conventions.  For some examples how
 accidentals can be printed according to different rules, see
 @ruser{Automatic accidentals}.
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Note names in other languages},
 @ruser{Accidentals}, @ruser{Automatic accidentals},
 @ruser{Key signature}.
@@ -852,8 +857,8 @@ larger groups of notes.  Slurs and ties can be nested.
 c2~( c8 fis fis4 ~ fis2 g2)
 @end lilypond
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Ties}, @ruser{Slurs},
 @ruser{Phrasing slurs}.
 
@@ -942,8 +947,8 @@ example @code{\f}, will end the (de)crescendo, or the command
 c2\< c2\ff\> c2 c2\!
 @end lilypond
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Articulations and ornamentations},
 @ruser{Fingering instructions}, @ruser{Dynamics}.
 
@@ -975,7 +980,6 @@ a1_\markup{
 
 
 @seealso
-
 Notation Reference: @ruser{Writing text}.
 
 
@@ -1025,8 +1029,8 @@ a8 c b4 d8. c16 b4
 a8 c b4 d8. c16 b4
 @end lilypond
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
 
 
@@ -1102,8 +1106,8 @@ c2 \appoggiatura b16 c2
 c2 \acciaccatura b16 c2
 @end lilypond
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
 @ruser{Upbeats}.
 
@@ -1366,8 +1370,8 @@ 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 bar lines.
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Keyboard and other multi-staff
 instruments},
 @ruser{Displaying staves}.
@@ -1423,57 +1427,16 @@ r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
 @funindex \\
 @funindex >>
 
-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 @w{@code{@{...@}}}) and combining these simultaneously,
-separating the voices with @code{\\}:
-
-@lilypond[verbatim,quote,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 (@code{s}) instead of a normal
-rest (@code{r}),
-
-@lilypond[verbatim,quote,relative=2]
-<<
-  { a4 g2 f4~ f4 } \\
-  { s4 g4 f2 f4 }
->>
-@end lilypond
-
-@noindent
-Again, these expressions can be nested arbitrarily.
-
-@lilypond[verbatim,quote,relative=2]
-<<
-  \new Staff <<
-    { a4 g2 f4~ f4 } \\
-    { s4 g4 f2 f4 }
-  >>
-  \new Staff <<
-    \clef bass
-    { <c g>1 ~ <c g>4 } \\
-    { e,,4 d e2 ~ e4}
-  >>
->>
-@end lilypond
+Polyphonic music in lilypond, while not difficult, uses concepts
+that we haven't discussed yet, so we're not going to introduce
+them here. Instead, the following sections introduce these concepts
+and explain them thoroughly.
 
 @seealso
+Learning Manual: @ref{Voices contain music}.
 
 Notation Reference: @ruser{Simultaneous notes}.
 
-
 @node Songs
 @section Songs
 
@@ -1697,7 +1660,6 @@ Here's an example from Rossini's @notation{Figaro}, where
 
 
 @seealso
-
 Notation Reference: @ruser{Vocal music}.
 
 
@@ -1739,12 +1701,11 @@ produced by separating out the score structure from the notes and
 lyrics with variables.  These are discussed in @ref{Organizing
 pieces with variables}.
 
-@seealso
 
+@seealso
 Notation Reference: @ruser{Vocal music}.
 
 
-
 @node Final touches
 @section Final touches