The first sentence should summarize the variable's or function's
purpose and it should fit on the first line. Change existing
doc-string by:
* Move first sentence onto first line even if that makes it _a bit_
long.
* Move additional notes out of first sentence and add them later,
possibly as complete sentences.
* If I am uncertain whether doing the above would alter the meaning,
_don't_ do it.
* If fitting the initial sentence on the first line would require a
complete rewrite of the doc-string _don't_ do so unless it is very
easy to do.
* Remove indentation from second and later lines if it is there to
align them with the first in the source code, instead of in
`describe-*' output.
* Make "pullet point" lists a bit more consistent.
Obviously this does not fix all problems but it's a start.
djcb
Jonas Bernoulli