bug#46702: Link symbol name in Help

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

When I wanted to a check a buffer's mode then I did a C-h v
major-mode to see which mode it is and wanted to jump to its code
to check something. The symbol value was not linked, so I had to
type it to look it up.

Demonstrated here with the scratch buffer, showing that
lisp-interaction-mode is not linked in the second line:

   https://i.imgur.com/KIWQE60.png

It could link to the symbol's help if the value is a symbol to
make looking it up more convenient.

If it's both a function and a variable then it can ask which one
I want to jump to when clicked.

bug#46702: Link symbol name in Help

[Andreas Schwab]

On Feb 22 2021, Peter Dean via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

> When I wanted to a check a buffer's mode then I did a C-h v
> major-mode to see which mode it is and wanted to jump to its code
> to check something. The symbol value was not linked, so I had to
> type it to look it up.

Didn't it work to move over the symbol and type C-h f?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>
> Didn't it work to move over the symbol and type C-h f?
>


It can work, but why should I press 3 keys instead of one (enter)? Convenience.

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> > Didn't it work to move over the symbol and type C-h f?
>
> It can work, but why should I press 3 keys instead of one (enter)? Convenience.


Also: discoverability. If a user sees the symbol is linked then he instantly knows
he can act on it by pressing enter or clicking.

bug#46702: Link symbol name in Help

[Lars Ingebrigtsen]

Peter Dean <laszlomail@protonmail.com> writes:

> Demonstrated here with the scratch buffer, showing that
> lisp-interaction-mode is not linked in the second line:
>
>    https://i.imgur.com/KIWQE60.png

This is due to this code:

(defun help-make-xrefs (&optional buffer)
[...]
      (goto-char (point-min))
      ;; Skip the header-type info, though it might be useful to parse
      ;; it at some stage (e.g. "function in `library'").
      (forward-paragraph)

Anybody know what the rationale behind this is?  I in complex values,
there may be false positives, but...  I tried just removing that bit and
looking at a couple of variables, and it fixes the problem described
here, and I didn't see any regressions.

Complex variable values aren't displayed here (but at the end of the
buffer), so that shouldn't be a problem.

Any opinions?

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

bug#46702: Link symbol name in Help

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 22 Feb 2021 16:01:35 +0100
> Cc: 46702@debbugs.gnu.org
> 
> (defun help-make-xrefs (&optional buffer)
> [...]
>       (goto-char (point-min))
>       ;; Skip the header-type info, though it might be useful to parse
>       ;; it at some stage (e.g. "function in `library'").
>       (forward-paragraph)
> 
> Anybody know what the rationale behind this is?  I in complex values,
> there may be false positives, but...  I tried just removing that bit and
> looking at a couple of variables, and it fixes the problem described
> here, and I didn't see any regressions.

I think we should instead insert a newline before "Its value is...".
There's absolutely no need for it to follow the initial text.  This
fixes the problem without doing anything with the proverbial first
paragraph.

bug#46702: Link symbol name in Help

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I think we should instead insert a newline before "Its value is...".
> There's absolutely no need for it to follow the initial text.  This
> fixes the problem without doing anything with the proverbial first
> paragraph.

Sure; some vertical space there looks better.  Now pushed to Emacs 28.

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

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On Monday, February 22, 2021 10:34 PM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
>
> Sure; some vertical space there looks better. Now pushed to Emacs 28.

Thanks. Unrelated to this bug, but maybe an empty line after Documentation:
too could improve readability (so the header does not merge with the actual
documentation text).

bug#46702: Link symbol name in Help

[Lars Ingebrigtsen]

Peter Dean <laszlomail@protonmail.com> writes:

> Thanks. Unrelated to this bug, but maybe an empty line after Documentation:
> too could improve readability (so the header does not merge with the actual
> documentation text).

I wonder whether it would make sense to just remove that line.  Below
an example of what it looks like currently -- the "Documentation:" line
seems rather redundant.  What other could the text be but documentation?

---------
dired-listing-switches is a variable defined in ‘dired.el’.

Its value is "-alh"
Original value was "-al"

  You can customize this variable.
  Probably introduced at or before Emacs version 16.

Documentation:
Switches passed to ‘ls’ for Dired.  MUST contain the ‘l’ option.
May contain all other options that don’t contradict ‘-l’;
may contain even ‘F’, ‘b’, ‘i’ and ‘s’.  See also the variable
‘dired-ls-F-marks-symlinks’ concerning the ‘F’ switch.


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

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On Monday, February 22, 2021 10:58 PM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
>
> I wonder whether it would make sense to just remove that line. Below
> an example of what it looks like currently -- the "Documentation:" line
> seems rather redundant. What other could the text be but documentation?

True. The user obviously expects the documentation when getting help for a
function/variable and the removal of that line makes the Help window less
cluttered.

bug#46702: Link symbol name in Help

[Eli Zaretskii]

> Date: Mon, 22 Feb 2021 21:52:58 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, "46702@debbugs.gnu.org" <46702@debbugs.gnu.org>
> 
> Unrelated to this bug, but maybe an empty line after Documentation:
> too could improve readability (so the header does not merge with the
> actual documentation text).

I'm not sure that's a good idea: "Documentation:" ends in a colon, so
the text should follow it.  Otherwise it might look unrelated.

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On Tuesday, February 23, 2021 4:28 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> I'm not sure that's a good idea: "Documentation:" ends in a colon, so
> the text should follow it. Otherwise it might look unrelated.

What do you think of Lars' idea of removing that line altogether, since
it's obvious the user is looking at the documentation (the user invoked
the command)?

