From MAILER-DAEMON Sun Nov 06 09:11:58 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RN3S2-0006CW-PO
	for mharc-axiom-developer@gnu.org; Sun, 06 Nov 2011 09:11:58 -0500
Received: from eggs.gnu.org ([140.186.70.92]:59634)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RN3S0-0006CQ-NX
	for axiom-developer@nongnu.org; Sun, 06 Nov 2011 09:11:57 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RN3Rz-00055m-Lu
	for axiom-developer@nongnu.org; Sun, 06 Nov 2011 09:11:56 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:36240
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RN3Rz-00055h-Hy
	for axiom-developer@nongnu.org; Sun, 06 Nov 2011 09:11:55 -0500
Received: from axiom-developer.org (lincoln.rosehosting.com [127.0.0.1])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pA6EBp75018482;
	Sun, 6 Nov 2011 08:11:51 -0600
From: daly@axiom-developer.org
Received: (from daly@localhost)
	by axiom-developer.org (8.12.8/8.12.8/Submit) id pA6EBo4H018479;
	Sun, 6 Nov 2011 08:11:50 -0600
Date: Sun, 6 Nov 2011 08:11:50 -0600
Message-Id: <201111061411.pA6EBo4H018479@axiom-developer.org>
To: "Waldek Hebisch" <hebisch@math.uni.wroc.pl>
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: [Axiom-developer] Clarification
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sun, 06 Nov 2011 14:11:57 -0000

Waldek,

It appears that the topic of merging systems has hit the fricas mailing list.

Two comments puzzle me.

  "Concerning merge, IMO merging back with Axiom is out of question -- the
   project go in too different directions (one trivial (but easy to 
   understand) example beeing that I spent several months removing trash
   from FriCAS while Axiom at the same time added more trash)."

What "trash" has Axiom added?



  "In FriCAS I deliberately limited changes to Spad language (to maximize
   compatibility with existing code)..."

Actually there is a subtle issue that make FriCAS Spad code non-portable.
There are new lisp functions quietly introduced that only exist in FriCAS
(e.g. GETREFV32) but are referenced in the Spad code. This code compiles 
but fails at runtime. 

There is no mention of this incompatibility in the pamphlet file
(u32vec.spad.pamphlet). The whole reason to use literate programming
is to communicate such facts to other people.




The use of literate programming is likely to be the main reason why
FriCAS (and OpenAxiom) will never merge back. I would like to keep the
algebra compatible.  I do my best to keep up with the new and changed
algebra but it is a bit of a challenge. The new algebra is packaged in
pamphlet files but there is no actual use of the literate style. New
algebra is not explained, there is no connection shown between theory
and its reduction to practice. There are no examples. There are no notes
to explain why new domains have incompatibilities that deviate from the
Spad language and will not compile in Axiom.

In fact, there is no attempt to communicate with the reader at all. 
The files contain raw Spad code. Why do you keep pamphlet files?

Tim







From MAILER-DAEMON Mon Nov 07 20:05:17 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNa7p-0005Ys-Cb
	for mharc-axiom-developer@gnu.org; Mon, 07 Nov 2011 20:05:17 -0500
Received: from eggs.gnu.org ([140.186.70.92]:48267)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <leonbaum2@gmail.com>) id 1RNa7m-0005Vr-5t
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 20:05:15 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <leonbaum2@gmail.com>) id 1RNa7k-0001EY-Qk
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 20:05:14 -0500
Received: from mail-vx0-f173.google.com ([209.85.220.173]:35160)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <leonbaum2@gmail.com>) id 1RNa7k-0001ER-O9
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 20:05:12 -0500
Received: by vcbf13 with SMTP id f13so4324141vcb.4
	for <axiom-developer@nongnu.org>; Mon, 07 Nov 2011 17:05:11 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=from:to:subject:date:message-id:user-agent:mime-version
	:content-type:content-transfer-encoding;
	bh=ubmfmn5VtF2vnp7Q8RzbecMQgIpM0xeZ4wBaC+g3QeM=;
	b=rp2gD+UIWYDA0aiY26HwtesqcHBXAyz/uVjiFUYhSdrOKACHvFVeKHjVVfuVUYA0En
	uDwWiB4s0UMZSbrVIFL+UjzzYS1QM8R2icKSaAmNk7uVrb+Y8ZAbem+uvl8T8XoWi5aV
	O0Kj4FgulN5gHe9OGvorp5pyugqUlS0YMGSSI=
Received: by 10.52.30.47 with SMTP id p15mr29373189vdh.79.1320714311570;
	Mon, 07 Nov 2011 17:05:11 -0800 (PST)
Received: from localhost (pool-108-5-82-190.nwrknj.east.verizon.net.
	[108.5.82.190])
	by mx.google.com with ESMTPS id bu10sm32930337vdb.3.2011.11.07.17.05.09
	(version=TLSv1/SSLv3 cipher=OTHER);
	Mon, 07 Nov 2011 17:05:10 -0800 (PST)
From: Leon Baum <leonbaum2@gmail.com>
To: axiom-developer@nongnu.org
Date: Mon, 07 Nov 2011 20:05:08 -0500
Message-ID: <878vnrzanv.fsf@gmail.com>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.90 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 209.85.220.173
Subject: [Axiom-developer] Newer GCL needed for gcc-4.6?
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 01:05:15 -0000


Hello,

I've been using my distro's packaged version of FriCAS, but I wanted to
try AXIOM because I like the idea of literate programming.

I ended up getting a github snapshot compiled with gcc-4.5, but just in
case you aren't already aware, I wanted to let you know that the bundled
version of GCL has problems with gcc-4.6.

According to the GCL mailing list [1] and a Debian bug report [2], it
looks like the problems have been already fixed upstream, so simply
updating GCL should fix things in AXIOM.

Error snippet:
...
Compiling gcl_cmpwt.lsp.
Loading ./gcl_cmpinit.lsp
Loading ../lsp/sys-proclaim.lisp
Finished loading ../lsp/sys-proclaim.lisp
Loading sys-proclaim.lisp
Finished loading sys-proclaim.lisp
Finished loading ./gcl_cmpinit.lsp
End of Pass 1.=20=20

Error: Someone tried to RETURN-FROM a TAGBODY.
Error signalled by LET.
Backtrace: system::gcl-top-level > if > let > setq > system:error-set > sys=
tem:error-set > progn > compile-file > loop > setq > apply > apply > compil=
e-file1 > let > unwind-protect > progn > let* > let > unwind-protect > prog=
n > when > compiler-pass2 > let > unwind-protect > progn > let > let > unwi=
nd-protect > progn > catch > ctop-write > do* > when > apply > apply > t3de=
fun > cond > analyze-regs > let > cond > let > analyze-regs1 > let > tagbod=
y > system:universal-error-handler > let > let > cond > apply > apply > sys=
tem:universal-error-handler > system::break-level > let* > UNLESS
gcl_cmpwt.c: In function =E2=80=98init_gcl_cmpwt=E2=80=99:
gcl_cmpwt.c:4:39: error: =E2=80=98VV=E2=80=99 undeclared (first use in this=
 function)
...


Leon

[1] http://lists.gnu.org/archive/html/gcl-devel/2011-04/msg00005.html
[2] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=3D625032


From MAILER-DAEMON Mon Nov 07 20:11:50 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNaEA-0006NP-1b
	for mharc-axiom-developer@gnu.org; Mon, 07 Nov 2011 20:11:50 -0500
Received: from eggs.gnu.org ([140.186.70.92]:49017)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNaE7-0006Kt-Hr
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 20:11:48 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNaE6-00024g-Cv
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 20:11:47 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:40468
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNaE6-00024R-8x
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 20:11:46 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pA81Bg75009260;
	Mon, 7 Nov 2011 19:11:43 -0600
From: daly <daly@axiom-developer.org>
To: Leon Baum <leonbaum2@gmail.com>
In-Reply-To: <878vnrzanv.fsf@gmail.com>
References: <878vnrzanv.fsf@gmail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Mon, 07 Nov 2011 20:11:08 -0500
Message-ID: <1320714668.30722.1164.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: quoted-printable
X-MIME-Autoconverted: from 8bit to quoted-printable by axiom-developer.org id
	pA81Bg75009260
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Newer GCL needed for gcc-4.6?
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 01:11:48 -0000

Sigh. Thanks for the message.
I'll update the GCL version as soon as I can.
What linux distro are you running?

Tim Daly


On Mon, 2011-11-07 at 20:05 -0500, Leon Baum wrote:
> Hello,
> I've been using my distro's packaged version of FriCAS, but I wanted to=
try AXIOM because I like the idea of literate programming.
> I ended up getting a github snapshot compiled with gcc-4.5, but just in=
case you aren't already aware, I wanted to let you know that the bundledv=
ersion of GCL has problems with gcc-4.6.
> According to the GCL mailing list [1] and a Debian bug report [2], itlo=
oks like the problems have been already fixed upstream, so simplyupdating=
 GCL should fix things in AXIOM.
> Error snippet:...Compiling gcl_cmpwt.lsp.Loading ./gcl_cmpinit.lspLoadi=
ng ../lsp/sys-proclaim.lispFinished loading ../lsp/sys-proclaim.lispLoadi=
ng sys-proclaim.lispFinished loading sys-proclaim.lispFinished loading ./=
gcl_cmpinit.lspEnd of Pass 1. =20
> Error: Someone tried to RETURN-FROM a TAGBODY.Error signalled by LET.Ba=
cktrace: system::gcl-top-level > if > let > setq > system:error-set > sys=
tem:error-set > progn > compile-file > loop > setq > apply > apply > comp=
ile-file1 > let > unwind-protect > progn > let* > let > unwind-protect > =
progn > when > compiler-pass2 > let > unwind-protect > progn > let > let =
> unwind-protect > progn > catch > ctop-write > do* > when > apply > appl=
y > t3defun > cond > analyze-regs > let > cond > let > analyze-regs1 > le=
t > tagbody > system:universal-error-handler > let > let > cond > apply >=
 apply > system:universal-error-handler > system::break-level > let* > UN=
LESSgcl_cmpwt.c: In function =E2=80=98init_gcl_cmpwt=E2=80=99:gcl_cmpwt.c=
:4:39: error: =E2=80=98VV=E2=80=99 undeclared (first use in this function=
)...
>=20
> Leon
> [1] http://lists.gnu.org/archive/html/gcl-devel/2011-04/msg00005.html[2=
] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=3D625032
> _______________________________________________Axiom-developer mailing =
listAxiom-developer@nongnu.orghttps://lists.nongnu.org/mailman/listinfo/a=
xiom-developer




From MAILER-DAEMON Mon Nov 07 22:51:11 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNciN-0000bJ-Ke
	for mharc-axiom-developer@gnu.org; Mon, 07 Nov 2011 22:51:11 -0500
Received: from eggs.gnu.org ([140.186.70.92]:56247)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNciL-0000bA-NV
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 22:51:10 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNciK-0007tm-CR
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 22:51:09 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:52371
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNciK-0007te-6F
	for axiom-developer@nongnu.org; Mon, 07 Nov 2011 22:51:08 -0500
Received: from axiom-developer.org (lincoln.rosehosting.com [127.0.0.1])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pA83p475027254;
	Mon, 7 Nov 2011 21:51:04 -0600
From: daly@axiom-developer.org
Received: (from daly@localhost)
	by axiom-developer.org (8.12.8/8.12.8/Submit) id pA83p4fY027233;
	Mon, 7 Nov 2011 21:51:04 -0600
Date: Mon, 7 Nov 2011 21:51:04 -0600
Message-Id: <201111080351.pA83p4fY027233@axiom-developer.org>
To: "Camm Maguire" <camm@debian.org>
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: [Axiom-developer] [GCL] EXTRAS are not included
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 03:51:10 -0000

Camm,

I checked out the latest gcl-2.6.8pre.

I have a patch that gets applied to h/linux.defs which adds the line:

EXTRAS = ${OBJ}/${SYS}/lib/cfuns-c.o ${OBJ}/${SYS}/lib/sockio-c.o

This had the effect of linking these two files into the lisp image.
Unfortunately the files don't appear to be linked. The OBJ and SYS
variables exist and have always worked in the past. The cfun-c.o
and sockio-c.o files exist as well as cfuns-c.ini and sockio-c.ini

cfuns-c defines a function called writeablep but this is not linked
into the image.

I don't see any changes related to EXTRAS.

What am I missing?

Tim Daly
daly@axiom-developer.org


From MAILER-DAEMON Tue Nov 08 09:25:38 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNmcM-0004wc-08
	for mharc-axiom-developer@gnu.org; Tue, 08 Nov 2011 09:25:38 -0500
Received: from eggs.gnu.org ([140.186.70.92]:59674)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNmcJ-0004wW-Kl
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 09:25:36 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNmc9-00047Q-Vy
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 09:25:35 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:47872
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNmc9-00047F-Lf
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 09:25:25 -0500
Received: from axiom-developer.org (lincoln.rosehosting.com [127.0.0.1])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pA8EPO75006414;
	Tue, 8 Nov 2011 08:25:24 -0600
From: daly@axiom-developer.org
Received: (from daly@localhost)
	by axiom-developer.org (8.12.8/8.12.8/Submit) id pA8EPOjf006411;
	Tue, 8 Nov 2011 08:25:24 -0600
Date: Tue, 8 Nov 2011 08:25:24 -0600
Message-Id: <201111081425.pA8EPOjf006411@axiom-developer.org>
To: axiom-developer@nongnu.org
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Subject: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 14:25:36 -0000

Knuth said:

Literate programming is a very personal thing. I think it's terrific,
but that might well be because I'm a very strange person. It has tens
of thousands of fans, but not millions.
 
In my experience, software created with literate programming has
turned out to be significantly better than software developed in more
traditional ways. Yet ordinary software is usually okay -- I'd give it
a grade of C (or maybe C++), but not F; hence, the traditinal methods
stay with us. Since they're understood by a vast community of
programmers, most people have no big incentive to change, just as I'm
not motivated to learn Esperanto even though it might be preferable to
English and German and French and Russian (if everybody switched).

Jon Bentley probably hit the nail on the head when he once was asked
why literate programming hasn't taken the whole world by storm. He
observed that a small percentage of the world's population is good at
programming, and a small percentage is good at writing; apparently I
am asking everybody to be in both subsets.

Yet to me, literate programming is certainly the most important thing
that came out of the TeX project. Not only has it enabled me to write
and maintain programs faster and more reliably than ever before, and
been one of my greatest sources of joy since the 1980s -- it has
actually been indispensable at times. Some of my major programs, such
as the MMIX meta-simulator, could not have been written with any other
methodology that I've ever heard of. The complexity was simply too
daunting for my limited brain to handle; without literate programming,
the whole enterprise would have flopped miserably.

If people discover nice ways to use the newfangled multithreaded
machines, I would expect the discovery to come from people who
routinely use literate programming. Literate programming is what you
need to rise above the ordinary level of achievement. But I don't
believe in forcing ideas on anybody. If literate programming isn't
your style, please forget it and do what you like. If nobody likes it
but me, let it die.

Knuth, Donald ``Interview with Donald Knuth''
www.informit.com/articles/article.aspx?p=1193856&_



From MAILER-DAEMON Tue Nov 08 09:46:34 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNmwc-0004o8-5q
	for mharc-axiom-developer@gnu.org; Tue, 08 Nov 2011 09:46:34 -0500
Received: from eggs.gnu.org ([140.186.70.92]:33989)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNmwU-0004hA-TL
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 09:46:32 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNmwP-0000OW-4D
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 09:46:26 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:58040
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNmwP-0000OL-03
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 09:46:21 -0500
Received: from axiom-developer.org (lincoln.rosehosting.com [127.0.0.1])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pA8EkJ75019215;
	Tue, 8 Nov 2011 08:46:19 -0600
From: daly@axiom-developer.org
Received: (from daly@localhost)
	by axiom-developer.org (8.12.8/8.12.8/Submit) id pA8EkJoC019212;
	Tue, 8 Nov 2011 08:46:19 -0600
Date: Tue, 8 Nov 2011 08:46:19 -0600
Message-Id: <201111081446.pA8EkJoC019212@axiom-developer.org>
To: axiom-developer@nongnu.org
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Subject: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 14:46:33 -0000

> Yet to me, literate programming is certainly the most important thing
> that came out of the TeX project. Not only has it enabled me to write
> and maintain programs faster and more reliably than ever before, and
> been one of my greatest sources of joy since the 1980s -- it has
> actually been indispensable at times. Some of my major programs, such
> as the MMIX meta-simulator, could not have been written with any other
> methodology that I've ever heard of. The complexity was simply too
> daunting for my limited brain to handle; without literate programming,
> the whole enterprise would have flopped miserably.
> 
> If people discover nice ways to use the newfangled multithreaded
> machines, I would expect the discovery to come from people who
> routinely use literate programming. Literate programming is what you
> need to rise above the ordinary level of achievement. 

I believe that Axiom's complexity is large enough to demand literate
programming. There are several reasons.

First, computational mathematics requires people to be exceptional at
mathematics and programming. This is a small subset of already small
sets. We might as well add another subset of those who can communicate
their ideas in writing.

Second, there are many design decisions that are necessary to reduce
a mathematical idea to implementation. Some of these design decisions
are mathematically arbitrary (e.g. branch cuts) or computationally
arbitrary (e.g. sparse versus dense) or programatically arbitrary
(e.g. all Spad versus Spad-and-lisp). These design decisions need to
be documented so people who maintain and modify the program know why
the decisions were made. Without this knowledge it would be trivial
to accidently destroy important optimizations.

