GNU bug report logs - #13801
[PATCH] Trivial fix for files.el

Previous Next

Full log

Message #11 received at 13801 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>, "'Xue Fuqiao'" <xfq.free <at> gmail.com>
Cc: 13801 <at> debbugs.gnu.org
Subject: RE: bug#13801: [PATCH] Trivial fix for files.el
Date: Sun, 24 Feb 2013 09:47:44 -0800

> The first line of the doc string should concisely say what
> the option does.

Correct.

Including, if possible, what a nil or non-nil value does, if the option is
Boolean.  And the first line should (must) be a full sentence.

> The old doc string did it, albeit not perfectly;

Incorrect.  The first line did not do that at all.  At all.

> the one you suggest does not.

Correct.  My guess is that it was an attempt to provide a short full sentence
(good), but it does not say what the option does (not good).

What is important in both the old and new doc strings, and can serve as the
first line, is that the option does this (77 chars):

"Non-nil means break a hard link for the visited file and write to a new file."

If you feel that 77 chars is too much, you can drop "a" before "hard link" or
"the" before "visited file".  The rest of the doc string can clarify things
further (e.g., mentioning `buffer-file-name').

Whatever the wording chosen, the point is that non-nil means Emacs writes a new
file, bypassing any hard link for `buffer-file-name'.

In fact, I'm not sure about "break" here.  Is the effect that the hard link no
longer exists, or simply that it is ignored by Emacs when saving?  Depending on
the answer, the doc might need to be tweaked a little more.

The old first line was not even a complete sentence.  And the old first sentence
was four lines!

And unless I'm mistaken, the old first sentence was incorrect or at least
misleading regarding the condition where the option applies: "has multiple
hardlinks".

I think the correct criterion is simply having a hard link for the visited file
(`buffer-file-name'), regardless of whether there are any other hard links,
i.e., not necessarily multiple such.

It is not easy to write a short summary sentence, especially when English is not
your maternal language.  This is a welcome initiative from Fuqiao.  He clearly
takes an interest in the doc (as do Eli and Drew), and that is a fairly rare
resource.  Thank you.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.