Re: Improving newlib's doc?

[Jeff Johnston <jjohnstn at redhat dot com>]

mwoehlke wrote:
> 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?).

It's not hard at all.  Most if not all changes can be figured out from 
existing docs already in the file and using copy and paste.

> 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. :-)

I have very little experience with documentation formats so I really 
don't know what help I can be on discussing which format is best.  I 
have few thoughts on the topic other than I don't want something so 
complicated that noone bothers to update the documentation anymore and 
it better produce html and info files.

Are you planning to rip out the documentation from the source files or 
simply change the format?  What are the actual benefits of what you are 
proposing?

> 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