Re: [Axiom-developer] Re: A modest proposal

[Stephen Wilson]

Hi Bill,

I share some of the concerns about literate programming, but I'd like
to spell out some of my thoughts.

"Bill Page" <address@hidden> writes:
> I agree with both Ralf and William Sit on this issue. Like Ralf, I
> think that I am a strong supporter of the *concept* of literate
> programming, but that the experiment in literate programming as
> defined by Tim Daly in the current Axiom open source project is (for
> the most part) a failure. And I do not think that this is simply
> because insufficient effort has been devoted to developing this part
> of the project. Or rather I should say it the other way: insufficient
> effort has be devoted to literate programming in the Axiom project
> *because* the current approach to literate programming in the project
> is a failure. I think the Knuth-style literate programming (pamphlet)
> methodology is just not suitable to the task.

> But I am not sure what to do about this. I think that already the
> Axiom project has suffered a very significant and maybe even critical
> lose of interest on the part of other possible contributors at least
> in part because of the insistence on this approach. It complicates the
> build environment and puts a extra layer between the developer and the
> system. 

The build environment is not an issue for me at all.  If there is
complication, it is due to the fact that there is no clean integration
between the tools required to both build the system and extract the
code/document bits.  This is one reason why I am excited about
asdf-literate, as it should significantly simplify the build as it
understands the model.  We need the proper tools for the job, and if
they do not yet exist, we can create them.

> It is clear that developers do not want to be reading their
> source code from a dvi viewer, two steps removed from the problem on
> which they are focused.

I dont do that myself.  I write my code as most other programmers do.
I write it and use traditional comments as a form of documentation.  I
do most of my coding in Lisp, which for the most part does not care
about things like the order of definitions.  So I can code and
document and build towards  a literate document.  Its not yet a
pamphlet, and the comments lack LaTeX markup,  but its a form of a
literate document.  It is no different than any other pice of code
written by any other programmer, except that the comments might seem a
tad verbose.

Once I have polished a file, once it is looking good and stable and Im
relatively sure it is up to snuff, It is pretty straight forward to
convert to a pamphlet.  I dont resent the need to convert the code.  I
view it as an opportunity to audit and re-check.  Something you can
never do enough of.

So the rpocess of writing a pamphlet file is something of a support
structure for writing nice code -- something you want anyways before
you even think about pushing a change out to the mainstream.

Of course, others might write literately from the beginning, but thats
not how I do it.  I would find that approach to be restrictive and
unproductive.  But thats just me.  Fortunately, nobody is telling me
how I should go about it.

Moreover, very few files in axiom are truely literate.  They are just
shells, just raw code waiting to be improved.

> And at the same time the raw pamphlet format source code is even
> more awkward and obscure than the original "illiterate" source code
> by the interposed presence of coding and documentation which is
> normally otherwise "out of the way".

This is one point to which I partially agree with.  The format is
somehow `odd' -- it is not native to the programming language in which
your writing.  However, it is fairly native to the task of writing a
document, but that is what your doing.  

Leo, from the small amount I know of it, trys to blend the two notions
of coding and documenting.  Some might prefer that way of working and
thinking.  Thats OK with me.  I feel that the main issue is having
high quality tools available.  I do pretty good with emacs, but it
certainly does not suit everyone.

> These comments (by me, Ralf, William and others) should *not* be
> construed as in anyway being against documentation or even against the
> concept of literate programming. But as Ralf says, we have to face up
> to these uncomfortable facts or risk the death of the Axiom project
> due to placing a barrier which no developer other than the one who
> originated the idea is willing to climb.

This is the main point of my post.  If you agree in principle with the
goals of the Axiom project then there is no real hill.  You can get to
the top either by doing somersaults of by taking the elevator.  The
challenge is discovering for yourself what the path of least
resistance is, what works for you.

The Axiom project, quite naturally, is based on a few fundamental
axioms.  These first principles are not the same as those found in
other projects.  But just like in science or math, when a new set of
fundamental ideas are suggested as a foundation for the discipline,
there is always resistance and criticism, years upon years of
resistance and criticism.

If you believe in the goals, if you believe in the axioms, the
philosophys, stand by them and press on.


Sincerley,
Steve