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

From: "Sébastien Vauban" <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org>
To: emacs-orgmode-mXXj517/zsQ@public.gmane.org
Subject: Re: Org-mode Code Blocks Manuscript: Request For Comments
Date: Tue, 07 Dec 2010 23:55:00 +0100	[thread overview]
Message-ID: <80k4jl2ny3.fsf@missioncriticalit.com> (raw)
In-Reply-To: 12760.1291360577@gamaville.dokosmarshall.org

Hi Eric,

Let's see if I'm a good proof-reader. Here are my comments, looking at things
not already said by others:

Page 1 -- "... desirable to mix prose, (add input data?,) code, and
computational results."

Page 3 -- It'd be better not to have commas in front of the Org-mode block in
Figure 1.

Page 9 -- You say that "tags and properties of a node are inherited by its
sub-nodes". I agree for tags, not for properties (at least, by default).

Page 10 -- "Active code blocks are marked with a source line, followed by a
name unique within the document". Why don't you call such "named code blocks"
as in Babel's code base?

BTW, what happens if there is a name clash with other code blocks (in the same
document, or in the LOB)?  Though, this is not for your paper...

Page 12 -- When results is set to output, what do you mean by "collected from
STDOUT incrementally"?  Not sure about the added value of incrementally...

Page 16 -- I find the name of the code block "ps-to-dot" very badly chosen. PS
makes me think of PostScript, while you mean here Pascal's triangle...

Page 17 -- In the LaTeX ATTR, better use linewidth instead of textwidth. This
is a more secure setting.

Page 18 -- Is the default value of var (1 2 1) compliant with the "pass" table
beneath it?

Side comment -- Wouldn't you use a standard way of handling the acronyms in
LaTeX, so that they're expanded when required, and listed at the end of the
document?  Example of such acro: ESS.

For the rest, an excellent document, but not that good (IMHO) for publishing
to a statistics journal. For doing so, I find you'd have to only include R
examples, and show that you can do everything Sweave can do, and even much
more. But I would focus on stats a lot more than it is here.

But, the way it is written, it is much more general, and offers a much widen
view. So, this is excellent, but for another audience.

Best regards,
  Seb

-- 
Sébastien Vauban

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode-mXXj517/zsQ@public.gmane.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode