From: Marius Amado Alves <amado.alves@netcabo.pt>
To: comp.lang.ada@ada-france.org
Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse
Date: Sun, 10 Oct 2004 12:26:50 +0100
Date: 2004-10-10T12:26:50+01:00 [thread overview]
Message-ID: <mailman.253.1097407620.390.comp.lang.ada@ada-france.org> (raw)
In-Reply-To: <ur7o63lmp.fsf@obry.org>
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 :-)
next prev parent reply other threads:[~2004-10-10 11:26 UTC|newest]
Thread overview: 65+ messages / expand[flat|nested] mbox.gz Atom feed top
2004-10-09 17:44 Literate Programming in Ada, AdaDoc, AdaBrowse Nick Roberts
2004-10-09 18:39 ` Wes Groleau
2004-10-09 21:04 ` Nick Roberts
2004-10-09 21:39 ` stephane richard
2004-10-09 23:40 ` Wes Groleau
2004-10-10 16:39 ` Simon Wright
2004-10-12 0:42 ` Georg Bauhaus
2004-10-11 7:33 ` Ole-Hjalmar Kristensen
2004-10-09 19:21 ` Pascal Obry
2004-10-09 21:47 ` Nick Roberts
2004-10-09 23:20 ` Björn Persson
2004-10-10 8:28 ` Oliver Kellogg
2004-10-10 10:03 ` Björn Persson
2004-10-10 15:27 ` Stephen Leake
2004-10-09 23:49 ` Wes Groleau
2004-10-10 10:36 ` Pascal Obry
2004-10-10 11:26 ` Marius Amado Alves [this message]
2004-10-18 8:17 ` Jacob Sparre Andersen
2004-10-18 11:15 ` Marius Amado Alves
2004-10-18 12:46 ` Björn Persson
2004-10-18 15:39 ` Marius Amado Alves
2004-10-18 13:47 ` Jacob Sparre Andersen
2004-10-09 22:54 ` Lionel Draghi
2004-10-09 22:56 ` Björn Persson
2004-10-09 23:55 ` Wes Groleau
2004-10-10 1:02 ` Björn Persson
2004-10-10 14:02 ` Wes Groleau
2004-10-10 3:29 ` Steve
2004-10-10 14:08 ` Wes Groleau
2004-10-10 15:06 ` Steve
2004-10-10 15:20 ` Stephen Leake
[not found] ` <rlsfz4jdjuj.fsf@jacob.crs4.it>
2004-10-15 13:33 ` Marius Amado Alves
2004-10-16 1:50 ` Steve
2004-10-16 19:46 ` Jacob Sparre Andersen
2004-10-17 3:46 ` Steve
2004-10-10 8:21 ` Stephane Riviere
2004-10-11 23:02 ` Björn Persson
2004-10-11 23:31 ` Missing features in NaturalAdaBrowseDoc Lionel Draghi
2004-10-12 0:14 ` tmoran
2004-10-12 12:58 ` Marc A. Criley
2004-10-12 21:20 ` Lionel Draghi
2004-10-12 17:49 ` Stephane Riviere
[not found] ` <416c48a7$0$28918$636a15ce@news.free.fr>
2004-10-12 21:18 ` Lionel Draghi
2004-10-13 16:38 ` Stephane Riviere
2004-10-14 19:56 ` Lionel Draghi
2004-10-15 16:59 ` Stephane Riviere
2004-10-12 17:29 ` Literate Programming in Ada, AdaDoc, AdaBrowse Stephane Riviere
2004-10-10 9:34 ` Andre
2004-10-10 15:24 ` Stephen Leake
2004-10-10 18:04 ` Andre
2004-10-11 23:32 ` Lionel Draghi
2004-10-12 0:13 ` Björn Persson
2004-10-10 15:13 ` Stephen Leake
2004-10-11 20:28 ` Nick Roberts
2004-10-11 22:26 ` Björn Persson
2004-10-12 14:09 ` Nick Roberts
2004-10-13 5:01 ` Pylinius
2004-10-13 16:06 ` Nick Roberts
2004-10-13 17:17 ` Pascal Obry
2004-10-17 18:47 ` Bernhard Mulder
2004-10-18 18:06 ` Nick Roberts
2004-10-19 4:41 ` Bernhard Mulder
2004-10-19 9:52 ` Peter Hermann
2004-10-19 10:01 ` Nick Roberts
2004-10-23 21:39 ` Bernhard Mulder
replies disabled
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox