RE: [R21.4] [COMMIT] Update glyph documentation
Ben> NOTE: This patch has been committed. This is an attempt
to
Ben> update the documentation in glyphs.el to correspond to what
Ben> David has asked for.
Ben> Stephen -- I'd suggest incorporating some of these updates
Ben> into the Lisp manual, if possible.
OK.
It would be nice if the long docstrings could be moved to the
manual, to be replaced by a reference clickable in the C-h f
buffer. This would avoid double maintenance.
What do you think, Vin, could that go into 21.4?
I think we need a general scheme here -- not just for "long" docstrings but
for all of them. Either we generate sections of the Lisp manual directly
from the doc strings or we incorporate the doc strings into the Lisp manual
and fix C-h f to automatically go to the right place. The latter solution
is what Microsoft uses. Of course, they use something like HTML as a
representation, and it automatically has "pages", and each function
description is usually on its own page, so the equivalent of C-h f just goes
to the page -- much like what we have already except pulling out of the Lisp
manual rather than the doc string. Ultimately I think this is the right way
to go -- it makes it easy to put in cross-references to the places that
explain concepts and doesn't require hacks like use `make-foo' functions
proxies for document descriptions on `foo'.
What think you, stephen? Any time?