On Mon, 2003-01-27 at 20:04, Frank Heckenbach wrote: <big snip>
Again I agree with you. I have only been able to find pasdoc but it was wrote for delphi/kylix/fpc which means the code may not be portable to gpc. It also has not been touched in a couple of years. I grabed a copy of the source and am going to take a look at getting it ported to gpc and add some things to it. For instance right now it will output HTML and Texi. The HTML part is OK but I will need to work on the Texi part and change it to texinfo as that is what is being used for gpc.
I've made some plans for such a utility, in particular some features required, and some ideas for the syntax.
My main goal would be (unlike some -- I don't know if all -- of the other utilities), to have the syntax as simple and readable as possible, e.g. to use paired quotes (like `foo') for markup (which would be @samp{foo} in texi). The purpose would explicitely *not* be to have a complete layout system (such as TeX; I think already texi is not), but to focus on the common things. (There can always be an escape mode for the occasional exception.)
In the end, the existing comments in the unit interfaces, where they exists, should be accepted with few modifications, and the output should replace the interface copies in p/doc/generated.
If there is some real interest, I could write my ideas (which now are just some random notes).
pasdoc, the tool I'm looking at was modeled after javadoc syntax. I personaly prefer more of a perl POD type syntax. Other words I would prefer to keep it simple. complex stuff just ends up not being used. the simple stuff that works gets used.
And yes I would love to see what your ideas are. As I would really prefer to know what everyone wants before starting to work on it. I would hate to spend the time to write something that no one but myself would use when there are others that would use it if only I had spent a little extra effort to get their input up front.
I may actualy just end up rewriting it from scratch as it is using quite a few custom class that duplicate units gpc already has and I would prefer to use the ones gpc provides verses costom ones.
BTW, I don't quite see where such a utility would need classes and collections and all that stuff at all, but then, I'm only a moderate OOP follower ...
OOP would make some things easer to do. For instance in the case of pasdoc it creates a document class that handles all of the parsing of the source files. Then a output class is pluged into the doc class to make the finished docs. Yes you can do something simular with out using OOP but OOP provides a more eligant solution to the problem. It also makes it easy to plug new output backends in with out affecting the main body of code.