X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftweaks.itely;h=3b6a79ffe0af70ecd01df4433f566b83addac3b1;hb=7ba0a22641cb0c7f5949d66a06d1e2e1fd0b3033;hp=d79ba1289d5116c0c610ede6484c96e511cca742;hpb=7bd6884c300f1a032b5b9f2e0b9ffa5a7938244a;p=lilypond.git

diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely
index d79ba1289d..3b6a79ffe0 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.12.0"
+@c \version "2.13.36"
 
 @node Tweaking output
 @chapter Tweaking output
@@ -562,7 +562,7 @@ should find
      Line thickness, generally measured in @code{line-thickness}
 @end example
 
-This looks a good bet to change the heaviness. It tells us that
+This looks a good bet to change the heaviness.  It tells us that
 the value of @code{thickness} is a simple @emph{number},
 that the default value is 1.2, and that the units are
 in another property called @code{line-thickness}.
@@ -1632,7 +1632,7 @@ Then it sorts the outside-staff objects according to their
 @code{outside-staff-priority}.  The outside-staff objects are
 taken one by one, beginning with the object with the lowest
 @code{outside-staff-priority}, and placed so that they do not
-collide with any objects that have already been placed. That is,
+collide with any objects that have already been placed.  That is,
 if two outside-staff grobs are competing for the same space, the
 one with the lower @code{outside-staff-priority} will be placed
 closer to the staff.  If two objects have the same
@@ -2033,7 +2033,7 @@ It also shows how ottava brackets are created.
 @cindex rehearsal marks, tweaking placement
 
 Note that bar numbers, metronome marks and rehearsal marks are not
-shown. By default these are created in the @code{Score} context and
+shown.  By default these are created in the @code{Score} context and
 their @code{outside-staff-priority} is ignored relative to the layout
 objects which are created in the @code{Staff} context.  If you wish to
 place bar numbers, metronome marks or rehearsal marks in accordance
@@ -2370,11 +2370,9 @@ This has already been covered in some detail -- see
 @ref{Within-staff objects}.
 
 @item
-@code{padding}, @code{left-padding},
-@code{right-padding}, @code{staff-padding}
+@code{padding}, @code{right-padding}, @code{staff-padding}
 
 @cindex padding
-@cindex left-padding property
 @cindex padding property
 @cindex right-padding property
 @cindex staff-padding property
@@ -2389,15 +2387,14 @@ applied to all objects which support the
 @code{side-position-interface}.
 
 Instead of @code{padding}, the placement of groups of accidentals
-is controlled by @code{left-padding} and @code{right-padding}.
-These properties are to be found in the @code{AccidentalPlacement}
-object which, note, lives in the @strong{staff} context.  In the
-type-setting process the note heads are type-set first and then
-the accidentals, if any, are added to the left of the note heads
-using the @code{right-padding} property to determine the separation
-from the note heads. So only the @code{right-padding} property of the
-@code{AccidentalPlacement} object has any effect on the placement
-of the accidentals.
+is controlled by @code{right-padding}.  This property is to be found
+in the @code{AccidentalPlacement} object which, note, lives in the
+@strong{Staff} context.  In the typesetting process the note heads
+are typeset first and then the accidentals, if any, are added to the
+left of the note heads using the @code{right-padding} property to determine
+the separation from the note heads and between individual accidentals.
+So only the @code{right-padding} property of the @code{AccidentalPlacement}
+object has any effect on the placement of the accidentals.
 
 The @code{staff-padding} property is closely related to the
 @code{padding} property: @code{padding} controls the minimum amount of
@@ -2521,7 +2518,7 @@ affecting anything else.
 @cindex positions property
 
 This is most useful for manually adjusting the slope and height
-of beams, slurs, and tuplets.   It takes a pair of numbers
+of beams, slurs, and tuplets.  It takes a pair of numbers
 giving the position of the left and right ends of the beam, slur,
 etc. relative to the center line of the staff.  Units are
 staff-spaces.  Note, though, that slurs and phrasing slurs cannot
@@ -2589,11 +2586,11 @@ b2\fermata
 @lilypond[quote,fragment,relative=1,verbatim]
 % This will not work, see below
 \override MetronomeMark #'padding = #3
-\tempo 4=120
+\tempo 4 = 120
 c1 |
 % This works
 \override Score.MetronomeMark #'padding = #3
-\tempo 4=80
+\tempo 4 = 80
 d1 |
 @end lilypond
 
