\start
Date: Fri,  9 May 2014 13:16:19 -0400 (EDT)
From: Tim Daly
To: ist
Subject: [Axiom-developer] Must hear...

With respect to "documentation" of open source software...

"You keep using that word. I don't think it means what you think it
means." -- "The Princess Bride"

The notion that "reading the code" is the ultimate truth for
"documentation" is based on a misunderstanding at so many levels it is
hard to explain. In fact, most of the ideas don't begin to cover
"documenting the system". Fortunately, Robert Lefkowitz absolutely
illuminates the scope of the problem in these delightful talks.

For those who have not heard it, this is truly a treat.
For those who "document" this is a must-hear.

Robert Lefkowitz -- The Semasiology of Open Source
http://web.archive.org/web/20130729214526id_/http://itc.conversationsnetwork.org/shows/detail169.html
http://web.archive.org/web/20130729210039id_/http://itc.conversationsnetwork.org/shows/detail662.html

\start
Date: Fri, 9 May 2014 12:43:52 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] Must hear...

There is a 3rd part to this series. Enjoy...

Robert Lefkowitz -- The Semasiology of Open Source (part 3)

http://daviding.wordpress.com/2007/10/22/robert-lefkowitz-the-semasiology-of-open-source-part-iii-oscon-2007-it-conversations-20060726/

\start
Date: Fri, 9 May 2014 15:38:27 -0500
From: Tim Daly
To: Bill Naylor
Subject: [Axiom-developer] Polynomial GCD code

Do you have a copy of your thesis code in Axiom?
If so, can I have a copy to try to incorporate into Axiom?

\start
Date: Sun, 11 May 2014 09:56:50 +0100
From: Martin Baker
To: list
Subject: Re: [Axiom-developer] Must hear...

On 09/05/14 18:16, Tim Daly wrote:
> With respect to "documentation" of open source software...
>
> "You keep using that word. I don't think it means what you think it
> means." -- "The Princess Bride"
>
> The notion that "reading the code" is the ultimate truth for
> "documentation" is based on a misunderstanding at so many levels it is
> hard to explain. In fact, most of the ideas don't begin to cover
> "documenting the system". Fortunately, Robert Lefkowitz absolutely
> illuminates the scope of the problem in these delightful talks.
>
> For those who have not heard it, this is truly a treat.
> For those who "document" this is a must-hear.
>
> Robert Lefkowitz -- The Semasiology of Open Source
> http://web.archive.org/web/20130729214526id_/http://itc.conversationsnetwork.org/shows/detail169.html
> http://web.archive.org/web/20130729210039id_/http://itc.conversationsnetwork.org/shows/detail662.html

So what should one do if one wants to modify parts of Axiom (or its 
forks) where all there is is the code?

Should one:
1) Trace through the code and try to reverse engineer the documentation, 
then modify that.
2) Try to understand generally what it does (such as working out what 
the inputs and outputs are). Then rewrite it from scratch in a 
documentation led way.

For me, in a lot of cases, I would prefer option 2. I would not claim to 
be as smart as the original authors, any algorithm that I would come up 
with might be less efficient and inferior in many respects. However I 
would try to document it as well as I could and try to make it a better 
basis for future improvement. Also, if I am going to make mistakes, at 
least I would learn more from my own mistakes.

\start
Date: Sun, 11 May 2014 15:35:47 -0400
From: Tim Daly
To: Martin Baker
Subject: Re: [Axiom-developer] Must hear...

> So what should one do if one wants to modify parts of Axiom (or its 
> forks) where all there is is the code?
> 
> Should one:
> 1) Trace through the code and try to reverse engineer the documentation, 
> then modify that.
> 2) Try to understand generally what it does (such as working out what 
> the inputs and outputs are). Then rewrite it from scratch in a 
> documentation led way.
> 
> For me, in a lot of cases, I would prefer option 2. I would not claim to 
> be as smart as the original authors, any algorithm that I would come up 
> with might be less efficient and inferior in many respects. However I 
> would try to document it as well as I could and try to make it a better 
> basis for future improvement. Also, if I am going to make mistakes, at 
> least I would learn more from my own mistakes.

For existing code there are many ways to approach the problem and I
can't recommend any general approach. The main goal to keep in mind is
to speak to a broad audience who might need to do something with the
code. For instance, with the sequence prediction code, what is the idea?
What papers should be read? What subset of the problem is covered? Are
there boundary cases?  Are there examples to try? How is the code
structured? Does it depend on a limit package? Does it work over floats?

The approach I'm taking is to start from the code, find the related
theory, then understand and document from the theory to the code.
At that point I feel I know enough to critically examine the code.

Any algebra author sufficiently clever and educated to write an algebra
package (e.g. JET), is bringing a LOT of background to the code. Writing
reasonable documentation without their help is a formidable challenge.
However if Axiom is going to survive and surpass the current state of
the art it is necessary to try.

If the information is available it can easily be restructured into the
books, hyperdoc, help files, ++ comments, test files, and examples.

The new )describe command currently shows working examples. That can be
enough for someone to start using the domains. The new )help command
will (eventually) pop into a browser worksheet with a series of
worked-out problems, explanations, and a live connection to the
interpreter so experiements can be done.

New algebra authors really do need to spend the time and effort to
bring the quality of their documentation up to the quality of their
code. Writing down the ideas while writing the code is not particularly
challenging and, in fact, is very likely to improve the quality of the
code, based on feedback from those who tried.

As Roboert Persig said in "Zen and the Art of Motorcycle Maintenance", 
it's all about quality. As Knuth said, it's all about communication.
Stealing from both, I say it is all about quality communication.

\start
Date: Sun, 11 May 2014 15:39:26 -0400
From: Tim Daly
To: list
Subject: [Axiom-developer] [m.kohlhase@jacobs-university.de: First Call for Papers: 26. OpenMath Workshop (at CICM 2014; July 7.  July 2014)]

Date: Sun, 11 May 2014 16:31:32 +0200
From: Michael Kohlhase
To: list
Subject: First Call for Papers: 26. OpenMath Workshop (at CICM 2014; July=
 7.  July 2014)=20
CC: Michael Kohlhase

26th OpenMath Workshop
Coimbra, Portugal
July 7. 2014
co-located with CICM 2014
Submission deadline 7 June

http://www.cicm-conference.org/2014/openmath/

OBJECTIVES

OpenMath (http://www.openmath.org) is a language for exchanging
mathematical formulae across applications (such as computer algebra
systems).  From 2010 its importance has increased in that OpenMath
Content Dictionaries were adopted as a foundation of the MathML 3 W3C
recommendation (http://www.w3.org/TR/MathML), the standard for
mathematical formulae on the Web.

Topics we expect to see at the workshop include

   * Feature Requests (Standard Enhancement Proposals) and Discussions
     for going beyond OpenMath 2;
   * Further convergence of OpenMath and MathML 3;
   * Reasoning with OpenMath;
   * Software using or processing OpenMath;
   * OpenMath on the Semantic Web;
   * New OpenMath Content Dictionaries;

Contributions can be either full research papers, Standard Enhancement
Proposals, or a description of new Content Dictionaries, particularly
ones that are suggested for formal adoption by the OpenMath Society.

IMPORTANT DATES (all times are "anywhere on earth")

   * 7. June 2014: Submission
   * 20. June 2014: Notification of acceptance or rejection
   * 5. July 2014: Final revised papers due
   * 7. July 2014: Workshop (Coimbra time)

SUBMISSIONS

Submission is via EasyChair (http://www.easychair.org/conferences?conf==
om20131). =20
Final papers must conform to the EasyChair LaTeX style.  Initial submissi=
ons in this=20
format  are welcome but not mandatory  but they should be in PDF and with=
in the=20
given limit of pages/words.

Submission categories:

   * Full paper: 5-10 EasyChair pages
   * Short paper: 1-4 EasyChair pages
   * CD description: 1-6 EasyChair pages; a .zip or .tgz file of the
     CDs must be attached, or a link to the CD provided.
   * Standard Enhancement Proposal: 1-10 EasyChair pages (as
     appropriate w.r.t. the background knowledge required); a .zip or
     .tgz file of any related implementation (e.g. a Relax NG schema)
     should be attached.

If not in EasyChair format, 500 words count as one page.

PROCEEDINGS

Electronic proceedings will be published with CEUR-WS.org.

ORGANISATION COMMITTEE

   * James Davenport (University of Bath, UK)
   * Michael Kohlhase (Jacobs University Bremen, Germany)

PROGRAMME COMMITTEE

   * James Davenport (University of Bath, UK)
   * Michael Kohlhase (Jacobs University Bremen, Germany)
   * Christoph Lange (Rheinische Friedrich-Wilhelms-Universit=C3=A4t Bonn=
, Germany)=20
   * Lars Hellstr=C3=B6m (Ume=C3=A5 Universitet, Sweden)
   * Jan Willem Knopper (Technische Universiteit Eindhoven, Netherlands)
   * Paul Libbrecht (PH Weingarten)
   * Chris Rowley (LaTeX3 Project and Open Math Society)

Comments/questions/enquiries: to be sent to the organizers

\start
Date: Sun, 11 May 2014 16:33:17 -0400 (EDT)
From: Tim Daly
To: Martin Baker
Subject: Re: [Axiom-developer] Must hear...

> So what should one do if one wants to modify parts of Axiom (or its 
> forks) where all there is is the code?
> 
> Should one:
> 1) Trace through the code and try to reverse engineer the documentation, 
> then modify that.
> 2) Try to understand generally what it does (such as working out what 
> the inputs and outputs are). Then rewrite it from scratch in a 
> documentation led way.
> 
> For me, in a lot of cases, I would prefer option 2. I would not claim to 
> be as smart as the original authors, any algorithm that I would come up 
> with might be less efficient and inferior in many respects. 

Martin,

Given my mono-maniacal focus on documentation I think I may have
mis-read what you wrote. Let me try another interpretation.

Are you asking "How do I modify existing code?". For new algebra that
I've written I've tried to provide documentation. But for existing
algebra I've been VERY relucant to change things, even where there
seems to be a better way. Fixing mistakes and extending the code
seem reasonable but changing the existing API?

One key reason is "backward compatibility". The book and the test
cases document the language and algebra. Old code should continue to
work, otherwise we get into the "python 2.7 vs 3.3 debates". If the
old code doesn't work the system is, by definition, broken.

Old code always has warts. Common Lisp has CAR which could easily
have been subsumed and removed by extending the definition of FIRST.
Pretty, but ... yeah, broken by definition.

Another key reason is that the author of the code was likely an expert
in the area. Even experts make mistakes that need to be fixed but
wholesale rewrites seem rather drastic. A rewrite assumes a higher
level of expertise. Some of the Axiom code was written as PhD thesis
work so the bar is pretty high.

That said, there may be valid reasons to modify or rewrite algebra.

> However I 
> would try to document it as well as I could and try to make it a better 
> basis for future improvement. Also, if I am going to make mistakes, at 
> least I would learn more from my own mistakes.

Unless there is some overarching reason it is hard to see the need to
rewrite existing code. A new design that regularizes many domains
might make a good reason. A complete extension of the whole area, such
as a major matrix package might make DHMATRIX a useless subset. But
changing the API of an existing domain so that old code doesn't work
is, by definition, broken.

Mistakes in the code will occur both in old code and in new code.
Unfortunately new mistakes are only likely to be uncovered by new
people using the new code... which by recursion on the motivation
to rewrite the code...  leads to yet a different set of mistakes. 

Code doesn't rust. It doesn't "get old". Especially computational
mathematics code. Tearing down the cathedral because we now know
how to make stones that lasts longer seems ... I don't know ...
disrespectful of the genius of the original architects?

\start
Date: Sun, 11 May 2014 16:47:57 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] ouch

The Low Quality of Scientific Code

http://techblog.bozho.net/?p=1423

