proposed new variable `emacs-lisp-docstring-fill-column'

[Matt Swift]

I have found that the following new variable makes writing
well-formatted Emacs-Lisp code and docstrings more convenient.

I propose to add it to emacs-lisp/lisp-mode.el, along with a simple
modification of `lisp-fill-paragraph' to use it.

I'm new to this list and my CVS write powers are new, so I would like
feedback before I add it.  Also, this is not a bugfix but a new
feature that alters Emacs's behavior, albeit very slightly, and I
think such changes merit discussion.


    (defcustom emacs-lisp-docstring-fill-column 65
      "Value of `fill-column' to use when filling a docstring.
    Any non-integer value means do not use a different value of
    `fill-column' when filling docstrings."
      :type '(choice (integer)
                     (const :tag "Use the current `fill-column'" t))
      :group 'lisp)


I have `fill-column' at 79.  I don't see a reason for the length of
comment lines or the auto-filling of code lines to be constrained like
docstring lines.  One could engineer it so that docstrings are
composed with a usual `fill-column' of 79 and get refilled with a more
appropriate lower value in an elint or checkdoc phase, but this is
much less desirable because it does not allow the docstring author to
choose linebreaks intelligently.

Regarding a good default value for this variable, the Elisp manual
says:

   * Format the documentation string so that it fits in an Emacs window
     on an 80-column screen.  It is a good idea for most lines to be no
     wider than 60 characters.  The first line should not be wider than
     67 characters or it will look bad in the output of `apropos'.

Note that a `fill-column' of N means that the average line length is
something less than N.  My guess is that it will be about N - 5, or
60.  67 also seems like a reasonable value. 

(This is a good puzzle to fill ;) an afternoon: Given a `fill-column'
of N, compute the expected average line length of a docstring; begin
by determining experimentally the average and std dev of word length
in existing Emacs docstrings.)