Slight update to the feathered beam example, to reduce the risk for confusion

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

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index d0602a3c66b0af92d9b46592f95d4aa5ba3c36cf..69beebf8204fba524fa967f6145cf83fcc1c0739 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::               
+* Page wrapping text::          
 * Overview of text markup commands::  
+* Overview of text markup list commands::  
 * Font selection::              
 * New dynamic marks::           
 @end menu
@@ -352,15 +354,15 @@ bar lines,
   c1
   \key cis \major
   \clef alto
-  \override Score.RehearsalMark #'break-align-symbol = #'key-signature
+  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
   \mark "on key"
   cis
   \key ces \major
-  \override Score.RehearsalMark #'break-align-symbol = #'clef
+  \override Score.RehearsalMark #'break-align-symbols = #'(clef)
   \clef treble
   \mark "on clef"
   ces
-  \override Score.RehearsalMark #'break-align-symbol = #'time-signature
+  \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
   \key d \minor
   \clef tenor
   \time 3/4
@@ -369,6 +371,36 @@ bar lines,
 }
 @end lilypond
 
+The text marks will, by default, be aligned with the middle of the notation
+object, but this can be changed by overriding the
+@code{break-align-anchor-alignment} and
+@code{break-align-anchor} properties for the appropriate grob.
+
+@lilypond[fragment,quote,ragged-right,verbatim]
+{
+  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+  c1
+  \key cis \major
+
+  % the RehearsalMark will be aligned with the left edge of the KeySignature
+  \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
+  \mark \default
+  cis1
+  \key ces \major
+
+  % the RehearsalMark will be aligned with the right edge of the KeySignature
+  \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
+  \mark \default
+  ces1
+
+  % the RehearsalMark will be aligned with the right edge of the KeySignature
+  % and then shifted right by an additional 2 units.
+  \once \override Staff.KeySignature #'break-align-anchor = #2
+  \mark \default
+  ces1
+}
+@end lilypond
+
 Although text marks are normally only printed above the topmost
 staff, you may alter this to print them on every staff,
 
@@ -575,6 +607,40 @@ block.
 }
 @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
@@ -583,6 +649,12 @@ The following commands can all be used inside @code{\markup @{ @}}.
 
 @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
@@ -1020,11 +1092,11 @@ setting @code{break-align-symbol}
 c1
 \key cis \major
 \clef alto
-\override Score.RehearsalMark #'break-align-symbol = #'key-signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
 \mark "on-key"
 cis
 \key ces \major
-\override Score.RehearsalMark #'break-align-symbol = #'clef
+\override Score.RehearsalMark #'break-align-symbols = #'(clef)
 \clef treble
 \mark "on clef"
 ces
@@ -1083,7 +1155,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
-@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}
 
@@ -1108,9 +1180,7 @@ c4 c c c
 
 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
@@ -1847,7 +1917,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
-@inputfileref{input/@/test,compound@/-time@/.ly}).
+@lsr{contemporary,compound-time-signature}.
 
 @lilypond[verbatim,ragged-right]
 % create 2/4 + 5/8
@@ -2161,9 +2231,9 @@ property of a @code{Beam}.  The @code{\featherDurations} function
 can be used to adjust note durations.
 
 @lilypond[ragged-right,relative=1,fragment,verbatim,quote]
+\override Beam #'grow-direction = #LEFT
 \featherDurations #(ly:make-moment 5 4) 
 {
-  \override Beam #'grow-direction = #LEFT
   c16[ c c c c c c]
 }
 @end lilypond
@@ -2178,7 +2248,7 @@ music snippets.
 
 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
@@ -2194,7 +2264,7 @@ There are shortcuts @code{\improvisationOn} (and an accompanying
 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
@@ -2608,7 +2678,6 @@ the notes.
 >>
 @end lilypond
 
-Examples: @inputfileref{input/@/regression,grid@/-lines@/.ly}.
-
+Examples: @lsrdir{education}