\start
Date: Mon, 12 May 2014 08:21:54 +0100
From: Martin Baker
To: list
Subject: Re: [Axiom-developer] Must hear...

On 11/05/14 21:33, Tim Daly wrote:
> Unless there is some overarching reason it is hard to see the need to
> rewrite existing code. A new design that regularizes many domains
> might make a good reason. A complete extension of the whole area, such
> as a major matrix package might make DHMATRIX a useless subset. But
> changing the API of an existing domain so that old code doesn't work
> is, by definition, broken.
>
> Mistakes in the code will occur both in old code and in new code.
> Unfortunately new mistakes are only likely to be uncovered by new
> people using the new code... which by recursion on the motivation
> to rewrite the code...  leads to yet a different set of mistakes.
>
> Code doesn't rust. It doesn't "get old". Especially computational
> mathematics code. Tearing down the cathedral because we now know
> how to make stones that lasts longer seems ... I don't know ...
> disrespectful of the genius of the original architects?

One of the ideas I seem to be getting from the Robert Lefkowitz talks is 
that most of the life-cycle of a piece of software is in maintenance 
(i.e. change) and that is why this type of documentation is needed. It 
seemed to me that a corollary of that is that, if the code does not need 
to change, then documentation is not required.

The thought also occurred to me that the wider axiom community has two 
types of factions, those who want to change without documentation and 
those who want to document without change. I don't mean this to be taken 
seriously, its totally unfair of me to write down such an untrue 
thought. I apologise unreservedly to people who are working very hard to 
improve a program they believe in strongly.

I agree about the genius of the original architects who were years ahead 
of their time. I think more history should be made available to let more 
people know about this.

However I don't want to use, or work on, software that is a museum or 
shrine to the genius of the original architects. I have convinced myself 
that the sort of changes, that I would like, are driven by real needs to 
support new mathematical structures and so on and not just a wish to 
tweak the margins of the program for the sake of it.

see my wish list:
http://www.euclideanspace.com/prog/scratchpad/fricas/wishlist/

I think what you are hinting at is that the original scratchpad software 
was written by a large number of brilliant people and I am a single, 
humble individual who is very far from being a genius. I assure you, I 
know that already. I really should set myself more realistic goals.

It seems to me what Robert Lefkowitz is saying is that programs need to 
change over time, and for that they need documentation and of course the 
meaning of the word 'documentation' changes over time and everyone 
understands the meaning of words differently. Mathematical truth may not 
change over time, but the way that people use it, what is considered 
important, notation and just about everything else does change. Perhaps 
'documentation' does not mean what I think it means but, for me, its 
about not freezing the program in time.

\start
Date: Mon, 12 May 2014 05:10:39 -0500
From: Tim Daly
To: Martin Baker
Subject: Re: [Axiom-developer] Must hear....

>> Unless there is some overarching reason it is hard to see the need to
>> rewrite existing code. A new design that regularizes many domains
>> might make a good reason. A complete extension of the whole area, such
>> as a major matrix package might make DHMATRIX a useless subset. But
>> changing the API of an existing domain so that old code doesn't work
>> is, by definition, broken.
>>
>> Mistakes in the code will occur both in old code and in new code.
>> Unfortunately new mistakes are only likely to be uncovered by new
>> people using the new code... which by recursion on the motivation
>> to rewrite the code...  leads to yet a different set of mistakes.
>>
>> Code doesn't rust. It doesn't "get old". Especially computational
>> mathematics code. Tearing down the cathedral because we now know
>> how to make stones that lasts longer seems ... I don't know ...
>> disrespectful of the genius of the original architects?

Perhaps my cathedral analogy was "over the top". That's partly because
I worked with people like Barry Trager, Manuel Bronstein, et.al. The
day-to-day contact made me realize how little I actually understand.
Naturally I am very careful when changing things, trying to understand
what exists before making changes. Google wouldn't let me change
their search algorithm without understanding it and the mathematics
of Axiom is much more complicated.




>One of the ideas I seem to be getting from the Robert Lefkowitz talks is 
>that most of the life-cycle of a piece of software is in maintenance 
>(i.e. change) and that is why this type of documentation is needed. It 
>seemed to me that a corollary of that is that, if the code does not need 
>to change, then documentation is not required.

Axiom is clearly in need of maintenance in so many areas. At the very
minimum we have spent a good portion of the time dealing with low-level
issues like changing libraries, changing tools, and changing operating
systems. Fortunately we are nearing a key goal of a lisp-only platform
so Axiom will only need a working standards-based common lisp. The
build machinery is about to be swallowed and then the front end
hyperdoc work (already started) will be subsumed.

Climbing beyond that level is the effort to document the huge library
of computational mathematics. The code needs to change to handle 
the rest of the Risch algorithm, for instance. But what exists also
needs to be brought to a state where we know what is there, where it
is, and how to extend the missing parts. Manuel gave me permission to
use all of his writings to document the code... It just takes time.

If Axiom was a 100 line program this would be trivial. At 1.2 million
lines it is going to take a while.




>The thought also occurred to me that the wider axiom community has two 
>types of factions, those who want to change without documentation and 
>those who want to document without change. I don't mean this to be taken 
>seriously, its totally unfair of me to write down such an untrue 
>thought. I apologise unreservedly to people who are working very hard to 
>improve a program they believe in strongly.

Well, that's not a bad way to characterize it. I'm re-working the
Axiom emails and I see many cases of changes proposed without even a
single line of comment. I also see a lot of pushback about the wisdom
of LP. So there is certainly a camp of "change without documentation". 
There hasn't been a single, well documented pamphlet file submitted. 
We're also watching LP die in the forks, leading to the "raw code" 
approach.

On the other hand, "documentation without change" seems to
characterize my position on things, mildly unfairly I think, but not
without merit.  I have added algebra for predicting sequences, for
JET, for BLAS, for numeric functions, etc. The numeric code I wrote is
reasonably well documented. The JET code was done as well as I could
from available words. I'd also like to pick up Waldek's recent
integration work but I have no idea where to start, nor what references
to read to understand it, nor enough background to document it. So 
Axiom is changing, slowly.

I've asked several authors for permission to quote their papers, which
is an exception permitted by copyright for research purposes. All but
one have said yes. I have a whole directory of papers slated to be
added as documentation to the related domains. Each one is "expensive"
because I have to learn the relevant background to write readable
documentation and connect it to the domains but, hey, it's a 30 year
horizon project :-)




>I agree about the genius of the original architects who were years ahead 
>of their time. I think more history should be made available to let more 
>people know about this.

>However I don't want to use, or work on, software that is a museum or 
>shrine to the genius of the original architects. I have convinced myself 
>that the sort of changes, that I would like, are driven by real needs to 
>support new mathematical structures and so on and not just a wish to 
>tweak the margins of the program for the sake of it.

There seem to be two philosophical approaches to computational
mathematics. From one side there are the "programmers doing mathematics". 
They follow the usual path of "write the code, read the code". They 
are very liberal about the programs, moving from patch-to-patch, 
changing things. They are fast and liberal, moving at the pace of
programmers everywhere.

On the other side I see the "mathematicians doing programming". They
follow the usual "write the paper, bury the code". They are very 
conservative about the math, moving theorem-to-theorem, proving each
step along the way. Change is slow and conservative, moving at the
pace of mathematicians everywhere. 

As a "computational mathematician" I'm trying to occupy the middle
ground where code gets written and it is intimately connected with the
paper and proof. There is no need to invent new mathematics as there
are whole landscapes of existing work that can be reduced to
programs. The ideas should stay with the code so future Axiom
developers can maintain and modify the mathematics in a disciplined
way. Indeed, a stated long term Axiom goal is to integrate with either
ACL2 or COQ to prove the algorithms in Axiom.  I believe that properly
written literate programs are the best vehicle for all that.

I have published an invited editorial in the Notices of the American
Mathematical Society, pushing for LP and Reproducible Research so
Axiom isn't the only place you'll see me moaning about this. I am
working with John Kitchin from Carnegie Mellon on an effort to teach
the next generation of students to write literate programs. The
hope is that the next generation of students will naturally document
their programs. John works in computational chemistry, which would
make an interesting extension area of Axiom (if I only had time...)





>see my wish list:
>http://www.euclideanspace.com/prog/scratchpad/fricas/wishlist/

I have research in Indefinites, Interval Arithmetic, and Provisos that
I really, really want to implement. I have done work in all three
areas. They would really extend Axiom's power.  I want to do work in
Quantum Physics, with things like Hadamard gates, so I can implement
the quantum fourier transform algorithm. I've been working with Albert
Rich on the computer algebra test suite (CATS) using his 50,000 
integrals. I want to implement his techniques in Axiom to cover the
cases we miss now.

Wish lists are long, days are short.

Axiom is a "spare time" effort, not a career, so time is limited.  I
miss the days when computational mathematics was supported financially.
This "nights and weekends" approach is painfully slow. In fact, without
the support of Gilbert Baumslag, Axiom's release might not have happened
at all.







>I think what you are hinting at is that the original scratchpad software 
>was written by a large number of brilliant people and I am a single, 
>humble individual who is very far from being a genius. I assure you, I 
>know that already. I really should set myself more realistic goals.

There are truly brilliant people I've seen in the open source version
of Axiom. There is no shortage of brilliant people here. Waldek is
doing amazing work, for instance.  Do not ever feel that I'm "hinting"
you're not. I'm not the one to judge, nor is my opinion worth the time
to consider. If you're doing computational mathematics at all, you're
already in the best of company.

We need the brilliant among us to write stuff down for lesser mortals
like myself. It is wonderful to bring the gift of fire ... but could
you explain that trick with rubbing the sticks again? :-)





>It seems to me what Robert Lefkowitz is saying is that programs need to 
>change over time, and for that they need documentation and of course the 
>meaning of the word 'documentation' changes over time and everyone 
>understands the meaning of words differently. Mathematical truth may not 
>change over time, but the way that people use it, what is considered 
>important, notation and just about everything else does change. Perhaps 
>'documentation' does not mean what I think it means but, for me, its 
>about not freezing the program in time.

Mathematics changes over time but very slowly. I've heavily quoted
from a 19th century treatise on quaternions in the Axiom documentation.
The words are still relevant.

I don't want Axiom frozen. I want it brought to a state where it can
be maintained, modified, and extended without being a 1-in-a-million
programmer/mathematician/genius. Add new algebra, but document it.
Change old algebra, but document it first. Expose the thinking as
well as the code. Whatever gets written will IMMEDIATELY become a
maintenance task for the future. Communicate the ideas.

\start
Date: Tue, 13 May 2014 08:13:59 -0500
From: Tim Daly
To: Helmut Jarausch
Subject: [Axiom-developer] open-axiom-1.4.2 cannot be built with sbcl-1.1.18
Cc: Gabriel Dos Reis <gdr@cs.tamu.edu>

Helmut,

Please contact Gabriel Dos Reis, copied above, for help.

The SBCL problem is not unusual. One of the hard parts of a 
large project is the amount of time spent keeping up with
the many different ports to many platforms. 

You might consider trying it on a prior version of SBCL to
see if you can isolate the problem and give him a more
detailed bug report. The actual bug could have nothing to do
with either piece of software.

\start
Date: Tue, 13 May 2014 13:32:50 +0200
From: Helmut Jarausch
To: list
Subject: [Axiom-developer] open-axiom-1.4.2 cannot be built with sbcl-1.1.18

Hi,

I'm trying to build open-axiom-1.4.2 with SBCL-1.1.18.
It fails with strange memory errors like

