Docs: NR Tweak command: can't be used to modify stems,

[lilypond.git] / Documentation / user / changing-defaults.itely

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index f3ba95a48a7bfbd9744f30295060dede185f082e..b63980e924431bc738d5dba35a20ff9a648fa636 100644 (file)
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -7,7 +7,7 @@
     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.65"
+@c \version "2.12.0"

 
 @node Changing defaults
 @chapter Changing defaults
 
 @node Changing defaults
 @chapter Changing defaults


@@ -57,6 +57,7 @@ This section describes what contexts are, and how to modify them.
 @menu
 * Contexts explained::
 * Creating contexts::
 @menu
 * Contexts explained::
 * Creating contexts::

+* Keeping contexts alive::

 * Modifying context plug-ins::
 * Changing context default settings::
 * Defining new contexts::
 * Modifying context plug-ins::
 * Changing context default settings::
 * Defining new contexts::


@@ -402,6 +403,156 @@ these forms
 
 @end itemize
 
 
 @end itemize
 

+@node Keeping contexts alive
+@subsection Keeping contexts alive
+
+@cindex contexts, keeping alive
+@cindex contexts, lifetime
+
+Contexts are usually terminated at the first musical moment in
+which they have nothing to do.  So @code{Voice} contexts die as
+soon as they contain no events; @code{Staff} contexts die as soon
+as all the @code{Voice} contexts within them contain no events; etc.
+This can cause difficulties if earlier contexts which have died
+have to be referenced, for example, when changing staves with
+@code{\change} commands, associating lyrics with a voice with
+@code{\lyricsto} commands, or when adding further musical events to
+an earlier context.
+
+There is an exception to this general rule: just one of the
+@code{Voice} contexts in a @code{Staff} context or in a
+@code{<<...>>} construct will always persist to the end of the
+enclosing @code{Staff} context or @code{<<...>>} construct, even
+though there may be periods when it has nothing to do.  The context
+to persist in this way will be the first one encountered in the
+first enclosed @code{@{...@}} construct, ignoring any in enclosed
+@code{<<...>>} constructs.
+
+Any context can be kept alive by ensuring it has something to do at
+every musical moment.  @code{Staff} contexts are kept alive by
+ensuring one of their voices is kept alive.  One way of doing this
+is to add spacer rests to a voice in parallel with the real music.
+These need to be added to every @code{Voice} context which needs to
+be kept alive.  If several voices are to be used sporadically it is
+safest to keep them all alive rather than attempting to rely on the
+exceptions mentioned above.
+
+In the following example, both voice A and voice B are kept alive
+in this way for the duration of the piece:
+
+@lilypond[quote,verbatim]
+musicA = \relative c'' { d4 d d d }
+musicB = \relative c'' { g4 g g g }
+keepVoicesAlive = {
+  <<
+    \new Voice = "A" { s1*5 }  % Keep Voice "A" alive for 5 bars
+    \new Voice = "B" { s1*5 }  % Keep Voice "B" alive for 5 bars
+  >>
+}
+
+music = {
+  \context Voice = "A" {
+    \voiceOneStyle
+    \musicA
+  }
+  \context Voice = "B" {
+    \voiceTwoStyle
+    \musicB
+  }
+  \context Voice = "A" { \musicA }
+  \context Voice = "B" { \musicB }
+  \context Voice = "A" { \musicA }
+}
+
+\score {
+  \new Staff <<
+    \keepVoicesAlive
+    \music
+  >>
+}
+@end lilypond
+
+@cindex lyrics, aligning with sporadic melody
+
+The following example shows how a sporadic melody line with lyrics
+might be written using this approach.  In a real situation the
+melody and accompaniment would consist of several different
+sections, of course.
+
+@lilypond[quote,verbatim]
+melody = \relative c'' { a4 a a a }
+accompaniment = \relative c' { d4 d d d }
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+\score {
+  <<
+    \new Staff = "music" {
+      <<
+        \new Voice = "melody" {
+          \voiceOne
+          s1*4  % Keep Voice "melody" alive for 4 bars
+        }
+        {
+          \new Voice = "accompaniment" {
+            \voiceTwo
+            \accompaniment
+          }
+          <<
+            \context Voice = "melody" { \melody }
+            \context Voice = "accompaniment" { \accompaniment }
+          >>
+          \context Voice = "accompaniment" { \accompaniment }
+          <<
+            \context Voice = "melody" { \melody }
+            \context Voice = "accompaniment" { \accompaniment }
+          >>
+        }
+      >>
+    }
+    \new Lyrics \with { alignAboveContext = #"music" }
+    \lyricsto "melody" { \words }
+  >>
+}
+@end lilypond
+
+An alternative way, which may be better in many circumstances, is
+to keep the melody line alive by simply including spacer notes to
+line it up correctly with the accompaniment:
+
+@lilypond[quote,verbatim]
+melody = \relative c'' {
+  s1  % skip a bar
+  a4 a a a
+  s1  % skip a bar
+  a4 a a a
+}
+accompaniment = \relative c' {
+  d4 d d d
+  d4 d d d
+  d4 d d d
+  d4 d d d
+}
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+
+\score {
+  <<
+    \new Staff = "music" {
+      <<
+        \new Voice = "melody" {
+          \voiceOne
+          \melody
+        }
+        \new Voice = "accompaniment" {
+          \voiceTwo
+          \accompaniment
+        }
+      >>
+    }
+    \new Lyrics \with { alignAboveContext = #"music" }
+    \lyricsto "melody" { \words }
+  >>
+}
+@end lilypond
+

 
 @node Modifying context plug-ins
 @subsection Modifying context plug-ins
 
 @node Modifying context plug-ins
 @subsection Modifying context plug-ins


@@ -602,6 +753,7 @@ to indicate improvisation in jazz pieces,
   \name ImproVoice
   \type "Engraver_group"
   \consists "Note_heads_engraver"
   \name ImproVoice
   \type "Engraver_group"
   \consists "Note_heads_engraver"

+  \consists "Rhythmic_column_engraver"

   \consists "Text_engraver"
   \consists Pitch_squash_engraver
   squashedPosition = #0
   \consists "Text_engraver"
   \consists Pitch_squash_engraver
   squashedPosition = #0


@@ -766,7 +918,7 @@ ossia = { f4 f f f }
   \relative c' \new Staff = "main" {
     c4 c c c
     <<
   \relative c' \new Staff = "main" {
     c4 c c c
     <<

-      \new Staff \with {alignAboveContext=main} \ossia
+      \new Staff \with { alignAboveContext = #"main" } \ossia

       { d8 f d f d f d f }
     >>
   }
       { d8 f d f d f d f }
     >>
   }


