How to change rendering of links in man pages?

Hello,

currently  I migrate man pages from *roff to Asciidoctor for the util-linux project. For "mailto:" links in the AUTHORS section, I use the following format:

mailto:johndoe@example.com[John Doe]

This renders in the *roff man page to:

.MTO "johndoe\(atexample.com" "John Doe" ""

This is OK so far; the "man" command shows name and link:

John Doe <johndoe@example.com>

But this is not all what I want. Having a look at a HTML page created directly with Asciidoctor, I get a clickable name which contains a "mailto:" link. To get such a link in *roff, the code needs to be:

.MT johndoe@example.com
John Doe
.ME

If this is a bit confusing, some more explanation: We convert the man pages to Asciidoctor to simplify the maintenance. Asciidoctor is much easier to read and write than the ancient and tricky *roff. The project tarball will be shipped with the *.adoc files which will be converted to *roff at end users side (or when the downstream package gets created) and installed into /usr/share/man/. We don't plan to publish HTML versions directly, because HTML based man page collections are already available from some Linux distributions, like Debian or Archlinux. They create the HTML versions from *roff man pages in distribution packages, not from Asciidoctor (or Perldoc, Markdown, whatever...) sources. That's why I need the version above in the final *roff man page. Is it possible to tell Asciidoctor to generate such a code for mail addresses?

Best Regards,
Mario

Hi,

looking at the source code of Asciidoctor man page backend converter the output you see can't be configured. Reading the comment at the beginning of the file, it is "trying to be consistent with the output produced by the a2x tool from AsciiDoc Python".

As the backends of Asciidoctor are plugable, you might be able to extend the existing converter and override convert_inline_anchor to do what you want to do.

Your mileage will vary based on your Ruby knowledge. To allow the downstream packages to convert AsciiDoc to man pages, you'll need to ship your extended backend with the rest of your sources.

Although this is not a full solution, I hope the shape of one possible solution emerges.

Thanks for the explanation.

Alexander Schwartz wrote

As the backends of Asciidoctor are plugable, you might be able to extend the existing converter and override convert_inline_anchor to do what you want to do.

Good idea, but ...

Your mileage will vary based on Ruby your knowledge. To allow the downstream packages to convert AsciiDoc to man pages, you'll need to ship your extended backend with the rest of your sources.

... I've neither Ruby nor any other programming language skills. Then it's a job for anyone else, or I accept the current appearance. The mentioned "trying to be consistent with the output produced by a2x" is a bit strange. Who benefits of such a consistent output? In my opinion, Asciidoctor should have a look at the nowadays usual things in *roff, and that is, for example, such a ".MT/.ME" mail address which enables a clickable name in the final HTML output produced by the distributions. But for the time being, I'm OK with this constraint. It's definitely better than sticking with *roff man pages.

Best Regards,
Mario

mariobl wrote

The mentioned "trying to be consistent with the output produced by a2x" is a bit strange. Who benefits of such a consistent output?

At some point Asciidoctor aimed to be a replacement to for this tool: a2x.

You might want to raise it upstream and open a GitHub ticket to change the standard behavior of Asciidoctor. If you can argue that a2x changed it behavior already, or that there is a *roff style guide that recommends it, this might be a plus.