From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Matt Swift Newsgroups: gmane.emacs.devel Subject: Re: proposed new variable `emacs-lisp-docstring-fill-column' Date: Fri, 28 Feb 2003 23:05:22 -0500 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1046491619 17282 80.91.224.249 (1 Mar 2003 04:06:59 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sat, 1 Mar 2003 04:06:59 +0000 (UTC) Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 18oyH4-0004Ub-00 for ; Sat, 01 Mar 2003 05:06:58 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18oyYm-0003P6-00 for ; Sat, 01 Mar 2003 05:25:16 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18oyGU-0007OS-05 for emacs-devel@quimby.gnus.org; Fri, 28 Feb 2003 23:06:22 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18oyGA-0007Ky-00 for emacs-devel@gnu.org; Fri, 28 Feb 2003 23:06:02 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18oyG7-0007Gy-00 for emacs-devel@gnu.org; Fri, 28 Feb 2003 23:06:00 -0500 Original-Received: from pool-68-160-54-133.bos.east.verizon.net ([68.160.54.133] helo=beth.swift.xxx) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18oyG0-00075X-00 for emacs-devel@gnu.org; Fri, 28 Feb 2003 23:05:52 -0500 Original-Received: from beth.swift.xxx (swift@localhost.swift.xxx [127.0.0.1]) h2145NpF014946verify=FAIL) for ; Fri, 28 Feb 2003 23:05:23 -0500 Original-Received: (from swift@localhost) by beth.swift.xxx (8.12.7/8.12.7/Debian-2) id h2145N0e014944; Fri, 28 Feb 2003 23:05:23 -0500 Original-To: emacs-devel@gnu.org In-Reply-To: (Richard Stallman's message of "Fri, 28 Feb 2003 21:26:39 -0500") User-Agent: Gnus/5.090016 (Oort Gnus v0.16) Emacs/21.2 (i386-debian-linux-gnu) X-Mailscanner: clean (beth.swift.xxx) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:12045 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:12045 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))