[Top][All Lists]

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

RE: Docstring line length

From: Drew Adams
Subject: RE: Docstring line length
Date: Tue, 20 Dec 2005 15:59:06 -0800

    in the case of docstrings, the fact that shorter lines means
    more lines makes the `C-h v' output _definitely_ more
    difficult to read in a pop-up window.

And _easier_ to read in a pop-up frame. (Short lines are generally easier to
read.) Especially if the frame is shrunk to fit the buffer (no wrap),
shorter lines are better, IMO.

    So I am not sure that the 60 character limit is a very good
    recommendation to begin with.  (Especially if it makes the difference
    between the entire `C-h v' doc fitting on the screen or not fitting on
    the screen.)

By "screen" here I think you mean Emacs window. If not, I don't understand

That said, I agree with you that 60 is too short. I use 70 chars as my
cut-off point - for all doc-string lines (first and subsequent). Why 67 and

The reason given for 67 for the first line was apparently its appearance in
*Apropos*. I don't see the point of this. The doc string is prepended by 11
or 12 characters in any case (e.g. "  Variable: "), so presumably the
guideline for other lines than the first should then be 67+12=79, not 60.

Why should subsequent lines be shorter than the first? My guess is that it
was thought that short lines (60) were better, but it was recognized that 60
is too short to get in all the info we need for the first line. Especially
when a frame is resized to fit its buffer, it makes sense to use the same
criterion for each line. If the first line is longer than all the rest, then
the frame is sized too wide (extra blank space) for the others, just to
accomodate it.

In any case, the argument for *Apropos* makes little sense. Do `M-x apropos
RET file' and look at the result. The Plist entries are much wider than any
of the doc-string entries. In the case of `file', they go as wide as 104
characters in emacs -q. Also, there are plenty of doc strings in emacs -q
that do not respect the 67-character guideline.

I vote for 70 as a guideline for all doc-string lines, and I suggest we do
something (e.g. wrap, with indenting) about the width of the Plist output in

reply via email to

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