Mailing-List: contact cygwin-help AT cygwin DOT com; run by ezmlm
List-Subscribe: <mailto:cygwin-subscribe AT cygwin DOT com>
List-Archive: <http://sourceware.org/ml/cygwin/>
List-Post: <mailto:cygwin AT cygwin DOT com>
List-Help: <mailto:cygwin-help AT cygwin DOT com>, <http://sourceware.org/ml/#faqs>
Sender: cygwin-owner AT cygwin DOT com
Mail-Followup-To: cygwin AT cygwin DOT com
Delivered-To: mailing list cygwin AT cygwin DOT com
From: ericblake AT comcast DOT net (Eric Blake)
To: Siegfried Heintze <siegfried AT heintze DOT com>, cygwin AT cygwin DOT com
Subject: RE: Documentation on functions
Date: Thu, 15 Sep 2005 16:48:28 +0000
Message-Id: <091520051648.3997.4329A5DC0008CE3600000F9D22073000330A050E040D0C079D0A@comcast.net>

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