links to other manpages in manpage rendered incorrectly

[boutil]

Hello,

We got the following bug report in Debian about result of asciidoctor to generate man page, with the example.
The link to the asciidoctor manpage is not rendered correctly when generating the manpage with asciidoctor --backend manpage. Whereas the a2x tool renders it correctly.

Replacing link: by xref: is a workaround for asciidoctor for the man output, but it seems a bit strange that the result with link: is not the same as the one generated by a2x.
What is the correct way to get the expected result?

ASCIIPATIENT(1)
===============

NAME
----
asciipatient - manpage links in a manpage are rendered in a weird way


DESCRIPTION
-----------

Observed in one of the packages I maintain: The links to other manpages
in the adoc provided by upstream are rendered in a unsual and
irritating way.

It is possible upstream did a bad job here - but all I can tell is
using the old a2x yields a sound result. In case this is just bad
adoc style - I could use a pointer to the documentation where this is
described. Read: While asciidoctor has a lot of documentation, I
constantly fail to find the bits I need to got something done.


HOW TO REPEAT
-------------

Run this document through "asciidoctor --backend manpage", then execute
"man ./asciipatient.1". Compare with the result of "a2x -f manpage".


SEE ALSO
--------

link:asciidoctor.1.adoc[*asciidoctor*(1)]


EXPECTED
--------

....
SEE ALSO
       asciidoctor(1)
....


GOT
---

....
SEE ALSO
       asciidoctor(1) <asciidoctor.1.adoc>
....

[mojavelinux]

For first-level support for a man link, you would need to solution for #3684 (currently available in the extension lab).

[mojavelinux]

Btw, the link macro always passes through the target as is, which in this case is to link to asciidoctor.1.adoc. If you want to link to a sibling document, that's what the xref macro is for. I don't quite know why a2x exhibits the behavior you describe, bit it's an accidental feature. xref is the right macro in this case.