bug#49587: Where are links in describe-symbol minor-mode?

bug#49587: Where are links in describe-symbol minor-mode?

[Juri Linkov]

Try to use 'C-h o' on the symbol of a minor mode defined by 'define-minor-mode'.

There are many such symbols, for example:

  C-h o dired-hide-details-mode

displays the Help buffer where text:

  See options: ‘dired-hide-details-hide-symlink-targets’ and
  ‘dired-hide-details-hide-information-lines’.

has no links in the first part of the buffer that describes the function,
but there are links only in the second part that describes the variable.

There is no such problem when a function and a variable are described separately:

  C-h f dired-hide-details-mode
  C-h v dired-hide-details-mode

Also such text in the output of 'C-h o' looks clumsy:

  This is a minor mode.  If called interactively, toggle the
  ‘Dired-Hide-Details mode’ mode.

Another problem is that with 'C-h o' the same Help buffer is displayed twice
that breaks some window-displaying commands.

bug#49587: Where are links in describe-symbol minor-mode?

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Try to use 'C-h o' on the symbol of a minor mode defined by 'define-minor-mode'.
>
> There are many such symbols, for example:
>
>   C-h o dired-hide-details-mode
>
> displays the Help buffer where text:
>
>   See options: ‘dired-hide-details-hide-symlink-targets’ and
>   ‘dired-hide-details-hide-information-lines’.
>
> has no links in the first part of the buffer that describes the function,
> but there are links only in the second part that describes the variable.

I think the *Help* buffer thing is due for an overhaul.  I've been
poking at it to make it more composable, but it's currently implemented
as a series of hacks that insert stuff into the buffer, and then it
later tries to determine what it's just inserted.

This is a fallout of that strategy -- it skips certain paragraphs when
it finally gets around to doing link recognition, instead of just doing
that immediately when inserting the doc string.

There's also the annoying reliance on `standard-output', which is pretty
bizarre, because it means that there's

	  (with-current-buffer standard-output
            ...

all over the place.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49587: Where are links in describe-symbol minor-mode?

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Try to use 'C-h o' on the symbol of a minor mode defined by 'define-minor-mode'.
>
> There are many such symbols, for example:
>
>   C-h o dired-hide-details-mode
>
> displays the Help buffer where text:
>
>   See options: ‘dired-hide-details-hide-symlink-targets’ and
>   ‘dired-hide-details-hide-information-lines’.
>
> has no links in the first part of the buffer that describes the function,
> but there are links only in the second part that describes the variable.

I've now fixed this in Emacs 29.

> Also such text in the output of 'C-h o' looks clumsy:
>
>   This is a minor mode.  If called interactively, toggle the
>   ‘Dired-Hide-Details mode’ mode.

Well, it looks pretty clumsy `C-h f', too.

> Another problem is that with 'C-h o' the same Help buffer is displayed twice
> that breaks some window-displaying commands.

I'm not sure what can be done about that -- the `C-h o' function
basically just calls `C-h f' and `C-h v'.  But what setups do they break
in practice?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49587: Where are links in describe-symbol minor-mode?

[Juri Linkov]

>> Another problem is that with 'C-h o' the same Help buffer is displayed twice
>> that breaks some window-displaying commands.
>
> I'm not sure what can be done about that -- the `C-h o' function
> basically just calls `C-h f' and `C-h v'.  But what setups do they break
> in practice?

With a setup like this

  (push `("\\*Help\\*" display-buffer-same-window
          (inhibit-same-window . nil))
        display-buffer-alist)

  M-x windmove-display-left RET
  C-h o dired-hide-details-mode RET

the *Help* buffer is displayed in two windows.
This is because of these lines in display-buffer-override-next-command:

                       ;; Reset display-buffer-overriding-action
                       ;; after the first display-buffer action (bug#39722).
                       (funcall clearfun)

In bug#39722 the same buffer was displayed in two tabs,
so now display-buffer-overriding-action affects only
the next display, and once the buffer is displayed,
it resets the specified location of the window to the
default location that is configured to the same window.

Does `C-h o' really need to display the same buffer twice?

BTW, I noticed that the generated docstring of define-minor-mode
refers back to the help of both function/variable, whereas it should
refer only to the variable:

```
diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index c3a4e9fc7a..ab91c2bc37 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ easy-mmode--arg-docstring
 Disable the mode if ARG is a negative number.
 
 To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate the variable `%s'.
 
 The mode's hook is called both when the mode is enabled and when
 it is disabled.")
```

bug#49587: Where are links in describe-symbol minor-mode?

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> With a setup like this
>
>   (push `("\\*Help\\*" display-buffer-same-window
>           (inhibit-same-window . nil))
>         display-buffer-alist)
>
>   M-x windmove-display-left RET
>   C-h o dired-hide-details-mode RET
>
> the *Help* buffer is displayed in two windows.

I see.

> Does `C-h o' really need to display the same buffer twice?

No, I think it was just implemented that way because it was simple.  As
somebody said in this thread, those functions should be rewritten
"inside out" -- i.e., separate out the stuff inside those commands that
actually generate the text to that they can be reused.  I'll have a go
at doing that...

> BTW, I noticed that the generated docstring of define-minor-mode
> refers back to the help of both function/variable, whereas it should
> refer only to the variable:

[...]

>  To check whether the minor mode is enabled in the current buffer,
> -evaluate `%s'.
> +evaluate the variable `%s'.

No, it's written in that hand-wavey way because the %s there may be a
getter function -- it might not be a variable.  It could be rewritten to
use totally different sentences in the variable vs. getter cases,
though.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49587: Where are links in describe-symbol minor-mode?

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> No, I think it was just implemented that way because it was simple.  As
> somebody said in this thread, those functions should be rewritten
> "inside out" -- i.e., separate out the stuff inside those commands that
> actually generate the text to that they can be reused.  I'll have a go
> at doing that...

And looking at this yet again, I really think all of these functions
should be radically rewritten -- they're incredibly convoluted at
present.  That is, pass in explicitly describe-function-orig-buffer etc
instead of the weird dance, and stop using standard-output for half of
the functions, because it really doesn't help.

But it's a pretty big job, and there few tests to detect if something
goes wrong (as it inevitably will)...

I'll come back to it later, and I'm leaving this bug report open.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no