Moar granular linting of manual pages

PATCH New Alejandro Colomar 1 participant 7 messages Mar 9, 2023

Subsystems (3)

Kbuild Library code Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Alejandro Colomar

author

2023-03-09 17:58 UTC #0 lore raw

cover Moar granular linting of manual pages

Hi,

I'm working on getting the linters run by the Debian packaging through override_dh_atuo_test (and hopefully other distros will do something similar; and hopefully other projects will be interested, and will also add some linting to their projects' manual pages, so we have better manual pages overall, but I know I'm hoping too much with that).

One of the issues was that there are still many warnings in many pages for most linters, so I wanted to have a large subset that would have little to no warnings. The only one that has no warnings at all is 'lint-man-tbl', and then there's 'lint-man-mandoc' which only has warnings in two (external) pages.

To reduce that issue, and be able to pass more linters to the pages, I'm splitting the 'lint-man-groff' pipeline into its elements, so I can hopefully run most of them without warnings. After this patch, we will be able to run part of this pipeline in the packaging tests, since they have no warnings, so we have some more testing.

And as a very nice side effect, we will have a complete set of intermediate files produced by the pipeline, which allows one to inspect any step without any manual intervention: just running the 'lint-man-groff' target will produce the entire set of intermediate files used in the groff(1) pipeline (and also the output of col(1)).

This will help debug groff(1) when a problem arises.

Cheers,

Alex

Alejandro Colomar (6):
lint-man.mk: make-lint-tbl: ffix
Makefile, lint-man.mk: lint-man-groff-tbl: Split target from
lint-man-groff
Makefile, lint-man.mk: lint-man-groff-eqn: Split target from
lint-man-groff
Makefile, lint-man.mk: lint-man-groff-troff: Split target from
lint-man-groff
Makefile, lint-man.mk: lint-man-groff-grotty: Split target from
lint-man-groff
Makefile, lint-man.mk: lint-man-groff-col, lint-man-groff-grep: Split
targets from lint-man-groff

 Makefile        |  8 ++++++-
 lib/lint-man.mk | 63 ++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 61 insertions(+), 10 deletions(-)

Signature · 1 line

2.39.2

Alejandro Colomar

author

2023-03-09 17:58 UTC #1 lore raw

PATCH 1/6 lint-man.mk: make-lint-tbl: ffix

Print 'LINT (tbl comment)' to not confuse users to think that we run tbl(1) at all.

Signed-off-by Alejandro Colomar <[email protected]>

---
 lib/lint-man.mk | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

lib/lint-man.mk +1 -1

index e0f72d303..c4a4c57b0 100644
@@ -98,7 +98,7 @@ $(_LINT_man_mandoc): $(_LINTDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% | $$(@D)/.
 	touch $@
 
 $(_LINT_man_tbl): $(_LINTDIR)/%.lint-man.tbl.touch: $(MANDIR)/% | $$(@D)/.
-	$(info LINT (tbl)	$@)
+	$(info LINT (tbl comment)	$@)
 	if $(GREP) -q '^\.TS$$' $< && ! $(HEAD) -n1 $< | $(GREP) -q '\\" t$$'; \
 	then \
 		>&2 $(ECHO) "$<:1: missing '\\\" t' comment:"; \

Signature · 1 line

2.39.2

Alejandro Colomar

author

2023-03-09 17:58 UTC #2 lore raw

PATCH 2/6 Makefile, lint-man.mk: lint-man-groff-tbl: Split target from lint-man-groff

In reply to Alejandro Colomar

Allow running tbl(1) separately, which has several benefits:

- More granular testing.
- Allows inspecting the output of tbl(1), which can be useful for debugging the pages.

Signed-off-by Alejandro Colomar <[email protected]>

---
 Makefile        |  3 ++-
 lib/lint-man.mk | 15 ++++++++++++---
 2 files changed, 14 insertions(+), 4 deletions(-)

Makefile +2 -1

index 54b492d40..46e71faab 100644
@@ -70,9 +70,10 @@ help:
 	$(info	lint-c-cpplint		Lint C programs from EXAMPLES with cpplint(1))
 	$(info	lint-c-iwyu		Lint C programs from EXAMPLES with iwyu(1))
 	$(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	lint-man-groff		Lint man pages with groff(1))
+	$(info	lint-man-groff-tbl	Lint man pages with tbl(1))
 	$(info	)
 	$(info	[un]install		Alias for "[un]install-man")
 	$(info	[un]install-man		Wrapper for [un]install-man* targets)

lib/lint-man.mk +12 -3

index c4a4c57b0..8207860d8 100644
@@ -64,6 +64,8 @@ MANDOCFLAGS         := $(DEFAULT_MANDOCFLAGS) $(EXTRA_MANDOCFLAGS)
 MANDOC              := mandoc
 
 
+_LINT_man_groff_eqn   :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.eqn,$(LINTMAN))
+
 _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))

