Docstring line length

Docstring line length

[Bill Wohler]

   * 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'.

I understand why the first line shouldn't be wider than 67 characters,
but why should most lines not be wider than 60? The reason isn't given
here. Perhaps it should.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: Docstring line length

[Luc Teirlinck]

Bill Wohler wrote:

   I understand why the first line shouldn't be wider than 67 characters,
   but why should most lines not be wider than 60? The reason isn't given
   here. Perhaps it should.

I guess it has something to do with it being experimentally determined
that long lines are harder to read for most people.  But 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.

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

Sincerely,

Luc.

RE: Docstring line length

[Drew Adams]

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

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
60?

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
*Apropos*.

Re: Docstring line length

[Luc Teirlinck]

Drew Adams wrote:

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

Yes.

Sincerely,

Luc.

Re: Docstring line length

[Luc Teirlinck]

Drew Adams wrote:

   The reason given for 67 for the first line was apparently its appearance in
   *Apropos*. I don't see the point of this.

For defcustoms there still is another reason for the first line of the
docstring not being too long: if you click on [More] in a Custom
buffer and the more changes to [Hide Rest], the docstring can look
_really_ ugly with a long first line.

Sincerely,

Luc.

RE: Docstring line length

[Drew Adams]

       The reason given for 67 for the first line was apparently
       its appearance in *Apropos*. I don't see the point of this.

    For defcustoms there still is another reason for the first line of the
    docstring not being too long: if you click on [More] in a Custom
    buffer and the more changes to [Hide Rest], the docstring can look
    _really_ ugly with a long first line.

Fair enough. How long is too long? What's a good guideline? Do you think the
cut-off for the first line should be <, =, or > the cut-off for subsequent
lines? I vote for 70 for all doc-string lines.

Re: Docstring line length

[Luc Teirlinck]

Drew Adams wrote:

   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.

You apparently resize your frames to fit the buffer.  But most people
use fixed 80 column frames.  Hence, the desirability for lines to be
strictly less than 80 characters.

Sincerely,

Luc.

RE: Docstring line length

[Drew Adams]

       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.

    You apparently resize your frames to fit the buffer.  But most people
    use fixed 80 column frames.  Hence, the desirability for lines to be
    strictly less than 80 characters.

Yes, I do.

I'm sure most people do not do as I do, but I'm not sure that most people
use fixed 80-char frames. Do we have any user data to go on?

In any case, I also want the lines to be strictly less than 80 chars. I
proposed 70.

Re: Docstring line length

[Luc Teirlinck]

Drew Adams wrote:

   I'm sure most people do not do as I do, but I'm not sure that most people
   use fixed 80-char frames. Do we have any user data to go on?

80 char frames are the default configuration of Emacs.

   Fair enough. How long is too long?

67 for the first line.  That is a given.  68 already forces an ugly
continuation line in the apropos output.

To me 70 for most subsequent lines with an absolute limit of 79 seems
better than the current 60.  But I do not believe that this is a
really big deal.

Sincerely,

Luc.

RE: Docstring line length

[Drew Adams]

       I'm sure most people do not do as I do, but I'm not sure
       that most people use fixed 80-char frames. Do we have any
       user data to go on?

    80 char frames are the default configuration of Emacs.

Sure. But do you think most people use that? Maybe so.

       Fair enough. How long is too long?

    67 for the first line.  That is a given.  68 already forces an ugly
    continuation line in the apropos output.

Only because we use 11 or 12 chars for "  Variable: ". If we used "  Fun: ",
"  Cmd: ", and "  Var: " (and "  Opt: " for option), then up to 72
characters could be in the first line. Those abbreviations are clear enough
(and large enough as buttons) - no?

If we indented one space instead of two, then up to 73 chars could be used.
If we allow for "  Face: " in the future, then we're back down to 71 or 72
max. 70 is a good guideline.

(In any case, many Plist entries already wrap as ugly continuation lines, so
they need to be fixed first.)

BTW - Wouldn't "  Props: " be better than "  Plist: "?

    To me 70 for most subsequent lines with an absolute limit of 79 seems
    better than the current 60.  But I do not believe that this is a
    really big deal.

    [I meant that whether the convention for "most" subsequent lines is at
    most 60 or at most 70 colums is no big deal (to me).]

No, of course it's not a big deal. But a guideline has been published and
the question was raised (by Bill about 60, by me about 67). If there is no
guideline, the result will be (more) variety (inconsistency). I vote for a
70-max guideline for all lines, getting rid of "most", and shortening the
button text in *Apropos*.

Re: Docstring line length

[Henrik Enberg]

>     80 char frames are the default configuration of Emacs.
> 
> Sure. But do you think most people use that? Maybe so.

