bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

Help windows and Info show quoted symbols linked/highlighted. The quotes
are added to denote the symbol in source docs, but when the symbol is
linked/highlighted then the symbol is already processed for display and
emphasised,  so there is  no need for displaying  the quotes.

Unnecessary characters make the text harder to the read, so the quotes
should be hidden from display in docs. (Can characters be hidden with a face?)

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Thu, 04 Mar 2021 16:57:24 +0000
> From:  scame via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Help windows and Info show quoted symbols linked/highlighted.

Help buffers do, but where did you see that in Info?  Can you show an
example?

> The quotes are added to denote the symbol in source docs, but when
> the symbol is linked/highlighted then the symbol is already
> processed for display and emphasised, so there is no need for
> displaying the quotes.

I disagree.  The quotes indicate that it's a symbol, the link face
indicates that we have more information about that symbol elsewhere.
These are two orthogonal indications, so they complete each other, not
contradict.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> Help buffers do, but where did you see that in Info? Can you show an
> example?

Info does not link, but highlight symbols. BTW, why symbols in info are
not linked to their index entries? E.g. the user could press Enter
on a highlighted symbol to quickly look it up. Why isn't this a thing?

> I disagree. The quotes indicate that it's a symbol, the link face
> indicates that we have more information about that symbol elsewhere.
> These are two orthogonal indications, so they complete each other, not
> contradict.

Well, is this a symbol?  Example from Elisp info:

‘(DISPLAY PLIST)’

or

‘(:foreground "red" :weight bold)’


These have the face Info-quoted like quoted symbols in Info. So the face
indicates this is a quoted entity (not necessarily a symbol).

If we have a face Info-quoted then there is no need for the quotes, because
the quotes are only text markups which are translated to a face, so the quoted
part is highlighted for the user, there is no point in leaving the markup there.

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Drew Adams]

> Help windows and Info show quoted symbols linked/highlighted. The
> quotes are added to denote the symbol in source docs, but when the symbol is
> linked/highlighted then the symbol is already processed for display and
> emphasised,  so there is  no need for displaying  the quotes.
> 
> Unnecessary characters make the text harder to the read, so the quotes
> should be hidden from display in docs. (Can characters be hidden with a
> face?)

No.  Please do not do this.

1. Users can turn off such highlighting.  They still need
   to be able to easily see such things.  The things need
   to stand out.

2. Users need to be able to search for such things, and
   one way to do that is to include the quotes, whether
   with a regexp or a plain-text pattern.

If you personally don't want to see the quotes, then
define some code that hides them.

Emacs itself could optionally have a command/mode to
hide them.  But I, personally, am not in favor of that.
Likewise, for hiding <...>, "...", '...', or any other
such envelopes.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Thu, 04 Mar 2021 17:50:27 +0000
> From: scame <laszlomail@protonmail.com>
> Cc: "46926@debbugs.gnu.org" <46926@debbugs.gnu.org>
> 
> >
> > Help buffers do, but where did you see that in Info? Can you show an
> > example?
> 
> Info does not link, but highlight symbols.

By "highlight", do you mean the special face we use there?  If so,
that's not highlighting.

> BTW, why symbols in info are not linked to their index entries?
> E.g. the user could press Enter on a highlighted symbol to quickly
> look it up. Why isn't this a thing?

I believe this was discussed recently.  But it's a different issue;
the Info manuals provide cross-references where the author thought
they are needed.

> > I disagree. The quotes indicate that it's a symbol, the link face
> > indicates that we have more information about that symbol elsewhere.
> > These are two orthogonal indications, so they complete each other, not
> > contradict.
> 
> Well, is this a symbol?  Example from Elisp info:
> 
> ‘(DISPLAY PLIST)’
> 
> or
> 
> ‘(:foreground "red" :weight bold)’

How is this related to the issue at hand?

> These have the face Info-quoted like quoted symbols in Info. So the face
> indicates this is a quoted entity (not necessarily a symbol).

We could discuss whether the face alone is enough in Info.  My
personal opinion is that it isn't enough: the face we use there
doesn't guarantee any highlighting, because the user could customize
the face to be anything but.

> If we have a face Info-quoted then there is no need for the quotes, because
> the quotes are only text markups which are translated to a face, so the quoted
> part is highlighted for the user, there is no point in leaving the markup there.

