From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,41cdd08c4c779b88 X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2002-05-13 13:17:32 PST Path: archiver1.google.com!news1.google.com!newsfeed.stanford.edu!news-spur1.maxwell.syr.edu!news.maxwell.syr.edu!news-han1.dfn.de!news-fra1.dfn.de!unlisys!news.snafu.de!news.eusc.inter.net!boavista!nobody From: Michael Erdmann Newsgroups: comp.lang.ada Subject: Re: Q: Generating Documenation from Ada Sources? Date: Mon, 13 May 2002 22:21:04 +0200 Organization: [Posted via] Inter.net Germany GmbH Message-ID: <3CE02030.7040500@snafu.de> References: <3CDD31D7.2060005@snafu.de> <5ee5b646.0205111029.3cde679@posting.google.com> <3CDD6BD7.5010503@snafu.de> <3CDE1B39.9060000@snafu.de> <3CDE2404.5030008@ib-paus.com> <3CDE88E1.70107@snafu.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Trace: news.eusc.inter.net 1021321051 21345 213.73.65.81 (13 May 2002 20:17:31 GMT) X-Complaints-To: abuse@eusc.inter.net User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.0rc1) Gecko/20020417 X-Accept-Language: en-us, en Xref: archiver1.google.com comp.lang.ada:23978 Date: 2002-05-13T22:21:04+02:00 List-Id: Stephen Leake wrote: > Michael Erdmann 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