Q: Generating Documenation from Ada Sources?

Q: Generating Documenation from Ada Sources?

[Michael Erdmann]

I am looking for open source tools which are
generating documentation out of package
specifications.
Such a tools sould not just list the items
in the specification but also extract the
comments belonging to these items into a
resonable format.

Who knows more about the topic?

Michael

Re: Q: Generating Documenation from Ada Sources?

[Robert Dewar]

Michael Erdmann <Michael.Erdmann@snafu.de> wrote in message news:<3CDD31D7.2060005@snafu.de>...
> I am looking for open source tools which are
> generating documentation out of package
> specifications.
> Such a tools sould not just list the items
> in the specification but also extract the
> comments belonging to these items into a
> resonable format.
> 
> Who knows more about the topic?
> 
> Michael


For a well written Ada spec, it would seem that the unix tool cat would
do what you want, or possibly something like gnathtml. I think you need
to be a whole lot more specific about what you are looking for. What else
is there in a spec except items and comments?

Re: Q: Generating Documenation from Ada Sources?

[Michael Erdmann]

Robert Dewar wrote:
> Michael Erdmann <Michael.Erdmann@snafu.de> wrote in message news:<3CDD31D7.2060005@snafu.de>...
> 
>>I am looking for open source tools which are
>>generating documentation out of package
>>specifications.
>>Such a tools sould not just list the items
>>in the specification but also extract the
>>comments belonging to these items into a
>>resonable format.
>>
>>Who knows more about the topic?
>>
>>Michael
> 
> 
> 
> For a well written Ada spec, it would seem that the unix tool cat would
> do what you want, or possibly something like gnathtml. I think you need
> to be a whole lot more specific about what you are looking for. What else
> is there in a spec except items and comments?


The point is that Ada spec. come along with
coments which expalains certain aspects of
an interface.
I like to generate from the *.ads file a
docbook (sgml) formated manual page which
contains the explanatory text. This mean
for example the package name goes into the
section name, the description into a
paragraph, the spec. it self goes into
a program listing section.

I guess i am not the first one having
such a problem!


Michael

Re: Q: Generating Documenation from Ada Sources?

[Randy Brukardt]

Michael Erdmann wrote in message <3CDD6BD7.5010503@snafu.de>...
>The point is that Ada spec. come along with coments which expalains
certain aspects of
>an interface.
>I like to generate from the *.ads file a docbook (sgml) formated manual
page which
>contains the explanatory text. This mean for example the package name
goes into the
>section name, the description into a paragraph, the spec. it self goes
into
>a program listing section.
>
>I guess i am not the first one having such a problem!