; compiling (DEFUN |bfOR| ...)
; compiling (DEFUN |bfAND| ...)CORRUPTION WARNING in SBCL pid 9224(tid =20
140737353516800):
Memory fault at 1878002f (pc=0x100099ca66, sp=0x7ffff6c8eaf8)
The integrity of this image is possibly compromised.
Continuing with fingers crossed.
CORRUPTION WARNING in SBCL pid 9224(tid 140737353516800):
Memory fault at 40200066 (pc=0x10015259aa, sp=0x7ffff6c8e430)
The integrity of this image is possibly compromised.
Continuing with fingers crossed.
CORRUPTION WARNING in SBCL pid 9224(tid 140737353516800):
Memory fault at 40200066 (pc=0x10015259aa, sp=0x7ffff6c8dbe0)
The integrity of this image is possibly compromised.
Continuing with fingers crossed.

debugger invoked on a SB-SYS:MEMORY-FAULT-ERROR in thread
#<THREAD "main thread" RUNNING {1002E5E1F3}>:
   Unhandled memory fault at #x40200066.

and so on.

I have built Fricas and Maxima successfully with SBCL.

What is so special about Open-Axiom?

Of course, no source program should ever get a compiler in producing
memory faults. But is it only SBCL which is wrong here?

Is there a patch to build Open-Axiom with SBCL ?

\start
Date: Tue, 13 May 2014 12:34:18 -0500
From: Tim daly
To: Helmut Jarausch
Subject: [Axiom-developer] open-axiom-1.4.2 cannot be built with sbcl-1.1.18

Helmut,

You have the wrong mailing list. The names of the two projects
is a source of confusion.

This is the mailing list for Axiom. Please contact Gaby.

Tim Daly

\start
Date: Sun, 18 May 2014 01:44:18 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] Axiom mentioned in an LP talk by Bart Childs
Cc: John Kitchin

I've been listening to various talks about literate programming.  Bart
Childs of Texas A&M University, presented a paper with a talk "Thirty
Years of Literate Programming and More?" and mentions Axiom at around
24:30 (actually, somebody named Nelson, I suspect Nelson Beebe, from
the audience talks about it at Bart's request).

http://www.youtube.com/watch?v=D1cKI2jsidc

https://www.tug.org/TUGboat/tb31-2/tb98childs.pdf

He had some interesting results from teaching using literate programming
in an undergraduate course.

\start
Date: Sun, 18 May 2014 08:41:00 +0100
From: Martin Baker
To: list
Subject: Re: [Axiom-developer] Axiom mentioned in an LP talk by Bart Childs

Tim,

The link you gave:
http://www.youtube.com/watch?v=D1cKI2jsidc
did not work on my computer, I think it should be:
http://www.youtube.com/watch?v=D1cKI2jsldc

\start
Date: Sun, 18 May 2014 07:42:31 -0700
From: Gabriel Dos Reis
To: Helmut Jarausch
Subject: Re: [Axiom-developer] open-axiom-1.4.2 cannot be built with sbcl-1.1.18

On Tue, May 13, 2014 at 4:32 AM, Helmut Jarausch 

> Hi,
>
> I'm trying to build open-axiom-1.4.2 with SBCL-1.1.18.
> It fails with strange memory errors like
>
> ; compiling (DEFUN |bfOR| ...)
> ; compiling (DEFUN |bfAND| ...)CORRUPTION WARNING in SBCL pid 9224(tid
> 140737353516800):
> Memory fault at 1878002f (pc=0x100099ca66, sp=0x7ffff6c8eaf8)
> The integrity of this image is possibly compromised.
> Continuing with fingers crossed.
> CORRUPTION WARNING in SBCL pid 9224(tid 140737353516800):
> Memory fault at 40200066 (pc=0x10015259aa, sp=0x7ffff6c8e430)
> The integrity of this image is possibly compromised.
> Continuing with fingers crossed.
> CORRUPTION WARNING in SBCL pid 9224(tid 140737353516800):
> Memory fault at 40200066 (pc=0x10015259aa, sp=0x7ffff6c8dbe0)
> The integrity of this image is possibly compromised.
> Continuing with fingers crossed.
>
> debugger invoked on a SB-SYS:MEMORY-FAULT-ERROR in thread
> #<THREAD "main thread" RUNNING {1002E5E1F3}>:
>   Unhandled memory fault at #x40200066.
>
> and so on.
>
> I have built Fricas and Maxima successfully with SBCL.
>
> What is so special about Open-Axiom?
>
> Of course, no source program should ever get a compiler in producing
> memory faults. But is it only SBCL which is wrong here?
>
> Is there a patch to build Open-Axiom with SBCL ?
>
> Many thanks for some hints,
> Helmut

Helmut,

Thanks for the report.  Issues related to OpenAxiom  should be reported to
OpenAxiom developers at

    open-axiom-devel@lists.sf.net
    open-axiom-bugs@lists.sf.net

Are you by any chance building on Gentoo?  It looks the same as this issue:

https://groups.google.com/forum/#!msg/sbcl-help-archive/fTYViJjaotE/dsWMdRWPjJgJ

\start
Date: Sun, 18 May 2014 07:45:59 -0700
From: Gabriel Dos Reis
To: Helmut Jarausch
Subject: Re: [Axiom-developer] open-axiom-1.4.2 cannot be built with sbcl-1.1.18

> I have built Fricas and Maxima successfully with SBCL.
>
> What is so special about Open-Axiom?
>
> Of course, no source program should ever get a compiler in producing
> memory faults. But is it only SBCL which is wrong here?
>
> Is there a patch to build Open-Axiom with SBCL ?
>

PS: I build OpenAxiom regularly with SBCL on openSUSE and Mac OS X.
I do not have access to a Gentoo box, so anyway that would help me
reproduce this would be most welcome.

\start
Date: Sun, 18 May 2014 12:12:29 -0500
From: Tim Daly
To: Helmut Jarausch
Subject: [Axiom-developer] open-axiom-1.4.2 cannot be built with sbcl-1.1.18

Helmut,

This problem is not related to Axiom. They are different projects.

Please do not copy axiom-developer@nongnu.org on your mailings.

\start
Date: Mon, 19 May 2014 03:07:57 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] On syntactic coloring of language

I had a debate about syntax highlighting of languages, an idea that
dates back to Ada, as near as I can determine. In Ada publications
it was traditional to highlight, by bold characters, all of the
keywords in the language. This notion continues today.

Highlighting, and in particular bolding, is intended to draw attention
to things of interest. In normal prose one highlights portions of text
that are under discussion, items of controversy, or famous quotes. The
technique is a primary tool of communication.

In computer languages, of which I have professionally coded in over 60,
it is usually used in the Ada tradition of highlighting syntax.

Several objections can be raised. 

First, suppose we applied this to English. We could make the editor
bold the 19 basic prepositions (at, after, by, down, for, from, in,
of, on, over, past, round, since, through, till, to, under, up, with).
While syntactically correct it is, to say the least, distracting.

This draws attention to these "keywords" in the sentence but, as a
native speaker of English, adds nothing worthwhile. In computer
languages this has the same effect. It is not at all useful to bold
keywords like IF, THEN, or ELSE. Any native speaker of the language
can see these at a glance. Bringing such "background" items to the
"foreground" of attention highlights the static, inverting the usual
use of the technique in communication.

Even worse, some languages don't have "keywords" in the usual sense.
In Lisp it is entirely possible to use the symbol "if" in any number
of contexts, only one of which invokes its meaning as a conditional
statement. It is a complete waste of cycles to dynamically re-parse
text that a native speaker can read.

Second, and worse, such highlighting undermines the most important
aspect of the technique, namely to draw the reader's attention to
something noteworthy. Bolding and other forms of highlighting are
textual means of emphasis in communication. Regular, repeated, and
non-communicative use removes this from the toolbox of the author.

Third, and on a personal aside, one often encounters color-coded
program text in these highlighting schemes. As someone who is
partially color blind it is often impossible to see some characters at
all. It is usually possible to change these settings online but in
printed text whole passages are unreadable. Thus

   void foo(char *x) {
     if (x > b) then c else d;
   }

in certain colors becomes

       foo(     x) 
       (x   b)      c       d

which, I must say, certainly de-emphasizes the language syntax though
losing a bit in semantics. :-)

So consider the difference between "coding for yourself" where your
editor highlights code in pretty rainbow colors and "coding or writing
for communication" where the techniques for directing the attention of
the audience matters.

BE BOLD! may work for a wiki but not for communication.

\start
Date: Mon, 19 May 2014 08:56:06 -0400
From: William Sit
To: list
Subject: Re: [Axiom-developer] On syntactic coloring of language

Dear Tim:

Your reasoning is perfect for natural languages. For 
computer languages, I do think there is a purpose for 
certain highlighting of keywords and their associated 
punctuations, particularly when the correct language 
syntax frequently demands nested pairs of delimiters whose 
scopes may be more than a few lines, and where structural 
indentations may not be practical. Examples would be html, 
Mathematica and TeX/LaTeX. Thus, the reason for 
highlighting an IF-THEN-ELSE (as just one example) is not 
because readers can't recognize those keywords, but 
because readers may find it difficult to identify the 
extents indicated by the hyphens in IF-THEN-ELSE. Such 
highlighting benefits both the authors and the readers and 
has its role for better syntactic communication.

One should not compare or confuse the highlighting of, 
say, prepositions in natural languages with scope defining 
highlighting in programming languages.

That said, it is not good programming practice to have 
long scopes between paired delimiters, or for that matter, 
deeply nested pairs of delimiters.

I agree that those who choose color highlighting should 
choose colors carefully. I would prefer background 
coloring only and not text coloring, to avoid the precise 
problems you illustrated. Text emphasis should be shown 
using different typefaces, and in rare situations, a solid 
color like red.

\start
Date: Mon, 19 May 2014 16:26:15 +0200
From: Ralf Hemmecke
To: list
Subject: Re: [Axiom-developer] On syntactic coloring of language

> I agree that those who choose color highlighting should choose colors
> carefully. I would prefer background coloring only and not text
> coloring, to avoid the precise problems you illustrated. Text emphasis
> should be shown using different typefaces, and in rare situations, a
> solid color like red.

We are no longer in the early days of computers.
And we are dealing with open source.

I think that it's nowadays totally easy to separate style elements from
the content and let the *reader* decide what style he/she wants. In
LaTeX we have .sty files, for HTML there is .css etc. etc.

The only issue is if the reader has no choice than to read badly styled
text.

\start
Date: Mon, 19 May 2014 15:04:15 -0400
From: William Sit
To: Ralf Hemmecke
Subject: Re: [Axiom-developer] On syntactic coloring of language

Hi Ralf:

I don't think Tim is talking about the "product" (such as 
a compiled pdf from LaTeX, or a rendered html web page), 
but about the source files. The style in a publication is 
rightly the choice of the author, as a personal artistic 
preference. While it is possible (I won't say "easy") to 
change the style of a published work (as a web page, by 
changing css file), I doubt a reader would waste time if 
the reader finds the rendition really subjectively 
offending. The work will most likely be ignored. But that 
is not an issue: the author most likely just wanted to 
appeal to "flocks of the same feather" and used the style 
as a filter.

If the source (ASCII text with markups) is the product, 
then I agree with you. By using a different editor, one 
can change the style or even make it plain text with 
relative ease (say cut and paste to Notepad). The main 
issue in that case is the ubiquitous LF/CR problem.

\start
Date: Tue, 20 May 2014 11:53:13 -0400
From: John Kitchin
To: Tim Daly
Subject: Re: [Axiom-developer] Axiom mentioned in an LP talk by Bart Childs

Thanks. I recently wrote probably my first serious attempt at a literate
program in org-mode to insert and format references in technical documents!


On Sun, May 18, 2014 at 2:44 AM, <daly@axiom-developer.org> wrote:

> I've been listening to various talks about literate programming.  Bart
> Childs of Texas A&M University, presented a paper with a talk "Thirty
> Years of Literate Programming and More?" and mentions Axiom at around
> 24:30 (actually, somebody named Nelson, I suspect Nelson Beebe, from
> the audience talks about it at Bart's request).
>
> http://www.youtube.com/watch?v=D1cKI2jsidc
>
> https://www.tug.org/TUGboat/tb31-2/tb98childs.pdf
>
> He had some interesting results from teaching using literate programming
> in an undergraduate course.

\start
Date: Tue, 20 May 2014 15:19:54 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] documentation

An interesting blog post by Yevgenly Brikman

"You are what you document"

http://brikis98.blogspot.com.tr/2014/05/you-are-what-you-document.html?spref=tw

\start
Date: Tue, 20 May 2014 17:40:16 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] Nelson Beebe quote

I transcribed Nelson's quote from the Tug meeting, for those of you
who missed his comment.

Nelson said:

===========================================================

I come from a mathematics department and many mathematicians,
particularly those in pure math, have a strong distrust of computers
and they are really not inclined to accept computer-based proofs,
although there have been some dramatic examples of those in the last
two or three decades.

In the early 1970s, researchers at IBM developed a symbolic algebra
system called Scratchpad and this went on inside IBM for many years.
There were lots of papers written about it. It ultimately got renamed
to Axiom and was sold by NAG, the Numerical Algorithms Group in
England, for a few years.  And then it disappeared from the market and
became unavailable.

People worried about this for probably about 5 years but finally NAG
was able to release it and a major decision has been taken. Axiom is
being completely reimplemented as a literate program. And the reason
is, is that software outlives hardware, and often its own authors. The
author of Scratchpad died about 5 years ago.

So they feel the only way that this system can survive and be used by
future generations is to be written as a literate program so that the
reason behind the program is embedded there as part of the description
of the code. I think this is really important and could be really
quite significant for the future growth of computing and mathematics.

===========================================================

\start
Date: Wed, 21 May 2014 06:03:04 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] Heidegger, literate programming, and communication

The primary focus of a "documentation system" is communication from 
the author to the audience.

One of the struggles apparent in discussing issues of communication,
especially with programmers, is Heideggers "present-at-hand" vs
"breaking down".

Programmers write programs to instruct a machine to perform some
task. In the ideal, this involves "communication" from the mind of
the programmer to the "execution of the program". If the program works
the first time it is all a seamless entity ("present-at-hand").

When the program fails, by compiler errors, missing libraries, runtime
errors, design errors, inappropriate actions, or any of the other dragons
of programming, the process is not seamless. The details of the process
rise to our awareness ("breaking down"). The burden of failure is likely
to fall on people who use or maintain the program rather than the authors.
If the program survives, these are likely audiences.



Programmers, generalizing from my own case, rarely have a seamless
experience.  Programs that work the first time, are correct, efficient, 
and all of the other properties, are rather far outside our experience.

The effect of this constant "breaking down" is that we have learned,
rather painfully, to be aware of the machinery of the process at every
step of the way. This focus on the machinery becomes the expected way
of communicating with the machine. Scratch any programmer, interview at
any company, listen to any talk, and you find "machinery".

But communication from the author to the audience is the underlying
theme of literate programming. Knuth's point is about communication,
not about the machinery of communication. The question is, to what
audience, not how.



Discussions seem to get lost in a debate about the machinery rather
than the goal. We focus our debate on docstrings versus markup versus
wiki. We consider literate programming to be "too much machinery".

In these forums there is rarely find any example of "present-at-hand"
issues of communication.  That is, given a large program (e.g. Axiom,
Clojure), what is it that we need to communicate, to what audience,
and at what level of detail?

Axiom focuses on "The 30 year horizon" under the assumption that the
computational mathematics will be forever valid and that the audience
will be unable to contact the likely-dead authors.

Pharr and Humphreys' "Physically Base Rendering" [0] is written as a
literate program, a book that won an Academy Award, using Tex and
C++. The very first thing they mention in the preface is the
"Audience". They communicate to humans and, also, to machines.

What is the audience for Clojure? 

Common Lisp has achieved a long-term horizon by raising the language
to a standard. No standard is perfect but it does make it possible to
construct programs which have a stable base for communication. That
base makes it possible to write a book like "Lisp in Small Pieces" [1]
which communicates ideas in natural language using an embedded program
as a reduction to practice.



So the fundamental point is what to communicate to what audience,
not how to implement it. Different audiences will need different
implementations (e.g. docstrings for REPL users) but we must avoid
losing ourselves in the noise. 

Axiom, by choice, has a defined audience. Does Clojure?

Tim Daly
daly@axiom-developer.org

[0] Pharr, Matt; Humphreys, Greg
    Physically Based Rendering
    ISBN 978-0-12-375079-2
[1] Queinnec, Christian
    Lisp in Small Pieces
    ISBN 978-0521545662

\start
Date: Wed, 21 May 2014 14:16:25 -0700 (PDT)
From: Marshall Abrams
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication

On Wednesday, May 21, 2014 6:03:04 AM UTC-5, da...@axiom-developer.org 
wrote:
>
> The primary focus of a "documentation system" is communication from 
> the author to the audience. 
>
> One of the struggles apparent in discussing issues of communication, 
> especially with programmers, is Heideggers "present-at-hand" vs 
> "breaking down". 
>
> Programmers write programs to instruct a machine to perform some 
> task. In the ideal, this involves "communication" from the mind of 
> the programmer to the "execution of the program". If the program works 
> the first time it is all a seamless entity ("present-at-hand"). 
>
> When the program fails, by compiler errors, missing libraries, runtime 
> errors, design errors, inappropriate actions, or any of the other dragons 
> of programming, the process is not seamless. The details of the process 
> rise to our awareness ("breaking down"). The burden of failure is likely 
> to fall on people who use or maintain the program rather than the authors. 
> If the program survives, these are likely audiences. 
>
>
>
> Programmers, generalizing from my own case, rarely have a seamless 
> experience.  Programs that work the first time, are correct, efficient, 
> and all of the other properties, are rather far outside our experience. 
>
> The effect of this constant "breaking down" is that we have learned, 
> rather painfully, to be aware of the machinery of the process at every 
> step of the way. This focus on the machinery becomes the expected way 
> of communicating with the machine. Scratch any programmer, interview at 
> any company, listen to any talk, and you find "machinery". 
>
> But communication from the author to the audience is the underlying 
> theme of literate programming. Knuth's point is about communication, 
> not about the machinery of communication. The question is, to what 
> audience, not how. 
>
>
>
> Discussions seem to get lost in a debate about the machinery rather 
> than the goal. We focus our debate on docstrings versus markup versus 
> wiki. We consider literate programming to be "too much machinery". 
>
> In these forums there is rarely find any example of "present-at-hand" 
> issues of communication.  That is, given a large program (e.g. Axiom, 
> Clojure), what is it that we need to communicate, to what audience, 
> and at what level of detail? 
>
> Axiom focuses on "The 30 year horizon" under the assumption that the 
> computational mathematics will be forever valid and that the audience 
> will be unable to contact the likely-dead authors. 
>
> Pharr and Humphreys' "Physically Base Rendering" [0] is written as a 
> literate program, a book that won an Academy Award, using Tex and 
> C++. The very first thing they mention in the preface is the 
> "Audience". They communicate to humans and, also, to machines. 
>
> What is the audience for Clojure? 
>
> Common Lisp has achieved a long-term horizon by raising the language 
> to a standard. No standard is perfect but it does make it possible to 
> construct programs which have a stable base for communication. That 
> base makes it possible to write a book like "Lisp in Small Pieces" [1] 
> which communicates ideas in natural language using an embedded program 
> as a reduction to practice. 
>
>
>
> So the fundamental point is what to communicate to what audience, 
> not how to implement it. Different audiences will need different 
> implementations (e.g. docstrings for REPL users) but we must avoid 
> losing ourselves in the noise. 
>
> Axiom, by choice, has a defined audience. Does Clojure? 
>
> Tim Daly 
> da...@axiom-developer.org <javascript:> 
>
> [0] Pharr, Matt; Humphreys, Greg 
>     Physically Based Rendering 
>     ISBN 978-0-12-375079-2 
> [1] Queinnec, Christian 
>     Lisp in Small Pieces 
>     ISBN 978-0521545662 
>

\start
Date: Wed, 21 May 2014 14:39:03 -0700 (PDT)
From: Marshall Abrams
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication


>From my point of view there are at least a few things that seem clear:

1. I think that Gregg Reynolds and I agree on a lot, but I would add to his 
remarks that there is almost always a human audience for source code, as 
well as the compiler/interpreter.  Sometimes, the audience is just the 
originally programmer, perhaps at a later date.  (If I missed something, 
Gregg, sorry, but I don't think you disagree, anyway.)

2. Since Clojure is a general-purpose tool, Clojure source code has no 
single kind of human audience for the code.  

In general, I do different things with comments, or with my coding style, 
depending on whether I expect that I will be the only maintainer of the 
code, or expect that others with whom I'm collaborating will need to 
interface with it, for example.  Further, I think about the skill levels 
and background of those who will read the code.  And I think about what 
they would want to do with it.  And then I make decisions that involve 
tradeoffs between competing desiderata.

3. There is a tradeoff between the desire to see a lot of code at once, 
without a lot of text cluttering it up, and understanding what the code is 
doing.  Comments hurt the former but can help the latter.  The same thing 
goes for literate programming, but--it depends on your goals and your human 
audience.

4. Two examples to convey the context-dependence of appropriate 
configuration schemes:

A. One time I wrote a small but slightly complex bit of code (in Perl, not 
Clojure).  I could see that it would be confusing, if someone just started 
reading the code at an arbitrary place.  But I also knew the ability of the 
other programmers I worked with, and I knew that if they started reading at 
one particular function, they would be able to figure out most of the 
rest.  I provided text that explained what they wouldn't be able to figure 
out.  About six months after I left the company, one of the programmers 
contacted me and asked me to explain the program; he had to make a 
modification.  I told him to look at such and such document, which mainly 
said "Start reading the code at such and such point, and understand these 
few other things."  He did, and that was all he needed.  If I wrote more 
documentation, I would only be duplicating the information that was already 
there in the source code, and that would be apparent for the kind of people 
who would read it.  In fact, if I provided *more* documentation, I doubt 
that the other programmers would have read it.  They would have just looked 
at the source.

B. Another example.

I generally don't like the idea of LP.  That is to say, I like the idea of 
people who want to be able to use it, using it, but I don't want to use it, 
usually.  And the reason that I don't want to use it is not simply that I 
don't want to bother writing it.  It's that I want the ability to use 
simple tools and I want to have relatively uncluttered source code.  (I 
could use LP and have uncluttered source much of the time, but only by 
using special tools.)

In my current main project, there is source code that implements the 
central functionality of the application, and there are rather complex 
configuration files.  I write documents to describe the central 
functionality source code, so that someone who wants to hack on it will 
know where to start and where to look.  I have to trust that they will know 
or will be willing to learn Clojure, because otherwise I'd have to explain 
too much.

However, the configuration files should be modifiable by people who won't 
understand the guts of the program, and yet, they are in Clojure, and would 
be pretty unintelligible to someone who merely understood in general what 
the program was supposed to do.  (I may create a DSL for the config files, 
but all that will do will be to get rid of a few parentheses.  The 
information in the config files won't be expressed significantly more 
succinctly.)

For the first time I'm thinking of using LP.  It would be perfect for the 
config files, and in fact, any other way of documenting the config files 
will probably be inadequate.  Interspersing explanations with the 
configuration code is precisely what's needed.

\start
Date: Thu, 22 May 2014 02:16:53 -0400
From: Tim Daly
To: Gregg Reynolds, Marshall Abrams
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication

Gregg and Gary,

I understand where you are coming from. Indeed, Maturana [0] is on your
side of the debate. Since even the philosophers can't agree, I doubt we
will find a common ground. 

Unfortunately, I've decided to take on the task of documenting the
Clojure internals because, yaknow, *I* don't feel I understand something
until I know what the hardware does; consider this a flaw in my
personality :-) I have to say that the posted Clojure code is
"somewhat lacking" in the communication department. Perhaps it is only
intended for an "audience of one", and I'm not "the one". :-)

Contrary to popular belief, I am reading the code. As a result, I have a
strongly held opinion that there is a lot that could be done to make
it less of a struggle.


>> From my point of view there are at least a few things that seem clear:
>>
>> 1. I think that Gregg Reynolds and I agree on a lot, but I would add to
>> his remarks that there is almost always a human audience for source code,
>> as well as the compiler/interpreter.  Sometimes, the audience is just the
>> originally programmer, perhaps at a later date.  (If I missed something,
>> Gregg, sorry, but I don't think you disagree, anyway.)
>>
>
>I agree; whoever writes the code automatically forms an "audience" of one.
>I guess I would say "reader/responder".

Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long.
What are the odds that the original authors will be maintaining the
code? Will the code still be "an audience of one"? Are you sure that's
a worthwhile goal?



>> 2. Since Clojure is a general-purpose tool, Clojure source code has no
>> single kind of human audience for the code.
>>
>> In general, I do different things with comments, or with my coding style,
>> depending on whether I expect that I will be the only maintainer of the
>> code, or expect that others with whom I'm collaborating will need to
>> interface with it, for example.  Further, I think about the skill levels
>> and background of those who will read the code.  And I think about what
>> they would want to do with it.  And then I make decisions that involve
>> tradeoffs between competing desiderata.
>

My experience "in industry" with "general-purpose tool" code is that
code does look a lot different from project to project and language to
language. But as code moved out of its childhood and off the desk, it
began to grow hair and get ugly. The authors all assumed they would be
"the only maintainer". For instance,

   I once had to maintain a C program that had 14 pages of nested ifdefs
   just to choose the correct #include files. Each include file had
   ifdefs.  The code ran everywhere, Intel, ARM, 68000s, SUNs, DEC,
   etc. but nearly every line was based on experience (e.g. compensating
   for floating-point errors on various platforms, hacking around errors
   in various C compilers and their "optimizers", etc.) with ifdefs
   around each hack. I had to run the compiler intermediate stage to
   figure out what the actual code would be for my platform. And then I
   had to reverse-engineer the fix into the appropriate include files;
   uncommented I might add. I wouldn't want to ruin the style.

   Sophisticated Lisp programmers use macros A LOT. Axiom, for instance,
   compiles code from a high-level algebra language, essentially a DSL,
   into macros that index into vectors for the function to call, or the
   category to inherit which might contain the call, and the environment
   passed to each function is a huge vector. DSLs, which make the top
   level code "so clear", often are macros generating machine-code-like
   lisp doing super-efficient vector indexing. One finds macros
   expanding into macros expanding into macros. Quick, what does the
   spadcall macro do?

   And we won't even mention that despite the use of a DSL, the DSL
   code isn't "perfectly clear" either. This is especially true when
   it gets mixed with inline, non-DSL code. For instance, Axiom's
   algebra code regularly invokes low-level lisp functions.



>Exactly.  Conclusion: it's hard, maybe impossible, to generalize about what
>all code should look like.  Maybe it's essentially pluralistic.

Yes, it is hard to generalize about what all code should look like. But
it is not hard to generalize that reading natural language explanations
is faster, more accurate, and a lot easier than reverse-engineering
code. It is MUCH easier to understand Greg Humphrey's rendering code
than it is to understand the Clojure internals.

Consider a randomly chosen paragraph from Physically Based Rendering
(p356):



  To do the permutation, this function loops over the samples, randomly
  permuting the sample points in one dimension at a time. Note that this
  is a different permutation than the earlier Shuffle() routine: that
  routine does one permutation, keeping all nDim sample points in each
  sample together, while here nDim separate permutations of a single
  dimension at a time are done. (Figure 7.21)

   for (uint32_t i = 0; i < nDim; ++1) {
     for (uint32_t j = 0; j < nSamples; ++j) {
       uint32_t other = j + (rng.RandomUInt() % (nSamples - j));
       swap(samples[nDim + j + i], samples[nDim * other + i]);
     }
   }

  Footnote: While it's not necessary to permute the first dimension of
  the LHS pattern, the implementation here does so anyway since making
  the elements of the first dimension be randomly ordered means that LHS
  patterns can be used in conjunction with sampling patterns from other
  sources without danger of correlation between their sample points.



So we learned what the code does. We also learned not to "optimize the
code" by replacing it with Shuffle(). Further, we learned that we 
shouldn't "optimize the code" by removing the apparently useless
shuffle of the first dimension. And, as a bonus, we get a figure.
NONE OF THIS INFORMATION IS IN THE CODE ITSELF.

In addition, this code lives in an organizing structure. It is 
in Chapter 7: Sampling and Reconstruction
     Section 7.3: Stratified Samples 


Heck, it is only 4 lines of C++. Why bother? *I* can read C++.  I can
even reverse engineer it (probably by inventing the diagram in Figure
2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is
all the organization necessary. :-)  But I can't reverse engineer the
important information in either paragraph of text.

For comparison, refer back to the multi-page Java code I posted
from the Clojure core. As a maintenance programmer, which would you
rather maintain?
  



Estimates are that programs that "live" spend 80% or more of their
"lifetime" in maintenance. 

Companies that depend on a "crufty old program" (a l33t-speak term for
any program not authored by the current maintainer) are willing to pay
the cost to have programmers read the code, take notes, and spend time
reverse-engineering the code.

In contrast, open source code tends to die the moment the original
authors stop typing. Sourceforge, github, savannah, etc. are
wall-to-wall full of code nobody will ever use. It is very common to
see someone write:

   "Well, it hasn't been updated in the last 6 months so I don't think
    it is being maintained anymore."

Being an "audience of one" when writing the code means the program
will have an "audience of one" in github; until 6 months pass and it has
an "audience of zero".

Languages come into fashion all the time. Almost all of them disappear.
Axiom and Clojure are worthwhile efforts. We really need a mindset that
extends into the future, communicating with the maintainers.

Tim Daly

For want of a comment, the fix was lost.
For want of a fix, the routine was lost.
For want of a routine, a program was lost.
For want of a program, the customer was lost.
For want of a customer, the company was lost.

[0] Zeleny, M. (ed.)
    "Autopoiesis, a Theory of the Living Organization"
    New York, Elsevier-North Holland (1978)

\start
Date: Wed, 21 May 2014 21:22:58 -0500
From: Gregg Reynolds
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication

On Wed, May 21, 2014 at 4:39 PM, Marshall Abrams wrote:

> Tim,
>
> From my point of view there are at least a few things that seem clear:
>
> 1. I think that Gregg Reynolds and I agree on a lot, but I would add to
> his remarks that there is almost always a human audience for source code,
> as well as the compiler/interpreter.  Sometimes, the audience is just the
> originally programmer, perhaps at a later date.  (If I missed something,
> Gregg, sorry, but I don't think you disagree, anyway.)
>

I agree; whoever writes the code automatically forms an "audience" of one.
I guess I would say "reader/responder".


>
> 2. Since Clojure is a general-purpose tool, Clojure source code has no
> single kind of human audience for the code.
>
> In general, I do different things with comments, or with my coding style,
> depending on whether I expect that I will be the only maintainer of the
> code, or expect that others with whom I'm collaborating will need to
> interface with it, for example.  Further, I think about the skill levels
> and background of those who will read the code.  And I think about what
> they would want to do with it.  And then I make decisions that involve
> tradeoffs between competing desiderata.
>

Exactly.  Conclusion: it's hard, maybe impossible, to generalize about what
all code should look like.  Maybe it's essentially pluralistic.

>
> 3. There is a tradeoff between the desire to see a lot of code at once,
> without a lot of text cluttering it up, and understanding what the code is
> doing.  Comments hurt the former but can help the latter.  The same thing
> goes for literate programming, but--it depends on your goals and your human
> audience.
>
> 4. Two examples to convey the context-dependence of appropriate
> configuration schemes:
>
> A. One time I wrote a small but slightly complex bit of code (in Perl, not
> Clojure).  I could see that it would be confusing, if someone just started
> reading the code at an arbitrary place.  But I also knew the ability of the
> other programmers I worked with, and I knew that if they started reading at
> one particular function, they would be able to figure out most of the
> rest.  I provided text that explained what they wouldn't be able to figure
> out.  About six months after I left the company, one of the programmers
> contacted me and asked me to explain the program; he had to make a
> modification.  I told him to look at such and such document, which mainly
> said "Start reading the code at such and such point, and understand these
> few other things."  He did, and that was all he needed.  If I wrote more
> documentation, I would only be duplicating the information that was already
> there in the source code, and that would be apparent for the kind of people
> who would read it.  In fact, if I provided *more* documentation, I doubt
> that the other programmers would have read it.  They would have just looked
> at the source.
>

Yep; there's always a point of diminishing returns.  I find that in
developing code (or trying to understand others' code) I often take
extensive notes and sometimes try to mentally "improve" what I deem sloppy
or hard-to-read by writing a clear description of it, or just expressing it
in different language.  But once I get comfortable with the code I don't
often return to my documentation.

...

> For the first time I'm thinking of using LP.  It would be perfect for the
> config files, and in fact, any other way of documenting the config files
> will probably be inadequate.  Interspersing explanations with the
> configuration code is precisely what's needed.
>

I agree, that's a case where monolithic LP is entirely appropriate.  Ditto
for APIs and unit tests; maybe also for simplified examples of API usage
expressly designed for training.

\start
Date: Thu, 22 May 2014 04:21:37 -0500
From: Gregg Reynolds
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication
Cc: Marshall Abrams

Howdy Tim,


On Thu, May 22, 2014 at 1:16 AM, u1204 <daly@axiom-developer.org> wrote:

> Gregg and Gary,
>
> I understand where you are coming from. Indeed, Maturana [0] is on your
> side of the debate. Since even the philosophers can't agree, I doubt we
> will find a common ground.
>

Ah, but philosophers never agree.  Disagreement is part of their job
description.  Why should programmers be any different?


>
> Unfortunately, I've decided to take on the task of documenting the
> Clojure internals because, yaknow, *I* don't feel I understand something
> until I know what the hardware does; consider this a flaw in my
> personality :-)


I suffer from a similar malady, which compels me to continually rewrite
other peoples code, since, gee whiz, "foo" is not quite the perfect name
for that darn variable, "bar" would be just slightly better, and on and
on.  You can see why I prefer code to commentary.
...
>>
>> 1. I think that Gregg Reynolds and I agree on a lot, but I would add to
>> his remarks that there is almost always a human audience for source code,
>> as well as the compiler/interpreter.  Sometimes, the audience is just the
>> originally programmer, perhaps at a later date.  (If I missed something,
>> Gregg, sorry, but I don't think you disagree, anyway.)
>>
>
>I agree; whoever writes the code automatically forms an "audience" of one.
>I guess I would say "reader/responder".

Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long.
> What are the odds that the original authors will be maintaining the
> code? Will the code still be "an audience of one"? Are you sure that's
> a worthwhile goal?
>

I think you may have misunderstood me (dunno about Gary): my point is that
even one-off code that gets discarded immediately has a human reader,
namely the author.  A statement of (minimal) fact, not a goal.

...

>
>    Sophisticated Lisp programmers use macros A LOT.


That's because they are language designers, and they know it.


>    expanding into macros expanding into macros. Quick, what does the
>    spadcall macro do?
>

HCF?

>Exactly.  Conclusion: it's hard, maybe impossible, to generalize about what
> >all code should look like.  Maybe it's essentially pluralistic.
>
> Yes, it is hard to generalize about what all code should look like. But
> it is not hard to generalize that reading natural language explanations
> is faster, more accurate, and a lot easier than reverse-engineering
> code.


Whoa Nelly!  I don't agree with that at all, either in principle or by
experience.  Well, ok, you've rigged the game.  Easier than
"reverse-engineering code" - what does that mean?  I guess you mean reading
well-written natural language explanations is faster etc. than reading
badly written code - but so what?  It's not a meaningful comparison.  Would
you take a comparison between a sample of well-written code and a sample
badly written LP as evidence against LP?  I would not.  To me the question
is whether well-written natural language explanation adds anything of
substance to well-written code.


> It is MUCH easier to understand Greg Humphrey's rendering code
> than it is to understand the Clojure internals.
>

Ok, but I don't see how exhibiting a piece of transparent code next to a
piece of opaque code demonstrates anything.


>
> Consider a randomly chosen paragraph from Physically Based Rendering
> (p356):
>
>   To do the permutation, this function loops over the samples, randomly
>   permuting the sample points in one dimension at a time. Note that this
>   is a different permutation than the earlier Shuffle() routine: that
>   routine does one permutation, keeping all nDim sample points in each
>   sample together, while here nDim separate permutations of a single
>   dimension at a time are done. (Figure 7.21)
>
>    for (uint32_t i = 0; i < nDim; ++1) {
>      for (uint32_t j = 0; j < nSamples; ++j) {
>        uint32_t other = j + (rng.RandomUInt() % (nSamples - j));
>        swap(samples[nDim + j + i], samples[nDim * other + i]);
>      }
>    }
>
>   Footnote: While it's not necessary to permute the first dimension of
>   the LHS pattern, the implementation here does so anyway since making
>   the elements of the first dimension be randomly ordered means that LHS
>   patterns can be used in conjunction with sampling patterns from other
>   sources without danger of correlation between their sample points.
>
> So we learned what the code does. We also learned not to "optimize the
> code" by replacing it with Shuffle(). Further, we learned that we
> shouldn't "optimize the code" by removing the apparently useless
> shuffle of the first dimension. And, as a bonus, we get a figure.
> NONE OF THIS INFORMATION IS IN THE CODE ITSELF.
>

For "what the code does":

/* inline random, total, in-place matrix permutation - contrast Shuffle() */
...code...

The first line of commentary is totally redundant, so it is a waste of time
to read both it and the code.  As for what not to "optimize": if none of
the conclusions you draw are in the code, they're not in the commentary,
either.  Replacing the code with Shuffle would change the meaning from
total to partial permutation, so it would not be an optimization.  Ditto
for replacing it with Shuffle.  But the explanation of the difference
between this code and Shuffle is unhelpful to me - what does "[the Shuffle]
routine does one permutation, keeping all nDim sample points in each sample
together" mean?  I'd have to read that code to find out, so the commentary
has just wasted my time.   As for the permutation of the first dimension,
here the commentary is bad again - first it says it is not necessary, then
it explains that it is necessary if you want to use it for a specific
purpose.  As for the figure, I assume the book has some kind of graphic.  I
don't think I need a graphic to understand the code - it's a simple
permutation.

So for me at least, this example counts against rather than for the point
that (I assume) you want to make.  The point I will make is not that
documentation is inherently evil - far from it - but merely that
explanatory prose is not a *necesssary* condition of readable code.  And it
often makes things worse, as in this case.


>
> In addition, this code lives in an organizing structure. It is
> in Chapter 7: Sampling and Reconstruction
>      Section 7.3: Stratified Samples
>
>
> Heck, it is only 4 lines of C++. Why bother? *I* can read C++.  I can
> even reverse engineer it (probably by inventing the diagram in Figure
> 2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is
> all the organization necessary. :-)  But I can't reverse engineer the
> important information in either paragraph of text.
>
> For comparison, refer back to the multi-page Java code I posted
> from the Clojure core. As a maintenance programmer, which would you
> rather maintain?
>

Really?  What's the point of comparing 4 lines of C++ and multiple pages of
Java?  I can tell you I would rather maintain the four lines of C++ without
the largely useless commentary.  I would also rather maintain a
(well-written) plain Pascal version of "Printing the primes" than the LP
version Knuth uses in his paper on LP (a web search will turn up a preprint
copy).

... snip ...

Languages come into fashion all the time. Almost all of them disappear.
> Axiom and Clojure are worthwhile efforts. We really need a mindset that
> extends into the future, communicating with the maintainers.
>

Dunno anything about Axiom, I'm afraid.  As for the future, I think it is
best served by doing our best to write clear *code* now.  You mentioned
Axiom has a 30 year timeline.  I won't be surprised if humans do relatively
little hands-on coding (or code reading) by then.  Between AI and automated
reasoning (for which the commentary part of LP is irrelevant) I expect the
number of programmer jobs to shrink drastically by then.

In any case, I wish you luck with your Clojure internals project.  If XML
doesn't give you the hives check out
https://github.com/mobileink/xsl.clj-ext - I think it could be used to good
effect to document the APIs, if not the internals, by example.

\start
Date: Thu, 22 May 2014 11:40:24 +0200
From: Ralf Hemmecke
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication

On 05/22/2014 11:21 AM, Gregg Reynolds wrote:
> I can tell you I would rather maintain the four lines of C++ without
> the largely useless commentary.

That's a simple AXIOM program, but I'm sure one can easily translate it
into any programming language.

foo(a: Integer, b: Integer): Integer ==
    if a > 0 then
        if a > b then return foo(b,a)
        return foo(b-a,a))
    return b

Question: Does the program have a bug?

\start
Date: Thu, 22 May 2014 15:29:11 +0200 (CEST)
From: Fabio Stumbo
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication

>> I can tell you I would rather maintain the four lines of C++ without
>> the largely useless commentary.
>
> That's a simple AXIOM program, but I'm sure one can easily translate it
> into any programming language.
>
> foo(a: Integer, b: Integer): Integer ==
>    if a > 0 then
>        if a > b then return foo(b,a)
>        return foo(b-a,a))
>    return b
>
> Question: Does the program have a bug?
>
> Ralf

Yes: there is an extra parenthesis in the fourth line... :)

