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=-2.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI autolearn=unavailable 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!news2.google.com!proxad.net!usenet-fr.net!enst.fr!melchior!cuivre.fr.eu.org!melchior.frmug.org!not-for-mail From: Stephen Leake Newsgroups: comp.lang.ada Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse Date: 10 Oct 2004 11:13:36 -0400 Organization: Cuivre, Argent, Or Message-ID: References: <2sqmccF1oit5sU1@uni-berlin.de> NNTP-Posting-Host: lovelace.ada-france.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: melchior.cuivre.fr.eu.org 1097422286 97860 212.85.156.195 (10 Oct 2004 15:31:26 GMT) X-Complaints-To: usenet@melchior.cuivre.fr.eu.org NNTP-Posting-Date: Sun, 10 Oct 2004 15:31:26 +0000 (UTC) To: comp.lang.ada@ada-france.org Return-Path: In-Reply-To: <2sqmccF1oit5sU1@uni-berlin.de> User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3 X-Virus-Scanned: by amavisd-new-20030616-p10 (Debian) at ada-france.org X-BeenThere: comp.lang.ada@ada-france.org X-Mailman-Version: 2.1.4 Precedence: list List-Id: "Gateway to the comp.lang.ada Usenet newsgroup" List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Xref: g2news1.google.com comp.lang.ada:4996 Date: 2004-10-10T11:13:36-04:00 Nick Roberts writes: > 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. That is certainly important. > 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. I use Texinfo or LaTeX, for things that are too complex for Ada comments. > I agree, LP is not a good choice. However, I think the motivation behind LP is still valid. That is, "find a way to keep documentation up to date". The LP approach to that is to integrate the documentation source with the code source. But I think the reason that works is developers can easily edit documentation and code source _within the same editor_. That suggests a different approach; different files and syntax for documentation source, but an Integrated Development Environment that can handle both with ease. Emacs and GPS and others are such an IDE for Ada, Texinfo, and LaTeX. > 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. This is what AdaBrowse does. Since it is based on comments in the Ada code, I don't think it solves the problem of how to document "things that are too complex for Ada comments". It can produce nice summaries of packages and type heirarchies, which is also a good thing; it helps people learn how the code works, and/or how to use the code. > 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. I think it is more important to focus on the information presented, and less on the mechanism to do that. There are some design decisions that simply can't be documented nicely in Ada comments. For a simple example, the design rule that all constructors should be declared in nested packages. You don't want to repeat that in every package, and you don't want to designate one package as the "prime document package". For a more complex example, the documentation of how signals are handled in Gtk needs its own separate document. > * 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). Emacs Ada mode does this. So does GPS. I consider this a minimum requirement for any IDE. (In my opinion, PFE is _not_ a good IDE). > * 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). Why would this be useful? If you want it, use --#include; at least it will be recognized. > * 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; What, exactly, does this mean? The line number before or after all (or some?) substitutions are made? See the C preprocessor for possible answers to this question. > * "FILE", which is replaced by the full pathname of the source file; > > * "DATE", which is replaced by the current date and time. Why would these be useful? These are configuration management issues, not design documentation issues. "Current" when the file is loaded into the IDE? when the file is processed by this tool? When the file was last written to disk? None of these are very meaningful. > I also propose writing another quite simple Ada program which will > generate an HTML rendition of an Ada source file. AdaBrowse does this. If you think it needs more features, please add them. Leverage other people's work, don't re-invent it. > Also being able to generate an Texinfo rendition might be very handy, > as well as XML (DocBook), TeX, or other formats. Exactly _why_ would these be handy? You are proposing a lot of work, with very little justification. I want documentation to be fully searchable. I find it hard to search a collection of html pages, but you could argue that's a browser function. For example, Texinfo is searchable only because the Emacs Info browser supports it. Any Open Source format that is fully searchable via an Open Source browser is fine with me. Hmm. I really do prefer the browser to be integrated with the IDE (Emacs in my case). I believe the bleeding edge Emacs can display rendered HTML, even on Windows. But I still want full searching. > 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); Why is this a problem? In my opinion, you run AdaBrowse only when you do a release of a project (that's what I do for SAL). The generated documentation is for people who need to learn the package, not for the package developer; the Ada code and comments should be good enough for them. > a compiler which supports ASIS must be available. Well, the only Open Source Ada compiler is GNAT, and ASIS is available for it. So this is a moot point (for a fully Open Source project). > It does seem almost like using a sledgehammer to crack a nut. ASIS is a way to access the Ada parser in the compiler front end. Any tool that parses Ada code should use the compiler front end; otherwise it's duplicating work. Not to mention probably wrong. Learning to use ASIS well does take time. Perhaps for "a simple comment parser", you don't need to parse the Ada code. But I don't think the results of "a simple comment parser" would be worth having. Learning to add to AdaBrowse should be simpler than learning to use ASIS from scratch (I have not looked at the AdaBrowse sources). I suggest you give it a try. -- -- Stephe