GDP: Process comments on LM 3 (C)

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

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index 1d21ed4a7f5e51789bbb038ff84f0cc8705663df..3c2c2a4d20aa1a17a2b445ff5466ca705328c94d 100644 (file)
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -6,13 +6,20 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.38"
+

 @node Text
 @section Text
 
 @lilypondfile[quote]{text-headword.ly}
 
 This section explains how to include text (with various
 @node Text
 @section Text
 
 @lilypondfile[quote]{text-headword.ly}
 
 This section explains how to include text (with various

-formatting) in your scores.
+formatting) in music scores.
+
+@noindent
+Some text elements that are not dealt with here are discussed in other
+specific sections: @ref{Vocal music}, @ref{Titles and headers}.
+

 
 @cindex Text, other languages
 @warning{To write accented and special text (such as characters
 
 @cindex Text, other languages
 @warning{To write accented and special text (such as characters


@@ -22,67 +29,23 @@ information, see @ref{Text encoding}.}
 
 @menu
 * Writing text::                
 
 @menu
 * Writing text::                

-* Text markup::                 
+* Formatting text::             
+* Fonts::                       

 @end menu
 
 
 @node Writing text
 @subsection Writing text
 
 @end menu
 
 
 @node Writing text
 @subsection Writing text
 

+This section introduces different ways of adding text to a score.
+

 @menu
 @menu

-* Overview of text entry::      

 * Text scripts::                
 * Text spanners::               
 * Text marks::                  
 * Text scripts::                
 * Text spanners::               
 * Text marks::                  

+* Separate text::               

 @end menu
 
 @end menu
 

-@node Overview of text entry
-@subsubsection Overview of text entry
-
-There are four ways to add text to scores:
-
-@itemize
-@item
-@ref{Text scripts}: blah blah
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4^"text" c c c
-@end lilypond
-
-@item
-@ref{Text spanners}: blah blah
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c1
-\override TextSpanner #'bound-details #'left #'text =
-  \markup { \upright "rall" } 
-c2\startTextSpan b c\stopTextSpan a
-@end lilypond
-
-@item
-@ref{Text marks}: blah blah
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4\mark "foo" c c c
-@end lilypond
-
-@item
-@ref{Vocal music}: blah blah, not in this section.
-
-@lilypond[verbatim,quote,ragged-right]
-<<
-  \relative c'' { c4 c c c }
-  \addlyrics { one two three four }
->>
-@end lilypond
-
-@end itemize
-
-@seealso
-
-Snippets: @lsrdir{Text,Text}
-
-

 
 @node Text scripts
 @subsubsection Text scripts
 
 @node Text scripts
 @subsubsection Text scripts


@@ -91,8 +54,8 @@ Snippets: @lsrdir{Text,Text}
 @cindex text items, non-empty
 @cindex non-empty texts
 
 @cindex text items, non-empty
 @cindex non-empty texts
 

-It is possible to add arbitrary text indications with
-@var{note}@code{-"}@var{text}@code{"}.
+It is possible to add arbitrary text indications
+to a score, as demonstrated in the following example.

 Such indications can also be manually placed
 above or below the staff, using the
 simple syntax described in @ref{Controlling direction and
 Such indications can also be manually placed
 above or below the staff, using the
 simple syntax described in @ref{Controlling direction and


@@ -104,8 +67,8 @@ d8^"pizz." e f g a4-"scherz." f
 
 In LilyPond, such text strings are called @command{markup}
 objects.  This syntax is actually a shorthand; more complex text
 
 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}.
+formatting may be added to a note by explicitly using a
+@code{\markup} block, as described in @ref{Formatting text}.

 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
 d8^\markup { \italic pizz. } e f g 
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
 d8^\markup { \italic pizz. } e f g 


@@ -131,11 +94,13 @@ d8^"pizz." e f g \textLengthOn a4_"scherzando" f
 
 @seealso
 
 
 @seealso
 

-Notation Reference: @ref{Text markup}.
+Notation Reference: @ref{Formatting text},
+@ref{Controlling direction and placement}.

 
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

-Internals Reference: @internalsref{TextScript}.
+Internals Reference: @rinternals{TextScript}.

 
 @knownissues
 
 
 @knownissues
 


@@ -157,9 +122,8 @@ default; to enable it, use
 Some performance indications, e.g., @i{rallentando} or
 @i{accelerando}, are written as text and are extended over many
 measures with dotted lines.
 Some performance indications, e.g., @i{rallentando} or
 @i{accelerando}, are written as text and are extended over many
 measures with dotted lines.

-

 Such objects, called @q{spanners}, may be created
 Such objects, called @q{spanners}, may be created

-from one note to another by using the following syntax:
+from one note to another using the following syntax:

 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \override TextSpanner #'bound-details #'left #'text = "rit." 
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \override TextSpanner #'bound-details #'left #'text = "rit." 


@@ -169,9 +133,9 @@ e,\stopTextSpan
 
 @noindent
 The string to be printed is set through
 
 @noindent
 The string to be printed is set through

-object properties. By default it is printed in italic characters,
+object properties.  By default it is printed in italic characters,

 but different formatting can be obtained using
 but different formatting can be obtained using

-@code{\markup} blocks:
+@code{\markup} blocks, as described in @ref{Formatting text}.

 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \override TextSpanner #'bound-details #'left #'text =
 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 \override TextSpanner #'bound-details #'left #'text =


@@ -181,7 +145,7 @@ e,\stopTextSpan
 @end lilypond
 
 The line style, as well as the text string, can be defined as an
 @end lilypond
 
 The line style, as well as the text string, can be defined as an

-object property. This syntax is described in @ref{Line styles}.
+object property.  This syntax is described in @ref{Line styles}.

 
 @predefined
 
 
 @predefined
 


@@ -194,9 +158,12 @@ object property. This syntax is described in @ref{Line styles}.
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{Text,Text}
+Notation Reference: @ref{Line styles}.
+
+Snippets:
+@rlsr{Text}.

 
 

-Internals Reference: @internalsref{TextSpanner}.
+Internals Reference: @rinternals{TextSpanner}.

 
 
 @node Text marks
 
 
 @node Text marks


@@ -212,12 +179,12 @@ Various text elements can be added to a score using
 the syntax described in @ref{Rehearsal marks}:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 the syntax described in @ref{Rehearsal marks}:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]

-c4\mark "dolce" c c c
+c4\mark "Allegro" c c c

 @end lilypond
 
 This syntax makes possible to put any text on a bar line;
 more complex text formatting may be added using a @code{\markup}
 @end lilypond
 
 This syntax makes possible to put any text on a bar line;
 more complex text formatting may be added using a @code{\markup}

-block, as described in @ref{Text markup}.  This can be used to print
+block, as described in @ref{Formatting text}.  This can be used to print

 signs like coda, segno or fermata, by specifying the appropriate
 symbol name:
 
 signs like coda, segno or fermata, by specifying the appropriate
 symbol name:
 


@@ -227,14 +194,14 @@ c1
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-Such objects are only typeset above the top staff of the score; they
-can be placed above the bar line or between notes, depending on whether
-you specify it at the end or the middle of a bar. When specified at the
-beginning of a score or at a line break, the mark will be printed at
+Such objects are only typeset above the top staff of the score; depending on
+whether they are specified at the end or the middle of a bar, they 
+can be placed above the bar line or between notes.  When specified at the
+beginning of a score or at a line break, marks will be printed at

 the beginning of the line (the next line, in case of a line break).
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 the beginning of the line (the next line, in case of a line break).
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]

-\mark "dolce" c1
+\mark "Allegro" c1

 c\mark "assai" \break
 c c
 @end lilypond
 c\mark "assai" \break
 c c
 @end lilypond


@@ -253,9 +220,13 @@ c c
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{Text,Text}
+Notation Reference: @ref{Rehearsal marks},
+@ref{Formatting text}, @ref{The Feta font}.

 
 

-Internals Reference: @internalsref{RehearsalMark}.
+Snippets:
+@rlsr{Text}.
+
+Internals Reference: @rinternals{RehearsalMark}.

 
 @knownissues
 @c  IMO this is a bug; hopefully it'll be fixed soon, so I can
 
 @knownissues
 @c  IMO this is a bug; hopefully it'll be fixed soon, so I can


@@ -266,14 +237,89 @@ If a mark is entered at the end of the last bar of the score (where
 there is no next line), then the mark will not be printed at
 all.
 
 there is no next line), then the mark will not be printed at
 all.
 

-@node Text markup
-@subsection Text markup
+@node Separate text
+@subsubsection Separate text
+
+@cindex separate text
+@cindex standalone text
+@cindex top-level text
+@cindex text, standalone
+@funindex \markup
+
+A @code{\markup} block can exist by itself, outside of any
+any @code{\score} block, as a @qq{top-level
+expression}.  This syntax is described in @ref{File structure}.
+
+@lilypond[quote,ragged-right,verbatim]
+\markup {
+  Tomorrow, and tomorrow, and tomorrow...
+}
+@end lilypond
+
+@noindent
+This allows to print text separately
+from the music, which is particularly 
+useful when the input file contains
+several music pieces, as described in
+@ref{Multiple scores in a book}.
+
+@lilypond[quote,ragged-right,verbatim]
+\score {
+  c'1
+}
+\markup {
+  Tomorrow, and tomorrow, and tomorrow...
+}
+\score {
+  c'1
+}
+@end lilypond
+
+Using a specific syntax, text blocks can be spread
+over multiple pages, making possible to print
+text documents or books -- and therefore to
+use LilyPond as a word processor.  This syntax is described in
+@ref{Multi-page markup}.
+
+@predefined
+
+@funindex \markup
+@code{\markup},
+@funindex \markuplines
+@code{\markuplines}
+
+@ignore
+@snippets
+
+TODO: add convenient snippets in input/new -vv
+@end ignore
+
+@seealso
+
+Notation Reference: @ref{Formatting text},
+@ref{File structure}, 
+@ref{Multiple scores in a book},
+@ref{Multi-page markup}.
+
+Snippets:
+@rlsr{Text}.
+
+Internals Reference: @rinternals{TextScript}.
+
+
+@node Formatting text
+@subsection Formatting text
+
+This section presents basic and advanced text formatting,
+using the @code{\markup} mode specific syntax.

 
 @menu
 * Text markup introduction::    
 
 @menu
 * Text markup introduction::    

-* Nested scores::               
-* Page wrapping text::          
-* Font selection::              
+* Common markup commands::      
+* Text alignment::              
+* Graphic notation inside markup::  
+* Music notation inside markup::  
+* Multi-page markup::          

 @end menu
 
 @node Text markup introduction
 @end menu
 
 @node Text markup introduction


@@ -285,7 +331,7 @@ all.
 @cindex typeset text
 
 A @code{\markup} block is used to typeset text with an extensible syntax,
 @cindex typeset text
 
 A @code{\markup} block is used to typeset text with an extensible syntax,

-called @q{markup mode}.
+called @qq{markup mode}.

 Specific commands can be entered in this mode, using the
 backslash @code{\} character.
 @c TODO: move the following sentence (and add an example?) -vv
 Specific commands can be entered in this mode, using the
 backslash @code{\} character.
 @c TODO: move the following sentence (and add an example?) -vv


@@ -304,8 +350,6 @@ c1_\markup { "\special {weird} #characters" }
 An exhaustive list of @code{\markup}-specific commands can be found in
 @ref{Text markup commands}.
 
 An exhaustive list of @code{\markup}-specific commands can be found in
 @ref{Text markup commands}.
 

-@code{\markup} blocks can be used anywhere text is called,
-and not only for @internalsref{TextScript}s objects.

 
 @lilypond[quote,verbatim]
 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
 
 @lilypond[quote,verbatim]
 \header{ title = \markup{ \bold { foo \italic { bar! } } } }


@@ -327,14 +371,7 @@ and not only for @internalsref{TextScript}s objects.
 }
 @end lilypond
 
 }
 @end lilypond
 

