AdaBrowse 1.5 available

AdaBrowse 1.5 available

[Thomas Wolf]

AdaBrowse is a HTML documentation generator for Ada 95 library
unit specs, similar to what javadoc does for Java.

AdaBrowse is GPLed and available at the URL

<http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/>,
 
both a pre-built executable (for Win NT/2k and GNAT 3.14p), and the
sources.

An example of what AdaBrowse can do is at the URL
<http://home.tiscalinet.ch/t_wolf/tw/ada95/util/doc/>.

AdaBrowse is a command-line utility; it has no graphical user
interface. It is highly configurable through command line options,
style sheets, and configuration files.

AdaBrowse takes apart the Ada 95 source and produces a structured
and extensively cross-referenced HTML documentation from it. It
extracts Ada comments and generates formatted descriptions from them.
For packages, it also produces a (cross-linked) type index containing
links to the primitive operations of the types.

AdaBrowse uses ASIS to gather semantic information about a library
unit spec. It can handle whole libraries and produce global unit,
subprogram, and type indices for all library units.

AdaBrowse has been extensively tested on many publicly available
Ada 95 libraries and specially constructed test cases (in total
more than 1000 Ada 95 library unit specs).

V1.5 has been improved in many ways over the last announced V1.2,
including:

- some bug fixes, and more work-arounds for bugs in ASIS-for-GNAT.
- support for krunched file names.
- index generation for units, subprograms, and types.

AdaBrowse builds and runs without further ado on both Win NT/2k
and Unix systems, and shouldn't be too hard to port to other ASIS
implementations than ASIS-for-GNAT.

The distribution comes with a comprehensive user's guide including
examples and instructions on how and where to submit bug reports.

AdaBrowse differs from gnathtml in several ways:

- AdaBrowse is a stand-alone executable; gnathtml is a perl script.
- AdaBrowse is more flexible, and can be customized to a much
  greater extent.
- AdaBrowse produces structured HTML output including formatted
  descriptions; gnathtml basically just encloses the source in
  <PRE></PRE> tags and adds cross-references.
- AdaBrowse uses ASIS to collect cross-reference information,
  whereas gnathtml relies on the GNAT-specific cross-reference
  info in the ALI files.
- AdaBrowse uses ASIS to gather semantic information about library
  units and makes use of it, e.g. to find all the primitive operations
  of a type.
- AdaBrowse can call e.g. a compiler if no ASIS information is found,
  whereas gnathtml doesn't generate cross-references if no ALI file
  is found.
- AdaBrowse does some limited form of pretty-printing, such as using
  identifiers as cased in their definition everywhere.

-- 
-----------------------------------------------------------------
Thomas Wolf                          e-mail: t_wolf@angelfire.com

Re: AdaBrowse 1.5 available

[Ted Dennison]

Thomas Wolf <t_wolf@angelfire.com> wrote in message news:<MPG.17162e33c80a52ca989687@news.ip-plus.net>...
> AdaBrowse is a HTML documentation generator for Ada 95 library
> unit specs, similar to what javadoc does for Java.
> 
> AdaBrowse is GPLed and available at the URL
> AdaBrowse differs from gnathtml in several ways:
> 
> - AdaBrowse is a stand-alone executable; gnathtml is a perl script.

This is great. I was (slowly) working one something like this using
OpenToken, but ASIS is a much better approach, and you seem to have
done a super job with it.

What are the chances we could check your sources into the gcc-gnat CVS
tree, and get rid of that stupid Perl script altogether?

-- 
T.E.D.
Home     -  mailto:dennison@telepath.com (Yahoo: Ted_Dennison)
Homepage -  http://www.telepath.com/dennison/Ted/TED.html

Re: AdaBrowse 1.5 available

[tmoran]

> but ASIS is a much better approach, ...
> ... and get rid of that stupid Perl script altogether?
  How would you generate reviewable docs for something that exists
only as the public part of a set of Ada specification parts?  ie,
that's uncompilable and thus un-ASIS-able?  Or what happens when
the latest compiler version has a bug that prevents compilation,
and ASIS generation, and thus prevents doc generation?

Re: AdaBrowse 1.5 available

[Jeffrey Creem]

<tmoran@acm.org> wrote in message
news:AQ0r8.851$Pd4.138617873@newssvr21.news.prodigy.com...
> > but ASIS is a much better approach, ...
> > ... and get rid of that stupid Perl script altogether?
>   How would you generate reviewable docs for something that exists
> only as the public part of a set of Ada specification parts?  ie,
> that's uncompilable and thus un-ASIS-able?  Or what happens when

Good question.

> the latest compiler version has a bug that prevents compilation,
> and ASIS generation, and thus prevents doc generation?

Umm..Use the older compiler version...

To be fair, the perl script is not really that much better in this regard
since it requires that
the ali files be present so if a new compiler comes out and the code will
not compile you may not
get enough data in the ali file to run it either.

Re: AdaBrowse 1.5 available

[Thomas Wolf]

dennison@telepath.com wrote:

> What are the chances we could check your sources into the gcc-gnat CVS
> tree, and get rid of that stupid Perl script altogether?

I have no basic objections to this, but:

- Is ASIS-for-GNAT in the gcc-gnat CVS tree? Without an
  ASIS-for-GNAT for the gcc-gnat, it wouldn't make much
  sense to put AdaBrowse there.

- I didn't care about GNU coding guidelines or whatever when I 
  developed AdaBrowse, so if it is to be put into the gcc-gnat
  CVS tree (and supposedly, into the gcc distribution), there
  may be some work to do in that respect.

- The source distribution doesn't contain any Makefiles. That also
  would have to be added by somebody. (Building AdaBrowse is as
  simple as "gnatmake -O2 adabrowse -lasis", so I didn't see the
  need for a Makefile-based build procedure.)

- AdaBrowse uses (and its source distribution contains) a couple
  of units that are *not* GPLed, but distributed under the more
  permissive Ada Community License (the one used by the Ada 95
  Booch components). I have no idea if this would be OK with GNU
  policies. An option might perhaps be to use something akin to
  the modified GPL as used by the GNAT library for these units.

-- 
-----------------------------------------------------------------
Thomas Wolf                          e-mail: t_wolf@angelfire.com

Re: AdaBrowse 1.5 available

[Ted Dennison]

Thomas Wolf <t_wolf@angelfire.com> wrote in message news:<MPG.171775b567a3c15a989688@news.ip-plus.net>...
> dennison@telepath.com wrote:
> 
> > What are the chances we could check your sources into the gcc-gnat CVS
> > tree, and get rid of that stupid Perl script altogether?
> 
> I have no basic objections to this, but:
> 
> - Is ASIS-for-GNAT in the gcc-gnat CVS tree? Without an
>   ASIS-for-GNAT for the gcc-gnat, it wouldn't make much
>   sense to put AdaBrowse there.

I don't know enough about ASIS to know what to look for, but if you do
you can check for yourself at
http://sources.redhat.com/cgi-bin/cvsweb.cgi/gcc/gcc/ada/?cvsroot=gcc
.

> 
> - I didn't care about GNU coding guidelines or whatever when I 
>   developed AdaBrowse, so if it is to be put into the gcc-gnat
>   CVS tree (and supposedly, into the gcc distribution), there
>   may be some work to do in that respect.

For the most part, they are irrelevant to Ada. When I looked into it
for one of my projects, the only one that seemed like it would be an
issue was the requirement to keep all documentation in texinfo format.
It might be a good idea to recompile things with the ACT style checks
on, but if you don't I'm sure someone else will later. :-)

> - AdaBrowse uses (and its source distribution contains) a couple
>   of units that are *not* GPLed, but distributed under the more
>   permissive Ada Community License (the one used by the Ada 95
>   Booch components). I have no idea if this would be OK with GNU
>   policies. An option might perhaps be to use something akin to
>   the modified GPL as used by the GNAT library for these units.

Ouch. I thought it was all GPL. That could be a serious problem.

If it qualifies as a Free Software license, and is compatable with the
GPL, then there should be no problem. If it isn't compatable with the
GPL, *that* could be a fatal problem, not only with the GNU folks, but
for everyone else as well. That   prevents *anyone* from distributing
your sources (not including you, of course, assuming you have the
copyright on everything).

The GPL is generally incompatable with any license that tries to place
extra restrictions on what people can do when they redistribute. I see
some worrysome stuff in there, but then its a bit obtuse and IANAL. It
claims to be derived from Perl's Artistic License. The original
version of that was considered non-free and GPL incompatable
(supposely for its extreme obtuseness). The current version (as well
as a "clarified version") is Free and GPL compatable. But who knows
which version the Ada folks used and what changes they introduced may
have done to things?

