R help - Dec 2010 - (S|odf)weave : how to intersperse (\LaTeX{}|odf) comments in source code ? Delayed R evaluation ?

Dear list,

Inspired by the original Knuth tools, and for paedaogical reasons, I wish 
to produce a document presenting some source code with interspersed 
comments in the source (see Knuth's books rendering TeX and metafont 
sources to see what I mean).

I seemed to remember that a code chunk could be defined piecewise, like in

Comments...

<<Chunk1, eval=FALSE, echo=TRUE>>SomeCode
@

Some other comments...

<<Chunk2, eval=FALSE, echo=TRUE>>MoreCode
@

And finally,

<<Chunk3, eval=TRUE, echo=TRUE>><<Chunk1>>
<<Chunk2>>
EndOfTheCode
@

That works ... as long as SomeCode, MoreCode and EndOfTheCode are self-
standing pieces of R code, but *not* code fragments. You can *not* 
intersperse comments in, say, a function body, or  local() environment 
this way : when Sweaving, *R* complains of an incomplete source (makes 
noise about an unexpected end of input at the end of Chunk1, IIRC, and 
never sees Chunk2).

I hoped that Sweave's "alternative" syntax could offer a way out :
no
such luck.

There seems to be no way to delay R evaluation of a R chunk passed by 
Sweave ; at least, the "eval=FALSE" option of chunk declaration is not
sufficient for that.

Am I missing something in the Sweave nd odfWeve documentations (that I 
read till I grew green and moldy) ? Or does this require a fundamental 
change in the relevant Sweave drivers ?

Can you suggest alternative ways of doing what I mean to do ? The only 
workaround I found is to paste a second copy of my code in a \verbatim 
environment (or, in the case of odfWeave, in the "text" part), and
spice
it with \end{verbatim} comments.. \begin{verbatim} chunks. This way, I 
lose any guarantee of consistency between commented text and effective 
code.

Any other idea ?

					Emmanuel Charpentier

On 11/12/2010 5:58 PM, Emmanuel Charpentier wrote:
> Dear list,
>
> Inspired by the original Knuth tools, and for paedaogical reasons, I wish
> to produce a document presenting some source code with interspersed
> comments in the source (see Knuth's books rendering TeX and metafont
> sources to see what I mean).
>
> I seemed to remember that a code chunk could be defined piecewise, like in
>
> Comments...
>
> <<Chunk1, eval=FALSE, echo=TRUE>>> SomeCode
> @
>
> Some other comments...
>
> <<Chunk2, eval=FALSE, echo=TRUE>>> MoreCode
> @
>
> And finally,
>
> <<Chunk3, eval=TRUE, echo=TRUE>>> <<Chunk1>>
> <<Chunk2>>
> EndOfTheCode
> @
>
> That works ... as long as SomeCode, MoreCode and EndOfTheCode are self-
> standing pieces of R code, but *not* code fragments. You can *not*
> intersperse comments in, say, a function body, or  local() environment
> this way : when Sweaving, *R* complains of an incomplete source (makes
> noise about an unexpected end of input at the end of Chunk1, IIRC, and
> never sees Chunk2).
>
> I hoped that Sweave's "alternative" syntax could offer a way
out : no
> such luck.
>
> There seems to be no way to delay R evaluation of a R chunk passed by
> Sweave ; at least, the "eval=FALSE" option of chunk declaration
is not
> sufficient for that.

It's not evaluation, it's parsing, but you're right:  there's no
way to
delay it.  Perhaps Sweave needs a "parse=FALSE" option.

>
> Am I missing something in the Sweave nd odfWeve documentations (that I
> read till I grew green and moldy) ? Or does this require a fundamental
> change in the relevant Sweave drivers ?
I suspect the latter.
>
> Can you suggest alternative ways of doing what I mean to do ? The only
> workaround I found is to paste a second copy of my code in a \verbatim
> environment (or, in the case of odfWeave, in the "text" part),
and spice
> it with \end{verbatim} comments.. \begin{verbatim} chunks. This way, I
> lose any guarantee of consistency between commented text and effective
> code.
Not any very satisfactory suggestions:

- write smaller functions, and make up your large function out of calls 
to them.  Then you can define a whole small function in one chunk.

- use keep.source=TRUE, and use R comments rather than nicely typeset 
ones if you need to make comments within a function definition.

I don't know any way to get what you were asking for, but perhaps these 
are close enough.

Duncan Murdoch
>
> Any other idea ?
>
> 					Emmanuel Charpentier
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.

On Sat, Dec 11, 2010 at 5:58 PM, Emmanuel Charpentier
<emm.charpentier at free.fr> wrote:
> Dear list,
>
> Inspired by the original Knuth tools, and for paedaogical reasons, I wish
> to produce a document presenting some source code with interspersed
> comments in the source (see Knuth's books rendering TeX and metafont
> sources to see what I mean).
>
> I seemed to remember that a code chunk could be defined piecewise, like in
>
> Comments...
>
> <<Chunk1, eval=FALSE, echo=TRUE>>> SomeCode
> @
>
> Some other comments...
>
> <<Chunk2, eval=FALSE, echo=TRUE>>> MoreCode
> @
>
> And finally,
>
> <<Chunk3, eval=TRUE, echo=TRUE>>> <<Chunk1>>
> <<Chunk2>>
> EndOfTheCode
> @
>
> That works ... as long as SomeCode, MoreCode and EndOfTheCode are self-
> standing pieces of R code, but *not* code fragments. You can *not*
> intersperse comments in, say, a function body, or ?local() environment
> this way : when Sweaving, *R* complains of an incomplete source (makes
> noise about an unexpected end of input at the end of Chunk1, IIRC, and
> never sees Chunk2).
>
> I hoped that Sweave's "alternative" syntax could offer a way
out : no
> such luck.
>
> There seems to be no way to delay R evaluation of a R chunk passed by
> Sweave ; at least, the "eval=FALSE" option of chunk declaration
is not
> sufficient for that.
>
> Am I missing something in the Sweave nd odfWeve documentations (that I
> read till I grew green and moldy) ? Or does this require a fundamental
> change in the relevant Sweave drivers ?
>
> Can you suggest alternative ways of doing what I mean to do ? The only
> workaround I found is to paste a second copy of my code in a \verbatim
> environment (or, in the case of odfWeave, in the "text" part),
and spice
> it with \end{verbatim} comments.. \begin{verbatim} chunks. This way, I
> lose any guarantee of consistency between commented text and effective
> code.
>
> Any other idea ?
Try the brew package.

