From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail3-relais-sop.national.inria.fr (mail3-relais-sop.national.inria.fr [192.134.164.104]) by sympa.inria.fr (Postfix) with ESMTPS id 56E79820A1 for ; Tue, 3 Sep 2013 02:15:34 +0200 (CEST) Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of oliver@first.in-berlin.de) identity=pra; client-ip=192.109.42.8; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="oliver@first.in-berlin.de"; x-sender="oliver@first.in-berlin.de"; x-conformance=sidf_compatible Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of oliver@first.in-berlin.de) identity=mailfrom; client-ip=192.109.42.8; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="oliver@first.in-berlin.de"; x-sender="oliver@first.in-berlin.de"; x-conformance=sidf_compatible Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of postmaster@einhorn.in-berlin.de) identity=helo; client-ip=192.109.42.8; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="oliver@first.in-berlin.de"; x-sender="postmaster@einhorn.in-berlin.de"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Al8BAJgpJVLAbSoIkGdsb2JhbABagzyDeLgRhTmBKxYOAQEBAQkUCRgkgiQBAQUjVhALCQ8CAgUUDQICDwUYMYgVBAinHZIFFoETjQ6BPweCaTSBAAOPK4Rwg1mVCYFm X-IPAS-Result: Al8BAJgpJVLAbSoIkGdsb2JhbABagzyDeLgRhTmBKxYOAQEBAQkUCRgkgiQBAQUjVhALCQ8CAgUUDQICDwUYMYgVBAinHZIFFoETjQ6BPweCaTSBAAOPK4Rwg1mVCYFm X-IronPort-AV: E=Sophos;i="4.89,1010,1367964000"; d="scan'208";a="25500182" Received: from einhorn.in-berlin.de ([192.109.42.8]) by mail3-smtp-sop.national.inria.fr with ESMTP/TLS/DHE-RSA-AES256-SHA; 03 Sep 2013 02:15:33 +0200 X-Envelope-From: oliver@first.in-berlin.de Received: from first (e178031053.adsl.alicedsl.de [85.178.31.53]) (authenticated bits=0) by einhorn.in-berlin.de (8.13.6/8.13.6/Debian-1) with ESMTP id r830FViw014793 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Tue, 3 Sep 2013 02:15:32 +0200 Received: by first (Postfix, from userid 1000) id 8762E154023F; Tue, 3 Sep 2013 02:15:31 +0200 (CEST) Date: Tue, 3 Sep 2013 02:15:31 +0200 From: oliver To: Jonathan Protzenko Cc: caml-list@inria.fr Message-ID: <20130903001531.GB1964@siouxsie> References: <5224B137.8070706@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <5224B137.8070706@gmail.com> User-Agent: Mutt/1.5.20 (2009-06-14) X-Scanned-By: MIMEDefang_at_IN-Berlin_e.V. on 192.109.42.8 Subject: Re: [Caml-list] Literate (sort-of) programming in OCaml 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 = "" 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.