[Top][All Lists]

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

RE: Improving describe-mode and discoverability

From: Drew Adams
Subject: RE: Improving describe-mode and discoverability
Date: Thu, 23 Jun 2016 13:26:44 -0700 (PDT)

> Among the many ways to get information about a package (READMEs,
> Commentaries, manuals, menu-bar menus, and describe-mode; are there
> others?), describe-mode is the only universally available one. It always
> works, but it's not very nice to use: it just gives you a list of function
> names and the associated bindings.

No, it gives you whatever is in the doc string for the `*-mode' function.

> Recently I added an extra documentation feature to one of my packages,
> biblio.el.  It's a single function that walks a keymap, and displays for
> each binding not only the name of the associated function, but also the
> first line of the documentation of each function. Here's how it looks in
> haskell-mode:
> It's not much, but I think it looks much better. I've attached examples of
> the output for several other modes to this email, as well as the code used
> to generate this example. Contrast with the default output of C-h m for
> haskell-mode:
> My implementation is rather brittle (I don't have sufficient knowledge of
> keymaps), but I think a documentation facility in the line of the one demoed
> above would be very useful.  Most interactive functions are already
> documented, so we'd be tapping into a large body of existing docs, making
> them more accessible.
> What do you think? I would be happy to get help in refining this code (and
> this proposal). For example, we could consider hyperlinking the function
> names to their sources, or letting users expand the first line of the
> documentation to show the full docstring. We could also think about ways to
> cover functions that are not bound to a key by default, but which users may
> want to bind (e.g. by looking for interactive functions starting with the
> mode's name).

My two cents: We should not do such a thing automatically.

Instead, if you think that some of what you envisage or you have
implemented can usefully be factored into useful building blocks
that are not already available for use in doc strings, then consider
adding those as separate functions.

For literal doc strings there are already the constructs \\[...],
\\<...>, and \\{..}.  For strings that you might create dynamically
you can use `substitute-command-keys'.  Anything automatic is likely
to be less than helpful, I think: overkill, underkill, or both.

Different modes serve different purposes.  A doc string should be
handwritten for a given mode.

Of course, some kinds of modes have some things in common, which
can be _added_ to the doc string automatically.  That's the case
for `define-minor-mode', for example.  But there is no substitute
for the _specific_ description of the mode (what you provide to
`define-minor-mode' as input, for example).

Generally, a mode's doc string calls out particular features of the
mode, which might include some particularly important commands or
keys.  Just listing descriptions of all keys and commands is not
the way to go, in general, even if it might be useful for some modes.

The particular descriptions used for the important commands and
variables can be tailored to fit the general presentation of the
mode, saying what is most appropriate for it as a whole.  IOW, in a
mode doc string the keys or commands are described _together_.
That description can be more/better than just an independent
one-liner for each command and variable.

A mode is more than the sum of its parts.  And a writer of a mode
is not limited to barebones descriptions or to just showing which
commands are bound to which keys.

There is no royal road to doc strings.

Just one opinion.

reply via email to

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