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

[Brent Gulanowski]

On Friday, October 11, 2002, at 01:51  AM, Philippe C.D. Robert wrote:

> Hi,
>
> I prefer TeX for nice looking documents. If we decide to go with that 
> (using ie. the free, excellent TeXShop on Mac OS X), I could also 
> upload the appropriate files of my early programmers' guide which 
> could be turned into a white paper/documentation. What do you think?

I have not use TeX but I am interested in it. I will locate TeXShop and 
give it a whirl. I have past experience with numerous word processors 
and page layout applications, and don't expect it would be hard to 
learn another system.

On Friday, October 11, 2002, at 09:15  AM, Matt Brandt wrote:

> I'm more of a Frame and Word kind of guy. It's been a long time since 
> I've used Tex, but I'll take a look before starting anything. I also 
> haven't tried the headerdoc stuff, but I think a word processor would 
> turn out a nicer product in general. I also have inDesign, Appleworks 
> (yuk), and ThinkFree. There is probably a good solution in there 
> somewhere. If Frame was OS X native, it would be an easy decision, but 
> as it is I have to run it under Classic (ugh!).

I have not heard of Frame, either, unless you mean Frame Maker. On OS 
X, no matter what we use, we can always generate PDFs. I love that. I 
use Word for documents, but I hate it. I'm going to try OmniOutliner 
one of these days and see if it can do better.

On Friday, October 11, 2002, at 10:44  AM, Philippe C.D. Robert wrote:
> 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.
>
> 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!

Yes, I second both points, now that you mention them. And this doesn't 
contradict my essential philosophy of document preparation: produced 
the content first, and format it after. Granted sometimes you need 
structure as you produce, but the headers themselves provide the 
structure for the API documentation, and the parser will preserve that. 
The programmer's guide probably doesn't need much structure, or at any 
rate it would be more naturally evolved, not imposed.

I suggest preparing the programmer's guide in .rtf or .rtfd, if the 
latter is supported by any GNU or Linux apps. Does anyone know?
> And remember, the GNU 3DKit is a GNU project...:-)

If we want to be really strict I could produce the programmer's guide 
in XEmacs :-). Please, no!
> WRT the generated API reference, what tool should we use? Is Apple's 
> HeaderDoc finally able to handle Objective-C?

It seems to be fine. What did Apple use for their class reference if 
not HeaderDoc? See:

http://developer.apple.com/darwin/projects/headerdoc/docs/ObjCTags.html

Another thing to download.
--
Brent Gulanowski                                address@hidden

Pluto Neptune Uranus Saturn Jupiter Mars Earth Venus Mercury Sun
  .      o      o      o      O      .     .     .      .    /\
                                           ^                 \/
                             You are here _|