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!usenet-fr.net!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: Sun, 10 Oct 2004 12:26:50 +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 1097407621 50720 212.85.156.195 (10 Oct 2004 11:27:01 GMT) X-Complaints-To: usenet@melchior.cuivre.fr.eu.org NNTP-Posting-Date: Sun, 10 Oct 2004 11:27:01 +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-OriginalArrivalTime: 10 Oct 2004 11:26:47.0330 (UTC) FILETIME=[0754D020:01C4AEBC] 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:4986 Date: 2004-10-10T12:26:50+01:00 I appreciate the requirement for some kind of master system containing both documentation and program elements. The original Knuthian literate programming idea was not special comments in the source code but the other way around, source code fragments embedded in the text, which text being a piece of technical literature describing the system under construction. It's not just a difference of perspective. Documentation and source code are two very different things, and one should not step on the feet of the other. Overloading the source code with documentation elements ruins the source code. Lately I've been putting all comments, if any, in the bottom of the source code file. And of course one should always write code in a way that it reduces the need for comments. When some unit needs extensive commentary, the place for that is in a separate file. The link between documentation and source code items is based on the names of the source code entities. This model is sufficient even for hypertext generation. The rest is pretty printing :-)