[avrdude-dev] Re: avrdude documentation (was: Re: avrdude + Windows)

[Joerg Wunsch]

[Branching this off from a private discussion with Eric.]

As eric wrote:

[MS Help, idea to convert the man page into that format since it's the
standard for reference documentation on Win*.]

> > Well, i have no idea about the tools that would create this format.
> > As long as we could somehow convert it from what we've already got,
> > why not?  Does perhaps Cygwin offer some tool for it?

> No MS Help! Evil! Well... I'll check to be sure.

Btw., what exactly is so evil about MS Help?  Not that i'd be thrilled
by that help system.  Every time i hade to use a Windoze, and
eventually asked the help system, it couldn't tell me anything i
didn't already knew by that time :), but that's hardly the fault of
the format itself.

Sorry if i'm sounding naive with my "why?", but i simply have no clues
about how MS Help is organized at all.  Maybe it's indeed all that
evil that we should avoid it.  My naive imagination is that it might
be in some way comparable to the GNU info files (only that it's all
binary junk instead of plain text), with some central directory where
you have to register etc.

[Next idea: split off the advanced documentation from the quick online
reference the "man" system is meant to be.  That would mean to move
out infos about the programming hardware out of the man page, add the
programmer's schematics, information about the syntax of the config
file, etc. pp.  I can imagine that this could be texinfo-maintained
documentation, resulting in GNU info files on Unix, plus PS/PDF/HTML
on all platforms.]

> Yes! Advanced docs with the topics you mentioned in PDF | HTML. That
> would be perfect for the Windows platform!

So the question is: what opinions do others have here?  I guess
doxygen is a bit out of the question.  Our experience in avr-libc
wasn't that nice after digging a bit deeper into all of it, and the
main reason for doxygen, the tight integration of code and
documentation, is only needed for documenting APIs and such.  This is
not the major pointer for the advanced avrdude documentation.

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

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