On Fri, 2012-01-20 at 15:43 +0000, Martin Baker wrote: > On Friday 20 Jan 2012 11:59:52 Ralf Hemmecke wrote: > > It all depends on your tools. If there were a tool that puts every code > > chunk into a separate file but while editing shows you the chunks in the > > order you want, you wouldn't care how your content is physically stored. > > Its just that the method Tim describes for embedding code into html here: > http://axiom-developer.org/axiom-website/litprog.html > has some complications and requires specialised tools. > > In some ways I find the current LP and hyperdoc stuff in Axiom flavors > actually makes it harder for me to produce the quality of documentation that > I > would like, although moving to an html version like this would help, I still > think custom tools like this are a major problem.
Custom tools? The litprog.html describes a short C program that is the only tool you need to do literate programming in HTML. And I've (almost completely) rewritten Axiom to use standard latex everywhere so the pamphlet files are straight latex using \begin{chunk}. The only tool needed is a small tangle program which I have as a C utility and is also compiled into the lisp image. A single extraction tool does not seem to be much overhead. > > I think it would be much better to use standard tools. I'm not sure that file > structure is the most important issue? This seems like a technical issue to > me. In the end the important issues to me are: > > * Can I use standard tools that I already know to edit code, html and > diagrams > in WYSIWYG mode. > * Does it require maintainence of specialised tools? > * Does it inhibit development of IDE capablitied like code completion and > debugging tools? > * Does it make documentation harder to produce rather than easier? > * Is there duplication between LP, Hyperdoc, )show, etc. > > I think there is a lot to be said for keeping the documentation (LP and > hyperdoc) on a server somwhere and only downloading code to users client. > Think of a calculus textbook. You want to keep the textbook on the server and only download the equations. That means that the user will have a directory of equations without meaning living on the local machine. I do not see the value of only downloading equations. There is a language called Clojure. I have created a literate form http://daly.axiom-developer.org/clojure.pamphlet http://daly.axiom-developer.org/clojure.pdf All of the information is in the pdf (and src) but basically you extract a tangle program http://daly.axiom-developer.org/tangle.c If you do gcc -o tangle tangle.c tangle clojure.pamphlet Makefile >Makefile make the makefile will extract the source code (mostly java) into the correct tree, compile the code, run the test cases, rebuild the pdf, and drop you into a running Clojure REPL. If you modify the src pamphlet all you need to type is make clean make and you now have a completely rebuilt, re-PDF'd, re-tested Clojure with a running REPL. To modify the program and test your new changes, just rinse and repeat. How hard is this? It could hardly be easier. Send the single pamphlet file to another user and they have everything. Tim _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org https://lists.nongnu.org/mailman/listinfo/axiom-developer