Re: ada/9406: Documentation suggestion

Re: ada/9406: Documentation suggestion

[Geert Bosch]

The following reply was made to PR ada/9406; it has been noted by GNATS.

From: Geert Bosch <bosch@gnat.com>
To: Simon Wright <simon@pushface.org>
Cc: bosch@gcc.gnu.org, bje@gcc.gnu.org, gcc-bugs@gcc.gnu.org,
	gcc-prs@gcc.gnu.org, gcc-gnats@gcc.gnu.org
Subject: Re: ada/9406: Documentation suggestion
Date: Thu, 20 Feb 2003 17:38:13 -0500

 On Thursday, Feb 20, 2003, at 16:35 America/New_York, Simon Wright 
 wrote:
 
 > You are of course entirely welcome to reject the suggested
 > rewording. However,
 >
 > (a) the first part of the patch corrected a grammatical error.
 Yes, I added to my initial reply that of course the grammar
 change was OK to apply.
 
 > My suggestion was to say "run the Ada binder on the Ada entry units"
 > but I suppose you could be all formal and say "run the Ada binder on
 > all the Ada units that contain subprograms that are called directly or
 > indirectly by the non-Ada main program". I think I would have
 > understood the former better. I certainly didn't understand the
 > present wording!
 >
 > (by the way, what about non-subprogram entities such as variables?)
 
 Actually, your "all formal" version shows some misunderstanding:
 you do not need to specify Ada units that are called indirectly
 by the non-Ada main program.
 
 Probably you are most helped by this quote from the Ada reference
 manual, 10.2(5):
 
       A partition is a program or part of a program that
       can be invoked from outside the Ada implementation.
       For example, on many systems, a partition might be
       an executable file generated by the system linker.
       The user can explicitly assign library units to a
       partition. The assignment is done in an implementation-
       defined manner. The compilation units included in
       a partition are those of the explicitly assigned
       library units, as well as other compilation units
       needed by those library units.
 
 This should also address your question about variables.
 
    -Geert
 

Re: ada/9406: Documentation suggestion

[Ben Elliston]

The following reply was made to PR ada/9406; it has been noted by GNATS.

From: Ben Elliston <bje@redhat.com>
To: Geert Bosch <bosch@gnat.com>
Cc: Simon Wright <simon@pushface.org>, bosch@gcc.gnu.org, gcc-bugs@gcc.gnu.org,
   gcc-prs@gcc.gnu.org, gcc-gnats@gcc.gnu.org
Subject: Re: ada/9406: Documentation suggestion
Date: 28 Feb 2003 01:07:22 +1100

 >>>>> "Geert" == Geert Bosch <bosch@gnat.com> writes:
 
   >> I see your point about partitions though I must say it was far from
   >> obvious that I should be looking there. Perhaps the UM should have a
   >> reference to the RM.
 
   Geert> I now see what you mean. I agree that the language here could
   Geert> be improved. Actually, the language from the Ada RM that I
   Geert> quoted seems to be pretty clear, so I think we should borrow
   Geert> from that or indeed put in a link (or both).
 
 I'm not an Ada language lawyer, so the scope of this PR is a bit
 beyond me now.  I will commit the simple grammar fix and then put the
 PR back into analysed state so that it can be finished off by one of
 you fellows.
 
 Cheers, Ben

Re: ada/9406: Documentation suggestion

[Geert Bosch]

The following reply was made to PR ada/9406; it has been noted by GNATS.

From: Geert Bosch <bosch@gnat.com>
To: Simon Wright <simon@pushface.org>
Cc: bosch@gcc.gnu.org, bje@gcc.gnu.org, gcc-bugs@gcc.gnu.org,
	gcc-prs@gcc.gnu.org, gcc-gnats@gcc.gnu.org
Subject: Re: ada/9406: Documentation suggestion
Date: Sun, 23 Feb 2003 09:51:23 -0500

 On Sunday, Feb 23, 2003, at 07:16 America/New_York, Simon Wright wrote:
 
 > Now (3) and (4) *cannot be right* because this is in a section where
 > *there is no ada main program*, OK?
 > ...
 > I see your point about partitions though I must say it was far from
 > obvious that I should be looking there. Perhaps the UM should have a
 > reference to the RM.
 
 I now see what you mean. I agree that the language here could be
 improved. Actually, the language from the Ada RM that I quoted seems
 to be pretty clear, so I think we should borrow from that or indeed
 put in a link (or both).
 
    -Geert
 

