Re: [Axiom-developer] Re: Ping: case insensitive filesystems

[C Y]

Waldek Hebisch wrote:

> I think we have conflicting paradigms here.  I belive that history
> has place in documentation only if it explains _significant_ aspect
> of current system.  In case of current filename change past status
> really tells you nothing about new system.

(insert 'mouth 'foot)

At the risk of getting into trouble, I must agree with Waldek that there
needs to be a distinction between documentation of the system which
describes its workings, and documentation which describes its evolution.
(If that is a fair characterization.)

Changelogs are, AFAICS, what we make them.  If we are planning to remove
or restructure something and want to explain why we are shifting from
the old to the new, that seems to me like a Changelog type of entry.  If
normal changelogs are too brief for what we are after and don't
highlight exact changes, why not create a changelog format that does
what we want?

I have always thought that if we are making Axiom into literate
documents, they should read as such - if I am looking for the pamphlet
that describes the SPAD compiler I am interested in what it IS doing and
what it is intended to do and why, not what it did in the past before it
was fixed.  If I run into a bug I might want to check what changes were
made and why, but that is the precise purpose of a changelog - to
preserve the description of system evolution.  If we want more extensive
changelogs than are standard today, let's define what would work for us.
 However, I must agree that I wouldn't want such things cluttering up
the pamphlet.  If the job that (say, for example) PDP11 specific code
did has no modern equivalent and is no longer needed, removal and a
changelog entry should suffice.  We don't need to document why that code
was there and how it worked if it handles a problem that no longer exists.

That's why I took the approach I did with the Units paper - study the
problem domain, determine what should happen, and then make the code fit
the ideas.  When I tried a Maxima units package I did it the other way
around, and while the code does do some things I rather doubt it would
scale correctly or handle some of the more subtle questions/issues.
Admittedly there isn't working code for Axiom yet, but the eventual
result of the Unit paper approach will be much more useful.

To take another example, I would like to see us first write the
paper/book on WHAT the SPAD language definition is, WHY we want it that
way, and HOW we want it to work (compilation algorithms, compiler design
considerations, etc.).  In the process, we will probably learn how it
SHOULD be done, rather than how it is done now.  The existing code will
be very useful as a reference and some pieces might be drop in, but I
would like to see the ideas lead the code instead of the code leading
the ideas.

In such a paradigm, what the old code was doing is less important than
the question of do we have code that does the right thing?  The pamphlet
literature then is driven not by the existing code but by what the code
SHOULD be, and in that sense adding notes for the reasons for removal of
old code are beside the point of the document.  Such removals should
indeed be explained, but in the changelogs and not the document itself.
 If the changelog should reference specific files/line numbers as part
of its format that makes sense to me - perhaps there is a way to
automate that as part of the SCMs.

Anyway, my 2c.

Cheers,
CY