Re: Best practices for literate programming [was: Latex export of tables]

[Rasmus Pank Roulund <rasmus@gmx.us>]

Dear Tom,

> I suppose this depends on what is meant by "reproducible."
>
> My goal is to produce a compendium as defined by Gentleman and Lang
> (see Gentleman R, Lang DT (2004). "Statistical Analyses and Reproducible
> Research." Technical report, Bioconductor Project. URL
> http://www.bepress.com/bioconductor/paper2).  
>
> I keep the init.el file as a babel source block with the reproducible
> document, so it can be tangled. I also have an editing setup in a babel
> source block that activates many of the same features handled by the
> init.el file, but also configures the new exporter to look for init.el
> (which might have a different name). The filters are all part of the Org
> document, too, and get pulled into the init.el file with noweb
> references.

My issue here is that this approach might lead to copy-paste
"preambles" which may or may not be desirable.  I can certainly see
the attraction in being able to just tangle the setup.  In fact for my
thesis I also had a preamble.tex blog in my file.  Your proposed setup
here is perhaps better in that it uses emacs-lisp.

Still, say I'm working on two files A and B.  If I fix a bug in
"preamble" A I would have to manually copy it over to B.  

Thus, the main question is how to distribute updates?  I guess one
could keep a separate file, but then we are back at square one in a
way. . .

One possibility might be a file structure like this

setup.org
A/project-A.org
A/setup-A.org
B/project-B.org
B/setup-B.org

where A and B both has a block like
#+BEGIN_SRC org
* Preamlbe    :noexport:
#+INCLUDE: "../setup.org"
#+INCLUDE: "setup-A.org"
#+END_SRC

To ship it off one would only have to write a command to replacing
#+INCLUDE with its content.  The exporter could likely be used for
this and one could produce an archive version when signing off a
project.

Even more robust, #+INCLUDE: would look for files in org-directory (it
might already do, I didn't check).

Am I missing something obvious (probably?) in the above stream of
random thoughts?  It's kind of a LaTeX-ish way of dealing with it, I
guess.

> I am able to distribute the compendium, typically as a single
> document (sometimes with associated data files produced by an
> on-line service that can't be used programmatically), which I
> believe is a good step toward reproducibility.

Agreed.

–Rasmus

-- 
Send from my Emacs