Update from Valentin.

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index bcdb2ee7c6a194b677ad7264c31819181ea558bf..01626800de567d3db148003886e429b00d64ffa0 100644 (file)
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -333,55 +333,30 @@ using the @code{\markup} mode specific syntax.
 A @code{\markup} block is used to typeset text with an extensible
 specific syntax called @qq{markup mode}.
 
-@c TODO: make a nicer example (maybe ask Trevor B?) -vv
-@lilypond[quote,verbatim]
-\header{ title = \markup{ \bold { foo \italic { bar! } } } }
-\score{
-  \relative c'' {
-    \override Score.RehearsalMark
-      #'break-visibility = #begin-of-line-invisible
-    \override Score.RehearsalMark #'self-alignment-X = #right
-
-    \set Staff.instrumentName = \markup{ \column{ Alto solo } }
-    c2^\markup{ don't be \flat }
-    \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
-    b2\startTextSpan
-    a2\mark \markup{ \large \bold Fine }
-    r2\stopTextSpan
-    \bar "||"
-  }
-  \addlyrics { bar, foo \markup{ \italic bar! } }
-}
-@end lilypond
-
 @cindex markup expressions
 @cindex markup syntax
 
 The markup syntax is similar to LilyPond's usual syntax: a
 @code{\markup} expression is enclosed in curly braces @code{@{
 @dots{} @}}.
-@c to delete?  -gp
-Markup expressions may also be enclosed in double quotes
-@code{"..."}, but these are treated as text strings.  Commands are
-interpreted literally.
 
 In markup mode, specific commands are entered using the backslash
 @code{\} character.  Such commands only affect the first following
 expression.
 
-In this example, the first markup is made of one word without any
-braces or quotes, while the following markups demonstrate the usefulness
-of nested markup expressions using braces.
-This syntax is prefered, as it allows both single-word and multi-word
-markups.
+Markup expressions may also be enclosed in double quotes
+@code{"..."}. Such expressions are treated as text strings
+and may not contain nested expressions or commands.
+Therefore, braces are generally prefered to double quotes;
+the following example demonstrates both syntaxes.
 
 @lilypond[quote,verbatim,fragment,relative=1]
-e1-\markup intenso
+e1-\markup "intenso"
 a2^\markup { poco \italic più forte  }
 c e1
 d2_\markup { \italic "string. assai" }
 e 
-b1^\markup { \bold { molto agitato } }
+b1^\markup { \bold { molto \italic  agitato } }
 c
 @end lilypond
 
@@ -404,8 +379,8 @@ cis a r4 r2
 @end lilypond
 
 The way markup expressions are defined affects 
-how these expressions will stacked, centered and aligned;
-this syntax is described in @ref{Text alignment}.
+how these expressions will stacked, centered and aligned
+when using the commands explained in @ref{Text alignment}.
 
 @lilypond[quote,verbatim,fragment,relative=1]
 c1^\markup { \column { a bbbb \line { c d } } }
@@ -426,7 +401,7 @@ c1^\markup { \center-align { a \line { bbb c } } }
 
 
 Markups can be stored in variables.  These variables may be
-attached to notes:
+directly attached to notes:
 
 @lilypond[quote,verbatim]
 allegro = \markup { \bold \large Allegro }
@@ -442,6 +417,37 @@ allegro = \markup { \bold \large Allegro }
 An exhaustive list of @code{\markup}-specific commands can be found in
 @ref{Text markup commands}.
 
+
+@seealso
+
+This manual: @ref{Text markup commands}.
+
+Snippets:
+@rlsr{Text}.
+
+Internals Reference: @rinternals{TextScript}.
+
+Init files: @file{scm/@/new@/-markup@/.scm}.
+
+
+@knownissues
+
+@c FIXME: this is totally deprecated, isn't it? -vv
+Kerning or generation of ligatures is only done when the @TeX{}
+backend is used.  In this case, LilyPond does not account for them
+so texts will be spaced slightly too wide.
+
+@c is the following sentence really relevant? -vv
+Syntax errors for markup mode are confusing.
+
+
+@node Common markup commands
+@subsubsection Common markup commands
+
+Some basic formatting can be used blah blah
+
+
+
 @ignore
 TODO: here are some commands that could be described here.
 I'm putting them in bulk, prior to working on this section. -vv
@@ -478,30 +484,6 @@ I'm putting them in bulk, prior to working on this section. -vv
 
 @end ignore
 
-@seealso
-
-This manual: @ref{Text markup commands}.
-
-Snippets:
-@rlsr{Text}.
-
-Internals Reference: @rinternals{TextScript}.
-
-Init files: @file{scm/@/new@/-markup@/.scm}.
-
-
-@knownissues
-
-Kerning or generation of ligatures is only done when the @TeX{}
-backend is used.  In this case, LilyPond does not account for them
-so texts will be spaced slightly too wide.
-
-Syntax errors for markup mode are confusing.
-
-@node Common markup commands
-@subsubsection Common markup commands
-
-Some basic formatting can be used blah blah
 
 
 @cindex font switching