From 6915fc287f2904a73a25e7b155653417e03a9fcf Mon Sep 17 00:00:00 2001
From: Jim Klimov <jimklimov+nut@gmail.com>
Date: Sun, 22 Dec 2024 08:14:16 +0100
Subject: [PATCH] scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in: introduce
 *_setDocLink() to refer to specific driver man pages, provide systemd
 implementation [#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
---
 .../upsdrvsvcctl/nut-driver-enumerator.sh.in  | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in b/scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in
index aee3d0b454..68b52a1fa4 100644
--- a/scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in
+++ b/scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in
@@ -172,6 +172,11 @@ if [ -z "${TIMEOUT_CMD+x}" ]; then
     fi
 fi
 
+# Should be populated by configure script during NUT build:
+NUT_WEBSITE_BASE='@NUT_WEBSITE_BASE@'
+# Fallback, no trailing slash!
+[ -n "${NUT_WEBSITE_BASE-}" ] || NUT_WEBSITE_BASE='https://www.networkupstools.org'
+
 # Cache needed bits of ups.conf to speed up later parsing. Note that these
 # data are needed for most operations, and populated by upslist_readFile()
 UPSCONF_DATA=""
@@ -195,6 +200,7 @@ hook_validInstanceSuffixName=""
 hook_getSavedDeviceName=""
 hook_findSavedDeviceName=""
 hook_setSavedDeviceName=""
+hook_setDocLink=""
 hook_getSavedMD5=""
 hook_setSavedMD5=""
 hook_restart_upsd=""
@@ -213,6 +219,7 @@ case "${SERVICE_FRAMEWORK-}" in
         hook_getSavedDeviceName="smf_getSavedDeviceName"
         hook_findSavedDeviceName="smf_findSavedDeviceName"
         hook_setSavedDeviceName="smf_setSavedDeviceName"
+        hook_setDocLink="smf_setDocLink"
         hook_getSavedMD5="smf_getSavedMD5"
         hook_setSavedMD5="smf_setSavedMD5"
         hook_restart_upsd="smf_restart_upsd"
@@ -230,6 +237,7 @@ case "${SERVICE_FRAMEWORK-}" in
         hook_getSavedDeviceName="systemd_getSavedDeviceName"
         hook_findSavedDeviceName="systemd_findSavedDeviceName"
         hook_setSavedDeviceName="systemd_setSavedDeviceName"
+        hook_setDocLink="systemd_setDocLink"
         hook_getSavedMD5="systemd_getSavedMD5"
         hook_setSavedMD5="systemd_setSavedMD5"
         hook_restart_upsd="systemd_restart_upsd"
@@ -247,6 +255,7 @@ case "${SERVICE_FRAMEWORK-}" in
         hook_getSavedDeviceName="selftest_NOOP"
         hook_findSavedDeviceName="selftest_NOOP"
         hook_setSavedDeviceName="selftest_NOOP"
+        hook_setDocLink="selftest_NOOP"
         hook_getSavedMD5="selftest_NOOP"
         hook_setSavedMD5="selftest_NOOP"
         hook_restart_upsd="selftest_NOOP"
@@ -739,6 +748,7 @@ smf_registerInstance() {
     smf_setSavedMD5 "$SVCINST" "`upsconf_getSection_MD5 "$DEVICE"`"
     # Save original device (config section) name to speed up some searches
     smf_setSavedDeviceName "$SVCINST" "$DEVICE"
+    smf_setDocLink "$SVCINST" "$DEVICE"
 
     /usr/sbin/svcadm refresh "${TARGET_FMRI}" || return
     if [ "$AUTO_START" = yes ] ; then
@@ -853,6 +863,16 @@ smf_setSavedDeviceName() {
     [ -n "$1" ] || return # No-op for global section
     smf_setSavedUniq "nut-driver:$1" "nut-driver-enumerator-generated-devicename" "DEVICE" astring "$2"
 }
+smf_setDocLink() {
+    # Save device (config section) name $2 into service instance $1
+    [ -n "$1" ] || return # No-op for global section
+    __TARGET_FMRI="$1"
+    __DRV=`"upsconf_getDriver "$2"`"
+#Documentation=man:${__DRV}(8)
+#Documentation=${NUT_WEBSITE_BASE}/docs/man/${__DRV}.html
+    unset __DRV
+    [ $? = 0 ] && echo "OK" || { echo "FAILED to stash the device doc links">&2 ; return 1 ; }
+}
 smf_restart_upsd() {
     echo "Reloading or restarting NUT data server to make sure it knows new configuration..."
     /usr/sbin/svcadm enable "nut-server" 2>/dev/null
@@ -924,6 +944,7 @@ EOF
 
     systemd_setSavedMD5 "$SVCINST" "`upsconf_getSection_MD5 "$DEVICE"`"
     systemd_setSavedDeviceName "$SVCINST" "$DEVICE"
+    systemd_setDocLink "$SVCINST" "$DEVICE"
 
     if [ "$AUTO_START" = yes ] ; then
         systemd_refreshSupervizor || echo "WARNING: Somehow managed to fail systemd_refreshSupervizor()" >&2
@@ -994,6 +1015,20 @@ Environment='DEVICE="$2"'
 EOF
     [ $? = 0 ] && echo "OK" || { echo "FAILED to stash the device name">&2 ; return 1 ; }
 }
+systemd_setDocLink() {
+    # Save device (config section) name $2 into service instance $1
+    [ -n "$1" ] || return # No-op for global section
+    PROPFILE="${SYSTEMD_CONFPATH}/nut-driver@$1.service.d/nut-driver-enumerator-generated-doclink.conf"
+    mkdir -p "${SYSTEMD_CONFPATH}/nut-driver@$1.service.d" && \
+    __DRV=`"upsconf_getDriver "$2"`"
+    cat > "${PROPFILE}" << EOF
+[Unit]
+Documentation=man:${__DRV}(8)
+Documentation=${NUT_WEBSITE_BASE}/docs/man/${__DRV}.html
+EOF
+    unset __DRV
+    [ $? = 0 ] && echo "OK" || { echo "FAILED to stash the device name">&2 ; return 1 ; }
+}
 systemd_setSavedMD5() {
     # Save checksum value $2 into service instance $1
     PROP="SECTION_CHECKSUM"