We developed such a tool for creating the Claw documents (it outputs
HTML and .RTF for WinHelp), but its not open source and its rather tied
to our Claw coding conventions. What it does is preprocess the
specifications into an intermediate file, which can be updated manually
to correct mistakes, add links and formatting, and the like. There is
also some tools for merging files (so that new versions of packages
don't lose the hand-work from previous versions). I thought about making
a GUI for it, and making it available as a tool, but I didn't think
there was likely to be enough demand to make it worthwhile.

If you don't find something else, drop me a line and we can discuss
making it available to you.

                Randy Brukardt.

Re: Q: Generating Documenation from Ada Sources?

[Michael Erdmann]

Randy Brukardt wrote:
> Michael Erdmann wrote in message <3CDD6BD7.5010503@snafu.de>...
> 
>>The point is that Ada spec. come along with coments which expalains
> 
> certain aspects of
> 
>>an interface.
>>I like to generate from the *.ads file a docbook (sgml) formated manual
> 
> page which
> 
>>contains the explanatory text. This mean for example the package name
> 
> goes into the
> 
>>section name, the description into a paragraph, the spec. it self goes
> 
> into
> 
>>a program listing section.
>>
>>I guess i am not the first one having such a problem!
> 
> 
> 
> We developed such a tool for creating the Claw documents (it outputs
> HTML and .RTF for WinHelp), but its not open source and its rather tied
> to our Claw coding conventions. 

I gues this is important to note, that i have to come up with
some kind of convention how the text is formated in order to
map the text into docbook.

I am wondering if it makes sense to add the commentary text already
in tagged format into the source. Any experiences on this?

Regards
    M.Erdmann

Re: Q: Generating Documenation from Ada Sources?

[Dr. Michael Paus]

Michael Erdmann wrote:
> Randy Brukardt wrote:
> 
>> Michael Erdmann wrote in message <3CDD6BD7.5010503@snafu.de>...
>>
>>> The point is that Ada spec. come along with coments which expalains
>>
>>
>> certain aspects of
>>
>>> an interface.
>>> I like to generate from the *.ads file a docbook (sgml) formated manual
>>
>>
>> page which
>>
>>> contains the explanatory text. This mean for example the package name
>>
>>
>> goes into the
>>
>>> section name, the description into a paragraph, the spec. it self goes
>>
>>
>> into
>>
>>> a program listing section.
>>>
>>> I guess i am not the first one having such a problem!
>>
>>
>>
>>
>> We developed such a tool for creating the Claw documents (it outputs
>> HTML and .RTF for WinHelp), but its not open source and its rather tied
>> to our Claw coding conventions. 
> 
> 
> I gues this is important to note, that i have to come up with
> some kind of convention how the text is formated in order to
> map the text into docbook.
> 
> I am wondering if it makes sense to add the commentary text already
> in tagged format into the source. Any experiences on this?

It sounds as if you are looking for something like JavaDoc (for Ada).
Hava you tried AdaBrowse? (http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/)
I have not had the time to try it out but it is supposed to do what you want.

Michael

Re: Q: Generating Documenation from Ada Sources?

[Michael Erdmann]

Dr. Michael Paus wrote:
> Michael Erdmann wrote:
> 
>> Randy Brukardt wrote:
>>
>>> Michael Erdmann wrote in message <3CDD6BD7.5010503@snafu.de>...
>>>
>>>> The point is that Ada spec. come along with coments which expalains
>>>
>>>
>>>
>>> certain aspects of
>>>
>>>> an interface.
>>>> I like to generate from the *.ads file a docbook (sgml) formated manual
>>>
>>>
>>>
>>> page which
>>>
>>>> contains the explanatory text. This mean for example the package name
>>>
>>>
>>>
>>> goes into the
>>>
>>>> section name, the description into a paragraph, the spec. it self goes
>>>
>>>
>>>
>>> into
>>>
>>>> a program listing section.
>>>>
>>>> I guess i am not the first one having such a problem!
>>>
>>>
>>>
>>>
>>>
>>> We developed such a tool for creating the Claw documents (it outputs
>>> HTML and .RTF for WinHelp), but its not open source and its rather tied
>>> to our Claw coding conventions. 
>>
>>
>>
>> I gues this is important to note, that i have to come up with
>> some kind of convention how the text is formated in order to
>> map the text into docbook.
>>
>> I am wondering if it makes sense to add the commentary text already
>> in tagged format into the source. Any experiences on this?
> 
> 
> It sounds as if you are looking for something like JavaDoc (for Ada).
> Hava you tried AdaBrowse? 
> (http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/)
> I have not had the time to try it out but it is supposed to do what you 
> want.
> 
Thanks i have tried it. What i am interested is more centered on
processing text in the source. Your browser does not care about
the contents of the comments. It is left to the used to build in
tags or not.

What i am looking for i a tool which maps the relevant part of the
coments in a package spec. and transforms this into a docbook document.
In order to do so such a program requieres certain key words.
Theretically the comment in the source could already contain
docbook format but i dont like the idea, since the comments
are getting unreadable.
I gues what i am looking for i a tool which is abble to retrieve
sections identified by headlines from normal and to convert it
into docbook format. Copying in the specification of a procedure
is the minor part of it.

Any way, adabrowser is based on asis, which requieres that the module
is compilable which i cannot gurantee.

Michael


> Michael
> 

Re: Q: Generating Documenation from Ada Sources?

[tmoran]

The tool for Claw only requires the public part of specifications to be
parsable with an ayacc Ada grammar.  The only semantic requirement I
recall is that things are assumed to be defined before use.

It would be nice if there was a cut down, highly forgiving, version of
ASIS to handle incomplete programs or situations where a compiler bug
prevents compilation and thus prevents use of the current ASIS.

Re: Q: Generating Documenation from Ada Sources?

[Ira D. Baxter]

The DMS Software Reengineering Toolkit
can parse Ada, build ASTs, and then
use custom code to extract what you want.
(It is kind of like ASIS, for a whole
set of langauges; not as complete
as ASIS wrt Ada, but more capable
than ASIS in the DMS can
actually change the source tree
and the prettyprint the changed
result.  The latter capability
isn't needed for documenation
extraction).

Part of the customization process can control
how many syntax faults are acceptable before
it gives up (at the price of getting a
syntax tree with error insertions that
might not make sense, but error
recovery is a tough topic).

For the original poster, who wants to
extract certain information and then
reformat the way he likes,
I'd suggest extracting the information
he needs and dumping as XML text.
One can use XSLT to reshape the
result pretty much as you like.
This decouples extraction from
formatting.

See http://www.semdesigns.com/Products/DMS/DMSToolkit.html.

--
Ira D. Baxter, Ph.D. CTO Semantic Designs, Inc.
http://www.semdesigns.com

<tmoran@acm.org> wrote in message
news:SWxD8.1171$fy5.65482852@newssvr21.news.prodigy.com...
> The tool for Claw only requires the public part of specifications to be
> parsable with an ayacc Ada grammar.  The only semantic requirement I
> recall is that things are assumed to be defined before use.
>
> It would be nice if there was a cut down, highly forgiving, version of
> ASIS to handle incomplete programs or situations where a compiler bug
> prevents compilation and thus prevents use of the current ASIS.

Re: Q: Generating Documenation from Ada Sources?

[Stefan Revets]

In article <3CDD31D7.2060005@snafu.de>, Michael Erdmann
<Michael.Erdmann@snafu.de> wrote:

> I am looking for open source tools which are
> generating documentation out of package
> specifications.
> Such a tools sould not just list the items
> in the specification but also extract the
> comments belonging to these items into a
> resonable format.
> 

Literate programming is another option. There is an AdaTangle and AdaWeave
around, implementing the ideas of Donald Knuth.

Stefan Revets

-- 
Stefan A. Revets
Department of Geology & Geophysics, University of Western Australia
Nedlands, WA6907
Australia

Re: Q: Generating Documenation from Ada Sources?

[Georg Bauhaus]

Stefan Revets <srevets@nospam.geol.uwa.edu.au> wrote:
: 
: Literate programming is another option. There is an AdaTangle and AdaWeave
: around, implementing the ideas of Donald Knuth.

It is Ada 83 though.

ftp://www.ctan.org/pub/tex/web/ada/aweb/

Re: Q: Generating Documenation from Ada Sources?

[Stephen Leake]

Michael Erdmann <Michael.Erdmann@snafu.de> writes:

> Dr. Michael Paus wrote:
> > It sounds as if you are looking for something like JavaDoc (for Ada).
> > Hava you tried AdaBrowse?
> > (http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/)
> > I have not had the time to try it out but it is supposed to do what
> > you want.
> >
> Thanks i have tried it. What i am interested is more centered on
> processing text in the source. Your browser does not care about
> the contents of the comments. It is left to the used to build in
> tags or not.

AdaBrowse is Open Source, so you can enhance it. Surely an ASIS-based
tool is the right way to go for an Ada documentation project :). At
least, if you need to go beyond cat (I agree with Robert Dewar here;
just write good comments!).

