[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Brent Gulanowski
Subject: Re: [Gnu3dkit-dev] White Paper and API reference
Date: Fri, 11 Oct 2002 11:06:00 -0400

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


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:

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]