On Mon, 2003-01-27 at 03:36, Grant Jacobs wrote:
A few observations from trying out gpc (Linux).
<snip>
- While I appreciate the effort that has been made, personally, I
don't consider projects complete until the docs have been written... it seems to me much of the doc. at present is just a shell, full of '(Under construction)'! It would make a huge difference if some of the people who know how things are supposed to be filled in the odd gap...
I couldn't agree with you more.
Where is the original (text) document format? Is it the HTML format? I might try poke the odd bit in myself.
It is in texinfo format in the ./p/doc/[lang] directory. also it seems some of the doc is generated as well.
Can I suggest that a scheme allowing user's to add comments/observations to the docs be made so that at least some information gets into the docs. while the implementors have their minds elsewhere? Perhaps add some keyword to indicate that this item/section has been written by a user rather than implementor? For example perhaps bracketing the text in the spirit of the way that XML does, so that the reader can easily identify which bits have been contributed by users and thus while probably true need to be taken with a little salt :-)
Alternatively add another section "user's observations" or some such to the description of each element.
It might also prove a useful reference of when user's experiences are at odds with the implementors intentions while a bug fix is pending.
A gpc wiki would fit the bill for such a setup.
Really the implementors ought to be using something like HeaderDoc or whatever and write these descriptions as they code... just a thought...
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 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.
Richard