Every console I've ever met is 80 chars wide by default, and consoles
are a lot harder to change.  Please don't advocate wider than 80 lines,
it makes life harder for a lot of users without giving any real
benefit to the rest.

Re: Docstring line length

[Richard M. Stallman]

    (In any case, many Plist entries already wrap as ugly continuation lines, so
    they need to be fixed first.)

Could you show me an example?

RE: Docstring line length

[Drew Adams]

        (In any case, many Plist entries already wrap as ugly
         continuation lines, so they need to be fixed first.)

    Could you show me an example?

By "fixed" I meant to wrap (fill) each Plist entry.

emacs -q

(In GNU Emacs 22.0.50.1 (i386-mingw-nt5.1.2600)
 of 2005-06-26 on NONIQPC
X server distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc
(3.3) --cflags -I../../jpeg-6b-3/include -I../../libpng-1.2.8/include -I../.
./tiff-3.6.1-2/include -I../../xpm-nox-4.2.0/include -I../../zlib-1.2.2/incl
ude')

M-x apropos RET RET

The following PList entries are longer than 80 chars (there are also plenty
of Function, Command, and Variable entries that are longer than 80 chars,
but the Plist entries, at least, could presumably be filled automatically):

Info-goto-emacs-command-node
  Plist: info-file event-symbol-element-mask event-symbol-elements
modifier-cache

Info-goto-emacs-key-command-node
  Plist: info-file event-symbol-element-mask event-symbol-elements
modifier-cache

abbrev-mode
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
custom-group standard-value variable-documentation custom-type
custom-requests

after-save-hook
  Plist: standard-value variable-documentation custom-options custom-type
custom-requests

apropos
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
group-documentation custom-prefix custom-group autoload

apropos-command
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
button-category-symbol autoload

auto-compression-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests

auto-hscroll-mode
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

auto-save-file-name-transforms
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

backspace
  Plist: modifier-cache event-symbol-element-mask event-symbol-elements
ascii-character

backward-delete-char-untabify-method
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

bahai-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

before-save-hook
  Plist: standard-value variable-documentation custom-options custom-type
custom-requests

beginning-of-buffer
  Plist: error-conditions error-message event-symbol-element-mask
event-symbol-elements modifier-cache

blink-cursor-delay
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

blink-cursor-interval
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

blink-cursor-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests event-symbol-element-mask event-symbol-elements
modifier-cache

buffers-menu-show-directories
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests

buffers-menu-show-status
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests

case-fold-search
  Plist: standard-value event-symbol-element-mask event-symbol-elements
modifier-cache variable-documentation

christian-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

clear
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
ascii-character

clipboard-kill-region
  Plist: menu-enable event-symbol-element-mask event-symbol-elements
modifier-cache

clipboard-kill-ring-save
  Plist: menu-enable event-symbol-element-mask event-symbol-elements
modifier-cache

clipboard-yank
  Plist: menu-enable event-symbol-element-mask event-symbol-elements
modifier-cache

column-number-mode
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
standard-value variable-documentation custom-set custom-type custom-requests

comment-region
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
menu-enable

confirm-kill-emacs
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

cua-mode
  Plist: variable-documentation custom-autoload custom-loads
event-symbol-element-mask event-symbol-elements modifier-cache

current-language-environment
  Plist: standard-value variable-documentation custom-links custom-set
custom-get custom-type custom-requests

cursor
  Plist: face face-defface-spec face-documentation custom-version
custom-group face-no-inherit group-documentation

cursor-in-non-selected-windows
  Plist: standard-value variable-documentation custom-tag custom-type
custom-set custom-requests

debug-on-error
  Plist: standard-value event-symbol-element-mask event-symbol-elements
modifier-cache variable-documentation

debug-on-quit
  Plist: standard-value event-symbol-element-mask event-symbol-elements
modifier-cache variable-documentation

default
  Plist: face face-defface-spec face-documentation event-symbol-element-mask
event-symbol-elements modifier-cache

default-button
  Plist: face mouse-face keymap type action help-echo evaporate
rear-nonsticky button

default-input-method
  Plist: standard-value variable-documentation custom-links custom-type
custom-dependencies custom-requests

delay-mode-hooks
  Plist: variable-documentation permanent-local edebug-form-spec
lisp-indent-function

delete
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
ascii-character

delete-frame
  Plist: event-kind event-symbol-elements event-symbol-element-mask
modifier-cache

delete-other-windows
  Plist: isearch-scroll event-symbol-element-mask event-symbol-elements
modifier-cache

devanagari
  Plist: coding-system coding-system-define-form eol-type
indian-glyph-code-offset

dired
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache menu-enable group-documentation custom-links autoload

dired-copy-preserve-time
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-directory
  Plist: variable-documentation face face-defface-spec face-documentation
custom-version

dired-dnd-protocol-alist
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

dired-dwim-target
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-keep-marker-copy
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-keep-marker-hardlink
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-keep-marker-rename
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-keep-marker-symlink
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-listing-switches
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-ls-F-marks-symlinks
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

dired-mark
  Plist: group-documentation custom-prefix custom-group face
face-defface-spec face-documentation custom-version

dired-trivial-filenames
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

display
  Plist: format-list-atomic-p custom-group event-symbol-element-mask
event-symbol-elements modifier-cache

display-hourglass
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

dnd-open-file-other-window
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

dnd-protocol-alist
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-version custom-type custom-requests

emacs-lisp-mode-hook
  Plist: standard-value variable-documentation custom-options custom-type
custom-requests

enable-local-eval
  Plist: standard-value variable-documentation custom-type custom-requests
risky-local-variable

encoded-kbd-mode
  Plist: variable-documentation custom-autoload custom-loads permanent-local
standard-value custom-set custom-type custom-requests autoload

end-of-buffer
  Plist: error-conditions error-message event-symbol-element-mask
event-symbol-elements modifier-cache

escape
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
display-table-slot ascii-character

eval-expression-debug-on-error
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

eval-expression-print-length
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

eval-region
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
menu-enable

face-font-family-alternatives
  Plist: standard-value variable-documentation custom-tag custom-type
custom-set custom-requests

face-font-registry-alternatives
  Plist: standard-value variable-documentation custom-tag custom-type
custom-version custom-set custom-requests

face-font-selection-order
  Plist: standard-value variable-documentation custom-tag custom-type
custom-set custom-requests

fill
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache group-documentation custom-links

fill-nobreak-predicate
  Plist: standard-value variable-documentation custom-type custom-options
custom-requests

find-file
  Plist: group-documentation custom-group event-symbol-element-mask
event-symbol-elements modifier-cache

find-file-hook
  Plist: standard-value variable-documentation custom-type custom-options
custom-version custom-requests

find-file-suppress-same-file-warnings
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

find-file-wildcards
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

focus-follows-mouse
  Variable: *Non-nil if window system changes focus when you move the mouse.
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

font-lock-mode
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
variable-documentation

frame-background-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests

general-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

global-font-lock-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests

gnus
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache

header-line
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache face
face-defface-spec face-documentation custom-version

hebrew-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

help
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache

hourglass-delay
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

iconify-frame
  Plist: event-kind event-symbol-elements event-symbol-element-mask
modifier-cache

idle-update-delay
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

indent-region
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
menu-enable

info
  Plist: info-file event-symbol-element-mask event-symbol-elements
modifier-cache

isearch
  Plist: group-documentation custom-links custom-prefix custom-group face
face-defface-spec face-documentation

isearch-lazy-highlight-cleanup
  Plist: variable-documentation byte-obsolete-variable byte-compile
byte-obsolete-info

islamic-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

keyboard-coding-system
  Plist: standard-value variable-documentation custom-type custom-links
custom-set custom-version custom-requests

kp-0 through kp-9
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
ascii-character

kp-add
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-decimal
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-divide
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-enter
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-multiply
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-separator
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-space
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

kp-subtract
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
ascii-character

kp-tab
  Plist: ascii-character event-symbol-element-mask event-symbol-elements
modifier-cache

large-file-warning-threshold
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

lazy-highlight
  Plist: custom-group group-documentation custom-prefix custom-version face
face-defface-spec face-documentation

left-fringe
  Plist: x-frame-parameter event-symbol-element-mask event-symbol-elements
modifier-cache

line-number-mode
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
standard-value variable-documentation custom-set custom-type custom-requests

linefeed
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
ascii-character

lisp-mode-hook
  Variable: Hook run when entering Lisp mode.
  Plist: standard-value variable-documentation custom-options custom-type
custom-requests

list-buffers
  Plist: isearch-scroll event-symbol-element-mask event-symbol-elements
modifier-cache

local-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

ls-lisp-support-shell-wildcards
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-type custom-requests

make-frame-visible
  Plist: event-kind event-symbol-elements event-symbol-element-mask
modifier-cache

menu
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache face
face-defface-spec face-documentation custom-version custom-group

menu-bar-mode
  Plist: standard-value variable-documentation custom-autoload custom-loads
event-symbol-element-mask event-symbol-elements modifier-cache custom-set
custom-type custom-requests

mode-line
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache face
face-defface-spec face-documentation custom-version

mode-require-final-newline
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

mouse-1
  Plist: modifier-cache event-symbol-element-mask event-symbol-elements
event-kind

mouse-1-click-follows-link
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

mouse-1-click-in-non-selected-windows
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

mouse-buffer-menu-mode-mult
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

mouse-drag-copy-region
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

mouse-movement
  Plist: event-kind event-symbol-elements event-symbol-element-mask
modifier-cache

mouse-wheel-click-event
  Plist: standard-value variable-documentation custom-type custom-set
custom-requests

mouse-wheel-down-event
  Plist: standard-value variable-documentation custom-type custom-set
custom-requests

mouse-wheel-mode
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-set custom-type custom-requests autoload

mouse-wheel-up-event
  Plist: standard-value variable-documentation custom-type custom-set
custom-requests

mule
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache

next
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
coding-system coding-system-define-form eol-type

next-error
  Plist: group-documentation custom-version face face-defface-spec
face-documentation custom-group

next-error-highlight
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

next-error-highlight-no-select
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

next-line-add-newlines
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

normal-erase-is-backspace
  Plist: standard-value variable-documentation custom-type custom-version
custom-set custom-requests

oriental-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

other-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

overwrite-mode
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
variable-documentation

query-replace
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache face
face-defface-spec face-documentation custom-version

query-replace-from-history-variable
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

query-replace-lazy-highlight
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

query-replace-skip-read-only
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

query-replace-to-history-variable
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

quit
  Plist: error-conditions error-message event-symbol-element-mask
event-symbol-elements modifier-cache

read-mail-command
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

return
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
ascii-character event-kind

right-fringe
  Plist: x-frame-parameter event-symbol-element-mask event-symbol-elements
modifier-cache

rmail
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
custom-group

rmail-file-name
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

rmail-output-file-alist
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

safe-local-eval-forms
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

scroll-bar-mode
  Plist: standard-value variable-documentation custom-type custom-set
custom-requests

select-window
  Plist: event-kind event-symbol-elements event-symbol-element-mask
modifier-cache

site-run-file
  Plist: standard-value variable-documentation custom-type custom-set
custom-requests

size-indication-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests event-symbol-element-mask event-symbol-elements
modifier-cache

solar-holidays
  Plist: risky-local-variable variable-documentation custom-autoload
custom-loads

split-window-vertically
  Plist: isearch-scroll event-symbol-element-mask event-symbol-elements
modifier-cache

switch-frame
  Plist: event-kind event-symbol-elements event-symbol-element-mask
modifier-cache

tab
  Plist: modifier-cache event-symbol-element-mask event-symbol-elements
ascii-character

temp-buffer-max-height
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

temp-buffer-resize-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests

text-mode-hook
  Plist: custom-options standard-value variable-documentation custom-type
custom-requests

tool-bar
  Plist: face face-defface-spec face-documentation custom-version
event-symbol-element-mask event-symbol-elements modifier-cache

tool-bar-mode
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-set custom-type custom-requests autoload

tools
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
custom-group

tooltip
  Plist: group-documentation custom-version custom-tag custom-group face
face-defface-spec face-documentation

tooltip-delay
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

tooltip-frame-parameters
  Plist: standard-value variable-documentation custom-type custom-tag
custom-requests

tooltip-hide-delay
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

tooltip-mode
  Plist: variable-documentation custom-autoload custom-loads standard-value
custom-set custom-type custom-requests

tooltip-recent-seconds
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

tooltip-short-delay
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

tooltip-use-echo-area
  Plist: standard-value variable-documentation custom-type custom-tag
custom-requests

tooltip-x-offset
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

tooltip-y-offset
  Plist: standard-value variable-documentation custom-tag custom-type
custom-requests

transient-mark-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests event-symbol-element-mask event-symbol-elements
modifier-cache

truncate-lines
  Plist: standard-value event-symbol-element-mask event-symbol-elements
modifier-cache variable-documentation

undo
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
custom-group

undo-ask-before-discard
  Variable: If non-nil ask about discarding undo info for the current
command.
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

unify-8859-on-decoding-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests custom-version

unify-8859-on-encoding-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-requests custom-version

utf-8-compose-scripts
  Plist: standard-value variable-documentation custom-version custom-type
custom-requests

utf-fragment-on-decoding
  Plist: standard-value variable-documentation custom-set custom-version
custom-type custom-requests

utf-translate-cjk-mode
  Plist: standard-value variable-documentation custom-set custom-type
custom-version custom-requests

utf-translate-cjk-unicode-range
  Plist: standard-value variable-documentation custom-version custom-type
custom-set custom-requests

vc
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache

vc-handled-backends
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

vc-stay-local
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

vertical-border
  Plist: face face-defface-spec face-documentation custom-version
display-table-slot

vertical-scroll-bar
  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
variable-documentation

view
  Plist: custom-group event-symbol-element-mask event-symbol-elements
modifier-cache

yank-excluded-properties
  Plist: standard-value variable-documentation custom-type custom-version
custom-requests

Re: Docstring line length

[Lennart Borgman]

Drew Adams wrote:

>        (In any case, many Plist entries already wrap as ugly
>         continuation lines, so they need to be fixed first.)
>
>    Could you show me an example?
>
>By "fixed" I meant to wrap (fill) each Plist entry.
>
>
>abbrev-mode
>  Plist: event-symbol-element-mask event-symbol-elements modifier-cache
>custom-group standard-value variable-documentation custom-type
>custom-requests
>  
>

Does this small patch make it more readable:


Index: apropos.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/apropos.el,v
retrieving revision 1.111
diff -c -r1.111 apropos.el
*** apropos.el    29 Nov 2005 23:52:59 -0000    1.111
--- apropos.el    21 Dec 2005 21:14:58 -0000
***************
*** 85,91 ****
    :group 'apropos
    :type 'face)
 
! (defcustom apropos-label-face 'italic
    "*Face for label (`Command', `Variable' ...) in Apropos output.
  A value of nil means don't use any special font for them, and also
  turns off mouse highlighting."
--- 85,91 ----
    :group 'apropos
    :type 'face)
 
! (defcustom apropos-label-face '(:underline t :foreground "blue" :slant 
italic)
    "*Face for label (`Command', `Variable' ...) in Apropos output.
  A value of nil means don't use any special font for them, and also
  turns off mouse highlighting."
***************
*** 976,990 ****
    (if (stringp (setq i (nth i apropos-item)))
        (progn
      (insert "  ")
!     (insert-text-button (button-type-get type 'apropos-label)
!                 'type type
!                 ;; Can't use the default button face, since
!                 ;; user may have changed the variable!
!                 ;; Just say `no' to variables containing faces!
!                 'face apropos-label-face
!                 'apropos-symbol (car apropos-item))
!     (insert ": ")
!     (insert (if do-keys (substitute-command-keys i) i))
      (or (bolp) (terpri)))))
 
 
--- 976,992 ----
    (if (stringp (setq i (nth i apropos-item)))
        (progn
      (insert "  ")
!         (let ((start (point)))
!           (insert-text-button (button-type-get type 'apropos-label)
!                               'type type
!                               ;; Can't use the default button face, since
!                               ;; user may have changed the variable!
!                               ;; Just say `no' to variables containing 
faces!
!                               'face apropos-label-face
!                               'apropos-symbol (car apropos-item))
!           (insert ": ")
!           (insert (if do-keys (substitute-command-keys i) i))
!           (fill-region start (point)))
      (or (bolp) (terpri)))))

Re: Docstring line length

[Richard M. Stallman]

I somehow thought we had legal papers from you, but I see that we
actually don't.  So we had better not install any more of your changes
until that is taken care of.  (I'll send you another message saying
how to do that.)

Legal papers for Emacs contributions (was: Re: Docstring line length)

[Giorgos Keramidas]

    Richard M. Stallman wrote:

    I somehow thought we had legal papers from you, but I see that we
    actually don't.  So we had better not install any more of your changes
    until that is taken care of.  (I'll send you another message saying
    how to do that.)

I apologize in advance if this is a FAQ, but I didn't have the time to
check all the details until now.

Are legal papers required for installing the FreeBSD/amd64 patch I came
up with a while ago too?  It's relatively simple, and it would be nice
to have it included with the next release.  Otherwise, we'd have to
commit it in the Ports tree of FreeBSD as a local diff :-/

- Giorgos

Re: Legal papers for Emacs contributions (was: Re: Docstring line length)

[Richard M. Stallman]

    Are legal papers required for installing the FreeBSD/amd64 patch I came
    up with a while ago too?

Alas, I don't remember anything about it.  Could you send it again?

Re: Legal papers for Emacs contributions (was: Re: Docstring line length)

[Giorgos Keramidas]

        Are legal papers required for installing the FreeBSD/amd64 patch
        I came up with a while ago too?

    Alas, I don't remember anything about it.  Could you send it again?

Yes, sure.  I can be found online at:
http://people.freebsd.org/~keramida/emacs/22/freebsd-amd64+libgcc.patch

Here it is, inline to save you the hassle of downloading it:

%%%
Index: configure.in
===================================================================
RCS file: /cvsroot/emacs/emacs/configure.in,v
retrieving revision 1.399
diff -u -r1.399 configure.in
--- configure.in	25 Oct 2005 01:09:39 -0000	1.399
+++ configure.in	28 Oct 2005 21:54:46 -0000
@@ -238,6 +238,7 @@
     case "${canonical}" in
       alpha*-*-freebsd*)	machine=alpha ;;
       i[3456]86-*-freebsd*)	machine=intel386 ;;