bug#46702: Link symbol name in Help

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 07:09:26 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: "larsi@gnus.org" <larsi@gnus.org>, "46702@debbugs.gnu.org" <46702@debbugs.gnu.org>
> 
> On Tuesday, February 23, 2021 4:28 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> >
> > I'm not sure that's a good idea: "Documentation:" ends in a colon, so
> > the text should follow it. Otherwise it might look unrelated.
> 
> What do you think of Lars' idea of removing that line altogether, since
> it's obvious the user is looking at the documentation (the user invoked
> the command)?

That would work in simple cases, such as this one, but we also have
variables whose value takes a lot of space when printed, and in those
cases we have

  Documentation:
  <the doc string>

  Value:
  <representation of the value>

E.g., try "C-h v char-script-table RET".

bug#46702: Link symbol name in Help

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> That would work in simple cases, such as this one, but we also have
> variables whose value takes a lot of space when printed, and in those
> cases we have
>
>   Documentation:
>   <the doc string>
>
>   Value:
>   <representation of the value>
>
> E.g., try "C-h v char-script-table RET".

Even there, I think removing the "Documentation:" line makes sense --
the "Value:" line clearly demarcates the documentation from the value.

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

bug#46702: Link symbol name in Help

[Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>
> Even there, I think removing the "Documentation:" line makes sense --
> the "Value:" line clearly demarcates the documentation from the value.
>

The line "Its value is shown below." even links to the value.

Changing this line to "Its value is shown below the documentation." where
"below the documentation" is the new link text, and removing the
"Documentation:" line may be a good solution which makes things
really obvious even in the large value case.

bug#46702: Link symbol name in Help

[Eli Zaretskii]

> Date: Wed, 24 Feb 2021 16:29:34 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, "46702@debbugs.gnu.org" <46702@debbugs.gnu.org>
> 
> >
> > Even there, I think removing the "Documentation:" line makes sense --
> > the "Value:" line clearly demarcates the documentation from the value.
> >
> 
> The line "Its value is shown below." even links to the value.
> 
> Changing this line to "Its value is shown below the documentation." where
> "below the documentation" is the new link text, and removing the
> "Documentation:" line may be a good solution which makes things
> really obvious even in the large value case.

I think we are splitting hair and painting the bike shed here.

bug#46702: Link symbol name in Help

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I think we are splitting hair and painting the bike shed here.

Indeed, so I've just removed the "Documentation:" line.  This makes the
output both more compact and less awkward to read, in my opinion.

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

bug#46702: Link symbol name in Help

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Peter Dean <laszlomail@protonmail.com>,  46702@debbugs.gnu.org
> Date: Wed, 24 Feb 2021 17:59:17 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think we are splitting hair and painting the bike shed here.
> 
> Indeed, so I've just removed the "Documentation:" line.  This makes the
> output both more compact and less awkward to read, in my opinion.

I think this change may require rewording the beginning of the doc
strings.  E.g., look at this random sample:

  resize-mini-windows is a variable defined in ‘C source code’.

  Its value is ‘grow-only’

    You can customize this variable.
    This variable was introduced, or its default value was changed, in
    version 25.1 of Emacs.
    Probably introduced at or before Emacs version 21.1.

  How to resize mini-windows (the minibuffer and the echo area).
  A value of nil means don’t automatically resize mini-windows.
  A value of t means resize them to fit the text displayed in them.
  A value of ‘grow-only’, the default, means let mini-windows grow only;
  they return to their normal size when the minibuffer is closed, or the
  echo area becomes empty.

The "How to resize mini-windows..." part begins "out of the blue".
It's actually incorrect English (incomplete sentence), AFAIK.  It
reads okay-ish when the first line is alone, or when the text follows
some heading, like "Documentation:", but that is gone now.

bug#46702: Link symbol name in Help

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>   Its value is ‘grow-only’
>
>     You can customize this variable.
>     This variable was introduced, or its default value was changed, in
>     version 25.1 of Emacs.
>     Probably introduced at or before Emacs version 21.1.
>
>   How to resize mini-windows (the minibuffer and the echo area).
>   A value of nil means don’t automatically resize mini-windows.
>   A value of t means resize them to fit the text displayed in them.
>   A value of ‘grow-only’, the default, means let mini-windows grow only;
>   they return to their normal size when the minibuffer is closed, or the
>   echo area becomes empty.
>
> The "How to resize mini-windows..." part begins "out of the blue".
> It's actually incorrect English (incomplete sentence), AFAIK.  It
> reads okay-ish when the first line is alone, or when the text follows
> some heading, like "Documentation:", but that is gone now.

I don't think the "Documentation:" line helps much here, though.  It's
just an awkward first line.

We've previously discussed rearranging the function/variable output in a
more "readerly" way -- for instance, it's odd that the block of indented
things come before the doc string, because those indented things aren't
what's most vital for normal users to know.

But even if the buffer started with:

  resize-mini-windows is a variable defined in ‘C source code’.

  How to resize mini-windows (the minibuffer and the echo area).
  A value of nil means don’t automatically resize mini-windows.

It'd still be an awkward doc string, because it's just an awkward
semi-sentence.

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

bug#46702: Link symbol name in Help

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: laszlomail@protonmail.com,  46702@debbugs.gnu.org
> Date: Thu, 25 Feb 2021 16:15:03 +0100
> 
> > The "How to resize mini-windows..." part begins "out of the blue".
> > It's actually incorrect English (incomplete sentence), AFAIK.  It
> > reads okay-ish when the first line is alone, or when the text follows
> > some heading, like "Documentation:", but that is gone now.
> 
> I don't think the "Documentation:" line helps much here, though.  It's
> just an awkward first line.

I didn't say we should reinstate that line, did I?

> But even if the buffer started with:
> 
>   resize-mini-windows is a variable defined in ‘C source code’.
> 
>   How to resize mini-windows (the minibuffer and the echo area).
>   A value of nil means don’t automatically resize mini-windows.
> 
> It'd still be an awkward doc string, because it's just an awkward
> semi-sentence.

Which is why I said we may wish rewriting it (and others like it, of
which we have quite a few, I think).