I don't think I agree, but maybe someone else will have an opinion?

And what about Help buffers?

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> No. Please do not do this.
>
> 1.  Users can turn off such highlighting. They still need
>     to be able to easily see such things. The things need
>     to stand out.

I meant it could be done with a face, so obviously a face
can be customized.

>
> 2.  Users need to be able to search for such things, and
>     one way to do that is to include the quotes, whether
>     with a regexp or a plain-text pattern.

If we consider Help buffers they usually not that large
that you have to search for symbols in them.

Check out this Help window. It is more tidy and readable
without the unnecessary quotes:

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

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Drew Adams]

> > If we have a face Info-quoted then there is no need for the quotes, because
> > the quotes are only text markups which are translated to a face, so the quoted
> > part is highlighted for the user, there is no point in leaving the markup there.
> 
> I don't think I agree, but maybe someone else will have an opinion?

I provided an opinion.

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Drew Adams]

> > 2.  Users need to be able to search for such things, and
> >     one way to do that is to include the quotes, whether
> >     with a regexp or a plain-text pattern.
> 
> If we consider Help buffers they usually not that large
> that you have to search for symbols in them.

As one user, I do sometimes search *Help* buffers.
Consider `C-h m', with multiple minor modes on.
`C-s' is a quick way to get around (as is `TAB').

> Check out this Help window. It is more tidy and readable
> without the unnecessary quotes:
> 
> https://urldefense.com/v3/__https://i.imgur.com/xiHv8lr.png__;!!GqivPVa
> 7Brio!KAfq4VYD_ewenpCsVCQ3R1KgAq-FHkBBTw2SyBUNvuGNuquMET3snfuX36dtA5fB$

No improvement, IMO.  No tidier, no more readable.
But different people have different preferences.

Don't get me wrong.  In some cases it can be useful
to replace the use of some envelope with just
highlighting (in some way) the enveloped text.

I do that with emphasized text in Info, for example.
That is, text such as _foo bar_.  But that choice is
controlled by an option, `Info-fontify-emphasis-flag'.

(All such things need to be optional, IMO.)

In some cases (e.g. "...") it generally makes sense
to highlight also the envelope char.  In other cases
(e.g. ‘...’, `...', <...>, '...'), it makes sense to
not highlight it (i.e., highlight only the text that's
enveloped).

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I don't think I agree, but maybe someone else will have an opinion?

I don't have an opinion here, really, but I think the example posted
without the quotes looked nicer.

On the other hand, since we quote symbols like that all over Emacs,
removing them just in info mode is perhaps not optimal.  

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

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> We could discuss whether the face alone is enough in Info. My
> personal opinion is that it isn't enough: the face we use there
> doesn't guarantee any highlighting, because the user could customize
> the face to be anything but.

There can be an option to show quotes or not. If the user removes
the face's coloring, etc. then he can turn on displaying quotes.

Currently, the face has attributes by default, so the default experience
can benefit from the cleaner look without quotes.

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> As one user, I do sometimes search Help buffers.
> Consider `C-h m', with multiple minor modes on.
> `C-s' is a quick way to get around (as is `TAB').

Yes, but you don't usually search for `, do you? Because
in my experience it's trivial to find things in Help
without having to type a quote.

Anyway, there can be an option to display the quotes if one
likes that better.

>
> No improvement, IMO. No tidier, no more readable.
> But different people have different preferences.

Well, Lars in this thread thinks it's better, so it's not just me.

But naturally there should be an option for it if one prefers
the old look.

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 936 bytes --]

> > I don't think I agree, but maybe someone else will have an opinion?
> 
> I don't have an opinion here, really, but I think
> the example posted without the quotes looked nicer.

Nicer than what?

Did you compare with an equivalent screenshot with
the quotes present?  Don't be misled by the fact
that the font is different from (arguably "nicer"
than) the default Emacs font.

Compare with & without quotes using the same config,
same fonts.  Do you really think absence of quotes
looks nicer?  How much so?  With link highlighting
the quotes are nearly imperceptible, IMO.  (With no
highlighting they become even more important.)

And of course we don't quote (`...') non-sexps and
non-keys.  So the text of a link without quotes can
be ambiguous as to whether it provides sexp/key
info or is just some text with a link.

See attached, for apples-to-apples comparison.
Same font, same size, default fonts.

