> On Thursday, June 22, 2000, Patrik Stridvall <[EMAIL PROTECTED]> wrote:
> > Then we have all the in code documention of the Windows API
> > that should be extracted and presented in an apropriate
> > format (DocBook?).
>
> We would probably have to do this by hand (I assume you're
> referring to
> all the inline comments about undocumented weirdness in Win32
> that Wine
> has to deal with).
Not only them, even though those is the most important.
I'm talking about documentation for _all_ Windows API:s.
So you simple can write:
man CreateWindowEx
and get the complete documentation about it.
Most important is of course information about Wine limitations
and behavior undocument in the Microsoft document, but it
should also everything else a developer need to know about the
function.
It is entirely possible that we will se a future where Windows
application are developed under Linux and WineLib and later
recompiled under Windows. But that is a post 1.0 item IMHO,
but any architecture we design now should keep that in mind.
> I think it makes sense to eventually incorporate
> these tidbits into the regular docs, rather than presenting them in a
> separate document.
We should of course do both. But your suggestion might be
realistic to do before 1.0.
> > Eventually they need to be man pages, can DocBook generate that?
>
> Well, being just a markup syntax DocBook can't generate anything.
Yes, I know. Poor choice of words. :-)
> The
> GTK+/GNOME project has a tool called db2man in their gtk-doc package:
>
> http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gtk-doc
Yes, that was what I was looking for.
> I have no idea how well-maintained it is, or how well it
> works, though.
> It's at least a starting point, though.
Indeed.
> > And we should not forget to write more in code documentatio,
> > eventhough I think we have to save that for post 1.0, to
> > many other more important things to do.
>
> Speaking of gtk-doc... GNOME & GTK+ use gtk-doc to translate
> their API
> reference documentation from inline comments in the source code into
> DocBook markup. Combined with some template glue files, gtk-doc can
> create a nicely formatted reference manual, with overview material,
> examples, and so on (most of the extra non-API stuff is
> pulled from the
> template files). Here's what it looks like:
>
> http://developer.gnome.org/doc/API/libgnomeui/book1.html
>
> While I'm not sure if we'd want to use gtk-doc as is, we could certainly
> learn some good tricks by studying the way gtk-doc handles things.
Probably.
> It
> does require some inline comments for each documented function, but such
> comments are already in place for the current Wine API doc-generation
> system, right?
Yes. The Wine variant is harder to parse, but I think it is worth it
since it looks nicer and is easier for a human to read IIRC.
> Anyway, food for thought.
Indeed.