I'd say personally (as someone who currently is running 4 "Open
Source" software projects), I wouldn't use that license. Its
"freenesss" wrt the GPL is debatable (it places restrictions on what
you can do with it when you don't even redistribute the result, which
the GPL never does). It is certianly more restrictive than the GMGPL.
It seems to be shooting for the same goals as the GMGPL, but its
compatability with GPL'ed systems is questionable while the GMGPL's is
not.

If I were you I'd at least satisfy myself that it is GPL-compatable
before combining it with GPL code and publicly distributing it.


-- 
T.E.D.
Home     -  mailto:dennison@telepath.com (Yahoo: Ted_Dennison)
Homepage -  http://www.telepath.com/dennison/Ted/TED.html

Re: AdaBrowse 1.5 available

[Florian Weimer]

tmoran@acm.org writes:

> Or what happens when the latest compiler version has a bug that
> prevents compilation, and ASIS generation, and thus prevents doc
> generation?

This is unlikely if AdaBrowse (and ASIS) was tested routinely during
GCC builds.

Re: AdaBrowse 1.5 available

[Florian Weimer]

Thomas Wolf <t_wolf@angelfire.com> writes:

> - Is ASIS-for-GNAT in the gcc-gnat CVS tree? Without an
>   ASIS-for-GNAT for the gcc-gnat, it wouldn't make much
>   sense to put AdaBrowse there.

No, it hasn't been incorporated yet.

> - I didn't care about GNU coding guidelines or whatever when I 
>   developed AdaBrowse, so if it is to be put into the gcc-gnat
>   CVS tree (and supposedly, into the gcc distribution), there
>   may be some work to do in that respect.

Not a big deal, I think.

> - The source distribution doesn't contain any Makefiles. That also
>   would have to be added by somebody. (Building AdaBrowse is as
>   simple as "gnatmake -O2 adabrowse -lasis", so I didn't see the
>   need for a Makefile-based build procedure.)

This isn't a problem at all.

> - AdaBrowse uses (and its source distribution contains) a couple
>   of units that are *not* GPLed, but distributed under the more
>   permissive Ada Community License (the one used by the Ada 95
>   Booch components). I have no idea if this would be OK with GNU
>   policies. An option might perhaps be to use something akin to
>   the modified GPL as used by the GNAT library for these units.

Oh, this is a showstopper.  First of all, the FSF prefers to have
copyright assignments for all source code it distributes, but
exceptions have been arranged in the past.

The fatal problem, however, is incompatibility of the Ada Community
License with the GPL (the ACL imposes further restrictions).  If you
are in the position to relicense or dual-license the ACL code, you
would have to do this first.

Re: AdaBrowse 1.5 available

[Pascal Obry]

Florian Weimer <fw@deneb.enyo.de> writes:

> > - The source distribution doesn't contain any Makefiles. That also
> >   would have to be added by somebody. (Building AdaBrowse is as
> >   simple as "gnatmake -O2 adabrowse -lasis", so I didn't see the
> >   need for a Makefile-based build procedure.)
> 
> This isn't a problem at all.

Well it is always good to provide a makefile to build the program, clean the
.o/.ali and executable, build a distrib tarball, install the soft... It act as
the minimum build documentation...

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|         http://perso.wanadoo.fr/pascal.obry
--|
--| "The best way to travel is by means of imagination"

Re: AdaBrowse 1.5 available

[Florian Weimer]

Pascal Obry <p.obry@wanadoo.fr> writes:

> Well it is always good to provide a makefile to build the program,
> clean the .o/.ali and executable, build a distrib tarball, install
> the soft... It act as the minimum build documentation...

It would have to be rewritten before it can be used in the GCC context
anyway (objdir/srcdir separation, using the freshly compiled GNAT
version, and so on).

Re: AdaBrowse 1.5 available

[Thomas Wolf]

dennison@telepath.com wrote:
> I don't know enough about ASIS to know what to look for, but if you do
> you can check for yourself at
> http://sources.redhat.com/cgi-bin/cvsweb.cgi/gcc/gcc/ada/?cvsroot=gcc

No, ASIS is not in the gcc-gnat CVS tree. So, for the time being, the
whole issue is moot anyway.

> > 
> > - I didn't care about GNU coding guidelines or whatever when I 
> >   developed AdaBrowse, so if it is to be put into the gcc-gnat
> >   CVS tree (and supposedly, into the gcc distribution), there
> >   may be some work to do in that respect.
> 
> For the most part, they are irrelevant to Ada. When I looked into it
> for one of my projects, the only one that seemed like it would be an
> issue was the requirement to keep all documentation in texinfo format.