+      amd64-*-freebsd*|x86_64-*-freebsd*) machine=amdx86-64 ;;
     esac
   ;;
 
Index: src/m/amdx86-64.h
===================================================================
RCS file: /cvsroot/emacs/emacs/src/m/amdx86-64.h,v
retrieving revision 1.8
diff -u -r1.8 amdx86-64.h
--- src/m/amdx86-64.h	7 Aug 2005 09:52:27 -0000	1.8
+++ src/m/amdx86-64.h	28 Oct 2005 21:54:46 -0000
@@ -100,11 +100,38 @@
 /* Define XPNTR to avoid or'ing with DATA_SEG_BITS */
 #undef DATA_SEG_BITS
 
+#ifdef __FreeBSD__
+
+/* The libraries for binaries native to the build host's architecture are
+   installed under /usr/lib in FreeBSD, and the ones that need special paths
+   are 32-bit compatibility libraries (installed under /usr/lib32).  To build
+   a native binary of Emacs on FreeBSD/amd64 we can just point to /usr/lib.  */
+
+#undef START_FILES
+#define START_FILES pre-crt0.o /usr/lib/crt1.o /usr/lib/crti.o
+
+/* The duplicate -lgcc is intentional in the definition of LIB_STANDARD.
+   The reason is that some functions in libgcc.a call functions from libc.a,
+   and some libc.a functions need functions from libgcc.a.  Since most
+   versions of ld are one-pass linkers, we need to mention -lgcc twice,
+   or else we risk getting unresolved externals.  */
+#undef LIB_STANDARD
+#define LIB_STANDARD -lgcc -lc -lgcc /usr/lib/crtn.o
+
+#else /* !__FreeBSD__ */
+
 #undef START_FILES
 #define START_FILES pre-crt0.o /usr/lib64/crt1.o /usr/lib64/crti.o
 
