Re: [Axiom-developer] build-improvements and latex

[C Y]

Ralf Hemmecke wrote:
>> I think perhaps the pamplet files should interact with hyperdoc. Or
>> rather hyperdoc should be replaced with a web browser interface that
>> would integrate with the dvi/pdf files including hyperlinks between
>> them.
> 
> I am more in favour of any webbrowser than hyperdoc. Hyperdoc looks old.
> The contents is what we should care about.

Agreed.

> And then I'd like to see a
> nice help system. I think Mathematica has quite a reasonable one. It
> also links to the Mathematica book. I am not an expert in that but I
> guess, we can achieve it also in a normal webbrowser. The Eclipse
> documenation would be an example.

I think the help system is extremely important, especially in such a
complex tool as Axiom.  Linking to the book will be somewhat tricky
though - we need to think carefully about what to link to for any given
type of help request, and possibly even write documentation with such
requests in mind in order to help make it more "searchable".  Whether
this meshes well with book style documentation I am not yet sure.

> And yes, I like some features of hyperdoc. I like to click on a category
> or a domain and see its documentation and I can ask a category for all
> domains that implement this category. That is sometimes quite helpful.

Definitely agree!

> So in a replacement of hyperdoc must be as "active" as hyperdoc is now.

I don't think that's in doubt.  Once we achieve ANSI lisp compliance
there are a number of interesting things that could be attempted in this
department.  One might be to explore the idea of using Lisp based http
server tools as a general communications protocol between all front ends
- things like Uncommon Web http://common-lisp.net/project/ucw/ and
http://www.cliki.net/araneida may prove useful in that respect.  Kai and
I talked about this briefly on IRC - one option might be to use araneida
as the "gateway" part of the client-server system.  Different clients
might not care to speak html, of course, but I doubt if there is any
fundamental reason we couldn't send arbitrary data down the pipe and
have araneida farm it out to the appropriate input handler.  I still
think McCLIM offers some very intriguing potential for an Axiom
interface in such a framework.  Anyway, interesting possibilities.


> Bill, believe me, I am actually on your side. But there are a few problems.
> 
> First. I did not find Leo too attractive to me since it does not
> actually enforce an LP style.

Perhaps that could be changed?  Or is the design of the tool not
compatible with such a requirement?  I do like the idea of the tools
enforcing the literate programming paradigm - it's too easy to get
sidetracked.  (Of course, we're going to need several hour long
"training videos" on how to work with the Axiom source code, sorta like
that SLIME tutorial movie.)

> Second. Although I like this idea with different views (oh that would be
> the "crystal idea" right?) on code+documentation, it becomes harder to
> actually write the documentation so that it stays human readable. 

I do have to agree there.

> The
> question namely is: What are the smallest resonable units that can be
> moved around and included in other views. If you change the content of
> one unit, it also has influence on another "view" where this unit is used.

I think the end consequence of such a method is that we will have to
write very small, "self contained" documentation for units that will be
used multiple places, and then "plug them in" to larger components.  I'm
dubious that discrete units below the scale of an academic paper will
prove really useful, but at a minimum it should be possible to (say)
document various TeX output formatting code (let's say I add knowledge
of siunits in a unit pamphlet, and someone else adds some chemistry
specific LaTeX output methods in a chemistry pamphlet) as part of the
original pamphlet, and then use a different view to collect all of the
various TeX output methods into a single view that could produce one
document describing all TeX output methods.  In this fashion, a general
change to all TeX output routines (for a new TeX distribution, say)
could be carried out very rapidly across many distinct categories,
without risk of "missing one" due to having to look at dozens or
hundreds of individual documents to check for special TeX output routines.

It may prove that the only really useful unit is the code chunk itself,
with the views being documents into which they plug in.  But if we could
as a chunk we were editing what views (documents) it was included in,
and check each of them before we commit the change, we could at least
keep everything consistent with a high degree of confidence and convenience.

> So my current position is a bit hesitant although I like this
> "multiple-views" thing.

I think it needs exploring, which I suppose means I need to take another
good hard run at Leo.  Such a setup also means we would need to "chunk"
the whole source code pretty much at the outset, and then fit in the
pieces - correct?  That's a mean job even without adding documentation,
but I suppose it would be a benefit in any case.

Cheers,
CY