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,FREEMAIL_FROM autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,81054609038e88e3 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news1.google.com!news.glorb.com!news2.telebyte.nl!newshub2.home.nl!newshub1.home.nl!home.nl!not-for-mail From: Andre Newsgroups: comp.lang.ada Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse Date: Sun, 10 Oct 2004 11:34:15 +0200 Organization: @Home Benelux Message-ID: References: <2sqmccF1oit5sU1@uni-berlin.de> NNTP-Posting-Host: cp538812-a.venra1.lb.home.nl Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Trace: news6.zwoll1.ov.home.nl 1097400856 3043 84.30.194.114 (10 Oct 2004 09:34:16 GMT) X-Complaints-To: usenet@corp.home.nl NNTP-Posting-Date: Sun, 10 Oct 2004 09:34:16 +0000 (UTC) User-Agent: Mozilla Thunderbird 0.8 (Windows/20040913) X-Accept-Language: en-us, en In-Reply-To: <2sqmccF1oit5sU1@uni-berlin.de> Xref: g2news1.google.com comp.lang.ada:4983 Date: 2004-10-10T11:34:15+02:00 List-Id: Nick Roberts wrote: > Time for the latest hairbrained scheme from your uncle Nicky. > > I've been struggling with the question of how best to do the > documentation accompanying open source Ada projects. It is especially > important that the maintenance (as well as user) documentation is > present, usable, and itself continuously maintainable, for this kind of > project. > > I've tinkered with DocBook, Texinfo, and other systems (even trying to > invent one of my own). I've attempted to add 'literate programming' > functionality to these systems. > > Literate programming is a fancy way of documenting source code. The > basic idea is that you break up the source code into fragments, and > intersperse appropriate documentation with the fragments. The fragments > can be reordered, and referentially contain other fragments (to form a > hierarchy). This technique is capable of producing superbly documentated > source code, since you can introduce concepts in the order which best > fits explication, and show just the source code that needs to be > described as you go along. > > However, LP has problems. The classic mechanism requires that orignal > program and document source text be intermixed in a single or set of > physical text files, called 'web' files (nothing to do with the WWW). A > 'tangle' tool must be run to generate the actual source code files > (which can be submitted to the compiler). This adds a new step, > potentially a big and slow one, to the program development cycle. An > alternate approach has been the idea of a mechanism to update the web > files from changes made directly in the source code files, but this > technique does not seem to have got very far. > > Up to now, I've been opposed to the idea of putting the main > (maintenance) documentation directly into the Ada source files > (particularly the package specifications), on the grounds that this > prevents the use of existing document preparation systems. > > However, I'm now coming around to the idea. My latest hairbrained scheme > is to write a program that will do a little bit of work reformatting > comments in an Ada source file. I'm fairly sure it's not an original > idea, but I cannot actually find references (on the WWW) to such a tool. > Can emacs Ada Mode do something like this? My favourite editor is PFE > (for Windows). It has a limited macro capability, but it's too limited > for something like this. > > Besides which, different people have differrent editors and document > preparation systems (as a matter of availability or choice), and so an > open source project ideally needs to be as agnostic on these things as > possible. > > So I propose to write a simple Ada program that will perform the > following transformations on an Ada source file: > > * If a line begins with "-- " (not indented), it and any immediately > following non-blank lines are word-filled. Before word-filling, any "-- > " at the beginning of a line is removed. After word-filling, every > output line is prefixed by "-- ". Words are simply delimited by > whitespace (there's no hyphenation or other fancy stuff). > > * If a line begins with "--+", the remainder of the line is taken to be > a pathname of a text file, whose contents are read. All following lines > up to (but not including) a line beginning with "---" are deleted. The > lines read from the text file are inserted, after having macro > substitutions performed (as described next). > > * Any occurrance of "${" followed by a name-string and then "}" is > replaced by another string according to the name-string, iff the > name-string is recognised. > > Recognised name-strings are: > > * "LINE", which is replaced by the current line number in the source file; > > * "FILE", which is replaced by the full pathname of the source file; > > * "DATE", which is replaced by the current date and time. > > I also propose writing another quite simple Ada program which will > generate an HTML rendition of an Ada source file. Features that could be > incrementally added to this program could be: > > * colour-code the Ada source text (highlighting reserved words, > literals, etc.); > > * simple formatting of the text in unindented comments (e.g. embolden > !never!, italicise /always/, -tag text between {} braces, etc.); > > * index the identifiers, including identifiers within braces within > unindented comments. > > Also being able to generate an Texinfo rendition might be very handy, as > well as XML (DocBook), TeX, or other formats. > > These ideas lead us to the existing AdaDoc and AdaBrowse projects, both > hosted on SourceForge. These seem to be very relevant to what I'm trying > to achieve. However: development on AdaDoc seems to have stopped (since > 2002); AdaBrowse relies on ASIS. > > AdaDoc is written substantially in French (by Frenchmen). I don't > personally have any objection to developing software in French, but it > might seem less than ideal to some people. (Does it?) Is AdaDoc a dead > project? > > There are two reasons why I have an objection to the use of ASIS: > AdaBrowse cannot be used on a source file which cannot be compiled (e.g. > because it is still in an early state of development, or it has an > unresolved error in it); a compiler which supports ASIS must be > available. It does seem almost like using a sledgehammer to crack a nut. > > Comments welcome. > I think you need to keep it simple (as many of the replies also state) Here a sample of how I write down my comment in the source code. -- .Operation: Put a date-time in a string -- .Preconditions: -- .in: FTime, the date-time -- .Semantics: -- Format the date-time in yyyy-mm-dd hh:mm:ss.mmm -- .Postconditions: -- .return: a string with the date-time function Date_As_Str (SysTime : SYSTEMTIME) return String; I have written a small program which takes the main ada source file as input and browses all 'with's to parse all source files. Each source file gets its onw HTML file with documentation. I use '-- .:' to detect if it is valid documentation. Of course this can be extended with additional stuff to format the documentation, add images, hyperlinks and .... When I finish a (re)design or want an update of my documentation, I just run my own program to create the HTML pages. I also create a Microsoft help project with all the HTML files. Then I can create a Compiled Help file, which I can print to paper or to PDF using PDF Creator.