@@ -73,10 +75,13 @@ linters_man := groff mandoc tbl
 lint_man    := $(foreach x,$(linters_man),lint-man-$(x))
 
 
-$(_LINT_man_groff): $(_LINTDIR)/%.lint-man.groff.touch: $(MANDIR)/% | $$(@D)/.
+$(_LINT_man_groff_eqn): $(_LINTDIR)/%.eqn: $(MANDIR)/% | $$(@D)/.
+	$(info LINT (tbl)	$@)
+	$(TBL) $< >$@
+
+$(_LINT_man_groff): %.lint-man.groff.touch: %.eqn | $$(@D)/.
 	$(info LINT (groff)	$@)
-	$(TBL) $< \
-	| $(EQN) $(EQNFLAGS) \
+	$(EQN) $(EQNFLAGS) <$< \
 	| $(TROFF) $(TROFFFLAGS) \
 	| $(GROTTY) $(GROTTYFLAGS) \
 	| $(COL) $(COLFLAGS) \

@@ -120,6 +125,10 @@ $(_LINT_man_tbl): $(_LINTDIR)/%.lint-man.tbl.touch: $(MANDIR)/% | $$(@D)/.
 	touch $@
 
 
+.PHONY: lint-man-groff-tbl
+lint-man-groff-tbl: $(_LINT_man_groff_eqn)
+	@:
+
 .PHONY: $(lint_man)
 $(lint_man): lint-man-%: $$(_LINT_man_%)
 	@:

Signature · 1 line

2.39.2

Alejandro Colomar

author

2023-03-09 17:58 UTC #3 lore raw

PATCH 3/6 Makefile, lint-man.mk: lint-man-groff-eqn: Split target from lint-man-groff

In reply to Alejandro Colomar

Allow running eqn(1) separately, which allows more granular testing, and also inspecting the output of eqn(1), which can be useful for debugging the pages.

Signed-off-by Alejandro Colomar <[email protected]>

---
 Makefile        |  1 +
 lib/lint-man.mk | 14 +++++++++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

Makefile +1 -0

index 46e71faab..b5171e377 100644
@@ -74,6 +74,7 @@ help:
 	$(info	lint-man-tbl		Lint man pages about '\" t' comment for tbl(1))
 	$(info	lint-man-groff		Lint man pages with groff(1))
 	$(info	lint-man-groff-tbl	Lint man pages with tbl(1))
+	$(info	lint-man-groff-eqn	Lint man pages with eqn(1))
 	$(info	)
 	$(info	[un]install		Alias for "[un]install-man")
 	$(info	[un]install-man		Wrapper for [un]install-man* targets)

lib/lint-man.mk +11 -3

index 8207860d8..928bb8c68 100644
@@ -65,6 +65,7 @@ MANDOC              := mandoc
 
 
 _LINT_man_groff_eqn   :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.eqn,$(LINTMAN))
+_LINT_man_groff_troff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.troff,$(LINTMAN))
 
 _LINT_man_groff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.groff.touch,$(LINTMAN))
 _LINT_man_mandoc:=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.mandoc.touch,$(LINTMAN))

@@ -79,10 +80,13 @@ $(_LINT_man_groff_eqn): $(_LINTDIR)/%.eqn: $(MANDIR)/% | $$(@D)/.
 	$(info LINT (tbl)	$@)
 	$(TBL) $< >$@
 
