Improving newlib's doc?

[mwoehlke <mwoehlke at tibco dot com>]

Jeff Johnston wrote:
> mwoehlke wrote:
> > In the mean time, would you be receptive if someone (me) took on 
> > overhauling the existing documentation system? (See the thread I FW'd 
> > here from cygwin-talk, "Re: What's wrong with *roff, anyway?".
>
> I don't see a posting with the subject you have quoted.  Could you 
> possibly resend it or refer me to the original message?  I replied to 
> your other question about where to update printf documentation.

Odd, gmane got it, but it does look like it got stuck there. Starting 
over...

I found newlib/libc/stdio/sprintf.c, and quite frankly I am a little 
surprised that this (format-wise) is all newlib has for doc; it seems 
like it would be a pain to maintain (all formatting is apparently done 
by hand?).

So... I was thinking about adding support for SGML documentation (or 
some other format that could be easily converted to both nroff and 
LaTeX/texinfo - I'm open to suggestions), and updating the makefiles 
accordingly so that both manpages and info would be produced. Then I was 
going to investigate "modernizing" (again, w.r.t. formatting) the doc 
using the Linux glibc manpages as a starting point. My justification is 
that I personally find that format much more 'readable', although so far 
I've only heard my own opinion. :-)

Honestly, I'd personally prefer maintaining everything in nroff 
(depending on the standards you use, converting *to* nroff can be 
difficult-to-impossible), but I'm not aware of a nroff->LaTeX converter.

(At any rate, I'm not touching that doc if it has to be formatted by hand.)

For reference, here is the original thread on cygwin-talk:
http://sourceware.org/ml/cygwin-talk/2006-q3/msg00151.html

--
Matthew
"We're all mad here. I'm mad. You're mad... You must be, or you wouldn't 
have come here." -- The Cheshire Cat