Update docs to point to LSR-snippet instead of input/test/ and

[lilypond.git] / Documentation / user / advanced-notation.itely

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 51911fe741249d047d2ebcfa1c5475c9090f4683..e7cd36b3a22c72657594ad0ba658d4b9a4c9c285 100644 (file)
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -46,7 +46,9 @@ saved as UTF-8.  For more information, see @ref{Text encoding}.
 * Text marks::                  
 * Text markup::                 
 * Nested scores::               
 * Text marks::                  
 * Text markup::                 
 * Nested scores::               

+* Page wrapping text::          

 * Overview of text markup commands::  
 * Overview of text markup commands::  

+* Overview of text markup list commands::  

 * Font selection::              
 * New dynamic marks::           
 @end menu
 * Font selection::              
 * New dynamic marks::           
 @end menu


@@ -59,7 +61,7 @@ saved as UTF-8.  For more information, see @ref{Text encoding}.
 @cindex text items, non-empty
 @cindex non-empty texts
 
 @cindex text items, non-empty
 @cindex non-empty texts
 

-It is possible to place arbitrary strings of text or @ref{Text markup}
+It is possible to place arbitrary strings of text or @ref{Text markup},

 above or below notes by using a string @code{c^"text"}.  By default,
 these indications do not influence the note spacing, but by using the
 command @code{\fatText}, the widths will be taken into account
 above or below notes by using a string @code{c^"text"}.  By default,
 these indications do not influence the note spacing, but by using the
 command @code{\fatText}, the widths will be taken into account


@@ -235,8 +237,7 @@ Program reference: @internalsref{TextSpanner},
 @internalsref{Glissando}, @internalsref{VoiceFollower},
 @internalsref{TrillSpanner}, @internalsref{line-spanner-interface}.
 
 @internalsref{Glissando}, @internalsref{VoiceFollower},
 @internalsref{TrillSpanner}, @internalsref{line-spanner-interface}.
 

-Examples: @lsr{expressive,line-styles.ly}
-@c  FIXME: add {contemporary/line-arrows.ly} when LSR is updated.  -gp
+Examples: @lsr{expressive,line-styles.ly}, @lsr{expressive,line-arrows.ly}

 
 
 @node Text spanners
 
 
 @node Text spanners


@@ -256,11 +257,13 @@ properties
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 c1
 \textSpannerDown
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 c1
 \textSpannerDown

-\override TextSpanner #'edge-text = #'("rall " . "")
+\override TextSpanner #'bound-details #'left #'text =
+  \markup { \upright "rall" } 

 c2\startTextSpan b c\stopTextSpan a
 \break
 \textSpannerUp
 c2\startTextSpan b c\stopTextSpan a
 \break
 \textSpannerUp

-\override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+\override TextSpanner #'bound-details #'left #'text =
+  \markup { \italic "rit" } 

 c2\startTextSpan b c\stopTextSpan a
 @end lilypond
 
 c2\startTextSpan b c\stopTextSpan a
 @end lilypond
 