-$(_LINT_man_groff): %.lint-man.groff.touch: %.eqn | $$(@D)/.
+$(_LINT_man_groff_troff): %.troff: %.eqn | $$(@D)/.
+	$(info LINT (eqn)	$@)
+	$(EQN) $(EQNFLAGS) <$< >$@
+
+$(_LINT_man_groff): %.lint-man.groff.touch: %.troff | $$(@D)/.
 	$(info LINT (groff)	$@)
-	$(EQN) $(EQNFLAGS) <$< \
-	| $(TROFF) $(TROFFFLAGS) \
+	$(TROFF) $(TROFFFLAGS) <$< \
 	| $(GROTTY) $(GROTTYFLAGS) \
 	| $(COL) $(COLFLAGS) \
 	| (! $(GREP) -n '.\{$(MANWIDTH)\}.' | $(SED) 's,^,$<:,' >&2)

@@ -129,6 +133,10 @@ $(_LINT_man_tbl): $(_LINTDIR)/%.lint-man.tbl.touch: $(MANDIR)/% | $$(@D)/.
 lint-man-groff-tbl: $(_LINT_man_groff_eqn)
 	@:
 
+.PHONY: lint-man-groff-eqn
+lint-man-groff-eqn: $(_LINT_man_groff_troff)
+	@:
+
 .PHONY: $(lint_man)
 $(lint_man): lint-man-%: $$(_LINT_man_%)
 	@:

Signature · 1 line

2.39.2

Alejandro Colomar

author

2023-03-09 17:58 UTC #4 lore raw

PATCH 4/6 Makefile, lint-man.mk: lint-man-groff-troff: Split target from lint-man-groff

In reply to Alejandro Colomar

Allow running troff(1) separately, which allows more granular testing, and also inspecting the output of troff(1), which can be useful for debugging the pages.

Signed-off-by Alejandro Colomar <[email protected]>

---
 Makefile        |  1 +
 lib/lint-man.mk | 18 +++++++++++++-----
 2 files changed, 14 insertions(+), 5 deletions(-)

Makefile +1 -0

index b5171e377..270ee00e3 100644
@@ -75,6 +75,7 @@ help:
 	$(info	lint-man-groff		Lint man pages with groff(1))
 	$(info	lint-man-groff-tbl	Lint man pages with tbl(1))
 	$(info	lint-man-groff-eqn	Lint man pages with eqn(1))
+	$(info	lint-man-groff-troff	Lint man pages with troff(1))
 	$(info	)
 	$(info	[un]install		Alias for "[un]install-man")
 	$(info	[un]install-man		Wrapper for [un]install-man* targets)

lib/lint-man.mk +13 -5

index 928bb8c68..bc3ce6a3d 100644
@@ -64,8 +64,9 @@ MANDOCFLAGS         := $(DEFAULT_MANDOCFLAGS) $(EXTRA_MANDOCFLAGS)
 MANDOC              := mandoc
 
 
-_LINT_man_groff_eqn   :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.eqn,$(LINTMAN))
-_LINT_man_groff_troff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.troff,$(LINTMAN))
+_LINT_man_groff_eqn    :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.eqn,$(LINTMAN))
+_LINT_man_groff_troff  :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.troff,$(LINTMAN))
+_LINT_man_groff_grotty :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.grotty,$(LINTMAN))
 
 _LINT_man_groff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.groff.touch,$(LINTMAN))
 _LINT_man_mandoc:=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.mandoc.touch,$(LINTMAN))

@@ -84,10 +85,13 @@ $(_LINT_man_groff_troff): %.troff: %.eqn | $$(@D)/.
 	$(info LINT (eqn)	$@)
 	$(EQN) $(EQNFLAGS) <$< >$@
 
-$(_LINT_man_groff): %.lint-man.groff.touch: %.troff | $$(@D)/.
+$(_LINT_man_groff_grotty): %.grotty: %.troff | $$(@D)/.
+	$(info LINT (troff)	$@)
+	$(TROFF) $(TROFFFLAGS) <$< >$@
+
+$(_LINT_man_groff): %.lint-man.groff.touch: %.grotty | $$(@D)/.
 	$(info LINT (groff)	$@)
