emacs-devel
[Top][All Lists]
Advanced

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

Re: master 2a7488d: Add support for displaying short documentation for f


From: Lars Ingebrigtsen
Subject: Re: master 2a7488d: Add support for displaying short documentation for function groups
Date: Sun, 11 Oct 2020 23:47:46 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux)

Eli Zaretskii <eliz@gnu.org> writes:

> 1) Is "shortdoc" the best name for this?  This is not really some
> short form of existing documentation, it is something else.  Unless we
> plan to add more similar features, how about "help-func-groups" or
> "help-func-summaries" instead?

Yes, it's a bad name; I tried coming up with a better name over a
month's time, but I just blanked.

> 2) A better name for the shortdoc-display-group command would be
> something like describe-function-group or somesuch -- this is
> basically a help command.  (And how about adding it to the Help menu?)

Hm...  function-overview?  function-group-overview?

And, yes, it should go in the Help menu.

> 3) An apropos-style command regarding the known groups should probably
> be added.  As long as the list of the groups is short, just C-h (which
> already works) is enough, but that will become inconvenient as the
> list grows, I think.

I'm not sure the list will grow all that much, though.  This stuff is
primarily useful for function discovery, and that's mostly useful when
talking about the "built-in", base functions, like the
string/list/vector manipulation functions, and not something like, say,
shr.  The latter is best handled in a traditional manual.

> 4) Invoking shortdoc-display-group with "file" as the group signals an
> error.  Looks like we lack some auto-loading machinery here.

I'll have a look.

> 5) Pushing the button with a function name in the group display pops
> up the ELisp manual.  I wonder whether this is a good idea: why not
> show the full doc string of the function instead?  Come think about
> it, why not _insert_ the full doc string right after the function's
> signature, in the same buffer, instead of popping up a new buffer?

I think the manual gives superior information in most cases, so I'd
really like this to link to the manual and not the doc strings.  This is
also a way to guide users into the manual and read more in-depth about
not just the functions described, but the machinery surrounding them,
giving them more context.

> 6) I question the particular faces used for the display.  Do you
> really find the gray background to be such a good idea?

No.  But I experimented with various ways of grouping, and I couldn't
find anything that wouldn't just make everything look like...  mush...
and still be compact.  Suggestions are very welcome.

The problem is that the text is sparse, and it can be problematic seeing
where the next function definition starts when you're skimming the list,
and skimming is what it's all about.

> 7) Loading the entire database of all the groups at once sounds
> un-economical, especially if we envision that the groups will grow and
> their number will increase.  Should we perhaps have a separate DB file
> for each group?

I don't envision that the list will increase greatly.  Perhaps a couple
more groups, but that's it.

> 8) The information stored in the group consists of 2 separate parts:
>
>   . the functions that belong to a group
>   . the examples of using each function
>
> These 2 are not necessarily tightly coupled, and the examples are
> useful on their own right.  For example, should we perhaps make the
> examples of using a particular function accessible from the *Help*
> buffer that describes that function?  The "group" button is not an
> efficient way of seeing those examples because it shows the entire
> group, not the function from which we started.

Yes, using the examples in the normal *Help* output would make sense.

> Also, how about some facility to add a description or explanation of
> what each example does?  It's IME sub-optimal to expect the reader to
> glean that on his/her own just by looking at the call and the result,
> especially when there are several non-trivial arguments.

No, adding more text here would be counter-productive.  I think that
there's a substantial number of programmers that don't like reading
words, but they love seeing examples.  If they liked reading, they'd be
reading the manual already.

> 9) Do we really need all the type keywords (:eval, :eg-result, etc.)?
> I'm not sure I understand why not just evaluate the example and
> produce the result automatically, without all those different types?
> E.g., it sounds artificial to me to use :no-eval* to get "[it
> depends]", instead of just saying "[it depends]" explicitly.

:eval is for side-effect-free forms, and the result shown is what they
actually eval to.  The rest are needed when we can't eval, but we still
want to show an example of what form the result from the function would
typically be on.

But, yes, the :no-eval* bit could use some work.

> 10) This should be documented in the user manual, as all other Help
> commands.

I'll add that.

-- 
(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]