@@ -1480,7 +1632,7 @@ command to remain immediately adjacent to the object to which it is
 to apply after the input file has been converted to a music stream.
 This is often not the case, as many additional elements are inserted
 into the music stream implicitly.  For example, when a note which is
 to apply after the input file has been converted to a music stream.
 This is often not the case, as many additional elements are inserted
 into the music stream implicitly.  For example, when a note which is

-not part of a chord is processed, Lilypond implicitly inserts a
+not part of a chord is processed, LilyPond implicitly inserts a

 @code{ChordEvent} event before the note, so separating the tweak
 from the note.  However, if chord symbols are placed round the
 tweak and the note, the @code{\tweak} command comes after the
 @code{ChordEvent} event before the note, so separating the tweak
 from the note.  However, if chord symbols are placed round the
 tweak and the note, the @code{\tweak} command comes after the


@@ -1521,12 +1673,12 @@ and @code{\tweak} may be used to modify any single occurrence of
 these items.
 
 Notably the @code{\tweak} command cannot be used to modify stems,
 these items.
 
 Notably the @code{\tweak} command cannot be used to modify stems,

-beams or accidentals, since these are generated later by note heads,
-rather than by music elements in the input stream.  Nor can a
-@code{\tweak} command be used to modify clefs or time signatures,
-since these become separated from any preceding @code{\tweak}
-command in the input stream by the automatic insertion of extra
-elements required to specify the context.
+beams or accidentals directly, since these are generated later by
+note heads, rather than by music elements in the input stream.
+Nor can a @code{\tweak} command be used to modify clefs or time
+signatures, since these become separated from any preceding
+@code{\tweak} command in the input stream by the automatic
+insertion of extra elements required to specify the context.

 
 But the @code{\tweak} command can be used as an alternative to
 the @code{\override} command to modify those notational elements
 
 But the @code{\tweak} command can be used as an alternative to
 the @code{\override} command to modify those notational elements


@@ -1799,6 +1951,15 @@ indicator is @strong{always} required before
 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
 @end itemize
 
 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
 @end itemize
 

+These indications affect only the next note.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+c2_( c)
+c2( c)
+c2^( c)
+@end lilypond
+

 @strong{The direction property}
 
 The position or direction of many layout objects is controlled
 @strong{The direction property}
 
 The position or direction of many layout objects is controlled


@@ -1836,6 +1997,17 @@ TrillPitchAccidental - not tried
 TrillPitchGroup - not tried
 @end ignore
 
 TrillPitchGroup - not tried
 @end ignore
 

