[Po4a-devel] Help with po4a on Ruby Document format

[Francesco Poli]

Hello!

First off, thanks for developing po4a, which looks like a very useful
tool for i18n of non-programmatic works!

I am the current maintainer of apt-listbugs [1].

[1] https://packages.debian.org/sid/apt-listbugs

I am trying to use po4a in order to internationalize the man page,
which is written in Ruby Document format.
The source for the man page (in Ruby Document format, as I said) may be
seen on the public git repository [2], embedded in the program code
(between =begin and =end markers).

[2] https://anonscm.debian.org/cgit/apt-listbugs/apt-listbugs.git/tree/bin/apt-listbugs

Unfortunately, the Ruby document format [3] does not seem to be
directly supported by po4a. Could you please confirm that?
Maybe I should file a wishlist bug report against po4a, requesting the
support for this format...

[3] https://en.wikipedia.org/wiki/Ruby_Document_format

Anyway, I was hoping that the POD format [4] could be similar enough,
and I tried with:

  $ po4a-gettextize -f pod -m apt-listbugs -p doc-apt-listbugs.pot

[4] https://en.wikipedia.org/wiki/Plain_Old_Documentation

I encountered a number of issues.

First of all, the processing did not stop at the =end marker and I
found all the program code at the end of the .pot file.

I tried to work around this with:

  $ sed '/^=end$/q' apt-listbugs | po4a-gettextize -f pod -m - -p doc-apt-listbugs.pot

but it turns out that po4a is not able to process standard input [5].
I hope this feature may be implemented soon.

[5] https://bugs.debian.org/378625

Then I tried to use a temporary file:

  $ sed '/^=end$/q' apt-listbugs > apt-listbugs.rd
  $ po4a-gettextize -f pod -m apt-listbugs.rd -p doc-apt-listbugs.pot
  $ rm -f apt-listbugs.rd

Maybe I should permanently separate out the man page source from the
program code, but I like the fact that it is embedded in the script...

Another issue is that I see that several text blocks are incorrectly
treated as verbatim blocks, just because they are indented. The first
such block is "Print usage help and exit".
Once again, this is probably caused by the lack of direct support for
the Ruby Document format and by the slightly different syntax of POD...
I can try and see whether I can modify the man page source, so that
those blocks are not indented (hoping that the generated man page does
not change too much), but I am beginning to suspect that I am getting
things wrong.

Could you please suggest a better strategy?

Please let me know.
Thanks for your time and for any help you may provide.


-- 
 http://www.inventati.org/frx/
 There's not a second to spare! To the laboratory!
..................................................... Francesco Poli .
 GnuPG key fpr == CA01 1147 9CD2 EFDF FB82  3925 3E1C 27E1 1F69 BFFE
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/po4a-devel/attachments/20160618/76dcb500/attachment.sig>