Re: [avr-gcc-list] gcc-avr/avr-libc wiki

[Joerg Wunsch]

Eric Weddington <address@hidden> wrote:

> For example, the current documentation is done via this Doxygen
> tool. It's not a perfect tool.

Of course, if someone would want to see something else used, say some
SGML or XML dialect, as long as it's readily available and operating
system independent (Unix, Win32 (Win64?), MacOS X), *and* that person
(or persons) are willing to convert the entire existing documentation
into the new format initially, we're open ears.  We've got enough
gripe with doxygen over the years (and if you look into the Makefiles,
there are some gross hacks to e.g. improve the large tables we are
producing compared to standard doxygen), so it's not we wouldn't
accept anything better.

However, the current documentation is something like 345 printed
pages, so it's nothing that would be thrown away, and rewritten from
scratch within a weekend's time.  Also, while we did have the idea to
convert it into another format, it's simply that sheer amount of
volume, combined with the lack of enough spare-time for those who are
currently contributing to avr-libc, that has kept us away from
seriously looking for an alternative.

Btw., even contributors who are willing to just contribute pieces of
text but lack the doxygen toolchain theirselves are welcome to send
patches: most of the doxygen stuff is just simple text with a bit of
markup that's arguably not harder to understand than any of those
fancy wiki languages, so as long as the *contents* matches the current
standard (in both, the things it is talking about, as well as the
language used), it should be easy enough for one of the current
maintainers to integrate it into the tree, test it on a real doxygen,
maybe fix stylistic nits that only become visible once you run it
through doxygen., and commit it to CVS.

However, if someone wants to seriously contribute to documentation (or
take over maintenance of it) in the sense of getting CVS commit rights
granted, that person is expected to have at least a working doxygen
toolchain so they can verify the results *before* committing.  But
that's nothing like rocket science, and I've seen many developers
using doxygen so far.

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

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