Issue 2924: Doc: \startMeasureCount and \stopMeasureCount needs documenting

The following patch is a preliminary step towards documenting the
Measure_counter_engraver added in version 2.17.7.  The patch consists of
two snippets, the first illustrating basic usage, and the second demonstrating
a workaround for creating centered bar numbers.

diff --git a/Documentation/snippets/centered-measure-numbers.ly b/Documentation/snippets/centered-measure-numbers.ly
new file mode 100644 (file)
index 0000000..490fde1
--- /dev/null
+++ b/Documentation/snippets/centered-measure-numbers.ly
@@ -0,0 +1,56 @@
+% DO NOT EDIT this file manually; it is automatically
+% generated from Documentation/snippets/new
+% Make any changes in Documentation/snippets/new/
+% and then run scripts/auxiliar/makelsr.py
+%
+% This file is in the public domain.
+%% Note: this file works from version 2.17.7
+\version "2.17.7"
+
+\header {
+  lsrtags = "contexts-and-engravers, repeats, staff-notation"
+
+  texidoc = "
+Scores of large ensemble works often have bar numbers placed beneath the
+system, centered horizontally on the measure's extent.  This snippet shows
+how the @code{Measure_counter_engraver} may be used to simulate this
+notational practice.  Here, the engraver has been added to a @code{Dynamics}
+context.
+
+"
+
+  doctitle = "Centered measure numbers"
+} % begin verbatim
+
+
+\layout {
+  \context {
+    \Dynamics
+    \consists #Measure_counter_engraver
+    \override MeasureCounter.direction = #DOWN
+    \override MeasureCounter.font-encoding = #'latin1
+    \override MeasureCounter.font-shape = #'italic
+    % to control the distance of the Dynamics context from the staff:
+    \override VerticalAxisGroup.nonstaff-relatedstaff-spacing.padding = #2
+  }
+  \context {
+    \Score
+    \remove "Bar_number_engraver"
+  }
+}
+
+pattern = \repeat unfold 7 { c'4 d' e' f' }
+
+\new StaffGroup <<
+  \new Staff {
+    \pattern
+  }
+  \new Staff {
+    \pattern
+  }
+  \new Dynamics {
+    \startMeasureCount
+    s1*7
+    \stopMeasureCount
+  }
+>>

diff --git a/Documentation/snippets/contexts-and-engravers.snippet-list b/Documentation/snippets/contexts-and-engravers.snippet-list
index 10ce65167de539119b9dd3a07066ae9c0a797029..87e008eeef3fce6e19238147a244e36e65df13f0 100644 (file)
--- a/Documentation/snippets/contexts-and-engravers.snippet-list
+++ b/Documentation/snippets/contexts-and-engravers.snippet-list
@@ -1,6 +1,7 @@
 adding-a-figured-bass-above-or-below-the-notes.ly
 adding-an-extra-staff-at-a-line-break.ly
 adding-an-extra-staff.ly
+centered-measure-numbers.ly
 centering-markup-on-note-heads-automatically.ly
 changing-midi-output-to-one-channel-per-voice.ly
 changing-time-signatures-inside-a-polymetric-section-using--scaledurations.ly
@@ -12,6 +13,7 @@ displaying-a-whole-grandstaff-system-if-only-one-of-its-staves-is-alive.ly
 engravers-one-by-one.ly
 mensurstriche-layout-bar-lines-between-the-staves.ly
 nesting-staves.ly
+numbering-groups-of-measures.ly
 removing-bar-numbers-from-a-score.ly
 use-square-bracket-at-the-start-of-a-staff-group.ly
 vocal-ensemble-template-with-lyrics-aligned-below-and-above-the-staves.ly

diff --git a/Documentation/snippets/editorial-annotations.snippet-list b/Documentation/snippets/editorial-annotations.snippet-list
index 6f500e1abc3cb75c34b86e91516b0fc10589df07..b2cb2d8ff9dacc90ac10820261cd38985c893949 100644 (file)
--- a/Documentation/snippets/editorial-annotations.snippet-list
+++ b/Documentation/snippets/editorial-annotations.snippet-list
@@ -25,6 +25,7 @@ how-to-print-two-rehearsal-marks-above-and-below-the-same-barline-method-2.ly
 making-some-staff-lines-thicker-than-the-others.ly
 marking-notes-of-spoken-parts-with-a-cross-on-the-stem.ly
 measure-counter.ly
+numbering-groups-of-measures.ly
 positioning-fingering-indications-precisely.ly
 positioning-text-markups-inside-slurs.ly
 printing-text-from-right-to-left.ly

diff --git a/Documentation/snippets/new/centered-measure-numbers.ly b/Documentation/snippets/new/centered-measure-numbers.ly
new file mode 100644 (file)
index 0000000..6fa6ee9
--- /dev/null
+++ b/Documentation/snippets/new/centered-measure-numbers.ly
@@ -0,0 +1,48 @@
+\version "2.17.7"
+
+\header {
+  lsrtags = "contexts-and-engravers, repeats, staff-notation"
+
+  texidoc = "
+Scores of large ensemble works often have bar numbers placed beneath the
+system, centered horizontally on the measure's extent.  This snippet shows
+how the @code{Measure_counter_engraver} may be used to simulate this
+notational practice.  Here, the engraver has been added to a @code{Dynamics}
+context.
+
+"
+
+  doctitle = "Centered measure numbers"
+}
+
+\layout {
+  \context {
+    \Dynamics
+    \consists #Measure_counter_engraver
+    \override MeasureCounter.direction = #DOWN
+    \override MeasureCounter.font-encoding = #'latin1
+    \override MeasureCounter.font-shape = #'italic
+    % to control the distance of the Dynamics context from the staff:
+    \override VerticalAxisGroup.nonstaff-relatedstaff-spacing.padding = #2
+  }
+  \context {
+    \Score
+    \remove "Bar_number_engraver"
+  }
+}
+
+pattern = \repeat unfold 7 { c'4 d' e' f' }
+
+\new StaffGroup <<
+  \new Staff {
+    \pattern
+  }
+  \new Staff {
+    \pattern
+  }
+  \new Dynamics {
+    \startMeasureCount
+    s1*7
+    \stopMeasureCount
+  }
+>>

diff --git a/Documentation/snippets/new/numbering-groups-of-measures.ly b/Documentation/snippets/new/numbering-groups-of-measures.ly
new file mode 100644 (file)
index 0000000..2722b3d
--- /dev/null
+++ b/Documentation/snippets/new/numbering-groups-of-measures.ly
@@ -0,0 +1,53 @@
+\version "2.17.7"
+
+\header {
+  lsrtags = "contexts-and-engravers, editorial-annotations, repeats, staff-notation"
+
+  texidoc = "
+This snippet demonstrates the use of the @code{Measure_counter_engraver} to
+number groups of successive measures.  Any stretch of measures may be numbered,
+whether consisting of repetitions or not.
+
+The engraver must be added to the appropriate context.  Here, a @code{Staff}
+context is used; another possibility is a @code{Dynamics} context.
+
+The counter is begun with @code{\\startMeasureCount} and ended with
+@code{\\stopMeasureCount}.  Numbering will start by default with @code{1}, but
+this behavior may be modified by overriding the @code{count-from} property.
+
+When a measure extends across a line break, the number will appear twice, the
+second time in parentheses.
+
+"
+  doctitle = "Numbering groups of measures"
+}
+
+\layout {
+  \context {
+    \Staff
+    \consists #Measure_counter_engraver
+  }
+}
+
+\new Staff {
+  \startMeasureCount
+  \repeat unfold 7 {
+    c'4 d' e' f'
+  }
+  \stopMeasureCount
+  \bar "||"
+  g'4 f' e' d'
+  \override Staff.MeasureCounter.count-from = #2
+  \startMeasureCount
+  \repeat unfold 5 {
+    g'4 f' e' d'
+  }
+  g'4 f'
+  \bar ""
+  \break
+  e'4 d'
+  \repeat unfold 7 {
+    g'4 f' e' d'
+  }
+  \stopMeasureCount
+}

