borgbackup
man pages: broken references to patterns help/manual
Have you checked borgbackup docs, FAQ, and open Github issues?
Yes
Is this a BUG / ISSUE report or a QUESTION?
BUG
Your borg version (borg -V).
borg 1.2.3
Operating system (distribution) and version.
OpenBSD/amd64 7.2-current
Describe the problem you're observing.
borg-create(1) and other manual pages contain what looks like unexpanded macros when it comes borg-patterns(1) and borg-placeholders(1):
$ man borg-create | col -b | grep -E -A1 'borg_(patterns|placeholders)'
For more help on include/exclude patterns, see the borg_patterns
command output.
--
For more help on placeholders, see the borg_placeholders command
output.
It should read either "see the borg help patterns command output" or
preferably, imho, just "see borg-patterns(1)".
Other manuals such as borg-prune(1) seem to just inline the command, which reads better while still inconsistent with the rest:
$ man borg-prune | col -b | grep -B2 borg_patterns
-aGLOB--glob-archivesGLOB
only consider archive names matching the glob. sh: rules apply,
see "borg help patterns".
Furthermore, neither borg-help(1) nor borg help output list either of those
two commands:
$ borg help | grep -e patterns -e placeholders ; echo $?
1
In other places, e.g. borg(1), proper references to borg-patterns(1) do exist
in the SEE ALSO section, so this appears to be an issue with whatever ought to
turn the literal borg_patterns reference into something.
Unfortunately, I don't quite understand how documentation is generated from the code and neither do I have the time to investigate this.
There is a mapping in borg.archiver._common.rst_plain_text_references that should be used in plain text contexts.
That will work for e.g. borg help delete - the plain text output by that is processed by nanorst and "borg_patterns" is expanded to "borg help patterns".
The html docs expand this correctly using a link to the correct place in the docs and link text being "borg help patterns".
Hmm, I suspect there is simply no code for this transformation in the man page generation (see setup_docs.py)