[Axiom-developer] Re: .pht file generation

[Waldek Hebisch]

> Waldek,
> 
> I'm trying to incorporate your changes to generate .pht files
> but it doesn't seem to be working. Can you take a moment to
> explain what you learned so I can understand what I might have 
> missed?
> 
> sman -noihere -paste OP.ht
> 
> just starts axiom and then hangs. I've tried to trace the process
> to understand how it works but have had no luck so far. What is
> the relationship between .ht files and .pht files? How should 
> the process work? 

Basic things:

1) You need to set up AXIOM environment variable
2) ht.db must contain information from .ht pages involved
3) there were multiple bugs which prevented the process from working:
  - gcl socket issues (the patch to sockio.lisp.pamphlet from 2006-11-03
    fixed the problem for me)
  - hyperdoc crash fixed (on 2006-11-26) by using strcpy
  - sman trying to set terminal setting on exit (caused hang when run
    in the background)
  - race in hyperdoc protocol (this one is worked around using -noihere
    and additionlly I added code to detect lost race, so that one gets
    sensible error message)

In general bugs in Axiom/sman/hyperdoc (or even in input pages) may cause
the .pht generation process to hang.

What is done: hypertex parses .ht file extracting from it Spad commands
(\spadpaste construct and similar).  Hypertex writes out extacted commands
to .input file and sends them (via sockets) to AXIOMsys for execution.
Then hypertex recevies AXIOMsys answers (again via sockets) and writes
them out to .pht file.

In short: .pht file caches Axiom output, so that hypertex can show
output of various commands without invoking AXIOMsys.

How the process works:

sman starts AXIOMsys and hypertex, giving special -k -ip options to
hypertex.  The main work is done by make_input_file_from_page routine
which calls print_paste (or print_graph_paste) for specific hunks.
Much of the work in those routines is simple bookkeeping to correctly
generate names of hunks in .pht file and generating boilerplate. 
AXIOMsys answers are read by get_spad_output routine.  At the end
hypertex send kill command to AXIOMsys.

In my experience hangs were caused by hypertex and AXIOMsys getting
out of sync.  Namely, hyperdoc protocol is mostly synchronous, meaning
that each side waits for expected answer from the other side.  However,
it seems that on errors AXIOMsys throws, and the corresponding catch is
outside protocol handler, so on error AXIOMsys may forget that it should
answer.  Also, there is race in the protocol and sman may interpret some
new request as answer to old request giving a misterous error (and
possibly hang later).

Since all communication is done via sockets any socket problems may
give errors or hangs.


-- 
                              Waldek Hebisch
address@hidden