-- 
Statistics & Software Consulting
GKX Group, GKX Associates Inc.
tel: 1-877-GKX-GROUP
email: ggrothendieck at gmail.com

On Sun, Dec 12, 2010 at 2:24 PM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
> Try the brew package.
>
There is another package, markup, which is similar to brew and Sweave.
See some comments in this thread [1]. To my knowledge it was never
officially released, but you could still try it out.

Regards
Liviu

[1] http://www.mail-archive.com/r-help at r-project.org/msg109238.html

Dear list,

see comment at end.

On Sat, 11 Dec 2010 22:58:10 +0000, Emmanuel Charpentier wrote?:
> Dear list,
> 
> Inspired by the original Knuth tools, and for paedaogical reasons, I
> wish to produce a document presenting some source code with interspersed
> comments in the source (see Knuth's books rendering TeX and metafont
> sources to see what I mean).
> 
> I seemed to remember that a code chunk could be defined piecewise, like
> in
> 
> Comments...
> 
> <<Chunk1, eval=FALSE, echo=TRUE>>> SomeCode
> @
> 
> Some other comments...
> 
> <<Chunk2, eval=FALSE, echo=TRUE>>> MoreCode
> @
> 
> And finally,
> 
> <<Chunk3, eval=TRUE, echo=TRUE>>> <<Chunk1>>
> <<Chunk2>>
> EndOfTheCode
> @
> 
> That works ... as long as SomeCode, MoreCode and EndOfTheCode are self-
> standing pieces of R code, but *not* code fragments. You can *not*
> intersperse comments in, say, a function body, or  local() environment
> this way : when Sweaving, *R* complains of an incomplete source (makes
> noise about an unexpected end of input at the end of Chunk1, IIRC, and
> never sees Chunk2).
> 
> I hoped that Sweave's "alternative" syntax could offer a way
out : no
> such luck.
> 
> There seems to be no way to delay R evaluation of a R chunk passed by
> Sweave ; at least, the "eval=FALSE" option of chunk declaration
is not
> sufficient for that.
> 
> Am I missing something in the Sweave nd odfWeve documentations (that I
> read till I grew green and moldy) ? Or does this require a fundamental
> change in the relevant Sweave drivers ?
> 
> Can you suggest alternative ways of doing what I mean to do ? The only
> workaround I found is to paste a second copy of my code in a \verbatim
> environment (or, in the case of odfWeave, in the "text" part),
and spice
> it with \end{verbatim} comments.. \begin{verbatim} chunks. This way, I
> lose any guarantee of consistency between commented text and effective
> code.
> 
> Any other idea ?
> 
> 					Emmanuel Charpentier

To summarize the answers I got so far, there seems to be no satisfactory 
solutions to my current problem with either Sweave or odfWeave :
	- every (Sw|odfW)eave code chunk has to be parseable in itself. 
One cannot break it in unparseable pieces in home to paste it later ;
	- the (hypothetical) "parse=FALSE" option, suggested by Duncan 
Murdoch, is, well, hypothetical ;
	- the brew package is not integrated in either Sweave or 
odfWeave ;
	- R-style comments will get you only so far (where is math markup 
when you need it ?) ;
	- subdivising work in small units is not a practical solution, 
when your "big piece" of software is a collection of small parts and 
local variable assignments, embedded in a (perforce large) local 
environment to keep things clean...

Therefore, I let this problem to sleep. However, I Cc this answer (with 
the original question below) to Max Kuhn and Friedrich Leisch, in the 
(faint) hope that this feature, which does not seem to have been missed 
by anybody in 8 years, might be considered sufficiently useful to grant 
addition someday...

Sincerely yours,

					Emmanuel Charpentier

Dear list,

The "starting" solution proposed by Duncan Murdoch is an *excellent* 
start for Sweave'ing. One can trivially redefine Sweave to start using it 
quasi-transparently (to use it transparently would require patching 
Sweave, which would be worth some failsafes and possibly options 
tinkering).

Integrating it on odfWeave is not as simple, because the driver as to 
spit out correct XML. I suspect that the odfCat() function of odfWeave 
will be useful, but my (very) cursory glance at odfWeave source did not 
(yet) ensured me that one could use the shortcuts that the simple 
structure of \TeX{} file allows. XML *needs* some caution, and the Open 
Document specification is *not* a simple beast. However, I have good 
hopes.

I'll keep the list posted about further enhancements, as my (somewhat 
busy) schedule will allow.

Again, kudos and a big thank you to Duncan Murdoch, who was able to give 
a *correct* solution before I have been able to *correctly* state the 
problem.

					Emmanuel Charpentier

On Sat, 11 Dec 2010 22:58:10 +0000, Emmanuel Charpentier wrote?:

[ Snip... ]