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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 76435 in the body.
You can then email your comments to 76435 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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)]

Message #10 received at 76435-done <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Simon Josefsson <simon <at> josefsson.org>
Cc: 76435-done <at> debbugs.gnu.org
Subject: Re: [bug#76435] [PATCH] Shepherd: build: Improve man-page synopsis.
Date: Thu, 20 Feb 2025 23:55:54 +0100

Simon Josefsson <simon <at> josefsson.org> skribis:

> 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.

Applied, thanks.

And thanks for the Debian packaging work!

Previous Next

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