Subject: [bug#76435] [PATCH] Shepherd: build: Improve man-page synopsis.

From: Simon Josefsson <[email-masked]>
Date: Thu, 20 Feb 2025 08:48:19 +0100

Hi,

Shepherd's shepherd.1 and herd.1 man pages does not include any
explanation of what the tools do.  This makes Debian's QA tools
complain.  The attached patch fixes this.

I changed the catch-all %.1 rule into herd.1 because it was the only
match right now.  I think it is better if rules are added per man page
going forward to make sure that "--name" is passed properly.

An alternative solution would be to use a help2man --include parameter
and a separate herd.h2m and shepherd.h2m file that include the relevant
text, but it felt more complex than what was needed to resolve the
original problem.

/Simon
From 79e829e239f8a00cdbc32db43392385b09e43461 Mon Sep 17 00:00:00 2001
From: Simon Josefsson <[email-masked]>
Date: Thu, 20 Feb 2025 08:41:57 +0100
Subject: [PATCH] build: Improve man-page NAME whatis string.

* Makefile.am (shepherd.1): Add --name.
(%.1, herd.1): Rename to add --name.
---
 Makefile.am | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 79de974..afad8ba 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -132,10 +132,12 @@ HELP2MANFLAGS = --source=GNU --info-page=$(PACKAGE_TARNAME)
 gen_man = $(AM_V_HELP2MAN)LANGUAGE= $(HELP2MAN) $(HELP2MANFLAGS)
 
 doc/shepherd.1: modules/shepherd.scm configure.ac
-	$(gen_man) --output="$@" "$(top_builddir)/`basename "$@" .1`"
+	$(gen_man) --name="Service manager for the GNU system" \
+	--output="$@" "$(top_builddir)/`basename "$@" .1`"
 
-doc/%.1: modules/shepherd/scripts/%.scm configure.ac
-	$(gen_man) --output="$@" "$(top_builddir)/`basename "$@" .1`"
+doc/herd.1: modules/shepherd/scripts/herd.scm configure.ac
+	$(gen_man) --name="Control the shepherd(1) service manager" \
+	--output="$@" "$(top_builddir)/`basename "$@" .1`"
 
 doc/%.8: modules/shepherd/scripts/%.scm configure.ac
 	$(gen_man) --section=8 --output="$@"	\
-- 
2.48.1