emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Perhaps rearrange *Help* buffer a bit?


From: Lars Ingebrigtsen
Subject: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 08 Jul 2019 22:18:58 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux)

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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]