maint.mk: expand syntax-check rule to catch @xref and @pxref abuse

* top/maint.mk (prohibit_undesirable_word_seq_RE_): An @xref{...}
should start a sentence and should not be preceded by "see",
"see also", etc.  Add heuristic for @pxref too.

diff --git a/ChangeLog b/ChangeLog
index c08ba76..479c360 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2012-04-16  Akim Demaille  <akim@lrde.epita.fr>
+       and Jim Meyering  <meyering@redhat.com>
+
+       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  <meyering@redhat.com>
 
        bootstrap: really use gnulib's po/Makefile.in.in

diff --git a/top/maint.mk b/top/maint.mk
index 2228a37..1c7af03 100644 (file)
--- a/top/maint.mk
+++ b/top/maint.mk
@@ -932,8 +932,15 @@ 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 of "see" or "also".
+# Also prohibit a prefix matching "\w+ +".
+# @pxref gets the same see/also treatment and should be parenthesized;
+# presume it must *not* start a sentence.
+bad_xref_re_ ?= (?:[\w,:;] +|(?:see|also)\s+)\@xref\{
+bad_pxref_re_ ?= (?:[.!?]|(?:see|also))\s+\@pxref\{
 prohibit_undesirable_word_seq_RE_ ?=                                   \
-  /\bcan\s+not\b/gims
+  /(?:\bcan\s+not\b|$(bad_xref_re_)|$(bad_pxref_re_))/gims
 prohibit_undesirable_word_seq_ =                                       \
     -e 'while ($(prohibit_undesirable_word_seq_RE_))'                  \
     $(perl_filename_lineno_text_)