Re: [PATCH] maint.mk: catch "see @xref{}"

[Jim Meyering]

Jim Meyering wrote:

> Eric Blake wrote:
>> On 04/16/2012 12:22 PM, Jim Meyering wrote:
>>> +++ b/top/maint.mk
>>> @@ -932,8 +932,11 @@ sc_prohibit_doubled_word:
>>>  # A regular expression matching undesirable combinations of words like
>>>  # "can not"; this matches them even when the two words appear on different
>>>  # lines, but not when there is an intervening delimiter like "#" or "*".
>>> +# Similarly undesirable, "See @xref{...}" expands to "See *Note ...".
>>
>> Doesn't it actually expand to "See see *Note"?
>
> What I wrote is the expansion in "info" output.
> In dvi/pdf output, it does expand to "See see Section..." (i.e., no
> "*Note" there), so I'll have to revise the advice in the comment.
> Per "info texinfo",
>
>     8.4 address@hidden'
>     ===========
>
>     The address@hidden' command generates a cross reference for the beginning 
> of a
>     sentence.
>
> So any preceding token should be punctuation.

It's not feasible to detect preceding punctuation
(skipping things like macro uses/definitions and comments)
without a full-blown parser, so here's a heuristic that should
be good enough.  It happens to catch two more nits in coreutils.texi:

>From d279b8ee8770a3dbe32fa4b4e2c887537984b69c Mon Sep 17 00:00:00 2001
From: Akim Demaille <address@hidden>
Date: Mon, 16 Apr 2012 20:21:51 +0200
Subject: [PATCH] maint.mk: catch "see @xref{}" and similar

* top/maint.mk (prohibit_undesirable_word_seq_RE_): An @xref{...}
should start a sentence.  Prohibit most other uses.
---
 ChangeLog    |    7 +++++++
 top/maint.mk |    7 ++++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index c08ba76..479c360 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2012-04-16  Akim Demaille  <address@hidden>
+       and Jim Meyering  <address@hidden>
+
+       maint.mk: catch "see @xref{}" and similar
+       * top/maint.mk (prohibit_undesirable_word_seq_RE_): Also
+       prohibit "See also @xref{", "Also see @pxref{", and similar.
+
 2012-04-16  Jim Meyering  <address@hidden>

        bootstrap: really use gnulib's po/Makefile.in.in
diff --git a/top/maint.mk b/top/maint.mk
index 2228a37..1353529 100644
--- a/top/maint.mk
+++ b/top/maint.mk
@@ -932,8 +932,13 @@ sc_prohibit_doubled_word:
 # A regular expression matching undesirable combinations of words like
 # "can not"; this matches them even when the two words appear on different
 # lines, but not when there is an intervening delimiter like "#" or "*".
+# Similarly undesirable, "See @xref{...}", since an @xref should start
+# a sentence.  Explicitly prohibit any prefix that is a combination of
+# "see" and "also".  Also prohibit a prefix matching "\w+ +".
+undesirable_xref_re_ ?=                                                        
\
+  (?:\w+ +|(?:see(?:\s+also)?|also(?:\s+see)?)\s+)address@hidden
 prohibit_undesirable_word_seq_RE_ ?=                                   \
-  /\bcan\s+not\b/gims
+  /(?:\bcan\s+not\b|$(undesirable_xref_re_))/gims
 prohibit_undesirable_word_seq_ =                                       \
     -e 'while ($(prohibit_undesirable_word_seq_RE_))'                  \
     $(perl_filename_lineno_text_)
--
1.7.10.169.g146fe