Third, nobody is an expert in the range of mathematics that Axiom can
and will implement. It is important to present some portions of the
theory associated with domains so people have a clue about the ideas
being encoded. Imagine what would happen if all of the math textbooks
only contained equations but no human-readable text. You might be able
to "read" a calculus textbook but not an infinite group theory textbook.

Fourth, a million line program is too large to put into your head. You
need to have some background on the data structures, control flow, any
special tricks (e.g. funcalls through the symbol-plist), database
design, communication protocols (e.g. between Axiom and Hyperdoc and
Graphics), parsing structures, and a million other details. At best,
the code tells you HOW it does something but not WHY, not what it
depends on, not what depends on it, etc.

Fifth, a program this large and this long-lived will eventually no
longer have the authors around to ask questions. Several of the Axiom
authors are already dead and most are not associated with it anymore.
Some of those authors are the world's expert in their subject matter.
That is a steep hill to climb if you want to understand the code,
especially if you have to debug or modify it.

Sixth, in the 30 year horizon view, we need to pursue a new level of
excellence. As Knuth said:

   "Literate programming is what you need to rise above 
    the ordinary level of achievement"

For all these reasons, and more, Axiom needs to be literate.

Tim Daly




From MAILER-DAEMON Tue Nov 08 16:04:43 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNsqZ-00041R-Ty
	for mharc-axiom-developer@gnu.org; Tue, 08 Nov 2011 16:04:43 -0500
Received: from eggs.gnu.org ([140.186.70.92]:33815)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RNsqX-0003zU-AB
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 16:04:42 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RNsqV-0003va-Nn
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 16:04:41 -0500
Received: from vms173011pub.verizon.net ([206.46.173.11]:56137)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RNsqV-0003uq-KO
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 16:04:39 -0500
Received: from [127.0.0.1] ([unknown] [108.41.95.236])
	by vms173011.mailsrvcs.net
	(Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16
	2009)) with ESMTPA id <0LUC00HTMYE0MLW1@vms173011.mailsrvcs.net> for
	axiom-developer@nongnu.org; Tue, 08 Nov 2011 14:03:48 -0600 (CST)
Message-id: <4EB98B18.9090407@attglobal.net>
Date: Tue, 08 Nov 2011 15:03:36 -0500
From: Eugene Surowitz <surow@attglobal.net>
User-Agent: Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20110929
	Thunderbird/7.0.1
MIME-version: 1.0
To: axiom-developer@nongnu.org
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
In-reply-to: <201111081446.pA8EkJoC019212@axiom-developer.org>
Content-type: text/plain; charset=ISO-8859-1; format=flowed
Content-transfer-encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Solaris 10 (1203?)
X-Received-From: 206.46.173.11
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: surow@attglobal.net
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 21:04:42 -0000

That literate programming is fully justified for Axiom is, well, almost axiomatic.
But the issue is more how to boost the ability to invert the process
and reverse engineer non-literate code piles into literate documents.

What, in your opinion, would be the most effective type of tool that could
be developed to render the literacy project more tractable?

Eugene J. Surowitz

On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
>> Yet to me, literate programming is certainly the most important thing
>> that came out of the TeX project. Not only has it enabled me to write
>> and maintain programs faster and more reliably than ever before, and
>> been one of my greatest sources of joy since the 1980s -- it has
>> actually been indispensable at times. Some of my major programs, such
>> as the MMIX meta-simulator, could not have been written with any other
>> methodology that I've ever heard of. The complexity was simply too
>> daunting for my limited brain to handle; without literate programming,
>> the whole enterprise would have flopped miserably.
>>
>> If people discover nice ways to use the newfangled multithreaded
>> machines, I would expect the discovery to come from people who
>> routinely use literate programming. Literate programming is what you
>> need to rise above the ordinary level of achievement.
>
> I believe that Axiom's complexity is large enough to demand literate
> programming. There are several reasons.
>
> First, computational mathematics requires people to be exceptional at
> mathematics and programming. This is a small subset of already small
> sets. We might as well add another subset of those who can communicate
> their ideas in writing.
>
> Second, there are many design decisions that are necessary to reduce
> a mathematical idea to implementation. Some of these design decisions
> are mathematically arbitrary (e.g. branch cuts) or computationally
> arbitrary (e.g. sparse versus dense) or programatically arbitrary
> (e.g. all Spad versus Spad-and-lisp). These design decisions need to
> be documented so people who maintain and modify the program know why
> the decisions were made. Without this knowledge it would be trivial
> to accidently destroy important optimizations.
>
> Third, nobody is an expert in the range of mathematics that Axiom can
> and will implement. It is important to present some portions of the
> theory associated with domains so people have a clue about the ideas
> being encoded. Imagine what would happen if all of the math textbooks
> only contained equations but no human-readable text. You might be able
> to "read" a calculus textbook but not an infinite group theory textbook.
>
> Fourth, a million line program is too large to put into your head. You
> need to have some background on the data structures, control flow, any
> special tricks (e.g. funcalls through the symbol-plist), database
> design, communication protocols (e.g. between Axiom and Hyperdoc and
> Graphics), parsing structures, and a million other details. At best,
> the code tells you HOW it does something but not WHY, not what it
> depends on, not what depends on it, etc.
>
> Fifth, a program this large and this long-lived will eventually no
> longer have the authors around to ask questions. Several of the Axiom
> authors are already dead and most are not associated with it anymore.
> Some of those authors are the world's expert in their subject matter.
> That is a steep hill to climb if you want to understand the code,
> especially if you have to debug or modify it.
>
> Sixth, in the 30 year horizon view, we need to pursue a new level of
> excellence. As Knuth said:
>
>     "Literate programming is what you need to rise above
>      the ordinary level of achievement"
>
> For all these reasons, and more, Axiom needs to be literate.
>
> Tim Daly
>
>
>
> _______________________________________________
> Axiom-developer mailing list
> Axiom-developer@nongnu.org
> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>
>



From MAILER-DAEMON Tue Nov 08 16:42:51 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RNtRT-0005gg-PQ
	for mharc-axiom-developer@gnu.org; Tue, 08 Nov 2011 16:42:51 -0500
Received: from eggs.gnu.org ([140.186.70.92]:44149)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNtRR-0005gX-Ky
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 16:42:51 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNtRM-0002oq-6o
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 16:42:49 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:53510
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RNtRL-0002om-Vq
	for axiom-developer@nongnu.org; Tue, 08 Nov 2011 16:42:44 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pA8Lgf75025726;
	Tue, 8 Nov 2011 15:42:41 -0600
From: daly <daly@axiom-developer.org>
To: surow@attglobal.net
In-Reply-To: <4EB98B18.9090407@attglobal.net>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net>
Content-Type: text/plain; charset="UTF-8"
Date: Tue, 08 Nov 2011 16:42:05 -0500
Message-ID: <1320788526.30722.1188.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 08 Nov 2011 21:42:51 -0000

Tools? The goal of literate programming is communicating from
human to human. It is like writing a novel. All you need is a
working Underwood typewriter and time.

I tend to favor Latex because a lot of math is involved and
Latex prints math well. But I'm presenting a talk about
Literate Programming in North Carolina this week and I plan
to show examples that use XML, html, and video.

Tim

On Tue, 2011-11-08 at 15:03 -0500, Eugene Surowitz wrote:
> That literate programming is fully justified for Axiom is, well, almost axiomatic.
> But the issue is more how to boost the ability to invert the process
> and reverse engineer non-literate code piles into literate documents.
> 
> What, in your opinion, would be the most effective type of tool that could
> be developed to render the literacy project more tractable?
> 
> Eugene J. Surowitz
> 
> On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
> >> Yet to me, literate programming is certainly the most important thing
> >> that came out of the TeX project. Not only has it enabled me to write
> >> and maintain programs faster and more reliably than ever before, and
> >> been one of my greatest sources of joy since the 1980s -- it has
> >> actually been indispensable at times. Some of my major programs, such
> >> as the MMIX meta-simulator, could not have been written with any other
> >> methodology that I've ever heard of. The complexity was simply too
> >> daunting for my limited brain to handle; without literate programming,
> >> the whole enterprise would have flopped miserably.
> >>
> >> If people discover nice ways to use the newfangled multithreaded
> >> machines, I would expect the discovery to come from people who
> >> routinely use literate programming. Literate programming is what you
> >> need to rise above the ordinary level of achievement.
> >
> > I believe that Axiom's complexity is large enough to demand literate
> > programming. There are several reasons.
> >
> > First, computational mathematics requires people to be exceptional at
> > mathematics and programming. This is a small subset of already small
> > sets. We might as well add another subset of those who can communicate
> > their ideas in writing.
> >
> > Second, there are many design decisions that are necessary to reduce
> > a mathematical idea to implementation. Some of these design decisions
> > are mathematically arbitrary (e.g. branch cuts) or computationally
> > arbitrary (e.g. sparse versus dense) or programatically arbitrary
> > (e.g. all Spad versus Spad-and-lisp). These design decisions need to
> > be documented so people who maintain and modify the program know why
> > the decisions were made. Without this knowledge it would be trivial
> > to accidently destroy important optimizations.
> >
> > Third, nobody is an expert in the range of mathematics that Axiom can
> > and will implement. It is important to present some portions of the
> > theory associated with domains so people have a clue about the ideas
> > being encoded. Imagine what would happen if all of the math textbooks
> > only contained equations but no human-readable text. You might be able
> > to "read" a calculus textbook but not an infinite group theory textbook.
> >
> > Fourth, a million line program is too large to put into your head. You
> > need to have some background on the data structures, control flow, any
> > special tricks (e.g. funcalls through the symbol-plist), database
> > design, communication protocols (e.g. between Axiom and Hyperdoc and
> > Graphics), parsing structures, and a million other details. At best,
> > the code tells you HOW it does something but not WHY, not what it
> > depends on, not what depends on it, etc.
> >
> > Fifth, a program this large and this long-lived will eventually no
> > longer have the authors around to ask questions. Several of the Axiom
> > authors are already dead and most are not associated with it anymore.
> > Some of those authors are the world's expert in their subject matter.
> > That is a steep hill to climb if you want to understand the code,
> > especially if you have to debug or modify it.
> >
> > Sixth, in the 30 year horizon view, we need to pursue a new level of
> > excellence. As Knuth said:
> >
> >     "Literate programming is what you need to rise above
> >      the ordinary level of achievement"
> >
> > For all these reasons, and more, Axiom needs to be literate.
> >
> > Tim Daly
> >
> >
> >
> > _______________________________________________
> > Axiom-developer mailing list
> > Axiom-developer@nongnu.org
> > https://lists.nongnu.org/mailman/listinfo/axiom-developer
> >
> >
> 
> 
> _______________________________________________
> Axiom-developer mailing list
> Axiom-developer@nongnu.org
> https://lists.nongnu.org/mailman/listinfo/axiom-developer




From MAILER-DAEMON Fri Nov 11 11:03:54 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1ROta6-0002qi-UN
	for mharc-axiom-developer@gnu.org; Fri, 11 Nov 2011 11:03:54 -0500
Received: from eggs.gnu.org ([140.186.70.92]:46748)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1ROta4-0002pS-6D
	for axiom-developer@nongnu.org; Fri, 11 Nov 2011 11:03:53 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1ROta1-0001Jv-Px
	for axiom-developer@nongnu.org; Fri, 11 Nov 2011 11:03:52 -0500
Received: from vms173017pub.verizon.net ([206.46.173.17]:52427)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1ROta1-0001J9-I8
	for axiom-developer@nongnu.org; Fri, 11 Nov 2011 11:03:49 -0500
Received: from [127.0.0.1] ([unknown] [108.41.95.236])
	by vms173017.mailsrvcs.net
	(Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16
	2009)) with ESMTPA id <0LUI007CK79P0SKU@vms173017.mailsrvcs.net> for
	axiom-developer@nongnu.org; Fri, 11 Nov 2011 10:03:35 -0600 (CST)
Message-id: <4EBD474E.3040709@attglobal.net>
Date: Fri, 11 Nov 2011 11:03:26 -0500
From: Eugene Surowitz <surow@attglobal.net>
User-Agent: Mozilla/5.0 (Windows NT 5.1; rv:8.0) Gecko/20111105 Thunderbird/8.0
MIME-version: 1.0
To: daly <daly@axiom-developer.org>,
	Axiom-Developer <axiom-developer@nongnu.org>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net> <1320788526.30722.1188.camel@pewter>
In-reply-to: <1320788526.30722.1188.camel@pewter>
Content-type: text/plain; charset=UTF-8; format=flowed
Content-transfer-encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Solaris 10 (1203?)
X-Received-From: 206.46.173.17
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: surow@attglobal.net
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Fri, 11 Nov 2011 16:03:53 -0000

I prefer the fountain pen for novelistic efforts.

The issue that aroused my question has to do with
comments that appear now and then in the list
about knowing what is where in the source code.

The reference to tools really was intended to address
the idea of the utility of a mechanism(s) that could
globally treat the entire source code as text to
answer that question.

Eugene J. Surowitz

On 11/8/2011 4:42 PM, daly wrote:
> Tools? The goal of literate programming is communicating from
> human to human. It is like writing a novel. All you need is a
> working Underwood typewriter and time.
>
> I tend to favor Latex because a lot of math is involved and
> Latex prints math well. But I'm presenting a talk about
> Literate Programming in North Carolina this week and I plan
> to show examples that use XML, html, and video.
>
> Tim
>
> On Tue, 2011-11-08 at 15:03 -0500, Eugene Surowitz wrote:
>> That literate programming is fully justified for Axiom is, well, almost axiomatic.
>> But the issue is more how to boost the ability to invert the process
>> and reverse engineer non-literate code piles into literate documents.
>>
>> What, in your opinion, would be the most effective type of tool that could
>> be developed to render the literacy project more tractable?
>>
>> Eugene J. Surowitz
>>
>> On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
>>>> Yet to me, literate programming is certainly the most important thing
>>>> that came out of the TeX project. Not only has it enabled me to write
>>>> and maintain programs faster and more reliably than ever before, and
>>>> been one of my greatest sources of joy since the 1980s -- it has
>>>> actually been indispensable at times. Some of my major programs, such
>>>> as the MMIX meta-simulator, could not have been written with any other
>>>> methodology that I've ever heard of. The complexity was simply too
>>>> daunting for my limited brain to handle; without literate programming,
>>>> the whole enterprise would have flopped miserably.
>>>>
>>>> If people discover nice ways to use the newfangled multithreaded
>>>> machines, I would expect the discovery to come from people who
>>>> routinely use literate programming. Literate programming is what you
>>>> need to rise above the ordinary level of achievement.
>>>
>>> I believe that Axiom's complexity is large enough to demand literate
>>> programming. There are several reasons.
>>>
>>> First, computational mathematics requires people to be exceptional at
>>> mathematics and programming. This is a small subset of already small
>>> sets. We might as well add another subset of those who can communicate
>>> their ideas in writing.
>>>
>>> Second, there are many design decisions that are necessary to reduce
>>> a mathematical idea to implementation. Some of these design decisions
>>> are mathematically arbitrary (e.g. branch cuts) or computationally
>>> arbitrary (e.g. sparse versus dense) or programatically arbitrary
>>> (e.g. all Spad versus Spad-and-lisp). These design decisions need to
>>> be documented so people who maintain and modify the program know why
>>> the decisions were made. Without this knowledge it would be trivial
>>> to accidently destroy important optimizations.
>>>
>>> Third, nobody is an expert in the range of mathematics that Axiom can
>>> and will implement. It is important to present some portions of the
>>> theory associated with domains so people have a clue about the ideas
>>> being encoded. Imagine what would happen if all of the math textbooks
>>> only contained equations but no human-readable text. You might be able
>>> to "read" a calculus textbook but not an infinite group theory textbook.
>>>
>>> Fourth, a million line program is too large to put into your head. You
>>> need to have some background on the data structures, control flow, any
>>> special tricks (e.g. funcalls through the symbol-plist), database
>>> design, communication protocols (e.g. between Axiom and Hyperdoc and
>>> Graphics), parsing structures, and a million other details. At best,
>>> the code tells you HOW it does something but not WHY, not what it
>>> depends on, not what depends on it, etc.
>>>
>>> Fifth, a program this large and this long-lived will eventually no
>>> longer have the authors around to ask questions. Several of the Axiom
>>> authors are already dead and most are not associated with it anymore.
>>> Some of those authors are the world's expert in their subject matter.
>>> That is a steep hill to climb if you want to understand the code,
>>> especially if you have to debug or modify it.
>>>
>>> Sixth, in the 30 year horizon view, we need to pursue a new level of
>>> excellence. As Knuth said:
>>>
>>>      "Literate programming is what you need to rise above
>>>       the ordinary level of achievement"
>>>
>>> For all these reasons, and more, Axiom needs to be literate.
>>>
>>> Tim Daly
>>>
>>>
>>>
>>> _______________________________________________
>>> Axiom-developer mailing list
>>> Axiom-developer@nongnu.org
>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>>>
>>>
>>
>>
>> _______________________________________________
>> Axiom-developer mailing list
>> Axiom-developer@nongnu.org
>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>
>
>
>



From MAILER-DAEMON Mon Nov 14 14:09:10 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RQ1u2-000114-1D
	for mharc-axiom-developer@gnu.org; Mon, 14 Nov 2011 14:09:10 -0500
Received: from eggs.gnu.org ([140.186.70.92]:53487)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RQ1tz-0000z8-88
	for axiom-developer@nongnu.org; Mon, 14 Nov 2011 14:09:08 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RQ1tx-00006E-C2
	for axiom-developer@nongnu.org; Mon, 14 Nov 2011 14:09:07 -0500
Received: from vms173019pub.verizon.net ([206.46.173.19]:36247)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RQ1tx-00005r-6q
	for axiom-developer@nongnu.org; Mon, 14 Nov 2011 14:09:05 -0500
