Re: [Axiom-developer] literate programming in html

[Martin Baker]

On Friday 20 Jan 2012 15:59:15 you wrote:
> How hard is this? It could hardly be easier. Send the single
> pamphlet file to another user and they have everything.

Tim,

Perhaps I'm too set in my ways or perhaps I'm missing something but I think we 
are going to have to agree to disagree on this issue.

I think we agree on the importance of documentation and the importance of 
explaining the reasons behind things and the aims of LP.

But I think we will have to agree to disagree on the mechanics and that there 
should only be one linear path through the documentation.

Perhaps my thinking comes from liking to understand things in terms of 
pictures and diagrams rather than big chunks of text (I suspect I differ from 
most people in the pan-Axiom community in this respect). So, what I'm looking 
for is documentation rich with pictures, diagrams, tables, lists, animations, 
hyperdoc-like capability, different layouts and so on. Not the equivalent of a 
very big book.

In order to do this I think the documentation has to be based on html + png + 
svg and so on. This is very different to existing pamphlet files, as far as I 
can see the Clojure example you give is not HTML?

I can't see that it would be very desirable to just put HTML tags into a mega 
pamphlet file and sort out the technical issues you mention in your document. 
For one thing, one does not want to edit low level HTML using a simple text 
editor, I think it really needs WYSIWYG html and graphics editors. Also the 
whole idea of hypertext seems to favour a more hierarchical approach rather 
than a linear document.

I want to be able to start with a quick introduction to the program and when I 
get to something I'm specially interested to click on a hyperlink and drill 
down to more detail. The navigation should give many ways to read the document 
including LP-like and Hyperdoc-like and )show-like (computer generated 
reference information) all richly interlinked.

We have discussed these things before and I think I'm starting to repeat 
myself so, as I say I think it best to agree to disagree. I will watch your 
experiment with interest and be ready to be proved wrong.

Martin