Skip to contentSkip to conversation

Makefile, etc/groff/tmac/deadly.tmac: Add lint and lint-groff targets

PATCH In review Alejandro Colomar 2 participants 3 messages Mar 18, 2022 – Mar 20, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Makefile, etc/groff/tmac/deadly.tmac: Add lint and lint-groff targets

'lint' is a metatarget that triggers all lint-* targets (currently that is just 'lint-groff').
'lint-groff' is a target that runs groff -rCHECKSTYLE to check manual pages' groff(7) correctness.

etc/groff/tmac/deadly.tmac is a file written by Branden, to make make groff(1) abort when it finds a style problem, which then causes make(1) to also abort.

CC "G. Branden Robinson" <[email protected]>

---

Hi Branden and Michael!

I'm delighted to add to the man-pages a make(1) target to run Branden's brand new (pun not intended :)) groff(1) linter.

Please have a look at it, and feel free to comment. As I expected, one of the first pages linted had problems (and I am surprised for good that it didn't abort right in the first page):

INSTALL tmp/lint/
INSTALL tmp/lint/man0/
LINT (groff) tmp/lint/man0/sysexits.h.0.lint.groff.touch
INSTALL tmp/lint/man1/
LINT (groff) tmp/lint/man1/getent.1.lint.groff.touch
LINT (groff) tmp/lint/man1/iconv.1.lint.groff.touch
LINT (groff) tmp/lint/man1/intro.1.lint.groff.touch
an.tmac:man1/intro.1:72: style: blank line in input
found style problems; aborting
make: *** [Makefile:244: tmp/lint/man1/intro.1.lint.groff.touch] Error 1

I may start cleaning all of those one day. Now that we have some tool that finds those for us, that day may be sooner than later.

Branden, I'm curious to learn how/if you're using it in your own Makefile in groff(1).

BTW, don't feel pressured by my premature usage of your unreleased feature to consider not changing it too much to avoid breaking this build system. I assume that it may change it the future when you release and will adapt if necessary.

Cheers,

Alex

 Makefile                   | 54 +++++++++++++++++++++++++++++++++-----
 etc/groff/tmac/deadly.tmac |  7 +++++
 2 files changed, 55 insertions(+), 6 deletions(-)
 create mode 100644 etc/groff/tmac/deadly.tmac
Makefile +48 -6
index f68066bec..7316b4582 100644
@@ -29,15 +29,19 @@ MAKEFLAGS += --no-print-directory
 MAKEFLAGS += --warn-undefined-variables
 
 
+srcdir := .
 builddir := tmp
+LINTDIR := $(builddir)/lint
 htmlbuilddir := $(builddir)/html
 HTOPTS :=
 
 DESTDIR :=
 prefix := /usr/local
+SYSCONFDIR := $(srcdir)/etc
+TMACDIR := $(SYSCONFDIR)/groff/tmac
 datarootdir := $(prefix)/share
 docdir := $(datarootdir)/doc
-MANDIR := $(CURDIR)
+MANDIR := $(srcdir)
 mandir := $(datarootdir)/man
 MAN0DIR := $(MANDIR)/man0
 MAN1DIR := $(MANDIR)/man1
@@ -71,12 +75,23 @@ htmldir := $(docdir)
 htmldir_ := $(htmldir)/man
 htmlext := .html
 
-INSTALL := install
+TMACFILES            := $(sort $(shell find $(TMACDIR) -not -type d))
+TMACNAMES            := $(basename $(notdir $(TMACFILES)))
+GROFF_CHECKSTYLE_LVL := 3
+DEFAULT_GROFFFLAGS   := -man
+DEFAULT_GROFFFLAGS   += -M $(TMACDIR)
+DEFAULT_GROFFFLAGS   += $(foreach x,$(TMACNAMES),-m $(x))
+DEFAULT_GROFFFLAGS   += -rCHECKSTYLE=$(GROFF_CHECKSTYLE_LVL)
+EXTRA_GROFFFLAGS     :=
+GROFFFLAGS           := $(DEFAULT_GROFFFLAGS) $(EXTRA_GROFFFLAGS)
+
+INSTALL      := install
 INSTALL_DATA := $(INSTALL) -m 644
-INSTALL_DIR := $(INSTALL) -m 755 -d
-RM := rm
-RMDIR := rmdir --ignore-fail-on-non-empty
-MAN2HTML := man2html
+INSTALL_DIR  := $(INSTALL) -m 755 -d
+RM           := rm
+RMDIR        := rmdir --ignore-fail-on-non-empty
+GROFF        := groff
+MAN2HTML     := man2html
 
 MAN_SECTIONS := 0 1 2 3 4 5 6 7 8
 
@@ -132,9 +147,11 @@ _man5pages := $(filter %$(man5ext),$(_manpages))
 _man6pages := $(filter %$(man6ext),$(_manpages))
 _man7pages := $(filter %$(man7ext),$(_manpages))
 _man8pages := $(filter %$(man8ext),$(_manpages))
+LINT_groff := $(patsubst $(MANDIR)/%,$(LINTDIR)/%.lint.groff.touch,$(MANPAGES))
 
 MANDIRS   := $(sort $(shell find $(MANDIR)/man? -type d))
 HTMLDIRS  := $(patsubst $(MANDIR)/%,$(htmlbuilddir)/%/.,$(MANDIRS))
+LINTDIRS  := $(patsubst $(MANDIR)/%,$(LINTDIR)/%/.,$(MANDIRS))
 _htmldirs := $(patsubst $(htmlbuilddir)/%,$(DESTDIR)$(htmldir_)/%,$(HTMLDIRS))
 _mandirs  := $(patsubst $(MANDIR)/%,$(DESTDIR)$(mandir)/%/.,$(MANDIRS))
 _man0dir  := $(filter %man0/.,$(_mandirs))
@@ -216,6 +233,31 @@ uninstall-man: $(_mandir_rmdir) $(uninstall_manX)
 	@:
 
 
+########################################################################
+# lint
+
+linters := groff
+lint    := $(foreach x,$(linters),lint-$(x))
+
+$(LINT_groff): $(LINTDIR)/%.lint.groff.touch: $(MANDIR)/% | $$(@D)/.
+	$(info LINT (groff)	$@)
+	$(GROFF) $(GROFFFLAGS) -z $<
+	touch $@
+
+$(LINTDIRS): %/.: | $$(dir %). $(LINTDIR)/.
+
+.PHONY: lint-groff
+lint-groff: $(LINT_groff) | lintdirs
+	@:
+
+lintdirs: $(LINTDIRS)
+	@:
+
+.PHONY: lint
+lint: $(lint)
+	@:
+
+
 ########################################################################
 # html
 
etc/groff/tmac/deadly.tmac new file +7 -0
new file mode 100644
index 000000000..b87cb6a3d
@@ -0,0 +1,7 @@
+.am an-style-warn
+.	ds LANDMINE\"
+..
+.de end-of-input-macro
+.	if d LANDMINE .ab found style problems; aborting
+..
+.em end-of-input-macro
Signature · 1 line
2.35.1
#1 lore raw

Hi, Alex!

Quoted 3 lines · Alejandro Colomar

etc/groff/tmac/deadly.tmac is a file written by Branden, to make make groff(1) abort when it finds a style problem, which then causes make(1) to also abort.

Oh, I'm glad to hear this worked out. I had on my to-do list a reply to you at one point when it wasn't working for some reason.

Quoted 2 lines

Branden, I'm curious to learn how/if you're using it in your own Makefile in groff(1).

Nothing sophisticated. :)

I use it only in doc/doc.am, in the targets that generate compiled text and PDF versions of all of the groff man pages[1]. These will be new documents shipping in groff 1.23.

I set the register CHECKSTYLE to "3" on the command line and format the pages with "groff -mandoc". Any warnings come out on standard error.

Quoted 4 lines

BTW, don't feel pressured by my premature usage of your unreleased feature to consider not changing it too much to avoid breaking this build system. I assume that it may change it the future when you release and will adapt if necessary.

I appreciate that. I have no disruptive plans--indeed, no plans at all for further development of the feature. I have thought of nothing else do that is both feasible and helpful in fixing problems with groff's own pages. (I acknowledge your talent at asking for things that are NP-hard. ;-)

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am#n232

#2 lore raw
Quoted 10 lines · G. Branden Robinson

Hi, Alex!

Quoted 3 lines · Alejandro Colomar

etc/groff/tmac/deadly.tmac is a file written by Branden, to make make groff(1) abort when it finds a style problem, which then causes make(1) to also abort.

Oh, I'm glad to hear this worked out. I had on my to-do list a reply to you at one point when it wasn't working for some reason.

Quoted 8 lines
Quoted 2 lines

Branden, I'm curious to learn how/if you're using it in your own Makefile in groff(1).

Nothing sophisticated. :)

I use it only in doc/doc.am, in the targets that generate compiled text and PDF versions of all of the groff man pages[1]. These will be new documents shipping in groff 1.23.

Oh, now I remember... I'll soon attempt to satisfy your desire of having PDF Linux man-pages. That, and linting C programs within man pages will be my next 2 things to do. And I also want to add a 'dist'[1] make(1) target (and also a 'dist-deb' one, for which I'll require your old Debian skills :p).

Expect a lot of additions to the Makefile.

Regarding PDF pages, can you please share some advice?
Can I build it incrementally as for example a .ar file made out of .o files, where you can build .o files as always with make(1), and then you just replace the necessary .o files in the archive? Is there something similar in the PDF world? Please tell me everything you can think of, since it will be the first time I build a multi-page PDF.

[1]:
<https://www.gnu.org/software/make/manual/html_node/Standard-Targets.html>

Quoted 4 lines

I set the register CHECKSTYLE to "3" on the command line and format the pages with "groff -mandoc". Any warnings come out on standard error.

I've recently seen some email in the groff@ list using -rCHECKSTYLE=5. Is that a thing? Should I use -rCHECKSTYLE=666 as a "give me everything" mode?

Quoted 11 lines
Quoted 5 lines

BTW, don't feel pressured by my premature usage of your unreleased feature to consider not changing it too much to avoid breaking this build system. I assume that it may change it the future when you release and will adapt if necessary.

I appreciate that. I have no disruptive plans--indeed, no plans at all for further development of the feature. I have thought of nothing else do that is both feasible and helpful in fixing problems with groff's own pages. (I acknowledge your talent at asking for things that are NP-hard. ;-)

;-)

Cheers,

Alex

Quoted 5 lines

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am#n232

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/