[Axiom-developer] Re: converting sexps to XML

[Kai Kaminski]

Hi Tim and everyone!

address@hidden wrote:

> I should amplify the point made earlier given this comment:  
>
> > What I meant is that converting sexps to XML is trivial in the sense
> > that "(tag :attribute value ...)" becomes "<tag attribte="value" ...
> > </tag>". 
> >    
>
> Ummm. nope. You assume no runtime meaning; that it is just syntax so that
>
> (anchor "slashdot" "slashdot.org")
>
> ==>  <a href="slashdot.org">slashdot</a>
>
> but lisp allows runtime behaviour thus
>
> (defun getAnchor (name) (gethash name URLhash))
>
> (anchor name (getAnchor name))
>
> ==> ?
>  
That's correct. I'm only considering XML as a syntax. You could do 
something like
<defun name="getAnchor" params="name">
   <call name="gethash" params="name URLhash" />
</defun>

or something similar, although you probably wouldn't want to. You can't 
compare Lisp and XML, Lisp is a language, XML is a mark-up scheme. 
That's why I always say sexp and not Lisp, sexps are just Lisp lists 
without any semantics attached. As far as I understand, the question 
here is wether we want a simple mark-up language for the HyperDoc pages 
or a full-blown programming language somewhat geared towards hypertext 
generation (macros could certainly do so, another example is Scribe 
(http://www-sop.inria.fr/mimosa/fp/Scribe/)).
We could actually adapt Scribe to some extent (with Common Lisp 
semantics, of course).

I suggest that we first aim for consensus regarding the expressive power 
of the page description language and then discuss the possible syntax.

Of course, we could offer tags like
<link style="axiom" ref="axiom/config">Axiom configuration</link>
<link style="internet" 
ref="http://reviews.com/articles/axiom-is-great.html";>Axiom Review</link>
<link style="axiom" ref="axiom/command_line">Command line for this Axiom 
session</link>
<link type="axiom" ref="community/developer">Axiom Developer Site</link>

or other tags which process some of the input. For example the last link 
would automatically lead to axiom-developer.org or some other 
appropriate site, even if its URL changes.

> We can certainly specify an API of function calls with restricted
> meaning and requirements. This requires a balance between at least
> two mindsets for very large values of two.
>
> Mindset one is that we want to be able to generate any XML. Thus we
> want to look at the XML spec and make sure we "cover" it, that is,
> make sure we can generate the full range of XML.
>
> Mindset two is that we want to be able to reproduce the existing
> browser functionality. Thus we want to look at the range of abilities
> of the existing browser and make sure we can implement it.
>
> Mindset three is that we want to take advantage of the new browser
> abilities, like tabs, bookmarks, popups, javascript, jsMath, etc.
> and want to reflect these abilities in the API so we can write code 
> to generate them.
>
>  
Do we really need the ability to generate all kinds of XML from within a 
HyperDoc page? I thought that the HyperDoc pages would look something 
like this (in LaTeX notation):

\begin{paragraph}[editable]
 some text
\end{paragraph}

and that the back-end would transform this to something like
<p class="editable" ...>
 some text
</p>

and also insert the necessary Javascript to make sure the paragraph is 
actually editable. I'm not sure if it is really desirable to give an 
author the ability to do whatever he wants. That way we couldn't 
guarantee a somewhat standard look-and-feel. I understand that there are 
some special pages in HyperDoc, e.g. for configuration, which might make 
good use of having Lisp at their disposal, but we can implement those as 
Lisp functions in the back-end.

Another issue with having too powerful a page language is that it is 
difficult to process automatically. You can't validate the pages, you 
never know if they'll finish rendering eventually or not. We would not 
only have bugs in the GUI and Axiom but also in the documentation. And 
if we ever change some aspect of the standard look-and-feel someone will 
have to go and hunt down and fix dozens if not hundreds of pages 
containing some Lisp that doesn't mix well with the new standard. If the 
language is simple markup, we just change the rendering code in the GUI 
back-end and all pages look all new and shiny.

If we really want to offer the full power of Lisp, that's easy, too. 
Give the user the option to supply a Lisp source file as the page 
source. We would offer some convenience functions/macros of course, 
something like the following maybe:

(define-hyperdoc-page
   :title "MyPowerfulPage"
   :axiom-ref "MPP"
   :content #'my-powerful-page)

(defun my-powerful-page (stream)
   (with-html
      ....))

But I don't think that forcing that degree of control onto everyone on 
every occasion is a good idea. The other problem is that people would 
have to learn Lisp or something similar. A good datapoint is LaTeX. It 
is programmable, but most people don't care. Everyone uses \newcommand, 
but mostly for abbreviations and other simple things.


Finally I'd like to note that I might have missed some capabilities of 
the old HyperDoc browser. Also I'm not writing many HyperDoc pages so 
it's really not my decision what to do.

> Ah, there is a carnival of voices in my head....  
I just spend several hours reading about US tax law and relevant 
treaties. Nothing can be worse than that. ;-)


Kai