-	$(TROFF) $(TROFFFLAGS) <$< \
-	| $(GROTTY) $(GROTTYFLAGS) \
+	$(GROTTY) $(GROTTYFLAGS) <$< \
 	| $(COL) $(COLFLAGS) \
 	| (! $(GREP) -n '.\{$(MANWIDTH)\}.' | $(SED) 's,^,$<:,' >&2)
 	touch $@

@@ -137,6 +141,10 @@ lint-man-groff-tbl: $(_LINT_man_groff_eqn)
 lint-man-groff-eqn: $(_LINT_man_groff_troff)
 	@:
 
+.PHONY: lint-man-groff-troff
+lint-man-groff-troff: $(_LINT_man_groff_grotty)
+	@:
+
 .PHONY: $(lint_man)
 $(lint_man): lint-man-%: $$(_LINT_man_%)
 	@:

Signature · 1 line

2.39.2

Alejandro Colomar

author

2023-03-09 17:58 UTC #5 lore raw

PATCH 5/6 Makefile, lint-man.mk: lint-man-groff-grotty: Split target from lint-man-groff

In reply to Alejandro Colomar

Allow running grotty(1) separately, which allows more granular testing, and also inspecting the output of grotty(1), which can be useful for debugging the pages.

Signed-off-by Alejandro Colomar <[email protected]>

---
 Makefile        |  1 +
 lib/lint-man.mk | 16 ++++++++++++----
 2 files changed, 13 insertions(+), 4 deletions(-)

Makefile +1 -0

index 270ee00e3..3788fb0f1 100644
@@ -76,6 +76,7 @@ help:
 	$(info	lint-man-groff-tbl	Lint man pages with tbl(1))
 	$(info	lint-man-groff-eqn	Lint man pages with eqn(1))
 	$(info	lint-man-groff-troff	Lint man pages with troff(1))
+	$(info	lint-man-groff-grotty	Lint man pages with grotty(1))
 	$(info	)
 	$(info	[un]install		Alias for "[un]install-man")
 	$(info	[un]install-man		Wrapper for [un]install-man* targets)

lib/lint-man.mk +12 -4

index bc3ce6a3d..a342eb44d 100644
@@ -67,6 +67,7 @@ MANDOC              := mandoc
 _LINT_man_groff_eqn    :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.eqn,$(LINTMAN))
 _LINT_man_groff_troff  :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.troff,$(LINTMAN))
 _LINT_man_groff_grotty :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.grotty,$(LINTMAN))
+_LINT_man_groff_col    :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.col,$(LINTMAN))
 
 _LINT_man_groff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.groff.touch,$(LINTMAN))
 _LINT_man_mandoc:=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.mandoc.touch,$(LINTMAN))

@@ -89,10 +90,13 @@ $(_LINT_man_groff_grotty): %.grotty: %.troff | $$(@D)/.
 	$(info LINT (troff)	$@)
 	$(TROFF) $(TROFFFLAGS) <$< >$@
 
-$(_LINT_man_groff): %.lint-man.groff.touch: %.grotty | $$(@D)/.
-	$(info LINT (groff)	$@)
-	$(GROTTY) $(GROTTYFLAGS) <$< \
-	| $(COL) $(COLFLAGS) \
+$(_LINT_man_groff_col): %.col: %.grotty | $$(@D)/.
+	$(info LINT (grotty)	$@)
+	$(GROTTY) $(GROTTYFLAGS) <$< >$@
+
+$(_LINT_man_groff): %.lint-man.groff.touch: %.col | $$(@D)/.
+	$(info LINT (col)	$@)
+	$(COL) $(COLFLAGS) <$< \
 	| (! $(GREP) -n '.\{$(MANWIDTH)\}.' | $(SED) 's,^,$<:,' >&2)
 	touch $@

@@ -145,6 +149,10 @@ lint-man-groff-eqn: $(_LINT_man_groff_troff)
 lint-man-groff-troff: $(_LINT_man_groff_grotty)
 	@:
 
+.PHONY: lint-man-groff-grotty
+lint-man-groff-grotty: $(_LINT_man_groff_col)
+	@:
+
 .PHONY: $(lint_man)
 $(lint_man): lint-man-%: $$(_LINT_man_%)
 	@:

Signature · 1 line

2.39.2

