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: proposed new variable `emacs-lisp-docstring-fill-column' Date: Thu, 27 Feb 2003 20:59:03 -0500 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1046397615 32406 80.91.224.249 (28 Feb 2003 02:00:15 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Fri, 28 Feb 2003 02:00:15 +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 18oZoo-0008Q9-00 for ; Fri, 28 Feb 2003 03:00:10 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18oa5z-0004uY-00 for ; Fri, 28 Feb 2003 03:17:55 +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 18oZoY-0007Xt-08 for emacs-devel@quimby.gnus.org; Thu, 27 Feb 2003 20:59:54 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18oZoC-0007Qr-00 for emacs-devel@gnu.org; Thu, 27 Feb 2003 20:59:32 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18oZo6-0007CP-00 for emacs-devel@gnu.org; Thu, 27 Feb 2003 20:59:27 -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 18oZnv-0006sq-00 for emacs-devel@gnu.org; Thu, 27 Feb 2003 20:59:15 -0500 Original-Received: from beth.swift.xxx (swift@localhost.swift.xxx [127.0.0.1]) h1S1x7pF021692verify=FAIL) for ; Thu, 27 Feb 2003 20:59:07 -0500 Original-Received: (from swift@localhost) by beth.swift.xxx (8.12.7/8.12.7/Debian-2) id h1S1x30s021690; Thu, 27 Feb 2003 20:59:03 -0500 Original-To: emacs-devel@gnu.org 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:12018 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:12018 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.)