Received: from [127.0.0.1] ([unknown] [108.41.95.236])
	by vms173019.mailsrvcs.net
	(Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16
	2009)) with ESMTPA id <0LUN00DEGZUC0JZ2@vms173019.mailsrvcs.net> for
	axiom-developer@nongnu.org; Mon, 14 Nov 2011 13:08:43 -0600 (CST)
Message-id: <4EC16735.6090302@attglobal.net>
Date: Mon, 14 Nov 2011 14:08:37 -0500
From: Eugene Surowitz <surow@attglobal.net>
User-Agent: Mozilla/5.0 (Windows NT 5.1; rv:8.0) Gecko/20111105 Thunderbird/8.0
MIME-version: 1.0
To: daly <daly@axiom-developer.org>,
	axiom-Developer <axiom-developer@nongnu.org>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net> <1320788526.30722.1188.camel@pewter>
	<4EBD474E.3040709@attglobal.net> <1321150607.1926.2.camel@pewter>
In-reply-to: <1321150607.1926.2.camel@pewter>
Content-type: text/plain; charset=UTF-8; format=flowed
Content-transfer-encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Solaris 10 (1203?)
X-Received-From: 206.46.173.19
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: surow@attglobal.net
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Mon, 14 Nov 2011 19:09:08 -0000


Will your talk and slides be available on the web?

Long term objective excellent; getting there is the rub.
It's ok at the developed and distributed level,
but from the developer's ant eye view the toc and index
are only as good as the choice of structure and
the entry selection.

There is also the headache of what the eyeball missed
and what opinion bias does or does not consider important.
Also texts tend to have concepts expressed as multiword
strings, such as "table of contents".
Pseudo-letters, such as "_" or "~", just add to the mess.

Exhaustive listing of everything was quite useful
in another book effort.  For a code the size of Axiom,
I guesstimate that a factor of three for the token file size.

Eugene J. Surowitz

On 11/12/2011 9:16 PM, daly wrote:
> Well, the question is whether you're looking for a concept
> (check table of contents) or a particular function (check
> the index). At least that is the long term intention.
>
> On Fri, 2011-11-11 at 11:03 -0500, Eugene Surowitz wrote:
>> I prefer the fountain pen for novelistic efforts.
>>
>> The issue that aroused my question has to do with
>> comments that appear now and then in the list
>> about knowing what is where in the source code.
>>
>> The reference to tools really was intended to address
>> the idea of the utility of a mechanism(s) that could
>> globally treat the entire source code as text to
>> answer that question.
>>
>> Eugene J. Surowitz
>>
>> On 11/8/2011 4:42 PM, daly wrote:
>>> Tools? The goal of literate programming is communicating from
>>> human to human. It is like writing a novel. All you need is a
>>> working Underwood typewriter and time.
>>>
>>> I tend to favor Latex because a lot of math is involved and
>>> Latex prints math well. But I'm presenting a talk about
>>> Literate Programming in North Carolina this week and I plan
>>> to show examples that use XML, html, and video.
>>>
>>> Tim
>>>
>>> On Tue, 2011-11-08 at 15:03 -0500, Eugene Surowitz wrote:
>>>> That literate programming is fully justified for Axiom is, well, almost axiomatic.
>>>> But the issue is more how to boost the ability to invert the process
>>>> and reverse engineer non-literate code piles into literate documents.
>>>>
>>>> What, in your opinion, would be the most effective type of tool that could
>>>> be developed to render the literacy project more tractable?
>>>>
>>>> Eugene J. Surowitz
>>>>
>>>> On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
>>>>>> Yet to me, literate programming is certainly the most important thing
>>>>>> that came out of the TeX project. Not only has it enabled me to write
>>>>>> and maintain programs faster and more reliably than ever before, and
>>>>>> been one of my greatest sources of joy since the 1980s -- it has
>>>>>> actually been indispensable at times. Some of my major programs, such
>>>>>> as the MMIX meta-simulator, could not have been written with any other
>>>>>> methodology that I've ever heard of. The complexity was simply too
>>>>>> daunting for my limited brain to handle; without literate programming,
>>>>>> the whole enterprise would have flopped miserably.
>>>>>>
>>>>>> If people discover nice ways to use the newfangled multithreaded
>>>>>> machines, I would expect the discovery to come from people who
>>>>>> routinely use literate programming. Literate programming is what you
>>>>>> need to rise above the ordinary level of achievement.
>>>>>
>>>>> I believe that Axiom's complexity is large enough to demand literate
>>>>> programming. There are several reasons.
>>>>>
>>>>> First, computational mathematics requires people to be exceptional at
>>>>> mathematics and programming. This is a small subset of already small
>>>>> sets. We might as well add another subset of those who can communicate
>>>>> their ideas in writing.
>>>>>
>>>>> Second, there are many design decisions that are necessary to reduce
>>>>> a mathematical idea to implementation. Some of these design decisions
>>>>> are mathematically arbitrary (e.g. branch cuts) or computationally
>>>>> arbitrary (e.g. sparse versus dense) or programatically arbitrary
>>>>> (e.g. all Spad versus Spad-and-lisp). These design decisions need to
>>>>> be documented so people who maintain and modify the program know why
>>>>> the decisions were made. Without this knowledge it would be trivial
>>>>> to accidently destroy important optimizations.
>>>>>
>>>>> Third, nobody is an expert in the range of mathematics that Axiom can
>>>>> and will implement. It is important to present some portions of the
>>>>> theory associated with domains so people have a clue about the ideas
>>>>> being encoded. Imagine what would happen if all of the math textbooks
>>>>> only contained equations but no human-readable text. You might be able
>>>>> to "read" a calculus textbook but not an infinite group theory textbook.
>>>>>
>>>>> Fourth, a million line program is too large to put into your head. You
>>>>> need to have some background on the data structures, control flow, any
>>>>> special tricks (e.g. funcalls through the symbol-plist), database
>>>>> design, communication protocols (e.g. between Axiom and Hyperdoc and
>>>>> Graphics), parsing structures, and a million other details. At best,
>>>>> the code tells you HOW it does something but not WHY, not what it
>>>>> depends on, not what depends on it, etc.
>>>>>
>>>>> Fifth, a program this large and this long-lived will eventually no
>>>>> longer have the authors around to ask questions. Several of the Axiom
>>>>> authors are already dead and most are not associated with it anymore.
>>>>> Some of those authors are the world's expert in their subject matter.
>>>>> That is a steep hill to climb if you want to understand the code,
>>>>> especially if you have to debug or modify it.
>>>>>
>>>>> Sixth, in the 30 year horizon view, we need to pursue a new level of
>>>>> excellence. As Knuth said:
>>>>>
>>>>>       "Literate programming is what you need to rise above
>>>>>        the ordinary level of achievement"
>>>>>
>>>>> For all these reasons, and more, Axiom needs to be literate.
>>>>>
>>>>> Tim Daly
>>>>>
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Axiom-developer mailing list
>>>>> Axiom-developer@nongnu.org
>>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>>>>>
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> Axiom-developer mailing list
>>>> Axiom-developer@nongnu.org
>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>>>
>>>
>>>
>>>
>
>
>
>



From MAILER-DAEMON Mon Nov 14 19:12:21 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RQ6dR-0005HC-NM
	for mharc-axiom-developer@gnu.org; Mon, 14 Nov 2011 19:12:21 -0500
Received: from eggs.gnu.org ([140.186.70.92]:36446)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RQ6dO-0005E6-Eh
	for axiom-developer@nongnu.org; Mon, 14 Nov 2011 19:12:19 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RQ6dM-00038K-Al
	for axiom-developer@nongnu.org; Mon, 14 Nov 2011 19:12:18 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:52295
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RQ6dM-000382-4W
	for axiom-developer@nongnu.org; Mon, 14 Nov 2011 19:12:16 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAF0CC75013729;
	Mon, 14 Nov 2011 18:12:12 -0600
From: daly <daly@axiom-developer.org>
To: surow@attglobal.net
In-Reply-To: <4EC16735.6090302@attglobal.net>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net> <1320788526.30722.1188.camel@pewter>
	<4EBD474E.3040709@attglobal.net> <1321150607.1926.2.camel@pewter>
	<4EC16735.6090302@attglobal.net>
Content-Type: text/plain; charset="UTF-8"
Date: Mon, 14 Nov 2011 19:12:12 -0500
Message-ID: <1321315932.1926.22.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-Developer <axiom-developer@nongnu.org>
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Tue, 15 Nov 2011 00:12:20 -0000

On Mon, 2011-11-14 at 14:08 -0500, Eugene Surowitz wrote:
> Will your talk and slides be available on the web?

I gave a presentation at the Clojure Conj on Literate
Programming which was fairly well received but there were
no slides. I don't believe the talk was recorded.

I have an article in the Notices of the American Mathematical
Society scheduled to appear in February.

> 
> Long term objective excellent; getting there is the rub.
> It's ok at the developed and distributed level,
> but from the developer's ant eye view the toc and index
> are only as good as the choice of structure and
> the entry selection.

Indeed, that's a struggle for all authors. However, I have
made the index and cross references for every function and
variable.

> 
> There is also the headache of what the eyeball missed
> and what opinion bias does or does not consider important.
> Also texts tend to have concepts expressed as multiword
> strings, such as "table of contents".
> Pseudo-letters, such as "_" or "~", just add to the mess.

Every function, macro, and variable is introduced with
     \defun{foo}
     \defmacro{foo}
     \defvar{foo}

All of the index entries are hand generated using latex as in:
     \calls{foo}{bar}
which will put an entry under "foo" for "bar" and
an entry under "bar" for "foo". This means that it is trivial
to find every place that "bar" is called. This reverse-lookup
usually requires a code walker.

For global variables there are:
     \refsdollar{foo}{var}
     \defsdollar{foo}{var}
which will put an entry in the index for $var.


> 
> Exhaustive listing of everything was quite useful
> in another book effort.  For a code the size of Axiom,
> I guesstimate that a factor of three for the token file size.
> 
> Eugene J. Surowitz
> 
> On 11/12/2011 9:16 PM, daly wrote:
> > Well, the question is whether you're looking for a concept
> > (check table of contents) or a particular function (check
> > the index). At least that is the long term intention.
> >
> > On Fri, 2011-11-11 at 11:03 -0500, Eugene Surowitz wrote:
> >> I prefer the fountain pen for novelistic efforts.
> >>
> >> The issue that aroused my question has to do with
> >> comments that appear now and then in the list
> >> about knowing what is where in the source code.
> >>
> >> The reference to tools really was intended to address
> >> the idea of the utility of a mechanism(s) that could
> >> globally treat the entire source code as text to
> >> answer that question.
> >>
> >> Eugene J. Surowitz
> >>
> >> On 11/8/2011 4:42 PM, daly wrote:
> >>> Tools? The goal of literate programming is communicating from
> >>> human to human. It is like writing a novel. All you need is a
> >>> working Underwood typewriter and time.
> >>>
> >>> I tend to favor Latex because a lot of math is involved and
> >>> Latex prints math well. But I'm presenting a talk about
> >>> Literate Programming in North Carolina this week and I plan
> >>> to show examples that use XML, html, and video.
> >>>
> >>> Tim
> >>>
> >>> On Tue, 2011-11-08 at 15:03 -0500, Eugene Surowitz wrote:
> >>>> That literate programming is fully justified for Axiom is, well, almost axiomatic.
> >>>> But the issue is more how to boost the ability to invert the process
> >>>> and reverse engineer non-literate code piles into literate documents.
> >>>>
> >>>> What, in your opinion, would be the most effective type of tool that could
> >>>> be developed to render the literacy project more tractable?
> >>>>
> >>>> Eugene J. Surowitz
> >>>>
> >>>> On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
> >>>>>> Yet to me, literate programming is certainly the most important thing
> >>>>>> that came out of the TeX project. Not only has it enabled me to write
> >>>>>> and maintain programs faster and more reliably than ever before, and
> >>>>>> been one of my greatest sources of joy since the 1980s -- it has
> >>>>>> actually been indispensable at times. Some of my major programs, such
> >>>>>> as the MMIX meta-simulator, could not have been written with any other
> >>>>>> methodology that I've ever heard of. The complexity was simply too
> >>>>>> daunting for my limited brain to handle; without literate programming,
> >>>>>> the whole enterprise would have flopped miserably.
> >>>>>>
> >>>>>> If people discover nice ways to use the newfangled multithreaded
> >>>>>> machines, I would expect the discovery to come from people who
> >>>>>> routinely use literate programming. Literate programming is what you
> >>>>>> need to rise above the ordinary level of achievement.
> >>>>>
> >>>>> I believe that Axiom's complexity is large enough to demand literate
> >>>>> programming. There are several reasons.
> >>>>>
> >>>>> First, computational mathematics requires people to be exceptional at
> >>>>> mathematics and programming. This is a small subset of already small
> >>>>> sets. We might as well add another subset of those who can communicate
> >>>>> their ideas in writing.
> >>>>>
> >>>>> Second, there are many design decisions that are necessary to reduce
> >>>>> a mathematical idea to implementation. Some of these design decisions
> >>>>> are mathematically arbitrary (e.g. branch cuts) or computationally
> >>>>> arbitrary (e.g. sparse versus dense) or programatically arbitrary
> >>>>> (e.g. all Spad versus Spad-and-lisp). These design decisions need to
> >>>>> be documented so people who maintain and modify the program know why
> >>>>> the decisions were made. Without this knowledge it would be trivial
> >>>>> to accidently destroy important optimizations.
> >>>>>
> >>>>> Third, nobody is an expert in the range of mathematics that Axiom can
> >>>>> and will implement. It is important to present some portions of the
> >>>>> theory associated with domains so people have a clue about the ideas
> >>>>> being encoded. Imagine what would happen if all of the math textbooks
> >>>>> only contained equations but no human-readable text. You might be able
> >>>>> to "read" a calculus textbook but not an infinite group theory textbook.
> >>>>>
> >>>>> Fourth, a million line program is too large to put into your head. You
> >>>>> need to have some background on the data structures, control flow, any
> >>>>> special tricks (e.g. funcalls through the symbol-plist), database
> >>>>> design, communication protocols (e.g. between Axiom and Hyperdoc and
> >>>>> Graphics), parsing structures, and a million other details. At best,
> >>>>> the code tells you HOW it does something but not WHY, not what it
> >>>>> depends on, not what depends on it, etc.
> >>>>>
> >>>>> Fifth, a program this large and this long-lived will eventually no
> >>>>> longer have the authors around to ask questions. Several of the Axiom
> >>>>> authors are already dead and most are not associated with it anymore.
> >>>>> Some of those authors are the world's expert in their subject matter.
> >>>>> That is a steep hill to climb if you want to understand the code,
> >>>>> especially if you have to debug or modify it.
> >>>>>
> >>>>> Sixth, in the 30 year horizon view, we need to pursue a new level of
> >>>>> excellence. As Knuth said:
> >>>>>
> >>>>>       "Literate programming is what you need to rise above
> >>>>>        the ordinary level of achievement"
> >>>>>
> >>>>> For all these reasons, and more, Axiom needs to be literate.
> >>>>>
> >>>>> Tim Daly
> >>>>>
> >>>>>
> >>>>>
> >>>>> _______________________________________________
> >>>>> Axiom-developer mailing list
> >>>>> Axiom-developer@nongnu.org
> >>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
> >>>>>
> >>>>>
> >>>>
> >>>>
> >>>> _______________________________________________
> >>>> Axiom-developer mailing list
> >>>> Axiom-developer@nongnu.org
> >>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
> >>>
> >>>
> >>>
> >>>
> >
> >
> >
> >




From MAILER-DAEMON Fri Nov 18 12:54:33 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRSe1-0007n3-VP
	for mharc-axiom-developer@gnu.org; Fri, 18 Nov 2011 12:54:33 -0500
Received: from eggs.gnu.org ([140.186.70.92]:56439)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RRSdw-0007lM-3K
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 12:54:31 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RRSdo-00012L-NC
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 12:54:28 -0500
Received: from vms173013pub.verizon.net ([206.46.173.13]:38668)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <surow@attglobal.net>) id 1RRSdo-00011w-IB
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 12:54:20 -0500
Received: from [127.0.0.1] ([unknown] [108.41.95.236])
	by vms173013.mailsrvcs.net
	(Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16
	2009)) with ESMTPA id <0LUV003SRB1E7V84@vms173013.mailsrvcs.net> for
	axiom-developer@nongnu.org; Fri, 18 Nov 2011 11:53:53 -0600 (CST)
Message-id: <4EC69BA3.9060001@attglobal.net>
Date: Fri, 18 Nov 2011 12:53:39 -0500
From: Eugene Surowitz <surow@attglobal.net>
User-Agent: Mozilla/5.0 (Windows NT 5.1; rv:8.0) Gecko/20111105 Thunderbird/8.0
MIME-version: 1.0
To: daly <daly@axiom-developer.org>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net> <1320788526.30722.1188.camel@pewter>
	<4EBD474E.3040709@attglobal.net> <1321150607.1926.2.camel@pewter>
	<4EC16735.6090302@attglobal.net> <1321315932.1926.22.camel@pewter>
In-reply-to: <1321315932.1926.22.camel@pewter>
Content-type: text/plain; charset=UTF-8; format=flowed
Content-transfer-encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Solaris 10 (1203?)
X-Received-From: 206.46.173.13
Cc: axiom-Developer <axiom-developer@nongnu.org>
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: surow@attglobal.net
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Fri, 18 Nov 2011 17:54:31 -0000


I was just at BICA2011 and they both record the talks and
are actually creating DVDs along with the collected slides.
(They sold last year's DVDs at this years conference.)
Some are talks are on the web site.

I'm thinking along the line of a "text crawler" complemented
by a relational data base with the capability to call up
the literate pamphlets at a click.  Thus reverse walking
gives a product support and development mechanism.
The net result would be the ability to locate "foobar"
whatever context it is in - code or description.
I am assuming the however well Axiom gets pamphleteer-ed (ouch)
the perversity of human nature will result in individuals
shoehorning and shotgunning in code and comments in when
and where it occurs to them.
I would hope that the easier it is to do literate code cleanly
would discourage that phenomena.

Eugene J. Surowitz

On 11/14/2011 7:12 PM, daly wrote:
> On Mon, 2011-11-14 at 14:08 -0500, Eugene Surowitz wrote:
>> Will your talk and slides be available on the web?
>
> I gave a presentation at the Clojure Conj on Literate
> Programming which was fairly well received but there were
> no slides. I don't believe the talk was recorded.
>
> I have an article in the Notices of the American Mathematical
> Society scheduled to appear in February.
>
>>
>> Long term objective excellent; getting there is the rub.
>> It's ok at the developed and distributed level,
>> but from the developer's ant eye view the toc and index
>> are only as good as the choice of structure and
>> the entry selection.
>
> Indeed, that's a struggle for all authors. However, I have
> made the index and cross references for every function and
> variable.
>
>>
>> There is also the headache of what the eyeball missed
>> and what opinion bias does or does not consider important.
>> Also texts tend to have concepts expressed as multiword
>> strings, such as "table of contents".
>> Pseudo-letters, such as "_" or "~", just add to the mess.
>
> Every function, macro, and variable is introduced with
>       \defun{foo}
>       \defmacro{foo}
>       \defvar{foo}
>
> All of the index entries are hand generated using latex as in:
>       \calls{foo}{bar}
> which will put an entry under "foo" for "bar" and
> an entry under "bar" for "foo". This means that it is trivial
> to find every place that "bar" is called. This reverse-lookup
> usually requires a code walker.
>
> For global variables there are:
>       \refsdollar{foo}{var}
>       \defsdollar{foo}{var}
> which will put an entry in the index for $var.
>
>
>>
>> Exhaustive listing of everything was quite useful
>> in another book effort.  For a code the size of Axiom,
>> I guesstimate that a factor of three for the token file size.
>>
>> Eugene J. Surowitz
>>
>> On 11/12/2011 9:16 PM, daly wrote:
>>> Well, the question is whether you're looking for a concept
>>> (check table of contents) or a particular function (check
>>> the index). At least that is the long term intention.
>>>
>>> On Fri, 2011-11-11 at 11:03 -0500, Eugene Surowitz wrote:
>>>> I prefer the fountain pen for novelistic efforts.
>>>>
>>>> The issue that aroused my question has to do with
>>>> comments that appear now and then in the list
>>>> about knowing what is where in the source code.
>>>>
>>>> The reference to tools really was intended to address
>>>> the idea of the utility of a mechanism(s) that could
>>>> globally treat the entire source code as text to
>>>> answer that question.
>>>>
>>>> Eugene J. Surowitz
>>>>
>>>> On 11/8/2011 4:42 PM, daly wrote:
>>>>> Tools? The goal of literate programming is communicating from
>>>>> human to human. It is like writing a novel. All you need is a
>>>>> working Underwood typewriter and time.
>>>>>
>>>>> I tend to favor Latex because a lot of math is involved and
>>>>> Latex prints math well. But I'm presenting a talk about
>>>>> Literate Programming in North Carolina this week and I plan
>>>>> to show examples that use XML, html, and video.
>>>>>
>>>>> Tim
>>>>>
>>>>> On Tue, 2011-11-08 at 15:03 -0500, Eugene Surowitz wrote:
>>>>>> That literate programming is fully justified for Axiom is, well, almost axiomatic.
>>>>>> But the issue is more how to boost the ability to invert the process
>>>>>> and reverse engineer non-literate code piles into literate documents.
>>>>>>
>>>>>> What, in your opinion, would be the most effective type of tool that could
>>>>>> be developed to render the literacy project more tractable?
>>>>>>
>>>>>> Eugene J. Surowitz
>>>>>>
>>>>>> On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
>>>>>>>> Yet to me, literate programming is certainly the most important thing
>>>>>>>> that came out of the TeX project. Not only has it enabled me to write
>>>>>>>> and maintain programs faster and more reliably than ever before, and
>>>>>>>> been one of my greatest sources of joy since the 1980s -- it has
>>>>>>>> actually been indispensable at times. Some of my major programs, such
>>>>>>>> as the MMIX meta-simulator, could not have been written with any other
>>>>>>>> methodology that I've ever heard of. The complexity was simply too
>>>>>>>> daunting for my limited brain to handle; without literate programming,
>>>>>>>> the whole enterprise would have flopped miserably.
>>>>>>>>
>>>>>>>> If people discover nice ways to use the newfangled multithreaded
>>>>>>>> machines, I would expect the discovery to come from people who
>>>>>>>> routinely use literate programming. Literate programming is what you
>>>>>>>> need to rise above the ordinary level of achievement.
>>>>>>>
>>>>>>> I believe that Axiom's complexity is large enough to demand literate
>>>>>>> programming. There are several reasons.
>>>>>>>
>>>>>>> First, computational mathematics requires people to be exceptional at
>>>>>>> mathematics and programming. This is a small subset of already small
>>>>>>> sets. We might as well add another subset of those who can communicate
>>>>>>> their ideas in writing.
>>>>>>>
>>>>>>> Second, there are many design decisions that are necessary to reduce
>>>>>>> a mathematical idea to implementation. Some of these design decisions
>>>>>>> are mathematically arbitrary (e.g. branch cuts) or computationally
>>>>>>> arbitrary (e.g. sparse versus dense) or programatically arbitrary
>>>>>>> (e.g. all Spad versus Spad-and-lisp). These design decisions need to
>>>>>>> be documented so people who maintain and modify the program know why
>>>>>>> the decisions were made. Without this knowledge it would be trivial
>>>>>>> to accidently destroy important optimizations.
>>>>>>>
>>>>>>> Third, nobody is an expert in the range of mathematics that Axiom can
>>>>>>> and will implement. It is important to present some portions of the
>>>>>>> theory associated with domains so people have a clue about the ideas
>>>>>>> being encoded. Imagine what would happen if all of the math textbooks
>>>>>>> only contained equations but no human-readable text. You might be able
>>>>>>> to "read" a calculus textbook but not an infinite group theory textbook.
>>>>>>>
>>>>>>> Fourth, a million line program is too large to put into your head. You
>>>>>>> need to have some background on the data structures, control flow, any
>>>>>>> special tricks (e.g. funcalls through the symbol-plist), database
>>>>>>> design, communication protocols (e.g. between Axiom and Hyperdoc and
>>>>>>> Graphics), parsing structures, and a million other details. At best,
>>>>>>> the code tells you HOW it does something but not WHY, not what it
>>>>>>> depends on, not what depends on it, etc.
>>>>>>>
>>>>>>> Fifth, a program this large and this long-lived will eventually no
>>>>>>> longer have the authors around to ask questions. Several of the Axiom
>>>>>>> authors are already dead and most are not associated with it anymore.
>>>>>>> Some of those authors are the world's expert in their subject matter.
>>>>>>> That is a steep hill to climb if you want to understand the code,
>>>>>>> especially if you have to debug or modify it.
>>>>>>>
>>>>>>> Sixth, in the 30 year horizon view, we need to pursue a new level of
>>>>>>> excellence. As Knuth said:
>>>>>>>
>>>>>>>        "Literate programming is what you need to rise above
>>>>>>>         the ordinary level of achievement"
>>>>>>>
>>>>>>> For all these reasons, and more, Axiom needs to be literate.
>>>>>>>
>>>>>>> Tim Daly
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Axiom-developer mailing list
>>>>>>> Axiom-developer@nongnu.org
>>>>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> Axiom-developer mailing list
>>>>>> Axiom-developer@nongnu.org
>>>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
>>>>>
>>>>>
>>>>>
>>>>>
>>>
>>>
>>>
>>>
>
>
>
>



From MAILER-DAEMON Fri Nov 18 14:34:58 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRUDC-0006Hp-O4
	for mharc-axiom-developer@gnu.org; Fri, 18 Nov 2011 14:34:58 -0500
Received: from eggs.gnu.org ([140.186.70.92]:43366)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRUD9-0006Eu-7W
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 14:34:56 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRUD7-0003cO-6D
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 14:34:55 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:39261
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRUD7-0003cB-0c
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 14:34:53 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAIJYn75009327;
	Fri, 18 Nov 2011 13:34:50 -0600
From: daly <daly@axiom-developer.org>
To: surow@attglobal.net
In-Reply-To: <4EC69BA3.9060001@attglobal.net>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net> <1320788526.30722.1188.camel@pewter>
	<4EBD474E.3040709@attglobal.net> <1321150607.1926.2.camel@pewter>
	<4EC16735.6090302@attglobal.net> <1321315932.1926.22.camel@pewter>
	<4EC69BA3.9060001@attglobal.net>
Content-Type: text/plain; charset="UTF-8"
Date: Fri, 18 Nov 2011 14:34:48 -0500
Message-ID: <1321644888.1926.101.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-Developer <axiom-developer@nongnu.org>
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Fri, 18 Nov 2011 19:34:56 -0000

I just wrote an example of a literate program using HTML
syntax. There is a professor at Dartmouth who is willing
to talk to the class about it but found Knuth's version
too confusing. See

http://axiom-developer.org/axiom-website/litprog.html

In my opinion Knuth made the mistake of showing his mature
working environment that contains too many bells and whistles.
I have simplified the whole idea down to a simple tangle
program.

That said, I believe Knuth's idea of literate programming is
really a fundamental breakthrough. 

On Fri, 2011-11-18 at 12:53 -0500, Eugene Surowitz wrote:
> I was just at BICA2011 and they both record the talks and
> are actually creating DVDs along with the collected slides.
> (They sold last year's DVDs at this years conference.)
> Some are talks are on the web site.
> 
> I'm thinking along the line of a "text crawler" complemented
> by a relational data base with the capability to call up
> the literate pamphlets at a click.  Thus reverse walking
> gives a product support and development mechanism.
> The net result would be the ability to locate "foobar"
> whatever context it is in - code or description.

Google already does this I believe.

> I am assuming the however well Axiom gets pamphleteer-ed (ouch)
> the perversity of human nature will result in individuals
> shoehorning and shotgunning in code and comments in when
> and where it occurs to them.

The hope is that people will start making literate programming
part of their code development in groups. When you get to a code
review your code should be written as a section in a book. You
distribute this section before the code review and people can
now read "why" you wrote things.

If that happened then the code reviews would not amount to a
critique of "where to put braces" but a review of the whole
section, code and explanation.

You would not be able to check in code unless the whole thing
was clear and readable.

I would even advocate that there should be an Editor-in-chief
on the team. That is, an English major rather than a programmer.

> I would hope that the easier it is to do literate code cleanly
> would discourage that phenomena.

I started out using literate programming to try to preserve Axiom.
I think Axiom is a modern "Newton's Notebook" that arose from
the collision of math and computers. I have since learned that
literate programming makes me a much better programmer. It really
does change the quality of programs.

I've been pushing this professor to stop teaching people to
program like it is 1970 and start creating a new generation of
professional programmers who write clear, clean code that can
be understood and maintained.

The hard part is that literate programming is like lisp...
you struggle with it and struggle with it and wonder why anyone
would write code this way... and THEN AH-HA! you GET IT! And
then you wonder why anyone would write code any other way.

We can be better programmers.

> 
> Eugene J. Surowitz
> 
> On 11/14/2011 7:12 PM, daly wrote:
> > On Mon, 2011-11-14 at 14:08 -0500, Eugene Surowitz wrote:
> >> Will your talk and slides be available on the web?
> >
> > I gave a presentation at the Clojure Conj on Literate
> > Programming which was fairly well received but there were
> > no slides. I don't believe the talk was recorded.
> >
> > I have an article in the Notices of the American Mathematical
> > Society scheduled to appear in February.
> >
> >>
> >> Long term objective excellent; getting there is the rub.
> >> It's ok at the developed and distributed level,
> >> but from the developer's ant eye view the toc and index
> >> are only as good as the choice of structure and
> >> the entry selection.
> >
> > Indeed, that's a struggle for all authors. However, I have
> > made the index and cross references for every function and
> > variable.
> >
> >>
> >> There is also the headache of what the eyeball missed
> >> and what opinion bias does or does not consider important.
> >> Also texts tend to have concepts expressed as multiword
> >> strings, such as "table of contents".
> >> Pseudo-letters, such as "_" or "~", just add to the mess.
> >
> > Every function, macro, and variable is introduced with
> >       \defun{foo}
> >       \defmacro{foo}
> >       \defvar{foo}
> >
> > All of the index entries are hand generated using latex as in:
> >       \calls{foo}{bar}
> > which will put an entry under "foo" for "bar" and
> > an entry under "bar" for "foo". This means that it is trivial
> > to find every place that "bar" is called. This reverse-lookup
> > usually requires a code walker.
> >
> > For global variables there are:
> >       \refsdollar{foo}{var}
> >       \defsdollar{foo}{var}
> > which will put an entry in the index for $var.
> >
> >
> >>
> >> Exhaustive listing of everything was quite useful
> >> in another book effort.  For a code the size of Axiom,
> >> I guesstimate that a factor of three for the token file size.
> >>
> >> Eugene J. Surowitz
> >>
> >> On 11/12/2011 9:16 PM, daly wrote:
> >>> Well, the question is whether you're looking for a concept
> >>> (check table of contents) or a particular function (check
> >>> the index). At least that is the long term intention.
> >>>
> >>> On Fri, 2011-11-11 at 11:03 -0500, Eugene Surowitz wrote:
> >>>> I prefer the fountain pen for novelistic efforts.
> >>>>
> >>>> The issue that aroused my question has to do with
> >>>> comments that appear now and then in the list
> >>>> about knowing what is where in the source code.
> >>>>
> >>>> The reference to tools really was intended to address
> >>>> the idea of the utility of a mechanism(s) that could
> >>>> globally treat the entire source code as text to
> >>>> answer that question.
> >>>>
> >>>> Eugene J. Surowitz
> >>>>
> >>>> On 11/8/2011 4:42 PM, daly wrote:
> >>>>> Tools? The goal of literate programming is communicating from
> >>>>> human to human. It is like writing a novel. All you need is a
> >>>>> working Underwood typewriter and time.
> >>>>>
> >>>>> I tend to favor Latex because a lot of math is involved and
> >>>>> Latex prints math well. But I'm presenting a talk about
> >>>>> Literate Programming in North Carolina this week and I plan
> >>>>> to show examples that use XML, html, and video.
> >>>>>
> >>>>> Tim
> >>>>>
> >>>>> On Tue, 2011-11-08 at 15:03 -0500, Eugene Surowitz wrote:
> >>>>>> That literate programming is fully justified for Axiom is, well, almost axiomatic.
> >>>>>> But the issue is more how to boost the ability to invert the process
> >>>>>> and reverse engineer non-literate code piles into literate documents.
> >>>>>>
> >>>>>> What, in your opinion, would be the most effective type of tool that could
> >>>>>> be developed to render the literacy project more tractable?
> >>>>>>
> >>>>>> Eugene J. Surowitz
> >>>>>>
> >>>>>> On 11/8/2011 9:46 AM, daly@axiom-developer.org wrote:
> >>>>>>>> Yet to me, literate programming is certainly the most important thing
> >>>>>>>> that came out of the TeX project. Not only has it enabled me to write
> >>>>>>>> and maintain programs faster and more reliably than ever before, and
> >>>>>>>> been one of my greatest sources of joy since the 1980s -- it has
> >>>>>>>> actually been indispensable at times. Some of my major programs, such
> >>>>>>>> as the MMIX meta-simulator, could not have been written with any other
> >>>>>>>> methodology that I've ever heard of. The complexity was simply too
> >>>>>>>> daunting for my limited brain to handle; without literate programming,
> >>>>>>>> the whole enterprise would have flopped miserably.
> >>>>>>>>
> >>>>>>>> If people discover nice ways to use the newfangled multithreaded
> >>>>>>>> machines, I would expect the discovery to come from people who
> >>>>>>>> routinely use literate programming. Literate programming is what you
> >>>>>>>> need to rise above the ordinary level of achievement.
> >>>>>>>
> >>>>>>> I believe that Axiom's complexity is large enough to demand literate
> >>>>>>> programming. There are several reasons.
> >>>>>>>
> >>>>>>> First, computational mathematics requires people to be exceptional at
> >>>>>>> mathematics and programming. This is a small subset of already small
> >>>>>>> sets. We might as well add another subset of those who can communicate
> >>>>>>> their ideas in writing.
> >>>>>>>
> >>>>>>> Second, there are many design decisions that are necessary to reduce
> >>>>>>> a mathematical idea to implementation. Some of these design decisions
> >>>>>>> are mathematically arbitrary (e.g. branch cuts) or computationally
> >>>>>>> arbitrary (e.g. sparse versus dense) or programatically arbitrary
> >>>>>>> (e.g. all Spad versus Spad-and-lisp). These design decisions need to
> >>>>>>> be documented so people who maintain and modify the program know why
> >>>>>>> the decisions were made. Without this knowledge it would be trivial
> >>>>>>> to accidently destroy important optimizations.
> >>>>>>>
> >>>>>>> Third, nobody is an expert in the range of mathematics that Axiom can
> >>>>>>> and will implement. It is important to present some portions of the
> >>>>>>> theory associated with domains so people have a clue about the ideas
> >>>>>>> being encoded. Imagine what would happen if all of the math textbooks
> >>>>>>> only contained equations but no human-readable text. You might be able
> >>>>>>> to "read" a calculus textbook but not an infinite group theory textbook.
> >>>>>>>
> >>>>>>> Fourth, a million line program is too large to put into your head. You
> >>>>>>> need to have some background on the data structures, control flow, any
> >>>>>>> special tricks (e.g. funcalls through the symbol-plist), database
> >>>>>>> design, communication protocols (e.g. between Axiom and Hyperdoc and
> >>>>>>> Graphics), parsing structures, and a million other details. At best,
> >>>>>>> the code tells you HOW it does something but not WHY, not what it
> >>>>>>> depends on, not what depends on it, etc.
> >>>>>>>
> >>>>>>> Fifth, a program this large and this long-lived will eventually no
> >>>>>>> longer have the authors around to ask questions. Several of the Axiom
> >>>>>>> authors are already dead and most are not associated with it anymore.
> >>>>>>> Some of those authors are the world's expert in their subject matter.
> >>>>>>> That is a steep hill to climb if you want to understand the code,
> >>>>>>> especially if you have to debug or modify it.
> >>>>>>>
> >>>>>>> Sixth, in the 30 year horizon view, we need to pursue a new level of
> >>>>>>> excellence. As Knuth said:
> >>>>>>>
> >>>>>>>        "Literate programming is what you need to rise above
> >>>>>>>         the ordinary level of achievement"
> >>>>>>>
> >>>>>>> For all these reasons, and more, Axiom needs to be literate.
> >>>>>>>
> >>>>>>> Tim Daly
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> _______________________________________________
> >>>>>>> Axiom-developer mailing list
> >>>>>>> Axiom-developer@nongnu.org
> >>>>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
> >>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>>
> >>>>>> _______________________________________________
> >>>>>> Axiom-developer mailing list
> >>>>>> Axiom-developer@nongnu.org
> >>>>>> https://lists.nongnu.org/mailman/listinfo/axiom-developer
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>
> >>>
> >>>
> >>>
> >
> >
> >
> >




From MAILER-DAEMON Fri Nov 18 23:24:39 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRcTn-0004N5-Ob
	for mharc-axiom-developer@gnu.org; Fri, 18 Nov 2011 23:24:39 -0500
Received: from eggs.gnu.org ([140.186.70.92]:50973)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <smustudent1@yahoo.com>) id 1RRcTj-0004JZ-Ae
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 23:24:36 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <smustudent1@yahoo.com>) id 1RRcTi-0005rs-28
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 23:24:35 -0500
Received: from nm4-vm0.bullet.mail.bf1.yahoo.com ([98.139.213.129]:24350)
	by eggs.gnu.org with smtp (Exim 4.71)
	(envelope-from <smustudent1@yahoo.com>) id 1RRcTh-0005ro-UV
	for axiom-developer@nongnu.org; Fri, 18 Nov 2011 23:24:34 -0500
Received: from [98.139.212.148] by nm4.bullet.mail.bf1.yahoo.com with NNFMP;
	19 Nov 2011 04:24:33 -0000
Received: from [98.139.212.244] by tm5.bullet.mail.bf1.yahoo.com with NNFMP;
	19 Nov 2011 04:24:33 -0000
Received: from [127.0.0.1] by omp1053.mail.bf1.yahoo.com with NNFMP;
	19 Nov 2011 04:24:33 -0000
X-Yahoo-Newman-Property: ymail-3
X-Yahoo-Newman-Id: 486709.71956.bm@omp1053.mail.bf1.yahoo.com
Received: (qmail 72744 invoked by uid 60001); 19 Nov 2011 04:24:33 -0000
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s1024;
	t=1321676673; bh=RvLggE1E3As54FITgxpQPgIT3KVJeAMK6xgDSsbPG3Y=;
	h=X-YMail-OSG:Received:X-Mailer:References:Message-ID:Date:From:Reply-To:Subject:To:Cc:In-Reply-To:MIME-Version:Content-Type;
	b=v4OLbxB+tzQPKYkzGMegVj3Eta6Et0Ur9Ed1v1PMvGJtLJsUlssXxCCCCH/QoVG3/FcZvp/OG/suJfnUGM9diMkN/SOPlO1U9e473GUhIP21RnVbxhM/PocsuAodDA/Whmng886Vvc25ckLGsM57P186R0o/mQ1GkUxIE76s6t0=
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=s1024; d=yahoo.com;
	h=X-YMail-OSG:Received:X-Mailer:References:Message-ID:Date:From:Reply-To:Subject:To:Cc:In-Reply-To:MIME-Version:Content-Type;
	b=zYuaU+BV+/UDwn/PkYFFPJMP2wX6Xh5vuLNGL9fSRCKx+ZzIfagt5PIy0Zq6VKQ6TIkQHVOXHK6KZmcX4oKgxU27KKmw4hzMJjn5a4Y1YWtnk9cGtMdqTdsuuGFAi25YZtnKZBsQwXqAERCOpKXj5P32qre3q40J80HOkOEskNE=;
X-YMail-OSG: hOLgSxcVM1leSJ5noDJiPBxZELwQOfSnzStqjqrnJEADFKL
	rfQEy7XzrAbK4qCrx.Qa_brfxfdM0b6DAypq77eviJO7HJ7IBYYl24FJERqZ
	.ZB0KDI6vtigupvzDX4ZD3RS_ZEIFybN6JpvYvt.QNJHRDkLbqMPn2oxxuzM
	XQok8lyrnWxOwVWOanSDcbUd8TH2UjgtUctwFM42fXucox6nu7lIU5sU6Unx
	Qw8xrQv8xDNglMp4FDwFqIofBaX76ukdtJdg.j55aINl7YON5DnPtdFTKv0E
	W.oUo4FhyVKVqzB8O8g62URRLyuysVyZPoJEJhopnl.XRqQvvmgHI42vVIFs
	jfdY0yCVOaaDSvJsbt4Zpb5YXVCV4h8JR2H9eZQyLHxh9GY1wkPCqTLP1T6q
	MgJhmgzD2PeFBNSB932CvL6ThWSF51w7B7Lmyxui7Qp2l5zaFu7Frk3BLUQN
	o4deE6GShtxzUug--
Received: from [173.75.184.72] by web161602.mail.bf1.yahoo.com via HTTP;
	Fri, 18 Nov 2011 20:24:33 PST
X-Mailer: YahooMailWebService/0.8.115.325013
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net>
	<1320788526.30722.1188.camel@pewter>
	<4EBD474E.3040709@attglobal.net> <1321150607.1926.2.camel@pewter>
	<4EC16735.6090302@attglobal.net> <1321315932.1926.22.camel@pewter>
	<4EC69BA3.9060001@attglobal.net> <1321644888.1926.101.camel@pewter>
Message-ID: <1321676673.71132.YahooMailNeo@web161602.mail.bf1.yahoo.com>
Date: Fri, 18 Nov 2011 20:24:33 -0800 (PST)
From: C Y <smustudent1@yahoo.com>
To: daly <daly@axiom-developer.org>
In-Reply-To: <1321644888.1926.101.camel@pewter>
MIME-Version: 1.0
Content-Type: multipart/alternative;
	boundary="406169123-1686376347-1321676673=:71132"
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 98.139.213.129
Cc: axiom-Developer <axiom-developer@nongnu.org>
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: C Y <smustudent1@yahoo.com>
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 04:24:36 -0000

--406169123-1686376347-1321676673=:71132
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable

Tim, =0A=0A=0AThat's quite an interesting example!=A0 Is there a license on=
 it?=A0 I can see that being useful in a lot of scenarios as an introductio=
n to the idea of literate programming.=0A=0ACheers,=0ACY=0A=0A=0A=0A_______=
_________________________=0A From: daly <daly@axiom-developer.org>=0ATo: su=
row@attglobal.net =0ACc: axiom-Developer <axiom-developer@nongnu.org> =0ASe=
nt: Friday, November 18, 2011 2:34 PM=0ASubject: Re: [Axiom-developer] Lite=
rate Programming -- Knuth interview=0A =0AI just wrote an example of a lite=
rate program using HTML=0Asyntax. There is a professor at Dartmouth who is =
willing=0Ato talk to the class about it but found Knuth's version=0Atoo con=
fusing. See=0A=0Ahttp://axiom-developer.org/axiom-website/litprog.html
--406169123-1686376347-1321676673=:71132
Content-Type: text/html; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable

<html><body><div style=3D"color:#000; background-color:#fff; font-family:ti=
mes new roman, new york, times, serif;font-size:12pt"><div><span>Tim, <br><=
/span></div><div><br><span></span></div><div><span>That's quite an interest=
ing example!&nbsp; Is there a license on it?&nbsp; I can see that being use=
ful in a lot of scenarios as an introduction to the idea of literate progra=
mming.</span></div><div><br><span></span></div><div><span>Cheers,</span></d=
iv><div><span>CY</span></div><div><br></div>  <div style=3D"font-family: ti=
mes new roman, new york, times, serif; font-size: 12pt;"> <div style=3D"fon=
t-family: times new roman, new york, times, serif; font-size: 12pt;"> <font=
 size=3D"2" face=3D"Arial"> <hr size=3D"1">  <b><span style=3D"font-weight:=
bold;">From:</span></b> daly &lt;daly@axiom-developer.org&gt;<br> <b><span =
style=3D"font-weight: bold;">To:</span></b> surow@attglobal.net <br><b><spa=
n style=3D"font-weight: bold;">Cc:</span></b> axiom-Developer
 &lt;axiom-developer@nongnu.org&gt; <br> <b><span style=3D"font-weight: bol=
d;">Sent:</span></b> Friday, November 18, 2011 2:34 PM<br> <b><span style=
=3D"font-weight: bold;">Subject:</span></b> Re: [Axiom-developer] Literate =
Programming -- Knuth interview<br> </font> <br>=0AI just wrote an example o=
f a literate program using HTML<br>syntax. There is a professor at Dartmout=
h who is willing<br>to talk to the class about it but found Knuth's version=
<br>too confusing. See<br><br>http://axiom-developer.org/axiom-website/litp=
rog.html<br><br><br><br> </div> </div>  </div></body></html>
--406169123-1686376347-1321676673=:71132--


From MAILER-DAEMON Sat Nov 19 00:03:44 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRd5c-0006tX-Ra
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 00:03:44 -0500
Received: from eggs.gnu.org ([140.186.70.92]:60317)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRd5Z-0006sa-Nr
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 00:03:43 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRd5X-0002yQ-MF
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 00:03:41 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:38320
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRd5X-0002yG-H5
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 00:03:39 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAJ53b75003129;
	Fri, 18 Nov 2011 23:03:37 -0600
From: daly <daly@axiom-developer.org>
To: C Y <smustudent1@yahoo.com>
In-Reply-To: <1321676673.71132.YahooMailNeo@web161602.mail.bf1.yahoo.com>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<4EB98B18.9090407@attglobal.net> <1320788526.30722.1188.camel@pewter>
	<4EBD474E.3040709@attglobal.net> <1321150607.1926.2.camel@pewter>
	<4EC16735.6090302@attglobal.net> <1321315932.1926.22.camel@pewter>
	<4EC69BA3.9060001@attglobal.net> <1321644888.1926.101.camel@pewter>
	<1321676673.71132.YahooMailNeo@web161602.mail.bf1.yahoo.com>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 19 Nov 2011 00:03:35 -0500
Message-ID: <1321679015.1926.170.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-Developer <axiom-developer@nongnu.org>
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 05:03:43 -0000

On Fri, 2011-11-18 at 20:24 -0800, C Y wrote: 
> Tim, 
> 
> 
> 
> That's quite an interesting example!  Is there a license on it?  I can
> see that being useful in a lot of scenarios as an introduction to the
> idea of literate programming.
> 
> 
> Cheers,
> CY
> 
License? Nope.

You have my permission to use it in any fashion anywhere,
at any time, for any purpose.

It would be fun to create a viral-literate license that
required you to write all your published programs that way :-)

I posted the example to the Clojure mailing list and got 
a response which I include here.

On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote:
> On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly wrote:
>         Many of you asked me to show an example of a literate
>         program and demonstrate the use of the tangle function.
>         
>         I usually use Latex for literate work but I've done
>         this example using HTML and <pre id="foo"> tags.
>         
>         I've written a self-referential literate program that
>         explains the details of the tangle function in literate
>         form. You can find the web page at
>         
>         http://daly.literatesoftware.com/lithtml/litprog.html
>         
> I have read your literate program, and must recognize that I know how
> tangle works even though I didn't want to really read the source code.
> I read your prose all the way through. I still haven't read the source
> code; 

In fact, that's the whole point. You don't read the equations in a
calculus textbook either. You read the words. The equations are icons.
If you understood the text and "spoke" mathematics you could probably
write the equations.

In programming we can reach the same level of literacy. Reading just
the words in the literate version it should be possible to recreate
the program in your favorite language. Note that you would be creating
a different program with different design decisions but the same 
functionality. 

> I didn't feel the need to read it. Were I to maintain your program,
> I'd have more than enough confidence to start hacking the code right
> now.

One thing worth trying would be to code the same program in Clojure.

The tangle program is conceptually very simple but there are a lot
of low level design decisions that I would make differently. For
example, there are loops in the C program which would go away.

Would you map read or would you slurp? Mapping a read function allows
transforming "& lt;" to < at read time. This does not matter in the C
program because the buffer is mutable but it would matter in Clojure.

Would you use the Clojure pattern language to find the <pre> tags?
Would you be able to parse out the string from the id? C encourages
character-level hacking but Clojure would be much more powerful.

> 
> 
> I think this speaks very positively about literate programming. What
> remains to be seen is how much (or not) I'm going to practice it in
> the future.

If you do try to rewrite it in Clojure please post the program. I 
would be very interested to see how Clojure's concise syntax and
semantics get reflected in your design decisions.

The tangle program in Clojure might turn out to be a single
s-expression of only a few lines. The code density would be a
huge win but a literate version would still have to have the
vitals of the story. Remember that the key test for a literate
program is the "independence test". Someone can read it without
talking to you, understand how it works, and be able to change it.

> 
> 
> What do you think of marginalia? It's a bit the reverse of tangle; it
> assembles all those 70's files together into this book you might want
> to read. Is it sound or not? Have your thoughts changed from what you
> wrote in [1]?
> 
> 
> [1] http://goo.gl/cXWzF

Literate programming is a mindset, not a tool. You can write a 
literate program in anything, including marginalia.

That said, I have yet to see a Clojure program that lays out a story
so I can sit and read it. For a real challenge, if you try to write
tangle in Clojure, try writing the story in marginalia. I'm sure
Fogus would welcome the feedback.


The readability aspect is a real feature. Heck, you could even give 
your programs to a company so they could read them BEFORE the job
interview. I would strongly favor hiring someone who could 
communicate, who cared about code quality, and who could improve
the company's maintenance headache in the long term. A Literate
Clojure programmer would be a real gotta-hire person. Companies
use many programming languages but all programmers really do need
good communication skills. 


In the long view, it would be sweet if the Clojure reader knew how
to read a literate program. Just call "(literate-load file chunk)" 
and you get the same effect as if you had tangled the program to 
a file.

With literate-load available you would be able to write all of
your Clojure code in a literate style, making Clojure much 
easier to understand, maintain, and modify.



Tim Daly





> 
> 

> 
> 
> 
> 




From MAILER-DAEMON Sat Nov 19 03:42:21 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRgVA-000401-MN
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 03:42:20 -0500
Received: from eggs.gnu.org ([140.186.70.92]:44099)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRgV8-0003xP-Cm
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 03:42:19 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRgV7-0001o7-D6
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 03:42:18 -0500
Received: from moutng.kundenserver.de ([212.227.126.186]:63443)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRgV7-0001nh-2W
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 03:42:17 -0500
Received: from linux-lkky.localnet (188-223-141-163.zone14.bethere.co.uk
	[188.223.141.163])
	by mrelayeu.kundenserver.de (node=mreu1) with ESMTP (Nemesis)
	id 0Lla4p-1QqhSE3Q99-00aolN; Sat, 19 Nov 2011 09:42:13 +0100
From: Martin Baker <ax87438@martinb.com>
To: axiom-developer@nongnu.org
Date: Sat, 19 Nov 2011 08:42:42 +0000
User-Agent: KMail/1.13.6 (Linux/2.6.37.6-0.9-desktop; KDE/4.6.0; x86_64; ; )
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<1321676673.71132.YahooMailNeo@web161602.mail.bf1.yahoo.com>
	<1321679015.1926.170.camel@pewter>
In-Reply-To: <1321679015.1926.170.camel@pewter>
MIME-Version: 1.0
Content-Type: Text/Plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Message-Id: <201111190842.42553.ax87438@martinb.com>
X-Provags-ID: V02:K0:c7OZb5hhcCWOfKY0Iw8hLKYzMmNrcaJvWnqlVpcZBeg
	E2nbD6GChdrEwl2s+hhPWsEe02UE89h31BgDgevGzM00LWriux
	ear5LZKWfbbzuPJN+1gGj5APYdtnfsgUOlTBmSOsQ3NC0j6fRt
	+Vs7xjrzgmgq0nOoDGmGmYqiyINp2PjRBTTUOpUT69Hjy5xThO
	SVjZOD1HNuUVkgYlFyK3xqCwqZkxGYTtxaysSSoC5vpsedbBLs
	au5AQtOq424N50EXvkmRYuDqq75oS6Qesd8SUP7v/TOTk1f+eB
	8SkNpSs6mKbYGi0BLVPrzVKQsj6obHJ18ojQ6p8cfak0xd7Csd
	WnB86RLhJ/hR3ibylIo8k533WY6yPqirV4hhaodOM
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 212.227.126.186
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 08:42:19 -0000

Tim,

One issue that occurred to me on this subject. It seems to me the point of 
HTML and hypertext is that they are not a linear book. What I like about this 
is that the reader can start at a high level with a small and concise page but 
they can drill down to any level of detail they may need. Also there can be 
different entry points for different types of readers such as end users as 
well as programmers. It would be good if all these types of 'documentation' 
could be produced by the same tools and advanced end users could drill down to 
information originally intended for programmers. Using standard code libraries 
its probably easier to access HTML user documentation/'help files' from within 
the program rather than writing custom code like hyperdoc.

I can see the advantages in putting the literate 'documentation' interleaved 
in the same file as the code. However there also seem to be a lot of 
disadvantages such as making the above ideas more difficult?

Martin


From MAILER-DAEMON Sat Nov 19 04:31:09 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRhGO-00040l-V1
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 04:31:08 -0500
Received: from eggs.gnu.org ([140.186.70.92]:57352)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRhGL-0003x9-NP
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 04:31:06 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRhGK-0001GW-A7
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 04:31:05 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:48391
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRhGK-0001GI-2W
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 04:31:04 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAJ9Uw75019176;
	Sat, 19 Nov 2011 03:30:59 -0600
From: daly <daly@axiom-developer.org>
To: Martin Baker <ax87438@martinb.com>
In-Reply-To: <201111190842.42553.ax87438@martinb.com>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<1321676673.71132.YahooMailNeo@web161602.mail.bf1.yahoo.com>
	<1321679015.1926.170.camel@pewter>
	<201111190842.42553.ax87438@martinb.com>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 19 Nov 2011 04:30:57 -0500
Message-ID: <1321695057.1926.207.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 09:31:06 -0000

On Sat, 2011-11-19 at 08:42 +0000, Martin Baker wrote:
> Tim,
> 
> One issue that occurred to me on this subject. It seems to me the point of 
> HTML and hypertext is that they are not a linear book. What I like about this 
> is that the reader can start at a high level with a small and concise page but 
> they can drill down to any level of detail they may need. Also there can be 
> different entry points for different types of readers such as end users as 
> well as programmers. It would be good if all these types of 'documentation' 
> could be produced by the same tools and advanced end users could drill down to 
> information originally intended for programmers. Using standard code libraries 
> its probably easier to access HTML user documentation/'help files' from within 
> the program rather than writing custom code like hyperdoc.

I chose HTML as the example case because it is known to everyone.
I much prefer latex but not everyone does.

Axiom has an implementation of an HTML replacement for hyperdoc in
Volume 11. There is still much work to be done.

I believe the split between end users and programmers is artificial
and an artifact of the way we currently develop code.

Consider writing a textbook. You start out writing what you believe will
be the first chapter, diving right into the interesting material. 
Eventually you find that Chapter 1 requires some background material
so you write a new Chapter 1 and your interesting material is now in
Chapter 2. As you continue this process you find that the material
you originally put in Chapter 1 is now somewhere near Chapter 4 because
you found many ideas that needed to be explained before you could really
cover the interesting material. 

Often I will read the first 3 chapters of a textbook, then find another
textbook on the same subject and read those first 3 chapters, and even
a third textbook. By the time I've done that I have a firm grasp on the
background essentials and find that I can make progress on later 
chapters with core material.

We have this belief that programmers have a natural ability to dive
into code that is lacking in other people. We assume that someone who
"speaks" C can just read the program and understand it. In my 
experience this is a bad assumption. Programmers have no way to
guess at a design decision that is not written in words any better
than anyone else. Nor do programmers have a magic mind that allows 
them to look at several hundred "sand files" and derive the big 
ideas of the program. Yet we continue to act as if they do.

My experience with literate programming has led me to expect that I
have to write the "first three chapters" (sections, paragraphs, or
whatever) as general overview. I have to make gradual steps from
ideas to implementation. Done properly I believe anyone can read a
literate program, at least superficially, and especially so for the
first few chapters.

After all, the point of literate programming is to communicate ideas
from one human to another. 

The organization of the material into one or many web pages is not
particularly important. I tend to follow the "book" metaphor as
I tend to read a lot of books. Linear material spread over a lot of
pages simply breaks my "linear mind" and I tend to stop reading after
getting a few pages into the material. However, with a PDF style
book my Kindle or PDF reader keeps my last-read-page bookmark and
I can pick up where I left off. 


> 
> I can see the advantages in putting the literate 'documentation' interleaved 
> in the same file as the code. However there also seem to be a lot of 
> disadvantages such as making the above ideas more difficult?

The key test for literate documentation is the "independence test".
Can you point someone at your literate program, have them go off
somewhere to read it, and then come back with the ability to maintain
and modify it?

When you read the tangle web page did you feel that it needed to be
broken up? I thought it made a reasonably smooth transition from the
ideas to the code details with enough words so you could skip reading
the actual code. The code is just there as icons for humans, like
equations in a math book.

If you feel that interleaving videos, animations, navigation, and any
other tricks improves the "independence test" results then these
techniques should be used. If, however, you are just trying to 
organize the material by some random criteria (e.g. alphabetical
or as trees of logically grouped files) then you are undermining 
the transfer of ideas.

Even today, with all of the hyperlinking tricks available, I still
see my iPad using linear, book-like presentations.

Tim 




From MAILER-DAEMON Sat Nov 19 05:36:14 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRiHO-0000Pe-GI
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 05:36:14 -0500
Received: from eggs.gnu.org ([140.186.70.92]:38969)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRiHM-0000Ov-2R
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 05:36:13 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRiHL-0001Ol-38
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 05:36:11 -0500
Received: from moutng.kundenserver.de ([212.227.126.171]:52498)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRiHK-0001Oe-LT
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 05:36:11 -0500
Received: from linux-lkky.localnet (188-223-141-163.zone14.bethere.co.uk
	[188.223.141.163])
	by mrelayeu.kundenserver.de (node=mrbap3) with ESMTP (Nemesis)
	id 0LyUBK-1QmRSw3z0Q-015tDm; Sat, 19 Nov 2011 11:36:09 +0100
From: Martin Baker <ax87438@martinb.com>
To: axiom-developer@nongnu.org
Date: Sat, 19 Nov 2011 10:36:46 +0000
User-Agent: KMail/1.13.6 (Linux/2.6.37.6-0.9-desktop; KDE/4.6.0; x86_64; ; )
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<201111190842.42553.ax87438@martinb.com>
	<1321695057.1926.207.camel@pewter>
In-Reply-To: <1321695057.1926.207.camel@pewter>
MIME-Version: 1.0
Content-Type: Text/Plain;
  charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <201111191036.46908.ax87438@martinb.com>
X-Provags-ID: V02:K0:dZ9wNOBoxOUP7uSL7MbbW3+oaMvwqxJTTFqtiu6G7E0
	UqeuJxx4yUH1ZU1VIwlgx+7k42ShWGe5JmVAmtxcLrx7chx6vh
	rTC1u8G+YaHyZ5tjl8cJLumGenNfOhuSsVJgWoK5kz2swcpa4z
	/xXBJ22ctVp9Awjs2nz4+rliuupCvMEKuaD3uStW8TAlupARzf
	lI2isBtRn3uKTLoowyO3yswalO2Vw4Xrt9ee4i562rv/NInLrQ
	Or03A8P9K0AI+M9KE7beL3IMCe57m+kJqAmm3lghb7lDzgqBuU
	bW6iFZ8eFe2fhnkPEeyKvgJfYvKfl7oE1W94Dz1A3VXYi3Mwhy
	5kYcsr4bJk31+Vtz51qbtmk2y+HVmJ5kKtB7885dk
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 212.227.126.171
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 10:36:13 -0000

> If you feel that interleaving videos, animations, navigation, and any
> other tricks improves the "independence test" results then these
> techniques should be used. If, however, you are just trying to
> organize the material by some random criteria (e.g. alphabetical
> or as trees of logically grouped files) then you are undermining
> the transfer of ideas.

Tim,

I think we may agree about the importance and general principles of this and 
we are just discussing the mechanics here? (although I think that navigation 
and diagrams are much more fundamental and powerful than just "tricks")

I think its good to take into account practical matters and allow the use of 
standard HTML and code editors and to separate these principles from the tools 
used.

I don't see problem in having multiple source, HTML and diagram files treated 
as single entity (in a ZIP file or something similar) the entry points would 
be at the root. I cant see a problem for the "independence test".

When the code is complied the HTML files can be transferred unchanged to the 
runtime so they are available for hyperdoc(HTML version) and help files at 
runtime.

Martin


From MAILER-DAEMON Sat Nov 19 05:41:57 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRiMv-0000s2-QS
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 05:41:57 -0500
Received: from eggs.gnu.org ([140.186.70.92]:52329)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRiMt-0000qs-7U
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 05:41:56 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRiMs-00024T-8I
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 05:41:55 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:58858
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRiMs-00024N-3A
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 05:41:54 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAJAfo75002455;
	Sat, 19 Nov 2011 04:41:51 -0600
From: daly <daly@axiom-developer.org>
To: Martin Baker <ax87438@martinb.com>
In-Reply-To: <201111191017.30876.ax87438@martinb.com>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<201111190842.42553.ax87438@martinb.com>
	<1321695057.1926.207.camel@pewter>
	<201111191017.30876.ax87438@martinb.com>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 19 Nov 2011 05:41:48 -0500
Message-ID: <1321699308.1926.227.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 10:41:56 -0000

On Sat, 2011-11-19 at 10:17 +0000, Martin Baker wrote:
> > If you feel that interleaving videos, animations, navigation, and any
> > other tricks improves the "independence test" results then these
> > techniques should be used. If, however, you are just trying to
> > organize the material by some random criteria (e.g. alphabetical
> > or as trees of logically grouped files) then you are undermining
> > the transfer of ideas.
> 
> Tim,
> 
> I think we may agree about the importance and general principles of this and 
> we are just discussing the mechanics here? (although I think that navigation 
> and diagrams are much more fundamental and powerful than just "tricks")

I think we are in agreement on principles I still shy away from a 
focus on the mechanics. Think typewriters.

> 
> I think its good to take into account practical matters and allow the use of 
> standard HTML and code editors and to separate these principles from the tools 
> used.

Well, maybe. Programmers love their tools and see nothing wrong with 
splashing "documentation" all over a tree of little files. You could
write a literate program that way but it would be like reading a
book in weekly installments in a magazine.

> 
> I don't see problem in having multiple source, HTML and diagram files treated 
> as single entity (in a ZIP file or something similar) the entry points would 
> be at the root. I cant see a problem for the "independence test".

Several people have pointed me at trees of code that are supposed to be
in a literate style. The problem is that they have confused the idea of
documentation or comments with the idea of literate programming.

Literate programming makes the human to human communication paramount.
This means that you ought to be able to "sit and read", like any good
novel. You could easily print the example page I used and read it from
beginning to end without a computer.

Documentation and comment systems are not like this. They make the
program organization "fit the machine". They talk about the code, and
focus on line-by-line or file-by-file. They tend to work well with all
kinds of "tools" like Eclipse, Javadoc, or Doxygen.

It is easy to confuse literate programming with these documentation
and commenting system but they are nowhere the same.

So if I have to know anything about file organization, if I have to
pop between files or if I have to have rules about what the correct
syntax is (e.g. Javadoc) then I am looking at a documentation and
comment system.

If I can write a story in any form I want and splash code icons in at
the appropriate moment, if the story focuses on ideas, and if I can
understand it without looking at the code then I am looking at a
literate program.

> 
> When the code is complied the HTML files can be transferred unchanged to the 
> runtime so they are available for hyperdoc(HTML version) and help files at 
> runtime.

That's a documentation and commenting tool.

Tim






From MAILER-DAEMON Sat Nov 19 11:11:03 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRnVP-0007I1-DW
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 11:11:03 -0500
Received: from eggs.gnu.org ([140.186.70.92]:58612)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRnVM-0007H8-Pl
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 11:11:01 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRnVL-00028A-CR
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 11:11:00 -0500
Received: from moutng.kundenserver.de ([212.227.126.171]:60562)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <ax87438@martinb.com>) id 1RRnVK-000285-U5
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 11:10:59 -0500
Received: from linux-lkky.localnet (188-223-141-163.zone14.bethere.co.uk
	[188.223.141.163])
	by mrelayeu.kundenserver.de (node=mrbap0) with ESMTP (Nemesis)
	id 0MDWCD-1RfqGq0t1Z-00HQTG; Sat, 19 Nov 2011 17:10:57 +0100
From: Martin Baker <ax87438@martinb.com>
To: axiom-developer@nongnu.org
Date: Sat, 19 Nov 2011 16:11:30 +0000
User-Agent: KMail/1.13.6 (Linux/2.6.37.6-0.9-desktop; KDE/4.6.0; x86_64; ; )
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<201111191017.30876.ax87438@martinb.com>
	<1321699308.1926.227.camel@pewter>
In-Reply-To: <1321699308.1926.227.camel@pewter>
MIME-Version: 1.0
Content-Type: Text/Plain;
  charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <201111191611.30770.ax87438@martinb.com>
X-Provags-ID: V02:K0:IjJYnwdGU8VsjnpzsAPFY6C2ID+NNq1fvnk5oPZVBAj
	oPcoEtpXpR5ioOk5BYatWWwzVtIv4pFT8EDAfB7qHHdO63Xr2O
	dFi0mwFmnANgTmmO4O8kDdTm80RjRTM8Pnk1vqX+xhq9qYS4Mx
	54lUb1SaPk1FHTf69tf0+c0FxIe3GFZWbgqIZ6nZDAkYz+cH8v
	rEMryMdiAgRt2ScE2pM96ahHehmKLg4Xk0qRPdKhKysUTSkZb6
	/ivagMlnZldm3+6rLnuSeUir+IjRnVQ1xaElnIRsVascn8mWOA
	hqtFwEDixrwA86iwSpbIvwqLo1ATjugSurOxj4Fxfx845csSr1
	QUmmCh4lcR51Q+WjSLR61UF0Y3jBHnbdZ4kwdB/uJ
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 212.227.126.171
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 16:11:01 -0000

> Documentation and comment systems are not like this. They make the
> program organization "fit the machine". They talk about the code, and
> focus on line-by-line or file-by-file. They tend to work well with all
> kinds of "tools" like Eclipse, Javadoc, or Doxygen.

I tend think of this as reference information. The sort of thing that Axiom 
produces dynamically at runtime like )show and )display. I think there would 
be advantages in generating this statically with a compile-time documentation 
tool, the information would be much more richly interlinked with itself and 
the other type of information.

> It is easy to confuse literate programming with these documentation
> and commenting system but they are nowhere the same.

They may not be the same but why should the user have to switch between them 
and know which to use and when?

In Axiom, I have often tried to find something in pdf generated by literate 
code when what I wanted was in hyperdoc or runtime commands or visa-versa. 
There seems to be a lot of overlap of these sources of information in Axiom. I 
would like to be able to link between them by clicking on the text.

Also I may be reading something as a story when I come across some issue that 
I need to clarify which may be a different type of documentation and so I need 
to switch to a more reference way of working. I think there are all kinds of 
things that the user/maintainer needs to do between these extremes and I find 
well produced HTML to be the best way to get to the information that I need 
(of course, like anything else, there is a lot of bad HTML around).

Also I think a tree structure scales up better than a linear structure.  A 
story works well for a small program, but for a big program like Axiom, there 
has to be some form of structure doesn't there? 

Martin




From MAILER-DAEMON Sat Nov 19 14:09:56 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRqIW-0004zW-Ty
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 14:09:56 -0500
Received: from eggs.gnu.org ([140.186.70.92]:45168)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRqIV-0004zN-60
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:09:56 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRqIU-0006hR-0l
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:09:55 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:54002
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRqIT-0006hG-PT
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:09:53 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAJJ9n75002052;
	Sat, 19 Nov 2011 13:09:49 -0600
From: daly <daly@axiom-developer.org>
To: Martin Baker <ax87438@martinb.com>
In-Reply-To: <201111191611.30770.ax87438@martinb.com>
References: <201111081446.pA8EkJoC019212@axiom-developer.org>
	<201111191017.30876.ax87438@martinb.com>
	<1321699308.1926.227.camel@pewter>
	<201111191611.30770.ax87438@martinb.com>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 19 Nov 2011 14:09:47 -0500
Message-ID: <1321729787.1926.240.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming -- Knuth interview
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 19:09:56 -0000

On Sat, 2011-11-19 at 16:11 +0000, Martin Baker wrote:
> > Documentation and comment systems are not like this. They make the
> > program organization "fit the machine". They talk about the code, and
> > focus on line-by-line or file-by-file. They tend to work well with all
> > kinds of "tools" like Eclipse, Javadoc, or Doxygen.
> 
> I tend think of this as reference information. The sort of thing that Axiom 
> produces dynamically at runtime like )show and )display. I think there would 
> be advantages in generating this statically with a compile-time documentation 
> tool, the information would be much more richly interlinked with itself and 
> the other type of information.
> 
> > It is easy to confuse literate programming with these documentation
> > and commenting system but they are nowhere the same.
> 
> They may not be the same but why should the user have to switch between them 
> and know which to use and when?
> 
> In Axiom, I have often tried to find something in pdf generated by literate 
> code when what I wanted was in hyperdoc or runtime commands or visa-versa. 
> There seems to be a lot of overlap of these sources of information in Axiom. I 
> would like to be able to link between them by clicking on the text.
> 
> Also I may be reading something as a story when I come across some issue that 
> I need to clarify which may be a different type of documentation and so I need 
> to switch to a more reference way of working. I think there are all kinds of 
> things that the user/maintainer needs to do between these extremes and I find 
> well produced HTML to be the best way to get to the information that I need 
> (of course, like anything else, there is a lot of bad HTML around).
> 
> Also I think a tree structure scales up better than a linear structure.  A 
> story works well for a small program, but for a big program like Axiom, there 
> has to be some form of structure doesn't there? 

Frankly, I don't know. I am learning what works and what doesn't as I
go. Axiom is the largest literate program I'm aware of so there are no
examples. I get to invent the mistakes.

Volume 12 is about the Crystal. The crystal idea is that there is a core
problem. Wrapped around the problem is a crystal with many facets. Each
facet presents a different view of the core problem. My thinking is
that one facet presents a PDF view of related material, say by showing
a particular section of the book. Another facet presents related
hyperdoc material. A third facet presents related code. A fourth
facet presents related material in HTML form, with embedded video
or animations. A fifth facet would show a graph, like the domain
graph, related to the problem. You "rotate" the crystal to find the
facet that has the information you want.

So I think there is a place for all of the various representations.
They need to be driven from the core problem. To my knowledge, there
are no examples and no effort anywhere to develop a crystal and 
facets idea. So this is all just one big research experiment on 
my part.

Tim




From MAILER-DAEMON Sat Nov 19 14:37:58 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRqjd-0000b5-Vq
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 14:37:57 -0500
Received: from eggs.gnu.org ([140.186.70.92]:41927)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRqjb-0000az-LR
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:37:57 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRqjZ-0003ge-R5
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:37:55 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:52773
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRqjZ-0003gZ-Li
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:37:53 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAJJbo75006815;
	Sat, 19 Nov 2011 13:37:50 -0600
From: daly <daly@axiom-developer.org>
To: clojure@googlegroups.com
In-Reply-To: <CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
References: <1321618628.1926.75.camel@pewter>
	<33378874.2870.1321675364798.JavaMail.geo-discussion-forums@yqoo7>
	<b75acd9e-855a-491b-b9fb-ae7ce813438a@q11g2000vbq.googlegroups.com>
	<CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 19 Nov 2011 14:37:48 -0500
Message-ID: <1321731468.1926.267.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming example
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 19:37:57 -0000

On Sat, 2011-11-19 at 14:35 +0100, Laurent PETIT wrote:
> Hello,
> 
> 2011/11/19 TimDaly <daly@axiom-developer.org>
>         On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote:
>         > On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly
>         wrote:
>         >         Many of you asked me to show an example of a
>         literate
>         >         program and demonstrate the use of the tangle
>         function.
>         >
>         >         I usually use Latex for literate work but I've done
>         >         this example using HTML and <pre id="foo"> tags.
>         >
>         >         I've written a self-referential literate program
>         that
>         >         explains the details of the tangle function in
>         literate
>         >         form. You can find the web page at
>         >
>         >
>         http://daly.literatesoftware.com/lithtml/litprog.html
>         >
>         > I have read your literate program, and must recognize that I
>         know how
>         > tangle works even though I didn't want to really read the
>         source code.
>         > I read your prose all the way through. I still haven't read
>         the source
>         > code;
>         
>         
>         In fact, that's the whole point. You don't read the equations
>         in a
>         calculus textbook either. You read the words. The equations
>         are icons.
>         If you understood the text and "spoke" mathematics you could
>         probably
>         write the equations.
>         
>         In programming we can reach the same level of literacy.
>         Reading just
>         the words in the literate version it should be possible to
>         recreate
>         the program in your favorite language. Note that you would be
>         creating
>         a different program with different design decisions but the
>         same
>         functionality.
>         
>         > I didn't feel the need to read it. Were I to maintain your
>         program,
>         > I'd have more than enough confidence to start hacking the
>         code right
>         > now.
>         
>         
>         One thing worth trying would be to code the same program in
>         Clojure.
>         
>         The tangle program is conceptually very simple but there are a
>         lot
>         of low level design decisions that I would make differently.
>         For
>         example, there are loops in the C program which would go away.
>         
>         Would you map read or would you slurp? Mapping a read function
>         allows
>         transforming "& lt;" to < at read time. This does not matter
>         in the C
>         program because the buffer is mutable but it would matter in
>         Clojure.
>         
>         Would you use the Clojure pattern language to find the <pre>
>         tags?
>         Would you be able to parse out the string from the id? C
>         encourages
>         character-level hacking but Clojure would be much more
>         powerful.
>         
>         >
>         >
>         > I think this speaks very positively about literate
>         programming. What
>         > remains to be seen is how much (or not) I'm going to
>         practice it in
>         > the future.
>         
>         
>         If you do try to rewrite it in Clojure please post the
>         program. I
>         would be very interested to see how Clojure's concise syntax
>         and
>         semantics get reflected in your design decisions.
>         
>         The tangle program in Clojure might turn out to be a single
>         s-expression of only a few lines. The code density would be a
>         huge win but a literate version would still have to have the
>         vitals of the story. Remember that the key test for a literate
>         program is the "independence test". Someone can read it
>         without
>         talking to you, understand how it works, and be able to change
>         it.
>         
>         >
>         >
>         > What do you think of marginalia? It's a bit the reverse of
>         tangle; it
>         > assembles all those 70's files together into this book you
>         might want
>         > to read. Is it sound or not? Have your thoughts changed from
>         what you
>         > wrote in [1]?
>         >
>         >
>         > [1] http://goo.gl/cXWzF
>         
>         
>         Literate programming is a mindset, not a tool. You can write a
>         literate program in anything, including marginalia.
>         
>         That said, I have yet to see a Clojure program that lays out a
>         story
>         so I can sit and read it. For a real challenge, if you try to
>         write
>         tangle in Clojure, try writing the story in marginalia. I'm
>         sure
>         Fogus would welcome the feedback.
>         
>         
>         The readability aspect is a real feature. Heck, you could even
>         give
>         your programs to a company so they could read them BEFORE the
>         job
>         interview. I would strongly favor hiring someone who could
>         communicate, who cared about code quality, and who could
>         improve
>         the company's maintenance headache in the long term. A
>         Literate
>         Clojure programmer would be a real gotta-hire person.
>         Companies
>         use many programming languages but all programmers really do
>         need
>         good communication skills.
>         
>         
>         In the long view, it would be sweet if the Clojure reader knew
>         how
>         to read a literate program. Just call "(literate-load file
>         chunk)"
>         and you get the same effect as if you had tangled the program
>         to
>         a file.
>         
>         With literate-load available you would be able to write all of
>         your Clojure code in a literate style, making Clojure much
>         easier to understand, maintain, and modify.
> 
> 
> I'd be interested in studies proving that programs written in a
> litterate style are easier to maintain.
> 
> 
> So far, there has been this metaphore between a "story" and a
> "program". How far can this metaphor be pushed ?
> 
> 
> Is it easy to write a book with more than a couple people ? To
> maintain it ? To modify it ?
> 
> 
> I can easily understand the appeal: if I were to discover a program
> for the first time, I would certainly be interested in discovering it
> via a literate style, because I would have some guarantee that some
> effort has been pushed into providing for the mainteners: contexts,
> argumentations, debates concerning design choices, etc.
> 
> 
> But past this first "introduction" to the program, I don't know what
> it would cost to maintain it without adding to the entropy of its
> literate part.
> 
> 
> I mean: to be honest, it's not as if, already, all programs written
> were correctly documented and we were facing a wall: "we can not
> improve our documentation further, we need to find another way to
> document our programs" ;-).
> 
> 
> Sorry to have to play the role of the devil's advocate, but I think
> there are currently holes in the argumentation in favor of literate
> programming, at least wrt to the material I've been exposed to so
> far ...
> 

YOU signed a contract with the Devil too? Hmmm. I thought I had an
exclusive contract. Perhaps he lied to me. :-)

I have experience what most programmers never see. I got my own code
back after many years because I volunteered to open source the Axiom
code. I was one of the original authors. 

I write dirt simple lisp code. I know exactly what it does. However,
I don't know why I wrote it. I don't know how it fits into the whole.
I was clearly solving a problem but the problem definition is gone
even though the code is there. I know I need the code because the
system crashes if I delete it.

I'm left with the problem of reverse-engineering the code. All I
can do is invent probable reasons. Nobody wrote down the design
decisions. It is very difficult to maintain and modify 1 million
lines of lisp code.

If you want to see the difference a literate program would make I
suggest taking one of Rich's ideas, such as software transactional
memory, and try to explain the code that implements it. I have
tried that in my Clojure in Small Pieces book and it is a LOT
harder than it looks.

Literate programming is not for you. In fact, it is probably not
worthwhile for most programs. But if you're going to make a program
that "lives" beyond you then it really matters. You need to communicate
to people you will never talk to and who cannot ask you questions.
Some of the authors of Axiom are already dead. They don't seem to
be answering my emails.

As a lifelong lisper I've decided that Clojure is interesting to me.
I'm willing to devote a lot of time and attention to it. In particular,
I want it to outlive Rich Hickey's involvement in it. Rich will
eventually retire into management somewhere and the code will begin
to rot. I am hoping that a literate form of Clojure will make it
possible for new people to maintain, modify, and extend it.

To that end, I'd like a literate form of Clojure that passes the
"independence test". That is, I'd like a new person to be able to
take the literate Clojure Core off to an island for a couple weeks
of reading and come back as a well informed, productive developer
capable of contributing correctly without breaking existing ideas.

Thus, literate programming is an investment in the future.

However, as Knuth points out and as I've already experienced, writing
a program in literate form vastly reduces the errors. There are two
causes I can find. 

First, if I have to write an explanation then I have to justify my
poor code hacks. Sometimes I find that I rewrite the code because the
very act of explaining the bad code made me realize that the code is
bad. I find I have to talk about memory allocations so I catch leaks.
I have to talk about argument handling so I end up proving that the
arguments are correct, or I end up checking for possible failures.

Second, because other people can see the reasoning at the code review,
they can chastise me for failing to explain, or explaining things that
the code does not do, or just plain failing to implement a correct
solution. 

I have found that literate programming makes me a better programmer.

Convincing people to use literate programming is like convincing
them to use lisp. Before the AH-HA moment occurs they can't imagine
why anyone would code this way. After the AH-HA moment they can't
imagine why anyone would code any other way. I have clearly crossed
that line.

Tim Daly





From MAILER-DAEMON Sat Nov 19 14:52:25 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRqxd-00029w-An
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 14:52:25 -0500
Received: from eggs.gnu.org ([140.186.70.92]:33735)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <raymond.rogers72@gmail.com>) id 1RRqxb-00029o-Qx
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:52:24 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <raymond.rogers72@gmail.com>) id 1RRqxa-00060D-W3
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:52:23 -0500
Received: from mail-iy0-f173.google.com ([209.85.210.173]:60801)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <raymond.rogers72@gmail.com>) id 1RRqxa-000601-Qs
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 14:52:22 -0500
Received: by iakk32 with SMTP id k32so5882664iak.4
	for <axiom-developer@nongnu.org>; Sat, 19 Nov 2011 11:52:21 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=message-id:date:from:user-agent:mime-version:to:cc:subject
	:references:in-reply-to:x-enigmail-version:content-type
	:content-transfer-encoding;
	bh=t+E1jX7itBgQNt8jo1h1dpuYWnXAV/nhKN6uN5jsKW8=;
	b=rQsDYLjZqIyTP2RaW/OwbE4CjcqQjLHvXuBAJBRbj2rni7fTeWhbbw03zAMt1UYGwW
	8Q0aqclYblIRl5YJp5o8iHIi/8m9ZX2faGx01OmaxKzJAfJMYtBtEZCbAwE8iH6gw/fx
	o53+N6nmS6II+YATGM8EB9S5eVJotBUkBcWBM=
Received: by 10.42.151.4 with SMTP id c4mr5906814icw.39.1321732341860;
	Sat, 19 Nov 2011 11:52:21 -0800 (PST)
Received: from [192.168.1.69] ([201.138.95.135])
	by mx.google.com with ESMTPS id z10sm20926560ibv.9.2011.11.19.11.52.18
	(version=SSLv3 cipher=OTHER); Sat, 19 Nov 2011 11:52:21 -0800 (PST)
Message-ID: <4EC80903.9070806@gmail.com>
Date: Sat, 19 Nov 2011 13:52:35 -0600
From: Raymond Rogers <raymond.rogers72@gmail.com>
User-Agent: Mozilla/5.0 (X11; Linux i686 on x86_64;
	rv:8.0) Gecko/20111105 Thunderbird/8.0
MIME-Version: 1.0
To: daly <daly@axiom-developer.org>
References: <1321618628.1926.75.camel@pewter>
	<33378874.2870.1321675364798.JavaMail.geo-discussion-forums@yqoo7>
	<b75acd9e-855a-491b-b9fb-ae7ce813438a@q11g2000vbq.googlegroups.com>
	<CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
	<1321731468.1926.267.camel@pewter>
In-Reply-To: <1321731468.1926.267.camel@pewter>
X-Enigmail-Version: 1.3.3
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 209.85.210.173
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming example
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 19:52:24 -0000

It's been a long time but I believe I read
Anatomy of Lisp
John Allen

As I recall it would be an example of "literate programing" in the sense
that every piece of code had extensive explanation before and after; and
could actually lift the code and implement it.
I found it a revelation; he actually built a lisp interpreter and a
memory management DB system right in front of my eyes; and I understood
it.  I had always thought that starting at that level and generating
what he did wouldn't be possible without inventing a new language for
the DB handling.  I thought DB handling was totally inappropriate for Lisp.
Of course he did start from a (small) kernel.
Sad to say it's out of print but Amazon has it available; for a
exorbitant price IMHO.

Ray



From MAILER-DAEMON Sat Nov 19 15:07:10 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRrBu-0004SU-7t
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 15:07:10 -0500
Received: from eggs.gnu.org ([140.186.70.92]:52709)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRrBs-0004SN-Ln
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 15:07:09 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRrBr-0000W4-TP
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 15:07:08 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:50260
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RRrBr-0000W0-LZ
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 15:07:07 -0500
Received: from [192.168.1.6] (dynamic-acs-72-23-235-203.zoominternet.net
	[72.23.235.203])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pAJK7475011262;
	Sat, 19 Nov 2011 14:07:04 -0600
From: daly <daly@axiom-developer.org>
To: Raymond Rogers <raymond.rogers72@gmail.com>
In-Reply-To: <4EC80903.9070806@gmail.com>
References: <1321618628.1926.75.camel@pewter>
	<33378874.2870.1321675364798.JavaMail.geo-discussion-forums@yqoo7>
	<b75acd9e-855a-491b-b9fb-ae7ce813438a@q11g2000vbq.googlegroups.com>
	<CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
	<1321731468.1926.267.camel@pewter>  <4EC80903.9070806@gmail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 19 Nov 2011 15:07:02 -0500
Message-ID: <1321733222.1926.273.camel@pewter>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.1 
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming example
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 20:07:09 -0000

I loved that book. I taught from it at Vassar.
It is well worth the price.

On Sat, 2011-11-19 at 13:52 -0600, Raymond Rogers wrote:
> It's been a long time but I believe I read
> Anatomy of Lisp
> John Allen
> 
> As I recall it would be an example of "literate programing" in the sense
> that every piece of code had extensive explanation before and after; and
> could actually lift the code and implement it.
> I found it a revelation; he actually built a lisp interpreter and a
> memory management DB system right in front of my eyes; and I understood
> it.  I had always thought that starting at that level and generating
> what he did wouldn't be possible without inventing a new language for
> the DB handling.  I thought DB handling was totally inappropriate for Lisp.
> Of course he did start from a (small) kernel.
> Sad to say it's out of print but Amazon has it available; for a
> exorbitant price IMHO.
> 
> Ray




From MAILER-DAEMON Sat Nov 19 16:21:58 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RRsMI-000569-0D
	for mharc-axiom-developer@gnu.org; Sat, 19 Nov 2011 16:21:58 -0500
Received: from eggs.gnu.org ([140.186.70.92]:55912)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <danieljomphe@gmail.com>) id 1RRsME-00055Z-3F
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 16:21:56 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <danieljomphe@gmail.com>) id 1RRsMB-0004gw-SF
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 16:21:53 -0500
Received: from mail-qy0-f185.google.com ([209.85.216.185]:64606)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <danieljomphe@gmail.com>) id 1RRsMB-0004gV-NB
	for axiom-developer@nongnu.org; Sat, 19 Nov 2011 16:21:51 -0500
Received: by qyk34 with SMTP id 34so8974831qyk.22
	for <axiom-developer@nongnu.org>; Sat, 19 Nov 2011 13:21:50 -0800 (PST)
Received: by 10.224.187.10 with SMTP id cu10mr1018493qab.13.1321737710472;
	Sat, 19 Nov 2011 13:21:50 -0800 (PST)
X-Google-Doc-Id: 92e2e15b1d9ebc13
X-Google-Web-Client: true
Date: Sat, 19 Nov 2011 13:21:50 -0800 (PST)
From: Daniel Jomphe <danieljomphe@gmail.com>
To: clojure@googlegroups.com
Message-ID: <8875452.1277.1321737710092.JavaMail.geo-discussion-forums@vbza28>
In-Reply-To: <1321731468.1926.267.camel@pewter>
References: <1321618628.1926.75.camel@pewter>
	<33378874.2870.1321675364798.JavaMail.geo-discussion-forums@yqoo7>
	<b75acd9e-855a-491b-b9fb-ae7ce813438a@q11g2000vbq.googlegroups.com>
	<CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
	<1321731468.1926.267.camel@pewter>
MIME-Version: 1.0
Content-Type: multipart/mixed; 
	boundary="----=_Part_1275_27311476.1321737710091"
