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