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. _______________________________________________ Axiom-developer mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/axiom-developer
