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

[Brent Gulanowski]

On Friday, October 11, 2002, at 05:18  PM, Matt Brandt wrote:

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

It's good because it means all of the changes get made in one place, 
and so it's more likely that the docs are in line with the code. I'm 
all for it, even if it seems a pain at first, once we're used to it, 
we'll be glad for it. It will certainly increase the usefulness of 
3DKit. HeaderDoc, like JavaDoc, produces HTML -- you can use HTML 
formatting of your own, too. It's pretty sensible, since the output is 
immediately ready for the web.
> 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.

Even the term "TeX" is too geeky for me. And I'm pretty geeky 
sometimes. I think we're feeling the GNU purism vs. vox populi strain a 
bit 8^). Anyway, TeX seems to be great for doing mathematical formulae, 
but what else does it have to offer? Layout is nice for book design, 
but we just want something readable and navigable, and HTML should 
suffice.
> > 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.

Speaking of wysiwyg HTML and free software, is there such a beast that 
combines those two features?

--
Brent Gulanowski                                address@hidden

"Of course the Universe hates you. You're working to reduce chaos by 
expending a lot of energy to do your job. Thus, you're contributing to 
the eventual heat death of the universe, and it's just protecting 
itself from you."               -- John Batzel