man pages: broken references to patterns help/manual

[klemensn]

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.

[ThomasWaldmann]

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

[ThomasWaldmann]

The html docs expand this correctly using a link to the correct place in the docs and link text being "borg help patterns".

[ThomasWaldmann]

Hmm, I suspect there is simply no code for this transformation in the man page generation (see setup_docs.py)