Add RemoveAllEmptyStaves command

Issue 4744

It has been noted several
times that we should have
a companion for RemoveEmptyStaves
and to also set remove-first to ##t.

A doc snippet, removing-the-first-empty-line.ly,
has become obsolete with these changes.

Contains commits:
Add missing word in changes.tely

Add changes entry for RemoveEmptyStavesAll

Use RemoveEmptyStavesAll for ossia example in
Notation Reference

This rewrites documentation for
RemoveEmptyStaves and adds
information on the newly added
RemoveEmptyStavesAll.

Add RemoveEmptyStavesAll command
Introduce a new context modification
identifier, RemoveEmptyStavesAll,
to complement RemoveEmptyStaves.

It sets both the remove-empty
and remove-first properties
of VerticalAxisGroup to ##t.

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 2a265ce914263d0810063289be7546c7ee0a0431..00e53b5e88ff347ea84ea001846164f9f7feae4a 100644 (file)
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -93,9 +93,14 @@ Customizing is possible with overrides of @code{thickness}, @code{angularity},
   }
 @end lilypond
 
+@item
+A new command, @code{\RemoveAllEmptyStaves}, has been made available, which
+acts exactly like @code{\RemoveEmptyStaves}, except for also removing empty
+staves on the first system in a score.
+
 @item
 Markup-commands @code{\undertie} and @code{\overtie} are now available, as well
-the generic markup-command @code{\tie}.
+as the generic markup-command @code{\tie}.
 @lilypond[quote,verbatim]
 \markup {
   \undertie "undertied"

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index db5d5ebab8fe0508986554f4d553e4af4bdb0818..1a2f07566daa8409658c88fbcb6d00eba08741ff 100644 (file)
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -669,11 +669,11 @@ example.
 @end lilypond
 
 
-Using the @code{\Staff \RemoveEmptyStaves} command to create ossia
+Using the @code{\RemoveAllEmptyStaves} command to create ossia
 staves may be used as an alternative.  This method is most
 convenient when ossia staves occur immediately following a line
 break.  For more information about
-@code{\Staff \RemoveEmptyStaves}, see @ref{Hiding staves}.
+@code{\RemoveAllEmptyStaves}, see @ref{Hiding staves}.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
@@ -681,6 +681,7 @@ break.  For more information about
     \remove "Time_signature_engraver"
     \hide Clef
     \magnifyStaff #2/3
+    \RemoveAllEmptyStaves
   } \relative {
     R1*3
     c''4 e8 d c2
@@ -694,13 +695,6 @@ break.  For more information about
     e4 d c2
   }
 >>
-
-\layout {
-  \context {
-    \Staff \RemoveEmptyStaves
-    \override VerticalAxisGroup.remove-first = ##t
-  }
-}
 @end lilypond
 
 
@@ -737,10 +731,14 @@ Internals Reference:
 @cindex Frenched staff
 @cindex staff, hiding
 @cindex staff, empty
-@cindex hiding of staves
+@cindex hiding staves
+@cindex hiding ancient staves
+@cindex hiding rhythmic staves
+@cindex hiding vaticana staves
 @cindex empty staves
 
 @funindex \RemoveEmptyStaves
+@funindex \RemoveAllEmptyStaves
 @funindex Staff_symbol_engraver
 @funindex \stopStaff
 @funindex stopStaff
@@ -758,11 +756,14 @@ alternative, @code{\stopStaff} may be used.
 @end lilypond
 
 
-Empty staves can be hidden by setting the
-@code{\Staff \RemoveEmptyStaves} command in the @code{\layout}
-block.  In orchestral scores, this style is known as @q{Frenched
-Score}.  By default, this command hides and removes all empty
-staves in a score except for those in the first system.
+Empty staves can be hidden (for a so-called @q{Frenched Score})
+by applying the @code{\RemoveEmptyStaves} command on a context, which
+can be done globally (in a @code{\layout} block) as well as for
+specific staves only (in a @code{\with} block).  This command removes
+all empty staves in a score except for those in the first system.  If
+you want those in the first system to be hidden also, use
+@code{\RemoveAllEmptyStaves}.  Supported contexts are @code{Staff},
+@code{RhythmicStaff} and @code{VaticanaStaff}.
 
 @warning{A staff is considered empty when it contains only
 multi-measure rests, rests, skips, spacer rests, or a combination of these
@@ -771,7 +772,8 @@ elements.}
 @lilypond[verbatim,quote,ragged-right]
 \layout {
   \context {
-    \Staff \RemoveEmptyStaves
+    \Staff
+    \RemoveEmptyStaves
   }
 }
 
@@ -792,32 +794,15 @@ elements.}
 @cindex ossia
 
 @noindent
-@code{\Staff \RemoveEmptyStaves} can also be used to create ossia
+@code{\RemoveAllEmptyStaves} can also be used to create ossia
 sections for a staff.  For details, see @ref{Ossia staves}.
 
-@cindex hiding ancient staves
-@cindex hiding rhythmic staves
-
-@funindex \RemoveEmptyStaves
-
-The @code{\VaticanaStaff \RemoveEmptyStaves} command may be used to
-hide empty staves in ancient music contexts.  Similarly,
-@code{\RhythmicStaff \RemoveEmptyStaves} may be used to hide empty
-@code{RhythmicStaff} contexts.
-
 
 @predefined
-@code{\Staff \RemoveEmptyStaves},
-@code{\VaticanaStaff \RemoveEmptyStaves},
-@code{\RhythmicStaff \RemoveEmptyStaves}.
+@code{\RemoveEmptyStaves},
+@code{\RemoveAllEmptyStaves}.
 @endpredefined
 
-
-@snippets
-
-@lilypondfile[verbatim,quote,texidoc,doctitle]
-{removing-the-first-empty-line.ly}
-
 @seealso
 Music Glossary:
 @rglos{Frenched staff}.

diff --git a/ly/context-mods-init.ly b/ly/context-mods-init.ly
index 24b8ce055845e3d730475b64da9c94e6a9e46b46..a4064f4b327a4df15bef871dff36d801efe50d2d 100644 (file)
--- a/ly/context-mods-init.ly
+++ b/ly/context-mods-init.ly
@@ -24,6 +24,14 @@ RemoveEmptyStaves = \with {
 to the list of interfaces set by @code{keepAliveInterfaces}."
 }
 
+RemoveAllEmptyStaves = \with {
+  \override VerticalAxisGroup.remove-empty = ##t
+  \override VerticalAxisGroup.remove-first = ##t
+  \description "Remove staves which are considered to be empty according
+to the list of interfaces set by @code{keepAliveInterfaces}, including those
+in the first system."
+}
+
 inherit-acceptability =
 #(define-void-function (to from)
    (symbol? symbol?)