Subject: RE: [External] : bug#60587: Patch for adding links to symbols' help documentation

From: Drew Adams <[email-masked]>
Date: Mon, 23 Jan 2023 16:16:18 +0000

> I don't think "button" is problematic.
> 
> > Drew thinks we should use the same standard term we
> > use everywhere - including in Info: for users it's a
> > link, not a button.
> 
> We use "buttons" as well as "hyperlinks".  See, e.g., the node "Mouse
> References" in the user manual, which basically describes the facility
> Dieter intends to use.

You're right - that node speaks of `"buttons", or
"hyperlinks"'.  And node `Scroll Bars' speaks of
"the scroll bar's up and down buttons".

I think such terminology is old - early/mid 90s.
"Hyperlinks" is OK, but in general they're just
referred to as "links" now, I think.  That is, since
the Internet and web took hold in a general way.

The UI things that actually look like buttons, can
reasonably be called "buttons", especially things
that perform some _action_ other than moving to a
different text location.  I think this applies to
icons in the tool bar and fields in the mode-line
and header line, and it applies to some of the spots
in Customize.  I don't think it's the best term to
use for text links.

That there are some remaining places where Emacs or
Elisp still refers to links as "buttons" isn't a
reason to continue using "button" for links, in new
doc or when updating existing doc (IMO).  My advice
is to progressively move away from such a use of
"button" when doing that.

But if you prefer to continue with "button", so be it.

> > > If the user types "M-x describe-text-properties RET",
> > > will he/she see that there's a button at point?
> I meant the hyperlinks in the *Help* buffer.

I see, thanks.  Yes, I see that - e.g.:

There are text properties here:
  button               (t)
  category             help-symbol-button
  help-args            (symbol-nearest-point)

However, again, this kind of help (showing text
properties) essentially exposes _implementation_
names, so that's no surprise.  Yes, Elisp has
things called "buttons".

Nothing wrong with help doing this, of course.
But that's not a reason why the user doc (e.g.
Emacs manual) should call links there "buttons".

The current change is for Info.  What terminology
does the Info manual use?  Searching for "button"
shows that the only occurrences are for mouse
buttons (physical buttons).  And there are lots
of occurrences of "link".  _All_ mention of what
we're talking about uses "link", never "button".
That's how Info talks about itself and its parts.

Here's a typical use of both terms from the Info
manual.  "Link" is the thing you see and click
(or hit `RET' on).  "Button" is a physical mouse
part that you click.

 >> Now type 'n', or click the middle mouse button
    on the 'Next' link, to visit the next node.

But if you prefer "buttons", "buttons" it is.
Users will understand, either way.