Issue 5127: Implement extra-offset for system positioning

Add the property 'extra-offset to 'line-break-system-details.

It is possible to position systems absolutely using the
properties 'X-offset and 'Y-offset of 'line-break-system-details.
Placement using 'Y-offset, in particular, often requires
considerable trial and error, since it is reckoned from the top
of the usable space.

To remedy this, an 'extra-offset property allows easy movement of
systems relative to where they currently are on the page--whether
there through default or absolute positioning.

This property supports displacements in both axes, though
movement in the Y direction is more generally useful.

System separators will be properly positioned. (Thanks go to Thomas
Morley.)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index b9782edbb85486b12fc6cc9575408c4564771b0f..77ddfb2b74873ef7715da9a5bbc374f1236a00d3 100644 (file)
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -61,6 +61,15 @@ which scares away people.
 
 @end ignore
 
+@item
+It is now possible to move systems with reference to their current
+position using the @code{extra-offset} subproperty of
+@code{NonMusicalPaperColumn.line-break-system-details}.  Both vertical
+and horizontal changes are possible.  This feature is especially useful
+for making slight adjustments to the default vertical position of
+individual systems. See @ruser{Explicit staff and system positioning} for
+more information.
+
 @item
 It is now possible to add text to analysis brackets through the
 @code{HorizontalBracketText} object.

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index fb455c1fdd55f52c4e03459eef336c44f0a6f2e5..daf43ec540aec955bf7cfa3d5a5b5bef0ebcb2a1 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -2440,11 +2440,12 @@ padding, @code{NonMusicalPaperColumn.line-break-system-details}
 can specify exact vertical positions on the page.
 
 @code{NonMusicalPaperColumn.line-break-system-details} accepts
-an associative list of three different settings:
+an associative list of four different settings:
 
 @itemize
 @item @code{X-offset}
 @item @code{Y-offset}
+@item @code{extra-offset}
 @item @code{alignment-distances}
 @end itemize
 
@@ -2557,6 +2558,41 @@ potentially many values, but that we set only one value here.  Note,
 too, that the @code{Y-offset} property here determines the exact vertical
 position on the page at which each new system will render.
 
+In contrast to the absolute positioning available through
+@code{Y-offset} and @code{X-offset}, relative positioning is possible
+with the @code{extra-offset} property of
+@code{line-break-system-details}.  Placement is relative to the
+default layout or to the absolute positioning created by setting
+@code{X-offset} and @code{Y-offset}.  The property @code{extra-offset}
+accepts a @code{pair} consisting of displacements along the X-axis and
+Y-axis.
+
+@lilypond[verbatim,quote,staffsize=16]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          s1*5 \break
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((extra-offset . (0 . 10)))
+          s1*5 \break
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((extra-offset . (0 . 10)))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
+  }
+}
+@end lilypond
+
 Now that we have set the vertical startpoint of each system
 explicitly, we can also set the vertical distances between staves
 within each system manually.  We do this using the @code{alignment-distances}
@@ -2642,9 +2678,10 @@ Some points to consider:
 do not count as a staff.
 
 @item The units of the numbers passed to @code{X-offset},
-@code{Y-offset} and @code{alignment-distances} are interpreted as multiples
-of the distance between adjacent staff lines.  Positive values move staves
-and lyrics up, negative values move staves and lyrics down.
+@code{Y-offset}, @code{extra-offset} and @code{alignment-distances} are
+interpreted as multiples of the distance between adjacent staff lines.
+Positive values move staves and lyrics up, negative values move staves
+and lyrics down.
 
 @item Because the @code{NonMusicalPaperColumn.line-break-system-details}
 settings given here allow the positioning of staves and systems anywhere

diff --git a/input/regression/page-layout-extra-offset.ly b/input/regression/page-layout-extra-offset.ly
new file mode 100644 (file)
index 0000000..0e5cbbc
--- /dev/null
+++ b/input/regression/page-layout-extra-offset.ly
@@ -0,0 +1,45 @@
+\version "2.19.60"
+
+\header {
+  texidoc = "By setting @code{extra-offset} within the
+@code{line-break-system-details} of @code{NonMusicalPaperColumn},
+systems may be moved in relation either to their default position on the
+printable area of the page or the absolute position specified by
+@code{X-offset} or @code{Y-offset} within
+@code{line-break-system-details}."
+
+}
+
+#(set-default-paper-size "a6" 'portrait)
+
+\paper {
+  indent = 0.0
+  oddHeaderMarkup = "header"
+  oddFooterMarkup = "footer"
+  system-separator-markup = \slashSeparator
+  ragged-right = ##t
+}
+
+\book {
+  \score {
+    {
+      \overrideProperty
+      Score.NonMusicalPaperColumn.line-break-system-details
+      #'((extra-offset . (8.0 . 0.0)))
+      c1 c1 \break
+
+      \overrideProperty
+      Score.NonMusicalPaperColumn.line-break-system-details
+      #'((extra-offset . (12.0 . 8.0)))
+      c1 c1 \break
+
+      \overrideProperty
+      Score.NonMusicalPaperColumn.line-break-system-details
+      #'((X-offset . 8.0)
+         (Y-offset . 36.0)
+         (extra-offset . (-8.0 . 30.0))
+      )
+      c1 c1
+    }
+  }
+}

diff --git a/scm/page.scm b/scm/page.scm
index c6e69658cea45b8c1cfac5f770b7b9ce10c0a3e9..20e58b61e21c4bf0bcdac8a61318a15cebace630 100644 (file)
--- a/scm/page.scm
+++ b/scm/page.scm
@@ -227,7 +227,7 @@
                                                        system-separator-markup)
                                      #f))
 
-       (page-stencil (ly:make-stencil '()))
+       (page-stencil empty-stencil)
 
        (last-system #f)
        (last-y 0.0)
@@ -243,12 +243,14 @@
        (add-system
         (lambda (system)
           (let* ((stencil (paper-system-stencil system))
-                 (y (ly:prob-property system 'Y-offset 0))
+                 (extra-offset (ly:prob-property system 'extra-offset '(0 . 0)))
+                 (x (+ (ly:prob-property system 'X-offset 0.0)
+                       (car extra-offset)))
+                 (y (+ (ly:prob-property system 'Y-offset 0.0)
+                       (cdr extra-offset)))
                  (is-title (paper-system-title?
                             system)))
-            (add-to-page stencil
-                         (ly:prob-property system 'X-offset 0.0)
-                         y)
+            (add-to-page stencil x y)
             (if (and (ly:stencil? system-separator-stencil)
                      last-system
                      (not (paper-system-title? system))