Ada documentation issues

Ada documentation issues

[Joseph S. Myers]

There are several issues with the documentation of the Ada front end which
need to be resolved:

* The front end should have a proper manual, distributed in the ada
directory.  Once this is done, I will attend to updating
update_web_docs and onlinedocs/index.html to have that manual
available online.

* gcc/doc/install.texi needs updating: both to include ada in the list
of valid --enable-languages values, and to document exactly what needs
to be preinstalled in order to build the Ada front end.  As long as
there is a separate "make gnatlib_and_tools", this also needs to be
documented in install.texi.

* gcc/doc/contrib.texi should have GNU Ada contributors listed.

* gcc/doc/gcc.texi should be updated, both in the chapter "Compile C,
C++, Objective C, Fortran, Java or CHILL" and in "Language Standards
Supported by GCC" (the latter possibly pointing to where the GNU Ada
documentation describes Ada standards and GNAT's relation to them).

* gcc/doc/invoke.texi should have documentation added for suffixes for
Ada source files and for whatever -x language options there are for
Ada.

* Some more GNU Ada maintainers may need adding to MAINTAINERS.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Ada documentation issues

[Geert Bosch]

On Fri, 5 Oct 2001, Joseph S. Myers wrote:

  There are several issues with the documentation of the Ada front end which
  need to be resolved:
  
  * The front end should have a proper manual, distributed in the ada
  directory.  Once this is done, I will attend to updating
  update_web_docs and onlinedocs/index.html to have that manual
  available online.

The reason the manual is not checked in yet, is that it requires
preprocessing with a special tool written in spitbol. I can
in the preprocessed manual with the note that there will be some
major changes soon, as we reorganize the manual to not require
preprocessing anymore. The reason I'm hesitant in checking this
in now, is the fact that it would not be a good base for changing yet.
  
The other documentation issues are noted, but it would be nice if
there would be volunteers for this, as it is quite separate from
the things in the gcc/ada directory which I'm busy working on now.

FYI, since the Ada front end was contributed, there have been more
than a hundred check ins already. I'm figuring out now how to make
those changes flow to the FSF sources in a manageable way.

  -Geert

Re: Ada documentation issues

[Gerald Pfeifer]

On Fri, 5 Oct 2001, Joseph S. Myers wrote:
> There are several issues with the documentation of the Ada front end
> which need to be resolved:

If these are not resolved by the end of this week, would you mind filing
these as PRs in the "ada" category?

And during the GCC 3.1 release process (at the latest), these will become
high priority PRs.

Just so that we don't forget...

Gerald
-- 
Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/

Re: Ada documentation issues

[Joseph S. Myers]

On Tue, 9 Oct 2001, Gerald Pfeifer wrote:

> On Fri, 5 Oct 2001, Joseph S. Myers wrote:
> > There are several issues with the documentation of the Ada front end
> > which need to be resolved:
> 
> If these are not resolved by the end of this week, would you mind filing
> these as PRs in the "ada" category?

Note that some (but not all) of these issues were addressed by Florian
Weimer in <URL: http://gcc.gnu.org/ml/gcc-patches/2001-10/msg00236.html >,
which needs to be reviewed / applied.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Ada documentation issues

[Gerald Pfeifer]

On Tue, 9 Oct 2001, Joseph S. Myers wrote:
> Note that some (but not all) of these issues were addressed by Florian
> Weimer in <URL: http://gcc.gnu.org/ml/gcc-patches/2001-10/msg00236.html >,
> which needs to be reviewed / applied.

Indeed, I was just reviewing that when your mail arrived. :-)

Florian, apart from a ChangeLog, there's only one issue I spotted with
the last part of your patch:

Index: invoke.texi
===================================================================
+@item @var{file}.ads
+Ada source code file which contains a library unit declaration (a
+declaration of a package, subprogram, or generic, or a generic
+instantiation), or a library unit renaming declaration (a package,
+generic, or subprogram renaming declaration).  These files are also
+called @dfn{specs}.

"Such files are also..."?

+@itemx @var{file}.adb
:
 @c GCC also knows about some suffixes for languages not yet included:
-@c Ada:
-@c @var{file}.ads
-@c @var{file}.adb
-@c @var{file}.ada

What happened to .ada? Your patch removes the old reference, but doesn't
introduce a new one -- is this intentional?

(As with the other parts, I'd prefer if one of our Ada maintainers
has a final look once you submit an updated version of your patches
and install them then.)

Gerald

Re: Ada documentation issues

[Geert Bosch]

On Tue, 9 Oct 2001, Gerald Pfeifer wrote:

  What happened to .ada? Your patch removes the old reference, but doesn't
  introduce a new one -- is this intentional?

Yes, see Kenner's recent check in to remove driver recognition of this. 
The .ada extension is no longer used for GNAT.
  
  -Geert
  

Re: Ada documentation issues

[dewar]

<<Note that some (but not all) of these issues were addressed by Florian
Weimer in <URL: http://gcc.gnu.org/ml/gcc-patches/2001-10/msg00236.html >,
which needs to be reviewed / applied.
>>

This patch certainly looks fine to me.
Robert Dewar

Re: Ada documentation issues

[dewar]

<<> FYI, since the Ada front end was contributed, there have been more
> than a hundred check ins already. I'm figuring out now how to make
> those changes flow to the FSF sources in a manageable way.
>>

Probably this will calm down a bit over time. For example, a huge number
of checkins was to deal with changing Linux to GNU/Linux in comments :-)

Re: Ada documentation issues

[mike stump]

> Date: Fri, 5 Oct 2001 17:48:27 -0400 (EDT)
> From: Geert Bosch <bosch@gnat.com>
> To: mike stump <mrs@windriver.com>
> Cc: jsm28@cam.ac.uk, gcc@gcc.gnu.org

> I'd like to have a somewhat better log than "merged in changes", but
> maybe that will be too hard.

The ChangeLog file can be as complete and featureful as you want..
Also, if you run it nightly, in the cvs ci command, you can include
The top hunk of the changelog.  Also, in the ChangeLog, you should not
have a comment like, merged in bla...

Re: Ada documentation issues

[Joseph S. Myers]

On Fri, 5 Oct 2001, Geert Bosch wrote:

> I'd like to have a somewhat better log than "merged in changes", but
> maybe that will be too hard.

A better log ought to mean each individual change being committed
individually, with a meaningful ChangeLog entry also serving as a commit
message, a testcase once we have an Ada testsuite, if a non-confidential
testcase for the change can reasonably be created, a message to
gcc-patches explaining the patch, etc..

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Ada documentation issues

[Geert Bosch]

On Fri, 5 Oct 2001, mike stump wrote:

  :-) I used to do this for the C++ frontend...  Basically, I just had
  reference copies of what I last merged from my tree, what was at the
  FSF, and used diff -r and patch to run in the new changes to my copy
  of the other tree, and then diff once more to obtain the FSF version
  of the patch, and then run that set into the FSF tree.  This was a
  unidirection process.  You do it twice, and you then have a
  bidirectional process.  Stir and run once a week, and presto.  My
  experience was that is was fairly reliable and didn't take much effort
  (I had a script that did it all).  The only think I had to do by hand
  was to resolve conflicts.  I always considered just putting it in cron
  and running nightly, but never got around to it.

I'd like to have a somewhat better log than "merged in changes", but
maybe that will be too hard.

  -Geert

Re: Ada documentation issues

[mike stump]

> Date: Fri, 5 Oct 2001 17:26:48 -0400 (EDT)
> From: Geert Bosch <bosch@gnat.com>
> To: "Joseph S. Myers" <jsm28@cam.ac.uk>
> Cc: gcc@gcc.gnu.org

> FYI, since the Ada front end was contributed, there have been more
> than a hundred check ins already. I'm figuring out now how to make
> those changes flow to the FSF sources in a manageable way.

:-) I used to do this for the C++ frontend...  Basically, I just had
reference copies of what I last merged from my tree, what was at the
FSF, and used diff -r and patch to run in the new changes to my copy
of the other tree, and then diff once more to obtain the FSF version
of the patch, and then run that set into the FSF tree.  This was a
unidirection process.  You do it twice, and you then have a
bidirectional process.  Stir and run once a week, and presto.  My
experience was that is was fairly reliable and didn't take much effort
(I had a script that did it all).  The only think I had to do by hand
was to resolve conflicts.  I always considered just putting it in cron
and running nightly, but never got around to it.

Would be nice if cvs directly supported this type of semantic.