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,FREEMAIL_FROM, 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!freenix!enst.fr!melchior!cuivre.fr.eu.org!melchior.frmug.org!not-for-mail From: Marius Amado Alves Newsgroups: comp.lang.ada Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse Date: Mon, 18 Oct 2004 16:39:51 +0100 Organization: Cuivre, Argent, Or Message-ID: References: <2sqmccF1oit5sU1@uni-berlin.de> <2sr4jaF1od20uU1@uni-berlin.de> NNTP-Posting-Host: lovelace.ada-france.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Trace: melchior.cuivre.fr.eu.org 1098114021 46218 212.85.156.195 (18 Oct 2004 15:40:21 GMT) X-Complaints-To: usenet@melchior.cuivre.fr.eu.org NNTP-Posting-Date: Mon, 18 Oct 2004 15:40:21 +0000 (UTC) To: comp.lang.ada@ada-france.org Return-Path: User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.4) Gecko/20030624 Netscape/7.1 (ax) X-Accept-Language: en-us, en In-Reply-To: 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.5 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:5402 Date: 2004-10-18T16:39:51+01:00 > If there's anything special I need to be aware of about a particular > function, then I want it to be noted in the most obvious place. I don't > want to scroll down to check if perchance there might be a note about > this function at the bottom of the file. Agreed. In this example there is nothing really special, but there are cases e.g. the infamous warning "the programmer is responsible for freeing this object". In those cases a *small* warning should be placed near the entities. > You also removed some important information: Where does the > parameterless Get_Line read from? Which line does it get? Does it always > return the whole line, from line break to line break, or could it be > just part of the line in some cases? If so, which part and in which > cases? We can assume that the second Get_Line reads from the file we > pass to it, but does it otherwise work the same as the first Get_Line or > are there any differences? The original file answers all of those > questions. All obvious answers, and so should be separate, if present at all. 1. http://www.liacc.up.pt/~maa/files/g-io_aux.ads 2. http://www.liacc.up.pt/~maa/files/g-io_aux-edited.ads 3. http://www.liacc.up.pt/~maa/files/g-io_aux-notes.html Note these are just fabricated outputs of an idealized master system for organizing source code with documentation. One viewable item can actually be the overloaded-with-comments source code file 1 which the tool keeps syncronized with 2 and 3. Then all views would be available for all tastes. (Hey, I just described a big part of my PhH hypothesis, Adaptive Hypertext :-) The main (sub)thesis here was that the information required to make the necessary connections is there in the position of the notes in 1 and in the names of the formal entities. No visible special markers necessary.