Improving newlib's doc?

[mwoehlke]

Jeff Johnston wrote:
> 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.

I was referring specifically to the formatting... it looks like one has 
to insert all the line breaks by hand (worse, do the indentation by 
hand) in order for things to "come out right". Or, at any rate, it is 
being maintained this way.

When working with nroff documents, protocol is flush-left indent (i.e. 
none), and line breaks after all sentences and phrases. The point is for 
*roff to build blocks and do the folding and line splitting itself. I'm 
not familiar with LaTeX, but I would think the same is true.

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

That's why I'm leaning towards SGML; it's bulkier than I think nroff 
would be, but less esoteric; most people understand the rudiments or can 
pick it up quickly. SGML should be ideal for producing all three major 
formats (nroff, LaTex/texinfo, and HTML) directly, and even if an 
existing parser cannot be found/used, it should be very easy to write 
one (starting with either nroff or LaTeX would be more complicated). Or, 
we could just extend the existing parser to handle more formatting (it's 
the bullets and indentation in particular that need to be handled 
differently) and use that. I haven't looked closely yet; before I do 
anything I want a feel for where you would be OK taking this.

> 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?

Benefits: an updated format style, ability to generate nroff directly 
(right now I am told the nroff doc - i.e. manpages - come from the info, 
and poorly at that) as well as proper LaTeX directly.

I don't see any reason why the doc *has* to be moved out, although I 
could argue for that. Really, though, it doesn't matter enough for me to 
make a case of it; IOW I'm fine with whatever your preference is. If the 
parsers need it separated, that should be easy to do as part of the make 
process.



This was very helpful in addressing my questions; thanks!

-- 
Matthew
Websites such as ... Wikipedia ... are reputed to occupy users for 
periods in excess of 5 hours. -- Wikipedia article on Internet Addiction