X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftweaks.itely;h=160c0e390114e773964043530e9f7d29e1699d87;hb=b512137cb2a89c9b5f880fc089221805491c9bdf;hp=5ee640a9b98d8b2d15e30b514b79399434136ee7;hpb=25ca54b640c067e2286a1d7ba47f24a1b4dc070e;p=lilypond.git

diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely
index 5ee640a9b9..160c0e3901 100644
--- a/Documentation/learning/tweaks.itely
+++ b/Documentation/learning/tweaks.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.20"
+@c \version "2.19.2"
 
 @node Tweaking output
 @chapter Tweaking output
@@ -107,6 +107,14 @@ ending point, and maybe other properties concerned with their
 shape.  Objects with an extended shape like these are called
 @q{Spanners}.
 
+What is more, there are @q{abstract} grobs which do not print
+anything of their own, but rather collect, position and manage
+other grobs.  Common examples for this are
+@code{DynamicLineSpanner}, @code{BreakAlignment},
+@code{NoteColumn}, @code{VerticalAxisGroup},
+@code{NonMusicalPaperColumn} and similar.  We will see how some of
+these are used later.
+
 It remains to explain what @q{Interfaces} are.  Many objects, even
 though they are quite different, share common features which need to
 be processed in the same way.  For example, all grobs have a color, a
@@ -450,7 +458,7 @@ the original event:
 This long form of the @code{\tweak} command can be described as
 
 @example
-\tweak @var{layout-object}.@var{layout-property} @var{value}
+\tweak @var{LayoutObject}.@var{layout-property} #@var{value}
 @end example
 
 @cindex tuplets, nested
@@ -2765,27 +2773,58 @@ of the staff in half staff-spaces.  It is useful in resolving
 collisions between layout objects like multi-measure rests, ties
 and notes in different voices.
 
+@item
+@code{horizontal-shift}
+
+@cindex horizontal-shift property
+@cindex note column
+@cindex note collisions
+@cindex collisions, notes
+@cindex shift commands
+@funindex \shiftOff
+@funindex shiftOff
+@funindex \shiftOn
+@funindex shiftOn
+@funindex \shiftOnn
+@funindex shiftOnn
+@funindex \shiftOnnn
+@funindex shiftOnnn
+
+Within a voice, all the notes occuring at the same musical moment are
+grouped into a note column, and a @code{NoteColumn} object is created
+to control the horizontal positioning of that group of notes (see
+@qq{Note columns} in @ref{Explicitly instantiating voices}).  If
+@emph{and only if} two or more note columns within a single Staff
+context, both with stems in the same direction, occur at the same
+musical moment, the values of their @code{horizontal-shift} properties
+are used to rank them and the columns in the higher ranks are
+progessively offset to avoid collisions of the noteheads.  This
+property is set by the @code{\voiceXXX} commands and may be overridden
+directly with an @code{\override} command or, more usually, by the
+@code{\shiftOn} commands.  Note that this property is used to
+@emph{rank} the note columns for off-setting - it does not specify the
+magnitude of the offset, which is progressively increased in steps
+based on the note head's width for each rank.  The steps are usually
+of half a note head's width, but may be a full note head's width when
+a closely spaced group of notes is involved.
+
 @item
 @code{force-hshift}
 
 @cindex force-hshift property
 
-Closely spaced notes in a chord, or notes occurring at the same
-time in different voices, are arranged in two, occasionally more,
-columns to prevent the note heads overlapping.  These are called
-note columns, and an object called @code{NoteColumn} is created
-to lay out the notes in that column.
-
 The @code{force-hshift} property is a property of a @code{NoteColumn}
 (actually of the @code{note-column-interface}).  Changing it permits a
