>       After reading Wine Weekly News Issue #200, (Congrats
> by the way), I stumbled across the Wine Status Pages.

Thanks.

>       In my humble opinion, this is a very dangerous and
> volatile place to have it.

It is volatile and there have definitely been instances of
people wondering where documentation has disappeared to.

>       This is quite tragic as my knowledge of XML is really
> weak. As far as I know, it's that HTML superset, isn't
> it?

SGML is the one document format To Rule Them All.  XML is
a subset of that.  HTML is a subset of XML (and therefore
SGML).  Realistically, Wine could probably use XML for all
its documents.  But we use SGML since that was around first.
We convert the SGML into various nice document formats
depending on how it's used.  If you know HTML then you won't
have much of a problem marking up SGML.

>       Stepping back a bit, I started thinking of tossing an
> SQL database on one of my machines and writing some
> kind of dynamic HTML front end for it.

I wouldn't.  Wine has lots of tools in use for building and
searching documentation, not the least of which is "grep". 

>       The second hurtle is what to put as the actual
> fields. I'm really only used to seeing function
> rendered an a "Unix man style" format. Name, synopsis,
> description, return value, errors, bugs.

I actually really like this idea.  The standard C library is
nicely documented in man pages, why shouldn't Win32 be the same
way?  I don't think we need another document format or repository
(Side note, is it just me, or is the GNU texinfo format the
stupidest form of documentation ever invented..)  The important
thing is, keep the documentation in a format that is easily
modifiable by developers.  Since most have a copy of CVS laying
around that probably means keeping docs in a text format somewhere
in the documentation/ directory.

The scope of this project is huge.  In some ways you're trying
to recreate MSDN, and as Greg pointed out that documentation
lives on real media in the hands of thousands of people.  Yes,
it might be nice to replicate that but copyright issues are
something you'll need to be aware of.  If you rewrite all of
it by hand you definitely won't infringe on copyrights, but is
there an easier way put it together?  Something tells me there's
already some resources out there that could be used as a foundation.

Also, be sure to read the "Terms of Use" link at the bottom of
msdn.microsoft.com.  It may as well just say "You can only read
our web pages."

A quick search on Google alludes to people writing man pages for
Win32.  This was on a NetBSD mailing list:

http://mail-index.netbsd.org/netbsd-bugs/2001/05/17/0008.html

>Number:         12974
>Category:       pkg
>Synopsis:       w32doc-borland - man pages for the win32 api
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    pkg-manager
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Thu May 17 13:16:00 PDT 2001
>Closed-Date:
>Last-Modified:
>Originator:     Ben Collver
>Release:        1.5
>Organization:
>Environment:
>Description:
>A set of Unix-like man pages for the Windows 32 API.  This package creates
>a new manual section (wb) containing man pages derived from a Windows
>help file distributed by Borland for Delphi2.  Once installed, you could for
>example read the WinMain man page by typing "man wb WinMain".

>This documentation is not as up-to-date as that in devel/w32doc.

---------------
Brian Vincent
Copper Mountain Telecom
vincentb@coppercolorado.com