+These indications affect all notes until they are cancelled.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+\slurDown
+c2( c)
+c2( c)
+\slurNeutral
+c2( c)
+@end lilypond
+

 
 
 @node Distances and measurements
 
 
 @node Distances and measurements


@@ -2761,7 +2933,7 @@ marks on such objects.
 * Setting @code{X-offset} and @code{Y-offset} directly::
 * Using the @code{side-position-interface}::
 * Using the @code{self-alignment-interface}::
 * Setting @code{X-offset} and @code{Y-offset} directly::
 * Using the @code{side-position-interface}::
 * Using the @code{self-alignment-interface}::

-* Using the @code{break-aligned-interface}::
+* Using the @code{break-alignable-interface}::

 @end menu
 
 @node Setting @code{X-offset} and @code{Y-offset} directly
 @end menu
 
 @node Setting @code{X-offset} and @code{Y-offset} directly


@@ -2928,17 +3100,20 @@ example shows the difference:
 
 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
 
 
 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
 

-@node Using the @code{break-aligned-interface}
-@unnumberedsubsubsec Using the @code{break-aligned-interface}
+@node Using the @code{break-alignable-interface}
+@unnumberedsubsubsec Using the @code{break-alignable-interface}

 
 

-Rehearsal marks may be aligned with notation objects other
-than bar lines.  These objects include @code{ambitus},
+@cindex align to objects
+@cindex break-align-symbols
+
+Rehearsal marks and bar numbers may be aligned with notation
+objects other than bar lines.  These objects include @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}.
 
 @code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
 @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
 @code{time-signature}.
 

-By default, rehearsal marks will be horizontally centered above the
-object:
+By default, rehearsal marks and bar numbers will be horizontally
+centered above the object:

 
 @lilypond[verbatim,quote,relative=1]
 e1
 
 @lilypond[verbatim,quote,relative=1]
 e1


@@ -2957,6 +3132,32 @@ e
 e2.
 @end lilypond
 
 e2.
 @end lilypond
 

+A list of possible target alignment objects may be specified.  If
+some of the objects are invisible at that point due to the setting
+of @code{break-visibility} or the explicit visibility settings for
+keys and clefs, the rehearsal mark or bar number is aligned to the
+first object in the list which is visible.  If no objects in the
+list are visible the object is aligned to the bar line.  If the bar
+line is invisible the object is aligned to the place where the bar
+line would be.
+
+@lilypond[verbatim,quote,relative=1]
+e1
+% the RehearsalMark will be centered above the Key Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e
+% the RehearsalMark will be centered above the Clef
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \minor
+\clef bass
+\mark "↓"
+e,
+@end lilypond
+

 The alignment of the rehearsal mark relative to the notation object
 can be changed, as shown in the following example.  In a score with
 multiple staves, this setting should be done for all the staves.
 The alignment of the rehearsal mark relative to the notation object
 can be changed, as shown in the following example.  In a score with
 multiple staves, this setting should be done for all the staves.


@@ -3001,7 +3202,6 @@ e
 @end lilypond
 
 
 @end lilypond
 
 

-

 @node Vertical grouping of grobs
 @subsection Vertical grouping of grobs
 
 @node Vertical grouping of grobs
 @subsection Vertical grouping of grobs
 


@@ -3081,6 +3281,11 @@ Notation Reference:
 @node Modifying ties and slurs
 @unnumberedsubsubsec Modifying ties and slurs
 
 @node Modifying ties and slurs
 @unnumberedsubsubsec Modifying ties and slurs
 

+@cindex slurs, modifying
+@cindex ties, modifying
+@cindex Bézier curves
+@cindex Bézier control points
+

 Ties, slurs and phrasing slurs are drawn as third-order Bézier
 curves.  If the shape of the tie or slur which is calculated
 automatically is not optimum, the shape may be modified manually by
 Ties, slurs and phrasing slurs are drawn as third-order Bézier
 curves.  If the shape of the tie or slur which is calculated
 automatically is not optimum, the shape may be modified manually by


@@ -3129,13 +3334,16 @@ scaling can be achieved by applying the same transformation to the
 curve's control points.
 
 For the example above the following override gives a satisfactory
 curve's control points.
 
 For the example above the following override gives a satisfactory

-tie:
+tie.  Note the placement -- it has to be immediately before the note
+to which the start of the tie (or slur) is attached.

 
 @lilypond[verbatim,quote,relative=1]
 <<
 
 @lilypond[verbatim,quote,relative=1]
 <<

-  \once \override Tie
-    #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
-  { e1 ~ e1 }
+  {
+    \once \override Tie
+      #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
+     e1 ~ e1
+  }

 \\
   { r4 <g c,> <g c,> <g c,>4  }
 >>
 \\
   { r4 <g c,> <g c,> <g c,>4  }
 >>