Perhaps rearrange *Help* buffer a bit?

Perhaps rearrange *Help* buffer a bit?

[Lars Ingebrigtsen]

I think Drew (or somebody?) mentioned this in a bug report the other
day: The way the automated stuff is arranged in the *Help* buffer is
perhaps not optimal.

Consider:

----

cadr is a compiled Lisp function in ‘subr.el’.

(cadr X)

  This function has a compiler macro ‘internal--compiler-macro-cXXr’.
  Probably introduced at or before Emacs version 20.

Return the car of the cdr of X.

----

car is a built-in function in ‘C source code’.

(car LIST)

  Probably introduced at or before Emacs version 1.2.
  This function does not change global state, including the match data.

Return the car of LIST.  If arg is nil, return nil.
Error if arg is not nil and not a cons cell.  See also ‘car-safe’.

See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
Lisp concepts such as car, cdr, cons cell and list.

----

So the thought here is that those indented lines isn't what's most
interesting to the user.  The compiler macro stuff is interesting to
about two people in the world, and the "introduced at or before" to
seven.  What people want to know is the calling convention (line 3) and
the stuff a human has lovingly written (starting in line 8 in both these
examples).

The first line is perhaps not vital for people to know either, but since
that's what I use to jump to function definitions, it's useful.  (But
perhaps a command that's just take us there is even better.)

Anyway, what about rearranging this a bit so that the stuff the users
are interested in comes first?

So...  something like...

----

cadr is a compiled Lisp function in ‘subr.el’.

(cadr X)

Return the car of the cdr of X.

--
(This function has a compiler macro ‘internal--compiler-macro-cXXr’.
Probably introduced at or before Emacs version 20.)

----

The automatic coda separated out in a separate parenthetical section?
Or with a dimmer colour?

Let the bike-shedding commence!

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

RE: Perhaps rearrange *Help* buffer a bit?

[Drew Adams]

> I think Drew (or somebody?) mentioned this in a bug report the other
> day: The way the automated stuff is arranged in the *Help* buffer is
> perhaps not optimal.

Yes, bug #36478.
Perhaps this should be merged.
Seems to be essentially a duplicate.

RE: Perhaps rearrange *Help* buffer a bit?

[Drew Adams]

> > I think Drew (or somebody?) mentioned this in a bug report the other
> > day: The way the automated stuff is arranged in the *Help* buffer is
> > perhaps not optimal.
> 
> Yes, bug #36478.
> Perhaps this should be merged.
> Seems to be essentially a duplicate.

Sorry; I thought I was reading your msg in a bug thread.

bug#36478: Perhaps rearrange *Help* buffer a bit?

[Stefan Monnier]

> I think Drew (or somebody?) mentioned this in a bug report the other
> day: The way the automated stuff is arranged in the *Help* buffer is
> perhaps not optimal.

>   This function has a compiler macro ‘internal--compiler-macro-cXXr’.
>   Probably introduced at or before Emacs version 20.
[...]
>   Probably introduced at or before Emacs version 1.2.
>   This function does not change global state, including the match data.
[...]
> So the thought here is that those indented lines isn't what's most
> interesting to the user.

I recently reworked the generation of this text specifically to try and
make it easier to tweak it.

> Anyway, what about rearranging this a bit so that the stuff the users
> are interested in comes first?
[...]
> Let the bike-shedding commence!

Here's my favorite color: 
- don't move it to the end, because it's much too far.
- hide it by default, with some obvious-enough button-like thingy to
  expand it on demand.
- maybe the first line could also be moved into this "metadata" block.
- These *Help* buffers would benefit from a bit of face-lift (e.g. put
  a different face on the metadata part, yet another on the
  calling-convention example, ...).


        Stefan

Re: Perhaps rearrange *Help* buffer a bit?

[Stefan Monnier]

> I think Drew (or somebody?) mentioned this in a bug report the other
> day: The way the automated stuff is arranged in the *Help* buffer is
> perhaps not optimal.

>   This function has a compiler macro ‘internal--compiler-macro-cXXr’.
>   Probably introduced at or before Emacs version 20.
[...]
>   Probably introduced at or before Emacs version 1.2.
>   This function does not change global state, including the match data.
[...]
> So the thought here is that those indented lines isn't what's most
> interesting to the user.

I recently reworked the generation of this text specifically to try and
make it easier to tweak it.

> Anyway, what about rearranging this a bit so that the stuff the users
> are interested in comes first?
[...]
> Let the bike-shedding commence!

Here's my favorite color: 
- don't move it to the end, because it's much too far.
- hide it by default, with some obvious-enough button-like thingy to
  expand it on demand.
- maybe the first line could also be moved into this "metadata" block.
- These *Help* buffers would benefit from a bit of face-lift (e.g. put
  a different face on the metadata part, yet another on the
  calling-convention example, ...).


        Stefan

Re: Perhaps rearrange *Help* buffer a bit?

[Basil L. Contovounesios]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I think Drew (or somebody?) mentioned this in a bug report the other
> day: The way the automated stuff is arranged in the *Help* buffer is
> perhaps not optimal.
>
> Consider:
>
> ----
>
> cadr is a compiled Lisp function in ‘subr.el’.
>
> (cadr X)
>
>   This function has a compiler macro ‘internal--compiler-macro-cXXr’.
>   Probably introduced at or before Emacs version 20.
>
> Return the car of the cdr of X.
>
> ----
>
> car is a built-in function in ‘C source code’.
>
> (car LIST)
>
>   Probably introduced at or before Emacs version 1.2.
>   This function does not change global state, including the match data.
>
> Return the car of LIST.  If arg is nil, return nil.
> Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
>
> See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
> Lisp concepts such as car, cdr, cons cell and list.
>
> ----
>
> So the thought here is that those indented lines isn't what's most
> interesting to the user.  The compiler macro stuff is interesting to
> about two people in the world, and the "introduced at or before" to
> seven.

Don't forget me!

> What people want to know is the calling convention (line 3) and
> the stuff a human has lovingly written (starting in line 8 in both these
> examples).

And in the case of variables, the trailing "You can _customize_ this
variable" which indicates a user option.

And maybe also the indication of the presence of some advice on a named
function: ":around advice: `some-function@my-advice'"

And maybe some other usual suspects I'm forgetting about.

> The first line is perhaps not vital for people to know either, but since
> that's what I use to jump to function definitions, it's useful.  (But
> perhaps a command that's just take us there is even better.)

The first line also indicates whether a function is interactive,
so I think it is useful for the average user.

> Anyway, what about rearranging this a bit so that the stuff the users
> are interested in comes first?

No objections here.

Thanks,

-- 
Basil

bug#36478: Perhaps rearrange *Help* buffer a bit?

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Here's my favorite color: 
> - don't move it to the end, because it's much too far.
> - hide it by default, with some obvious-enough button-like thingy to
>   expand it on demand.
> - maybe the first line could also be moved into this "metadata" block.

A button that says "Technical details..." or something?  Or... a
text-less button would perhaps be better.

To take the `car' example again:

---
(car LIST) ...

Return the car of LIST.  If arg is nil, return nil.
Error if arg is not nil and not a cons cell.  See also ‘car-safe’.

See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
Lisp concepts such as car, cdr, cons cell and list.
---

The "..." after the function call signature could be marked in the link
face, and could expand into:

---
  car is a built-in function in ‘C source code’.
  Probably introduced at or before Emacs version 1.2.
  This function does not change global state, including the match data.
---

And `car' in the signature could be a link to the source code, as the
"C source code" is now, so you don't have to expand the details to get
to the link.

> - These *Help* buffers would benefit from a bit of face-lift (e.g. put
>   a different face on the metadata part, yet another on the
>   calling-convention example, ...).

The parameters are in an italic face...  If we're hiding the details,
perhaps a special face for the details isn't necessary?

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

Re: Perhaps rearrange *Help* buffer a bit?

[Lars Ingebrigtsen]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> And in the case of variables, the trailing "You can _customize_ this
> variable" which indicates a user option.

Oh yeah, let's bikeshed the variable help buffers, too.  Here's a random
example:

---
gnus-summary-article-delete-hook is a variable defined in ‘gnus-sum.el’.
Its value is nil
Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value is the same.

  This variable may be risky if used as a file-local variable.

Documentation:
A hook called after an article is deleted.

You can customize this variable.

This variable was introduced, or its default value was changed, in
version 22.1 of Emacs.
---

Let's see...  Along the lines of what Stefan bikeshod (that's the
correct past tense of "bikeshed"), we could have...

---
The value of `gnus-summary-article-delete-hook' value is
nil ...

Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*;
global value is the same.

A hook called after an article is deleted.
---

The "..." is a button that will reveal this text:

---
  `gnus-summary-article-delete-hook' is a variable defined in ‘gnus-sum.el’.
  This variable may be risky if used as a file-local variable.

  This variable was introduced, or its default value was changed, in
  version 22.1 of Emacs.

  You can customize this variable.
---

> And maybe also the indication of the presence of some advice on a named
> function: ":around advice: `some-function@my-advice'"
>
> And maybe some other usual suspects I'm forgetting about.

Probably; there's a lot of variations.  :-)

>> The first line is perhaps not vital for people to know either, but since
>> that's what I use to jump to function definitions, it's useful.  (But
>> perhaps a command that's just take us there is even better.)
>
> The first line also indicates whether a function is interactive,
> so I think it is useful for the average user.

That's true, so perhaps that line should stay at the start of the
buffer.

Let's look at one of these, and I choose at random:

---
insert-char is an interactive built-in function in ‘C source code’.

It is bound to C-x 8 RET.

(insert-char CHARACTER &optional COUNT INHERIT)

  Probably introduced at or before Emacs version 18.

[documentation here]
---

What about...

---
(insert-char CHARACTER &optional COUNT INHERIT) ...

This is an interactive function bound to C-x 8 RET.

[documentation here]
---


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

bug#36478: Perhaps rearrange *Help* buffer a bit?

[Drew Adams]

> > Here's my favorite color:
> > - don't move it to the end, because it's much too far.
> > - hide it by default, with some obvious-enough button-like thingy to
> >   expand it on demand.
> > - maybe the first line could also be moved into this "metadata" block.
> 
> A button that says "Technical details..." or something?  Or... a
> text-less button would perhaps be better.

FWIW, I think I disagree with handling all such
"metadata" equally, e.g. hiding it all by default.

To me, it makes sense to show, without fishing, that
a function is autoloaded (e.g. not yet loaded),
compiled, etc.; and to show its definition location,
with a link to it; and to show a link to its advice
- especially if the advice changes the doc (which is
what the help is mainly for); and to show a variable's
value.

Such things are helpful for most users, I think, and
they're not in the way.  Such things are not so
concerned with "our" implementation details as they
are with the definition - what the thing is/does.

This is a bit like using `C-u C-x ='.  Both kinds
of help can and do show lots of information.  And
it's not good to overwhelm users at the outset with
too much info, especially in a not-very-organized
way.

But I think that for `*Help*' the info we've long
shown is pretty much user-oriented.  It's more a
question of organization.  I objected, in bug
#36478, to sticking the following kind of info
near the top, before even the first line of the
doc string:

 This function has a compiler macro 'zerop--anon-cmacro'.

Dunno how useful that info is, but a priori that's
not the place to stick it, IMO.  

Many users (I'm one) have no clue what a "compiler
macro" is or why they should care.  (And it's not
explained in the manual, which is a big part of
what bug bu#36478g is about.)

But if that info is actually useful for users (I'm
ignorant, so can't judge that) and if it were put
at or near the end of `*Help*' (and if "compiler
macro" got documented, and especially if those
words linked to the place in the manual where that's
documented), then I'd have no problem with it.

bug#36478: Perhaps rearrange *Help* buffer a bit?

[Stefan Monnier]

> To take the `car' example again:
>
> ---
> (car LIST) ...
>
> Return the car of LIST.  If arg is nil, return nil.
> Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
>
> See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
> Lisp concepts such as car, cdr, cons cell and list.
> ---

Sounds about right, yes.  I think I'd vote to keep the function/macro
distinction displayed by default at least (and maybe function/command as
well).  Maybe simply as

    Function: (car LIST) ...
    
    Return the car of LIST.  If arg is nil, return nil.
    Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
    
    See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
    Lisp concepts such as car, cdr, cons cell and list.

> And `car' in the signature could be a link to the source code, as the
> "C source code" is now, so you don't have to expand the details to get
> to the link.

Sounds good.

>> - These *Help* buffers would benefit from a bit of face-lift (e.g. put
>>   a different face on the metadata part, yet another on the
>>   calling-convention example, ...).
> The parameters are in an italic face...  If we're hiding the details,
> perhaps a special face for the details isn't necessary?

Maybe you're right.  Then again, I think it's worth keeping the block
highlighted somehow to clearly indicate the difference between the
docstring and the auto-generated metadata, maybe with a discreet
background color.


        Stefan

Re: Perhaps rearrange *Help* buffer a bit?

[Eric Abrahamsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> "Basil L. Contovounesios" <contovob@tcd.ie> writes:
>
>> And in the case of variables, the trailing "You can _customize_ this
>> variable" which indicates a user option.
>
> Oh yeah, let's bikeshed the variable help buffers, too.  Here's a random
> example:
>
> ---
> gnus-summary-article-delete-hook is a variable defined in ‘gnus-sum.el’.
> Its value is nil
> Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value is the same.
>
>   This variable may be risky if used as a file-local variable.

I'll lean out of my passing car and shoot a paintball at the shed:

I've never understood what "risky" meant. Why would I make it file-local
to begin with? What would happen if I did? Who would be at risk?

If any of this information belongs "below the fold", I'm voting for this
bit.

Re: Perhaps rearrange *Help* buffer a bit?

[Basil L. Contovounesios]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> gnus-summary-article-delete-hook is a variable defined in ‘gnus-sum.el’.
>> Its value is nil
>> Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value is the same.
>>
>>   This variable may be risky if used as a file-local variable.
>
> I'll lean out of my passing car and shoot a paintball at the shed:
>
> I've never understood what "risky" meant. Why would I make it file-local
> to begin with? What would happen if I did? Who would be at risk?

Do  (info "(emacs) Safe File Variables")
and (info "(elisp) File Local Variables")
answer your questions?  If not, why not?

-- 
Basil

Re: Perhaps rearrange *Help* buffer a bit?

[Eric Abrahamsen]

On 07/09/19 01:59 AM, Basil L. Contovounesios wrote:
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> Lars Ingebrigtsen <larsi@gnus.org> writes:
>>
>>> gnus-summary-article-delete-hook is a variable defined in ‘gnus-sum.el’.
>>> Its value is nil
>>> Local in buffer *Summary nnimap+quimby.gnus.org:emacs-devel*; global value is the same.
>>>
>>>   This variable may be risky if used as a file-local variable.
>>
>> I'll lean out of my passing car and shoot a paintball at the shed:
>>
>> I've never understood what "risky" meant. Why would I make it file-local
>> to begin with? What would happen if I did? Who would be at risk?
>
> Do  (info "(emacs) Safe File Variables")
> and (info "(elisp) File Local Variables")
> answer your questions?  If not, why not?

Okay, I shouldn't have said "I've never understood...", I should have
said, "I keep forgetting...". It's not that I can't find the
information, it's that it is very rarely relevant to anything I'm doing
with the variable in question. IMO it could be moved down into the "less
important" information section.

Re: Perhaps rearrange *Help* buffer a bit?

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Sounds about right, yes.  I think I'd vote to keep the function/macro
> distinction displayed by default at least (and maybe function/command as
> well).  Maybe simply as
>
>     Function: (car LIST) ...
>
>     Return the car of LIST.  If arg is nil, return nil.
>     Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
>
>     See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
>     Lisp concepts such as car, cdr, cons cell and list.

Yes, that makes sense -- whether something's a macro or not is pretty
important information.

> Maybe you're right.  Then again, I think it's worth keeping the block
> highlighted somehow to clearly indicate the difference between the
> docstring and the auto-generated metadata, maybe with a discreet
> background color.

Yes, that sounds good.

Should I perhaps just start a branch for this and start hacking?  This
is the sort of thing that'll probably take a lot of tweaks to get right,
because it's all about aesthetics and readability.

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

Re: Perhaps rearrange *Help* buffer a bit?

[Stefan Monnier]

> Should I perhaps just start a branch for this and start hacking?

"Start hacking" sounds good,


        Stefan

Re: Perhaps rearrange *Help* buffer a bit?

[Howard Melman]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Should I perhaps just start a branch for this and start hacking?  This
> is the sort of thing that'll probably take a lot of tweaks to get right,
> because it's all about aesthetics and readability.

Can I recommend looking at helpful.el
https://melpa.org/#/helpful

-- 

Howard

Re: Perhaps rearrange *Help* buffer a bit?

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> Can I recommend looking at helpful.el
> https://melpa.org/#/helpful

That looks nice, but a bit beyond what I think we're aiming for here.
It's also a bit on the chatty side for my tastes... 

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

Re: Perhaps rearrange *Help* buffer a bit?

[Howard Melman]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Howard Melman <hmelman@gmail.com> writes:
>
>> Can I recommend looking at helpful.el
>> https://melpa.org/#/helpful
>
> That looks nice, but a bit beyond what I think we're aiming for here.
> It's also a bit on the chatty side for my tastes... 

Fair enough. 

I think its "'View in manual" button could be useful to
general (and new) users. 

If there's a Technical Details button hiding some things,
perhaps some of it could be useful (aliases, symbol
properties).

-- 

Howard

RE: Perhaps rearrange *Help* buffer a bit?

[Drew Adams]

> I think its "'View in manual" button could be useful to
> general (and new) users.

Good.

Since 2011 library `help-fns+.el' has had that feature.

And it's user configurable - not just on/off, by
option `help-cross-reference-manuals':

1. Choose the list of manuals to search. Default:
   Emacs and Elisp manuals.

2. Choose whether to (a) search systematically,
   when `*Help*' is created, and add a `manuals'
   link only if search finds hits, or (b) always
   create a link, and search only when the link
   is followed.  Default: (b).

`C-h v help-cross-reference-manuals' shows this
(`manuals' is the added link):

---

help-cross-reference-manuals is a variable defined in `help-fns+.el'.
Its value is (("emacs" "elisp"))

Documentation:
Manuals to search, for a `*Help*' buffer link to the manuals.
A cons.

 The car is a list of manuals to search, or the symbol `all', to
  search all.  If nil, then do not create a cross-reference link.

 The cdr is a boolean:

  Non-`nil' means search the manuals, then create a cross-ref link:
        create it only if some search hits are found.

  `nil' means create a cross-ref link without searching manuals
        first (but only if there are some manuals to search).

You can customize this variable.

For more information check the manuals.