Re: [Axiom-developer] browser front end, statement of plans and progress

[Martin Rubey]

Dear Tim,

address@hidden writes:

> Ralf is concerned that we would not have API documentation, which is quite
> reasonable. We extract the existing documentation automatically so I don't
> believe there is any difference caused by displaying this documentation in a
> standard browser rather than hyperdoc. The documentation strings are
> extracted by the compiler and should be available from the database files or
> the running image if we so desire.

If this is what you intend, great. I did mention that I'd hope everything was a
big misunderstanding on my part.

> I agree that we ought to carefully study the API documentation
> issue. Possibly we could adopt a new syntax similar to javadoc that allows us
> to use existing tools. Failing that we could probably dynamically generate
> API documentation at compile time that would be properly hyperlinked and easy
> to display.

So, what's wrong with the conventions used by ALLPROSE (they come from AlDoc
and AldorDoc...) ? Furthermore, they are quite close to HyperTeX... What more
can you want? You can put everything (graphics, videos, text) in the api you
like, of course. LaTeX is quite flexible.

> "Hyperdoc uses essentially _the same_ TeX notation as the book..."  It does?
> The book contains nothing about pages or buttons.  It says nothing about the
> requirements for free references to prior values.

I'd be surprised if you could manage to create a (paper-printed copy of a) book
that contains buttons :-) But why shouldn't we use the same "language" for both
the browser and the book. I think, that's the spirit of HyperTeX. By the way,
MuPAD uses quite a similar philosophy.

> Martin writes: "...Ralf has written an excellent environment for literate
> programs...". Yes, he showed it to me in France and I'm really quite
> impressed. I'm not sure what this has to do with the front-end issues to
> Axiom, however.

I'm repeatedly saying that I only want *one* set of conventions for writing
documentation and code. And I'm absolutely convinced that this should be LaTeX
like. Ralf has shown that this can be done, in a very user friendly manner.

> "Some time ago I asked you whether asq could be used to fetch the
> documentation information also dynamically...I faintly remember you answered
> but I never heard any further response."  I put up a web page that used asq
> to provide access to database information from the web [...]

But that's not what I meant with "dynamic". I meant (and I hope I explained)
that I want asq or (any hyperdoc replacement) be able to use freshly generated
databases. I like your web page very very much, I think it is a great proof of
concept. 

> "...I cannot find any sane reason to give up these concepts from ALLPROSE and
> Hyperdoc..."? Somehow you see using a browser to access information from a
> back end as implying that we have to give up our programming tools. I'm not
> sure why these two things seem to be related. The fact that Axiom uses a
> different front end should have no effect on what tools you use to write
> programs.

Great. I was only afraid that you want me to write api documentation - possible
also other documentation, I did not understand that part - in a language other
than LaTeX, or with a set of conventions different from those used for the rest
of the documentation. If this is not the case, I'm entirely happy.

I think it's time to set a price again. I'll pay 100$ anyone who writes a new,
or modifies an existing program, that displays the documentation of a +++
environment (and only this bit of documentation) as generated by ALLPROSE, on
demand, i.e., using a web interface similar to that Tim provided.

To get started, do the following

----------------------------------------------------------------------

svn co svn://svn.risc.uni-linz.ac.at/hemmecke/combinat/trunk

cd combinat/trunk/combinat

notangle -t8 Makefile.nw > Makefile

make VARIANTSTOBUILD=axiom

cd lib

for f in $(ar t libcombinatax.al); do ar x libcombinatax.al $f; done
for f in $(ar t libcombinatax.al); do echo ")lib $f" >> combinat.input; done

cd ../src

axiom

-- now everything of combinat is available. To generate a libdb.text say

)se co args "-O -Fasy -Fao -Flsp -laxiom -Mno-AXL_W_WillObsolete -DAxiom -Y 
$AXIOM/algebra -i ../include"

)co csseries
----------------------------------------------------------------------
(very likely, there is an easier way to generate the libdb file.)

To explain the process a bit: (Ralf, please correct me if I'm wrong)

  make VARIANTSTOBUILD=axiom

extracts using noweb documentation and code from the source files, for example
series.as.nw. All of the code and the api description (i.e., everything between
\begin{+++} ... \end{+++} ) is put into a file csseries.as.

")co csseries" is one way to extract the +++ strings and write them into
libdb.text.

The best thing would be, of course, if one could simply call tex4ht on the
individual +++ strings. One would have to write a suitable LaTeX preamble, of
course, that \usepackages the appropriate style files. However, I do not know
how hyperlinking will work then. (In fact, I don't even understand hyperlinking
within ALLPROSE, and Ralf begs me to read the documentation since a few
months...)

Maybe it also makes sense to run a preprocessor over the literate
program. I.e., to modify ALLPROSE so that preprocecessed LaTeX (for example
html) is put into a database. But I would like the other solution better.

It would already be a great thing if doc could be displayed without
hyperlinks. That shouldn't be too hard, I believe.

> Is tex4ht the right tool? I have no idea as I have not tried it.

PLEASE try it. It produces just wonderful results. I admit, though, that I
myself found it difficult to set up. However, I'm sure you'll get help if you
ask for it.

> Supposedly noweb will also generate html. 

What? I thought noweb simply extracts code and documentation, thus preparing
for LaTeX / TeX and Aldor / SPAD / C / Perl / whatever ?



Martin