Which, BTW, I discovered as soon as I pasted it in a file since 
it was error-highlighted by the syntax highlighting in vim :))

A part from this, I think the example points out that perhaps we can make 
a difference between source code of axiom (as a piece of software) and 
implementation of (higher) mathematics: maybe the need for a 
complete and thorough documentation can be considered of different 
importance in the two cases.

\start
Date: Thu, 22 May 2014 15:40:11 +0200
From: Ralf Hemmecke
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication
Cc: Marshall Abrams, Gregg Reynolds

On 05/22/2014 03:29 PM, Fabio S. wrote:
>>> I can tell you I would rather maintain the four lines of C++ without
>>> the largely useless commentary.
>>
>> That's a simple AXIOM program, but I'm sure one can easily translate it
>> into any programming language.
>>
>> foo(a: Integer, b: Integer): Integer ==
>>    if a > 0 then
>>        if a > b then return foo(b,a)
>>        return foo(b-a,a))
>>    return b
>>
>> Question: Does the program have a bug?
>>
>> Ralf
> 
> Yes: there is an extra parenthesis in the fourth line... :)
> 
> Which, BTW, I discovered as soon as I pasted it in a file since it was
> error-highlighted by the syntax highlighting in vim :))

Well, you caught me, so I try again. ;-)
And... the problem is be no means specific to AXIOM.

foo(a: Integer, b: Integer): Integer ==
    if a > 0 then
        if a > b then return foo(b,a)
        return foo(b-a,a)
    return b

Question: Does the program have a bug?

> A part from this, I think the example points out that perhaps we can
> make a difference between source code of axiom (as a piece of software)
> and implementation of (higher) mathematics: maybe the need for a
> complete and thorough documentation can be considered of different
> importance in the two cases.

Sorry, I don't get the difference.

\start
Date: Thu, 22 May 2014 16:00:28 +0000
From: Doug Stewart
To: Ralf Hemmecke
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication
Cc: Marshall Abrams, Gregg Reynolds

I think that your question is related to the fact that if we don't
know the purpose of a function then we cannot know if there is a bug
in the function.And LP would explain the purpose of the function.

I am 100% in agreement with LP.

when I was teaching C C++ I was always repeating to my students that
when you comment a line or section of code "don't tell me the this
code copies the value in y to x (x=y) but tell me why that section of
code is there."

I think that one of the posters is really missing the point of proper
documentation when he said that the comments are useless because
he can always read the code. The comments are not there to explain
what the code does on that low of a level=2C but why is it there and
what is its overall purpose and why I did it that way and not some
other way.

Just my 2 cents worth.

PS I have many chunks of code that I wrote 20-30 years ago and I have
no idea why and what the  code was written for!!!! even after reading 
each line  of the code!!!! 

\start
Date: Thu, 22 May 2014 19:25:13 +0200 (CEST)
From: Fabio Stumbo
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication

...
>> And... the problem is be no means specific to AXIOM.
>>
>> foo(a: Integer, b: Integer): Integer ==
>>     if a > 0 then
>>         if a > b then return foo(b,a)
>>         return foo(b-a,a)
>>     return b
>>
>> Question: Does the program have a bug?
>>
>
> I think that your question is related to the fact that if we don't know 
> the purpose of a function then we cannot know if there is a bug in the 
> function.And LP would explain the purpose of the function.
...

My thought is that things are a little more complicated: you should 
explain both the purpose of the function and how it is implemented.

In this case, a little change in the "how" creates the problem: Ralf's 
function is clearly an implementation of the original (and 
inefficient) euclidean algorithm from the "Elements".
Yet it gives wrong results, since he changed deliberately domain and 
codomain; for example, if a<0 then simply foo(a,b)=b.

The point is that the proof in the Elements assumes that a,b are PI.
So to have a function without bugs either we need to change the domain to 
PIxPI or we need to add two auxiliary variables
c:=abs(a)
d:=abs(b)
and then we work with them.

This is what I meant when talking about documenting maths: it can look 
correct from a syntactic point of view and can compile correctly, yet the 
result can be wrong. If the underlying math is advanced, the debugging is 
complicated by the fact that not a lot of people have the necessary 
knowledge to track the function and find the error: if it is not well 
documented, probably nobody will do it.

> Just my 2 cents worth.

and these are just mine...

\start
Date: Thu, 22 May 2014 13:35:57 -0400 (EDT)
From: Tim Daly
To: Gregg Reynolds
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication

Forward from Ralf Hemmecke:


On 05/22/2014 11:21 AM, Gregg Reynolds wrote:
> I can tell you I would rather maintain the four lines of C++ without
> the largely useless commentary.

That's a simple AXIOM program, but I'm sure one can easily translate it
into any programming language.

foo(a: Integer, b: Integer): Integer ==
    if a > 0 then
        if a > b then return foo(b,a)
        return foo(b-a,a))
    return b

Question: Does the program have a bug?

Ralf

\start
Date: Thu, 22 May 2014 14:46:51 -0400
From: Tim Daly
To: Doug Stewart
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication

>PS I have many chunks of code that I wrote 20-30 years ago and I have no
>idea why and what the code was written for!!!! even after reading each
>line of the code!!!!

This is what got me interested in literate programming. 

Axiom was written at IBM as "research code", mostly by people trying to
get a PhD. I wrote bits and pieces of the internals but didn't bother
to document anything, especially since I write "dirt simple code".

Fifteen years later I'm looking at my own code. I know what it does.
I can even tell you what bytes the compiler will lay down in memory.
I know the code is needed since the system fails if I remove it.

But I have no clue WHY I wrote it.

The person who wrote the code failed to communicate with the person
who maintains the code. I have the misfortune of being both people.

I understand the strong opposition to writing good documentation at any
level.  Especially when writing code; it just seems wasteful to "state
the obvious". 

