Rename \compressFullBarRests and document it.

- Rename \compressFullBarRests to \compressEmptyMeasures as suggested by Trevor in #4375. - Document the new command (and explain its difference with \compressMMRests) by creating a new subsubsec in NR 1.6.3 "Writing parts". - Add index entries and links everywhere I can think of, obviously starting with NR 1.2.2.3 "Full measure rests". - Add convert rule and update syntax through the doc. - Clarify the (in)famous progerror "Multi_measure_rest::get_rods (): I am not spanned!" - Address minor errors caught by Werner and Trevor.
lilypond · Mar 25, 2020 · 68fb45e · 68fb45e
1 parent 786c366
commit 68fb45e
Show file tree

Hide file tree

Showing 24 changed files with 221 additions and 96 deletions.
diff --git a/Documentation/changes.tely b/Documentation/changes.tely
@@ -62,6 +62,14 @@ which scares away people.
 @end ignore
 
 
+@item
+@code{\compressFullBarRests} has been renamed to
+@code{\compressEmptyMeasures}, to avoid
+possible confusion with @code{\compressMMRests}.
+Likewise, @code{\expandFullBarRests} has now become
+@code{\expandEmptyMeasures}.
+
+
 @item
 LilyPond for Windows (MinGW) can handle Unicode filenames
 on Windows 10 1903 and above.

diff --git a/Documentation/de/changes.tely b/Documentation/de/changes.tely
@@ -273,12 +273,12 @@ Verhältnis bestimmt.  Die Standardvorgabe dieses Wertes beträgt
 @code{2.0}.
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 R1*2 R1*4 R1*64 R1*16
 @end lilypond
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 \override Staff.MultiMeasureRest.space-increment = 2.5
 R1*2 R1*4 R1*64 R1*16
 @end lilypond

diff --git a/Documentation/de/notation/changing-defaults.itely b/Documentation/de/notation/changing-defaults.itely
@@ -1221,7 +1221,7 @@ des äußeren Kontextes neu positioniert, anstatt innerhalb von ihm
 gesetzt zu werden.
 
 Die @qq{accepts}-Liste eines Kontextes kann mit dem Befehlen
-@code{\accepts} und @code{\denies} verändert werden.  @code{\accepts} 
+@code{\accepts} und @code{\denies} verändert werden.  @code{\accepts}
 fügt einen Kontext zur @qq{accepts}-Liste, und @code{\denies}
 entfernt einen Kontext aus der Liste.  Akkordbezeichnungen sollen
 beispielsweise normalerweise nicht innerhalb eines @code{Staff}-Kontextes
@@ -1254,7 +1254,7 @@ geführt ist.  Wenn er aber benötigt wird, kann er hinzugefügt werden:
 @end lilypond
 
 @code{\denies} wird vorrangig eingesetzt, wenn ein neuer Kontext
-basierend auf einem existierenden erstellt wird, aber sein 
+basierend auf einem existierenden erstellt wird, aber sein
 Schachtelungsverhalten sich unterscheidet.  Der
 @code{VaticanaStaff}-Kontext beispielsweise basiert auf dem
 @code{Staff}-Kontext, hat aber den @code{VaticanaVoice}-Kontext
@@ -2844,7 +2844,7 @@ a
 
 @lilypond[verbatim,quote,relative=2]
 a1
-\compressFullBarRests
+\compressEmptyMeasures
 R1*23
 % increase the length of the rest bar
 \once \override MultiMeasureRest.minimum-length = #20

diff --git a/Documentation/de/notation/rhythms.itely b/Documentation/de/notation/rhythms.itely
@@ -845,7 +845,7 @@ Noten eingegeben, wobei die Bezeichnung ein Großbuchstabe
 
 @lilypond[quote,verbatim,relative=2]
 % Rest measures contracted to single measure
-\compressFullBarRests
+\compressEmptyMeasures
 R1*4
 R1*24
 R1*4
