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

From: Drew Adams <[email-masked]>
Date: Mon, 8 Jul 2019 16:21:52 -0700 (PDT)

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