bug#65874: 30.0.50; outline-minor-mode-use-buttons missing choice

[Juri Linkov]

>>> The docstring for outline-minor-mode-use-buttons says its value can be
>>> the symbol insert, but that choice is not present in its :type.
>>>
>>> I can't send a patch, because I can't figure out a good :tag for it.
>>
>> Such omission is intentional, because 'insert' can be used only
>> in generated buffers, not in editable buffers, so disallowing
>> customization to the value 'insert' protects the users
>> from damaging editable buffers.
>
> I see, thanks.  How about adding something to the docstring some text to
> explain that?  And/or maybe add a comment in the :type to clarify that
> the omission is intentional?

Maybe something like this for the emacs-29 branch?

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 3d3f2562617..6f57bae8fef 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1024,10 +1024,11 @@ Outline Minor Mode
 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..7cdfec753d1 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -314,12 +314,15 @@ outline-minor-mode-use-buttons
 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))