[-- Attachment #2: throw-bug-46926-quotes.png --]
[-- Type: image/png, Size: 41902 bytes --]

[-- Attachment #3: throw-bug-46926-no-quotes.png --]
[-- Type: image/png, Size: 41672 bytes --]

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Help windows and Info show quoted symbols linked/highlighted. The quotes
  > are added to denote the symbol in source docs, but when the symbol is
  > linked/highlighted then the symbol is already processed for display and
  > emphasised,  so there is  no need for displaying  the quotes.

Sometimes there is.
 
  > Unnecessary characters make the text harder to the read, so the quotes
  > should be hidden from display in docs.

You're proposing to achieve a minor benefit by risking confusion.
This is a bad sort of bet.

To be sure that no significant serious confusion would result would
require a careful study of all the sorts of situations that can occur.
In the absence of that, I say no.

In fact, I know of a situation that would become unclear: @code{FOO}
would become indistinguishable from @var{foo}.

Why would capital letters appear in @code{}?  For shell variables with
upper-case names.



-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> I don't think I agree, but maybe someone else will have an opinion?
>
> I don't have an opinion here, really, but I think the example posted
> without the quotes looked nicer.

Yes, I must agree that it looks far better.

The point of `quotes' is to make these symbols stand out in comparison
to the surrounding text.  But the linking face we use is already very
aggressive: not just blue but also underlined.  So I think this is by
far already highlighted enough, which means the quotes are superfluous
and should be removed.

Speaking strictly about help-mode, I think removing them is therefore
just sound typography that will make it easier to read the help text.

> On the other hand, since we quote symbols like that all over Emacs,
> removing them just in info mode is perhaps not optimal.

I have no opinion about Info, as there we do not have any linking going
on.  IOW, the extra emphasis the `quotes' add is fine in that context.

About the only drawback I see to removing them from help is what you
say: that we lose some consistency as compared to the rest of Emacs.
IMO, this price is well worth paying to get cleaner help buffers.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The point of `quotes' is to make these symbols stand out in comparison
  > to the surrounding text.

The purpose of quotes in Texinfo output is to make semantic
distinctions.  In other words, to show what kind of role that text
plays in the program being documented.

Texinfo has many constructs for semantic markup.  Some of these constructs
display quotes, in some output formats, to distinguish them from other
constructs.

Since those distinctions are important to help users understand the
documentation, changes in the design of these distinctions ought to
be made by Texinfo experts as part of the Texinfo package.  Please
don't change them elsewhere (for instance, in Emacs).


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> The purpose of quotes in Texinfo output is to make semantic
> distinctions. In other words, to show what kind of role that text
> plays in the program being documented.

In the main body of the Help text only symbols are linked AFAIK. Is
that right?

So the quotes don't convey any extra meaning and the symbols are linked,
so they can be clicked to instantly see their documentation. The quotes
are just extra noise in the rendered output, breaking the visual flow of
the text unnecessarily.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Stefan Kangas]

scame <laszlomail@protonmail.com> writes:

>> The purpose of quotes in Texinfo output is to make semantic
>> distinctions. In other words, to show what kind of role that text
>> plays in the program being documented.
>
> In the main body of the Help text only symbols are linked AFAIK.

Richard is discussing Texinfo, but it seems like you are discussing
`help-mode'.  I would suggest not treating them as the same thing.
There are some similarities, of course, but also important differences.

> Is that right?

Pretty much, but see `help-make-xrefs' for the full story.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Cc: "46926@debbugs.gnu.org" <46926@debbugs.gnu.org>,
>  "larsi@gnus.org" <larsi@gnus.org>, Stefan Kangas <stefan@marxist.se>
> Date: Sat, 13 Mar 2021 06:08:31 +0000
> From:  scame via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> >
> > The purpose of quotes in Texinfo output is to make semantic
> > distinctions. In other words, to show what kind of role that text
> > plays in the program being documented.
> 
> In the main body of the Help text only symbols are linked AFAIK. Is
> that right?
> 
> So the quotes don't convey any extra meaning and the symbols are linked,
> so they can be clicked to instantly see their documentation. The quotes
> are just extra noise in the rendered output, breaking the visual flow of
> the text unnecessarily.

Help buffers are not directly related to Texinfo.  However, we had
already some complaints in the past about the differences between
those two, so I think it would make sense not to make them diverge any
further.

Your opinion that the quotes are visual noise is noted (you expressed
it several times already), but it doesn't mean we must accept it.

Since the quotes are present in the original doc strings (and will
stay there, for sure), the implementation of your proposal would be to
remove them when we generate the "buttons" (a.k.a. "links") for them
in the Help buffer.  So, if people feel that removing the quotes could
be desired by some users, how about making it optional, by default
off?

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> Richard is discussing Texinfo, but it seems like you are discussing
> `help-mode'. I would suggest not treating them as the same thing.
> There are some similarities, of course, but also important differences.


Yes, I'm discussing Help, because that is what this bug is about.

No one suggests removing the quotes from texinfo files. They should be
hidden by emacs when displaying help, because in 28 the symbols are linked
in Help buffers, so they stand out already and they can be clicked to get
immediate help about them.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> Since the quotes are present in the original doc strings (and will
> stay there, for sure), the implementation of your proposal would be to
> remove them when we generate the "buttons" (a.k.a. "links") for them
> in the Help buffer. So, if people feel that removing the quotes could
> be desired by some users, how about making it optional, by default
> off?

The aim of this bug to make the default epxerience cleaner.

In the first place it is not developers who should decide these things,
but visual designers. E.g. I guess Gnome has some visual designers who
create the Gnome look. They can be asked, but I'm pretty sure they
will say the cleaner look is better for users.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Sat, 13 Mar 2021 07:51:11 +0000
> From: scame <laszlomail@protonmail.com>
> Cc: "rms@gnu.org" <rms@gnu.org>, "46926@debbugs.gnu.org" <46926@debbugs.gnu.org>, "larsi@gnus.org" <larsi@gnus.org>, "stefan@marxist.se" <stefan@marxist.se>
> 
> > Since the quotes are present in the original doc strings (and will
> > stay there, for sure), the implementation of your proposal would be to
> > remove them when we generate the "buttons" (a.k.a. "links") for them
> > in the Help buffer. So, if people feel that removing the quotes could
> > be desired by some users, how about making it optional, by default
> > off?
> 
> The aim of this bug to make the default epxerience cleaner.
> 
> In the first place it is not developers who should decide these things,
> but visual designers. E.g. I guess Gnome has some visual designers who
> create the Gnome look. They can be asked, but I'm pretty sure they
> will say the cleaner look is better for users.

That sounds like "my way or the highway" to me.  Not very
constructive, I'm afraid.

Does anyone else here think the compromise I proposed could have some
merit?

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> That sounds like "my way or the highway" to me. Not very
> constructive, I'm afraid.

Not at all. I mean it to be constructive the emacs project should invite
a visual designer of Gnome to improve the default look.

The default look is pretty ugly, no offense. I know people did their
best to come up with something agreeable, but development and visual
design are to different areas for good reason. Good developers are
usually not good visual designers.


> Does anyone else here think the compromise I proposed could have some
> merit?

If changing the default is refused then I agree a config
option is a  good compromise, because then people can see its effect
at everyday usage and they can judge its merits if they change the option.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Sat, 13 Mar 2021 16:24:22 +0000
> From: scame <laszlomail@protonmail.com>
> Cc: "rms@gnu.org" <rms@gnu.org>, "46926@debbugs.gnu.org" <46926@debbugs.gnu.org>, "larsi@gnus.org" <larsi@gnus.org>, "stefan@marxist.se" <stefan@marxist.se>
> 
> >
> > That sounds like "my way or the highway" to me. Not very
> > constructive, I'm afraid.
> 
> Not at all. I mean it to be constructive the emacs project should invite
> a visual designer of Gnome to improve the default look.

If someone can reach out to them and ask them to be our HFI experts,
that'd be welcome, I think.  For now we have to get by with what we
have.

> If changing the default is refused then I agree a config
> option is a  good compromise, because then people can see its effect
> at everyday usage and they can judge its merits if they change the option.

Thanks.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> If someone can reach out to them and ask them to be our HFI experts,
> that'd be welcome, I think.

RMS may have enough pull to do that. The expert doesn't need to follow
the emacs-devel list all the time, but if from time to time he can be
consulted on such issues, deciding between variants, etc. that itself
could be quite useful.

> For now we have to get by with what we have.

Until the project has such an expert consultant, wouldn't asking the
emacs community be a better way to decide such issues? E.g. running
a vote on /r/emacs.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Stefan Kangas]

scame <laszlomail@protonmail.com> writes:

> Not at all. I mean it to be constructive the emacs project should invite
> a visual designer of Gnome to improve the default look.

I agree that help from a graphical/UIX designer would be very good.  But
I don't know how to procure such help.  It seems like Emacs has had this
need for the last 20 years or so, but someone has yet to step up.

> The default look is pretty ugly, no offense.

I don't think people are easily offended even by sharp criticism around
here.  But it is better to be more concrete, as it is hard to do
something about the rather abstract statement that Emacs is "ugly".

For example, the suggestion you made in this bug report is concrete and
actionable.  I invite you to make more such proposals that can help us
move forward in this area.

>> Does anyone else here think the compromise I proposed could have some
>> merit?
>
> If changing the default is refused then I agree a config
> option is a  good compromise, because then people can see its effect
> at everyday usage and they can judge its merits if they change the option.

Agreed.  I have explained previously why I think it would be better if
the option was on by default, but baby steps are still steps.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Sat, 13 Mar 2021 17:05:27 +0000
> From: scame <laszlomail@protonmail.com>
> Cc: "rms@gnu.org" <rms@gnu.org>, "46926@debbugs.gnu.org" <46926@debbugs.gnu.org>, "larsi@gnus.org" <larsi@gnus.org>, "stefan@marxist.se" <stefan@marxist.se>
> 
> Until the project has such an expert consultant, wouldn't asking the
> emacs community be a better way to decide such issues? E.g. running
> a vote on /r/emacs.

No, because offering an opt-in behavior is a better way of letting
users to try the feature.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

> > a visual designer of Gnome to improve the default look.
>
> I agree that help from a graphical/UIX designer would be very good. But
> I don't know how to procure such help.

Someone with a reddit account can ask the emacs subreddit. I checked and
there are 50,000 readers there, so there is a good chance that at least
some of them work in the field of UI design.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > The purpose of quotes in Texinfo output is to make semantic
  > > distinctions. In other words, to show what kind of role that text
  > > plays in the program being documented.

  > In the main body of the Help text only symbols are linked AFAIK. Is
  > that right?

  > So the quotes don't convey any extra meaning and the symbols are linked,
  > so they can be clicked to instantly see their documentation. The quotes
  > are just extra noise in the rendered output, breaking the visual flow of
  > the text unnecessarily.

Can you please tell me how I can look at an instance of what you mean?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#46926: Remove quotes from the highlighted symbols list

[Aleksandr Petrosyan]

Dear all, 

UI designer from KDE/Qt/Maui. 

I agree that there are orthogonal design decisions at play here: quotes indicate that the object is a symbol. Then the link face indicates that it is also something that can be expanded upon. However, the quotes, while useful for “someone in the know”, are distracting in text. 

My preferred solution, would be to use a code face, specifically for symbols and highlight the symbol such that it appears as every other symbol does in emacs lisp. One can inherit the monospace font from GTK to distinguish from documentation text. The link... it can be anything: it could be the documentation for the symbol, or the file which it’s defined in. A user needs to know *exactly* what’s going to happen if they click, so if it’s going to visit e.g. Python.el, and not the documentation of what Python.el is part of, it’s better to say explicitly “visit elisp file”. A button can serve better, but emacs has... ugly buttons and doesn’t use them very consistently, so a link is fine. 


Sincerely 
Aleksandr Petrosyan

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Dmitry Gutov]

