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

[root]

>But you remember there were pages in hyperdoc that could be explicitly 
>executed by pressing a button. So if that is connected to ++E and ++R 
>that would not be a problem, because the user asked for it. Well of 
>course, you must check that the user did not modify the ++E stuff before 
>you compare with ++R.

I have a "layered" approach to the documentation depending on how
the user is approaching the problem of finding an answer.



Suppose the user is at the command prompt and needs function help:

In the algebra the ++E syntax is only used at the moment to provide
example output for the
  )display operation 
command. Your excellent suggestion integrates that into the testing.
Thus anything the user sees should have passed test in build.



Suppose the user is at the command prompt and needs domain help:

Some algebra files now have )help documentation that gets automatically
extracted and added to the system. So if a user wants help on domains
rather than operations then the 
   )help domain
ascii text documentation is available. These pages are extracted and
tested now as part of the standard build. Thus anything the user sees
should have passed test in build.


Suppose the user is in hyperdoc or firefox:


If the user is in hyperdoc then the usual tests are applied. This is
no longer automated (although it used to be at IBM). However, hyperdoc
pages are rarely ever changed as far as I can tell. Maybe the new PDF
format will make them easier to understand and change.

If the user is in Firefox then the pages are planned to be automatically
extracted and tested but this does not yet exist. There is still a large
buildout of new functionality. 

In either case I could modify the extraction function to elide the
++E/++R lines so testing can be inlined in the pages.




Suppose the user is trying to do a classroom task:

The .input files are used for testing at the moment but the plan is to
expand them into documentation for a particular problem in a
particular domain, as a whitepaper on some subject like doing Binary
Decision Diagrams (in process). These are intended to be more tutorial
in nature. Professors interested in teaching can create tutorials and
have them automatically tested.  Clearly the automated testing syntax
will survive here.




Suppose the user is trying to understand how it all works:

The final layer of documentation is the .pamphlet file PDFs which
will eventually contain all of the source code.




I could take your suggestion for the )display ++E/++R syntax and build
it into the PDF machinery. Currently the hyperdoc pages are taken
directly from the .pamphlet file and soon the firefox html pages will
also come directly from the .pamphlet file. I can modify the extraction
process to filter out the ++E/++R testing syntax lines automatically.
Then they do not show up in user displays but are automatically tested.

Tim