[Axiom-developer] Executed Examples in documentation ---> Testsuite

[Ralf Hemmecke]

Dear Tim,

> there is a new extension to the syntax to add examples. Essentially
> any line that begins with ++E will be output as Example documentation
> to the display command. So the coerce from Tuple now reads:
>
>    coerce: PrimitiveArray S -> %
>     ++ coerce(a) makes a tuple from primitive array a
>     ++
>     ++E t1:PrimitiveArray(Integer):= [i for i in 1..10]
>     ++E t2:=coerce(t1)$Tuple(Integer)

That seems to be common nowadays. But what if for some reason the output 
is wrong? Then the user sees that in the documentation. So, personally, 
I would rather add another tag like ++R, for example, that lists the 
explicit (expected) output.

Why I think ++R is a good idea, is that the ++E and ++R could be used
for the TestSuite.

You could also move some checking time to the users machine. At the time 
the documentation is rendered, the commands in ++E are executed and 
compared internally with the ++R stuff.
Since execution might take some time, first show the ++R output and 
spawn a background process that compares the output of ++E with ++R.
If that is equal, everything is fine. If it is different. That is a bug. 
So notify the user with all the information (about his system) that s/he 
should send to a bugtracker.

Just some strange ideas...

Ralf