From 28add695953862ef4a87f9fbeadd1d02dc299244 Mon Sep 17 00:00:00 2001
From: David Kastrup <dak@gnu.org>
Date: Tue, 8 Sep 2015 09:57:36 +0200
Subject: [PATCH] Issue 4609/7: Document \once \revert

---
 Documentation/changes.tely                     | 18 ++++++++++++++++++
 Documentation/learning/tweaks.itely            | 16 ++++++----------
 Documentation/notation/changing-defaults.itely |  6 +++---
 3 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index ca142c3286..7ba1fa281b 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -61,6 +61,24 @@ which scares away people.
 
 @end ignore
 
+@item
+All of @code{\override}, @code{\revert}, @code{\set}, and
+@code{\unset} now work with the @code{\once} prefix for making
+one-time settings.
+@lilypond[quote,verbatim]
+\relative {
+  c'4 d
+  \override NoteHead.color = #red
+  e4 f |
+  \once \override NoteHead.color = #green
+  g4 a
+  \once \revert NoteHead.color
+  b c |
+  \revert NoteHead.color
+  f2 c |
+}
+@end lilypond
+
 @item
 When outputting MIDI, LilyPond will now store the @code{title}
 defined in a score's @code{\header} block (or, if there is no
diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely
index c1e2cc20f3..cd8df5c912 100644
--- a/Documentation/learning/tweaks.itely
+++ b/Documentation/learning/tweaks.itely
@@ -310,9 +310,9 @@ of the note head to the default value for the final two notes:
 @funindex \once
 @funindex once
 
-Both the @code{\override} and the @code{\set} commands may be prefixed
-by @code{\once}.  This causes the following @code{\override} or
-@code{\set} command to be effective only during the current musical
+@code{\override}, @code{\revert}. @code{\set}, and @code{\unset}
+commands may be prefixed with @code{\once}.  This causes such a
+command to be effective only during the current musical
 moment before the property reverts back to its previous value (this can
 be different from the default if another @code{\override} is still in
 effect).  Using the same example, we can change the color of a single
@@ -328,8 +328,10 @@ note like this:
   e4 f |
   \once \override NoteHead.color = #green
   g4 a
-  \revert NoteHead.color
+  \once \revert NoteHead.color
   b c |
+  \revert NoteHead.color
+  f2 c |
 }
 @end lilypond
 
@@ -347,12 +349,6 @@ predefined commands to limit their effect to one musical moment:
 }
 @end lilypond
 
-However, predefined commands of the form @code{\@dots{}Neutral},
-@code{\@dots{}Off} and @code{\un@dots{}} use @code{\revert} internally
-rather than @code{\override} so prefixing these with @code{\once} has no
-effect.
-
-
 @node The overrideProperty command
 @unnumberedsubsubsec The @code{@bs{}overrideProperty} command
 
diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index efcf8549b3..bb5a2c2b60 100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -2050,8 +2050,8 @@ are equivalent if the current bottom context is @code{Voice}.
 
 
 @cindex \once
-Preceding a @code{\set} command by @code{\once} makes the
-setting apply to only a single time-step:
+Preceding a @code{\set} or @code{\unset} command by @code{\once}
+makes the setting apply to only a single time-step:
 
 @lilypond[quote,fragment,verbatim]
 c''4
@@ -2181,7 +2181,7 @@ grobs in the affected context from the current time forward:
 @funindex \once
 @cindex overriding for only one moment
 
-@code{\once} can be used with @code{\override}
+@code{\once} can be used with @code{\override} or @code{\revert}
 to affect only the current time step:
 
 @lilypond[quote,verbatim]
-- 
2.39.2