GNU bug report logs - #61062
29.0.60; Split Outline Mode node to Outline Minor Mode node

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 61062 in the body.
You can then email your comments to 61062 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.60; Split Outline Mode node to Outline Minor Mode node
Date: Wed, 25 Jan 2023 19:31:28 +0200

[Message part 1 (text/plain, inline)]

Tags: patch

Text that describes Outline minor mode is too long and more features
will be added to it, so better to split it to the separate node:

[outline-minor-mode-node.patch (text/x-diff, inline)]

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 8fbf731a4f7..83d5869ee64 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -958,8 +958,6 @@ Outline Mode
 @cindex invisible lines
 
 @findex outline-mode
-@findex outline-minor-mode
-@vindex outline-minor-mode-prefix
 @vindex outline-mode-hook
   Outline mode is a major mode derived from Text mode, which is
 specialized for editing outlines.  It provides commands to navigate
@@ -982,6 +980,19 @@ Outline Mode
 line really kills all the following invisible text associated with the
 ellipsis.
 
+@menu
+* Outline Minor Mode::  Outline mode to use with other major modes.
+* Outline Format::      What the text of an outline looks like.
+* Outline Motion::      Special commands for moving through outlines.
+* Outline Visibility::  Commands to control what is visible.
+* Outline Views::       Outlines and multiple views.
+* Foldout::             Folding means zooming in on outlines.
+@end menu
+
+@node Outline Minor Mode
+@subsection Outline Minor Mode
+
+@findex outline-minor-mode
   Outline minor mode is a buffer-local minor mode which provides the
 same commands as the major mode, Outline mode, but can be used in
 conjunction with other major modes.  You can type @kbd{M-x
@@ -990,6 +1001,7 @@ Outline Mode
 specific file (@pxref{File Variables}).
 
 @kindex C-c @@ @r{(Outline minor mode)}
+@vindex outline-minor-mode-prefix
   The major mode, Outline mode, provides special key bindings on the
 @kbd{C-c} prefix.  Outline minor mode provides similar bindings with
 @kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
@@ -1014,14 +1026,6 @@ Outline Mode
 sub-heading, and showing all for the current section.  @kbd{S-@key{TAB}}
 does the same for the entire buffer.
 
-@menu
-* Outline Format::      What the text of an outline looks like.
-* Outline Motion::      Special commands for moving through outlines.
-* Outline Visibility::  Commands to control what is visible.
-* Outline Views::       Outlines and multiple views.
-* Foldout::             Folding means zooming in on outlines.
-@end menu
-
 @node Outline Format
 @subsection Format of Outlines
 

Message #8 received at 61062 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 61062 <at> debbugs.gnu.org
Subject: Re: bug#61062: 29.0.60;
 Split Outline Mode node to Outline Minor Mode node
Date: Wed, 25 Jan 2023 19:51:47 +0200

> From: Juri Linkov <juri <at> linkov.net>
> Date: Wed, 25 Jan 2023 19:31:28 +0200
> 
> Text that describes Outline minor mode is too long and more features
> will be added to it, so better to split it to the separate node:

I agree, thanks.

Message #11 received at 61062 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61062 <at> debbugs.gnu.org
Subject: Re: bug#61062: 29.0.60; Split Outline Mode node to Outline Minor
 Mode node
Date: Wed, 25 Jan 2023 20:20:40 +0200

>> Text that describes Outline minor mode is too long and more features
>> will be added to it, so better to split it to the separate node:
>
> I agree, thanks.

Pushed, but not yet closed.  I could try to document
outline-minor-mode-highlight as well since its counterpart
outline-minor-mode-cycle was already added to the manual.

Message #14 received at 61062 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 61062 <at> debbugs.gnu.org
Subject: Re: bug#61062: 29.0.60; Split Outline Mode node to Outline Minor
 Mode node
Date: Wed, 25 Jan 2023 21:54:51 +0200

> From: Juri Linkov <juri <at> linkov.net>
> Cc: 61062 <at> debbugs.gnu.org
> Date: Wed, 25 Jan 2023 20:20:40 +0200
> 
> >> Text that describes Outline minor mode is too long and more features
> >> will be added to it, so better to split it to the separate node:
> >
> > I agree, thanks.
> 
> Pushed, but not yet closed.  I could try to document
> outline-minor-mode-highlight as well since its counterpart
> outline-minor-mode-cycle was already added to the manual.

It sounds like this is a problematic option, whose use could produce
unwanted results.  Are you sure it is a good idea to document it in
the manual?

Message #17 received at 61062 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61062 <at> debbugs.gnu.org
Subject: Re: bug#61062: 29.0.60; Split Outline Mode node to Outline Minor
 Mode node
Date: Fri, 27 Jan 2023 09:56:52 +0200

>> Pushed, but not yet closed.  I could try to document
>> outline-minor-mode-highlight as well since its counterpart
>> outline-minor-mode-cycle was already added to the manual.
>
> It sounds like this is a problematic option, whose use could produce
> unwanted results.  Are you sure it is a good idea to document it in
> the manual?

I agree that it's not suitable for the manual.

Another question that I'm not sure about is whether it makes sense to
mention all outline-minor-mode supported modes in etc/NEWS?  I mean
that we prepared outline-minor-mode related settings in some modes,
but not enabled outline-minor-mode in these modes.

For example, we set such values as outline-search-function,
outline-level, outline-minor-mode-use-buttons, etc.
in apropos-mode and xref.  So the users could easily enable
outline-minor-mode in these modes, and it will work
without additional customization.

Does it make sense to list these modes in etc/NEWS, so users will know
where they can enable outline-minor-mode?  Probably support for
apropos-mode could be mentioned under the section Help mode,
and outline-minor-mode for xref under the section Xref?

BTW, it looks like more links could be added to the manual:

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 83d5869ee64..6a943c775b2 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1017,14 +1017,16 @@ Outline Minor Mode
 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.
+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
-non-@code{nil}, the @kbd{TAB} and @kbd{S-@key{TAB}} keys are enabled on the
-outline heading lines.  @kbd{TAB} cycles hiding, showing the
-sub-heading, and showing all for the current section.  @kbd{S-@key{TAB}}
-does the same for the entire buffer.
+non-@code{nil}, the @kbd{TAB} and @kbd{S-@key{TAB}} keys that cycle
+the visibility are enabled on the outline heading lines.  @kbd{TAB}
+cycles hiding, showing the sub-heading, and showing all for the
+current section.  @kbd{S-@key{TAB}} does the same for the entire
+buffer (@pxref{Outline Visibility, outline-cycle}).
 
 @node Outline Format
 @subsection Format of Outlines

Message #20 received at 61062 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 61062 <at> debbugs.gnu.org
Subject: Re: bug#61062: 29.0.60; Split Outline Mode node to Outline Minor
 Mode node
Date: Fri, 27 Jan 2023 10:15:37 +0200

> From: Juri Linkov <juri <at> linkov.net>
> Cc: 61062 <at> debbugs.gnu.org
> Date: Fri, 27 Jan 2023 09:56:52 +0200
> 
> Another question that I'm not sure about is whether it makes sense to
> mention all outline-minor-mode supported modes in etc/NEWS?  I mean
> that we prepared outline-minor-mode related settings in some modes,
> but not enabled outline-minor-mode in these modes.
> 
> For example, we set such values as outline-search-function,
> outline-level, outline-minor-mode-use-buttons, etc.
> in apropos-mode and xref.  So the users could easily enable
> outline-minor-mode in these modes, and it will work
> without additional customization.
> 
> Does it make sense to list these modes in etc/NEWS, so users will know
> where they can enable outline-minor-mode?  Probably support for
> apropos-mode could be mentioned under the section Help mode,
> and outline-minor-mode for xref under the section Xref?

If the list is not too long, I think listing those modes in NEWS would
be useful.

> BTW, it looks like more links could be added to the manual:

Adding cross-references is always a Good Thing, thanks.  The only
situation where such cross-references could be inappropriate is if
some prior text in the same node and close enough already has a
cross-reference to the same place.  In all other cases, such
cross-references are most welcome.

Message #23 received at 61062 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61062 <at> debbugs.gnu.org
Subject: Re: bug#61062: 29.0.60; Split Outline Mode node to Outline Minor
 Mode node
Date: Sat, 28 Jan 2023 19:59:47 +0200

close 61062 29.0.60
quit

>> Another question that I'm not sure about is whether it makes sense to
>> mention all outline-minor-mode supported modes in etc/NEWS?  I mean
>> that we prepared outline-minor-mode related settings in some modes,
>> but not enabled outline-minor-mode in these modes.
>> 
>> For example, we set such values as outline-search-function,
>> outline-level, outline-minor-mode-use-buttons, etc.
>> in apropos-mode and xref.  So the users could easily enable
>> outline-minor-mode in these modes, and it will work
>> without additional customization.
>> 
>> Does it make sense to list these modes in etc/NEWS, so users will know
>> where they can enable outline-minor-mode?  Probably support for
>> apropos-mode could be mentioned under the section Help mode,
>> and outline-minor-mode for xref under the section Xref?
>
> If the list is not too long, I think listing those modes in NEWS would
> be useful.

Done.

>> BTW, it looks like more links could be added to the manual:
>
> Adding cross-references is always a Good Thing, thanks.  The only
> situation where such cross-references could be inappropriate is if
> some prior text in the same node and close enough already has a
> cross-reference to the same place.  In all other cases, such
> cross-references are most welcome.

Also pushed to emacs-29.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.