Re: [Caml-list] Literate (sort-of) programming in OCaml

[oliver <oliver@first.in-berlin.de>]

Hi,

On Mon, Sep 02, 2013 at 05:39:35PM +0200, Jonathan Protzenko wrote:
> Hi,
> 
> I am currently writing a big, mostly textual document in format blah 
> (blah being of a course a meta-variable). Are there any tools that 
> would allow me to interleave OCaml code with the contents of my 
> document?
> 
> More on my use-case. Creating this document requires me to perform 
> various subtasks, such as:
> - write a code snippet in the document,
> - put the code snippet in a file,
> - call an external program on the file,
> - paste the output into the document.
> 
> Naturally, I wish to automate this. I could roll my own set of 
> commands, and parse them with OCaml, but I would be re-creating a 
> scripting language, and it seems to me that interleaving OCaml code 
> within my document would be better. Here's what I have in mind:
> 
> 
> blah blah blah blah blah blah blah blah blah blah blah blah blah blah 
> blah blah
> blah blah blah blah blah blah blah blah blah blah blah blah blah blah 
> blah blah
> blah ... we thus write the following code ... :
> 
> {%
>   let code = "<sample code>" in
>   output code
> %}
> 
> blah blah blah ... after running the command blah ... the output is as 
> follows ... blah
> 
> {%
>   let f = write_into_temp_file code in
>   let s = run_and_read "myprogram" [f] in
>   output s
> %}
> 
> blah blah blah blah blah blah blah blah blah blah blah blah blah blah 
> blah blah ...
> 
> 
> Are you aware of any tool that would allow me to achieve this?
[...]


Hmhhh, long, long ago I explored some of the good-old / classical
literate programming tools (well, to be detailed, I did not tried Web,
so it was not THE classical one, but later developments, influenced by
Knuth's Web.)

Some of these tools were limited to certain languages, but as far as I remember
at least one was able to work with any (???) language.
Or at least some tools were very flexible to work with many languages.

I have forgotten most of the names of the tools I used, possibly I tried
noweb and some others.

All had their advantages and also their limitations.

There was one (or two?) that looked so promising that I had planned to try it
(them) too, but I stopped with Literate Programming (LP) before I had the
motivation to try it/them.
  (Trying so many tools at some time has exhausted and demotivated me.
   Those I tried were not powerful/flexible enough, nevertheless needed their
   time to look at them. Tools should help in the work and help saving time,
   not eat the time...)

As far as I remember, and I'm not sure, FWEB and/or FunnelWeb was/were the
remaining tools that I had selected as the most prommising ones (but did not
tried them, as mentioned above, so I can't really vote for them).

(In/with R you can use Sweave, which allows to embed code and results from code
 like tables, and even to embedd created graphics into the document!)


An overview with links to some of the LP-tools can be found here:

  http://www.literateprogramming.com/tools.html


I remember that there were a lot more free tools, than mentioned there.

  I remember one really nice tool only for C-dialects, which did not have
  big functionality, but allowed to pretty print C-Code with real TeX-Comments
  inserted. And the syntax was very simple.
  But it was not allowing insertion of the results of the program,
  at least not directly. But via TeX/LaTeX-include/input--commands I think it was possible
  indirectly.

  But you look for more functionality, and want to pass back the results into
  your document. Something like Sweave.

Possibly FWEB or FunnelWEB are the tools, you should explore first.
(But be prepared to learn their syntax....)

Let me know, which tool you selected, and how your experience was with it.


Ciao,
   Oliver


P.S.: In a documenting-/reverse-engineering project I programmed my own
      literate programming tool(s), so that I could insert Text and
      graphviz-commands into the code-comments. The Perl-Tools did extract the
      text and the graphviz code, invoked graphviz and created a LaTeX-document
      that contained the Code, the documenting text and the Graphviz-graphics
      (e.g. for Flowcharts), and created a nice pdf-document, including the
      nice references, to open certain parts of the doc by clicking on the
      entries in the table of contents. :-)
      By organizing the document via includes/inputs, the document structure could be
      organized the way I wanted. (The laTeX-code was also created by the
      Perl-script(s).


P.P.S.: When using troff it's possible to write C code and it's documentation
        in troff (including PIC-macros :-)) in a way, that it can be C-compiled
        directly, without tangling-process, and the document can be set with
        troff without weaving-process. So, it's possible to have one C-file and
        pass it into C-compiler and troff without changes. :-) Very funny, to
        make this. But changing the order of sections is not possible. Real
        LP-tools IMHO should offer reordering of sections, but most of them
        don't.