+/* The duplicate -lgcc is intentional in the definition of LIB_STANDARD.
+   The reason is that some functions in libgcc.a call functions from libc.a,
+   and some libc.a functions need functions from libgcc.a.  Since most
+   versions of ld are one-pass linkers, we need to mention -lgcc twice,
+   or else we risk getting unresolved externals.  */
 #undef LIB_STANDARD
 #define LIB_STANDARD -lgcc -lc -lgcc /usr/lib64/crtn.o
+
+#endif /* __FreeBSD__ */
 
 /* arch-tag: 8a5e001d-e12e-4692-a3a6-0b15ba271c6e
    (do not change this comment) */
%%%

Re: Legal papers for Emacs contributions

[David Kastrup]

Giorgos Keramidas <keramida@ceid.upatras.gr> writes:

>     Richard M. Stallman wrote:
>
>     I somehow thought we had legal papers from you, but I see that we
>     actually don't.  So we had better not install any more of your changes
>     until that is taken care of.  (I'll send you another message saying
>     how to do that.)
>
> I apologize in advance if this is a FAQ, but I didn't have the time to
> check all the details until now.
>
> Are legal papers required for installing the FreeBSD/amd64 patch I
> came up with a while ago too?

Legal stuff pretty much is required for everything with few
exceptions.  While it is possible that in this case an exception might
apply, the next occasion where it won't is not far away if you intend
to contribute to Emacs.  So better start getting the legal hassle over
with as soon as possible if your work situation does not prohibit it.
It is a nuisance, but not to be avoided.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Legal papers for Emacs contributions

