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).
- --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.)
- 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.
- 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?
- 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]
- 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
Grant Jacobs wrote:
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.
OK, I think I can do that -- to add an input form at the bottom of each page, so anything entered there will appear on the page (just above the input form I guess) marked as user notes, and is sent to me so I can put it into the main documentation if it's alright. Is that what you mean?
I'm still skeptical how much it will gain us in the end, but since there's not much to lose, I'll try it (with the next update) ...
Frank
At 11:03 PM +0100 30/1/03, Frank Heckenbach wrote:
Grant Jacobs wrote:
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.
OK, I think I can do that -- to add an input form at the bottom of each page, so anything entered there will appear on the page (just above the input form I guess) marked as user notes, and is sent to me so I can put it into the main documentation if it's alright. Is that what you mean?
I was thinking more of a field like the ones already there. E.g. You have for each item synopsis, description ... see also.
I was thinking after 'see also' add 'User's observations' (or some-such)
This way their observations are tied to each element, rather the bottom of each page. Let that field be added to by users as they see fit. Periodically spring-clean shifting bits that look OK to the main ("certified" :-) ) part of the docs.
Its a little awkward, but ideally you'd have a section like this after every section in the docs. You could filter the docs so that empty User observation sections are stripped (outside the appendix listings of the keywords, that is; these probably should have a fixed format as they do now so its easier for a reader to spot missing stuff) before making the PDFs, etc.
So, say I want to add some of my own observations to '3.4.6 What about C strings', I can submit/add to a 3.4.6U (of sorts), which will appear under 'User observations' (or whatever) in that section. Later these can be integrated if they are deemed OK, or possibly junked if they can be contradicted.
Would this be too difficult? Or am I too confusing :-)
I'm still skeptical how much it will gain us in the end, but since there's not much to lose, I'll try it (with the next update) ...
You gotta try!! If there is an easy route for people to add their bits they are more likely to do it - we hope...
Grant
Grant Jacobs wrote:
OK, I think I can do that -- to add an input form at the bottom of each page, so anything entered there will appear on the page (just above the input form I guess) marked as user notes, and is sent to me so I can put it into the main documentation if it's alright. Is that what you mean?
I was thinking more of a field like the ones already there. E.g. You have for each item synopsis, description ... see also.
I was thinking after 'see also' add 'User's observations' (or some-such)
This way their observations are tied to each element, rather the bottom of each page. Let that field be added to by users as they see fit. Periodically spring-clean shifting bits that look OK to the main ("certified" :-) ) part of the docs.
Perhaps we mean the same thing. By page I meant HTML pages, not printed pages in the PS/PDF version, and in HTML, each routine etc. has its own page. (Or do you actually mean one input field for synopsis, one for description, etc.? I think that would be too much.)
I've now set up a test version of the GPC pages with the input forms as I understand them at http://www.gnu-pascal.de/test-input/. (Some links may not work correctly, or point to the original page, but this is only a demo.) This way has the advantage that it was relatively easy to set up, and it can be applied to basically any HTML page.
Let me know what you think of it.
Frank
At 5:00 AM +0100 3/2/03, Frank Heckenbach wrote:
Grant Jacobs wrote:
OK, I think I can do that -- to add an input form at the bottom of each page, so anything entered there will appear on the page (just above the input form I guess) marked as user notes, and is sent to me so I can put it into the main documentation if it's alright. Is that what you mean?
I was thinking more of a field like the ones already there. E.g. You have for each item synopsis, description ... see also.
I was thinking after 'see also' add 'User's observations' (or some-such)
This way their observations are tied to each element, rather the bottom of each page. Let that field be added to by users as they see fit. Periodically spring-clean shifting bits that look OK to the main ("certified" :-) ) part of the docs.
Perhaps we mean the same thing. By page I meant HTML pages, not printed pages in the PS/PDF version, and in HTML, each routine etc. has its own page. (Or do you actually mean one input field for synopsis, one for description, etc.? I think that would be too much.)
Right, we did get confused on the word page! Its like me trying not to use the word client in case my prospective customers think I'm referring to them instead of the client in the client-server stuff...
What I was thinking was that 'User observations' would appear as the last keyword/section in each portion of the resulting documentation.
I've now set up a test version of the GPC pages with the input forms as I understand them at http://www.gnu-pascal.de/test-input/. (Some links may not work correctly, or point to the original page, but this is only a demo.) This way has the advantage that it was relatively easy to set up, and it can be applied to basically any HTML page.
Let me know what you think of it.
You're way ahead of me :-) This is very nice! Its a wonder other projects don't do something this. (Do they?) Now I guess we (you!) get to sit back and if anything happens.
Grant
Grant Jacobs wrote:
I've now set up a test version of the GPC pages with the input forms as I understand them at http://www.gnu-pascal.de/test-input/. (Some links may not work correctly, or point to the original page, but this is only a demo.) This way has the advantage that it was relatively easy to set up, and it can be applied to basically any HTML page.
Let me know what you think of it.
You're way ahead of me :-) This is very nice! Its a wonder other projects don't do something this. (Do they?)
I haven't seen this before. This is just what came to my mind when I read your mails, and it was surprisingly easy to implement.
Now I guess we (you!) get to sit back and if anything happens.
As soon as it's on the official pages. I'll do that with the next update (perhaps next week). Until then, it would be nice of some of you could test it to make sure it basically works ...
Frank
-
Frank Heckenbach -
Grant Jacobs -
Grant Jacobs