@@ -858,7 +858,7 @@ eine ganze Anzahl an Taktlängen sein, weshalb Punktierungen
 und Brüche recht häufig eingesetzt werden müssen.
 
 @lilypond[quote,relative=2,verbatim]
-\compressFullBarRests
+\compressEmptyMeasures
 \time 2/4
 R1 | R2 |
 \time 3/4
@@ -886,10 +886,8 @@ R1*2 |
 @cindex Pausen, mehrere Takte komprimieren
 @cindex Mehrtaktpausen, komprimieren
 
-@funindex \expandFullBarRests
-@funindex \compressFullBarRests
-@funindex expandFullBarRests
-@funindex compressFullBarRests
+@funindex \expandEmptyMeasures
+@funindex \compressEmptyMeasures
 
 In den Standardeinstellungen werden mehrtaktige Pausen
 ausgeschrieben gesetzt, sodass sie die entsprechende Anzahl von
@@ -904,10 +902,10 @@ der Pausendauer über dem Pausenzeichen ausgegeben wird:
 \time 2/4 R2 |
 \time 4/4
 % Rest measures contracted to single measure
-\compressFullBarRests
+\compressEmptyMeasures
 r1 | R1*17 | R1*4 |
 % Rest measures expanded
-\expandFullBarRests
+\expandEmptyMeasures
 \time 3/4
 R2.*2 |
 @end lilypond
@@ -927,7 +925,7 @@ Textbeschriftung kann Mehrtaktpausen mit @code{\markup}
 hinzugefügt werden.
 
 @lilypond[quote,verbatim,relative=2]
-\compressFullBarRests
+\compressEmptyMeasures
 \time 3/4
 R2.*10^\markup { \italic "ad lib." }
 @end lilypond
@@ -960,14 +958,14 @@ Taktprüfungswarnungen nicht angezeigt.
 
 @funindex \textLengthOn
 @funindex \textLengthOff
-@funindex \compressFullBarRests
-@funindex \expandFullBarRests
+@funindex \compressEmptyMeasures
+@funindex \expandEmptyMeasures
 
 @predefined
 @code{\textLengthOn},
 @code{\textLengthOff},
-@code{\compressFullBarRests},
-@code{\expandFullBarRests}.
+@code{\compressEmptyMeasures},
+@code{\expandEmptyMeasures}.
 @endpredefined
 
 @snippets
@@ -1749,7 +1747,7 @@ verschoben werden.
 
 @subsubheading Zusammengesetzte Taktarten
 
-Taktarten aus mehreren Teilen werden mit der Funktion 
+Taktarten aus mehreren Teilen werden mit der Funktion
 @code{\compoundMeter} erstellt.  Die Syntax ist folgende:
 
 @example
@@ -2435,7 +2433,7 @@ nicht beendet wurde und weiterhin Noten erwartet, wird dieser
 letzte Balken nicht ausgegeben.  Das Gleiche gilt auch für
 polyphone Stimmen, die mit der
 @code{<< @dots{} \\ @dots{} >>}-Konstruktion notiert wurden.  Wenn eine
-polyphone Stimme endet, während ein Balken noch weitere Noten
+polyphone Stimme endet, während ein Balken noch weitere Noten
 erwartet, wird der Balken nicht gesetzt.  Eine Notlösung für
 dieses Probelm ist, den letzten Balken in der Stimme oder
 Partitur manuell zu setzen.

diff --git a/Documentation/de/notation/staff.itely b/Documentation/de/notation/staff.itely
@@ -1082,7 +1082,7 @@ wird dann benutzt, um den Wechsel vorzunehmen:
 }
 \relative c' {
   \clef tenor
-  \compressFullBarRests
+  \compressEmptyMeasures
   c2 g'
   R1*16
   \instrumentSwitch "contrabassoon"

