From 1836c135bc1c8603edebe60a0b6c4d2f20870d95 Mon Sep 17 00:00:00 2001 From: Thomas Lamprecht Date: Mon, 21 Oct 2024 09:07:55 +0200 Subject: [PATCH] docs: prefix node.cfg man page with proxmox-backup As node.cfg is a rather general name that could clash with manual pages from other packages, or at least be a bit confusing if there's another tool providing a node.cfg. In the long term we should rename all existing manual pages from section 5 and 7, i.e. all those that are not directly named after an executable. As those normally talk about product-specific configs and topics where just the filename is not specific enough for a system wide manual page. Note that there was some off-list discussion with proposal of using "section suffixes" that man supports and can be used to differ between manual pages with the same name (and in the same section), for example `man 3pm Git`, but to me this seems a bit more obscure and potentially less discoverable, but can be a great way to provide an link alias for convenience. Signed-off-by: Thomas Lamprecht --- debian/proxmox-backup-server.install | 2 +- docs/Makefile | 5 ++++- docs/conf.py | 2 +- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/debian/proxmox-backup-server.install b/debian/proxmox-backup-server.install index 836023b3f..79757eadb 100644 --- a/debian/proxmox-backup-server.install +++ b/debian/proxmox-backup-server.install @@ -32,7 +32,7 @@ usr/share/man/man5/domains.cfg.5 usr/share/man/man5/media-pool.cfg.5 usr/share/man/man5/notifications-priv.cfg.5 usr/share/man/man5/notifications.cfg.5 -usr/share/man/man5/node.cfg.5 +usr/share/man/man5/proxmox-backup.node.cfg.5 usr/share/man/man5/remote.cfg.5 usr/share/man/man5/sync.cfg.5 usr/share/man/man5/tape-job.cfg.5 diff --git a/docs/Makefile b/docs/Makefile index ac612a3f9..d98302ffb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -35,12 +35,15 @@ MAN1_PAGES := \ proxmox-tape.1 \ pxar.1 \ +# FIXME: prefix all man pages that are not directly relating to an existing executable with +# `proxmox-backup.`, like the newer added proxmox-backup.node.cfg but add backwards compatible +# symlinks, e.g. with a "5pbs" man page "suffix section". MAN5_PAGES := \ acl.cfg.5 \ datastore.cfg.5 \ domains.cfg.5 \ media-pool.cfg.5 \ - node.cfg.5 \ + proxmox-backup.node.cfg.5 \ notifications-priv.cfg.5 \ notifications.cfg.5 \ remote.cfg.5 \ diff --git a/docs/conf.py b/docs/conf.py index 92ff83868..07712889f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -108,7 +108,7 @@ man_pages = [ ('config/datastore/man5', 'datastore.cfg', 'Datastore Configuration', [author], 5), ('config/domains/man5', 'domains.cfg', 'Realm Configuration', [author], 5), ('config/media-pool/man5', 'media-pool.cfg', 'Media Pool Configuration', [author], 5), - ('config/node/man5', 'node.cfg', 'Node Configuration', [author], 5), + ('config/node/man5', 'proxmox-backup.node.cfg', 'Proxmox Backup Server - Node Configuration', [author], 5), ('config/remote/man5', 'remote.cfg', 'Remote Server Configuration', [author], 5), ('config/sync/man5', 'sync.cfg', 'Synchronization Job Configuration', [author], 5), ('config/tape-job/man5', 'tape-job.cfg', 'Tape Job Configuration', [author], 5),