Re: desktop-missing-file-warning doc

[Luc Teirlinck <teirllm@dms.auburn.edu>]

My CC to `Lars Hansen <lists@soem.dk>' in my previously sent message
(repeated below) somehow disappeared from the version that was sent to
me by emacs-devel.  I _did_ include it in the message I sent: it is in
the copy that got sent to my archive file.  I do not know what happened.

Anyway, if you reply, reply to this version.  I hope the CC comes
through correctly this time.

Original message:

`(elisp)Documentation Tips' states that the first line of a docstring
should not be wider than 67 characters.  The stated reason for that is
that otherwise it looks bad in apropos output.  But for defcustoms,
another reason is that if the first line is too long, it can look
really bad in a Custom buffer.  Just do `M-x customize-group desktop RET'
and look at desktop-missing-file-warning (assuming the default 80 chars
per line).

The first line of desktop-missing-file-warning is way too long:

If non-nil then `desktop-read' asks if a non-existent file should be recreated.

It has other problems.  If you just look at that first line, you get
the impression that if the value is nil, `desktop-read' creates the
file without asking, especially given the -warning at the end of the
name.  That is not what happens.  Since it seems impossible to
recreate a file that never existed, I guess that non-existent means
deleted.  The current first line uses the passive and there is another
convention to avoid that if it is unnecessary.

What about the following alternative first line, which reduces the
length of the first line to 60 characters, does not use passive and in
addition is also, I believe, clearer and easier to read.  I could
install if desired.

===File ~/desktop.el-diff===================================
*** desktop.el	13 May 2006 11:24:56 -0500	1.100
--- desktop.el	13 May 2006 16:56:13 -0500	
***************
*** 201,207 ****
    :version "22.1")
  
  (defcustom desktop-missing-file-warning nil
!   "*If non-nil then `desktop-read' asks if a non-existent file should be recreated.
  Also pause for a moment to display message about errors signaled in
  `desktop-buffer-mode-handlers'.
  
--- 201,207 ----
    :version "22.1")
  
  (defcustom desktop-missing-file-warning nil
!   "If non-nil,`desktop-read' offers to recreate a deleted file.
  Also pause for a moment to display message about errors signaled in
  `desktop-buffer-mode-handlers'.
  
============================================================