> What i am looking for i a tool which maps the relevant part of the
> coments in a package spec. and transforms this into a docbook
> document. 

This should be easy to add to AdaBrowse. You do have to establish
conventions in coding style, so AdaBrowse+ can know which comments are
"relevant".

> In order to do so such a program requieres certain key words.
> Theretically the comment in the source could already contain docbook
> format but i dont like the idea, since the comments are getting
> unreadable. I gues what i am looking for i a tool which is abble to
> retrieve sections identified by headlines from normal and to convert
> it into docbook format. Copying in the specification of a procedure
> is the minor part of it.

Ok, you want a somewhat elaborate syntax in the comments. AdaBrowse at
least gets you the top level source traversal, and lets you write the
comment parsing in Ada. Use GNAT.Spitbol or GNAT.Regexp, or
Ada.Strings.Fixed, or OpenToken.

> Any way, adabrowser is based on asis, which requieres that the
> module is compilable which i cannot gurantee.

Why not? Surely you want to know that the document is accurate, which
means that the Ada code compiles! Otherwise you could have
inconsistent information!

Sometimes in reverse engineering an application, the code does not yet
compile because you have switched compilers or OSs or something. But
in that case, I don't see how this sort of documentation can help;
it's really just a prettier form of the source. If you were attempting
to create top-level withing charts or data flows, then being able to
process non-compilable code might be relevant.

