Re: [avr-libc-dev] Re: Revised release criteria for GCC 4.0

[Joerg Wunsch]

As Bernardo Innocenti wrote:

> >Well, that's what documentation is for. ;-) See the avr-libc user
> >manual for more info.

> It's too bad Google didn't find it for me... Maybe that
> would be a good reason for making avr-libc documentation
> available online? :-)

Strange, if I google for »avr-libc documentation«, it's the very
first link presented:

http://www.nongnu.org/avr-libc/user-manual/

> >I'm perfectly willing to drop doxygen. In my mind it is too
> >restrictive.  Joerg will have to state his opinion.

> The fancy documentation tool used in newlib appears to follow
> Doxygen's philosophy, while using an ugly syntax.  I've never
> seen what the formatted output looks like, but I'd bet it's not
> on par with Doxygen's.

That doesn't sound too interesting then. :-/

I'm not a very happy camper with doxygen, just for the records, we've
mainly chosen it by its time because Ted Roth was already familiar
with it (from his simulavr project).  We've learned a lot by using it,
mostly that it is quite often not one of the most flexible tools.  I
remember that Ted once mentioned he wouldn't use it again when
starting afresh.  It has turned out that it was quite often more in
your way than being helpful when trying to achive something.

OTOH, if one wants to tie the documentation closely to the source,
it's probably still the best you can have.  However, when starting
from scratch, I could certainly imagine of other options:

. Write it completely in some SGML/XML dialect, without much other
  tools except of a good text editor.  This will allow for the most
  flexible output options (basically anything doxygen can already
  produce, but you can achieve whatever formatting tricks you want).
  On the downside, the exact markup will be in the hands of only a few
  people who are willing to learn it.  This is IMHO not as big of a
  problem as it might seem at first.  I've only seen very rare
  contributions of ready-to-go doxygen documentation from third
  parties (in particular, from end user), so 99 % of all documentation
  issues are in the domain of the major developers, who are usually
  also capable of writing up a markup language directly.

  Another point would be that documentation were decoupled from the
  source, so it requires a bit of self-discipline on the developers to
  keep the docs up to date.

. A mixed traditional man page (mdoc format) + SGML approach: all
  actual reference documentation is maintained in mdoc format, so it
  can be displayed using man(1) directly under Unix.  (Getting man to
  work under WinAVR shouldn't be too hard either, and I think there
  are Tcl/Tk frontends for it as well.)  As mdoc format is structured
  based on contents (as opposed to based on markup), it ought to be
  even possible to form a larger hyperlink reference out of it (maybe
  that has already been done by someone).

  All additional information is then maintained in SGML/XML, so the
  `prosaic' part of the docs that is more than the short reference can
  be kept apart.  Partially, we already do this within doxygen (see
  the `Modules' vs. `Related pages' entries), but we are strictly
  bound to the layout doxygen imposes to us, and as conceptual
  documentation is scattered through actual function documentation,
  the resulting structure is often a bit chaotic.  I personally feel
  the traditional man page + separate `handbook-style' documentation
  would help here.  I feel that the FreeBSD documentation is an
  excellent example here: man pages are maintained by the developers
  fairly strictly along with their source code modifications, while
  the handbook has developed into a well-structured, nicely written
  conceptual documentation that helps newcomers to find their way into
  using the software.

  OK, I might be a bit biased. ;-)

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

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