Re: Org-mode Code Blocks Manuscript: Request For Comments

[Nick Dokos <nicholas.dokos@hp.com>]

Eric Schulte <schulte.eric@gmail.com> wrote:


> Dan Davison, Tom Dye, Carsten Dominik and myself have been working on a
> paper introducing Org-mode's code block functionality.  We plan to
> submit this paper to the Journal of Statistical Software.  As both
> Org-mode and the code block functionality are largely products of this
> mailing list community, and in the spirit of an open peer review process
> we are releasing the current draft of the paper here to solicit your
> review and comments.
> 
> Both the .org and .pdf formats of the paper are available at the
> following locations.
> 
> http://cs.unm.edu/~eschulte/org-paper/babel.org
> 
> http://cs.unm.edu/~eschulte/org-paper/babel.pdf
> 

I just finished reading the paper. I have watched babel go by without
doing much with it so far, so I knew a little of the motivation and the
functionality, but seeing the examples in action is another matter
altogether: beautiful stuff.

I haven't tried evaluating all the code blocks yet, but here are some
corrections to minor things and some questions, after this first
reading:

o p.9, Sec. 3.1.2: in the TODO example, a \texttt has sneaked into the
  output.

o p.14, Sec 3.3: second line of the "weaving" description, "...to export
  to HTML an number of other target formats,..." should probably be
  "...to export to HTML and a number of other target formats,..."
  perhaps?

o p. 17, Sec. 4.1.2, code block ps-to-fig, the #+ATT should
  be #+ATTR_LaTeX: I think.

o p. 20, Sec. 4.3, end of first paragraph: is "propagate" the right
  word? should it perhaps be "populate"?

o p.21, Sec. 4.3, sqlite code block: it does not have a #+source
  attribute (should it?) and the quoted code is out of sync with the
  "real" code, missing the "drop table" construct and some header args.
  I take it there is no concept of radio-code that would populate the
  ``#+begin_src org'' block with an up-to-date copy of the real code, is
  there?

o p.21, Sec. 4.3, paragraph after sqlite code block: refers to get-temps
  code block which does not exist. Even if omitted from the published
  version for brevity, it should be included in babel.org.

o p.23, Sec. 5: in the "Widely available" description, "... an wide
  variety..." should be "... a wide variety...".  In the "General and
  extensible" description, I would omit "pursuit of".

o There are widows/orphans in some examples (e.g. bottom of p.8, top of
  p.17) but I presume you'll wait to deal with those at the very end.

Finally, the questions: in Sec. 4.1.3, I may be missing something
fundamental, but I don't understand how that works at all. In
particular, is the table formula complete as it stands? How does it get
the diagonals? How are these things passed to the code block? Why does
the code block have values given to the variables? Is it correct as it
stands, or are things missing? This is the one section where I was
completely lost.  Could somebody explain?

Thanks,
Nick