Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
3 posts
|
Thanks for the explanation.
Good idea, but ... ... 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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
48 posts
|
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Free forum by Nabble | Edit this page |