Re: ada/9406: Documentation suggestion

[Simon Wright]

The following reply was made to PR ada/9406; it has been noted by GNATS.

From: Simon Wright <simon@pushface.org>
To: bosch@gnat.com
Cc: bosch@gcc.gnu.org, bje@gcc.gnu.org, gcc-bugs@gcc.gnu.org,
   gcc-prs@gcc.gnu.org, gcc-gnats@gcc.gnu.org
Subject: Re: ada/9406: Documentation suggestion
Date: Sun, 23 Feb 2003 12:16:03 GMT

 I've obviously failed to make my point! I'll have another go and shut up ..
 
 This is the present document:
 
    If the main program is in some language other than Ada, Then you
    may have more than one entry point in the Ada subsystem. You must
    use a special option of the binder to generate callable routines to
    initialize and finalize the Ada units (see Binding with Non-Ada
    Main Programs). Calls to the initialization and finalization
    routines must be inserted in the main program, or some other
    appropriate point in the code. The call to initialize the Ada units
    must occur before the first Ada subprogram is called, and the call
    to finalize the Ada units must occur after the last Ada subprogram
    returns. You use the same procedure for building the program as
    described previously. In this case, however, the binder only places
    the initialization and finalization subprograms into file b~xxx.adb
    instead of the main program. So, if the main program is not in Ada,
    you should proceed as follows:
 
    1. Compile the other language files to generate object files. For
       instance:
 
           gcc -c file1.c
           gcc -c file2.c
           
 
    2. Compile the Ada units to produce a set of object files and ALI
       files. For instance:
 
           gnatmake -c entry_point1.adb
           gnatmake -c entry_point2.adb
           
 
    3. Run the Ada binder on the Ada main program. For instance:
 
           gnatbind -n entry_point1.ali entry_point2.ali
           
 
    4. Link the Ada main program, the Ada objects and the other
       language objects. You only need to give the last entry point
       here. For instance:
 
           gnatlink entry_point2.ali file1.o file2.o
           
 
 Now (3) and (4) *cannot be right* because this is in a section where
 *there is no ada main program*, OK?
 
 My point about Ada subprograms being called indirectly by the non-Ada
 main program is not that there might be calls via Ada, which are
 obviously going to be handled, but that there might be calls via (a
 chain of) non-Ada units, and the user needs to account for them as
 well. And for variables (the second line of the first para above talks
 about "entry points", a naive user might not recognise that variables
 count).
 
 I see your point about partitions though I must say it was far from
 obvious that I should be looking there. Perhaps the UM should have a
 reference to the RM.

Re: ada/9406: Documentation suggestion

[Simon Wright]

The following reply was made to PR ada/9406; it has been noted by GNATS.

From: Simon Wright <simon@pushface.org>
To: bosch@gcc.gnu.org, bje@gcc.gnu.org, gcc-bugs@gcc.gnu.org,
   gcc-prs@gcc.gnu.org, simon@pushface.org, gcc-gnats@gcc.gnu.org
Cc: bje@gcc.gnu.org, gcc-bugs@gcc.gnu.org, gcc-prs@gcc.gnu.org
Subject: Re: ada/9406: Documentation suggestion
Date: Thu, 20 Feb 2003 21:35:16 GMT

 > X-Envelope-To: simon@pushface.org
 > X-Forwarding-To: simon@pushface.org
 > Date: 19 Feb 2003 20:56:15 -0000
 > From: bosch@gcc.gnu.org
 > Reply-To: bosch@gcc.gnu.org, bje@gcc.gnu.org, gcc-bugs@gcc.gnu.org,
 >   gcc-prs@gcc.gnu.org, simon@pushface.org, gcc-gnats@gcc.gnu.org
 > 
 > Synopsis: Documentation suggestion
 > 
 > State-Changed-From-To: feedback->closed
 > State-Changed-By: bosch
 > State-Changed-When: Wed Feb 19 20:56:15 2003
 > State-Changed-Why:
 >     Suggestion inconsistent with wording in language standard and rest of documentation. Furthermore the term "entry unit" is confusing as both "entry" and "unit" are terms defined in the Ada reference manual.
 > 
 > http://gcc.gnu.org/cgi-bin/gnatsweb.pl?cmd=view%20audit-trail&database=gcc&pr=9406
 
 You are of course entirely welcome to reject the suggested
 rewording. However,
 
 (a) the first part of the patch corrected a grammatical error.
 
 (b) the second part begins "Run the Ada binder on the Ada main
 program." but ----
 
          we are in a section of the manual which begins "If the main
          program is in some language other than Ada"!!!!!!!
 
 (c) (I missed this) the next para has the same error, it begins "Link
 the Ada main program".
 
 
 So there is a problem with the manual.
 
 
 My suggestion was to say "run the Ada binder on the Ada entry units"
 but I suppose you could be all formal and say "run the Ada binder on
 all the Ada units that contain subprograms that are called directly or
 indirectly by the non-Ada main program". I think I would have
 understood the former better. I certainly didn't understand the
 present wording!
 
 (by the way, what about non-subprogram entities such as variables?)

Re: ada/9406: Documentation suggestion

[bosch]

Synopsis: Documentation suggestion

State-Changed-From-To: feedback->closed
State-Changed-By: bosch
State-Changed-When: Wed Feb 19 20:56:15 2003
State-Changed-Why:
    Suggestion inconsistent with wording in language standard and rest of documentation. Furthermore the term "entry unit" is confusing as both "entry" and "unit" are terms defined in the Ada reference manual.

http://gcc.gnu.org/cgi-bin/gnatsweb.pl?cmd=view%20audit-trail&database=gcc&pr=9406

Re: ada/9406: Documentation suggestion

[bje]

Synopsis: Documentation suggestion

State-Changed-From-To: analyzed->feedback
State-Changed-By: bje
State-Changed-When: Tue Feb 18 14:06:20 2003
State-Changed-Why:
    Patch submitted to gcc-patches; awaiting approval.

http://gcc.gnu.org/cgi-bin/gnatsweb.pl?cmd=view%20audit-trail&database=gcc&pr=9406

Re: ada/9406: Documentation suggestion

[bje]

Synopsis: Documentation suggestion

Responsible-Changed-From-To: unassigned->bje
Responsible-Changed-By: bje
Responsible-Changed-When: Tue Feb 18 12:09:30 2003
Responsible-Changed-Why:
    I'll take it.
State-Changed-From-To: open->analyzed
State-Changed-By: bje
State-Changed-When: Tue Feb 18 12:09:30 2003
State-Changed-Why:
    Looks reasonable to me.

http://gcc.gnu.org/cgi-bin/gnatsweb.pl?cmd=view%20audit-trail&database=gcc&pr=9406

ada/9406: Documentation suggestion

[simon]

>Number:         9406
>Category:       ada
>Synopsis:       Documentation suggestion
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    unassigned
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Jan 22 20:56:00 UTC 2003
>Closed-Date:
>Last-Modified:
>Originator:     Simon Wright
>Release:        gcc version 3.3 20021130 (experimental)
>Organization:
>Environment:
i686-pc-linux-gnu
>Description:
A slight lack of clarity wrt how to link with non-Ada mains: suggested patch..
--- gcc/ada/gnat_ug.texi        28 Dec 2002 21:38:51 -0000      1.6
+++ gcc/ada/gnat_ug.texi        22 Jan 2003 20:50:34 -0000
@@ -2409,7 +2409,7 @@
 
 @cindex Binder output file
 @noindent
-If the main program is in some language other than Ada, Then you may
+If the main program is in some language other than Ada, you may
 have more than one entry point in the Ada subsystem. You must use a
 special option of the binder to generate callable routines to initialize
 and finalize the Ada units (@pxref{Binding with Non-Ada Main Programs}).
@@ -2440,7 +2440,7 @@
 @end smallexample
 
 @item
-Run the Ada binder on the Ada main program. For instance:
+Run the Ada binder on the Ada entry units. For instance:
 @smallexample
 gnatbind ^-n^/NOMAIN^ entry_point1.ali entry_point2.ali
 @end smallexample
>How-To-Repeat:
n/a
>Fix:
Apply suggested rewrite
>Release-Note:
>Audit-Trail:
>Unformatted: