Re: [Axiom-developer] literate programming in html

[daly]

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