[PATCH] INSTALL, Makefile, cmd.mk, lint-man.mk: Lint about '\" t' comment for tbl(1)

[Alejandro Colomar <alx.manpages@gmail.com>]

This is to make sure that we have correct \" t comments in the pages,
which are necessary for the Debian package checker:

On 8/19/22 22:21, Jakub Wilk wrote:
> * Michael Kerrisk <mtk.manpages@gmail.com>, 2020-07-24 12:13:
>> For 15 years or at least, I've not paid any attention to adding the
>> 't' comments when I added tables to pages, and I do recall anyone
>> reporting ill effects.  So, I'm inclined to apply Mike's patch, but
>> will hold off a moment, in case there's other feedback.
>
> I'm a bit late, but...
>
> Lintian, the Debian package checker, sets the MANROFFSEQ environment
> variable to empty string as a speed optimization.  This turns off
> loading preprocessors that weren't explicitly declared in the source.
> The lack of '\" comments can cause false positives (and maybe also
> false negatives?) in Lintian.
>
> The use of $MANROFFSEQ for Lintian was proposed here:
> https://bugs.debian.org/677874
>
> Beware that the man(1) man page does not correctly explain what
> $MANROFFSEQ does: <https://bugs.debian.org/971009>

Also update the dependencies list, since now we also need head(1) and
tail(1) for linting man(7) source.

Link: <https://lore.kernel.org/linux-man/07a7d4e7-79a6-b2c3-6892-1e39a0679f27@gmail.com/T/#mcf36c8a387fd5ff4f800dc220e3dbdd229b556bd>
Cc: Mike Frysinger <vapier@gentoo.org>
Cc: Mike Frysinger <vapier@chromium.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Reported-by: Jakub Wilk <jwilk@jwilk.net>
Co-developed-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Jakub,

Since you contributed the initial rough scripts used in this patch, it's
fair to say that you co-developed it.  Would you mind signing off the
patch?

Cheers,

Alex


 INSTALL         |  2 ++
 Makefile        |  1 +
 lib/cmd.mk      |  2 ++
 lib/lint-man.mk | 22 +++++++++++++++++++++-
 4 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/INSTALL b/INSTALL
index bcaadf763..ab513f8c4 100644
--- a/INSTALL
+++ b/INSTALL
@@ -93,7 +93,9 @@ Description
           -  For linting man(7) source:
              -  eqn(1)
              -  grotty(1)
+             -  head(1)
              -  mkdir(1)
+             -  tail(1)
              -  tbl(1)
              -  troff(1) >= 1.23.0 - GNU troff is required.
 
diff --git a/Makefile b/Makefile
index e7be1e291..66f02dea8 100644
--- a/Makefile
+++ b/Makefile
@@ -71,6 +71,7 @@ help:
 	$(info	lint-man		Wrapper for lint-man-* targets)
 	$(info	lint-man-groff		Lint man pages with groff(1))
 	$(info	lint-man-mandoc		Lint man pages with mandoc(1))
+	$(info	lint-man-tbl		Lint man pages about '\" t' comment for tbl(1))
 	$(info	)
 	$(info	[un]install		Alias for "[un]install-man")
 	$(info	[un]install-man		Wrapper for [un]install-man* targets)
diff --git a/lib/cmd.mk b/lib/cmd.mk
index c9c22d0ae..7d6d9abd9 100644
--- a/lib/cmd.mk
+++ b/lib/cmd.mk
@@ -14,12 +14,14 @@ FIND       := find
 GIT        := git
 GREP       := grep
 GZIP       := gzip
+HEAD       := head
 INSTALL    := install
 LOCALE     := locale
 PKG-CONFIG := pkg-config
 SED        := sed
 SORT       := sort
 TAC        := tac
+TAIL       := tail
 TAR        := tar
 XARGS      := xargs
 XZ         := xz
diff --git a/lib/lint-man.mk b/lib/lint-man.mk
index 18b71446b..c86f3addd 100644
--- a/lib/lint-man.mk
+++ b/lib/lint-man.mk
@@ -66,9 +66,10 @@ MANDOC              := mandoc
 
 _LINT_man_groff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.groff.touch,$(LINTMAN))
 _LINT_man_mandoc:=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.mandoc.touch,$(LINTMAN))
+_LINT_man_tbl   :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.tbl.touch,$(LINTMAN))
 
 
-linters_man := groff mandoc
+linters_man := groff mandoc tbl
 lint_man    := $(foreach x,$(linters_man),lint-man-$(x))
 
 
@@ -87,6 +88,25 @@ $(_LINT_man_mandoc): $(_LINTDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% | $$(@D)/.
 	$(MANDOC) $(MANDOCFLAGS) $<
 	touch $@
 
+$(_LINT_man_tbl): $(_LINTDIR)/%.lint-man.tbl.touch: $(MANDIR)/% | $$(@D)/.
+	$(info LINT (tbl)	$@)
+	if $(GREP) '^\.TS$$' <$< >/dev/null && ! $(HEAD) -n1 <$< | $(GREP) '\\" t$$' >/dev/null; then \
+		2>&1 $(ECHO) "$<: 1: missing '\\\" t' comment:"; \
+		2>&1 $(HEAD) -n1 <$<; \
+		exit 1; \
+	fi;
+	if $(HEAD) -n1 <$< | $(GREP) '\\" t$$' >/dev/null && ! $(GREP) '^\.TS$$' <$< >/dev/null; then \
+		2>&1 $(ECHO) "$<: 1: spurious '\\\" t' comment:"; \
+		2>&1 $(HEAD) -n1 <$<; \
+		exit 1; \
+	fi;
+	if $(TAIL) -n+2 <$< | $(GREP) '\\" t$$' >/dev/null ; then \
+		2>&1 $(ECHO) "$<: spurious '\\\" t' not in first line:"; \
+		2>&1 $(GREP) -n '\\" t$$' $< /dev/null; \
+		exit 1; \
+	fi;
+	touch $@
+
 
 .PHONY: $(lint_man)
 $(lint_man): lint-man-%: $$(_LINT_man_%)
-- 
2.38.1