On 13.03.2021 19:08, Eli Zaretskii wrote:
>> Until the project has such an expert consultant, wouldn't asking the
>> emacs community be a better way to decide such issues? E.g. running
>> a vote on /r/emacs.
> No, because offering an opt-in behavior is a better way of letting
> users to try the feature.

Perhaps these two actions can be combined?

We have had a UI professional chime in here now, BTW.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Cc: 46926@debbugs.gnu.org, larsi@gnus.org, stefan@marxist.se, rms@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 15 Mar 2021 19:28:34 +0200
> 
> On 13.03.2021 19:08, Eli Zaretskii wrote:
> >> Until the project has such an expert consultant, wouldn't asking the
> >> emacs community be a better way to decide such issues? E.g. running
> >> a vote on /r/emacs.
> > No, because offering an opt-in behavior is a better way of letting
> > users to try the feature.
> 
> Perhaps these two actions can be combined?

How would you propose to combine them?

> We have had a UI professional chime in here now, BTW.

Good news.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Dmitry Gutov]

On 15.03.2021 19:51, Eli Zaretskii wrote:
>>>> Until the project has such an expert consultant, wouldn't asking the
>>>> emacs community be a better way to decide such issues? E.g. running
>>>> a vote on /r/emacs.
>>> No, because offering an opt-in behavior is a better way of letting
>>> users to try the feature.
>> Perhaps these two actions can be combined?
> How would you propose to combine them?

