* doc/emacs/text.texi (Outline Minor Mode): Add a note about value 'insert'.

* lisp/outline.el (outline-minor-mode-use-buttons): Add a note and
a comment about the value 'insert' (bug#65874).

2 files changed, 8 insertions, 4 deletions

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 7037c8c943a..0691cc7b78b 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1020,10 +1020,11 @@ addition to ellipsis, to show that a section is hidden.  Clicking the
 mouse on the button toggles display of the section.  If the value of
 this variable is @code{insert}, the buttons are inserted directly into
 the buffer text, so @key{RET} on the button will also toggle display
-of the section, like a mouse click does.  If the value is
-@code{in-margins}, Outline minor mode will use the window margins to
-indicate that a section is hidden.  The buttons are customizable as icons
-(@pxref{Icons}).
+of the section, like a mouse click does.  Using the value @code{insert}
+is not recommended in editable buffers because it modifies them.
+If the value is @code{in-margins}, Outline minor mode will use the
+window margins to indicate that a section is hidden.  The buttons are
+customizable as icons (@pxref{Icons}).
 
 @vindex outline-minor-mode-cycle
   If the @code{outline-minor-mode-cycle} user option is
diff --git a/lisp/outline.el b/lisp/outline.el
index 97a51c9b92a..d8dd491212e 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -314,12 +314,15 @@ These buttons can be used to hide and show the body under the heading.
 When the value is `insert', additional placeholders for buttons are
 inserted to the buffer, so buttons are not only clickable,
 but also typing `RET' on them can hide and show the body.
+Using the value `insert' is not recommended in editable
+buffers because it modifies them.
 When the value is `in-margins', then clickable buttons are
 displayed in the margins before the headings.
 When the value is `t', clickable buttons are displayed
 in the buffer before the headings.  The values `t' and
 `in-margins' can be used in editing buffers because they
 don't modify the buffer."
+  ;; The value `insert' is not intended to be customizable.
   :type '(choice (const :tag "Do not use outline buttons" nil)
                  (const :tag "Show outline buttons in margins" in-margins)
                  (const :tag "Show outline buttons in buffer" t))