-note column to be moved in units appropriate to a note column,
-viz. the note head width of the first voice note.  It should be used
-in complex situations where the normal @code{\shiftOn} commands (see
+note column to be moved in situations where the note columns overlap.
+Note that it has no effect on note columns that do not overlap.
+It is specified in units appropriate to a note column, viz. the note
+head width of the first voice note.  It should be used in complex
+situations where the normal @code{\shiftOn} commands (see
 @ref{Explicitly instantiating voices}) do not resolve the note
-conflict.  It is preferable to the @code{extra-offset} property for
-this purpose as there is no need to work out the distance in
-staff-spaces, and moving the notes into or out of a @code{NoteColumn}
-affects other actions such as merging note heads.
+conflict satisfactorily.  It is preferable to the @code{extra-offset}
+property for this purpose as there is no need to work out the distance
+in staff-spaces, and moving the notes into or out of a
+@code{NoteColumn} affects other actions such as merging note heads.
 
 @end itemize
 
@@ -3119,12 +3158,12 @@ collide with the ties:
 {
   \time 4/2
   <<
-    { c'1 ~ c'2. e'8 f' }
+    { c'1 ~ 2. e'8 f' }
     \\
     { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
   >>
   <<
-    { c'1 ~ c'2. e'8 f' }
+    { c'1 ~ 2. e'8 f' }
     \\
     { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
   >>
@@ -3143,7 +3182,7 @@ say, 1:
 {
   \time 4/2
   <<
-    { c'1 ~ c'2. e'8 f' }
+    { c'1 ~ 2. e'8 f' }
     \\
     {
       \override Beam.positions = #'(-1 . -1)
@@ -3151,7 +3190,7 @@ say, 1:
     }
   >>
   <<
-    { c'1 ~ c'2. e'8 f' }
+    { c'1 ~ 2. e'8 f' }
     \\
     { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
   >>
@@ -3188,14 +3227,20 @@ was left looking like this:
 @noindent
 The inner note of the first chord (i.e. the A-flat in the fourth
 Voice) need not be shifted away from the note column of the higher
-note.  To correct this we set @code{force-hshift}, which is a property
-of @code{NoteColumn}, of this note to zero.
-
-In the second chord we prefer the F to line up with the A-flat and the
-lowest note to be positioned slightly right to avoid a collision of
-stems.  We achieve this by setting @code{force-hshift} in the
+note.  We might expect to correct this by using @code{\shiftOff}, but
+this will cause warnings about clashing note columns.  Instead, we
+set @code{force-hshift}, which is a property of @code{NoteColumn},
+of this note to zero.
+
+In the second chord we prefer the F to line up with the A-flat and
+the lowest note to be positioned slightly right to avoid a collision
+of stems.  We achieve this by setting @code{force-hshift} in the
 @code{NoteColumn} of the low D-flat to move it to the right by half
-a staff-space.
+a staff-space, and setting @code{force-hshift} for the F to zero.
+Note that we use @code{\once} to avoid the settings propagating
+beyond the immediate musical moment, although in this small example
+the @code{\once} and the second @code{\override} in Voice four could
+be omitted.  This would not be good practice.
 
 Here's the final result:
 
@@ -3208,17 +3253,11 @@ Here's the final result:
   <<
     { c2 aes4. bes8 }
     \\
-    {
-      <ees, c>2
-      \once \override NoteColumn.force-hshift = #0.5
-      des2
-    }
+    { <ees, c>2 \once \override NoteColumn.force-hshift = 0.5 des }
     \\
     \\
-    {
-      \override NoteColumn.force-hshift = #0
-      aes'2 f4 fes
-    }
+    { \once \override NoteColumn.force-hshift = 0 aes'2
+      \once \override NoteColumn.force-hshift = 0 f4 fes }
   >> |
   <c ees aes c>1 |
 }
@@ -3255,7 +3294,7 @@ rhMusic = \relative c'' {
     \time 6/4
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     <<
       { c,8 d fis bes a }
       \new Voice {
@@ -3340,7 +3379,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3397,7 +3436,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3469,7 +3508,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3507,8 +3546,8 @@ lhMusic = \relative c' {
 @end lilypond
 
 On to bar three and the start of the Moderato section.  The tutorial
-showed how to add bold text with the @code{\markup} command, so
-adding @qq{Moderato} in bold is easy.  But how do we merge notes in
+showed how to add a tempo indication with the @code{\tempo} command, so
+adding @qq{Moderato} is easy.  But how do we merge notes in
 different voices together?  This is where we need to turn again to
 the Notation Reference for help.  A search for @qq{merge} in the
 Notation Reference index quickly leads us to the commands for merging
@@ -3542,7 +3581,7 @@ rhMusic = \relative c'' {
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3550,7 +3589,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3616,7 +3655,7 @@ rhMusic = \relative c'' {
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3686,7 +3725,7 @@ rhMusic = \relative c'' {
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3784,7 +3823,7 @@ same voice can be connected with ties.  By using two voices,
 with the tied notes in one of them
 
 @lilypond[quote,fragment,relative=2]
-<< { b8~ b\noBeam } \\ { b8[ g] } >>
+<< { b8~ 8\noBeam } \\ { b8[ g] } >>
 @end lilypond
 
 @noindent
@@ -3798,7 +3837,7 @@ cross voices:
 <<
   {
     \tweak Stem.transparent ##t
-    b8~ b\noBeam
+    b8~ 8\noBeam
   }
 \\
   { b8[ g] }
@@ -3814,7 +3853,7 @@ too much, we can lengthen the stem by setting the
   {
     \tweak Stem.transparent ##t
     \tweak Stem.length #8
-    b8~ b\noBeam
+    b8~ 8\noBeam
   }
 \\
   { b8[ g] }
@@ -3836,7 +3875,7 @@ possible to rewrite the above example as
     \single \hide Stem
     \single \hide Flag
     \tweak Stem.length #8
-    b8~ b\noBeam
+    b8~ 8\noBeam
   }
 \\
   { b8[ g] }