* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
@ 2020-02-25 12:22 Štěpán Němec
2020-02-25 15:49 ` Drew Adams
2020-02-28 13:19 ` Eli Zaretskii
0 siblings, 2 replies; 12+ messages in thread
From: Štěpán Němec @ 2020-02-25 12:22 UTC (permalink / raw)
To: 39778
[-- Attachment #1: Type: text/plain, Size: 240 bytes --]
"Cf." is a common abbreviation in documentation.
Currently checkdoc warns about lack of double space after "cf." or
"Cf.". The attached patch adds an exception similar to the already
handled "eg." and and "ie.".
--
Štěpán
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-checkdoc-Don-t-mistake-cf.-for-sentence-end.patch --]
[-- Type: text/x-patch, Size: 1174 bytes --]
From bb705cf2425537b91dd39d24689bb2dbb378f73d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= <stepnem@gmail.com>
Date: Thu, 29 Aug 2019 19:42:21 +0200
Subject: [PATCH] checkdoc: Don't mistake "cf." for sentence end
* lisp/emacs-lisp/checkdoc.el (checkdoc-sentencespace-region-engine):
Recognize "cf." as an abbreviation, not a sentence end.
---
lisp/emacs-lisp/checkdoc.el | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index ccdddb47c3..e15836ee7d 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -2073,7 +2073,7 @@ checkdoc-sentencespace-region-engine
;; piece of an abbreviation
;; FIXME etc
(looking-at
- "\\([a-zA-Z]\\|[iI]\\.?e\\|[eE]\\.?g\\)\\."))
+ "\\([a-zA-Z]\\|[iI]\\.?e\\|[eE]\\.?g\\|[cC]f\\)\\."))
(error t))))
(if (checkdoc-autofix-ask-replace
b e
--
2.25.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 12:22 bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end Štěpán Němec
@ 2020-02-25 15:49 ` Drew Adams
2020-02-25 16:02 ` Štěpán Němec
2020-02-28 13:19 ` Eli Zaretskii
1 sibling, 1 reply; 12+ messages in thread
From: Drew Adams @ 2020-02-25 15:49 UTC (permalink / raw)
To: Štěpán Němec, 39778
> "Cf." is a common abbreviation in documentation.
>
> Currently checkdoc warns about lack of double space after "cf." or
> "Cf.". The attached patch adds an exception similar to the already
> handled "eg." and and "ie.".
Yes.
But even better is to remove uses of "Cf." (which
is not so common nowadays, and is understood by
fewer and fewer readers). It can typically be
replaced by something as simple as "Compare" or
sometimes even just "See also".
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 15:49 ` Drew Adams
@ 2020-02-25 16:02 ` Štěpán Němec
2020-02-25 16:35 ` Drew Adams
0 siblings, 1 reply; 12+ messages in thread
From: Štěpán Němec @ 2020-02-25 16:02 UTC (permalink / raw)
To: Drew Adams, 39778
On Tue, 25 Feb 2020 07:49:49 -0800
Drew Adams wrote:
>> "Cf." is a common abbreviation in documentation.
>>
>> Currently checkdoc warns about lack of double space after "cf." or
>> "Cf.". The attached patch adds an exception similar to the already
>> handled "eg." and and "ie.".
>
> Yes.
>
> But even better is to remove uses of "Cf." (which
> is not so common nowadays, and is understood by
> fewer and fewer readers). It can typically be
> replaced by something as simple as "Compare" or
> sometimes even just "See also".
Do you have any hard data for your claims? Couldn't the same be argued
about "e.g." vs "for example" or "i.e." vs "that is"? Is "cf." really so
much less common?
Anyway, it is probably largely subjective, but unless you can bring up
many examples of potential further requests (I can't think of anything
else myself), just adding "cf." shouldn't hurt, should it?
--
Štěpán
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 16:02 ` Štěpán Němec
@ 2020-02-25 16:35 ` Drew Adams
2020-02-25 16:41 ` Bastien
0 siblings, 1 reply; 12+ messages in thread
From: Drew Adams @ 2020-02-25 16:35 UTC (permalink / raw)
To: Štěpán Němec, 39778
> > Yes.
> >
> > But even better is to remove uses of "Cf." (which
> > is not so common nowadays, and is understood by
> > fewer and fewer readers). It can typically be
> > replaced by something as simple as "Compare" or
> > sometimes even just "See also".
>
> Do you have any hard data for your claims?
No, and I won't bother looking for it (which doesn't
mean that such data doesn't exist).
> Couldn't the same be argued about "e.g." vs "for
> example" or "i.e." vs "that is"?
Anyone could argue that if they wanted to, of course.
I wouldn't argue it. In my experience, those two,
and "etc.", are pretty commonly recognized and
understood ("i.e." probably less so than the others,
sometimes being misunderstood as the same as "e.g.").
> Is "cf." really so much less common?
I think it is, but I won't try to support that as a fact.
> Anyway, it is probably largely subjective, but unless you can bring up
> many examples of potential further requests (I can't think of anything
> else myself), just adding "cf." shouldn't hurt, should it?
I never said that removing the bug of 2-spaces after
"cf." would hurt or is a bad idea.
In fact, I said, "Yes." It's a good idea. Even
better is to remove occurrences of "cf.", but yes,
that fix should be done anyway, in case someone
does use "cf."
^ permalink raw reply [flat|nested] 12+ messages in thread* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 16:35 ` Drew Adams
@ 2020-02-25 16:41 ` Bastien
2020-02-25 21:00 ` Stefan Kangas
0 siblings, 1 reply; 12+ messages in thread
From: Bastien @ 2020-02-25 16:41 UTC (permalink / raw)
To: Drew Adams; +Cc: 39778, Štěpán Němec
Hi Drew and Štěpán,
Drew Adams <drew.adams@oracle.com> writes:
>> Is "cf." really so much less common?
>
> I think it is, but I won't try to support that as a fact.
FWIW I think "cf." is pretty common. It also has the advantage
of being understood by non-english speaker.
>> Anyway, it is probably largely subjective, but unless you can bring up
>> many examples of potential further requests (I can't think of anything
>> else myself), just adding "cf." shouldn't hurt, should it?
>
> I never said that removing the bug of 2-spaces after
> "cf." would hurt or is a bad idea.
>
> In fact, I said, "Yes." It's a good idea.
I also think it is a good idea.
--
Bastien
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 16:41 ` Bastien
@ 2020-02-25 21:00 ` Stefan Kangas
2020-02-25 21:41 ` Drew Adams
2020-02-26 2:57 ` Richard Stallman
0 siblings, 2 replies; 12+ messages in thread
From: Stefan Kangas @ 2020-02-25 21:00 UTC (permalink / raw)
To: Bastien; +Cc: 39778, Štěpán Němec
Bastien <bzg@gnu.org> writes:
> Drew Adams <drew.adams@oracle.com> writes:
>
>>> Is "cf." really so much less common?
>>
>> I think it is, but I won't try to support that as a fact.
While looking into this, I found Writing for Computer Science by
(2004) by Justin Zobel.
"It is often tempting to use abbreviations such as 'no.', 'i.e.',
'e.g.' 'c.f.' and 'w.r.t.' These save little space on the page,
but slow readers down. It is almost always desirable to expand
these abbreviations, to 'number', 'that is', 'for example',
'compared with' (or more accurately 'in contrast to', since that
is the sense in which 'c.f.' should be used), and 'with respect
to', or synonyms of these expressions. Where such abbreviations
are used, the punctuation should be as if the expanded form were
used. Also consider expanding abbreviations such as 'Fig.' and
'Alg.' and don't use concoctions such as '1st' or '2nd'. Months
should not be abbreviated. Make sure that all abbreviations and
acronyms are explained when they are first used." (page 57)
I think the above points should be carefully considered.
> FWIW I think "cf." is pretty common. It also has the advantage
> of being understood by non-english speaker.
That's not the case when it comes to speakers of Swedish. I don't
know this for a fact, but I'd assume that this abbreviation is more
common in the Romance languages.
Best regards,
Stefan Kangas
^ permalink raw reply [flat|nested] 12+ messages in thread* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 21:00 ` Stefan Kangas
@ 2020-02-25 21:41 ` Drew Adams
2020-02-26 2:57 ` Richard Stallman
1 sibling, 0 replies; 12+ messages in thread
From: Drew Adams @ 2020-02-25 21:41 UTC (permalink / raw)
To: Stefan Kangas, Bastien; +Cc: 39778, Štěpán Němec
> >>> Is "cf." really so much less common?
> >> I think it is, but I won't try to support that as a fact.
>
> While looking into this, I found Writing for Computer Science by
> (2004) by Justin Zobel.
>
> "It is often tempting to use abbreviations such as 'no.', 'i.e.',
> 'e.g.' 'c.f.' and 'w.r.t.' These save little space on the page,
> but slow readers down. It is almost always desirable to expand
> these abbreviations, to 'number', 'that is', 'for example',
> 'compared with' (or more accurately 'in contrast to', since that
> is the sense in which 'c.f.' should be used), and 'with respect
> to', or synonyms of these expressions. Where such abbreviations
> are used, the punctuation should be as if the expanded form were
> used. Also consider expanding abbreviations such as 'Fig.' and
> 'Alg.' and don't use concoctions such as '1st' or '2nd'. Months
> should not be abbreviated. Make sure that all abbreviations and
> acronyms are explained when they are first used." (page 57)
>
> I think the above points should be carefully considered.
I agree. Nothing is really gained, and something is
lost, for many readers.
> > FWIW I think "cf." is pretty common. It also has the advantage
> > of being understood by non-english speaker.
>
> That's not the case when it comes to speakers of Swedish. I don't
> know this for a fact, but I'd assume that this abbreviation is more
> common in the Romance languages.
Yes, especially for non-English readers, in general.
Many programmers whose main language is not English
will understand "see also" or "compare". But how
many will need to look up "cf."?
(But again, reasons to avoid using "cf." are not
reasons not to fix the 2-space bug. That should
be done, regardless of whether we replace uses of
"cf.")
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 21:00 ` Stefan Kangas
2020-02-25 21:41 ` Drew Adams
@ 2020-02-26 2:57 ` Richard Stallman
2020-02-26 15:03 ` Drew Adams
1 sibling, 1 reply; 12+ messages in thread
From: Richard Stallman @ 2020-02-26 2:57 UTC (permalink / raw)
To: Stefan Kangas; +Cc: bzg, 39778, stepnem
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> "It is often tempting to use abbreviations such as 'no.', 'i.e.',
> 'e.g.' 'c.f.' and 'w.r.t.' These save little space on the page,
> but slow readers down.
That is good advice, but it changes the subject.
The question is not whether to use those old abbreviations.
It is whether Emacs should support editing of files that do use them.
--
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
^ permalink raw reply [flat|nested] 12+ messages in thread* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-26 2:57 ` Richard Stallman
@ 2020-02-26 15:03 ` Drew Adams
2020-03-10 2:41 ` Richard Stallman
0 siblings, 1 reply; 12+ messages in thread
From: Drew Adams @ 2020-02-26 15:03 UTC (permalink / raw)
To: rms, Stefan Kangas; +Cc: bzg, 39778, stepnem
>> "It is often tempting to use abbreviations such as 'no.', 'i.e.',
>> 'e.g.' 'c.f.' and 'w.r.t.' These save little space on the page,
>> but slow readers down.
>
> That is good advice, but it changes the subject.
> The question is not whether to use those old abbreviations.
> It is whether Emacs should support editing of files that do use them.
Really? Was that the question? I didn't
understand that that question was being raised.
Why shouldn't Emacs support editing files that
use _any_ text? Was there an argument against
letting one edit such files? Or did you perhaps
mean something special (what?) here by "support"?
The bug reported was only about Emacs treating
the `.' as a sentence end. I think everyone
agreed that that's a bug to be fixed ("cf."
does not end a sentence, generally).
Beyond the bug, the thread discussed the use
of "cf." by Emacs's own doc. Yes, that was a
change of subject from the bug report. But
that was the only real discussion (question)
here, I think. Unless I missed someone's
argument in favor of two spaces after "cf.".
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
2020-02-25 12:22 bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end Štěpán Němec
2020-02-25 15:49 ` Drew Adams
@ 2020-02-28 13:19 ` Eli Zaretskii
1 sibling, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2020-02-28 13:19 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 39778-done
> From: Štěpán Němec
> <stepnem@gmail.com>
> Date: Tue, 25 Feb 2020 13:22:16 +0100
>
> "Cf." is a common abbreviation in documentation.
>
> Currently checkdoc warns about lack of double space after "cf." or
> "Cf.". The attached patch adds an exception similar to the already
> handled "eg." and and "ie.".
Thanks, I installed this on the emacs-27 branch.
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2020-03-10 13:58 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-02-25 12:22 bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end Štěpán Němec
2020-02-25 15:49 ` Drew Adams
2020-02-25 16:02 ` Štěpán Němec
2020-02-25 16:35 ` Drew Adams
2020-02-25 16:41 ` Bastien
2020-02-25 21:00 ` Stefan Kangas
2020-02-25 21:41 ` Drew Adams
2020-02-26 2:57 ` Richard Stallman
2020-02-26 15:03 ` Drew Adams
2020-03-10 2:41 ` Richard Stallman
2020-03-10 13:58 ` Stefan Kangas
2020-02-28 13:19 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).