@@ -302,7 +305,7 @@ The @code{\mark} command is primarily used for
 but it can also be used to put signs like coda,
 segno, and fermata on a bar line.  Use @code{\markup} to
 access the appropriate symbol (symbols are listed in
 but it can also be used to put signs like coda,
 segno, and fermata on a bar line.  Use @code{\markup} to
 access the appropriate symbol (symbols are listed in

-@ref{The Feta font})
+@ref{The Feta font}).

 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 c1 \mark \markup { \musicglyph #"scripts.ufermata" }


@@ -415,7 +418,7 @@ c1_\markup { "\special {weird} #characters" }
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-See @ref{Overview of text markup commands} for a list of all
+See @ref{Overview of text markup commands}, for a list of all

 commands.
 
 @code{\markup} is primarily used for @internalsref{TextScript}s,
 commands.
 
 @code{\markup} is primarily used for @internalsref{TextScript}s,


@@ -431,7 +434,7 @@ but it can also be used anywhere text is called in lilypond
 
     \set Staff.instrumentName = \markup{ \column{ Alto solo } }
     c2^\markup{ don't be \flat }
 
     \set Staff.instrumentName = \markup{ \column{ Alto solo } }
     c2^\markup{ don't be \flat }

-    \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+    \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }

     b2\startTextSpan
     a2\mark \markup{ \large \bold Fine }
     r2\stopTextSpan
     b2\startTextSpan
     a2\mark \markup{ \large \bold Fine }
     r2\stopTextSpan


@@ -519,7 +522,7 @@ effect.
 
 In addition, vertical placement is performed after creating the
 text markup object.  If you wish to move an entire piece of markup,
 
 In addition, vertical placement is performed after creating the
 text markup object.  If you wish to move an entire piece of markup,

-you need to use the #'padding property or create an "anchor" point
+you need to use the #'padding property or create an @q{anchor} point

 inside the markup (generally with @code{\hspace #0}).
 
 @lilypond[quote,verbatim,fragment,relative=1]
 inside the markup (generally with @code{\hspace #0}).
 
 @lilypond[quote,verbatim,fragment,relative=1]


@@ -533,7 +536,7 @@ c'4^\markup{ \hspace #0 \raise #1.5 raised }
 Some situations (such as dynamic marks) have preset font-related
 properties.  If you are creating text in such situations, it
 is advisable to cancel those properties with
 Some situations (such as dynamic marks) have preset font-related
 properties.  If you are creating text in such situations, it
 is advisable to cancel those properties with

-@code{normal-text}.  See @ref{Overview of text markup commands}
+@code{normal-text}.  See @ref{Overview of text markup commands},

 for more details.
 
 
 for more details.
 
 


@@ -574,6 +577,40 @@ block.
 }
 @end lilypond
 
 }
 @end lilypond
 

+@node Page wrapping text
+@subsection Page wrapping text
+Whereas @code{\markup} is used to enter a non-breakable block of text,
+@code{\markuplines} can be used at top-level to enter lines of text that
+can spread over multiple pages:
+
+@verbatim
+\markuplines {
+  \justified-lines {
+    A very long text of justified lines.
+    ...
+  }
+  \justified-lines {
+    An other very long paragraph.
+    ...
+  }
+  ...
+}
+@end verbatim
+
+@code{\markuplines} accepts a list of markup, that is either the result
+of a markup list command, or a list of markups or of markup lists. The
+built-in markup list commands are described in
+@ref{Overview of text markup list commands}.
+
+@seealso
+
+This manual: @ref{Overview of text markup list commands}, 
+@ref{New markup list command definition}.
+
+@refcommands
+
+@funindex \markuplines
+@code{\markuplines}

 
 @node Overview of text markup commands
 @subsection Overview of text markup commands
 
 @node Overview of text markup commands
 @subsection Overview of text markup commands


@@ -582,6 +619,12 @@ The following commands can all be used inside @code{\markup @{ @}}.
 
 @include markup-commands.tely
 
 
 @include markup-commands.tely
 

+@node Overview of text markup list commands
+@subsection Overview of text markup list commands
+
+The following commands can all be used with @code{\markuplines}.
+
+@include markup-list-commands.tely

 
 @node Font selection
 @subsection Font selection
 
 @node Font selection
 @subsection Font selection


@@ -704,7 +747,7 @@ marks.  Note that the dynamic font only contains the characters
 Some situations (such as dynamic marks) have preset font-related
 properties.  If you are creating text in such situations, it
 is advisable to cancel those properties with
 Some situations (such as dynamic marks) have preset font-related
 properties.  If you are creating text in such situations, it
 is advisable to cancel those properties with

-@code{normal-text}.  See @ref{Overview of text markup commands}
+@code{normal-text}.  See @ref{Overview of text markup commands},

 for more details.
 
 @cindex make-dynamic-script
 for more details.
 
 @cindex make-dynamic-script


@@ -904,7 +947,7 @@ c4^\markup {
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-See @ref{Text markup} for more details.
+See @ref{Text markup}, for more details.

 
 
 @seealso
 
 
 @seealso


@@ -1009,7 +1052,7 @@ c1
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-See @ref{The Feta font} for a list of symbols which may be
+See @ref{The Feta font}, for a list of symbols which may be

 printed with @code{\musicglyph}.
 
 The horizontal location of rehearsal marks can be adjusted by
 printed with @code{\musicglyph}.
 
 The horizontal location of rehearsal marks can be adjusted by


@@ -1048,7 +1091,7 @@ definition of @code{format-mark-numbers} and
 @code{format-mark-letters}.  They can be used as inspiration for other
 formatting functions.
 
 @code{format-mark-letters}.  They can be used as inspiration for other
 formatting functions.
 

-Examples: @lsr{preparing,rehearsal-mark-numbers.ly}
+Examples: @lsr{parts,rehearsal-mark-numbers.ly}

 
 
 @node Bar numbers
 
 
 @node Bar numbers


@@ -1082,7 +1125,7 @@ be added
 Bar numbers can be typeset at regular intervals instead of at the
 beginning of each line.  This is illustrated in the following example,
 whose source is available as
 Bar numbers can be typeset at regular intervals instead of at the
 beginning of each line.  This is illustrated in the following example,
 whose source is available as

-@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}
+@lsr{staff,making-bar-numbers-appear-at-regular-intervals.ly}.

 
 @lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly}
 
 
 @lilypondfile[ragged-right,quote]{bar-number-regular-interval.ly}
 


@@ -1107,9 +1150,7 @@ c4 c c c
 
 Program reference: @internalsref{BarNumber}.
 
 
 Program reference: @internalsref{BarNumber}.
 

-Examples:
-@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
-and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
+Examples: @lsrdir{staff}

 
 
 @refbugs
 
 
 @refbugs


@@ -1391,7 +1432,7 @@ a piece of music with multiple @code{\tag} entries,
 
 @seealso
 
 
 @seealso
 

-Examples: @lsr{preparing,tag@/-filter@/.ly}
+Examples: @lsr{parts,tag@/-filter@/.ly}

 
 
 @refbugs
 
 
 @refbugs


@@ -1658,10 +1699,7 @@ Quoting nested triplets may result in poor notation.
 
 In this manual: @ref{Instrument transpositions}.
 
 
 In this manual: @ref{Instrument transpositions}.
 

-Examples:
-@c  FIXME: Add when LSR is updated.  -gp
-@c @i nputfileref{input/@/regression,quote@/.ly}
-@c @i nputfileref{input/@/regression,quote@/-transposition@/.ly}
+Examples: @lsr{parts,quote.ly}, @lsr{parts,quote-transportation.ly}

 
 Program reference: @internalsref{QuoteMusic}.
 
 
 Program reference: @internalsref{QuoteMusic}.
 


@@ -1699,19 +1737,19 @@ smaller = {
 
 \addQuote clarinet \relative {
   R1*20
 
 \addQuote clarinet \relative {
   R1*20

-  r2 r8 c f f
+  r2 r8 c' f f

 }
 
 \new Staff \relative  <<
 
 }
 
 \new Staff \relative  <<
 

-  % setup a context for  cue  notes.
+  % setup a context for cue notes.

   \new Voice = "cue" { \smaller \skip 1*21 }
 
   \set Score.skipBars = ##t
 
   \new Voice {
     R1*20
   \new Voice = "cue" { \smaller \skip 1*21 }
 
   \set Score.skipBars = ##t
 
   \new Voice {
     R1*20

-    \cueDuring #"clarinet" #1 {
+    \cueDuring #"clarinet" #UP {

       R1
     }
     g4 g2.
       R1
     }
     g4 g2.


@@ -1849,7 +1887,7 @@ Double time signatures are not supported explicitly, but they can be
 faked.  In the next example, the markup for the time signature is
 created with a markup text.  This markup text is inserted in the
 @internalsref{TimeSignature} grob. See also
 faked.  In the next example, the markup for the time signature is
 created with a markup text.  This markup text is inserted in the
 @internalsref{TimeSignature} grob. See also

-@inputfileref{input/@/test,compound@/-time@/.ly}).
+@lsr{contemporary,compound-time-signature}.

 
 @lilypond[verbatim,ragged-right]
 % create 2/4 + 5/8
 
 @lilypond[verbatim,ragged-right]
 % create 2/4 + 5/8


@@ -2108,12 +2146,6 @@ chords, e.g.,
 \makeClusters { <c e > <b f'> }
 @end lilypond
 
 \makeClusters { <c e > <b f'> }
 @end lilypond
 

-The following example (from
-@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
-looks like
-
-@lilypondfile[ragged-right,quote]{cluster.ly}
-

 Ordinary notes and clusters can be put together in the same staff,
 even simultaneously.  In such a case no attempt is made to
 automatically avoid collisions between ordinary notes and clusters.
 Ordinary notes and clusters can be put together in the same staff,
 even simultaneously.  In such a case no attempt is made to
 automatically avoid collisions between ordinary notes and clusters.


@@ -2124,7 +2156,7 @@ Program reference: @internalsref{ClusterSpanner},
 @internalsref{ClusterSpannerBeacon},
 @internalsref{Cluster_spanner_engraver}.
 
 @internalsref{ClusterSpannerBeacon},
 @internalsref{Cluster_spanner_engraver}.
 

-Examples: @inputfileref{input/@/regression,cluster@/.ly}.
+Examples: @lsr{contemporary,cluster@/.ly}.

 
 @refbugs
 
 
 @refbugs
 


@@ -2186,7 +2218,7 @@ music snippets.
 
 Improvisation is sometimes denoted with slashed note heads.  Such note
 heads can be created by adding a @internalsref{Pitch_squash_engraver}
 
 Improvisation is sometimes denoted with slashed note heads.  Such note
 heads can be created by adding a @internalsref{Pitch_squash_engraver}

-to the @internalsref{Staff} or @internalsref{Voice} context.  Then, the
+to the @internalsref{Voice} context.  Then, the

 following command
 
 @example
 following command
 
 @example


@@ -2202,7 +2234,7 @@ There are shortcuts @code{\improvisationOn} (and an accompanying
 the following example
 
 @lilypond[verbatim,ragged-right,quote]
 the following example
 
 @lilypond[verbatim,ragged-right,quote]

-\new Staff \with {
+\new Voice \with {

   \consists Pitch_squash_engraver
 } \transpose c c' {
   e8 e g a a16(bes)(a8) g \improvisationOn
   \consists Pitch_squash_engraver
 } \transpose c c' {
   e8 e g a a16(bes)(a8) g \improvisationOn


@@ -2547,7 +2579,7 @@ An x11 color is not necessarily exactly the same shade as a similarly
 named normal color.
 
 Notes in a chord cannot be colored with @code{\override}; use
 named normal color.
 
 Notes in a chord cannot be colored with @code{\override}; use

-@code{\tweak} instead.  See @ref{Objects connected to the input}
+@code{\tweak} instead.  See @ref{Objects connected to the input},

 for details.
 
 
 for details.
 
 


@@ -2579,9 +2611,43 @@ This only functions inside chords, even for single notes
 @node Grid lines
 @subsection Grid lines
 
 @node Grid lines
 @subsection Grid lines
 

-@c FIXME: get an example for grid lines.  -gp

 Vertical lines can be drawn between staves synchronized with
 the notes.
 
 Vertical lines can be drawn between staves synchronized with
 the notes.
 

-Examples: @inputfileref{input/@/regression,grid@/-lines@/.ly}.
+@lilypond[ragged-right,quote,verbatim]
+\layout {
+  \context {
+    \Staff
+    \consists "Grid_point_engraver" %% sets of grid
+    gridInterval = #(ly:make-moment 1 4)
+  }
+}
+
+\new Score \with {
+  \consists "Grid_line_span_engraver"
+  %% centers grid lines  horizontally below noteheads
+  \override NoteColumn #'X-offset = #-0.5
+}
+
+\new ChoirStaff <<
+  \new Staff {
+    \stemUp
+    \relative {
+      c'4. d8 e8 f g4
+    }
+  }
+  \new Staff {
+    %% centers grid lines  vertically
+    \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
+    \stemDown
+    \clef bass
+    \relative c {
+      c4  g'  f  e
+    }
+  }
+>>
+@end lilypond
+
+Examples: @lsrdir{education}
+