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

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.)

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

[Richard Stallman]

	(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)

It sounds like a good idea; would you like to implement the code
to actually use it, and show us that?

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

[Matt Swift]

    rms> It sounds like a good idea; would you like to implement the code
    rms> to actually use it, and show us that?

Here's the whole change.  I've been using it happily for a dozen or
two hours of working in Emacs Lisp mode.  I'm noticing other bugs in
filling ELisp, but they're not due to this change.
                                          
Using the new variable is as simple as adding a single `let' binding,
marked with ;;; HERE.

You may notice the function has other changes, so I should list them
all now:

  (1) use the new variable `emacs-lisp-docstring-fill-column'
  (2) add "`(" to `paragraph-start' so that `defmacro's whose bodies
      begin with backquote (i.e. most of them) will fill properly.
      This requires ?( to be escaped when "`(" begins a line in a
      docstring.   I think good style would escape all ?( chars in
      a docstring. 
  (3) recognize (and thus do not fill) a docstring's first line when
      it ends with ?, as well as ?.  Checkdoc-mode optionally permits
      a comma, so let's have filling recognize that situation.
  (4) revise the comments



(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)

(defun lisp-fill-paragraph (&optional justify)
  "Like \\[fill-paragraph], but handle Emacs Lisp comments and docstrings.
If any of the current line is a comment, fill the comment or the
paragraph of it that point is in, preserving the comment's indentation
and initial semicolons."
  (interactive "P")
  (or (fill-comment-paragraph justify)
      ;; We are on a program line; we are interested particularly in docstring
      ;; lines.
      ;;
      ;; The buffer-local variables `paragraph-start' and `paragraph-separate'
      ;; are bound with a `let' so that in the buffer they can have values that
      ;; make `forward-paragraph' and friends do something helpful for the
      ;; user.
      ;;
      ;; The `(' in the character alternative and the left-singlequote plus `('
      ;; sequence after the \\| alternative prevents a sexp following a
      ;; docstring from being filled.  It also has the consequence of
      ;; inhibiting filling program lines, which is sensible, since the user
      ;; probably asked for filling by accident, or expecting indentation
      ;; (Should we instead try to reindent the current function?)  The `;' and
      ;; `:' stop the filled paragraph at following comment lines and at
      ;; keywords (e.g., in `defcustom').
      (let ((paragraph-start (concat paragraph-start
				     "\\|\\s-*\\([\(;:\"]\\|`\(\\)"))
	    ;; Avoid filling the first line of docstring.
	    (paragraph-separate
	     (concat paragraph-separate "\\|\\s-*\".*[,\\.]$"))
;;; HERE
            (fill-column (if (integerp emacs-lisp-docstring-fill-column)
                             emacs-lisp-docstring-fill-column
                           fill-column)))
	(fill-paragraph justify))
      ;; Never return nil.
      t))

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

[Stefan Monnier]

> 
>     rms> It sounds like a good idea; would you like to implement the code
>     rms> to actually use it, and show us that?
> 
> Here's the whole change.  I've been using it happily for a dozen or
> two hours of working in Emacs Lisp mode.  I'm noticing other bugs in
> filling ELisp, but they're not due to this change.

I don't like this change because docstrings shouldn't be
limted to 65 chars.  The doc only says that they should
fit within 80 columns.  Only the first line should be shorter.

>   (2) add "`(" to `paragraph-start' so that `defmacro's whose bodies
>       begin with backquote (i.e. most of them) will fill properly.
>       This requires ?( to be escaped when "`(" begins a line in a
>       docstring.   I think good style would escape all ?( chars in
>       a docstring. 
>   (3) recognize (and thus do not fill) a docstring's first line when
>       it ends with ?, as well as ?.  Checkdoc-mode optionally permits
>       a comma, so let's have filling recognize that situation.

I have no opinion on this part, on the other hand.


	Stefan

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

[Matt Swift]

>> "S" == Stefan wrote:

    S> I don't like this change because docstrings shouldn't be
    S> limted to 65 chars.  The doc only says that they should
    S> fit within 80 columns.  Only the first line should be shorter.

Is this an objection to the variable or to the default value?  If the
default value were t instead of 65, default behavior of Emacs would
not change.  Users who do like the feature could enable it with
customization.

I agree the wording below is not a requirement, but it is a
recommendation, and I was looking for a way to heed it while still
filling code and comments to a more practical, wider length.

>From (elisp)Documentation Tips:

   * 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'.

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

[Stefan Monnier]

>     S> I don't like this change because docstrings shouldn't be
>     S> limted to 65 chars.  The doc only says that they should
>     S> fit within 80 columns.  Only the first line should be shorter.
> 
> Is this an objection to the variable or to the default value?  If the
> default value were t instead of 65, default behavior of Emacs would
> not change.  Users who do like the feature could enable it with
> customization.
> 
> I agree the wording below is not a requirement, but it is a
> recommendation, and I was looking for a way to heed it while still
> filling code and comments to a more practical, wider length.

Why can't they set fill-column in their emacs-lisp-mode-hook ?
It looks to me like an unnecessary customization variable.


	Stefan

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

[Matt Swift]

>> "S" == Stefan wrote:

    >> I agree the wording below is not a requirement, but it is a
    >> recommendation, and I was looking for a way to heed it while still
    >> filling code and comments to a more practical, wider length.

    S> Why can't they set fill-column in their emacs-lisp-mode-hook ?

They can, but it won't achieve my objective, which is to fill
docstrings to one length, and use another length to fill comments and
for auto-filling.  Having context-dependent values for `fill-column'
can't be accomplished in a hook.

    S> It looks to me like an unnecessary customization variable.

Of course that is a reasonable opinion, but I think not because the
variable is redundant.

There are other schemes.

One can define an alternative to `lisp-fill-paragraph' and elect that
function in the mode-hook.  That is how I have done it at home.

One could avoid adding a customization variable by permitting
`fill-column' to have other forms, such as an alist of contexts and
values.  But changing all the code that refers to `fill-column' would
be a big job that really doesn't seem worth it if it's not a widely
useful abstraction.

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

[Richard Stallman]

    Why can't they set fill-column in their emacs-lisp-mode-hook ?
    It looks to me like an unnecessary customization variable.

This feature is good to enable by default.
It is better to implement it directly, not thru a hook.

    I don't like this change because docstrings shouldn't be
    limted to 65 chars.

This won't limit them, it will just normally fill them to 65 chars.
Longer lines than that are not a good idea except in special
circumstances, and in those special circumstances, you can simply
avoid filling.

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

[Richard Stallman]

These changes seem reasonable.  Please install them.

Please make the comments describe all three changes.