We add the option, announce it, and in 2-4 weeks ask people for their 
opinion based on their experience with the changed UI.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Stefan Kangas]

Dmitry Gutov <dgutov@yandex.ru> writes:

> We add the option, announce it, and in 2-4 weeks ask people for their
> opinion based on their experience with the changed UI.

Sounds good to me.

IOW, it would follow a similar procedure to the one we used for "M-o".

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Cc: laszlomail@protonmail.com, 46926@debbugs.gnu.org, larsi@gnus.org,
>  stefan@marxist.se, rms@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 16 Mar 2021 01:20:27 +0200
> 
> On 15.03.2021 19:51, Eli Zaretskii wrote:
> >>>> Until the project has such an expert consultant, wouldn't asking the
> >>>> emacs community be a better way to decide such issues? E.g. running
> >>>> a vote on /r/emacs.
> >>> No, because offering an opt-in behavior is a better way of letting
> >>> users to try the feature.
> >> Perhaps these two actions can be combined?
> > How would you propose to combine them?
> 
> We add the option, announce it, and in 2-4 weeks ask people for their 
> opinion based on their experience with the changed UI.

I don't see how this is different from offering an opt-in behavior, so
I'm okay with this.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 15 Mar 2021 21:37:00 -0500
> Cc: laszlomail@protonmail.com, 46926@debbugs.gnu.org, larsi@gnus.org, 
> 	rms@gnu.org
> 
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
> > We add the option, announce it, and in 2-4 weeks ask people for their
> > opinion based on their experience with the changed UI.
> 
> Sounds good to me.
> 
> IOW, it would follow a similar procedure to the one we used for "M-o".

