From: Alejandro Colomar <alx@kernel.org>
Date: Tue, 19 Aug 2025 11:31:41 +0000 (+0200)
Subject: share/mk/: lint-man-poems: Diagnose (lack of) semantic newlines
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=bba4af63a0b987901ff42aa9f1afae0fa1bb23f3;p=thirdparty%2Fman-pages.git

share/mk/: lint-man-poems: Diagnose (lack of) semantic newlines

Write poems, not prose.

This only catches the most obvious issues, but at least that's
something.

We need pcre2grep(3) because it allows multiple patterns, whereas
grep(1) in -P mode only accepts one.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

diff --git a/share/mk/lint/man/_.mk b/share/mk/lint/man/_.mk
index 0bf60eaa6..ba25943d8 100644
--- a/share/mk/lint/man/_.mk
+++ b/share/mk/lint/man/_.mk
@@ -10,6 +10,7 @@ MAKEFILE_LINT_MAN_INCLUDED := 1
 lint-man: \
 	lint-man-blank \
 	lint-man-mandoc \
+	lint-man-poems \
 	lint-man-quote \
 	lint-man-so \
 	lint-man-tbl \
diff --git a/share/mk/lint/man/poems.mk b/share/mk/lint/man/poems.mk
new file mode 100644
index 000000000..239a973e0
--- /dev/null
+++ b/share/mk/lint/man/poems.mk
@@ -0,0 +1,46 @@
+# Copyright, the authors of the Linux man-pages project
+# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception
+
+
+ifndef MAKEFILE_LINT_MAN_POEMS_INCLUDED
+MAKEFILE_LINT_MAN_POEMS_INCLUDED := 1
+
+
+include $(MAKEFILEDIR)/build/man/nonso.mk
+include $(MAKEFILEDIR)/configure/build-depends/coreutils/cat.mk
+include $(MAKEFILEDIR)/configure/build-depends/coreutils/echo.mk
+include $(MAKEFILEDIR)/configure/build-depends/coreutils/touch.mk
+include $(MAKEFILEDIR)/configure/build-depends/pcre2-utils/pcre2grep.mk
+
+
+ext := .lint-man.poems.touch
+xfail := $(MAKEFILEDIR)/lint/man/poems.xfail
+regexf := $(MAKEFILEDIR)/lint/man/poems.pcre2grep
+
+tgts := $(patsubst %, %$(ext), $(_NONSO))
+ifeq ($(SKIP_XFAIL),yes)
+tgts := $(filter-out $(patsubst %, $(_MANDIR)/%$(ext), $(file < $(xfail))), $(tgts))
+endif
+
+
+$(tgts): %$(ext): % $(regexf) $(MK) | $$(@D)/
+	$(info	$(INFO_)PCRE2GREP	$@)
+	$(CAT) <$< \
+	| if $(PCRE2GREP) -f '$(filter %.pcre2grep, $^)' >/dev/null; then \
+		>&2 $(ECHO) "lint-man-poems: $<: Use semantic newlines (see man-pages(7)):"; \
+		>&2 $(PCRE2GREP) -n -f '$(filter %.pcre2grep, $^)' <$<; \
+		exit 1; \
+	fi;
+	$(TOUCH) $@
+
+
+.PHONY: lint-man-poems
+lint-man-poems: $(tgts);
+
+
+undefine ext
+undefine tgts
+undefine regexf
+
+
+endif  # include guard
diff --git a/share/mk/lint/man/poems.pcre2grep b/share/mk/lint/man/poems.pcre2grep
new file mode 100644
index 000000000..50dbd015d
--- /dev/null
+++ b/share/mk/lint/man/poems.pcre2grep
@@ -0,0 +1,2 @@
+^(?!.[A-Z])(?:(?!Subject: )(?!Author: )(?!for \().)*[^ ]\. [^ ]
+^(?![.[:space:]])(?:(?!\bfor \()[^\t:=0-9[])*; [^ ][^\t:=0-9[]*$
diff --git a/share/mk/lint/man/poems.xfail b/share/mk/lint/man/poems.xfail
new file mode 100644
index 000000000..7449bfd65
--- /dev/null
+++ b/share/mk/lint/man/poems.xfail
@@ -0,0 +1,5 @@
+man5/tzfile.5
+man7/bpf-helpers.7
+man8/tzselect.8
+man8/zdump.8
+man8/zic.8