I thought this was moving over to gpc-doc? Should I send my postings which I've held back until sorting a hiccup registering for gpc-doc here instead? (more below)
At 1:30 AM -0600 30/1/03, Richard D. Jackson wrote:
On Tue, 2003-01-28 at 22:41, Frank Heckenbach wrote:
Richard D. Jackson wrote:
[snip]
What I envioson is more of a tag syntax verses a complete layout system. By tag I mean something that indicates that something is: Author name Module version copyright notice description return type/description ( may or may not need this ) paramiter code example header ( by this I mean module header or description ) referance index this for later cross referance ect... But not a whole lot of stuff. Leave formating and structure up to the output code. This is how POD, JavaDoc ( core stuff that is ) and a few others do. That way if you don't like the output you can write your own output generator that will format it the way you want. Core Doxygen does this as well but becasue the backend dictates the output form/layout it has had many output generaters created for it. But I think its down fall is that it does allow the programmer to use or embed form/layout stuff for specific output generaters which means the programmer spends can spend too much time trying to do some special form/layout verses just writing the doc. POD on the other had basicly has taken the stance that this is all you get and if you don't like it write your own output module to get what you want. This means that it has sacrificed flexablity for conformance to a standard. And do you know something Perl code is some of the best documented code out there. Which is why I want to follow the perl lead but mostlikly not the format itself. Mostly becase POD does contain some format/layout command in it as well. I really don't want to worry about format/layout when I document code.
What I intend to do before writing any code is to write a specification which I will run by here for comments before writing any code. As I would rather have input and some kind of agrement that it is what we want.
Sounds as if we have been thinking along similar lines. I have my own with notes somewhere on my system...
I agree with leaving formatting to later. You could generate XML and then downstream users could use CSS for layout, for example.
Don't include format per se, but include some style class information like 'header' 'text' etc so that it can be appropriately formatted later.
[big snip; us documentation types write a bit... :-) !]
First the question I would have is what is the target application of the documenter? If for only documenting single monolithic units then a single pass ( single file ) tool would do the job. But on the other hand if you want to handle multi-module/unit applications that need to beable to cross link the documention and or have a unified cross-referance amogst all the code modules then what you really want to do is process all of the files in a single pass. And for doing this OOP will be very helpfull. One other thing I would like for it to do besides output the documentation is to output a cross referance list so that other modules can referance the doc if needed. For instance lets say I'm writing a string utility unit wouldn't it be nice if I could referance the RTS with in my doc's and actualy have a working link to the RTS doc for a paricular function/procedure verses something like this " see these functions in the RTS documentation ....."
Its a good point, but I think processing all the files in a single pass has exactly the same flaw as compiling code in the same fashion. The interface/implementation approach was developed for that reason. I have some thoughts about this, but perhaps they make the doc application too complex for an initial version, so I'll hold off for now.
Grant