man page "SEE ALSO": prohibit terminating "."

[Jim Meyering]

Pádraig Brady wrote:
...
> commit f2dabd68064a3324d08285e0d4f013d6d9cf6191
> Author: Benoît Knecht <address@hidden>
> Date:   Fri Jul 8 14:52:41 2011 +0200
>
>     doc: don't terminate SEE ALSO sections with a period
>
>     man-pages(7) explicitly says about SEE ALSO sections: "Do not terminate
>     this with a period." This is also in line with all the other man pages
>     in coreutils.
>
>     * man/cat.x: Remove period at the end of the SEE ALSO section.
>     * man/tac.x: Likewise.
>
> -----------------------------------------------------------------------
>
> Summary of changes:
>  man/cat.x |    2 +-
>  man/tac.x |    2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/man/cat.x b/man/cat.x
> index 0890200..b84600f 100644
> --- a/man/cat.x
> +++ b/man/cat.x
> @@ -3,4 +3,4 @@ cat \- concatenate files and print on the standard output
>  [DESCRIPTION]
>  .\" Add any additional description here
>  [SEE ALSO]
> -\fBtac\fP(1).
> +\fBtac\fP(1)
...

Thanks!

However, I'll never remember that, so here's a crutch
to ensure that I don't have to:

>From 145b871482590ba79fd7bd143c4aaa3a00d11e20 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Fri, 8 Jul 2011 17:10:17 +0200
Subject: [PATCH] maint: add syntax-check rule to prohibit "."-terminated "SEE
 ALSO"

* cfg.mk (sc_prohibit_man_see_also_period): Prohibit a period at
the end of the first line after a "SEE ALSO" marker in man/*.x.
---
 cfg.mk |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/cfg.mk b/cfg.mk
index ce27cf6..d36f7c8 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -219,6 +219,14 @@ sc_prohibit_tab_based_indentation:
        halt='TAB in indentation; use only spaces'                      \
          $(_sc_search_regexp)

+# The SEE ALSO section of a man page should not be terminated with
+# a period.  Check the first line after each "SEE ALSO" line in man/*.x:
+sc_prohibit_man_see_also_period:
+       @grep -nB1 '\.$$' $$($(VC_LIST_EXCEPT) | grep 'man/.*\.x$$')    \
+           | grep -A1 -e '-\[SEE ALSO\]' | grep '\.$$' &&              \
+         { echo '$(ME): do not end "SEE ALSO" section with a period'   \
+             1>&2; exit 1; } || :
+
 # Don't use "indent-tabs-mode: nil" anymore.  No longer needed.
 sc_prohibit_emacs__indent_tabs_mode__setting:
        @prohibit='^( *[*#] *)?indent-tabs-mode:'                       \
--
1.7.6.430.g34be2