<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="MS Exchange Server version 5.5.2653.12">
<TITLE>Re: Internally maintained end-to-end API documentation</TITLE>
</HEAD>
<BODY>
<BR>
<P><FONT SIZE=2>> After reading Wine Weekly News Issue #200, (Congrats </FONT>
<BR><FONT SIZE=2>> by the way), I stumbled across the Wine Status Pages. </FONT>
</P>
<P><FONT SIZE=2>Thanks. </FONT>
</P>
<P><FONT SIZE=2>> In my humble opinion, this is a very dangerous and </FONT>
<BR><FONT SIZE=2>> volatile place to have it. </FONT>
</P>
<P><FONT SIZE=2>It is volatile and there have definitely been instances of </FONT>
<BR><FONT SIZE=2>people wondering where documentation has disappeared to. </FONT>
</P>
<P><FONT SIZE=2>> This is quite tragic as my knowledge of XML is really </FONT>
<BR><FONT SIZE=2>> weak. As far as I know, it's that HTML superset, isn't </FONT>
<BR><FONT SIZE=2>> it? </FONT>
</P>
<P><FONT SIZE=2>SGML is the one document format To Rule Them All. XML is </FONT>
<BR><FONT SIZE=2>a subset of that. HTML is a subset of XML (and therefore </FONT>
<BR><FONT SIZE=2>SGML). Realistically, Wine could probably use XML for all </FONT>
<BR><FONT SIZE=2>its documents. But we use SGML since that was around first. </FONT>
<BR><FONT SIZE=2>We convert the SGML into various nice document formats </FONT>
<BR><FONT SIZE=2>depending on how it's used. If you know HTML then you won't </FONT>
<BR><FONT SIZE=2>have much of a problem marking up SGML. </FONT>
</P>
<P><FONT SIZE=2>> Stepping back a bit, I started thinking of tossing an </FONT>
<BR><FONT SIZE=2>> SQL database on one of my machines and writing some </FONT>
<BR><FONT SIZE=2>> kind of dynamic HTML front end for it. </FONT>
</P>
<P><FONT SIZE=2>I wouldn't. Wine has lots of tools in use for building and </FONT>
<BR><FONT SIZE=2>searching documentation, not the least of which is "grep". </FONT>
</P>
<P><FONT SIZE=2>> The second hurtle is what to put as the actual </FONT>
<BR><FONT SIZE=2>> fields. I'm really only used to seeing function </FONT>
<BR><FONT SIZE=2>> rendered an a "Unix man style" format. Name, synopsis, </FONT>
<BR><FONT SIZE=2>> description, return value, errors, bugs. </FONT>
</P>
<P><FONT SIZE=2>I actually really like this idea. The standard C library is </FONT>
<BR><FONT SIZE=2>nicely documented in man pages, why shouldn't Win32 be the same </FONT>
<BR><FONT SIZE=2>way? I don't think we need another document format or repository </FONT>
<BR><FONT SIZE=2>(Side note, is it just me, or is the GNU texinfo format the </FONT>
<BR><FONT SIZE=2>stupidest form of documentation ever invented..) The important </FONT>
<BR><FONT SIZE=2>thing is, keep the documentation in a format that is easily </FONT>
<BR><FONT SIZE=2>modifiable by developers. Since most have a copy of CVS laying </FONT>
<BR><FONT SIZE=2>around that probably means keeping docs in a text format somewhere </FONT>
<BR><FONT SIZE=2>in the documentation/ directory. </FONT>
</P>
<P><FONT SIZE=2>The scope of this project is huge. In some ways you're trying </FONT>
<BR><FONT SIZE=2>to recreate MSDN, and as Greg pointed out that documentation </FONT>
<BR><FONT SIZE=2>lives on real media in the hands of thousands of people. Yes, </FONT>
<BR><FONT SIZE=2>it might be nice to replicate that but copyright issues are </FONT>
<BR><FONT SIZE=2>something you'll need to be aware of. If you rewrite all of </FONT>
<BR><FONT SIZE=2>it by hand you definitely won't infringe on copyrights, but is </FONT>
<BR><FONT SIZE=2>there an easier way put it together? Something tells me there's </FONT>
<BR><FONT SIZE=2>already some resources out there that could be used as a foundation. </FONT>
</P>
<P><FONT SIZE=2>Also, be sure to read the "Terms of Use" link at the bottom of </FONT>
<BR><FONT SIZE=2>msdn.microsoft.com. It may as well just say "You can only read </FONT>
<BR><FONT SIZE=2>our web pages." </FONT>
</P>
<P><FONT SIZE=2>A quick search on Google alludes to people writing man pages for </FONT>
<BR><FONT SIZE=2>Win32. This was on a NetBSD mailing list: </FONT>
</P>
<P><FONT SIZE=2><A HREF="http://mail-index.netbsd.org/netbsd-bugs/2001/05/17/0008.html" TARGET="_blank">http://mail-index.netbsd.org/netbsd-bugs/2001/05/17/0008.html</A> </FONT>
</P>
<P><FONT SIZE=2>>Number: 12974 </FONT>
<BR><FONT SIZE=2>>Category: pkg </FONT>
<BR><FONT SIZE=2>>Synopsis: w32doc-borland - man pages for the win32 api </FONT>
<BR><FONT SIZE=2>>Confidential: no </FONT>
<BR><FONT SIZE=2>>Severity: non-critical </FONT>
<BR><FONT SIZE=2>>Priority: low </FONT>
<BR><FONT SIZE=2>>Responsible: pkg-manager </FONT>
<BR><FONT SIZE=2>>State: open </FONT>
<BR><FONT SIZE=2>>Class: change-request </FONT>
<BR><FONT SIZE=2>>Submitter-Id: net </FONT>
<BR><FONT SIZE=2>>Arrival-Date: Thu May 17 13:16:00 PDT 2001 </FONT>
<BR><FONT SIZE=2>>Closed-Date: </FONT>
<BR><FONT SIZE=2>>Last-Modified: </FONT>
<BR><FONT SIZE=2>>Originator: Ben Collver </FONT>
<BR><FONT SIZE=2>>Release: 1.5 </FONT>
<BR><FONT SIZE=2>>Organization: </FONT>
<BR><FONT SIZE=2>>Environment: </FONT>
<BR><FONT SIZE=2>>Description: </FONT>
<BR><FONT SIZE=2>>A set of Unix-like man pages for the Windows 32 API. This package creates </FONT>
<BR><FONT SIZE=2>>a new manual section (wb) containing man pages derived from a Windows </FONT>
<BR><FONT SIZE=2>>help file distributed by Borland for Delphi2. Once installed, you could for </FONT>
<BR><FONT SIZE=2>>example read the WinMain man page by typing "man wb WinMain". </FONT>
</P>
<P><FONT SIZE=2>>This documentation is not as up-to-date as that in devel/w32doc. </FONT>
</P>
<P><FONT SIZE=2>---------------</FONT>
<BR><FONT SIZE=2>Brian Vincent</FONT>
<BR><FONT SIZE=2>Copper Mountain Telecom</FONT>
<BR><FONT SIZE=2>vincentb@coppercolorado.com</FONT>
</P>
</BODY>
</HTML>