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

[Joerg Wunsch]

As E. Weddington wrote:

> >Not even WinAVR does.  It ships a `man' command, but that would
> >need a lot of hacking before it could be made work.

> That's correct. And even if somebody got 'man' working on Windows,
> most Windows users wouldn't think to use it. man is not a typical
> doc distrubution mechanism on Windows.

Well, at least "info" can also display man pages, no idea about
Tkinfo.

> Another option, that I'm exploring for both a "WinAVR user manual"
> and for avr-libc, is the use of AsciiDoc (google for it). It's a
> text file, with very minimal formatting that gets translated by the
> "asciidoc" program, a Python script, and it can output HTML and
> Docbook (as well as LinuxDoc).

I'm a bit sceptical of Yet Another Doc Converter, as doxygen has shown
us (in avr-libc) that we often enough ended up with wanting more than
the automatic conversion could provide for us.  I'm currently more
inclined to use docbook directly for avr-libc.  As Eric Raymond's tool
could save all the existing man page work for avrdude into docbook
format, it seems to be an option to me here, too.

The existing mdoc man page file has a lot of structural information
that would completely get lost if you convert it to plaintext that can
be processed with asciidoc, and you have to rely again completely on
asciidoc to re-invent that structure.  docbook supposedly offers the
same amount of structural information, so that could all be preserved.

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

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