On Thursday, June 22, 2000, Patrik Stridvall <[EMAIL PROTECTED]> wrote:
>
> Well, that is a problem for everything except pure text.
> I'm more intrested in specific DocBook problems.
I'll try to come up with some more DocBook-specific limitations.
> 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). I think it makes sense to eventually incorporate
these tidbits into the regular docs, rather than presenting them in a
separate document.
> Eventually they need to be man pages, can DocBook generate that?
Well, being just a markup syntax DocBook can't generate anything. 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
I have no idea how well-maintained it is, or how well it works, though.
It's at least a starting point, though.
> 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. 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?
Anyway, food for thought.
John
--
[EMAIL PROTECTED] http://www.gnome.org
[EMAIL PROTECTED] http://www.worldforge.org