@@ -2609,9 +2606,8 @@ their @code{outside-staff-priority}, then that object and all
 objects outside it are moved.
 
 
-@subheading left-padding and right-padding
+@subheading right-padding
 
-@cindex left-padding property
 @cindex right-padding property
 
 The @code{right-padding} property affects the spacing between the
@@ -2908,7 +2904,7 @@ We end this section on Tweaks by showing the steps to be taken to
 deal with a tricky example which needs several tweaks to produce
 the desired output.  The example has been deliberately chosen to
 illustrate the use of the Notation Reference to resolve unusual
-problems with notation.  It is not representative of more usual
+problems with notation.  It is not representative of the more usual
 engraving process, so please do not let these difficulties put
 you off!  Fortunately, difficulties like these are not very common!
 
@@ -2921,38 +2917,46 @@ dynamics, fingering and pedalling.
 @c The following should appear as music without code
 @c This example should not be indexed
 @c line-width ensures no break
-@lilypond[quote,ragged-right,line-width=5.5\in]
+@lilypond[quote,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4.\( g8 |
-  \once \override Tie #'staff-position = #3.5
-  bes1~ |
-  \bar "||"
-  \time 6/4
-  \mergeDifferentlyHeadedOn
-  \mergeDifferentlyDottedOn
-  bes2.^\markup { \bold "Moderato" } r8
-  <<
-    { c,8 d fis bes a }
-  \\
-    {
-      % Reposition the c2 to the right of the merged note
-      c,8~ \once \override NoteColumn #'force-hshift = #1.0
-      % Move the c2 out of the main note column so the merge will work
-      \shiftOnn c2
-    }
-  \\
-    {
-      % Stem on the d2 must be down to permit merging
-      s8 \stemDown
-      \once \override Stem #'transparent = ##t
-      d2
-    }
-  \\
-    { s4 fis4. }
-  >> |
-  \mergeDifferentlyHeadedOff
-  \mergeDifferentlyDottedOff
-  g2.\)
+  \new Voice {
+    r2 c4.\( g8 |
+    \once \override Tie #'staff-position = #3.5
+    bes1~ |
+    \bar "||"
+    \time 6/4
+    \mergeDifferentlyHeadedOn
+    \mergeDifferentlyDottedOn
+    bes2.^\markup { \bold "Moderato" } r8
+    <<
+      { c,8 d fis bes a }
+      \new Voice {
+        \voiceTwo
+        c,8~
+        % Reposition the c2 to the right of the merged note
+        \once \override NoteColumn #'force-hshift = #1.0
+        % Move the c2 out of the main note column so the merge will work
+        \shiftOnn
+        c2
+      }
+      \new Voice {
+        \voiceThree
+        s8
+        % Stem on the d2 must be down to permit merging
+        \stemDown
+        % Stem on the d2 should be invisible
+        \once \override Stem #'transparent = ##t
+        d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    \mergeDifferentlyHeadedOff
+    \mergeDifferentlyDottedOff
+    g2.\)
+  }
 }
 
 lhMusic = \relative c' {
@@ -2982,31 +2986,44 @@ requires four voices.  These are the five beamed eighth notes,
 the tied C, the half-note D which is merged with the eighth note
 D, and the dotted quarter note F-sharp, which is also merged with
 the eighth note at the same pitch.  Everything else is in a single
-voice, so the easiest way is to introduce these four voices
+voice, so the easiest way is to introduce these extra three voices
 temporarily at the time they are needed.  If you have forgotten
-how to do this, look at @ref{I'm hearing Voices}.  Let us begin
-by entering the notes as two variables and setting up the staff
-structure in a score block, and see what LilyPond produces by
-default:
+how to do this, look at @ref{I'm hearing Voices} and @ref{Explicitly
+instantiating voices}.  Here we choose to use explicitly instantiated
+voices for the polyphonic passage, as LilyPond is better able to
+avoid collisions if all voices are instantiated explicitly in this
+way.
+
+So let us begin by entering the notes as two variables, setting up
+the staff structure in a score block, and seeing what LilyPond
+produces by default:
 
 @c line-width ensures no break
-@lilypond[quote,verbatim,ragged-right,line-width=5.5\in]
+@lilypond[quote,verbatim,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4. g8 |
-  bes1~ |
-  \time 6/4
-  bes2. r8
-  % Start polyphonic section of four voices
-  <<
-    { c,8 d fis bes a }
-  \\
-    { c,8~ c2 }
-  \\
-    { s8 d2 }
-  \\
-    { s4 fis4. }
-  >> |
-  g2. |
+  \new Voice {
+    r2 c4. g8 |
+    bes1~ |
+    \time 6/4
+    bes2. r8
+    % Start polyphonic section of four voices
+    <<
+      { c,8 d fis bes a }  % continuation of main voice
+      \new Voice {
+        \voiceTwo
+        c,8~ c2
+      }
+      \new Voice {
+        \voiceThree
+        s8 d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    g2.  % continuation of main voice
+  }
 }
 
 lhMusic = \relative c' {
@@ -3032,30 +3049,38 @@ lhMusic = \relative c' {
 @end lilypond
 
 All the notes are right, but the appearance is far from
-satisfactory.  The tie clashes with the change in time signature,
-the notes are not merged together, and several notation elements
+satisfactory.  The tie collides with the change in time signature,
+some notes are not merged together, and several notation elements
 are missing.  Let's first deal with the easier things.  We can
 easily add the left hand slur and the right hand phrasing slur,
 since these were all covered in the Tutorial.  Doing this gives:
 
 @c line-width ensures no break
-@lilypond[quote,verbatim,ragged-right,line-width=5.5\in]
+@lilypond[quote,verbatim,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4.\( g8 |
-  bes1~ |
-  \time 6/4
-  bes2. r8
-  % Start polyphonic section of four voices
-  <<
-    { c,8 d fis bes a }
-  \\
-    { c,8~ c2 }
-  \\
-    { s8 d2 }
-  \\
-    { s4 fis4. }
-  >> |
-  g2.\) |
+  \new Voice {
+    r2 c4.\( g8 |
+    bes1~ |
+    \time 6/4
+    bes2. r8
+    % Start polyphonic section of four voices
+    <<
+      { c,8 d fis bes a }  % continuation of main voice
+      \new Voice {
+        \voiceTwo
+        c,8~ c2
+      }
+      \new Voice {
+        \voiceThree
+        s8 d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    g2.\)  % continuation of main voice
+  }
 }
 
 lhMusic = \relative c' {
@@ -3090,8 +3115,8 @@ produced by the @code{\bar "||"} command.  That's easily done.  We
 next need to correct the collision of the tie with the time signature.
 This is best done by moving the tie upwards.  Moving objects was
 covered earlier in @ref{Moving objects}, which says that objects
-positioned relative to the staff can be moved by overriding their
-@code{staff-position} property, which is specified in half staff
+positioned relative to the staff can be moved vertically by overriding
+their @code{staff-position} property, which is specified in half staff
 spaces relative to the center line of the staff.  So the following
 override placed just before the first tied note would move the tie up
 to 3.5 half staff spaces above the center line:
@@ -3101,25 +3126,33 @@ to 3.5 half staff spaces above the center line:
 This completes bar two, giving:
 
 @c line-width ensures no break
-@lilypond[quote,verbatim,ragged-right,line-width=5.5\in]
+@lilypond[quote,verbatim,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4.\( g8 |
-  \once \override Tie #'staff-position = #3.5
-  bes1~ |
-  \bar "||"
-  \time 6/4
-  bes2. r8
-  % Start polyphonic section of four voices
-  <<
-    { c,8 d fis bes a }
-  \\
-    { c,8~ c2 }
-  \\
-    { s8 d2 }
-  \\
-    { s4 fis4. }
-  >> |
-  g2.\) |
+  \new Voice {
+    r2 c4.\( g8 |
+    \once \override Tie #'staff-position = #3.5
+    bes1~ |
+    \bar "||"
+    \time 6/4
+    bes2. r8
+    % Start polyphonic section of four voices
+    <<
+      { c,8 d fis bes a }  % continuation of main voice
+      \new Voice {
+        \voiceTwo
+        c,8~ c2
+      }
+      \new Voice {
+        \voiceThree
+        s8 d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    g2.\)  % continuation of main voice
+  }
 }
 
 lhMusic = \relative c' {
@@ -3145,15 +3178,15 @@ lhMusic = \relative c' {
 @end lilypond
 
 On to bar three and the start of the Moderato section.  The tutorial
-showed how to add embolded text with the @code{\markup} command, so
-adding @q{Moderato} in bold is easy.  But how do we merge notes in
+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
 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
-differently headed and differently dotted notes in @ruser{Collision
-resolution}.  In our example we need to merge both types of note for
-the duration of the polyphonic section in bar 3, so using the
-information we find in the Notation Reference we add
+differently headed and differently dotted notes in
+@ruser{Collision resolution}.  In our example we need to merge both
+types of note for the duration of the polyphonic section in bar 3,
+so using the information we find in the Notation Reference we add
 
 @example
 \mergeDifferentlyHeadedOn
@@ -3172,29 +3205,37 @@ to the start of that section and
 to the end, giving:
 
 @c line-width ensures no break
-@lilypond[quote,ragged-right,line-width=5.5\in]
+@lilypond[quote,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4.\( g8 |
-  \once \override Tie #'staff-position = #3.5
-  bes1~ |
-  \bar "||"
-  \time 6/4
-  bes2.^\markup { \bold "Moderato" } r8
-  \mergeDifferentlyHeadedOn
-  \mergeDifferentlyDottedOn
-  % Start polyphonic section of four voices
-  <<
-    { c,8 d fis bes a }
-  \\
-    { c,8~ c2 }
-  \\
-    { s8 d2 }
-  \\
-    { s4 fis4. }
-  >> |
-  \mergeDifferentlyHeadedOff
-  \mergeDifferentlyDottedOff
-  g2.\) |
+  \new Voice {
+    r2 c4.\( g8 |
+    \once \override Tie #'staff-position = #3.5
+    bes1~ |
+    \bar "||"
+    \time 6/4
+    bes2.^\markup { \bold "Moderato" } r8
+    \mergeDifferentlyHeadedOn
+    \mergeDifferentlyDottedOn
+    % Start polyphonic section of four voices
+    <<
+      { c,8 d fis bes a }  % continuation of main voice
+      \new Voice {
+        \voiceTwo
+        c,8~ c2
+      }
+      \new Voice {
+        \voiceThree
+        s8 d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    \mergeDifferentlyHeadedOff
+    \mergeDifferentlyDottedOff
+    g2.\)  % continuation of main voice
+  }
 }
 
 lhMusic = \relative c' {
@@ -3238,35 +3279,39 @@ Applying these changes gives:
 @cindex staff-position property, example
 
 @c line-width ensures no break
-@lilypond[quote,verbatim,ragged-right,line-width=5.5\in]
+@lilypond[quote,verbatim,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4.\( g8 |
-  \once \override Tie #'staff-position = #3.5
-  bes1~ |
-  \bar "||"
-  \time 6/4
-  bes2.^\markup { \bold "Moderato" } r8
-  \mergeDifferentlyHeadedOn
-  \mergeDifferentlyDottedOn
-  % Start polyphonic section of four voices
-  <<
-    { c,8 d fis bes a }
-  \\
-    {
-      % Move the c2 out of the main note column so the merge will work
-      c,8~ \shiftOnn c2
-    }
-  \\
-    {
-      % Stem on the d2 must be down to permit merging
-      s8 \stemDown d2
-    }
-  \\
-    { s4 fis4. }
-  >> |
-  \mergeDifferentlyHeadedOff
-  \mergeDifferentlyDottedOff
-  g2.\) |
+  \new Voice {
+    r2 c4.\( g8 |
+    \once \override Tie #'staff-position = #3.5
+    bes1~ |
+    \bar "||"
+    \time 6/4
+    bes2.^\markup { \bold "Moderato" } r8
+    \mergeDifferentlyHeadedOn
+    \mergeDifferentlyDottedOn
+    % Start polyphonic section of four voices
+    <<
+      { c,8 d fis bes a }  % continuation of main voice
+      \new Voice {
+        \voiceTwo
+        % Move the c2 out of the main note column so the merge will work
+        c,8~ \shiftOnn c2
+      }
+      \new Voice {
+        \voiceThree
+        % Stem on the d2 must be down to permit merging
+        s8 \stemDown d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    \mergeDifferentlyHeadedOff
+    \mergeDifferentlyDottedOff
+    g2.\)  % continuation of main voice
+  }
 }
 
 lhMusic = \relative c' {
@@ -3303,38 +3348,47 @@ the @code{force-hshift} property.  Here's the final result:
 @cindex transparent property, example
 
 @c line-width ensures no break
-@lilypond[quote,verbatim,ragged-right,line-width=5.5\in]
+@lilypond[quote,verbatim,ragged-right,line-width=6\in]
 rhMusic = \relative c'' {
-  r2 c4.\( g8 |
-  \once \override Tie #'staff-position = #3.5
-  bes1~ |
-  \bar "||"
-  \time 6/4
-  bes2.^\markup { \bold "Moderato" } r8
-  \mergeDifferentlyHeadedOn
-  \mergeDifferentlyDottedOn
-  <<
-    { c,8 d fis bes a }
-  \\
-    {
-      % Reposition the c2 to the right of the merged note
-      c,8~ \once \override NoteColumn #'force-hshift = #1.0
-      % Move the c2 out of the main note column so the merge will work
-      \shiftOnn c2
-    }
-  \\
-    {
-      % Stem on the d2 must be down to permit merging
-      s8 \stemDown
-      \once \override Stem #'transparent = ##t
-      d2
-    }
-  \\
-    { s4 fis4. }
-  >> |
-  \mergeDifferentlyHeadedOff
-  \mergeDifferentlyDottedOff
-  g2.\) |
+  \new Voice {
+    r2 c4.\( g8 |
+    \once \override Tie #'staff-position = #3.5
+    bes1~ |
+    \bar "||"
+    \time 6/4
+    bes2.^\markup { \bold "Moderato" } r8
+    \mergeDifferentlyHeadedOn
+    \mergeDifferentlyDottedOn
+    % Start polyphonic section of four voices
+    <<
+      { c,8 d fis bes a }  % continuation of main voice
+      \new Voice {
+        \voiceTwo
+        c,8~
+        % Reposition the c2 to the right of the merged note
+        \once \override NoteColumn #'force-hshift = #1.0
+        % Move the c2 out of the main note column so the merge will work
+        \shiftOnn
+        c2
+      }
+      \new Voice {
+        \voiceThree
+        s8
+        % Stem on the d2 must be down to permit merging
+        \stemDown
+        % Stem on the d2 should be invisible
+        \once \override Stem #'transparent = ##t
+        d2
+      }
+      \new Voice {
+        \voiceFour
+        s4 fis4.
+      }
+    >> |
+    \mergeDifferentlyHeadedOff
+    \mergeDifferentlyDottedOff
+    g2.\)  % continuation of main voice
+  }
 }
 
 lhMusic = \relative c' {
@@ -3502,6 +3556,10 @@ required, but the transparent metronome mark in the first line
 forces the following tempo indication too high while the
 second (with the stencil removed) does not.
 
+@seealso
+Music Glossary:
+@rglos{system}.
+
 @node Using variables for tweaks
 @subsection Using variables for tweaks
 
@@ -3666,10 +3724,10 @@ inst =
 @end example
 
 We will refer to this file using the @code{\include} command near
-the top of the music file. (The extension @code{.ily} is used to
+the top of the music file.  (The extension @file{.ily} is used to
 distinguish this included file, which is not meant to be compiled
 on its own, from the main file.)
-Now let's modify our music (let's save this file as @file{"music.ly"}).
+Now let's modify our music (let's save this file as @file{music.ly}).
 
 @c  We have to do this awkward example/lilypond-non-verbatim
 @c  because we can't do the \include stuff in the manual.
@@ -4016,7 +4074,7 @@ The following are the most useful files to be found in
 @end multitable
 
 Other settings (such as the definitions of markup commands) are
-stored as @code{.scm} (Scheme) files.  The Scheme programming
+stored as @file{.scm} (Scheme) files.  The Scheme programming
 language is used to provide a programmable interface into
 LilyPond internal operation.  Further explanation of these files
 is currently outside the scope of this manual, as a knowledge of
@@ -4060,16 +4118,20 @@ compress that line of the score just enough to fit within the
 margins.
 
 To be effective under all circumstances these checks must be enabled
-by placing the overrides in a Score @code{\with} block, rather than
-in-line in music, as follows:
+by placing the overrides using @code{\context} within a @code{\layout}
+block, rather than in-line in music, as follows:
 
 @example
-\new Score \with @{
-  % Makes sure text scripts and lyrics are within the paper margins
-  \override PaperColumn #'keep-inside-line = ##t
-  \override NonMusicalPaperColumn #'keep-inside-line = ##t
-@} @{
-   ..
+\score @{
+  @{ @dots{}notes@dots{} @}
+  \layout @{
+    \context @{
+      \Score
+      % Makes sure text scripts and lyrics are within the paper margins
+      \override PaperColumn #'keep-inside-line = ##t
+      \override NonMusicalPaperColumn #'keep-inside-line = ##t
+    @}
+  @}
 @}
 @end example