Re: [Axiom-developer] literate programming in html

[daly]

On Fri, 2012-01-20 at 10:57 +0000, Martin Baker wrote:
> Does the code have to be physically in the same document as the documentation 
> to achieve the aims of literate programming?
> 
> The analogy that I would make is with graphics in html, these are stored in 
> their own files so we can edit a .gif file or a .jpeg file or .png or .svg 
> and 
> so on each with there own appropriate graphics editor. The browser brings 
> these all together, when its being read,  so that the end user can read the 
> "story".
> 
> Is there some way this could be done for code? That is get the browser to 
> insert it into the document when its being read rather than build what looks 
> like quite messy tangling and untangling tools?
> 
> Martin
> 

The example I gave was
http://axiom-developer.org/axiom-website/litprog.html
which was a literate program in HTML.

It only depends on the ability to find <pre> tags which
contain an id= field as in <pre id="chunkname">

If you have control of the server it would be possible to
use PHP to construct your documentation "on the fly" by
including source chunks and sending them to the final page.
You could put id fields on <a> tags and parse the href field.

Latex does allow you to \include files but that would be
missing the point. Latex can also re-render in html.

Unfortunately it feels like you are trying to maintain the
idea that source code should live in little files. This has
a very long history but is actually a very bad idea. We are
forced to create tools to handle this (e.g. IDEs) so we can
manipulate the program "as a whole". You want to go from the
little files to the big document. Literate programs are
generally structured to work from big to little.

Literate programs change the structure of files in very
fundamental ways. The first priority of a literate program
is to communicate to another human. The code is expanded
in the document when it is properly motivated. Thus you 
find that the contents of a header file is usually spread
around in a literate document and re-assembled for the
compiler.

Tim