Re: 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
[e-mail]

Internally maintained end-to-end API documentation

[Joshua Walker]

--- "Brian Vincent (C)" 
wrote:
>

<snip>
> >   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".

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 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.

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 (^_^)