Subject: bug#77860: closed (Re: [bug#77860] [PATCH] Shepherd: build: Improve man-page NAME whatis string for *.8., [PATCH] build: Improve man-page NAME whatis string for *.8.)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 12 May 2025 08:55:04 +0000

Your bug report

#77860: [PATCH] Shepherd: build: Improve man-page NAME whatis string for *.8.

which was filed against the guix-patches package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
77860: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=77860
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: [bug#77860] [PATCH] Shepherd: build: Improve man-page NAME whatis string for *.8., [PATCH] build: Improve man-page NAME whatis string for *.8.
From: Ludovic Courtès <[email-masked]>
To: Simon Josefsson <[email-masked]>
Cc: [email-masked]
Date: Mon, 12 May 2025 10:36:24 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi Simon,

Simon Josefsson <[email-masked]> writes:

> The attached patch solves the same issue but for halt.8 and reboot.8.
>
> This uses help2man's --include-opt instead which I think is a better
> mechanism (and allows the relevant SEE ALSO).
>
> What do you think?

I don’t know, no strong preference here, but consistency may be a good
thing.

> From d97e2485ca700162474d40ffde0b53a06e358ee6 Mon Sep 17 00:00:00 2001
> From: Simon Josefsson <[email-masked]>
> Date: Thu, 17 Apr 2025 11:13:14 +0200
> Subject: [PATCH] build: Improve man-page NAME whatis string for *.8.
>
> * Makefile.am (%.8): Pass --include-opt.
> doc/halt.8.h2m: Add.
> doc/reboot.8.h2m: Add.
> Makefile.am (EXTRA_DIST): Add doc/*.h2m's.

Applied, thanks!

Ludo’.

Subject: [PATCH] Shepherd: build: Improve man-page NAME whatis string for *.8.
From: Simon Josefsson <[email-masked]>
To: [email-masked]
Date: Thu, 17 Apr 2025 11:42:45 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi,

Thanks for 1.0.4!  Frequent releases helps to iterate on small
improvements that I'm reminded of when a new release happens.

The Debian packages now puts halt and reboot below
/usr/libexec/shepherd/ like this:

jas@kaka:~/src/shepherd$ ls -la /usr/libexec/shepherd/sbin/
totalt 16
drwxr-xr-x 2 root root 4096 17 apr 10.54 .
drwxr-xr-x 3 root root 4096 19 mar 13.43 ..
-rwxr-xr-x 1 root root  288 17 apr 09.24 halt
-rwxr-xr-x 1 root root  290 17 apr 09.24 reboot
lrwxrwxrwx 1 root root    4 17 apr 09.24 shutdown -> halt
jas@kaka:~/src/shepherd$ 

This allows someone to use `PATH=/usr/libexec/shepherd/sbin:$PATH` to
use Shepherd's halt and reboot commands.  It is unclear to me why anyone
would want that, but it seems conceviable, and I recall hearing from
people who managed to use Shepherd as pid 1 on a Debian system.

Man pages for these commands are installed as shepherd-halt.8 and
shepherd-reboot.8 to not conflict with Debian's halt(8) and reboot(8).
Maybe there is a better way to deal with that, but it seems better to
ship them under another name than to not ship them at all, pending some
better approach.

The QA tooling complained about these manpages:

W: shepherd: useless-whatis-entry [usr/share/man/man8/shepherd-halt.8.gz]
N: 
N:   The whatis entry for this manual page (the brief description found in the
N:   NAME section) is of the form:
N:   
N:    program - manual page for program
N:   
N:   This conveys no information about what the program is for and is
N:   repetitive. The short description should contain brief information about
N:   what the program is for to aid in searching with apropos and similar
N:   programs.
N:   
N:   If this manual page was generated by help2man, use the -n option to
N:   provide a more meaningful description.

That is the same as for shepherd.1 and herd.1 that you patched earlier:

https://issues.guix.gnu.org/76435

The attached patch solves the same issue but for halt.8 and reboot.8.

This uses help2man's --include-opt instead which I think is a better
mechanism (and allows the relevant SEE ALSO).

What do you think?

If this approach seems right, I may propose a patch to create
doc/shepherd.1.h2m and doc/herd.1.h2m too, cleaning up Makefile.am
slightly.

/Simon
From d97e2485ca700162474d40ffde0b53a06e358ee6 Mon Sep 17 00:00:00 2001
From: Simon Josefsson <[email-masked]>
Date: Thu, 17 Apr 2025 11:13:14 +0200
Subject: [PATCH] build: Improve man-page NAME whatis string for *.8.

* Makefile.am (%.8): Pass --include-opt.
doc/halt.8.h2m: Add.
doc/reboot.8.h2m: Add.
Makefile.am (EXTRA_DIST): Add doc/*.h2m's.
---
 Makefile.am      | 3 +++
 doc/halt.8.h2m   | 4 ++++
 doc/reboot.8.h2m | 4 ++++
 3 files changed, 11 insertions(+)
 create mode 100644 doc/halt.8.h2m
 create mode 100644 doc/reboot.8.h2m

diff --git a/Makefile.am b/Makefile.am
index a61b403..bdb1909 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -143,8 +143,11 @@ doc/herd.1: modules/shepherd/scripts/herd.scm configure.ac
 
 doc/%.8: modules/shepherd/scripts/%.scm configure.ac
 	$(gen_man) --section=8 --output="$@"	\
+	--include=$(srcdir)/$@.h2m			\
 	  "$(top_builddir)/`basename "$@" .8`"
 
+EXTRA_DIST += doc/halt.8.h2m doc/reboot.8.h2m
+
 dist_man1_MANS = doc/shepherd.1 doc/herd.1
 dist_man8_MANS = doc/halt.8 doc/reboot.8
 
diff --git a/doc/halt.8.h2m b/doc/halt.8.h2m
new file mode 100644
index 0000000..b6162d8
--- /dev/null
+++ b/doc/halt.8.h2m
@@ -0,0 +1,4 @@
+[NAME]
+halt \- tell Shepherd to stop services and turn off system
+[SEE ALSO]
+shepherd(1), herd(1), reboot(8)
diff --git a/doc/reboot.8.h2m b/doc/reboot.8.h2m
new file mode 100644
index 0000000..4480ba7
--- /dev/null
+++ b/doc/reboot.8.h2m
@@ -0,0 +1,4 @@
+[NAME]
+reboot \- tell Shepherd to stop services and reboot system
+[SEE ALSO]
+shepherd(1), herd(1), halt(8)
-- 
2.49.0