--- "Brian Vincent (C)" VincentB@coppercolorado.com wrote:
<snip>
Stepping back a bit, I started thinking oftossing 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".
You know, funny things happen when you actully read the manual (^_^)
I'm up to speed on how the API is documented in the code now. I'm going to start there. I was going to pull down the latest CVS and start working on it when I thought it might be a good idea to clean out the old cruft in my /opt dir.
root# rm -rf /opt/*
And so /opt/gnome and /opt/kde are now history. (Oops! Who the heck put *Those* in there! Can someone tell me why on earth it wasn't in /usr/X11/* like the rest of X apps in the known universe? Better yet, why is vim linked against GTK? Isn't that suppoed to be able to run when they system is smashed?)
As I am wihout a desktop envionment, I'm forced to use the windows "lab box" as I scratch my head and figure out how to get Gnome 2 on my system. (I was running 1.4, I needed the upgrade anyway) This puts a bit of a kabosh on the documentation process. I was going to throw around a few formatting ideas (Of course, while not breaking the current formatting rules) I can be a bit verbose at times and wanted to bounce some ideas off of the group at large.
The second hurtle is what to put as theactual
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.
I was going to see what I can do to insert this into the code without creating these HUGE headers. Depending on the cosmetics however, it might me a good thing.
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.
I was only going to use MSDN as a simple cross-check. I enjoy writing with my own ten fingers. Cut and paste is out of the question.
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."
Typical (^_^)
A quick search on Google alludes to people writing man pages for Win32. This was on a NetBSD mailing list:
I'll have to research this when Naru's running at 100% again. If it's GPLed, I could expand on that.
Th only real issue I have is that some API fuctions can be pretty complex in thier execution. This could make for rather large function headers in the code. That's why, then things are normal again, I'll bouce some code snippits to the group before I kick a full blown patch to be accepted.
-Joshua
P.S. I'm on a really crapy mail client. The spell checker is a bit fruity and has been known to eat my corrispondance in the past. Please ignore the mild dislexia. I like to think of it as a gift that I can read backwards quicker than forewards.
I solved that problem by majoring in Japanese (^_^)