Alejandro Colomar

author

2023-03-09 17:58 UTC #6 lore raw

PATCH 6/6 Makefile, lint-man.mk: lint-man-groff-col, lint-man-groff-grep: Split targets from lint-man-groff

In reply to Alejandro Colomar

Allow running col(1) and grep(1) separately, which allows more granular testing, and also inspecting the output of col(1), which can be useful for debugging the pages.

Signed-off-by Alejandro Colomar <[email protected]>

---
 Makefile        |  4 +++-
 lib/lint-man.mk | 18 +++++++++++++++---
 2 files changed, 18 insertions(+), 4 deletions(-)

Makefile +3 -1

index 3788fb0f1..c370244d7 100644
@@ -72,11 +72,13 @@ help:
 	$(info	lint-man		Wrapper for lint-man-* targets)
 	$(info	lint-man-mandoc		Lint man pages with mandoc(1))
 	$(info	lint-man-tbl		Lint man pages about '\" t' comment for tbl(1))
-	$(info	lint-man-groff		Lint man pages with groff(1))
+	$(info	lint-man-groff		Alias for "lint-man-groff-grep")
 	$(info	lint-man-groff-tbl	Lint man pages with tbl(1))
 	$(info	lint-man-groff-eqn	Lint man pages with eqn(1))
 	$(info	lint-man-groff-troff	Lint man pages with troff(1))
 	$(info	lint-man-groff-grotty	Lint man pages with grotty(1))
+	$(info	lint-man-groff-col	Lint man pages with col(1))
+	$(info	lint-man-groff-grep	Lint man pages with grep(1))
 	$(info	)
 	$(info	[un]install		Alias for "[un]install-man")
 	$(info	[un]install-man		Wrapper for [un]install-man* targets)

lib/lint-man.mk +15 -3

index a342eb44d..e819d1a95 100644
@@ -68,6 +68,7 @@ _LINT_man_groff_eqn    :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.eqn,$(LINTMAN))
 _LINT_man_groff_troff  :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.troff,$(LINTMAN))
 _LINT_man_groff_grotty :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.grotty,$(LINTMAN))
 _LINT_man_groff_col    :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.col,$(LINTMAN))
+_LINT_man_groff_grep   :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.grep,$(LINTMAN))
 
 _LINT_man_groff :=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.groff.touch,$(LINTMAN))
 _LINT_man_mandoc:=$(patsubst $(MANDIR)/%,$(_LINTDIR)/%.lint-man.mandoc.touch,$(LINTMAN))

@@ -94,10 +95,13 @@ $(_LINT_man_groff_col): %.col: %.grotty | $$(@D)/.
 	$(info LINT (grotty)	$@)
 	$(GROTTY) $(GROTTYFLAGS) <$< >$@
 
-$(_LINT_man_groff): %.lint-man.groff.touch: %.col | $$(@D)/.
+$(_LINT_man_groff_grep): %.grep: %.col | $$(@D)/.
 	$(info LINT (col)	$@)
-	$(COL) $(COLFLAGS) <$< \
-	| (! $(GREP) -n '.\{$(MANWIDTH)\}.' | $(SED) 's,^,$<:,' >&2)
+	$(COL) $(COLFLAGS) <$< >$@
+
+$(_LINT_man_groff): %.lint-man.groff.touch: %.grep | $$(@D)/.
+	$(info LINT (grep)	$@)
+	! $(GREP) -n '.\{$(MANWIDTH)\}.' $< /dev/null >&2
 	touch $@
 
 $(_LINT_man_mandoc): $(_LINTDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% | $$(@D)/.

@@ -153,6 +157,14 @@ lint-man-groff-troff: $(_LINT_man_groff_grotty)
 lint-man-groff-grotty: $(_LINT_man_groff_col)
 	@:
 
+.PHONY: lint-man-groff-col
+lint-man-groff-col: $(_LINT_man_groff_grep)
+	@:
+
+.PHONY: lint-man-groff-grep
+lint-man-groff-grep: $(_LINT_man_groff)
+	@:
+
 .PHONY: $(lint_man)
 $(lint_man): lint-man-%: $$(_LINT_man_%)
 	@:

Signature · 1 line

2.39.2