Re: [avrdude-dev] Documentation build tools requirements - many complaints

[Joerg Wunsch]

As Brian Dean wrote:

> This command takes the mdoc and generates html (sort've):

>      tbl < avrdude.1 | groff -mtty-char -Thtml -mandoc > avrdude.html

> This _almost_ does the right thing, but the formatting is not quite
> right.  I do get some mdoc errors while running this, perhaps that
> is the reason.  I don't get those errors when using the 'ascii'
> output device and the formatting looks good in that case.  Odd.

It seems the HTML processor cannot cope with the nested .Bl/.El
structures used.

I'm still trying to find a way for generating either native texinfo
files, or compiled info pages, as WinAVR installs Tkinfo as an info
browser (most of the GNU tools ship with extended info docs anyway),
so it would be nice to have it all there.

Failing this, we could always have groff -mdoc generate Postscript,
and convert that to PDF.  That's probably about as convenient for the
typical MS-Win user as HTML were (and it doesn't suffer from the
formatting problems of groff's HTML backend).

Hmm, Eric Raymond wrote doclifter, a tool that can convert mdoc to
Docbook/XML:

http://www.catb.org/~esr//doclifter/doclifter-2.1.tar.gz

Maybe use this as a base to move the doc to docbook, and maintain that
one only?  The generated XML looks OK at the first glance, but I have
yet to see what's the exact toolchain to convert that to something
printable (like PS) in order to review the final result.

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)