Shifting this thread over from gpc@gnu.de... (excuse the length of this)

At 3:04 AM +0100 28/1/03, Frank Heckenbach wrote:

Grant Jacobs wrote:

...

A few observations from trying out gpc (Linux).

1. --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 ... ;-)

If you try use --interface-only on its own, the compiler stops and says you must use either -c or -S with it. So I presumed (always a bad thing to do!) after reading the -c description that your interface modules are stored as object files. (see below, also)

...

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.

Yes, I agree the behaviour is OK; Its the docs that need attending to! I wasn't actually meaning to complain about the behaviour.

...

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.

I sort-of got this right the first time around ;-)

The reason I went astray, was that I expected that compiling a unit would produce an object file, which would later be linked in when the main was compiled. In practice, none of the units I've tried compile fully on their own. You get complaints about undefined main, etc., which lead me to thinking that there much be some sort of compiler switch that'd tell it to not look for / create a main function, just create an object file 9library if that suits you better) to later be linked to a main program. That, in turn, lead me to fiddling around with different options. Which... you get the drift, anyway.

This is why a description of how to compile units/modules would have helped... I suppose there is something down in the description of generation of .gpi/.gpm files that might have caused the penny to drop. But currently there appears to be nothing explicit says how its supposed to work.

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

This paragraph ought to be inserted into the docs in the --interface-only description! (Nicely, worded - thanks.)

...

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

I read the reset docs, not rewrite. I might tweak the docs at some stage.

...

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.

But how about an explicit default by the user from the command-line? Easier than fiddling with their code (not that that's a terribly to do in this case)... low priority... its solvable if faintly irritating. if it was C, I'd use a macro to solve this, FWIW.

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.

Or redefine type File, doing which, err, must raise its own issues...

type file = file of void ; {or} file = file[1] ; { ie file[<bufsize] }

{or assigning it, a la OOP in an initialisation section } file.bufsize = 1 ;

Hmm. Getting a bit fanciful, perhaps. What I'm trying to do is to tie the buffer size with the file handle, which does makes some sense. I suspect fewe users would vary the buffer size from one reset/rewrite to another, so in principle it could be associated with the file for most folk. But I can see the merits of sometimes needing to altering it.

...

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

Grr. Any ideas on how long its going to take for this to appear?

I got the vague idea that part of the strategy of GPC was to allow keywords to be redefined so that older code won't bump into keywords from newer/different implementations of Pascal. So this isn't really in place yet?

...

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

But no topic headings... yet ;-)

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?

Hmm. Both, but in my ideal world (!) I'd lay out the docs. in a different way. To me the best indexing/reference scheme I have seen is in 'Web Design in a Nutshell' (O'Reilly). I wish O'Reilly would use it in their other books. The index (or appendix) has the keywords in alphabetical order, referring you to an appendix with brief synopses of the keywords in alphabetical order. These, in turn, refer you to a complete synopsis at the head of a chapter. If you still can't remember how to use the thing, you're conveniently at the start of the chapter that covers that subject area needed to (re)learn it.

The beauty of this is that it can be read either front-to-back or as a reference via the index/appendices without either disrupting the use of the other.

For example, <frameset> in the index, points to p473, which contains

<frameset> Chapter 11, page 207 ------------------------------------------------- Description: Frameset Attributes: border bordercolour cols frameborder framespacing ...

Page 207 has the full synopsis, with standards support and short descriptions of the keyword's functions, eg:

<frameset> NN: 2,3,4 - MSIE: 3,4,5 - HTML 4 - WebTV - Opera3 ------------------------------------------------------------------------ <frameset> ... </frameset>

Defines a collection of frames or other framesets

Attributes

border=number Sets frame border thickness (in pixels) ... ...

If you're _still_ stuck, you read the chapter that follows.

There is a nice hierarchy that you traverse, stopping when you've reached the level you need. If you're learning, you read from the front.

This looks like a lot of work, but if done from HeaderDoc or the like, it might be possible to automate much of this straight from descriptions in the source code.

Besides, we could aim to write our own O'Reilly Nutshell book :-) JK! And I really mean JK!

[snip]

...

6. 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. ;-)

I know, but... :-)

[snip]

...

...

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.

What I'm suggesting is a little different. Provide a framework within the docs that users can add their own observations to, but one that such that readers can see that its a user contribution. Then users can add as little or much as they like.

You'd occasionally want an editor to run over the whole thing and make it more consistent. (Or have two versions of the docs - last edited version and the free-for-all version)

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

If you can get the automatic docs out in some format, have a field 'user notes' or whatever present. Let the users add to that. You can then receive contrib.s as diffs or simply merge the new and old docs.

So I suggest to focus on the content first, not on the formalities.

I agree. Fits with what I see as the pragmatic nature of GPC. The user notes can help in this respect.

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

:-)

I'd just have people submit their bits "without delay" so we'd discover that soon enough before they built up too much of a head of steam... :-) Lazier than some formal coordination scheme!

...

...

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.

I've been working on something along these lines myself. (I'm very slowly working towards writing my very own little language, which will probably have an audience of one, ie. me!)

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

I agree: the learning curve needs to be small.

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'd be interested to see how our ideas compare. I'm working in C, but trying to make it language-independent in a simplistic way.

...

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.

I know what you mean :-)

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

-- Frank Heckenbach, frank@g-n-u.de, http://fjf.gnu.de/, 7977168E GPC To-Do list, latest features, fixed bugs: http://www.gnu-pascal.de/todo.html GPC download signing key: 51FF C1F0 1A77 C6C2 4482 4DDC 117A 9773 7F88 1707