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

Alejandro Colomar <alx.manpages@xxxxxxxxx> · Wed, 9 Nov 2022 16:40:00 +0100

Hi Jakub!

On 11/9/22 16:18, Alejandro Colomar wrote:
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@xxxxxxxxx>, 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@xxxxxxxxx/T/#mcf36c8a387fd5ff4f800dc220e3dbdd229b556bd>
Cc: Mike Frysinger <vapier@xxxxxxxxxx>
Cc: Mike Frysinger <vapier@xxxxxxxxxxxx>
Cc: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
Cc: Michael Kerrisk <mtk.manpages@xxxxxxxxx>
Cc: Stefan Puiu <stefan.puiu@xxxxxxxxx>
Reported-by: Jakub Wilk <jwilk@xxxxxxxxx>
Co-developed-by: Jakub Wilk <jwilk@xxxxxxxxx>
Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
---

I also used your script to add the comment to the pages, and used this linter to 
make sure that it works fine, so I added the following commit:

commit 629a402fe4eee48f31c658b2a7ba6de28990e780 (HEAD -> tbl)
Author: Alejandro Colomar <alx@xxxxxxxxxx>
Date:   Wed Nov 9 16:36:36 2022 +0100

    Many pages: Add '\" t' comment where necessary

    Scripted change:

    $ grep -l -x '^[.]TS$' man*/* | sort -u | xargs sed -i -e "1i'\\\\\" t"

    Tested-by: Alejandro Colomar <alx@xxxxxxxxxx>
    Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>


The diff is huge, so I won't send it, but you can expect what it is by just 
running your own script :)

Would you mind also signing that patch?

Cheers,

Alex


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_%)

--
<http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature

Description: OpenPGP digital signature




