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-Thread: 103376,81054609038e88e3,start X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news2.google.com!fu-berlin.de!uni-berlin.de!not-for-mail From: Nick Roberts Newsgroups: comp.lang.ada Subject: Literate Programming in Ada, AdaDoc, AdaBrowse Date: Sat, 09 Oct 2004 18:44:43 +0100 Message-ID: <2sqmccF1oit5sU1@uni-berlin.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Trace: news.uni-berlin.de yFuDxsE1SwokwE7CIMf+gQWtthgFW4e7TCAJ5BrxNV/6Yxczo= User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.2) Gecko/20040803 X-Accept-Language: en-us, en Xref: g2news1.google.com comp.lang.ada:4958 Date: 2004-10-09T18:44:43+01:00 List-Id: 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. -- Nick Roberts