I hope not, because we are at an impasse there now.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I hope not, because we are at an impasse there now.

FWIW, I don't see any impasse.  The experiment was successfully carried out, and
has allowed us to gather feedback on which to base a final decision.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 15 Mar 2021 22:51:47 -0500
> Cc: dgutov@yandex.ru, laszlomail@protonmail.com, 46926@debbugs.gnu.org, 
> 	larsi@gnus.org, rms@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I hope not, because we are at an impasse there now.
> 
> FWIW, I don't see any impasse.  The experiment was successfully carried out, and
> has allowed us to gather feedback on which to base a final decision.

Maybe I'm missing something, but didn't Lars say a few days ago that
(almost) no feedback was received?  And if we gathered enough
feedback, then why are we once again disputing whether "M-o M-o" is an
important binding, and if so, where to move it?

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Gregory Heytings]

>>> I hope not, because we are at an impasse there now.
>>
>> FWIW, I don't see any impasse.  The experiment was successfully carried 
>> out, and has allowed us to gather feedback on which to base a final 
>> decision.
>
> Maybe I'm missing something, but didn't Lars say a few days ago that 
> (almost) no feedback was received?
>

Yes, and this was the expected outcome of the experiment.  The experiment 
said: "If the removal of this key binding doesn't annoy too many people". 
So if (almost) no feedback is received, it means that it doesn't annoy to 
many people, IOW, that the experiment was successful, and that the key 
binding can be removed.

>
> And if we gathered enough feedback, then why are we once again disputing 
> whether "M-o M-o" is an important binding, and if so, where to move it?
>

I don't see any dispute.

You (and two other people) mentioned that you want to keep the 
functionality of "M-o M-o" in vanilla Emacs.

Stefan M explained that "M-o M-o" = font-lock-fontify-block does not work 
well, and that he would like to deprecate it.

I proposed a font-lock-update command that would be bound on "C-x x f", 
and said that while the "C-x x f" binding is less convenient than "M-o 
M-o", this regression is (largely?) compensated by the fact that 
font-lock-update works correctly, unlike font-lock-fontify-block. 
Moreover, the font-lock-update command is also more general, as it can be 
used to correctly toggle Font Lock mode, which M-x font-lock-mode can't 
do.

