This is the mail archive of the
newlib@sourceware.org
mailing list for the newlib project.
Re: Improving newlib's doc?
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