Help needed with man page conversions to asciidoc?

[mariobl]

Hello,

in Documentation/TODO I found this:

(!) rewrite man pages to AsciiDoc and generate final man pages by Asciidoctor & Docbook

I was wondering if you need help with this task? Obviously nobody works on this currently; I haven't found an appropriate Git branch. So I did some tests with doclifter (to get the docbook version), pandoc (to get the asciidoc version) and asciidoctor (to create the man page). See [1] for the result. Admittedly, neither doclifter nor pandoc produce something which is usable out-of-the-box. But there is not that much to fix. The file which I've »postprocessed« manually is already usable; it needs only some tweaks regarding link formattings. To create the man page using the asciidoc source, run the following command in the unpacked tarball:

asciidoctor -b manpage chrt.1.adoc

There's a file named translation.adoc conditionally included. This means, it would be nice to make the man pages translatable. The asciidoc format is perfectly suitable to be used with po4a [2]. In the manpages-l10n project [3], many util-linux man page translations are hosted, but this external approach has some disadvantages: distribution packages will be downloaded, then we create translation templates, translate the content and release a new version every three months. Besides the delay between the upstream release of util-linux and the release of manpages-l10n, we can never be sure that the installed translated man pages are in sync with the installed util-linux tools. That's why it would be much better to maintain the man page translations in util-linux itself and provide the translation template at GNU TP, as for the UI translations.

If you could imagine this, then I would fork util-linux, convert the man pages to asciidoc, write some scripts to create the translation templates and some other stuff, and I would provide help to the TP teams with importing the existing man page translations. The only thing I can't do is the integration of the asciidoc/po4a workflow into the autotools toolchain. I've no idea how this works...

But don't expect too much regarding the targeted util-linux version. During the tests, I've already created a translation template based on all available man pages, which has ~6000 (!) gettext messages. No worries, hardcore translators don't let that put them off ;) But the conversion and import of the current .po files will take some time, maybe weeks, maybe months. But if we get the man page translations into the upstream project - where they really belong - it's worth the effort for me. And besides that, asciidoc is much easier to maintain than *roff. Alternatively, we could focus first on the asciidoc conversion itself and add translations later.

[1] https://drive.google.com/file/d/1r5K5FQ_bd4wddVZCU--5JdIOsxDd1a9x/view?usp=sharing
[2] https://po4a.org/
[3] https://salsa.debian.org/manpages-l10n-team/manpages-l10n

[karelzak]

Oh, it's like reading a dream -- sure, go ahead :-)

It would be probably good to move this discussion to util-linux@vger.kernel.org upstream mailing list to make it possible to others to contribute with ideas and objections.

I like the idea with translated man pages maintained in the upstream tree, keep it all in one place is the only way how to keep it up to date. If I good understand then the result will be another template on translationproject.org to maintain man pages strings in po, right? What about in-tree .po files? I guess it should be separate from normal po files, po-docs/ directory?

For now (as the first step) for me more important is ASCII to man pages conversion with some usable result. The translations should be the next logical step. Is there any possibility to use some "style" template for conversion to the man pages (for example the same header/footer for all pages, generic sections like AVAILABILITY, etc.)?

Don't worry about Autotools, I'll do this task. All I need is some command-line examples of how to do the conversion.

[mariobl]

I'm now subscribed to util-linux@vger.kernel.org, so we can continue there.

[mariobl]

OK, the asciidoc files have been committed to the master branch. So I consider this issue as resolved.

[mator]

I'm sorry to post in a closed issue, but ...

no way to compile if there's no asciidoctor installed ?

$ git desc
v2.36-780-gae4e859f6
$ grep -A1 asciidoctor config.log
configure:20541: checking for asciidoctor
configure:20574: result: no
$ make
make  all-recursive
make[1]: Entering directory '/1/mator/util-linux'
Making all in po
make[2]: Entering directory '/1/mator/util-linux/po'
make[2]: Nothing to be done for 'all'.
make[2]: Leaving directory '/1/mator/util-linux/po'
make[2]: Entering directory '/1/mator/util-linux'
  GEN      lib/terminal-colors.d.5
/bin/bash: line 3: -b: command not found
make[2]: *** [Makefile:15969: lib/terminal-colors.d.5] Error 127
make[2]: Leaving directory '/1/mator/util-linux'
make[1]: *** [Makefile:14234: all-recursive] Error 1
make[1]: Leaving directory '/1/mator/util-linux'
make: *** [Makefile:6084: all] Error 2

not a problem installing it, but util-linux depends on ruby now to build. or we need to patch configure script to skip manual pages build, if asciidoctor is not installed.

[karelzak]

not a problem installing it, but util-linux depends on ruby now to build. or we need to patch configure script to skip manual pages build, if asciidoctor is not installed.

This is a bug. I'll fix it ASAP. The man pages have to be optional.

[mariobl]

But note, Ruby is no runtime dependency. It is only needed to build the *roff man pages from Asciidoc sources.

[karelzak]

Fixed.