X-Google-Token: EO67oPYE_F4RfUlNrqM0
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 209.85.216.185
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming example
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: clojure@googlegroups.com
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sat, 19 Nov 2011 21:21:56 -0000

------=_Part_1275_27311476.1321737710091
Content-Type: multipart/alternative; 
	boundary="----=_Part_1276_32914097.1321737710091"

------=_Part_1276_32914097.1321737710091
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

On Saturday, November 19, 2011 2:37:48 PM UTC-5, TimDaly wrote:
>
> However, as Knuth points out and as I've already experienced, writing
> a program in literate form vastly reduces the errors. There are two
> causes I can find. 
>
> First, if I have to write an explanation then I have to justify my
> poor code hacks. Sometimes I find that I rewrite the code because the
> very act of explaining the bad code made me realize that the code is
> bad. I find I have to talk about memory allocations so I catch leaks.
> I have to talk about argument handling so I end up proving that the
> arguments are correct, or I end up checking for possible failures.
>
> Second, because other people can see the reasoning at the code review,
> they can chastise me for failing to explain, or explaining things that
> the code does not do, or just plain failing to implement a correct
> solution.
>
With the tools available to us today, there's no reason why we at least 
shouldn't have everything needed to make literate programming more 
seamless, more natural. For example, while reading your toy example, I 
found myself wanting to ask a question or comment on your thoughts a few 
times. If your book had been displayed on a dynamic website geared towards 
literate programming, I might have been able to click on a paragraph and 
write my question/comment right there. And then, after a short conversation 
there, you would have integrated the fruits of our conversation directly 
into the end result. Thus each new reader would have been an occasion to 
improve the book. ...It's nothing surprising since this kind of review 
system already exists in some publishers' toolkits.

Another thing that appeals to me regarding Tangle, is the fact that it may 
be used to keep things DRY. For example, when we have many arity-overloaded 
implementations of a function, some of their arguments are repeated, and we 
need to duplicate their api docs. Tangle could be leveraged to get rid of 
this duplication.

------=_Part_1276_32914097.1321737710091
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On Saturday, November 19, 2011 2:37:48 PM UTC-5, TimDaly wrote:<blockquote =
class=3D"gmail_quote" style=3D"margin: 0;margin-left: 0.8ex;border-left: 1p=
x #ccc solid;padding-left: 1ex;"><p>However, as Knuth points out and as I'v=
e already experienced, writing<br>a program in literate form vastly reduces=
 the errors. There are two<br>causes I can find. </p><p>First, if I have to=
 write an explanation then I have to justify my<br>poor code hacks. Sometim=
es I find that I rewrite the code because the<br>very act of explaining the=
 bad code made me realize that the code is<br>bad. I find I have to talk ab=
out memory allocations so I catch leaks.<br>I have to talk about argument h=
andling so I end up proving that the<br>arguments are correct, or I end up =
checking for possible failures.</p><p>Second, because other people can see =
the reasoning at the code review,<br>they can chastise me for failing to ex=
plain, or explaining things that<br>the code does not do, or just plain fai=
ling to implement a correct<br>solution.</p></blockquote><div>With the tool=
s available to us today, there's no reason why we at least shouldn't have e=
verything needed to make literate programming more seamless, more natural. =
For example, while reading your toy example, I found myself wanting to ask =
a question or comment on your thoughts a few times. If your book had been d=
isplayed on a dynamic website geared towards literate programming, I might =
have been able to click on a paragraph and write my question/comment right =
there. And then, after a short conversation there, you would have integrate=
d the fruits of our conversation directly into the end result. Thus each ne=
w reader would have been an occasion to improve the book. ...It's nothing s=
urprising since this kind of review system already exists in some publisher=
s' toolkits.</div><div><br></div><div>Another thing that appeals to me rega=
rding Tangle, is the fact that it may be used to keep things DRY. For examp=
le, when we have many arity-overloaded implementations of a function, some =
of their arguments are repeated, and we need to duplicate their api docs. T=
angle could be leveraged to get rid of this duplication.</div>
------=_Part_1276_32914097.1321737710091--

------=_Part_1275_27311476.1321737710091--


From MAILER-DAEMON Sun Nov 20 17:20:14 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RSFkE-0000GK-2x
	for mharc-axiom-developer@gnu.org; Sun, 20 Nov 2011 17:20:14 -0500
Received: from eggs.gnu.org ([140.186.70.92]:59419)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <danieljomphe@gmail.com>) id 1RSFkB-0000Ft-EA
	for axiom-developer@nongnu.org; Sun, 20 Nov 2011 17:20:12 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <danieljomphe@gmail.com>) id 1RSFkA-0005eo-9d
	for axiom-developer@nongnu.org; Sun, 20 Nov 2011 17:20:11 -0500
Received: from mail-qy0-f185.google.com ([209.85.216.185]:65296)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <danieljomphe@gmail.com>) id 1RSFkA-0005eS-3P
	for axiom-developer@nongnu.org; Sun, 20 Nov 2011 17:20:10 -0500
Received: by qyk34 with SMTP id 34so10115866qyk.22
	for <axiom-developer@nongnu.org>; Sun, 20 Nov 2011 14:20:09 -0800 (PST)
Received: by 10.224.197.196 with SMTP id el4mr1342551qab.8.1321827609136;
	Sun, 20 Nov 2011 14:20:09 -0800 (PST)
X-Google-Doc-Id: aa10dcb03d0b512e
X-Google-Web-Client: true
Date: Sun, 20 Nov 2011 14:20:08 -0800 (PST)
From: Daniel Jomphe <danieljomphe@gmail.com>
To: clojure@googlegroups.com
Message-ID: <10127240.1593.1321827608732.JavaMail.geo-discussion-forums@vbza28>
In-Reply-To: <CAG=8xfPWRwDnWrhGr8iHQdo8wRQRaHahuN3VFNAkKwspE0pT4g@mail.gmail.com>
References: <1321618628.1926.75.camel@pewter>
	<33378874.2870.1321675364798.JavaMail.geo-discussion-forums@yqoo7>
	<b75acd9e-855a-491b-b9fb-ae7ce813438a@q11g2000vbq.googlegroups.com>
	<CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
	<1321731468.1926.267.camel@pewter>
	<8875452.1277.1321737710092.JavaMail.geo-discussion-forums@vbza28>
	<CAG=8xfPWRwDnWrhGr8iHQdo8wRQRaHahuN3VFNAkKwspE0pT4g@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; 
	boundary="----=_Part_1591_23215137.1321827608731"
X-Google-Token: EJj6pfYE4y3TbZuAwig0
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 209.85.216.185
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming example
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
Reply-To: clojure@googlegroups.com
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sun, 20 Nov 2011 22:20:12 -0000

------=_Part_1591_23215137.1321827608731
Content-Type: multipart/alternative; 
	boundary="----=_Part_1592_5882161.1321827608731"

------=_Part_1592_5882161.1321827608731
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

On Sunday, November 20, 2011 6:17:13 AM UTC-5, robermann79 wrote:
>
> FYI: some time ago the Opensuse project used such a collaborative tool
> (http://www.co-ment.com) in order to get a shared mindset of its
> goals.
> This was the result, see how clicking on higlight words points to
> their comments:
> https://lite.co-ment.com/text/lNPCgzeGHdV/view/


Interesting. And funny, considering I bought the cochapter.com domain to do 
something similar. I'm yet to deliver the application that's planned to 
power that domain.

------=_Part_1592_5882161.1321827608731
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit

On Sunday, November 20, 2011 6:17:13 AM UTC-5, robermann79 wrote:<blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">FYI: some time ago the Opensuse project used such a collaborative tool<br>(<a href="http://www.co-ment.com" target="_blank">http://www.co-ment.com</a>) in order to get a shared mindset of its<br>goals.<br>This was the result, see how clicking on higlight words points to<br>their comments:<br><a href="https://lite.co-ment.com/text/lNPCgzeGHdV/view/" target="_blank">https://lite.co-ment.com/text/<wbr>lNPCgzeGHdV/view/</a></blockquote><div><br></div><div>Interesting. And funny, considering I bought the cochapter.com domain to do something similar. I'm yet to deliver the application that's planned to power that domain.</div>
------=_Part_1592_5882161.1321827608731--

------=_Part_1591_23215137.1321827608731--


From MAILER-DAEMON Mon Nov 21 08:52:02 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RSUHy-0000dj-Mk
	for mharc-axiom-developer@gnu.org; Mon, 21 Nov 2011 08:52:02 -0500
Received: from eggs.gnu.org ([140.186.70.92]:54804)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <robermann@gmail.com>) id 1RS5Oe-0004o8-Jj
	for axiom-developer@nongnu.org; Sun, 20 Nov 2011 06:17:17 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <robermann@gmail.com>) id 1RS5Oc-00073y-Vk
	for axiom-developer@nongnu.org; Sun, 20 Nov 2011 06:17:16 -0500
Received: from mail-vx0-f173.google.com ([209.85.220.173]:52645)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <robermann@gmail.com>) id 1RS5Oc-00073m-RL
	for axiom-developer@nongnu.org; Sun, 20 Nov 2011 06:17:14 -0500
Received: by vcbfl11 with SMTP id fl11so271167vcb.4
	for <axiom-developer@nongnu.org>; Sun, 20 Nov 2011 03:17:14 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=mime-version:in-reply-to:references:date:message-id:subject:from:to
	:cc:content-type;
	bh=+fZAa/M8bZ8gnkdaavaOOyfY9BYCMcRM5oRsxezPrWI=;
	b=B2AxzhUJ/Hf8mncITd9x8Z4iYaBc87ubQfa6eOLyv31ZafV2S3wXY6dM1PtnV3Dka9
	fA/8tccRJ8sAL81HKhpvolsYEzIR2goSB1VQtJm59Pol0y5qdMnbdur6iiIlWskKDgg3
	u4hXhw1lsI5Dl5yVf5pTDSk7Lvj+fHTRMi7xw=
MIME-Version: 1.0
Received: by 10.52.100.106 with SMTP id ex10mr10380431vdb.28.1321787833995;
	Sun, 20 Nov 2011 03:17:13 -0800 (PST)
Received: by 10.52.37.200 with HTTP; Sun, 20 Nov 2011 03:17:13 -0800 (PST)
In-Reply-To: <8875452.1277.1321737710092.JavaMail.geo-discussion-forums@vbza28>
References: <1321618628.1926.75.camel@pewter>
	<33378874.2870.1321675364798.JavaMail.geo-discussion-forums@yqoo7>
	<b75acd9e-855a-491b-b9fb-ae7ce813438a@q11g2000vbq.googlegroups.com>
	<CAKVVxfp5T+PqaQZGrmDPUjLuh3iQQ7CyJHLeCOhXktjPX_t5Uw@mail.gmail.com>
	<1321731468.1926.267.camel@pewter>
	<8875452.1277.1321737710092.JavaMail.geo-discussion-forums@vbza28>
Date: Sun, 20 Nov 2011 12:17:13 +0100
Message-ID: <CAG=8xfPWRwDnWrhGr8iHQdo8wRQRaHahuN3VFNAkKwspE0pT4g@mail.gmail.com>
From: Roberto Mannai <robermann@gmail.com>
To: clojure@googlegroups.com
Content-Type: text/plain; charset=ISO-8859-1
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 209.85.220.173
X-Mailman-Approved-At: Mon, 21 Nov 2011 08:52:00 -0500
Cc: axiom-developer@nongnu.org
Subject: Re: [Axiom-developer] Literate Programming example
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Sun, 20 Nov 2011 11:17:17 -0000

FYI: some time ago the Opensuse project used such a collaborative tool
(http://www.co-ment.com) in order to get a shared mindset of its
goals.
This was the result, see how clicking on higlight words points to
their comments:
https://lite.co-ment.com/text/lNPCgzeGHdV/view/

On Sat, Nov 19, 2011 at 10:21 PM, Daniel Jomphe <danieljomphe@gmail.com> wrote:
> With the tools available to us today, there's no reason why we at least
> shouldn't have everything needed to make literate programming more seamless,
> more natural. For example, while reading your toy example, I found myself
> wanting to ask a question or comment on your thoughts a few times. If your
> book had been displayed on a dynamic website geared towards literate
> programming, I might have been able to click on a paragraph and write my
> question/comment right there. And then, after a short conversation there,
> you would have integrated the fruits of our conversation directly into the
> end result. Thus each new reader would have been an occasion to improve the
> book. ...It's nothing surprising since this kind of review system already
> exists in some publishers' toolkits.


From MAILER-DAEMON Wed Nov 30 23:52:59 2011
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1RVydn-0007vr-0y
	for mharc-axiom-developer@gnu.org; Wed, 30 Nov 2011 23:52:59 -0500
Received: from eggs.gnu.org ([140.186.70.92]:42575)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RVydj-0007sZ-IQ
	for axiom-developer@nongnu.org; Wed, 30 Nov 2011 23:52:56 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RVydi-0007EY-4q
	for axiom-developer@nongnu.org; Wed, 30 Nov 2011 23:52:55 -0500
Received: from vs338.rosehosting.com ([209.135.140.38]:38573
	helo=axiom-developer.org) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <daly@axiom-developer.org>) id 1RVydh-0007EI-Sy
	for axiom-developer@nongnu.org; Wed, 30 Nov 2011 23:52:54 -0500
Received: from axiom-developer.org (lincoln.rosehosting.com [127.0.0.1])
	by axiom-developer.org (8.12.8/8.12.8) with ESMTP id pB14qp75017258;
	Wed, 30 Nov 2011 22:52:51 -0600
From: daly@axiom-developer.org
Received: (from daly@localhost)
	by axiom-developer.org (8.12.8/8.12.8/Submit) id pB14qpG4017255;
	Wed, 30 Nov 2011 22:52:51 -0600
Date: Wed, 30 Nov 2011 22:52:51 -0600
Message-Id: <201112010452.pB14qpG4017255@axiom-developer.org>
To: axiom-developer@nongnu.org
X-detected-operating-system: by eggs.gnu.org: Linux 2.6? (barebone, rare!)
X-Received-From: 209.135.140.38
Subject: [Axiom-developer] Axiom release for November 2011
X-BeenThere: axiom-developer@nongnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Axiom Developers <axiom-developer.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/axiom-developer>, 
	<mailto:axiom-developer-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/axiom-developer>
List-Post: <mailto:axiom-developer@nongnu.org>
List-Help: <mailto:axiom-developer-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/axiom-developer>,
	<mailto:axiom-developer-request@nongnu.org?subject=subscribe>
X-List-Received-Date: Thu, 01 Dec 2011 04:52:56 -0000

November 2011 Release

Treeshaking the interpreter and compiler continues and a few more files
were merged and removed.

Several books and Makefiles were converted to use lisp tangle rather 
than noweb. This is part of the general process to remove noweb.

Global function rewrites continue, including removing GETREFV and makeprop.

Work was done to improve OpenMath support. The OpenMath semantics CDs were
added and the OpenMath parser was enhanced.

More effort was put into literate work. In particular, an example of a
literate program using HTML was created and presented at the Clojure/Conj
conference. (See http://axiom-developer.org/axiom-website/litprog.html )

books/Makefile
   removed noweb, move to lisp tangle
   fix missing index files on PDfs

books/tangle.lisp 
   fix .input file algebra extraction

books/bookvol10.2
   missing/unused function cleanup
   remove makeprop
   remove noweb, move to lisp tangle

books/bookvol10.3 
   remove GETREFV
   remove makeprop
   remove noweb, move to lisp tangle

books/bookvol10.4 
   remove noweb, move to lisp tangle

books/bookvol10.5 
   remove noweb, move to lisp tangle

books/bookvol4
   missing/unused function cleanup
   remove makeprop

books/bookvol5 
   OpenMath support
   add OpenMath stubs
   missing/unused function cleanup
   remove makeprop
   remove noweb, move to lisp tangle
   treeshake interpreter

books/bookvol7.1 
   fix documentation
   update What's New Page

books/bookvol9
   missing/unused function cleanup
   remove makeprop
   treeshake and merge c-doc.lisp

books/bookvolbib
   Axiom OpenMath references
   add additional references
   add references

books/ps/
   v71releasenotes.eps add release notes
   v71sept2011.eps added

src/algebra/Makefile 
   fix .input file algebra extraction
   remove noweb, move to lisp tangle

src/axiom-website/documentation.html
   add Alexander quote
   add Knuth quote
   add litprog.html
   add quote

src/axiom-website/download.html
   update to latest release

src/axiom-website/litprog.html
   added
   add quote
   literate program example update

src/interp/Makefile 
   remove apply.lisp
   remove c-doc.lisp
   remove noweb, move to lisp tangle
   remove nruntime.lisp

src/interp
   apply.lisp removed, merged with bookvol9
   buildom.lisp remove GETREFV
   c-doc.lisp removed
   c-util.lisp missing/unused function cleanup
   category.lisp remove GETREFV
   functor.lisp missing/unused function cleanup, remove GETREFV
   g-util.lisp missing/unused function cleanup
   i-eval.lisp remove nruntime.lisp
   i-spec1.lisp treeshake interpreter
   i-spec2.lisp fix AN has sqrt: % -> %
   i-spec2.lisp remove makeprop
   nruncomp.lisp remove GETREFV, treeshake compiler
   nrungo.lisp remove nruntime.lisp, treeshake interpreter, remove GETREFV
   nruntime.lisp removed
   parsing.lisp remove makeprop
   sys-pkg.lisp missing/unused function cleanup, remove GETREFV, makeprop
   template.lisp remove GETREFV
   vmlisp.lisp missing/unused function cleanup, remove GETREFV, makeprop

zips
   add cds.tar.gz OpenMath support. add OpenMath CDs


