RE: Changes in revision 114466

[Drew Adams <drew.adams@oracle.com>]

> > IMO every user option and every command needs documentation.
> 
> First, the original issue that started this thread was about changes
> in the ELisp manual, 

That may be.  But the statement that every user option and command needs
documentation does not speak about manuals.  In any case, that's how I
understood it: these things need documentation.

Which they (and others, IMHO) do: doc strings.

> The only serious problem with the doc strings is that they lack the
> "glue": the kind of overview and background material that we usually
> put in the manual when we describe a significant topic.

A manual is exactly where such glue (overview, background, context,
relations) belongs.

> So what would probably be a good idea in order to improve the visibility
> of those commands and options that are not in the manual is the following
> measures:

I disagree.  We don't need such an additional manual.

Either (a) something should be documented in the manual or
(b) it does not to be documented there and doc strings suffice.

By "doc strings" (plural), I include the possibility that one doc string
refers to (links to) another.

What we might want/need (I have proposed this several times, and so have
others) is linking from doc strings to the manuals.  That would indeed be
useful, IMO.  It would provide missing glue, as you put it.

There are a very few doc strings, IIRC, that actually do this.  It would
be good to generalize it, or at least make use of it more.