[Giorgos Keramidas]

    Legal stuff pretty much is required for everything with few
    exceptions.  While it is possible that in this case an
    exception might apply, the next occasion where it won't is not
    far away if you intend to contribute to Emacs.  So better start
    getting the legal hassle over with as soon as possible if your
    work situation does not prohibit it.  It is a nuisance, but not
    to be avoided.

Sure.  I don't think my work would be a problem, but it may take
a few days to find out, since I'm far away from our HQ and it
certainly makes sense to ask.  Thanks for the clarification :)

Re: Legal papers for Emacs contributions

[Richard M. Stallman]

    > Are legal papers required for installing the FreeBSD/amd64 patch I
    > came up with a while ago too?

That patch is small enough that we can put it in without papers.

Re: Docstring line length

[Juri Linkov]

> ! (defcustom apropos-label-face 'italic
>    "*Face for label (`Command', `Variable' ...) in Apropos output.
>  A value of nil means don't use any special font for them, and also
>  turns off mouse highlighting."
> --- 85,91 ----
>    :group 'apropos
>    :type 'face)
>
> ! (defcustom apropos-label-face '(:underline t :foreground "blue" :slant italic)

I think the right face to use here is `button':

(defcustom apropos-label-face 'button

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Docstring line length

[Lennart Borgman]

Juri Linkov wrote:

>>! (defcustom apropos-label-face 'italic
>>   "*Face for label (`Command', `Variable' ...) in Apropos output.
>> A value of nil means don't use any special font for them, and also
>> turns off mouse highlighting."
>>--- 85,91 ----
>>   :group 'apropos
>>   :type 'face)
>>
>>! (defcustom apropos-label-face '(:underline t :foreground "blue" :slant italic)
>>    
>>
>
>I think the right face to use here is `button':
>
>(defcustom apropos-label-face 'button
>  
>
This sounds good to me. However in that case I would propose that the 
color of the button face is set to "blue". This would make the link more 
easily recognized. Since this face is also used for help mode it would 
have the same benefit there.

A note: Underlined blue is the most common way to tell something is a 
link on a web page. On quite a lot of pages I have seen underlined black 
text who are not links (this is in my opinion quite confusing and I do 
not recommend it, but I have seen it).

Re: Docstring line length

[Juri Linkov]

>>I think the right face to use here is `button':
>>
>>(defcustom apropos-label-face 'button
>>
> This sounds good to me. However in that case I would propose that the
> color of the button face is set to "blue". This would make the link more
> easily recognized. Since this face is also used for help mode it would
> have the same benefit there.
>
> A note: Underlined blue is the most common way to tell something is a link
> on a web page. On quite a lot of pages I have seen underlined black text
> who are not links (this is in my opinion quite confusing and I do not
> recommend it, but I have seen it).

I agree.  I see no reason for Help links to have a different appearance
than Info links and Web links.

-- 
Juri Linkov
http://www.jurta.org/emacs/

link appearance (again) (was: RE: Docstring line length)

[Drew Adams]

    > A note: Underlined blue is the most common way to tell
    > something is a link
    > on a web page. On quite a lot of pages I have seen underlined
    > black text
    > who are not links (this is in my opinion quite confusing and I do not
    > recommend it, but I have seen it).

    I agree.  I see no reason for Help links to have a different appearance
    than Info links and Web links.

We've been through this before..., but add my vote (again) for underlined
blue foreground, for links - as is the case now in Info. Links are not the
same as buttons (even if we use a `button' face to implement them).

I would make an exception in buffers that are link-dense - that is,
essentially tables or lists of links. Such buffers include Dired, Buffer
List, Occur, and compilation (e.g. grep). Almost everything in such a buffer
is a link (or it should be).

In such buffers, I would prefer to see the whole line be a link (although,
where appropriate, it could be divided into more than one link, with
different destinations). And I would propose _not_ using any face to
indicate such links. The mouse-face is enough to indicate a link, because
the mouse is nearly always over some link in a link-dense buffer. The
mouse-face should then be an underline (perhaps blue) - that is, it should
look like a link.

Re: Docstring line length

[Richard M. Stallman]

    The following PList entries are longer than 80 chars (there are also plenty
    of Function, Command, and Variable entries that are longer than 80 chars,
    but the Plist entries, at least, could presumably be filled automatically):

It would be good to do that.  Would someone like to?

Re: Docstring line length

[Ken Raeburn]

On Dec 20, 2005, at 19:54, Luc Teirlinck wrote:
> Drew Adams wrote:
>
>    I'm sure most people do not do as I do, but I'm not sure that  
> most people
>    use fixed 80-char frames. Do we have any user data to go on?
>
> 80 char frames are the default configuration of Emacs.

Yup, but I wonder how many people resize their windows to something  
convenient to whatever they're working on, and ignore the 80-char  
"standard".  Especially with the popularity of variable-width fonts,  
I'm not sure how important a column-count width standard is these  
days.  Certainly for code and RFCs and such it makes sense, but  
what's the average user doing, and is she going to care about fixed- 
width fonts and 80-column limits?  I widen my Emacs window for some  
things, and at least on my Mac, resizing doesn't tell me how many  
columns wide it is, so when I go to put it back, I have no idea if  
I'm back at 80 columns; so I probably use not-80-column widths more  
than I realize....

It occurred to me recently to wonder, perhaps we should consider  
making the doc strings a little more structured and their display  
more intelligent: Explicit markers for line breaks and indented  
sections, and wrapped paragraphs for the main descriptive text, using  
whatever width (and font) the user has chosen for her window.  (Of  
course, that gets a bit more complicated if a help buffer is  
displayed in two windows of different sizes.)  Not *today*,  
obviously, but somewhere down the line....

(No, I haven't thought much about how to actually accomplish it.)

Ken

Re: Docstring line length

[Richard M. Stallman]

    It occurred to me recently to wonder, perhaps we should consider  
    making the doc strings a little more structured and their display  
    more intelligent: Explicit markers for line breaks and indented  
    sections, and wrapped paragraphs for the main descriptive text, using  
    whatever width (and font) the user has chosen for her window.

Putting such a plan into effect would be a very large job.  Since our
resources are limited, I am against this regardless of the details,
both now and after the release.  We have lots of other work to do.

Re: Docstring line length

[Johan Bockgård]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> To me 70 for most subsequent lines with an absolute limit of 79
> seems better than the current 60.  But I do not believe that this is
> a really big deal.

The default value of `emacs-lisp-docstring-fill-column' is 65, btw.

-- 
Johan Bockgård

Re: Docstring line length

[Luc Teirlinck]

>From my earlier message:

   67 for the first line.  That is a given.  68 already forces an ugly
   continuation line in the apropos output.

   To me 70 for most subsequent lines with an absolute limit of 79 seems
   better than the current 60.  But I do not believe that this is a
   really big deal.

I meant that whether the convention for "most" subsequent lines is no
big deal ("most" is vague anyway).  I believe that more than 79 for
_any_ line is really bad and that such docstrings should definitely be
fixed.  I also believe that docstrings with a first line longer than
67 should be fixed.

Sincerely,

Luc.

Re: Docstring line length

[Luc Teirlinck]

>From my earlier message:

   I meant that whether the convention for "most" subsequent lines is no
   big deal ("most" is vague anyway).

I meant that whether the convention for "most" subsequent lines is at
most 60 or at most 70 colums is no big deal (to me).

Sincerely,

Luc.

Re: Docstring line length

[Bill Wohler]

"Drew Adams" <drew.adams@oracle.com> writes:

> I'm sure most people do not do as I do, but I'm not sure that most people
> use fixed 80-char frames. Do we have any user data to go on?

Some people say that character-width standards are pretty much
obsolete these days. I disagree. Someone will always be able to have a
bigger screen than another so what might look good on one person's
screen will not look good on everyone else's.

So a standard width is a good idea so that code and text looks good on
*everyone's* screen.

Since TTYs have been 80 characters for decades, it is the best
standard. Indeed, the only standard.

If you can find data that says that 100% of the people use a larger
width, then perhaps we can consider upping the width to the lowest
common denominator.

But you won't since I use 80 columns ;-).

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

RE: Docstring line length

[Drew Adams]

    > I'm sure most people do not do as I do, but I'm not sure that
    > most people use fixed 80-char frames. Do we have any user data
    > to go on?

    Since TTYs have been 80 characters for decades, it is the best
    standard. Indeed, the only standard.

I have no objection to using 80 as the default, even for non-tty frames. I
was just curious whether anyone had any usage data.

Re: Docstring line length

[Stefan Monnier]

> Since TTYs have been 80 characters for decades, it is the best
> standard. Indeed, the only standard.

There are also issues of legibility which make it undesirable to use lines
longer than 80 chars unless a significant portion is devoted to whitepspace
(e.g. indentation, but note that excessive indentation usually leads to
unreadable code and it's then preferable to extract the inner code into its
own function).

I think it's important to make sure that if people really want to write
illegible text and unreadable code they can do it.  But I also think that
it's even more important to make sure that for sane people things work as
best as they can.


        Stefan

Re: Docstring line length

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Since TTYs have been 80 characters for decades, it is the best
>> standard. Indeed, the only standard.
>
> There are also issues of legibility which make it undesirable to use lines
> longer than 80 chars unless a significant portion is devoted to whitepspace
> (e.g. indentation, but note that excessive indentation usually leads to
> unreadable code and it's then preferable to extract the inner code into its
> own function).

Remember that the original punch card design (where the 80 is from)
had 6 columns in front and 8 in the back for different purposes,
making for a total of 66 material columns, which is rather close to
what book designers recommend as a good line length for a human
reader.

Whatever.  Let's move on.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Docstring line length

[Richard M. Stallman]

    > I'm sure most people do not do as I do, but I'm not sure that most people
    > use fixed 80-char frames. Do we have any user data to go on?

    Some people say that character-width standards are pretty much
    obsolete these days. I disagree.

I am with you on this--and my mind is firmly made up.
We will continue with the 80-column default, and continue
designing Emacs displays to work with it.

I'm not against making some displays adapt to other widths,
when someone wants to implement that, assuming the code is clean.
But let's not further consider any larger change.

Re: Docstring line length

[Richard M. Stallman]

    I understand why the first line shouldn't be wider than 67 characters,
    but why should most lines not be wider than 60?

It is because longer lines are harder to read, as has been said.

I do not want to consider changing this.  Let's work on what
needs to be done for the release.