[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Matt Swift
Subject: Re: proposed new variable `emacs-lisp-docstring-fill-column'
Date: Fri, 28 Feb 2003 23:05:22 -0500
User-agent: Gnus/5.090016 (Oort Gnus v0.16) Emacs/21.2 (i386-debian-linux-gnu)

    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
            ;; Avoid filling the first line of docstring.
             (concat paragraph-separate "\\|\\s-*\".*[,\\.]$"))
;;; HERE
            (fill-column (if (integerp emacs-lisp-docstring-fill-column)
        (fill-paragraph justify))
      ;; Never return nil.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]