-- 
-- Stephe

Re: Q: Generating Documenation from Ada Sources?

[Michael Erdmann]

Stephen Leake wrote:
> Michael Erdmann <Michael.Erdmann@snafu.de> writes:
> 
> 
>>Dr. Michael Paus wrote:
>>
>>>It sounds as if you are looking for something like JavaDoc (for Ada).
>>>Hava you tried AdaBrowse?
>>>(http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/)
>>>I have not had the time to try it out but it is supposed to do what
>>>you want.
>>>
>>
>>Thanks i have tried it. What i am interested is more centered on
>>processing text in the source. Your browser does not care about
>>the contents of the comments. It is left to the used to build in
>>tags or not.
> 
> 
> AdaBrowse is Open Source, so you can enhance it. Surely an ASIS-based
> tool is the right way to go for an Ada documentation project :). At
> least, if you need to go beyond cat (I agree with Robert Dewar here;
> just write good comments!).
> 
> 
>>What i am looking for i a tool which maps the relevant part of the
>>coments in a package spec. and transforms this into a docbook
>>document. 
> 
> 
> This should be easy to add to AdaBrowse. You do have to establish
> conventions in coding style, so AdaBrowse+ can know which comments are
> "relevant".
Actually this is what i am interested in. I like to avoid that
the user has to think about special tags and so on. I am
currently playing around with certain heutistics based on a
minimal common sense snytax, e.g.

Description
===========

....textblock ...


Means, the text block is a description, or e.g.

...listed below:

   * Item 1.....
   * Item 2 .....

is a list, where a list is always introduced by the ':' at the end
of a line and so on.


The input format should be a "normal" as possible in order to
avoid costly reformatting of older source parts.



> 
> 
>>In order to do so such a program requieres certain key words.
>>Theretically the comment in the source could already contain docbook
>>format but i dont like the idea, since the comments are getting
>>unreadable. I gues what i am looking for i a tool which is abble to
>>retrieve sections identified by headlines from normal and to convert
>>it into docbook format. Copying in the specification of a procedure
>>is the minor part of it.
> 
> 
> Ok, you want a somewhat elaborate syntax in the comments. AdaBrowse at
> least gets you the top level source traversal, and lets you write the
> comment parsing in Ada. Use GNAT.Spitbol or GNAT.Regexp, or
> Ada.Strings.Fixed, or OpenToken.
> 
> 
>>Any way, adabrowser is based on asis, which requieres that the
>>module is compilable which i cannot gurantee.
> 
> 
> Why not? Surely you want to know that the document is accurate, which
> means that the Ada code compiles! Otherwise you could have
> inconsistent information!
> 
May be you are right about this point. I think i will first
play with the heuristics above, then think about integrating
it into a tool like ada browser.

