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

[tsd@tsdye.com (Thomas S. Dye)]

Aloha Rasmus,

Rasmus <rasmus@gmx.us> writes:

> The following message is a courtesy copy of an article
> that has been posted to gmane.emacs.orgmode as well.
>
>
> Thomas,
>
>>> Tom, do tell us more about what these habits are.
>>
>> The new exporter is really your friend.  Where before I might choose to
>> generate a LaTeX block, now I look to generate Org output and then count
>> on the exporter to do the right thing on the way to pdf.  
>>
>> The exporter's attribute system is very easy to use.  The attributes you
>> need to access are always right there.
>>
>> I've also come to rely on filters quite a bit. I use them for
>> non-breaking spaces, the plus/minus symbol, and for the multiple
>> citation commands used by biblatex (e.g., \parencites). There seems to
>> be a move afoot to collect filters so they can be widely distributed.
>> I'd like to see the filters go to the Library of Babel, but for
>> reproducible research it is probably best to keep them with the source
>> document so there is no doubt about the fidelity of filter code.
>
> I too rely heavily on filters and customizations.  I haven't been able
> to fully appreciate the asynchronous exporter yet.
>
> For instance I set some defaults for tables, pictures, add lots of
> entities etc. in my init file, and I went as far as writing a separate
> init file just loading just the org stuff.  Now, this is clearly /not/
> a very reproducible way of doing this.

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.

A compendium with this structure gets past the problem, often aired on
the ML, that there is "something in my setup" that causes unexpected
behavior.  The Org setup is completely contained in the compendium.

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.

Of course, it leaves open the question of changes in the underlying
software. This is a real problem. Org 8.0, with its new (and sweet)
exporter has broken my first two compendia. Conceivably, changes in
Emacs might break a compendium, as could changes in all the other
software referenced by babel code blocks.  Aaron Ecay seems to be on to
a possible mechanism to take care of at least some of this.  AFAICT,
however, his solution doesn't change the utility of the compendium,
which seems to me an integral part of the reproducibility equation.

What do you think?  

>
> So I'm really interested in hearing or seeing implementation where the
> goal is reproducibility.  On one hand I can appreciate keeping Org
> close to a vanilla state.  On the other hand, I'd have to overwrite
> defaults every time (e.g. I /always/ want booktab tables).  I guess I
> could keep an emacs-lisp block in the top of the file specifying
> stuff, but it also seems kind of tedious (copy-pasting every time).
> (Perhaps this could be resolved by loading external files hosted
> somewhere accessible).

Some journals specify which LaTeX packages can or cannot be used.
PLOS-One, for instance, doesn't use booktab tables, so a reproducible
research document sent to them couldn't include your default setting.
My sense of the publishing world is that it is sufficiently variable
eventually to break almost any default you might hope to establish.   

Incidentally, I think this is an area ripe for growth within Org
mode--additions to the Library of Babel that configure a compendium to
produce LaTeX code that meets the requirements of particular publishing
venues. It would be ideal to do something like <<init-plos-one>> and
then, when the journal sends back your paper with a digital pink slip,
change that to something like <<init-nature>> and send it off again.

All the best,
Tom 

-- 
T.S. Dye & Colleagues, Archaeologists
735 Bishop St, Suite 315, Honolulu, HI 96813
Tel: 808-529-0866, Fax: 808-529-0884
http://www.tsdye.com