Login  Register

How to change rendering of links in man pages?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options Options
Embed post
Permalink
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

How to change rendering of links in man pages?

mariobl
3 posts
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
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to change rendering of links in man pages?

Alexander Schwartz
48 posts
This post was updated on Mar 22, 2021; 8:57pm.
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.

Alexander Schwartz (alexander.schwartz@gmx.net)
https://www.ahus1.de
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to change rendering of links in man pages?

mariobl
3 posts
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
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to change rendering of links in man pages?

Alexander Schwartz
48 posts
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.

Alexander Schwartz (alexander.schwartz@gmx.net)
https://www.ahus1.de
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: How to change rendering of links in man pages?

mojavelinux
Administrator
2681 posts
In reply to this post by mariobl
Mario,

Regarding this comment:

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

Please don't use shaming tactics to try to get what you want, especially without understanding why a decision was made. If you want to present a concrete proposal about how we can build on what we have, feel free to bring that proposal to the floor. But please do so in a constructive way. Suggesting that we don't know our own users is not constructive.

> Asciidoctor should have a look at the nowadays usual things in *roff

Asciidoctor isn't an entity you can address. Asciidoctor doesn't just do things. It's a community. You can lift up other community members who are interested in building on what has already been done, or you can do it yourself. But you can't just point at the project and say "do that". It doesn't work that way. And saying what it does is wrong, limiting, or a constraint, but that you will use it anyway (implying it's bad, but you put up with it), isn't how you help make it better. All that does is create animosity and harm the project. In the future, please be both constructive and respectful when you leave comments.

-Dan

--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux