Grant Jacobs wrote:
A few observations from trying out gpc (Linux).
- --interface-only -c doesn't (always) produce a .o as the docs
say,
Where does it say so? Oh, you mean in the `-c' description. OK, the `--interface-only' description should make it clearer that it overrides `-c' in this regard. (To me, "compiling the interface" is clear enough to mean producing only a gpi file, but probably not to everyone ... ;-)
but rather only a .gpi (and a .gpm in the case of modules), at least in my case.
I think that's reasonable behaviour, and the docs should be adjusted.
Either that, or its placing the object files somewhere else on my system! In turn, this seems to block me from compiling with units or modules unless I use --autobuild on the main program to force the issue, so to speak.
Maybe you misunderstand the purpose of the option. It means to process only the interface part of a unit/module. Of course, you generally don't get a complete program without the implementation.
`--interface-only' is only useful (necessary) in situations with circular unit/module dependencies, e.g., A's interface uses B, and B's implementation uses A. The only way to compile this is to first compile B with `--interface-only', then A and B again without the option.
- The blocksize parameter to reset() appears not to be optional (as
the doc says it is)
: Reset : : Like @samp{Rewrite}, @samp{Append} and @samp{Extend} do, : @samp{Reset} accepts an optional second and third parameter for the : name of the file in the filesystem and, for untyped files, the block : size of the file. (For details, see @ref{Rewrite}.)
: Rewrite : : The last optional parameter determines the block size of the file. : It is valid only for untyped files. Almost always, 1 is the most : reasonable value here. However, the existence of this parameter is a : BP compatibility feature, and in BP it defaults to 128 because of : historic misdesign. Therefore, GPC requires this parameter to be : present. In @samp{--borland-pascal} mode, it makes it optional (like : BP does), but warns about the strange default if omitted.
I admit, it could have been made a little clearer ;-), and if you or someone wants to help on the documentation, that's always welcome.
if the file is untyped. It'd be nice if there was a 'silent default' so that existing programs work 'as is'. For example reset( infile, infname ) ; gives a syntax error and demands that a buffer size be added.
Yes, it's be nice, but BP stands in the way, as noted above. (AFAIK, the misdesign goes back to UCSD Pascal and the CPM file system ...) I think it would be too confusing to have two different silent defaults, depending on the dialect option.
The only thing I could possibly imagine would be to make the difference clear in some other way, e.g. to have the file declared as `file of Void' or so (with a default of 1), whereas a simple `file' (as in BP) behaves as it does now.
- One of my enumerated types contains 'property' and 'operator'
which prove to be GPC reserved words of some sort as the compiler throws up a syntax error. I don't really want to have to alter these... are these keywords part of some new standard?
`property' is from Delphi, `operator' from PXSC.
Generally, if you don't want any extensions (which include a few new keywords, of course), try `--extended-pascal'.
The next GPC will also support `--disable-keyword=property,operator' (or `{$disable-keyword=property operator}' in the source).
- It'd be nice to sort the command-line options. They are hard to
locate as they are without trawling through the whole list.
OTOH, they are (somewhat) sorted by topic now.
Well, we could have one list as it is now, and another one in alphabetic order with the same information.
Since the list is generated automatically, this should be rather easy to do. But would it help, or be more confusing?
- The index on the left of the PDF format seems to always "point" to
immediately _after_ the item, rather than to the item (minor quibble).
This might be a problem in texinfo.tex. In the texi source, the index items are defined as `@cindex'. If they're put before the start of a "node", the index in Info gets wrong (points to the previous node). So they have to be put after it, as is done now, which apparently causes this behaviour in TeX. We could report it and hope that someone will fix it ...
- While I appreciate the effort that has been made, personally, I
don't consider projects complete until the docs have been written...
I don't think anyone would consider GPC complete in any way. ;-)
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.
Yep -- for the units, that's currently just a copy of their interface part, and some other information (list of options and keywords) is extracted from the compiler sources.
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.
I'm somewhat skeptical. There have been a number of other suggestions over the years to address the "formal issues", but in many cases, the potential contributors lost interest or had no time to spend shortly after (or even before) the formalities had been settled.
In the end, it really comes down to the fact that someone has to write the stuff ...
Actually, it's not a big issue for me to apply documentation changes I get (and to review them for serious mistakes) -- a simple patch sent to me or the gpc-doc list will do. I've been getting some up to now -- but unfortunately too sporadic and by far not enough to really cover the holes ...
So I suggest to focus on the content first, not on the formalities. Of course, if there are several contributors you might want to agree on the areas you work on to avoid overlaps (though the chances are small, given the number of holes) ...
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'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).
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 ...
Frank