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

[Philippe C . D . Robert]

On Freitag, Oktober 11, 2002, at 11:46  Uhr, Brent Gulanowski wrote:
> 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.

Exactly my point!...:-)

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

Hehe ... or Mac vs. Unix culture ...:-) Anyway, my point here is that 
we should use sth which follows the following rules:

- everyone is able to contribute
- it is easy to use
- it allows the 'conversion' to TeX, PDF, HTML or XML via a 
filter/converter

Did I forget something ?

I therefore suggest

- for API documentation we use autodoc, autogsdoc or HeaderDoc
- for the white paper and documentation guides we use either XML or 
plain text.

What do you think?

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

I dunno, I am not a HTML guy...:-)

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