* bug#46702: Link symbol name in Help
@ 2021-02-22 6:05 Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 8:21 ` Andreas Schwab
2021-02-22 15:01 ` Lars Ingebrigtsen
0 siblings, 2 replies; 20+ messages in thread
From: Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-02-22 6:05 UTC (permalink / raw
To: 46702
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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 6:05 bug#46702: Link symbol name in Help Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-02-22 8:21 ` Andreas Schwab
2021-02-22 8:26 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 15:01 ` Lars Ingebrigtsen
1 sibling, 1 reply; 20+ messages in thread
From: Andreas Schwab @ 2021-02-22 8:21 UTC (permalink / raw
To: 46702; +Cc: laszlomail
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."
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 6:05 bug#46702: Link symbol name in Help Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 8:21 ` Andreas Schwab
@ 2021-02-22 15:01 ` Lars Ingebrigtsen
2021-02-22 15:55 ` Eli Zaretskii
1 sibling, 1 reply; 20+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-22 15:01 UTC (permalink / raw
To: Peter Dean; +Cc: 46702
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 15:01 ` Lars Ingebrigtsen
@ 2021-02-22 15:55 ` Eli Zaretskii
2021-02-22 21:34 ` Lars Ingebrigtsen
0 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2021-02-22 15:55 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: laszlomail, 46702
> 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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 15:55 ` Eli Zaretskii
@ 2021-02-22 21:34 ` Lars Ingebrigtsen
2021-02-22 21:52 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 20+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-22 21:34 UTC (permalink / raw
To: Eli Zaretskii; +Cc: laszlomail, 46702
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 21:34 ` Lars Ingebrigtsen
@ 2021-02-22 21:52 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 21:58 ` Lars Ingebrigtsen
2021-02-23 3:28 ` Eli Zaretskii
0 siblings, 2 replies; 20+ messages in thread
From: Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-02-22 21:52 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: Eli Zaretskii, 46702@debbugs.gnu.org
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).
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 21:52 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-02-22 21:58 ` Lars Ingebrigtsen
2021-02-22 22:08 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-23 3:28 ` Eli Zaretskii
1 sibling, 1 reply; 20+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-22 21:58 UTC (permalink / raw
To: Peter Dean; +Cc: 46702@debbugs.gnu.org
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 21:58 ` Lars Ingebrigtsen
@ 2021-02-22 22:08 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 0 replies; 20+ messages in thread
From: Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-02-22 22:08 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: Eli Zaretskii, 46702@debbugs.gnu.org
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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-22 21:52 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 21:58 ` Lars Ingebrigtsen
@ 2021-02-23 3:28 ` Eli Zaretskii
2021-02-23 7:09 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2021-02-23 3:28 UTC (permalink / raw
To: Peter Dean; +Cc: larsi, 46702
> 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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-23 3:28 ` Eli Zaretskii
@ 2021-02-23 7:09 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-23 15:31 ` Eli Zaretskii
0 siblings, 1 reply; 20+ messages in thread
From: Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-02-23 7:09 UTC (permalink / raw
To: Eli Zaretskii; +Cc: larsi@gnus.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)?
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-23 7:09 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-02-23 15:31 ` Eli Zaretskii
2021-02-24 16:09 ` Lars Ingebrigtsen
0 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2021-02-23 15:31 UTC (permalink / raw
To: Peter Dean; +Cc: larsi, 46702
> 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".
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-23 15:31 ` Eli Zaretskii
@ 2021-02-24 16:09 ` Lars Ingebrigtsen
2021-02-24 16:29 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 20+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-24 16:09 UTC (permalink / raw
To: Eli Zaretskii; +Cc: Peter Dean, 46702
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-24 16:09 ` Lars Ingebrigtsen
@ 2021-02-24 16:29 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-24 16:38 ` Eli Zaretskii
0 siblings, 1 reply; 20+ messages in thread
From: Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-02-24 16:29 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: Eli Zaretskii, 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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-24 16:29 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-02-24 16:38 ` Eli Zaretskii
2021-02-24 16:59 ` Lars Ingebrigtsen
0 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2021-02-24 16:38 UTC (permalink / raw
To: Peter Dean; +Cc: larsi, 46702
> 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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-24 16:38 ` Eli Zaretskii
@ 2021-02-24 16:59 ` Lars Ingebrigtsen
2021-02-24 17:05 ` Eli Zaretskii
0 siblings, 1 reply; 20+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-24 16:59 UTC (permalink / raw
To: Eli Zaretskii; +Cc: Peter Dean, 46702
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-24 16:59 ` Lars Ingebrigtsen
@ 2021-02-24 17:05 ` Eli Zaretskii
2021-02-25 15:15 ` Lars Ingebrigtsen
0 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2021-02-24 17:05 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: laszlomail, 46702
> 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.
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-24 17:05 ` Eli Zaretskii
@ 2021-02-25 15:15 ` Lars Ingebrigtsen
2021-02-25 15:29 ` Eli Zaretskii
0 siblings, 1 reply; 20+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-25 15:15 UTC (permalink / raw
To: Eli Zaretskii; +Cc: laszlomail, 46702
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* bug#46702: Link symbol name in Help
2021-02-25 15:15 ` Lars Ingebrigtsen
@ 2021-02-25 15:29 ` Eli Zaretskii
0 siblings, 0 replies; 20+ messages in thread
From: Eli Zaretskii @ 2021-02-25 15:29 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: laszlomail, 46702
> 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).
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2021-02-25 15:29 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-02-22 6:05 bug#46702: Link symbol name in Help Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 8:21 ` Andreas Schwab
2021-02-22 8:26 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 8:38 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 15:01 ` Lars Ingebrigtsen
2021-02-22 15:55 ` Eli Zaretskii
2021-02-22 21:34 ` Lars Ingebrigtsen
2021-02-22 21:52 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-22 21:58 ` Lars Ingebrigtsen
2021-02-22 22:08 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-23 3:28 ` Eli Zaretskii
2021-02-23 7:09 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-23 15:31 ` Eli Zaretskii
2021-02-24 16:09 ` Lars Ingebrigtsen
2021-02-24 16:29 ` Peter Dean via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-02-24 16:38 ` Eli Zaretskii
2021-02-24 16:59 ` Lars Ingebrigtsen
2021-02-24 17:05 ` Eli Zaretskii
2021-02-25 15:15 ` Lars Ingebrigtsen
2021-02-25 15:29 ` Eli Zaretskii
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.