-A @code{\markup} block can also be printed on its own at the top-level
-of the input file, away from
-any @code{\score} block. This syntax is described in
-@ref{Multiple scores in a book}.

 
 

-@lilypond[quote,ragged-right,verbatim]
-\markup{ Here is some text. }
-@end lilypond

 
 @cindex font switching
 
 
 @cindex font switching
 


@@ -399,7 +436,7 @@ allegro = \markup @{ \bold \large @{ Allegro @} @}
 
 Some objects have alignment procedures of their own, which cancel
 out any effects of alignments applied to their markup arguments as
 
 Some objects have alignment procedures of their own, which cancel
 out any effects of alignments applied to their markup arguments as

-a whole.  For example, the @internalsref{RehearsalMark} is
+a whole.  For example, the @rinternals{RehearsalMark} is

 horizontally centered, so using @code{\mark \markup @{ \left-align
 .. @}} has no effect.
 
 horizontally centered, so using @code{\mark \markup @{ \left-align
 .. @}} has no effect.
 


@@ -422,14 +459,50 @@ properties.  If you are creating text in such situations, it is
 advisable to cancel those properties with @code{normal-text}.  See
 @ref{Text markup commands}, for more details.
 
 advisable to cancel those properties with @code{normal-text}.  See
 @ref{Text markup commands}, for more details.
 

