[Openswan dev] problems in ipsec_pluto.8..

[Eric S. Raymond]

mcr at xelerance.com <mcr at xelerance.com>:
>   Actually, we want to switch to DocBook for our man pages, anyway.

Oh, good!  With my patches to your pages and and doclifter, that job is done.  
Everybody wins.

>   Our major concern is that we still do not see an easily installed
> distro-agnostic DocBook->man converter. 

I know of two good ones -- Tim Walsh's xmlto and Steve Cheng's docbook2man.
I don't think either is especially distro-dependent.  Both want xsltproc,
docbook2man wants Perl.  

Is either of these dependencies a problem?  I have some clout with
both maintainers, in fact Steve Cheng has made the design decision to
have docbook2man be a doclifter inverse and tests it with doclifter
conversions.  Whatever your concerns are, if it's reasonably possible
to address them let's do it.

>   We currently document both the daemon ("pluto") and the control
> program ("whack") in the same man page. (It is installed twice) 
>   I'm not sure that I like having the {} notation in the heading.
>   Is this the only alternative?

The hard constraint is that DocBook can handle multiple names per
refentry but only one description line per refentry.   So what you
could do is this:

NAME
     ipsec pluto, ipsec whack -- description goes here
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>