unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Perhaps rearrange *Help* buffer a bit?
@ 2019-07-08 20:18 Lars Ingebrigtsen
  2019-07-08 20:29 ` Drew Adams
                   ` (2 more replies)
  0 siblings, 3 replies; 15+ messages in thread
From: Lars Ingebrigtsen @ 2019-07-08 20:18 UTC (permalink / raw)
  To: emacs-devel

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




^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2019-07-10 14:06 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-07-08 20:18 Perhaps rearrange *Help* buffer a bit? Lars Ingebrigtsen
2019-07-08 20:29 ` Drew Adams
2019-07-08 20:31   ` Drew Adams
2019-07-08 21:14 ` Stefan Monnier
     [not found]   ` <m3bly4yxgq.fsf@gnus.org>
     [not found]     ` <jwv5zocaz3r.fsf-monnier+emacs@gnu.org>
2019-07-09 13:58       ` Lars Ingebrigtsen
2019-07-09 14:18         ` Stefan Monnier
2019-07-10  3:58         ` Howard Melman
2019-07-10 11:27           ` Lars Ingebrigtsen
2019-07-10 12:59             ` Howard Melman
2019-07-10 14:06               ` Drew Adams
2019-07-08 21:24 ` Basil L. Contovounesios
2019-07-08 22:38   ` Lars Ingebrigtsen
2019-07-09  0:02     ` Eric Abrahamsen
2019-07-09  0:59       ` Basil L. Contovounesios
2019-07-09  3:26         ` Eric Abrahamsen

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).