Re: Help needed with man page conversions to asciidoc?

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hello,

Am Fr., 19. März 2021 um 23:50 Uhr schrieb Mario Blättermann
<mario.blaettermann@xxxxxxxxx>:
>
> Hello,
>
> Am Di., 9. März 2021 um 09:49 Uhr schrieb Karel Zak <kzak@xxxxxxxxxx>:
> >
> > On Mon, Mar 08, 2021 at 09:10:34PM +0100, Mario Blättermann wrote:
> > > >
> > > > 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?
> > > >
> > > Yes, it needs a separate .po file. It's not OK to mix UI and doc
> > > translations. Well, it's theoretically possible to merge both .pot
> > > files in one to force translators to work on both UI and man pages.
> > > But I think the UI .pot file with more than 4000 gettext messages is
> > > big enough, especially for newbies. So don't let's blow it up to more
> > > than 10000.
> >
> >  I agree.
> >
> > > I propose the following structure:
> > >
> > > The asciidoc man pages will be stored where the *roff man pages reside
> > > for ages: in their respective subdirectories (sys-utils, schedutils,
> > > whatever). For the special asciidoc files footer.adoc,
> > > translation.adoc and asciidoc.conf we need an extra directory, let's
> > > name it "man-common".
> >
> >  OK.
> >
> > > For the man page translations, we can also use man-common. It's a good
> > > place for files like po4a.conf or the TP sync script (if desired), and
> > > the subdirectory "po".
> >
> >  OK. For scripts, see also tools/ directory where we have some
> >  checkers, simple script to commit po/ changes to git (git-tp-sync)
> >  etc.
> >
> > ...
> > > > 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.)?
> > > >
> > > Yes, see the attached tarball for an example footer.adoc. I could
> > > extend it with a "Reporting bugs" section.
> >
> >  I see, it looks pretty cool and readable.
> >
> > > > Don't worry about Autotools, I'll do this task. All I need is some
> > > > command-line examples of how to do the conversion.
> > >
> > > Oh, very nice... Although I also use Autotools in manpages-l10n (but
> > > haven't written all the Makefile* and related stuff), my knowledge is
> > > poor, and I'm happy after each release without problems;)
> > >
> > > Karel, I've already forked the util-linux project at Github; maybe it
> > > is useful to create a branch for the Asciidoc stuff in your main repo,
> > > which I can check out into the forked repo? This would be probably the
> > > most painless way for a merge request.
> >
> >  OK, I have created a new branch "topic/asciidoc" on github.
> >
>
> Just FYI: I'm finished with the import, but I stumbled upon some
> peculiarity in Asciidoc. Many of the current util-linux man pages use
> "mailto:"; links as follows:
>
> .MT johndoe@xxxxxxxxxxx
> John Doe
> .ME
>
> This leads to properly clickable links in the online man page
> collections of certain Linux distributions, such as Archlinux [1] or
> Debian [2]. But the *roff conversion engine of Asciidoctor produces a
> slightly different code:
>
> .MTO "johndoe\(atexample.com" "John Doe" ""
>
> Which renders to ...
>
> John Doe <johndoe@xxxxxxxxxxx>
>
> ... in the HTML output generated by man2html which is used by the
> mentioned online collections. The link is not clickable. Because I
> consider the online collections as the second most important way to
> view man pages, a non-clickable "mailto:"; link would be a step back,
> which I don't want. I've posted this issue in the Asciidoctor forum
> [3]. Maybe it is possible to create the desired custom code using a
> macro... I hope so. Or the Asciidoctor developers change it upstream -
> which would be the better solution.
>
> BTW, the same applies to weblinks, but first let's find out how to get
> proper mail links.
>
> [1] https://man.archlinux.org/
> [2] https://manpages.debian.org/
> [3] https://discuss.asciidoctor.org/How-to-change-rendering-of-links-in-man-pages-tt8575.html
>

Just found another problem: After applying the Makefile patches [1]
and running "autogen.sh" and "configure", the command »make gen-man«
fails:

[mariob@t450 util-linux-mariobl]$ make gen-man
Makefile:15938: warning: overriding recipe for target 'misc-utils/uuidd.8'
Makefile:15927: warning: ignoring old recipe for target 'misc-utils/uuidd.8'
Makefile:15938: warning: overriding recipe for target 'misc-utils/getopt.1'
Makefile:15927: warning: ignoring old recipe for target 'misc-utils/getopt.1'
 GEN      lib/terminal-colors.d.5
/bin/sh: line 3: lib/terminal-colors.d.5.adoc: Permission denied
make: *** [Makefile:15940: lib/terminal-colors.d.5] Error 126

Don't know what permissions are really needed here:

[mariob@t450 util-linux-mariobl]$ ls -l lib/terminal-colors.d.5.adoc
-rw-r--r-- 1 mariob mariob 4947 Mar 20 16:34 lib/terminal-colors.d.5.adoc

I cannot imagine that lib/terminal-colors.d.5.adoc needs to be
executable... However, after chmod +x, the error message is even
stranger than before:

[mariob@t450 util-linux-mariobl]$ make gen-man
Makefile:15938: warning: overriding recipe for target 'misc-utils/uuidd.8'
Makefile:15927: warning: ignoring old recipe for target 'misc-utils/uuidd.8'
Makefile:15938: warning: overriding recipe for target 'misc-utils/getopt.1'
Makefile:15927: warning: ignoring old recipe for target 'misc-utils/getopt.1'
 GEN      lib/terminal-colors.d.5
lib/terminal-colors.d.5.adoc: line 1: //po4a:: No such file or directory
lib/terminal-colors.d.5.adoc: line 2: ////: Is a directory
lib/terminal-colors.d.5.adoc: line 3: terminal-colors.d.5: command not found
lib/terminal-colors.d.5.adoc: line 4: syntax error near unexpected
token `newline'
lib/terminal-colors.d.5.adoc: line 4: `Copyright 2014 Ondrej Oprala <ooprala@red
hat.com>'
make: *** [Makefile:15940: lib/terminal-colors.d.5] Error 2

Obviously the script cannot handle the comment lines at all.

I noticed the following line in the Makefile generated by the configure script:

asciidoc_man_cmd = $(ASCIIDOCTOR)

This seems to be the pure "asciidoctor" command without any options,
as far as I can tell, given my poor knowledge about GNU Autotools.

[1] https://github.com/mariobl/util-linux/commit/34455501de74c405b56daa438ee3e839e92fbc17

Best Regards,
Mario




[Index of Archives]     [Netdev]     [Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux