bug#46702: Link symbol name in Help

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Emacs - Bugs mailing list
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.



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Andreas Schwab-2
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, [hidden email]
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Emacs - Bugs mailing list

>
> 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.



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Emacs - Bugs mailing list

> > 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.



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Eli Zaretskii
In reply to this post by Emacs - Bugs mailing list
> From: Lars Ingebrigtsen <[hidden email]>
> Date: Mon, 22 Feb 2021 16:01:35 +0100
> Cc: [hidden email]
>
> (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.



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Emacs - Bugs mailing list
On Monday, February 22, 2021 10:34 PM, Lars Ingebrigtsen <[hidden email]> 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).



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Lars Ingebrigtsen
Peter Dean <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Emacs - Bugs mailing list
On Monday, February 22, 2021 10:58 PM, Lars Ingebrigtsen <[hidden email]> 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.




Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Eli Zaretskii
In reply to this post by Emacs - Bugs mailing list
> Date: Tue, 23 Feb 2021 07:09:26 +0000
> From: Peter Dean <[hidden email]>
> Cc: "[hidden email]" <[hidden email]>, "[hidden email]" <[hidden email]>
>
> On Tuesday, February 23, 2021 4:28 AM, Eli Zaretskii <[hidden email]> 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".



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Lars Ingebrigtsen
Eli Zaretskii <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Emacs - Bugs mailing list
>
> 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.



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Eli Zaretskii
> Date: Wed, 24 Feb 2021 16:29:34 +0000
> From: Peter Dean <[hidden email]>
> Cc: Eli Zaretskii <[hidden email]>, "[hidden email]" <[hidden email]>
>
> >
> > 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.



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Lars Ingebrigtsen
Eli Zaretskii <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#46702: Link symbol name in Help

Eli Zaretskii
> From: Lars Ingebrigtsen <[hidden email]>
> Cc: [hidden email],  [hidden email]
> 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).