diff --git a/Documentation/fr/changes.tely b/Documentation/fr/changes.tely
@@ -263,12 +263,12 @@ totale, sous contrôle de @code{MultiMeasureRest.space-increment}. La
 valeur par défaut est fixée à @code{2.0}.
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 R1*2 R1*4 R1*64 R1*16
 @end lilypond
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 \override Staff.MultiMeasureRest.space-increment = 2.5
 R1*2 R1*4 R1*64 R1*16
 @end lilypond

diff --git a/Documentation/it/changes.tely b/Documentation/it/changes.tely
@@ -251,12 +251,12 @@ durata totale e può essere modificato attraverso la proprietà
 @code{MultiMeasureRest.space-increment}. Il valore predefinito è @code{2.0}.
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 R1*2 R1*4 R1*64 R1*16
 @end lilypond
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 \override Staff.MultiMeasureRest.space-increment = 2.5
 R1*2 R1*4 R1*64 R1*16
 @end lilypond

diff --git a/Documentation/ja/changes.tely b/Documentation/ja/changes.tely
@@ -268,12 +268,12 @@ dob, rebb misb fabsb | sold ladd six dosd | rédsd1
 長さ分の幅を持つようになりました。デフォルト値は @code{2.0} です。
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 R1*2 R1*4 R1*64 R1*16
 @end lilypond
 
 @lilypond[fragment,verbatim,quote]
-\compressFullBarRests
+\compressEmptyMeasures
 \override Staff.MultiMeasureRest.space-increment = 2.5
 R1*2 R1*4 R1*64 R1*16
 @end lilypond
