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