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

[Philippe C . D . Robert]

On Freitag, Oktober 11, 2002, at 11:18  Uhr, Matt Brandt wrote:
> 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.

Well, autodoc was/is pretty cool and the output was very profession 
looking. You could create TeX, HTML or TXT as far as I remember. Given 
that you can easily produce PDF form TeX, this really could be an 
option.

But I encourage you to have a look at the available options so that we 
use the Right Thing from start!

> 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 dunno ... TeX is pretty standard, at least in academic circles...:-)

But to summarise I would say:

- we need some generated API doc/ref
- we need a users' guide/programmers' guide which is based on the above
- we need a white paper describing the 3DKit, its goals, limitations 
etc.

The best would be to use a system which lets you create different 
output from the same source, ie. TeX, HTML or ASCII.

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

Then I'd prefer plain ASCII (or XML?) because content matters - and it 
can easily be turned into TeX, HTML or whatever else later on...:-)

-Phil
--
Philippe C.D. Robert
http://www.nice.ch/~phip