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

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

[-- Attachment #1.1: Type: text/plain, Size: 6057 bytes --]

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@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>
> ---

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@kernel.org>
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@kernel.org>
     Signed-off-by: Alejandro Colomar <alx@kernel.org>


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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]