This is the mail archive of the cygwin mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

RE: Documentation on functions


> Is there "documentation on the documentation"?
> 
> In other words, is the process of submitting documentation documented? Does
> one use the GNU texi or SGML docbook or some other format? I've been curious
> about these tools for years but have never used them.

A while ago (Feb 05, if you are trying to see the changes in
newlib CVS), I documented newlib's strftime (well, improved the
existing documentation) when I added all the remaining bits
required to become POSIX compliant.  I did this by checking the
newlib sources out of CVS, then edited newlib/libc/time/strftime.c
and other files, and submitted the patch to the newlib mailing
list, where it was accepted.  A while later, once a subsequent cygwin
documentation release was made, man strftime (as well as info
strftime) had my doc edits!

For newlib documentation, the documentation is embedded
inline in the C files, plus a couple of glue .tex files, which are then
processed during the newlib build by texinfo to create the
documentation.  I just followed the existing styles, so strftime.c
is an example you can use when adding documentation to
functions that have none.

I'm not sure about adding cygwin function documentation.

> 
> Are there any functions documented (and I just had the bad luck of picking
> the only three that were not documented) or do they all need to be
> documented? (Yikes! That could be a big job)!
> 
> Is it a simple matter of cutting and pasting from linux (e.g. fedora) man
> pages or does one have to go to the source code and extract the copious
> comments there and just reformat them into man pages?

Don't just steal documentation from fedora, as it is likely to be wrong.
But it can be a good starting point.  newlib is different from glibc, and
not all things work the same between the systems.  It takes effort
to document actual behavior.  Also, editing man pages directly is
useless, because the format is so archaic, and because man pages
are usually generated from an upstream format (like texinfo).

--
Eric Blake



--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]