* bug#36478: Perhaps rearrange *Help* buffer a bit?
[not found] <m3lfx81dql.fsf@gnus.org>
@ 2019-07-08 21:14 ` Stefan Monnier
[not found] ` <jwvlfx8ck2j.fsf-monnier+emacs@gnu.org>
1 sibling, 0 replies; 4+ messages in thread
From: Stefan Monnier @ 2019-07-08 21:14 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: bug#36478
> 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.
> This function has a compiler macro ‘internal--compiler-macro-cXXr’.
> Probably introduced at or before Emacs version 20.
[...]
> Probably introduced at or before Emacs version 1.2.
> This function does not change global state, including the match data.
[...]
> So the thought here is that those indented lines isn't what's most
> interesting to the user.
I recently reworked the generation of this text specifically to try and
make it easier to tweak it.
> Anyway, what about rearranging this a bit so that the stuff the users
> are interested in comes first?
[...]
> Let the bike-shedding commence!
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.
- 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, ...).
Stefan
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#36478: Perhaps rearrange *Help* buffer a bit?
[not found] ` <jwvlfx8ck2j.fsf-monnier+emacs@gnu.org>
@ 2019-07-08 22:26 ` Lars Ingebrigtsen
2019-07-08 23:21 ` Drew Adams
2019-07-08 23:30 ` Stefan Monnier
0 siblings, 2 replies; 4+ messages in thread
From: Lars Ingebrigtsen @ 2019-07-08 22:26 UTC (permalink / raw)
To: Stefan Monnier; +Cc: bug#36478
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#36478: Perhaps rearrange *Help* buffer a bit?
2019-07-08 22:26 ` Lars Ingebrigtsen
@ 2019-07-08 23:21 ` Drew Adams
2019-07-08 23:30 ` Stefan Monnier
1 sibling, 0 replies; 4+ messages in thread
From: Drew Adams @ 2019-07-08 23:21 UTC (permalink / raw)
To: Lars Ingebrigtsen, Stefan Monnier; +Cc: bug#36478
> > 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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#36478: Perhaps rearrange *Help* buffer a bit?
2019-07-08 22:26 ` Lars Ingebrigtsen
2019-07-08 23:21 ` Drew Adams
@ 2019-07-08 23:30 ` Stefan Monnier
1 sibling, 0 replies; 4+ messages in thread
From: Stefan Monnier @ 2019-07-08 23:30 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: bug#36478
> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2019-07-08 23:30 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <m3lfx81dql.fsf@gnus.org>
2019-07-08 21:14 ` bug#36478: Perhaps rearrange *Help* buffer a bit? Stefan Monnier
[not found] ` <jwvlfx8ck2j.fsf-monnier+emacs@gnu.org>
2019-07-08 22:26 ` Lars Ingebrigtsen
2019-07-08 23:21 ` Drew Adams
2019-07-08 23:30 ` Stefan Monnier
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).