One non-obvious side effect of doing literate programming is that the
code quality improves a LOT. As Bill Hart said:

    Another thing I've been enjoying lately is literate programming.
    Amazingly it turns out to be faster to write a literate program
    than an ordinary program because debugging takes almost no time.

I fear that we're going to have the same approach as the physicists.
"New theories get accepted when the previous generation dies out."

Fortunately statistics show that programmers retire into management
at age 35 so we won't have to wait that long. If there is any justice,
the managers will have to hire noobs to maintain code they wrote so
they get to listen to the noobs trash talk about their code. :-)

\start
Date: Thu, 22 May 2014 12:18:44 -0700 (PDT)
From: Marshall Abrams
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming,	and communication
Cc: Gregg Reynolds

Tim,

Your project of LP'ing the Clojure internals is not at all  inconsistent 
with my view.  That is code that would benefit from being widely 
understood, even by people who won't maintain it.  I learned a lot from 
reading the "Lions" book on an early version of Unix, even though I 
probably never even used hardware old enough to run it.  (On the other 
hand, I'm not sure that there should be documentation that explains the 
complexities of the chunking mechanism both at the definitions of `map` and 
`doseq`, for example.  That seems redundant.  Maybe LP software has 
convenient ways of dealing with that sort of issue, though.)

And I agree that won't can't know what code will live for 25 years, and 
what won't, and how many people will have to maintain the code.  So one 
approach is simply to assume that all code will live a long time and be 
maintained by many people, many of whom will be unfamiliar with the code.  
But that means that you waste a lot of time on code that gets put aside 
(for reasons other than lack of documentation).  

Yeah, there are tradeoffs.  We have to make our best judgments.

One option: Write with whatever documentation you think will help the 
code's forseen uses.  Then, if you discover later, that it needs better 
documentation, write it then.  That won't be as easy as writing it in the 
first place: In hindsight, it's less efficient, but it may be more 
efficient overall across all projects.  (i.e. one "faults in" the 
documentation: It's sometimes most efficient to allocate all of an 
executable's image and heap as soon it runs, but modern OSes instead often 
allocate memory only as needed, which, in hindsight, is less efficient, but 
overall, makes for a more efficient system.)

(I think I am the "Gary" mentioned above, although that isn't my name.  But 
I'm happy to take on that name in this discussion.)

\start
Date: Thu, 22 May 2014 15:20:39 -0700 (PDT)
From: Marshall Abrams
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication

On Thursday, May 22, 2014 4:05:58 PM UTC-5, Gary Johnson wrote:
>
> Hi folks,
>
>   I suspect I'm the Gary that Tim thought he was referring to since I've 
> posted on several of his other LP-related threads (though not this one 
> until now). 
>

I cede the name "Gary" to Gary.
 

>   But really, at the end of the day, I'm just getting tired of listening 
> to people razzing on LP for the reasons listed above. 
>

For my part, I have never intended to criticize LP per se.  When it sounds 
as if someone is arguing that everyone should use LP all the time (or 
something similar), I sometimes object. 

\start
Date: Thu, 22 May 2014 16:48:56 -0700 (PDT)
From: Gary Johnson
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication

On Thursday, May 22, 2014 6:20:39 PM UTC-4, Mars0i wrote:
>
> On Thursday, May 22, 2014 4:05:58 PM UTC-5, Gary Johnson wrote:
>>
>> Hi folks,
>>
>>   I suspect I'm the Gary that Tim thought he was referring to since I've 
>> posted on several of his other LP-related threads (though not this one 
>> until now). 
>>
>
> I cede the name "Gary" to Gary.
>

No worries. You can be Gary too if you'd like. It's a passable name, all 
things considered. ;-)
 

>  
>
>>   But really, at the end of the day, I'm just getting tired of listening 
>> to people razzing on LP for the reasons listed above. 
>>
>
> For my part, I have never intended to criticize LP per se.  When it sounds 
> as if someone is arguing that everyone should use LP all the time (or 
> something similar), I sometimes object. 
>

Hey, point taken. I'm certainly not out to force LP on anyone. I'm just 
here to soak up advice from the folks who have been using it for awhile. 
I'm happy keeping the kool-aid to myself, so to speak. :-P

\start
Date: Thu, 22 May 2014 14:05:58 -0700 (PDT)
From: Gary Johnson
To: list
Subject: Re: [Axiom-developer] Heidegger, literate programming, and communication

Hi folks,

  I suspect I'm the Gary that Tim thought he was referring to since I've 
posted on several of his other LP-related threads (though not this one 
until now). I'm reading along and enjoying the back and forth as usual, but 
I'm sorry to say that I don't have much to add to this philosophical 
swordfight.

  As I've stated on other threads, I find LP quite useful to me, both in 
helping me remember later what my old code does (and WHY I wrote it that 
way in the first place) as well as helping me to write clearer and more 
parsimonious code in the first place (since I don't want to document a 
crazy web of unnecessary complexity if I can avoid it). All in all, my 
personal LP journey has been an interesting and reasonably productive one. 
And of course, using an expressive functional language like Clojure does 
allow me to keep my code snippets shorter and more isolated from one 
another. All good things for LP as well.

  I know that Tim likes to poke the mailing list occasionally and remind 
people that LP is the bee's knees and that they should really get on board 
with it. I also know that without fail one or more folks will quickly 
respond that LP doesn't provide enough value above docstrings, inline 
comments, autogenerated API docs, and the occasional blog post to invest 
the necessary time in developing new LP-mindful workflows. And, of course, 
someone will inevitably chime in with the rally cry "clear code doesn't 
need documentation".

  I understand that really embracing LP does require relearning how to 
program in several fundamental respects, AND it makes it quite difficult to 
use many of the developer tools many folks in the Clojure community have 
come to rely on. This makes the task appear somewhere between challenging 
and onerous to many programmers (or so I would imagine from following Tim's 
threads over the past year). However, (speaking only for myself here) I 
think the maintenance benefits often outweigh the upfront investment for 
any piece of software I intend to keep around for more than a few months. 
So for me, it's a net good. For some folks it's not. I get that. Enough 
said.

  But really, at the end of the day, I'm just getting tired of listening to 
people razzing on LP for the reasons listed above. There ARE good tools out 
there for doing this kind of programming. People just have to invest time 
and energy into learning them. I regularly cite Emacs' Org-mode as 
providing most everything you might need to comfortably create LP programs 
without even writing one line of LaTeX or XML (if you're allergic to those 
languages). Obviously, as Tim points out, it's an almost trivial assignment 
to roll your own tangle and weave scripts in whatever language you like 
(and I've tried that route too). So guys, if you don't like the ideas 
behind LP or just feel like it is too much of a hassle to use, then I 
completely understand that you don't want to use it. But could we maybe 
call a truce on this mailing list on the topic?

  Perhaps instead of constantly being pulled into philosophical arguments, 
those of us who actually do enjoy exploring LP could then use this forum to 
discuss amongst ourselves what tools or references we are finding useful in 
our journey. Clearly some folks (Gregg included) are churning out some 
pretty neat looking tools to make LP easier to do in the Clojure world. I 
for one would love to see more lively discussion around that and not feel 
like we're just bear-baiting whenever we mention the forbidden paradigm of 
Literate Programming.

  My 2c,
    ~ (the actual) Gary

\start
Date: Mon, 26 May 2014 04:00:50 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] Computational Mathematics, proofs, and correctness
Cc: Douglas Troeger

One of Axiom's project goals involves proofs of the computational
mathematics.

In plan, but not yet attacked, is the question of proving Axiom.
Axiom claims to be "computational mathematics", after all.

This raises a lot of thought bubbles, but most interesting to me at
the moment is what the goal means. There seems to be several 
interpretations and my shower committee (i.e. what I mutter to myself
about in the shower) seems unfocused. The top level question is:

   What would it mean to prove Axiom correct?

The first interpretation is computational.

The second interpretation is mathematical.

The third interpretation is both computational and mathematical.

Consider these in order. From a computational point of view Axiom is a
big lisp program. It implements a domain specific language called Spad
which compiles to lisp programs. ACL2 [0] is ideal for proving
programs at this level. ACL2 is also a lisp program and could easily be
co-resident with Axiom in a lisp image. Models can be defined and
proved to have certain properties. The lisp code could be decorated
with theorems and lemmas. This would make it possible to bring much
more rigor to the implementation. It provides an opportunity to define
a model for interpreting and compiling Spad which can be used to check
the implementation.

>From a mathematical point of view, Axiom is an implementation of
abstract-algebra-like categories and domains. One could consider
decorating the Spad algebra code with axioms (e.g. the abelian
group axioms) and theorems. COQ [1] seems ideal for proving Spad
code at some level of abstraction. Of course, Spad's view of
algebra differs somewhat from the abstract algebra scaffold.
Proving an algorithm (e.g. finding primes) over all possible
domains is really a non-trivial task.

>From a computational and mathematical point of view, there is what
I call the "kittens" problem, as in, "it is kittens all the way down"
(cause, yaknow, the internet doesn't like turtles). What does it mean
to prove something in Axiom? Is doesn't seem sufficient to prove that
the interpreter/compiler provide a correct translation of Spad. Nor
does it seem sufficient to prove that a Spad domain properly preserves
the commutative property.

What I'd like to achieve (and, given that we are just starting toward
a 30 year horizon we have plenty of time), is some confidence that
Axiom programs can be used with some reasonable degree of assurance
that it does what it says on the tin. At the moment, computational
mathematics seems to "float" on nothing. 

I am deeply unhappy with the current state of the art. The current
state makes it hard for a computer scientist to see where the
interpreter/compiler needs work. The current state makes it hard for a
mathematician to see where integration needs work. That we are decades
into the collision of mathematics and computers yet have no standards
of proof is, to my mind, unacceptable.

The computer scientist side of me wants some form of non-computational
model of the interpreter/compiler. The mathematician side of me wants
some convergence of the algebra and mathematics. 

We can do better. In fact, any attempt at all would be better.
Even if nothing were formally proved I'm sure the side-effect would
be a better, more trustworthy Axiom, which is a worthwhile goal.

Nobody wants their "Ph.D recalled" due to a bug in Axiom. :-)

Excelsior!
Tim Daly

[0] Kaufmann, Matt; Moore, J Strother
    ACL2 Version 6.4
    http://www.cs.utexas.edu/~moore/acl2

[1] various
    The Coq Proof Assistant
    http://coq.inria.fr

\start
Date: Mon, 26 May 2014 15:28:12 +0100
From: Martin Baker
To: list
Subject: Re: [Axiom-developer] Computational Mathematics, proofs, and correctness

Tim,

Yes, I think it would be really good if Axiom could live up to its name 
and include axioms.