diff --git a/Documentation/snippets/numbering-groups-of-measures.ly b/Documentation/snippets/numbering-groups-of-measures.ly
new file mode 100644 (file)
index 0000000..7c082be
--- /dev/null
+++ b/Documentation/snippets/numbering-groups-of-measures.ly
@@ -0,0 +1,61 @@
+% DO NOT EDIT this file manually; it is automatically
+% generated from Documentation/snippets/new
+% Make any changes in Documentation/snippets/new/
+% and then run scripts/auxiliar/makelsr.py
+%
+% This file is in the public domain.
+%% Note: this file works from version 2.17.7
+\version "2.17.7"
+
+\header {
+  lsrtags = "contexts-and-engravers, editorial-annotations, repeats, staff-notation"
+
+  texidoc = "
+This snippet demonstrates the use of the @code{Measure_counter_engraver} to
+number groups of successive measures.  Any stretch of measures may be numbered,
+whether consisting of repetitions or not.
+
+The engraver must be added to the appropriate context.  Here, a @code{Staff}
+context is used; another possibility is a @code{Dynamics} context.
+
+The counter is begun with @code{\\startMeasureCount} and ended with
+@code{\\stopMeasureCount}.  Numbering will start by default with @code{1}, but
+this behavior may be modified by overriding the @code{count-from} property.
+
+When a measure extends across a line break, the number will appear twice, the
+second time in parentheses.
+
+"
+  doctitle = "Numbering groups of measures"
+} % begin verbatim
+
+
+\layout {
+  \context {
+    \Staff
+    \consists #Measure_counter_engraver
+  }
+}
+
+\new Staff {
+  \startMeasureCount
+  \repeat unfold 7 {
+    c'4 d' e' f'
+  }
+  \stopMeasureCount
+  \bar "||"
+  g'4 f' e' d'
+  \override Staff.MeasureCounter.count-from = #2
+  \startMeasureCount
+  \repeat unfold 5 {
+    g'4 f' e' d'
+  }
+  g'4 f'
+  \bar ""
+  \break
+  e'4 d'
+  \repeat unfold 7 {
+    g'4 f' e' d'
+  }
+  \stopMeasureCount
+}

diff --git a/Documentation/snippets/repeats.snippet-list b/Documentation/snippets/repeats.snippet-list
index c9b276e8ff251c94da8b644a26cbf942fa9fc9bd..3b55be22a85c818a8d458590c6bf421500ffbb2c 100644 (file)
--- a/Documentation/snippets/repeats.snippet-list
+++ b/Documentation/snippets/repeats.snippet-list
@@ -1,8 +1,10 @@
 adding-volta-brackets-to-additional-staves.ly
+centered-measure-numbers.ly
 cross-staff-tremolos.ly
 engraving-tremolos-with-floating-beams.ly
 isolated-percent-repeats.ly
 measure-counter.ly
+numbering-groups-of-measures.ly
 percent-repeat-count-visibility.ly
 percent-repeat-counter.ly
 positioning-segno-and-coda-with-line-break.ly

diff --git a/Documentation/snippets/staff-notation.snippet-list b/Documentation/snippets/staff-notation.snippet-list
index a8c9f1bf638f8ce77abc964092764b89a7d4a605..0a2df88f19cde82cc0f3955837f284851c95f959 100644 (file)
--- a/Documentation/snippets/staff-notation.snippet-list
+++ b/Documentation/snippets/staff-notation.snippet-list
@@ -5,6 +5,7 @@ adding-indicators-to-staves-which-get-split-after-a-break.ly
 adding-orchestral-cues-to-a-vocal-score.ly
 adding-timing-marks-to-long-glissandi.ly
 alternative-bar-numbering.ly
+centered-measure-numbers.ly
 changing-the-number-of-lines-in-a-staff.ly
 changing-the-staff-size.ly
 creating-blank-staves.ly
@@ -25,6 +26,7 @@ measure-counter.ly
 mensurstriche-layout-bar-lines-between-the-staves.ly
 nesting-staves.ly
 non-traditional-key-signatures.ly
+numbering-groups-of-measures.ly
 orchestra,-choir-and-piano-template.ly
 putting-lyrics-inside-the-staff.ly
 quoting-another-voice-with-transposition.ly