Nobody replied to that proposal (yet?).

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Tue, 16 Mar 2021 13:01:36 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: 46926@debbugs.gnu.org
> 
> > And if we gathered enough feedback, then why are we once again disputing 
> > whether "M-o M-o" is an important binding, and if so, where to move it?
> >
> 
> I don't see any dispute.
> 
> You (and two other people) mentioned that you want to keep the 
> functionality of "M-o M-o" in vanilla Emacs.
> 
> Stefan M explained that "M-o M-o" = font-lock-fontify-block does not work 
> well, and that he would like to deprecate it.
> 
> I proposed a font-lock-update command that would be bound on "C-x x f", 
> and said that while the "C-x x f" binding is less convenient than "M-o 
> M-o", this regression is (largely?) compensated by the fact that 
> font-lock-update works correctly, unlike font-lock-fontify-block. 
> Moreover, the font-lock-update command is also more general, as it can be 
> used to correctly toggle Font Lock mode, which M-x font-lock-mode can't 
> do.

That's the "dispute" I alluded to.  If the word "dispute" is
unfortunate here, I take it back, but the main point remains: the
issue is still under discussion, with new aspects being revealed and
discussed, so it doesn't sound like we gathered enough feedback to
allow us to make a decision, not yet anyway.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Dmitry Gutov]

On 16.03.2021 05:36, Eli Zaretskii wrote:
>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Mon, 15 Mar 2021 21:37:00 -0500
>> Cc: laszlomail@protonmail.com, 46926@debbugs.gnu.org, larsi@gnus.org,
>> 	rms@gnu.org
>>
>> Dmitry Gutov <dgutov@yandex.ru> writes:
>>
>>> We add the option, announce it, and in 2-4 weeks ask people for their
>>> opinion based on their experience with the changed UI.
>>
>> Sounds good to me.
>>
>> IOW, it would follow a similar procedure to the one we used for "M-o".
> 
> I hope not, because we are at an impasse there now.

The procedure would be a bit different, obviously.

But speaking of 'M-o', even if we end up reverting the change because we 
receive enough evidence of the change being problematic, that wouldn't 
characterize the approach as bad. It would just reach one of its 
possible conclusions, as any good scientific experiment should.

What could reflect on the approach poorly, is if, for example, we follow 
it, then keep the change because nobody brings up significant problems, 
and then, after Emacs 28 is released, we find out about some big 
breakage caused by the change.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Dmitry Gutov]

On 16.03.2021 05:32, Eli Zaretskii wrote:
>> Cc: laszlomail@protonmail.com, 46926@debbugs.gnu.org, larsi@gnus.org,
>>   stefan@marxist.se, rms@gnu.org
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> Date: Tue, 16 Mar 2021 01:20:27 +0200
>>
>> On 15.03.2021 19:51, Eli Zaretskii wrote:
>>>>>> Until the project has such an expert consultant, wouldn't asking the
>>>>>> emacs community be a better way to decide such issues? E.g. running
>>>>>> a vote on /r/emacs.
>>>>> No, because offering an opt-in behavior is a better way of letting
>>>>> users to try the feature.
>>>> Perhaps these two actions can be combined?
>>> How would you propose to combine them?
>>
>> We add the option, announce it, and in 2-4 weeks ask people for their
>> opinion based on their experience with the changed UI.
> 
> I don't see how this is different from offering an opt-in behavior, so
> I'm okay with this.

Simply saying "let's make it opt-in" closes the door on the discussion 
of the subsequent change of the default, which is often what reporters 
care about in discussions like this.

But if we say "let's make it opt-in then discuss the change later", that 
has a higher chance of making both sides happier. And helps us gather 
feedback backed by some usage experience.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> Simply saying "let's make it opt-in" closes the door on the discussion
> of the subsequent change of the default, which is often what reporters
> care about in discussions like this.

The UI pro agreed that not showing the quotes is better for the user.

How about hiding the quotes by default, but adding an option to restore
them if one prefers that?

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Gregory Heytings]