A no-can-do for me. If it ever gets into the gcc tree, somebody else
will have to do that (and maintain it).

> It might be a good idea to recompile things with the ACT style checks
> on, but if you don't I'm sure someone else will later. :-)

Done. :-) (Except -gnatyc and -gnatys, which I don't like.) Also made
a couple of minor changes to silence -gnatwa.

> Ouch. I thought it was all GPL. That could be a serious problem.

I wasn't aware that the FSF thinks the ACL (or the Perl Artistic
License) had problems. I just chose the ACL because it seems to work
well for the Ada 95 Booch components.

It's not a big issue for me, and the GMGPL does indeed, as you point
out, accomplish the same goals. So I changed the licenses on these
few files (easy to do, since it's all mine -- no third parties
involved). AdaBrowse 1.51 (now at the URL
<http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/>)
contains all these changes (code clean-up and using the GMGPL instead
of the ACL for the generally useful files). It has also a simple 
Makefile now. 

So the license at least shouldn't be an issue anymore when and if ever
AdaBrowse should be checked-in into the gcc-gnat CVS tree.

But remember, first ASIS-for-GNAT has to get in there! Why was it
omitted in the first place?

-- 
-----------------------------------------------------------------
Thomas Wolf                          e-mail: t_wolf@angelfire.com

Re: AdaBrowse 1.5 available

[tmoran]

> > Or what happens when the latest compiler version has a bug that
> This is unlikely if AdaBrowse (and ASIS) was tested routinely during
  Perhaps there's a misunderstanding here.   We had a case where a
new release of a compiler fixed one problem but instruced a new one.  The
symptom of the new problem was a compiler crash on legal source code.
Clearly in that case the new compiler, having crashed, won't generate
ASIS stuff, and thus can't be used with AdaBrowse.  Using the old compiler
is undesirable because a) it had a (different) problem that forced a special
contorted version of our source code, and b) I don't know of any way
to switch easily between two versions of Gnat on one machine.
  Demanding that something completely compile with a possibly broken
compiler seems excessive when all you really want is a prettification of
the public part of some specs and some fancy cross-refererencing info.

Re: AdaBrowse 1.5 available

[jim]

I havent seen this entire thread.  is there someway to use asis for the
gnat in the fsf tree.  we have built gnat for mac os x and i would like
to get adabrowse running on it.

thanks jim

Re: AdaBrowse 1.5 available

[Ted Dennison]

Thomas Wolf <t_wolf@angelfire.com> wrote in message news:<MPG.171accfee1802fbe989689@news.ip-plus.net>...
> dennison@telepath.com wrote:
> > For the most part, they are irrelevant to Ada. When I looked into it
> > for one of my projects, the only one that seemed like it would be an
> > issue was the requirement to keep all documentation in texinfo format.
> 
> A no-can-do for me. If it ever gets into the gcc tree, somebody else
> will have to do that (and maintain it).

That was exactly my reaction when I was told about it. With a few more
months under my belt, I'm now thinking it isn't that big of a deal
though. There are apparently tools to convert texinfo into just about
any format around, including html. In fact, that seems to be the whole
point. One can use it as sort of the "sources" for the HTML docs, and
build the HTML docs as part of the system build. Now I'm not pushing
you to do this; that would be quite hypocritical, as I haven't done it
for any of my projects either. I'm just saying I personally don't see
it as such a problem after thinking about it for a while.

> > Ouch. I thought it was all GPL. That could be a serious problem.
> 
> I wasn't aware that the FSF thinks the ACL (or the Perl Artistic
> License) had problems. I just chose the ACL because it seems to work
> well for the Ada 95 Booch components.

To be precise, they have problems with the original Perl Artistic
license. They don't have big problems with the "Clarified Artistic
License", the "Artistic License 2.0" (which they say no one uses), or
the current license that Perl uses.

To see the full discussion of this, see
http://www.gnu.org/licenses/license-list.html .

> out, accomplish the same goals. So I changed the licenses on these
> few files (easy to do, since it's all mine -- no third parties
> involved). AdaBrowse 1.51 (now at the URL
> <http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/>)
> contains all these changes (code clean-up and using the GMGPL instead
> of the ACL for the generally useful files). It has also a simple 
> Makefile now. 

Great!


-- 
T.E.D.
Home     -  mailto:dennison@telepath.com (Yahoo: Ted_Dennison)
Homepage -  http://www.telepath.com/dennison/Ted/TED.html