GNU bug report logs - #39778
[PATCH] checkdoc: Don't mistake "cf." for sentence end

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39778 in the body.
You can then email your comments to 39778 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Štěpán Němec <stepnem <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 13:22:16 +0100

[Message part 1 (text/plain, inline)]

"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

[0001-checkdoc-Don-t-mistake-cf.-for-sentence-end.patch (text/x-patch, inline)]

From bb705cf2425537b91dd39d24689bb2dbb378f73d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= <stepnem <at> 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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Štěpán Němec <stepnem <at> gmail.com>,
 39778 <at> debbugs.gnu.org
Subject: RE: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 07:49:49 -0800 (PST)

> "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".

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

From: Štěpán Němec <stepnem <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 39778 <at> debbugs.gnu.org
Subject: RE: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 17:02:12 +0100

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Štěpán Němec <stepnem <at> gmail.com>,
 39778 <at> debbugs.gnu.org
Subject: RE: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 08:35:00 -0800 (PST)

> > 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."

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

From: Bastien <bzg <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 39778 <at> debbugs.gnu.org,
 Štěpán Němec <stepnem <at> gmail.com>
Subject: Re: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 17:41:40 +0100

Hi Drew and Štěpán,

Drew Adams <drew.adams <at> 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

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Bastien <bzg <at> gnu.org>
Cc: 39778 <at> debbugs.gnu.org,
 Štěpán Němec <stepnem <at> gmail.com>,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 22:00:29 +0100

Bastien <bzg <at> gnu.org> writes:

> Drew Adams <drew.adams <at> 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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Bastien <bzg <at> gnu.org>
Cc: 39778 <at> debbugs.gnu.org,
 Štěpán Němec <stepnem <at> gmail.com>
Subject: RE: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 13:41:31 -0800 (PST)

> >>> 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.")

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

From: Richard Stallman <rms <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: bzg <at> gnu.org, 39778 <at> debbugs.gnu.org, stepnem <at> gmail.com
Subject: Re: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 25 Feb 2020 21:57:53 -0500

[[[ 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)

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

From: Drew Adams <drew.adams <at> oracle.com>
To: rms <at> gnu.org, Stefan Kangas <stefan <at> marxist.se>
Cc: bzg <at> gnu.org, 39778 <at> debbugs.gnu.org, stepnem <at> gmail.com
Subject: RE: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Wed, 26 Feb 2020 07:03:39 -0800 (PST)

>> "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.".

Message #34 received at 39778-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Štěpán Němec <stepnem <at> gmail.com>
Cc: 39778-done <at> debbugs.gnu.org
Subject: Re: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Fri, 28 Feb 2020 15:19:45 +0200

> From: Štěpán Němec
>  <stepnem <at> 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.

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

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: bzg <at> gnu.org, 39778 <at> debbugs.gnu.org, stefan <at> marxist.se, stepnem <at> gmail.com
Subject: Re: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Mon, 09 Mar 2020 22:41:39 -0400

[[[ 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. ]]]

  > Beyond the bug, the thread discussed the use
  > of "cf." by Emacs's own doc.

I did not see that, but as regards that issue
I am in favor of replacing those abbreviations.


-- 
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)

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Richard Stallman <rms <at> gnu.org>
Cc: Bastien <bzg <at> gnu.org>, 39778 <at> debbugs.gnu.org,
 Štěpán Němec <stepnem <at> gmail.com>,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#39778: [PATCH] checkdoc: Don't mistake "cf." for sentence end
Date: Tue, 10 Mar 2020 14:58:42 +0100

Richard Stallman <rms <at> gnu.org> writes:

> I did not see that, but as regards that issue
> I am in favor of replacing those abbreviations.

I have now created Bug#40011 titled "Remove unnecessary abbreviations
from documentation":
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=40011

Best regards,
Stefan Kangas

Previous Next

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