Update from Valentin.

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index fe4464f894d58358112e4c06bc06785942c26a3e..9a7aa024576749311ce9c6cca4ef4da9d8414e7a 100644 (file)
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -92,16 +92,23 @@ Snippets: @lsrdir{Text,Text}
 @cindex text items, non-empty
 @cindex non-empty texts
 
-It is possible to place arbitrary strings of text or @ref{Text
-markup} with @var{note}@code{-"}@var{text}@code{"}.
+It is possible to add arbitrary text indications with
+@var{note}@code{-"}@var{text}@code{"}. Such indications can be
+placed above or below the staff, using the simple syntax described
+in @ref{Controlling direction and placement}.
 
-INSERT EXAMPLE
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+d8^"pizz." e f g a4_"scherz." f
+@end lilypond
 
-More complex formatting may also be added to a note by using the
+In LilyPond, such text strings are called @command{markup}
+objects.  This syntax is actually a shorthand; more complex text
+formatting may be added to a note by explicitly using the
 @code{\markup} command, as described in @ref{Text markup}.
 
 @lilypond[fragment,ragged-right,verbatim,quote]
-c'4^\markup { bla \bold bla }
+d8^\markup { \italic pizz. } e f g 
+a4_\markup { \tiny scherz. \bold molto } f
 @end lilypond
 
 @predefined
@@ -111,15 +118,13 @@ c'4^\markup { bla \bold bla }
 @funindex \textLengthOff
 @code{\textLengthOff}.
 
-
-@snippets
-@c TODO: put this in the LSR. -vv
-By default, these indications do not influence the note spacing.
+By default, text indications do not influence the note spacing.
 However, by using the command @code{\textLengthOn}, the widths
-will be taken into account:
+will be taken into account: in the following example, the first
+text string does not affect spacing, whereas the second one does.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c4^"this does not affect spacing" \textLengthOn c4_"whereas this does" c4
+d8^"pizz." e f g \textLengthOn a4_"scherzando" f
 @end lilypond
 
 @noindent
@@ -127,7 +132,9 @@ After having used such a command, to go back to the default behavior
 and prevent text from influencing spacing, use @code{\textLengthOff}.
 
 
-@c TODO: LSR-ize this as well -vv
+@snippets
+
+@c FIXME: add an example and LSR-ize this? -vv
 Checking to make sure that text scripts and lyrics are within the
 margins is a relatively large computational task.  To speed up
 processing, lilypond does not perform such calculations by