> Sometimes in reverse engineering an application, the code does not yet
> compile because you have switched compilers or OSs or something. But
> in that case, I don't see how this sort of documentation can help;
> it's really just a prettier form of the source. If you were attempting
> to create top-level withing charts or data flows, then being able to
> process non-compilable code might be relevant.
> 
I am not focussing on reverese engeneering. I like to have a cheap
way of extracting the "important" parts of library components into
docbook documentation.

Regards
    M.Erdmann

Re: Q: Generating Documenation from Ada Sources?

[tmoran]

> > conventions in coding style, so AdaBrowse+ can know which comments are
> > "relevant".
>...
> currently playing around with certain heutistics based on a
> minimal common sense snytax, e.g.

  We went a different way, since most of the source files already
existed, including customer's copies, and we didn't want to change
them.  We have a database of information, for instance every entity
has a Remarks section (which of course may be empty) and a Spec
section.  Subprograms additionally have an Exceptions Raised section,
and so forth.  These are filled in as much as possible by a program
that scans source files for specs, links, comments saying "Raises ..."
directly following a subprogram etc.  But this is viewed as just a
convenience.  We expect most of the text to be entered, or at least
modified by, a human writer.  Syntactic information like the file
something is declared in, the package to "with" for it, any
predefined constants of a type, etc comes from scanning the source
code and is not modified by the documentation writer.

Re: Q: Generating Documenation from Ada Sources?

[Stefan Revets]

In article <abodj8$9s$1@a1-hrz.uni-duisburg.de>, Georg Bauhaus
<sb463ba@l1-hrz.uni-duisburg.de> wrote:

> Stefan Revets <srevets@nospam.geol.uwa.edu.au> wrote:
> : 
> : Literate programming is another option. There is an AdaTangle and AdaWeave
> : around, implementing the ideas of Donald Knuth.
> 
> It is Ada 83 though.
> 
> ftp://www.ctan.org/pub/tex/web/ada/aweb/

True. But Norman Ramsey wrote Spidery Web which allows one to generate
*Tangle and *Weave for about any language desired. Using awk, you define
the things you desire to be done with the language of choice, process it
and build both tangle and weave from it. Norman Ramsey included and
Ada.spider file: it should require that much investment of time to get an
Ada* version.

iirc, it can be found at ftp://www.ctan.org/pub/tex/web/spider/

Stefan

-- 
Stefan A. Revets
Department of Geology & Geophysics, University of Western Australia
Nedlands, WA6907
Australia

Re: Q: Generating Documenation from Ada Sources?

[Michael Erdmann]

tmoran@acm.org wrote:
>>>conventions in coding style, so AdaBrowse+ can know which comments are
>>>"relevant".
>>
>>...
>>currently playing around with certain heutistics based on a
>>minimal common sense snytax, e.g.
> 
> 
>   We went a different way, since most of the source files already
> existed, including customer's copies, and we didn't want to change
> them.  We have a database of information, for instance every entity
> has a Remarks section (which of course may be empty) and a Spec
> section.  Subprograms additionally have an Exceptions Raised section,
> and so forth.  These are filled in as much as possible by a program
> that scans source files for specs, links, comments saying "Raises ..."
> directly following a subprogram etc.  But this is viewed as just a
> convenience.  We expect most of the text to be entered, or at least
> modified by, a human writer.  Syntactic information like the file
> something is declared in, the package to "with" for it, any
> predefined constants of a type, etc comes from scanning the source
> code and is not modified by the documentation writer.
So you generated a templacte out of the source which might be
modified by the author.

May be this is one way to go. My Problem is that i like to make
it as easy as possible for an author to submit a package with
reasonable documentation. May be process could be like this:

Step 1 - Author presents package to the libary management
Step 2 - A tool is running over the software which generating a
          reasonable deocumentation skeleton.
Step 3 - Author updates the relevant sections
Step 4 - Final checkin, tooling checks  the contents of the
          documentation in the code and converts it to docbook!

Michael