It seems to me that categories in Axiom are mostly about function 
signatures (I know I'm vastly oversimplifying here) but they would be 
more like the mathematical concepts they represent if they included axioms?

Are you talking about two different types of capability here:
* Proof Assistants like 'Coq' or 'Isabelle'.
* Algebraic Specification Languages like 'CASL'.
Does ACL2 fit into this distinction?

So I'm thinking that proof assistance are based on rules and driven by 
human input and algebraic Specification Languages are based on axioms 
and provide some level of automatic checking, although I guess there is 
some overlap?

I get the impression that Axiomatic systems are problematic in that a 
single error allows you to prove anything (true=false) and, as you have 
pointed out to me, rule based systems are difficult to debug.

Even so, I think that the addition of axioms into categories would be a 
big benefit, even it it was only initially used for human readers and 
some automated checking.

The choice of what rules to call axioms may be arbitrary but there are 
all sorts of choices that have to be made when supporting an algebra, 
like notation and which algorithm to use, which don't follow 
automatically from the mathematics.

> What would it mean to prove Axiom correct?

I get the impression that, at some level a computer program is only an 
approximation to mathematics (float approximates to reals and so on). 
Issues with proving code(algorithms) - 'halting problem'. Despite these 
limits to a complete proof of the whole program, there is a lot that can 
be done at a higher level if axioms were included in the program.

So I think this sort of capability would be really good, I'm just too 
impatient to wait 30 years.

\start
Date: Mon, 26 May 2014 18:26:34 +0200 (CEST)
From: Waldek Hebisch
To: list
Subject: Re: [Axiom-developer] Computational Mathematics, proofs, and correctness

Tim Daly wrote:
> 
> One of Axiom's project goals involves proofs of the computational
> mathematics.
> 
> In plan, but not yet attacked, is the question of proving Axiom.
> Axiom claims to be "computational mathematics", after all.
> 
> This raises a lot of thought bubbles, but most interesting to me at
> the moment is what the goal means. There seems to be several 
> interpretations and my shower committee (i.e. what I mutter to myself
> about in the shower) seems unfocused. The top level question is:
> 
>    What would it mean to prove Axiom correct?


That is pretty clear: there is algebra, there is interpreter there is
compiler.  For algebra one needs to specify what each function is
supposed to do and prove it.  There are well-known notations for
specifications and proofs, for example Hoare triples.  Proof rules
depend on language used, but from point of view of proofs Spad is
quite conventianal imperative language, with a little syntatic sugar
for few constructs, so writing proof rules for Spad is not hard.  Spad
supports rich values (arrays, lists, functions, types), so axiom for
values will require work.  Then one needs to prove compiler correct,
for this one needs specify meaning of output.  If the output is Lisp,
we need proof rules for Lisp, and we need to prove that proof rules
used for algebra are satisfied.  Finally we need some specification
for interpreter and we need to prove that interpreter satisfies this
specification.

The real question is how to do this.  Several years ago my student did
"by hand" a proof in Hoare logic of a simple 20 line long program.
The proof is 20 pages long.  The proof is rather detailed, but he
consided some facts as known and some readers probably would ask
questions demanding more details.  While this is small sample it
clearly shows that doing proofs by hand is huge task and we are
unlikely to ever have needed resources.  Obvious answer lies in
automation.  But even with automation this is still large task: the L4
operation system kernel is clained to be proved correct with
mechanically verifed proof.  But that required about 8 lines of proof
annotations per line of executable code.  For me this is still too big
to even start.  IMO proving correctness will be reasible with better
proof assistants.  And there are signs that such assistants may appear
pretty soon (there was large progress in last few years).

Let me repeat: it is not a question of what a proof is.  Already
Turing around 1946 gave apropriate notion of proof.  The question is
how.

BTW: Some people want proof to have be "certain" that progam works.
Of course to get valid conclusion we would have to prove lower layers.
I consider this out of scope, but you may wish to prove that Lisp
implementation is correct in terms of machine instructions and that
logic of processor correctly implements machine level.  We would also
like to have some assurance that gates do what they are supposed to
do.  Now, correctenss of gates is physics, not math.  Correctness of
processor is rather hard to establish, because internal design is kept
secret.  But above what proof means is clear and methods are known --
it is "only" problem of huge effort needed for such work.

\start
Date: Mon, 26 May 2014 14:15:25 -0500
From: Tim Daly
To: Waldek Hebisch
Subject: [Axiom-developer] Computational Mathematics, proofs, and correctness

Waldek,

>The real question is how to do this.  Several years ago
>my student did "by hand" a proof in Hoare logic of a simple 20
>line long program.  The proof is 20 pages long.  The proof
>is rather detailed, but he consided some facts as known
>and some readers probably would ask questions demanding
>more details.

Was this proof published anywhere? Do you have a URL?

\start
Date: Tue, 27 May 2014 10:08:23 +0800
From: Jia Zhao Cong
To: list
Subject: Re: [Axiom-developer] Computational Mathematics, proofs, and correctness

I have some experience with ACL2, ACL2 uses a very small subset
of common lisp, there are no side effects and no higher order
functions, although Axiom is written in a pretty small subset of CL, it
will be very difficult or require unimaginable mount of work to prove
"the Spad compiler is correct" (this Axiom implementation of Spad
language compiler agrees with Spad language specification).

As for the second interpretation, I am not familiar with Coq. I can
only mention about PVS [1], a common lisp theorem prover but
unlike ACL2 which is first-order and weak typing, PVS and Coq are
high-order and strong typing. But I am not familiar with PVS either.

[1] PVS   http://pvs.csl.sri.com/

\start
Date: Mon, 26 May 2014 22:30:12 -0500
From: Tim Daly
To: Jia Zhao Cong
Subject: [Axiom-developer] PVS

Thanks. I had not heard of PVS but I will look into it.

I have used ACL2 in the distant past and will have to get up
to speed on it again. I've downloaded and built the latest version.

I know that ACL2 is not capable of handling a Spad compiler but one
has to start somewhere. The important point, in my mind, is the focus
on some sort of proof in the long term.  We really need to have a
higher standard for computational mathematics, and, as they say,
"If not us, who? If not now, when?".

Matt Kaufmann and J Moore have always been quite helpful in the
past. I suspect they would be interested in any work we do in
this area.

\start
Date: Mon, 26 May 2014 22:39:41 -0500
From: Tim Daly
To: Waldek Hebisch
Subject: Re: [Axiom-developer] Computational Mathematics, proofs, and correctness

>This was "Master Thesis", unpublished and in Polish.  This
>is work that students are supposed to do to get finish
>their study and get Master degree.  Most of the work
>presents material from literature, the proof is original.
>I can send you a .ps file if you want.

My command of English is marginal at best. I'm sure that a
thesis written in Polish would exceed my abilities. Thanks
anyway. 

If your student referenced any interesting work in English
in the bibliography I'd appreciate the reference. I think I
need to research a range of existing work.

\start
Date: Mon, 26 May 2014 22:47:10 -0500
From: Tim Daly
To: list
Subject: Re: [Axiom-developer] Computational Mathematics, proofs, and correctness

  "The society of scientists, the community of scientists, has
   this advantage, that from the moment we enter it, we all know
   that fifty years from now, most of the things we learned here
   will turn out not to have been quite right."

  -- Jacob Bronowski, Silliman lectures, Yale 1967

\start
Date: Tue, 27 May 2014 12:38:51 -0500
From: daly@axiom-developer.org
To: Waldek Hebisch
Subject: Re: [Axiom-developer] Computational Mathematics, proofs, and correctness

Waldek,

Thanks for the references.
Oddly, many of them are from my graduate course :-)

\start
Date: Fri, 30 May 2014 00:01:43 -0500
From: Tim Daly
To: Lawrence Bottorff
Subject: Re: [Axiom-developer] Books versus "Tunneling"

Lawrence,

I copied portions of your email to the mailing list along with my
reply. I hope you don't mind.

>I just watched your talk "Literate Programming in the Large" on YouTube.
>I've been investigating literate programming for a bit now, and I've come
>up with a term for non-literate programming: I call it "tunneling." Imagine
>you're a programmer doing your regular programming thing, writing code all
>the live-long day -- and not doing it in any sort of literate way. I say
>that's the same as some mole or miner digging a tunnel. Either the tunnel
>collapses right behind the mindless digger diggings -- or the software is
>actually used and the tunnel doesn't collapse right away, i.e., there's
>traffic in the tunnel. For example, Windows XP is a big, wide tunnel . . .
>that is now beginning to rapidly collapse. Soon enough there will maybe be
>a depression in the ground. "XP was down there." So yes, eventually all
>non-literate software is just so much tunneling that eventually collapses.
>You might argue that "open source" software is not such a tunnel. Maybe.
>But who reads code besides a very rare few? And like you said in your talk,
>code is notoriously difficult to fathom, especially if some "153" crops up.

Actually, you're the second quote on Axiom's documentation page. See
http://axiom-developer.org/axiom-website/documentation.html

>A well-written book, on the other hand, is at the very least a dialogue
>with yourself. Consider what I've done in the past: SQL database. I
>typically would crank around with SQL snippets until I got the database
>where I wanted it, or some output/report generated. But all the steps I had
>taken were lost! Better it would have been if I had been typing an "SQL
>blog" with the SQL code embedded in the text where I describe my process.
>"Dear diary. . ."

I don't know if a diary is the best analogy. The best book I've seen
so far is Pharr and Humphreys' "Physically Based Rendering". It contains
all the source code, properly explains the theory, and is exceptionally
well cross-referenced and indexed. The BOOK won an academy award. If 
you haven't seen it, buy it. Believe me, you'll be amazed.

I have to say, they have really "raised the bar" of what I expect a
good literate program to be. They explain the theory, show the math,
and have numerous diagrams. Axiom has a new standard of excellence.

If Axiom were documented as well as the Pharr/Humphreys book I am
certain that it would be used to teach computational mathematics at
both undergraduate and graduate levels. I can even see a sub-department
of "computational mathematics". There is, of course, the minor detail
of actually documenting the system :-)

Greg Humphreys, one of the authors, and Paul C. Agnostopoulos, the
author of zzTek, which is the tool used, have both given me the
tooling they used to create the book. I hope to use at least some of
it in Axiom. Paul formats books professionally (windfall.com).






>I so much agree with you about literate programming. I don't get much
>buy-in; many think I'm just a crackpot. Alas, but I think it's the real
>wave of the future. A book is meant to be read. Coding is just tunneling.
>Think of all the ga-zillions of lines of code that is buried in all those
>tunnels!

Yeah. There is a saying in physics. "New theories are accepted once the
previous generation dies". John Kitchin at CMU is teaching the new
generation to write literate programs. Once everyone over 30 dies we
can flush all the non-literate, abandoned piles of code in github,
sourceforge, savannah, etc. and get on with the business of
communication.

At least that's my theory and I'm sticking to it :-)





>Two questions: Have you ever seen the outline style Buckminster Fuller used
>in "Synergetics?" Each outline point makes fairly self-contained statement.
>Here's the table of contents:

No, I haven't seen that book. I'll put it on the queue. Thanks.





>And, have you seen Emacs org-mode? It has a built-in literate capability.

I sat in on Kitchin's class where he is teaching students using literate
programming. He is using org-mode. 

It was really interesting in that NOBODY was taking notes. Not a single
pen or piece of paper anywhere. No typing on their laptops. John taught
from his emacs buffer, displayed on an overhead. Everything he taught
was in the buffer. He could execute code, update tables, show graphs.
He could edit changes into the document based on student questions.

At the end of class, all students had the latest set of notes and
all of the executable code already on their laptops. He is working to
spread this kind of teaching across all of the compsci, math, chemE,
and other departments. Frankly, I think it changes the game but I'm
already a convert.



>Also, I'm using Ubuntu and I see there is an "axiom" and an "open-axiom" in
>the package manager. Which do I want? Or should I just grab it from the
>site?

Axiom is this project. Executables are available at 
http://axiom-developer.org/axiom-website/download.html

If you want to compile and/or develop Axiom system code there are
instructions of which packages to apt-get.

\start
Date: Fri, 30 May 2014 12:12:29 -0500
From: Tim Daly
To: list
Subject: [Axiom-developer] Axiom and proofs

I picked up two books that seem to be useful in the task of trying
to prove at least one algorithm in Axiom "correct", for some 
philosophical version of correct.

I'd really like to show an automated proof of Axiom's GCD algorithm.
Pointers to published work on GCD proofs would be really useful.

Yves and Pierre [0] has a whole chapter on "Infinite Objects and
Proofs" with a section on co-inductive types (streams, lazy lists,
lazy binary trees).

Chandy and Misra [1] has a section on prime number generation by sieving.

Suggestions of other reading material is most welcome.

[0] Bertot, Yves; Casteran, Pierre
    "Interactive Theorem Proving and Program Development"
    ISBN 3-540-20854-2

[1] Chandy, Mani ; Misra, Jayadev
    "Parallel Program Design"
    ISBN 0-201-05866-9