>> You (and two other people) mentioned that you want to keep the 
>> functionality of "M-o M-o" in vanilla Emacs.
>>
>> Stefan M explained that "M-o M-o" = font-lock-fontify-block does not 
>> work well, and that he would like to deprecate it.
>>
>> I proposed a font-lock-update command that would be bound on "C-x x f", 
>> and said that while the "C-x x f" binding is less convenient than "M-o 
>> M-o", this regression is (largely?) compensated by the fact that 
>> font-lock-update works correctly, unlike font-lock-fontify-block. 
>> Moreover, the font-lock-update command is also more general, as it can 
>> be used to correctly toggle Font Lock mode, which M-x font-lock-mode 
>> can't do.
>
> That's the "dispute" I alluded to.  If the word "dispute" is unfortunate 
> here, I take it back, but the main point remains: the issue is still 
> under discussion, with new aspects being revealed and discussed, so it 
> doesn't sound like we gathered enough feedback to allow us to make a 
> decision, not yet anyway.
>

As far as I can see, all aspects have been revealed and discussed, but the 
discussion has stalled.  In short, font-lock-fontify-buffer and 
font-lock-fontify-block are "defined by their implementation" as Stefan M 
said, which means that they don't work as they should.  The command I 
proposed is short (five lines), and uses font-lock-fontify-region, which 
does not have that problem.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Cc: laszlomail@protonmail.com, 46926@debbugs.gnu.org, larsi@gnus.org,
>  rms@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 16 Mar 2021 17:41:10 +0200
> 
> But speaking of 'M-o', even if we end up reverting the change because we 
> receive enough evidence of the change being problematic, that wouldn't 
> characterize the approach as bad. It would just reach one of its 
> possible conclusions, as any good scientific experiment should.
> 
> What could reflect on the approach poorly, is if, for example, we follow 
> it, then keep the change because nobody brings up significant problems, 
> and then, after Emacs 28 is released, we find out about some big 
> breakage caused by the change.

I agree: what you describe above is not a failure of the procedure.
The failure is if we are unable to make a decision.  And from what
I've seen we might be there with the M-o issue.  That's why I hope
this one will be different.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Maybe I'm missing something, but didn't Lars say a few days ago that
> (almost) no feedback was received?

There were very few complaints about the removed keystrokes, yes.  But
that's different from getting no feedback.

> And if we gathered enough feedback, then why are we once again
> disputing whether "M-o M-o" is an important binding, and if so, where
> to move it?

Are we disputing anything about `M-o M-o'?  Questions were raised about
what the use case of `font-lock-fontify-block' was (because it's a
command that some people have never used, and some people seem to find
very useful).  Which is one of the things this process seems to be handy
at clarifying.

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

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

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

>
> Are we disputing anything about`M-o M-o'? Questions were raised about what the use case of`font-lock-fontify-block' was (because it's a
> command that some people have never used, and some people seem to find
> very useful). Which is one of the things this process seems to be handy
> at clarifying.
>

Could you all who discuss the M-o problem take this discussion off from
bug46926's thread? For those of us who follow this specific bug, details
of the M-o  discussion is unrelated noise. Thanks.

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Eli Zaretskii]

> Date: Wed, 17 Mar 2021 06:00:33 +0000
> From: scame <laszlomail@protonmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "46926@debbugs.gnu.org" <46926@debbugs.gnu.org>, "rms@gnu.org" <rms@gnu.org>
> 
> Could you all who discuss the M-o problem take this discussion off from
> bug46926's thread? For those of us who follow this specific bug, details
> of the M-o  discussion is unrelated noise. Thanks.

You are asking for the impossible.  When some side issue arises in the
midst of a discussion, people tend to use the same thread to discuss
those side issues.  As long as the main discussion doesn't get
derailed, and the side messages are relevant, there's nothing we can
do about that.  We are all human.

You will have to filter out the messages that are noise for you, as
everyone else does.

(Of course, if the side issue is off-topic here, those who raise it
should be asked to take that elsewhere.  This isn't such a case,
though.)

bug#46926: [External] : bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Drew Adams]

> Could you all who discuss the M-o problem take this discussion off from
> bug46926's thread? For those of us who follow this specific bug, details
> of the M-o  discussion is unrelated noise. Thanks.

+1

bug#46926: Remove the quotes from highlighted/linked symbols when displaying docs

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> No, because offering an opt-in behavior is a better way of letting
> users to try the feature.

I've now added this as `help-clean-buttons' in Emacs 29.

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