desktop-missing-file-warning doc

desktop-missing-file-warning doc

[Luc Teirlinck]

`(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'.
  
============================================================

Re: desktop-missing-file-warning doc

[Luc Teirlinck]

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

Re: desktop-missing-file-warning doc

[Luc Teirlinck]

>From my previous message:

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

No, did not happen.  I guess that this is a local problem with my mail
setup rather than an Emacs devel problem.  I will try to figure out
what causes this strangeness.  Anyway, if somebody other than Lars
replies, please CC "Lars Hansen <lists@soem.dk>" manually.

Sincerely,

Luc.

Re: desktop-missing-file-warning doc

[Luc Teirlinck]

>From my previous message:

   No, did not happen.  I guess that this is a local problem with my mail
   setup rather than an Emacs devel problem.

As you can see from the latest mangled CC, it definitely _is_  a local problem.

Sincerely,

Luc.

Re: desktop-missing-file-warning doc

[Lars Hansen]

Luc Teirlinck wrote:

>===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'.
>  
>============================================================
>  
>
This is definitely an improvement.
However, the file is not recreated, only its buffer. So maybe it should be

   If non-nil,`desktop-read' offers to recreate the buffer of a deleted
file.

But that text is to wide. Maybe

   If non-nil, offer to recreate the buffer of a deleted file.

then? Also, the prompt

   (y-or-n-p (concat msg " Re-create? "))

in desktop-restore-file-buffer should be changed to

   (y-or-n-p (concat msg " Re-create buffer? "))

Re: desktop-missing-file-warning doc

[Luc Teirlinck]

Lars Hansen wrote:

   But that text is to wide. Maybe

      If non-nil, offer to recreate the buffer of a deleted file.

   then? Also, the prompt

      (y-or-n-p (concat msg " Re-create? "))

   in desktop-restore-file-buffer should be changed to

      (y-or-n-p (concat msg " Re-create buffer? "))

Yes, that looks good.

Sincerely,

Luc.

Re: desktop-missing-file-warning doc

[Lars Hansen]

Luc Teirlinck wrote:

>Yes, that looks good.
>  
>
Installed. Thanks!

Re: desktop-missing-file-warning doc

[Richard Stallman]

    But that text is to wide. Maybe

       If non-nil, offer to recreate the buffer of a deleted file.

    then? Also, the prompt

       (y-or-n-p (concat msg " Re-create? "))

    in desktop-restore-file-buffer should be changed to

       (y-or-n-p (concat msg " Re-create buffer? "))

Those both seem like improvements.