Internally maintained end-to-end API documentation

[Brian Vincent (C)]

>       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 at coppercolorado.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.winehq.org/pipermail/wine-devel/attachments/20031215/46945c26/attachment.html