* Q: Generating Documenation from Ada Sources? @ 2002-05-11 14:59 Michael Erdmann 2002-05-11 18:29 ` Robert Dewar 2002-05-13 5:36 ` Stefan Revets 0 siblings, 2 replies; 16+ messages in thread From: Michael Erdmann @ 2002-05-11 14:59 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-11 14:59 Q: Generating Documenation from Ada Sources? Michael Erdmann @ 2002-05-11 18:29 ` Robert Dewar 2002-05-11 19:07 ` Michael Erdmann 2002-05-13 5:36 ` Stefan Revets 1 sibling, 1 reply; 16+ messages in thread From: Robert Dewar @ 2002-05-11 18:29 UTC (permalink / raw) 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? ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-11 18:29 ` Robert Dewar @ 2002-05-11 19:07 ` Michael Erdmann 2002-05-12 2:05 ` Randy Brukardt 0 siblings, 1 reply; 16+ messages in thread From: Michael Erdmann @ 2002-05-11 19:07 UTC (permalink / raw) To: Robert Dewar 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-11 19:07 ` Michael Erdmann @ 2002-05-12 2:05 ` Randy Brukardt 2002-05-12 7:35 ` Michael Erdmann 0 siblings, 1 reply; 16+ messages in thread From: Randy Brukardt @ 2002-05-12 2:05 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-12 2:05 ` Randy Brukardt @ 2002-05-12 7:35 ` Michael Erdmann 2002-05-12 8:12 ` Dr. Michael Paus 0 siblings, 1 reply; 16+ messages in thread From: Michael Erdmann @ 2002-05-12 7:35 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-12 7:35 ` Michael Erdmann @ 2002-05-12 8:12 ` Dr. Michael Paus 2002-05-12 15:23 ` Michael Erdmann 0 siblings, 1 reply; 16+ messages in thread From: Dr. Michael Paus @ 2002-05-12 8:12 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-12 8:12 ` Dr. Michael Paus @ 2002-05-12 15:23 ` Michael Erdmann 2002-05-12 17:49 ` tmoran 2002-05-13 14:11 ` Stephen Leake 0 siblings, 2 replies; 16+ messages in thread From: Michael Erdmann @ 2002-05-12 15:23 UTC (permalink / raw) 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 > ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-12 15:23 ` Michael Erdmann @ 2002-05-12 17:49 ` tmoran 2002-05-12 20:43 ` Ira D. Baxter 2002-05-13 14:11 ` Stephen Leake 1 sibling, 1 reply; 16+ messages in thread From: tmoran @ 2002-05-12 17:49 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-12 17:49 ` tmoran @ 2002-05-12 20:43 ` Ira D. Baxter 0 siblings, 0 replies; 16+ messages in thread From: Ira D. Baxter @ 2002-05-12 20:43 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-12 15:23 ` Michael Erdmann 2002-05-12 17:49 ` tmoran @ 2002-05-13 14:11 ` Stephen Leake 2002-05-13 20:21 ` Michael Erdmann 1 sibling, 1 reply; 16+ messages in thread From: Stephen Leake @ 2002-05-13 14:11 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-13 14:11 ` Stephen Leake @ 2002-05-13 20:21 ` Michael Erdmann 2002-05-13 22:25 ` tmoran 0 siblings, 1 reply; 16+ messages in thread From: Michael Erdmann @ 2002-05-13 20:21 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-13 20:21 ` Michael Erdmann @ 2002-05-13 22:25 ` tmoran 2002-05-14 18:01 ` Michael Erdmann 0 siblings, 1 reply; 16+ messages in thread From: tmoran @ 2002-05-13 22:25 UTC (permalink / raw) > > 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-13 22:25 ` tmoran @ 2002-05-14 18:01 ` Michael Erdmann 0 siblings, 0 replies; 16+ messages in thread From: Michael Erdmann @ 2002-05-14 18:01 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-11 14:59 Q: Generating Documenation from Ada Sources? Michael Erdmann 2002-05-11 18:29 ` Robert Dewar @ 2002-05-13 5:36 ` Stefan Revets 2002-05-13 13:03 ` Georg Bauhaus 1 sibling, 1 reply; 16+ messages in thread From: Stefan Revets @ 2002-05-13 5:36 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-13 5:36 ` Stefan Revets @ 2002-05-13 13:03 ` Georg Bauhaus 2002-05-14 5:20 ` Stefan Revets 0 siblings, 1 reply; 16+ messages in thread From: Georg Bauhaus @ 2002-05-13 13:03 UTC (permalink / raw) 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/ ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Q: Generating Documenation from Ada Sources? 2002-05-13 13:03 ` Georg Bauhaus @ 2002-05-14 5:20 ` Stefan Revets 0 siblings, 0 replies; 16+ messages in thread From: Stefan Revets @ 2002-05-14 5:20 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
end of thread, other threads:[~2002-05-14 18:01 UTC | newest] Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2002-05-11 14:59 Q: Generating Documenation from Ada Sources? Michael Erdmann 2002-05-11 18:29 ` Robert Dewar 2002-05-11 19:07 ` Michael Erdmann 2002-05-12 2:05 ` Randy Brukardt 2002-05-12 7:35 ` Michael Erdmann 2002-05-12 8:12 ` Dr. Michael Paus 2002-05-12 15:23 ` Michael Erdmann 2002-05-12 17:49 ` tmoran 2002-05-12 20:43 ` Ira D. Baxter 2002-05-13 14:11 ` Stephen Leake 2002-05-13 20:21 ` Michael Erdmann 2002-05-13 22:25 ` tmoran 2002-05-14 18:01 ` Michael Erdmann 2002-05-13 5:36 ` Stefan Revets 2002-05-13 13:03 ` Georg Bauhaus 2002-05-14 5:20 ` Stefan Revets
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox