Well I've spent some time to learn texinfo. Well I should say I've gone over it and think I understand how it works that is.
Anyways there are a few things I want to achive before working on pas2texi. They are in order:
1) A sample of expected output from the program. This will serve as a guide when I start to code. It will also let us agree on what that output should be.
2) A some what complete manual for the program. Again this will serve as a guide when I start to code. It will also allow us argue and or discuss the implementation details.
3) Start coding.
So as a start here is an initial draft of what I think the output should be. It is the texinfo source that you can use makeinfo to transform into info/html.
So after you have had a chance to look at it lets talk about it and revise it to fit what we want as far as output goes that is.
Richard
Richard D. Jackson wrote:
Well I've spent some time to learn texinfo. Well I should say I've gone over it and think I understand how it works that is.
I think that's enough for most purposes. :-)
Anyways there are a few things I want to achive before working on pas2texi. They are in order:
- A sample of expected output from the program. This will serve as a
guide when I start to code. It will also let us agree on what that output should be.
So as a start here is an initial draft of what I think the output should be. It is the texinfo source that you can use makeinfo to transform into info/html.
So after you have had a chance to look at it lets talk about it and revise it to fit what we want as far as output goes that is.
: * GPC RTS: (rts). GNU Pascal Runtime Library.
We usually call it "Runtime System". But that's not a matter of the program -- it will get it from the input data.
: @author Frank Heckenbach @email{frank@@pascal.gnu.de}
And some more. I'm the only one listed in the file gpc.pas since I wrote this file alone, but the actual implementation was written by many others as well. (That's a special case since usually a unit contains its implementation while gpc.pas is a purely external interface module.) I guess I should simply list all authors in gpc.pas then (will do in the next release) ...
: @c ***************************************************************************** : @c =============[ Main menu ]=================================================== : @c *****************************************************************************
I'm not really a friend of such "bold ASCII headers" -- and in an automatically generated file they're not necessary for an author to orientate. But then again, in an automatically generated file they also don't disturb anyone ...
: * Variables:: Variables, Constants, and types exported by the : Runtime system.
I think those variables, constants and types declared in the sections below should be documented there, so I'd rather call this initial section something like "Misc". But again, this must be done in gpc.pas and should not affect the program, so I don't mind ...
(Of course, it's also useful to have a list of all constants etc., but that's already served for by the indices.)
: @node Top : @top GNU Pascal Runtime System (GPC) : : [...] : : @chapter Variables
BTW, the program should have options to shift down the whole hierarchy one or two levels, e.g. put the main menu in a section and the other nodes in sub- and subsubsections, for inclusion into other texts. (In this case, of course, the texi header and title page would be omitted and the copyright notice inserted only in the main menu node.)
: @table @code : : @item MaxLongInt : @conindex MaxLontInt : @table @asis : @item Declared As : @code{MaxLongInt = High (LongInt);}
(I'd add `const' here.)
: @item Description : The maximum value a @code{LongInt} can be. : @end table : : @item MaxVarSize : @conindex MaxVarSize : @table @asis : @item Declared As : @code{MaxVarSize = MaxInt div 8;} : @item Description : Maximum size of a variable. : @end table : : @end table
: @subheading Synopsis : @verbatim : uses GPC; : function SinH (x: Real): Real; : @end verbatim : @subheading Description : The @code{SinH(x)} function returns the hyperbolic sine of x, which is defined : mathematically as (exp(x) - exp(-x)) / 2. : @subheading Example : under construction : @subheading See Also : @xref{Hyperbolic Functions, libc sinh, , libc},
Why use different formatting for constants/variables and routines? I.e., why not use `Synopsis', and subheadings instead of the table for the former as well?
Frank
Excuse my being frustrated. I am trying damn hard to get GPC (2.1 (20020510), based on gcc-2.95.3 20010315 (release)) to compile a Pascal program I wrote some time ago but keep running it things I can't make sense of. Maybe I'm being unfair, but I'll give you the whole story just in case its something new. The latest issue I'm having is a run of type vs. identifier conflict errors of the form:
./GHJ_AARegions.pas:49: type name expected, identifier `Fnames' given ./GHJ_AARegions.pas:49: warning: missing type in declaration of `Infname' ./GHJ_AARegions.pas:54: warning: parameter has incomplete type
My trouble was fnames *is* a type. It is *only* defined as a type. So how the heck does the compiler come away thinking that its an identifier?????
I eventually resolved this by directly 'using' modules, rather than rely on the hierarchy (read on).
When this error occurred the GHJ_AARegions unit uses GHJFnames. GHJFnames in turn uses GHJFiles, which is where the type fnames is defined. (Really these two levels need to be the other way around, but this is a legacy program I am porting, so I have to deal with that after the port.)
Since these uses statements were within the interface section, I presumed the definitions would propagate upwards so that they form a hierarchy. Or, put another way, I assumed the interface of a unit is extended by any units it uses in its interface section.
Originally, I had:
unit GHJ_AARegions ;
{ Holds routines for dealing with the region indicies. }
interface
uses GHJStdDefs, GHJStdMaths { for inrange() }, GHJttInterface { for press_return() }, {GHJTextIO} { for skip_aa_comments() } {,} GHJStrings { for get_string8() }, {=>} GHJFnames { for get_fname() }, GHJ_AAErrors, GHJ_AAUtils, GHJ_AAGlobalUnit ;
By getting GHJ_AARegions to explicitly, directly, use GHJFiles, the compiler stopped complaining. ie. I changed the above code to:
unit GHJ_AARegions ;
{ Holds routines for dealing with the region indicies. }
interface
uses GHJStdDefs, GHJStdMaths { for inrange() }, GHJttInterface { for press_return() }, {GHJTextIO} { for skip_aa_comments() } {,} GHJStrings { for get_string8() }, {=>} GHJFiles, GHJFnames { for get_fname() }, GHJ_AAErrors, GHJ_AAUtils, GHJ_AAGlobalUnit ;
{=>} points out the offending line of source. If this is truly the problem, then I presume there is no way of building a hierarchy of units in GPC at present? (In this case my safest strategy is to have every unit uses *all* the lower units directly, "just in case". Or put, another way, I might just as well use includes to make everything one big flat program. Sorry, but I *am* frustrated!)
Three thoughts:
1. This is the correct behaviour?: surely I should be able to use a higher-level module and have all the lower-level modules definitions within that higher-level module "gotten" at the same time without have to explicitly duck behind the scenes and drag out each module??? Excuse me for asking this, but its not terribly clear from the docs, at least on my reading of it.
2. Why the heck does the compiler report the message it does? "Missing type fnames" perhaps, but since fnames is only ever defined as a type and never as an identifier, it shouldn't be able to report the message it did...
3. Is there any chance you can tell the user where the "identifier" (see the error message) is defined so that in future users might have chance of trying to second-guess just what the compiler is "thinking"?
Sorry I can't provide a full code example: I am porting a largish program (approx. 60,000 lines of sources in a dozen or so modules) and in any event I can't understand the problem well enough to create an example - catch-22...
Looking at the known bugs for ver. 2.1 there are a couple that might be relevant, esp."Types declared in a module interface are not visible in the implementation" (but does this refer to the same module's interface section and how are units and modules related with reference to this?)
While I'm writing, is there any chance you can make the compiler keep trying after one unit has failed, rather than stopping at that point? It seems that if there is even one error in a unit, the compilation is abandoned at the end of that unit.
(Now to try figure out how GPC claims a type-mismatch on something that is definitely the same type and the type is only defined in one place... probably the same issue, we'll see...)
Grant
At 12:24 PM +1300 28/2/03, Grant Jacobs wrote:
Excuse my being frustrated. I am trying damn hard to get GPC (2.1
Whoops, wrong group, sorry... gpc@ and gpc-doc@ are rather similar if you're in a hurry! I'll try again... ignore my last post.
Grant
-
Frank Heckenbach -
Grant Jacobs -
Richard D. Jackson