Re: Improving describe-mode and discoverability

[Clément Pit--Claudel]

Hi Drew,

Thanks for your opinion. Maybe my proposal wasn't clear, though, and lead to 
confusion.

I'm not proposing to replace mode docstrings by auto-generated text; in other 
words, the output that I displayed was not intended to be the only thing 
displayed on C-h m.
Instead, my proposal is to keep displaying mode docstrings. However, when a 
mode docstring includes a \\{mode-map} (which seems to be a very common thing 
to do), my proposal is to enhance the rendering of that \\{mode-map} construct 
to print an actually useful table.
Of course, we could put this behaviour behind a flag.

My hunch is that modes that do things very well, and the description of 
keybindings into the mode docstring as you describe, don't include the 
\\{mode-map} at the end.  For the other ones, though, the ones that don't 
describe the mode's bindings too well, we can make the life of users nicer by 
making the rendering of \\{...} more readable.

To sum up: we could just transform one kind of automatic output into another 
kind of automatic output.

What do you think? Does this make the proposal more clear?
Clément.

On 2016-06-23 16:26, Drew Adams wrote:
>> 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.
>

signature.asc
Description: OpenPGP digital signature