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

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

[Štěpán Němec]

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

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

[Drew Adams]

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

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

[Štěpán Němec]

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

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

[Drew Adams]

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

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

[Bastien]

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

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

[Stefan Kangas]

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

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

[Drew Adams]

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

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

[Richard Stallman]

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

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

[Drew Adams]

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

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

[Eli Zaretskii]

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

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

[Richard Stallman]

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

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

[Stefan Kangas]

Richard Stallman <rms@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