From: "Drew Adams" <drew.adams@oracle.com>
To: "'Eli Zaretskii'" <eliz@gnu.org>, "'Xue Fuqiao'" <xfq.free@gmail.com>
Cc: 13801@debbugs.gnu.org
Subject: bug#13801: [PATCH] Trivial fix for files.el
Date: Sun, 24 Feb 2013 09:47:44 -0800 [thread overview]
Message-ID: <6EA8FD3B20FB44C289A386DEA3E477D9@us.oracle.com> (raw)
In-Reply-To: <83mwutkayo.fsf@gnu.org>
> 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.
next prev parent reply other threads:[~2013-02-24 17:47 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-02-24 6:33 bug#13801: [PATCH] Trivial fix for files.el Xue Fuqiao
2013-02-24 15:06 ` Eli Zaretskii
2013-02-24 17:47 ` Drew Adams [this message]
2013-02-24 21:45 ` Stephen Berman
2013-02-24 22:27 ` Drew Adams
2013-02-24 22:47 ` Xue Fuqiao
2013-12-17 15:10 ` Chong Yidong
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=6EA8FD3B20FB44C289A386DEA3E477D9@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=13801@debbugs.gnu.org \
--cc=eliz@gnu.org \
--cc=xfq.free@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.