RE: [External] : Feature Request: Help: Display Relevant Bits First?

[Drew Adams]

> At present, if you do describe-function on any command that toggles a
> mode, you get a lot of common boiler-plate, with the salient bits
> about that particular function at the end -- could we reverse this?

The most salient info is the first line of the doc string:

  Toggle syntax highlighting in this buffer (Font Lock mode).

But that's part of the text (you say) you want moved to
the end.

Anyway, I support your general proposal.  I agree that
minor-mode boilerplate info should come after specifics
about the particular minor mode.  It might even be good
to separate the two with a separator (e.g. line).

The problem of documenting minor modes has been around a
l o n g  time.  For a long time the boilerplate info was
only in the doc of `define-minor-mode' itself (but a few
minor-mode doc strings duplicated some of that info).

Eventually maybe we'll get to a place where `C-h f' for a
minor mode shows both the particular info (preferably up
front) and the generic (boilerplate) info, consistently
for all minor modes, and preferably with the two separated.

Either that or just show the particular info and (always)
provide a link to a single description of the generic
(boilerplate) info - IOW, factor that out.  But introduce
that link by saying that it describes the behavior of all
minor modes (to make clear that it's part of the behavior
of this particular command).