+@ignore
+TODO: here are some commands that could be described here.
+I'm putting them in bulk, prior to working on this section. -vv
+
+\simple
+
+\char
+\fraction
+
+\combine
+\concat
+\put-adjacent
+
+
+\page-ref (see also "Table of contents")
+\fromproperty
+\verbatim-file
+\with-url
+
+\on-the-fly 
+\override
+
+
+\null
+\hspace
+
+\lower
+\raise 
+\translate 
+\translate-scaled
+\rotate
+\transparent
+\whiteout
+
+@end ignore

 
 @seealso
 
 This manual: @ref{Text markup commands}.
 
 
 @seealso
 
 This manual: @ref{Text markup commands}.
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

-Internals Reference: @internalsref{TextScript}.
+Internals Reference: @rinternals{TextScript}.

 
 Init files: @file{scm/@/new@/-markup@/.scm}.
 
 
 Init files: @file{scm/@/new@/-markup@/.scm}.
 


@@ -442,13 +515,186 @@ so texts will be spaced slightly too wide.
 
 Syntax errors for markup mode are confusing.
 
 
 Syntax errors for markup mode are confusing.
 

+@node Common markup commands
+@subsubsection Common markup commands
+
+Some basic formatting can be used blah blah
+
+\italic 
+\upright
+\bold 
+\medium        
+\underline
+       
+
+@c TODO: what's the difference between the following commands? -vv
+\smallCaps     
+\caps 
+\fontCaps
+
+
+Some alternate font families can easily be selected:
+
+\sans
+\typewriter
+\roman
+\number (only for numbers, such as fingerings and time signatures)
+@c TODO: add \slashed-digit here? -vv
+
+The size can be blah blah blah
+
+\fontsize
+
+Some predefined font sizes can be used blah blah
+
+\teeny
+\tiny
+\small 
+\normalsize
+\large
+\huge
+
+Some shorcuts allow to change the font size relatively to its previous value 
+
+\smaller
+\bigger
+\larger
+
+\magnify
+
+Text may be printed as subscript or superscript:
+
+\sub 
+\super
+
+To obtain subscripts or superscripts in a normal text size, use
+\normal-size-sub
+\normal-size-super
+
+All these settings (except the size) can be reverted to the default font:
+
+\normal-text 

 
 

