Re: [Gnu3dkit-dev] White Paper and API reference

[Matt Brandt]

On Friday, October 11, 2002, at 09:44 AM, Philippe C.D. Robert wrote:

> Hi,
>
> the point here is that the API reference has to be *generated*. 
> Otherwise one cannot keep it in sync, that's reality. So the way it 
> works is that API documentation is added to the header file, which is 
> then parsed by ie. HeaderDoc or AutoDoc to generate the reference. I 
> don't think the output quality is thereby worse than with Word - you 
> can generate TeX, HTML or whatever

While having "generated" documentation is nice in theory, I've never 
seen a generator that didn't require significant reformatting of the 
output to get something I would want to read. I'll be happy to check 
out a few of these though, and see if one of them is adequate for our 
purposes. The point really is to end up with accurate and usable 
documentation, not to produce non-functional art, so it is probably 
worth investigating.

As for TexShop, I downloaded it and tried it out. I wasn't familiar 
with Tex before. Wow, real geekware. I used to use troff back in the 
dim times but I didn't think anyone still used this kind of thing :-) I 
don't mind exerting the effort (and a few bucks to get a book) to learn 
how to use it effectively, but I think we may be limiting ourselves in 
terms of quickly bringing anyone new into the documentation project in 
the future if we use this kind of tool.

> I will not consider using Frame nor Word because they are proprietary, 
> incl. their format. Not anyone has Word or Frame, but anyone should be 
> able to contribute!

Point taken. I would like to make it easy for anyone to edit our stuff 
too. How about if we make the standard documentation format HTML and 
not worry about how it is produced? That way the wysiwyg crowd can use 
any number of editors and still produce files that can be edited by 
nearly anything. It also gives us a shortcut to an online manual.

Matt