Posted by mariobl on Mar 19, 2021; 10:21pm
URL: https://discuss.asciidoctor.org/How-to-change-rendering-of-links-in-man-pages-tp8575.html

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