-@node Nested scores
-@subsubsection Nested scores

 
 

-It is possible to nest music inside markups, by adding a
-@code{\score} block to a markup expression.  Such a score must
-contain a @code{\layout} block.
+@node Text alignment
+@subsubsection Text alignment
+
+Alignment basics:
+\left-align
+\center-align
+\right-align
+
+Horizontal alignment:
+\hcenter
+\general-align
+\halign 
+
+
+Vertical alignment: 
+\vcenter
+\column 
+\dir-column 
+
+Building a "large" markup:
+
+\line
+
+\fill-line
+
+\hcenter-in
+       
+\pad-around
+\pad-markup
+\pad-to-box
+\pad-x
+       
+Alignment inside a "large" markup:
+
+\justify-field 
+\justify
+\justify-string
+
+\wordwrap-field
+\wordwrap
+\wordwrap-string
+
+@node Graphic notation inside markup
+@subsubsection Graphic notation inside markup
+Graphics around text:
+\box
+\circle
+
+\bracket
+\hbracket
+
+"Standalone" graphics:
+
+\arrow-head
+\draw-line
+\draw-circle
+\filled-box
+\triangle
+\strut
+
+\with-color
+
+
+Advanced graphics:
+\stencil
+
+\postscript
+\epsfile
+
+\with-dimensions
+
+@node Music notation inside markup
+@subsubsection Music notation inside markup
+
+Notes can be printed in markup mode blah blah:
+
+\note  
+\note-by-number
+
+Accidental symbols can be obtained easily:
+
+\doubleflat
+\sesquiflat
+\flat
+\semiflat
+\natural
+\semisharp
+\sharp
+\sesquisharp
+\doublesharp
+
+Some other notation objects blah blah
+
+\beam
+\finger
+\dynamic
+\tied-lyric
+\markalphabet
+\markletter
+@c TODO: add \text here? -vv
+
+Any musical symbol can be printed
+
+\musicglyph
+@c TODO: add \lookup here? -vv
+
+
+The markup mode has support for fret diagrams:
+
+\fret-diagram 
+\fret-diagram-terse
+\fret-diagram-verbose
+
+An entire @code{\score} block can even be nested in a @code{\markup}
+block.  In such a case, the @code{\score} must contain a @code{\layout} block.
+
+
+\score
+

 
 @lilypond[quote,verbatim,ragged-right]
 \relative {
 
 @lilypond[quote,verbatim,ragged-right]
 \relative {


@@ -464,10 +710,11 @@ contain a @code{\layout} block.
 
 @seealso
 
 
 @seealso
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 

-@node Page wrapping text
-@subsubsection Page wrapping text
+@node Multi-page markup
+@subsubsection Multi-page markup

 
 Whereas @code{\markup} is used to enter a non-breakable block of
 text, @code{\markuplines} can be used at top-level to enter lines
 
 Whereas @code{\markup} is used to enter a non-breakable block of
 text, @code{\markuplines} can be used at top-level to enter lines


@@ -497,15 +744,61 @@ lists.  The built-in markup list commands are described in
 This manual: @ref{Text markup list commands}, @ref{New
 markup list command definition}.
 
 This manual: @ref{Text markup list commands}, @ref{New
 markup list command definition}.
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.

 
 @predefined
 
 @funindex \markuplines
 @code{\markuplines}
 
 
 @predefined
 
 @funindex \markuplines
 @code{\markuplines}
 

-@node Font selection
-@subsubsection Font selection
+
+
+@c TODO: move the following subsubsec into NR3 -vv
+@c maybe.  -gp
+@node Fonts
+@subsection Fonts
+
+@menu
+* Entire document fonts::       
+* Single entry fonts::          
+@end menu
+
+@node Entire document fonts
+@subsubsection Entire document fonts
+
+It is also possible to change the default font family for the
+entire document.  This is done by calling the
+@code{make-pango-font-tree} from within the @code{\paper} block.
+The function takes names for the font families to use for roman,
+sans serif and monospaced text.  For example,
+
+@cindex font families, setting
+@cindex Pango
+
+
+@lilypond[verbatim]
+\paper  {
+  myStaffSize = #20
+
+  #(define fonts
+    (make-pango-font-tree "Times New Roman"
+                          "Nimbus Sans"
+                          "Luxi Mono"
+                           (/ myStaffSize 20)))
+}
+
+{
+  c'^\markup { roman: foo \sans bla \typewriter bar }
+}
+@end lilypond
+
+@c we don't do Helvetica / Courier, since GS incorrectly loads
+@c Apple TTF fonts
+
+
+@node Single entry fonts
+@subsubsection Single entry fonts

 
 @cindex font selection
 @cindex font magnification
 
 @cindex font selection
 @cindex font magnification


@@ -582,39 +875,11 @@ property.  The resulting size is taken relative to the
 @cindex font magnification
 
 
 @cindex font magnification
 
 

-It is also possible to change the default font family for the
-entire document.  This is done by calling the
-@code{make-pango-font-tree} from within the @code{\paper} block.
-The function takes names for the font families to use for roman,
-sans serif and monospaced text.  For example,
-
-@cindex font families, setting
-@cindex Pango
-
-
-@lilypond[verbatim]
-\paper  {
-  myStaffSize = #20
-
-  #(define fonts
-    (make-pango-font-tree "Times New Roman"
-                          "Nimbus Sans"
-                          "Luxi Mono"
-                           (/ myStaffSize 20)))
-}
-
-{
-  c'^\markup { roman: foo \sans bla \typewriter bar }
-}
-@end lilypond
-
-@c we don't do Helvetica / Courier, since GS incorrectly loads
-@c Apple TTF fonts
-

 
 
 @seealso
 
 
 
 @seealso
 

-Snippets: @lsrdir{Text,Text}
+Snippets:
+@rlsr{Text}.