[Axiom-developer] Re: Requiring LaTeX

[C Y]

--- root <address@hidden> wrote:

> \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 we take that approach, then it is just as important to bundle TeX in
some form along with Axiom as it is to bundle GCL.  Particularly on
Windows, where an installation of TeX probably does not already exist.
 
> I get the distinct impression that no-one has really made the
> transition to literate programming. 

That may be true, in some sense - if you mean going from "making a
document that describes a design and then integrating the code into
that design" to writing a document which happens to have some passages
in source code.  I liken it to writing a document containing both
English and Ancient Egyptian - if you don't speak Ancient Egyptian
fluently, you're going to wind up either writing out the Egyptian and
then going back and writing the English paper (because they require
different types of concentration) or writing the English paper and then
creating the Ancient Egyptian to support what you need  (the latter
approach is the one I am planning for the units package).  Obviously it
is iterative for both languages but eventually you arrive at something
reasonable.

I think, Tim, you are capable of writing fluently in both English and
programming languages - in both cases they are merely ways in which you
"speak" your ideas.  To me at least it is not (yet) this natural - if
I'm translating an idea into code I have to stop and figure out how to
do it, with a lot of trial and error.  I can't do that and write at the
same time, as yet - for me it is two different kinds of concentration.
 
> Do you write the documentation before and during program development 
> or are you coding and then "adding the documentation"? 

The former, more or less, although I will likely change both code and
document significantly before this process is done.  If I hit a sticky
point of coding that requires an hour of banging my head into new
shapes I don't bother writing latex until I can say something
intelligent.  This may be because I am not a skilled coder - when it
comes more "naturally" to me perhaps I will become better at the "write
a document some of which happens to be in the Aldor language" style of
working.

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

The latter, or as I build a document I will notangle it to get the
support structure, and then fool around with the next piece until it
makes sense, then go back and embed it to have it become part of the
"support" structure and main document.

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

Hopefully the two are not mutually exclusive.  I am in the somewhat
precarious position of trying to write a high quality literate program
without having at the beginning of the process either the academic
knowledge or the programming knowledge to achieve the goal at the
outset.  Ralf and William have both been an immeasurable help in
improving that situation, but many of the issues I have to figure out
are due to my not yet being "fluent" in the subjects of Aldor, Axiom,
and units/dimensions/types.  It would be like including someone
learning English for the first time in a document attempting to do a
literary review of a book - you want the review to be about the book,
not about the author of the review learning how to write the review.

> 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?

Heh - I guess since my pamphlet file is so far all latex code it's a
bit of a moot point.  On the Emacs mode pamphlet, it was sort of a mix.

> 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)

That part I do understand.  I order the ideas for humans and then put
things in the correct order at the end.

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

I agree.  That methodology, however, requires a fluency level in
programming which will require some time for me to achieve.

> 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.

:-).  Oh, no question there.  But before I consider myself qualified to
write a document about a program, I want to have something that works. 
If I don't have running code for an idea I will usually describe the
idea, and then grab the programming tools and beat my head against it
until something works.  THEN I (might) be qualified to start talking
about the how and why of making the idea into a coded algorithm.  

I may change some of this once I am comfortable enough to do "real
work" in Aldor.

> 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.

I wasn't programming 15 years ago, but I agree this is true.

> 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.

Definitely agree.  We have reinvented so many wheels so many times it
borders on crazy.

> 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.

OK.  I don't want to hammer too hard on this point Tim, but for things
like the lisp and boot code in the interperter I think there is already
so little understanding of that code that the changes required to make
it run on ANSI, documented or not, are going to do very little to
change the "live" status of that code in a literate sense.  Your work
on bookvol5 is what WILL change it, and eventually a re-write which
cleans up and makes known the issues involved with the interperter
design, but the practical benefits of ANSI compatible changes are
mostly orthogonal to the goal of a comprehensible literate interperter.
 Obviously the BEST idea is to make the interperter into a literate
program, but my one run at that pretty much convinced me that we should
just start at an ideas level, design what the interperter SHOULD be,
and then use the existing code where applicable as either a guide or
copied over to create the new interperter.  Since that task is down the
road on the current plan, I would like to see a minimal ANSI compatible
subset change made (with or without comments, since the codebase is
already too dense for many of us to understand at the moment anyway and
thus we don't DECREASE comprehensibility any) to allow us to make use
of tools being created for Lisp today.  

I understand this doesn't advance the goal of making Axiom truly
literate and so may be counter to the goals of the project, I'm just
presenting (as well as I can) the argument for a few short term, quick,
and immediate steps to improve immediate problems like being able to
run only on GCL, which doesn't support things like McCLIM, cffi, Slime
(maybe?), and other tools used by most modern lisp programmers today. 
If they are not convincing then that's OK too.

> 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.

Agreed.

> 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?

But we don't require the user to install GCL - Axiom deliberately
includes it in the tree as of now.  We DO require an external install
of LaTeX - is the plan to bundle some subset of TeX and LaTeX as well? 
(I can see this if we have a cl-typesetting type solution since that
typesetting logic can also be used in GUI situations as well as
literate coding, but I don't think TeX was designed for this type of
situation.)

> 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.

OK.  But for those of us who are not qualified to comment on issues
related to those particular questions (which are quite non-trivial as I
understand it, but that's about all I know about it) how much
background should be documented in Axiom?  The idea of building
software itself from human readable languages into binaries?  The
reasons for platform differences?  The issues of compiling expressions
to Ultrasparc vs AMD64 binary code, and the consequences of the design
differences?

Personally, I think those types of questions (indeed most related to
building code) should be documented at a system-wide level as literate
programs (literate autoconf and automake) rather than be the
responsibility of Axiom.  I find this an attractive idea (which is why
things like the literate lisp implementation and things like
Movitz/CADR lisp machine code interest me) but personally I think there
has to be a point beyond which Axiom shouldn't have to go because Axiom
is a CAS, not an operating system.  I don't know for sure what the line
is, but (for example) I would rather leave the extremely messy issues
of building on different platforms to the autoconf/automake experts. 
Would it be nice of autoconf and automake were literate programs,
describing all the issues and how to deal with them?  Yes.  Is this
Axiom's responsibility?  I don't know.

> 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.

Standards are themselves a moving target, (hopefully) improved by
increasing knowledge and skill on the part of the people creating them.

> 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.

It is extremely unfortunate that these platform specific issues are
there to cause us trouble.  I think the idea of autoconf and automake
is to isolate programs from the lower level cross-platform issues, and
instead allow the program to focus on writing their own code, but I
confess I don't know enough about it to know for sure.  Gaby?

> 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).

That's reasonable.

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

I have been and am, but I make one final observation:

"To write literature with a language one must first be fluent in it."

Fluency in programming languages, like human languages, takes time and
practice.  Perhaps I should not be attempting any serious Axiom work
until I first achieve fluency.

Cheers,
CY

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com