unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* proposed new variable `emacs-lisp-docstring-fill-column'
@ 2003-02-28  1:59 Matt Swift
  2003-03-01  2:26 ` Richard Stallman
  0 siblings, 1 reply; 9+ messages in thread
From: Matt Swift @ 2003-02-28  1:59 UTC (permalink / raw)



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

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2003-03-02 15:07 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2003-02-28  1:59 proposed new variable `emacs-lisp-docstring-fill-column' Matt Swift
2003-03-01  2:26 ` Richard Stallman
2003-03-01  4:05   ` Matt Swift
2003-03-01 20:38     ` Stefan Monnier
2003-03-01 20:54       ` Matt Swift
2003-03-01 20:56         ` Stefan Monnier
2003-03-01 21:32           ` Matt Swift
2003-03-02 15:07           ` Richard Stallman
2003-03-02 15:07     ` Richard Stallman

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).