Merge branch 'master' into lilypond/translation

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

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index d8be87f2e44898f41668ef2e49194df1fc3a585d..428a793359a6ea6b36274293982f26c812fa2a5a 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


@@ -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


@@ -353,15 +354,15 @@ bar lines,
   c1
   \key cis \major
   \clef alto
   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
   \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
   \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
   \key d \minor
   \clef tenor
   \time 3/4


@@ -370,6 +371,42 @@ bar lines,
 }
 @end lilypond
 
 }
 @end lilypond
 

+Possible symbols for the @code{break-align-symbols} list are
+@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
+@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
+@code{key-signature}, and @code{time-signature}.
+
+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
+  \key cis \major
+
+  % the RehearsalMark will be aligned with the left edge of the KeySignature
+  % and then shifted right by 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,
 
 Although text marks are normally only printed above the topmost
 staff, you may alter this to print them on every staff,
 


@@ -576,6 +613,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


@@ -584,6 +655,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


@@ -1014,30 +1091,7 @@ c1
 See @ref{The Feta font}, for a list of symbols which may be
 printed with @code{\musicglyph}.
 
 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
-setting @code{break-align-symbol}
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative]
-c1
-\key cis \major
-\clef alto
-\override Score.RehearsalMark #'break-align-symbol = #'key-signature
-\mark "on-key"
-cis
-\key ces \major
-\override Score.RehearsalMark #'break-align-symbol = #'clef
-\clef treble
-\mark "on clef"
-ces
-@end lilypond
-
-@code{break-align-symbol} may also accept the following values:
-@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
-@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
-@code{key-signature}, and @code{time-signature}.  Setting
-@code{break-align-symbol} will only have an effect if the symbol
-appears at that point in the music.
-
+For common tweaks to the positioning of rehearsal marks, see @ref{Text marks}.

 
 @seealso
 
 
 @seealso
 


@@ -1050,7 +1104,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


@@ -1084,7 +1138,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}
 


@@ -1109,9 +1163,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


@@ -1393,7 +1445,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


@@ -1660,10 +1712,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}.
 


@@ -1851,7 +1900,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


@@ -2110,12 +2159,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.


@@ -2126,7 +2169,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
 


@@ -2171,9 +2214,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]
 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) 
 {
 \featherDurations #(ly:make-moment 5 4) 
 {

-  \override Beam #'grow-direction = #LEFT

   c16[ c c c c c c]
 }
 @end lilypond
   c16[ c c c c c c]
 }
 @end lilypond


@@ -2188,7 +2231,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


@@ -2204,7 +2247,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


@@ -2581,9 +2624,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}
+