Merged branch bug-1581955fff, fixing [1581955fff]

1 files changed, 33 insertions, 16 deletions

diff --git a/doc/text.n b/doc/text.n
index e55c4a0..88de877 100644
--- a/doc/text.n
+++ b/doc/text.n
@@ -634,15 +634,23 @@ embedded window annotation causes a window to be displayed at a particular
 point in the text. There may be any number of embedded windows in a text
 widget, and any widget may be used as an embedded window (subject to the usual
 rules for geometry management, which require the text window to be the parent
-of the embedded window or a descendant of its parent). The embedded window's
-position on the screen will be updated as the text is modified or scrolled,
-and it will be mapped and unmapped as it moves into and out of the visible
-area of the text widget. Each embedded window occupies one unit's worth of
-index space in the text widget, and it may be referred to either by the name
-of its embedded window or by its position in the widget's index space. If the
-range of text containing the embedded window is deleted then the window is
-destroyed. Similarly if the text widget as a whole is deleted, then the window
-is destroyed.
+of the embedded window or a descendant of its parent).
+.PP
+The embedded window's position on the screen will be updated as the text is
+modified or scrolled, and it will be mapped and unmapped as it moves into and
+out of the visible area of the text widget. Each embedded window occupies one
+unit's worth of index space in the text widget, and it may be referred to
+either by the name of its embedded window or by its position in the widget's
+index space. If the range of text containing the embedded window is deleted
+then the window is destroyed. Similarly if the text widget as a whole is
+deleted, then the window is destroyed.
+.PP
+Eliding an embedded window immediately after scheduling it for creation via
+\fIpathName \fBwindow create \fIindex \fB-create\fR will prevent it from being
+effectively created. Uneliding an elided embedded window scheduled for creation
+via \fIpathName \fBwindow create \fIindex \fB-create\fR will automatically
+trigger the associated creation script. After destroying an elided embedded
+window, the latter won't get automatically recreated.
 .PP
 When an embedded window is added to a text widget with the \fIpathName
 \fBwindow create\fR widget command, several configuration options may be
@@ -706,13 +714,22 @@ The final form of annotation in text widgets is an embedded image. Each
 embedded image annotation causes an image to be displayed at a particular
 point in the text. There may be any number of embedded images in a text
 widget, and a particular image may be embedded in multiple places in the same
-text widget. The embedded image's position on the screen will be updated as
-the text is modified or scrolled. Each embedded image occupies one unit's
-worth of index space in the text widget, and it may be referred to either by
-its position in the widget's index space, or the name it is assigned when the
-image is inserted into the text widget with \fIpathName \fBimage create\fR. If
-the range of text containing the embedded image is deleted then that copy of
-the image is removed from the screen.
+text widget.
+.PP
+The embedded image's position on the screen will be updated as the text is
+modified or scrolled. Each embedded image occupies one unit's worth of index
+space in the text widget, and it may be referred to either by its position in
+the widget's index space, or the name it is assigned when the image is inserted
+into the text widget with \fIpathName \fBimage create\fR. If the range of text
+containing the embedded image is deleted then that copy of the image is removed
+from the screen.
+.PP
+Eliding an embedded image immediately after scheduling it for creation via
+\fIpathName \fBimage create \fIindex \fB-create\fR will prevent it from being
+effectively created. Uneliding an elided embedded image scheduled for creation
+via \fIpathName \fBimage create \fIindex \fB-create\fR will automatically
+trigger the associated creation script. After destroying an elided embedded
+image, the latter won't get automatically recreated.
 .PP
 When an embedded image is added to a text widget with the \fIpathName \fBimage
 create\fR widget command, a name unique to this instance of the image is