Re: [Axiom-developer] literate programming in html

[daly]

On Fri, 2012-01-20 at 18:53 +0000, Martin Baker wrote:
> 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.

Literate programming is a change of mindset. You clearly get it.
There is no "right" way to do it. And I don't feel we are disagreeing.

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

Absolutely. And I think you are doing an excellent job.

> 
> 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.

Well I read a LOT and I find that non-linear paths leave me with the
feeling that I'm missing something important. I don't have a way to
mark my path so I know what other paths to follow.

> 
> 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?

Yes, I'm using Latex for most of my work except for Volume 11
which is the new Axiom browser-based help system. I am experimenting
with using <canvas> tags as we speak. See
http://axiom-developer.org/axiom-website/axiomgraph
so I do find HTML5 interesting. 

I have included png and diagrams (see the Clojure pamphlet). 
I have seen 3D animations in PDF files which is a technology
I have bookmarked but not yet tried to use.
> 
> 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.

In fact, I do write all of my HTML by hand. I don't use WYSIWYG tools
at all. And the way I use hypertex is the same way I use latex, that 
is to say, I use #name tags into the same document to do things like
jump between sections. This allows the user to jump around in a
linear discussion.

> 
> 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.

The navigation is fine. What I find hard about hyperlinked documents
is that I quickly feel lost. Instead of moving from chapter to chapter
it feels like I'm reading random websites with random browser 
crashes. When I "put the website down" like I would with a book
I don't know how to start again.

You've done a good job at overall organization of your site by
keeping the tree structure at the top. However, when I re-visit
your site I don't know what I've seen and what I haven't.

> 
> 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.

I don't think you're wrong. I just think we have found our own
approach comfortable. As an old man with a large library I find
reading books to be a useful paradigm. You find the web to be a
useful paradigm. Either approach is fine.

Much more important is the literate programming mindset and
you clearly know that already. Keep up the good work.