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

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

[Alejandro Colomar]

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: "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?

v2:

-  Improve readability by making lines shorter and with fewer special
   characters. [Mike]

-  Remove ';' at the end of shell commands in Makefile. [Mike]

Patch 2/2:  Since the second patch is huge, it's not suitable for the
            mailing list.  It's posted as a signed tag in my personal
            repository.  Please check there and also sign:

<http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/>
<git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git>

            The signed tag name is: tblv2

Cheers,

Alex

 INSTALL         |  2 ++
 Makefile        |  1 +
 lib/cmd.mk      |  2 ++
 lib/lint-man.mk | 25 ++++++++++++++++++++++++-
 4 files changed, 29 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..4c8d42818 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,28 @@ $(_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) -q '^\.TS$$' $< && ! $(HEAD) -n1 $< | $(GREP) -q '\\" t$$'; \
+	then \
+		2>&1 $(ECHO) "$<:1: missing '\\\" t' comment:"; \
+		2>&1 $(HEAD) -n1 <$<; \
+		exit 1; \
+	fi
+	if $(HEAD) -n1 $< | $(GREP) -q '\\" t$$' && ! $(GREP) -q '^\.TS$$' $<; \
+	then \
+		2>&1 $(ECHO) "$<:1: spurious '\\\" t' comment:"; \
+		2>&1 $(HEAD) -n1 <$<; \
+		exit 1; \
+	fi
+	if $(TAIL) -n+2 <$< | $(GREP) -q '\\" t$$'; \
+	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