On Saturday 13 December 2003 04:40 am, Joshua Walker wrote:
There is one thing that really bugging the heck out of me. Most of the API documentation is possessed by MSDN. In my humble opinion, this is a very dangerous and volatile place to have it.
I was once told that using the internet as a data resource is like watching The Library of Alexandria burn over and over again.
lol. That's about right. However, if you subscribe to MSDN Library, you can get snapshots of the Library on DVD. They are pretty complete, do not create logs at Microsoft every time you research any small thing, and they do not disappear at the whim or accident of Microsoft.
Better still: I find that most info I need to develop wine is part of the Platform SDK; this is a freely downloadable subset of the Library from Microsoft (if you consider a click-through EULA "free").
I think it's about time to take the various Windows APIs and place them onto a fishbowl for safe keeping.
Wine has its own internal (in-source) documentation which is robotically put somewhere on the web. Some if it is good, some of it sucks... you are welcome and encouraged to contribute.
Having lurked here for as long as I have, I havefound two constants about announcing projects on wine-devel that I'd like to share.
- In order to have Alexandre change direction, you
better have a very good reason.
that's a good thing.
- Many ideas have been announced here with no real
clear goal or steps of execution. They soon die of atrophy shortly after.
so is that :) Wine requires lots of brainstorming and tossing of ideas back and forth. Also, unpaid volunteers are probably less likely to follow through sometimes. For example, I'm guilty of this across several axes. Also, some projects, like the Internet Exploder replacement for example, are simply put on the backburner for technical or project-scope reasons, although they really are not discarded, and will eventually arrive.
As for myself, I'm thinking to taking up the mantle for documenting the Windows API, or at least setting up public facilties for myself and others to use. The problem I have is how about will it be documented?
Good idea.
First goal is to figure out where on earth to *put* the documentation.. I'm thinking of some kind of universal data holder where API information can aggregated, parsed, and rendered to one's choosing. As I shook my magic hate-ball I asked, "What do you think about storing the API data in some kind of XMLish-thingy format?" All signs pointed to yes. 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?
For a start, just follow the conventions you see in the wine sources already. They will be picked up by the robot and put on-line AFAIK.
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. The SQL idea is nice because I can write the front end to spit out what I have in any data format I can dream of, including XML. It also allows people to come to my website, pop in an API function that wan't there, and move on with their lives. That seems plausible.
I think this is overkill. In-source doc's are good enough for now, and if we eventually need something more sophisticated, one of the perl hackers around here will have a conversion plan.
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. See "man fork" for example. We will also need kind of a DLL overview, (man stdio?). What about something a little more UML compatible.
Again, there are existing conventions you can follow. They are quite simple and easy to implement, and there are abundant examples in the source.
Good luck! I welcome your enthusiasm and look forward to your patches. One word of advice: I am not a big fan of legal nonsense, but please bear in mind that the Microsoft documentation is copyrighted. A good way to avoid infringement is to document the functionality you see implemented in the wine sources, using MSDN only for proofreading purposes, or not at all.