[Axiom-developer] Re: Requiring LaTeX

[root]

> I understand the desire to make literate programming part of the
> process and I agree with that goal, but in cases like the sourceforge
> compile farm I can certainly see checking the non-latex parts of the
> build on those platforms.  We aren't in the business (so far as I know)

\begin{rant}

We part company on this one.
I guess I'm alone in understanding that the Latex IS THE SOURCE.

Latex is not optional, it is not overhead, it is not waste.
If latex is not installed then axiom SHOULD NOT BUILD.

If you just want a system without source code that's fine.
But that has nothing much to do with the design and testing of
the axiom configure/make process.

I get the distinct impression that no-one has really made the
transition to literate programming. 

Do you write the documentation before and during program development 
or are you coding and then "adding the documentation"? 

Do you always notangle or do you write code and embed it later?

Are you writing for the end user and future developers
or are you programming and then explaining?

Do you create the .dvi file and xdvi it on every change
or do you call gcc/lisp directly and only look at the .dvi later?

Do you rewrite paragraphs so they flow easier, have index entries,
and are placed where they logically belong in the explanation or
do you write paragraphs around where the compiler wants the code?
(hint: if your code is in compiler order in the file you are most
likely NOT doing literate programming. Humans don't understand
design issues in compiler order)



Literate programming has almost nothing to do with latex.
It is a change in MINDSET and a change in development methodology.



Few people have had the opportunity to get their own code returned
to them after 15 years. Believe me, your "deep understanding" of
the makefiles, algebra code, etc. will be lost on you when you are
asked to explain or maintain it 15 years from now.

Code that you need to explain (and which you are no longer around
to explain) is DEAD CODE. Code written for the machine rather than
people is DEAD CODE. Don't believe me? Show me code you wrote 15
years ago that is still used and maintained by others.

Since we are only in the first 50 years of computer science and
most code dies when the company kills it or the company dies we
have not had the issue of creating live code. LIVE CODE is code
that will survive many GENERATIONS of programmers. Few examples
exist because most code dies.

Axiom cannot afford to add more dead code. It will not survive.
Open source will NOT do it. I've already had one of my open
source projects die (pinger, an SNMP client/server in Java), 
even sourceforge removed it.



After much pondering on the subject I believe that literate
programming is the only technology that promises to make code live.
It can do that because it changes the MINDSET so that programmers
write for PEOPLE, not machines.



The new makefiles should be 3/4 documentation. They should discuss
the design decisions (like separate build trees) based on today's
understanding so that when the trends change (and they will) the
next generation knows the why and how of the design. Why is it ok
to require the user to install GCL but not Latex? Why is it important
to have automatically generated makefiles? Why is it important to
use automake? How is non-linux portability addressed? What linux
assumptions are made so I know what to change for BSD? What about
getting it to run on a MAC? Windows?

We SHOULD be reading the literate makefiles like you would
peer-review a paper. That way we could correct design mistakes
and debate wording of explanations that affect code.

Unreasonable? Hardly. I've gotten a fair amount of grief over the
design of the current Makefile tree. I've been told that it is
unclear (even though the first paragraph of the top level Makefile
starts explaining the design points). I've been told it is not
'standard' even though it preceeds automake by 10 years. I've been
told that it doesn't support 'standard stanzas' (like distclean,
whatever that does). I've been told that it should use special
GNU-make features (whereas it used to use standard make and used
to build on Suns which it won't do now). I've been told that it
is a complete mess even though it follows a very small number of
design principles everywhere (stanza per file, makefile per 
subdirectory, unique echo per stanza, $SRC/$INT/$OBJ/$MNT variables,
etc.

Believe me, you're going to catch grief from the next person to
touch the makefile process. At least explain why the new process
does what it does so that you can point out where changes go against
design principles (such as the src/int/obj/mnt principles).



Above all, please try to make the transition to a literate mindset,
at least while working on Axiom code. The future demands it.

\end{rant}

Tim