@@ -794,7 +794,7 @@ m = {
 これらの関数は、@code{\lyrics} や @code{\chords} が受け入れるような@c
 区切られた引数リストを受け入れるようになりました。後方互換性を追加し、@c
 音楽識別子 (例えば @code{\mus}) を引数に取ることができるようになりました。@c
-@code{convert-ly} のルールが追加され、余分に使用されている @code{\lyricmode} 
+@code{convert-ly} のルールが追加され、余分に使用されている @code{\lyricmode}
 を削除し、コンテキストを開始するコマンドと各種歌詞コマンドが組み合わせて@c
 使用されている場合には、通常 @code{\lyricsto} が最後に配置されるように@c
 変換されます。

diff --git a/Documentation/ja/notation/rhythms.itely b/Documentation/ja/notation/rhythms.itely
@@ -936,7 +936,7 @@ R2.*2 |
 マークアップを複数小節にまたがる休符に付け加えることができます。
 
 @lilypond[quote,verbatim,relative=2]
-\compressFullBarRests
+\compressEmptyMeasures
 \time 3/4
 R2.*10^\markup { \italic "ad lib." }
 @end lilypond
@@ -976,8 +976,8 @@ R1\fermata
 
 @funindex \textLengthOn
 @funindex \textLengthOff
-@funindex \compressFullBarRests
-@funindex \expandFullBarRests
+@funindex \compressEmptyMeasures
+@funindex \expandEmptyMeasures
 
 @predefined
 @code{\textLengthOn},

diff --git a/Documentation/notation/ancient.itely b/Documentation/notation/ancient.itely
@@ -639,7 +639,7 @@ The following example demonstrates the @code{petrucci} style:
 @c separate the notes for easier identification.
 
 @lilypond[quote,fragment,ragged-right,verbatim]
-\set Score.skipBars = ##t
+\compressEmptyMeasures
 \autoBeamOff
 \override NoteHead.style = #'petrucci
 a'\maxima a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 a'
@@ -716,7 +716,7 @@ ancient rests.  Supported ancient styles are
 The following example demonstrates these styles:
 
 @lilypond[quote,fragment,ragged-right,verbatim]
-\set Score.skipBars = ##t
+\compressEmptyMeasures
 \override Rest.style = #'mensural
 r\longa^"mensural" r\breve r1 r2 r4 r8 r16 s \break
 \override Rest.style = #'neomensural

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
@@ -1983,6 +1983,7 @@ change value over time while interpreting a piece of music;
 this.  Context properties are modified with @code{\set}.
 
 For example, multimeasure rests will be combined into a single bar
+(as explained in @ref{Compressing empty measures})
 if the context property @code{skipBars} is set to @code{#t}:
 
 @lilypond[quote,fragment,verbatim]

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
@@ -865,7 +865,10 @@ Internals Reference:
 @funindex R
 
 Rests for one or more full measures are entered like notes with
-the note name uppercase @code{R}:
+the note name uppercase @samp{R}.  Their duration is entered
+identically to the duration notation used for notes, including
+the ability to use duration multipliers, as explained in
+@ref{Scaling durations}:
 
 @lilypond[quote,verbatim]
 % Rest measures contracted to single measure
@@ -877,10 +880,13 @@ the note name uppercase @code{R}:
 }
 @end lilypond
 
-The duration of full-measure rests is identical to the duration
-notation used for notes.  The duration in a multi-measure rest must
-always be an integral number of measure-lengths, so augmentation dots
-or fractions must often be used:
+The example above also demonstrates how to compress
+multiple empty measures, as explained in
+@ref{Compressing empty measures}.
+
+The duration of a multi-measure rest must always be equal to the
+length of one or several measures.   Therefore, some time signatures
+require the use of augmentation dots or fractions:
 
 @lilypond[quote,verbatim]
 \compressMMRests {
@@ -907,29 +913,6 @@ R1*3/2 |
 R1*2 |
 @end lilypond
 
-@cindex multi-measure rest, expanding
-@cindex multi-measure rest, contracting
-
-By default a multi-measure rest is expanded in the printed score to
-show all the rest measures explicitly.  Alternatively, a multi-measure
-rest can be shown as a single measure containing a multi-measure rest
-symbol, with the number of measures of rest printed above the measure:
-
-@lilypond[quote,verbatim,fragment]
-% Default behavior
-\time 3/4 r2. | R2.*2 |
-\time 2/4 R2 |
-\time 4/4
-% Rest measures contracted to single measure
-\compressMMRests {
-  r1 | R1*17 | R1*4 |
-}
-% Rest measures expanded again
-\time 3/4
-R2.*2 |
-@end lilypond
-
-
 @cindex text, on multi-measure rest
 @cindex multi-measure rest, attaching text
 @cindex script, on multi-measure rest
@@ -993,19 +976,6 @@ setting, resulting bar-check warnings may not be displayed.
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {multi-measure-rest-length-control.ly}
 
-@cindex multi-measure rest, numbering
-@funindex restNumberThreshold
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{numbering-single-measure-rests.ly}
-
-@cindex church rest
-@cindex rest, church
-@cindex kirchenpause
-@cindex multi-measure rest, style
-@cindex style, multi-measure rests
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-form-of-multi-measure-rests.ly}
-
 @cindex multi-measure rest, positioning
 @cindex position, multi-measure rest
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
@@ -1025,6 +995,8 @@ Music Glossary:
 
 Notation Reference:
 @ref{Durations},
+@ref{Scaling durations},
+@ref{Compressing empty measures},
 @ref{Text},
 @ref{Formatting text},
 @ref{Text scripts}.
@@ -1386,7 +1358,8 @@ written by including an empty string in the input:
 @funindex \markLengthOn
 @funindex \markLengthOff
 
-In a part for an instrument with long periods of rests,
+In a part for an instrument with long periods of rests (see
+@ref{Full measure rests}),
 tempo indications sometimes follow each other closely.
 The command @code{\markLengthOn} provides extra horizontal space
 to prevent tempo indications from overlapping, and @code{\markLengthOff}
@@ -1440,7 +1413,8 @@ Music Glossary:
 
 Notation Reference:
 @ref{Formatting text},
-@ref{Creating MIDI output}.
+@ref{Creating MIDI output},
+@ref{Full measure rests}.
 
 Snippets:
 @rlsr{Staff notation}.