GNU bug report logs - #76435
[PATCH] Shepherd: build: Improve man-page synopsis.

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Simon Josefsson <simon <at> josefsson.org>
To: guix-patches <at> gnu.org
Subject: [PATCH] Shepherd: build: Improve man-page synopsis.
Date: Thu, 20 Feb 2025 08:48:19 +0100

[Message part 1 (text/plain, inline)]

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

[0001-build-Improve-man-page-NAME-whatis-string.patch (text/x-diff, inline)]

From 79e829e239f8a00cdbc32db43392385b09e43461 Mon Sep 17 00:00:00 2001
From: Simon Josefsson <simon <at> josefsson.org>
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

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.