literate programming

Hi Terry,

You can do this with Sweave (and something smart like emacs with ESS 
installed as your editor), but you have to work at it a little. The key 
is the fact that a couple of releases ago they added options for 
"keep.source" and "expand". For example, you do the following:

First, describe the various steps in the algorithm. (Unless you are 
defining functions to use later, you probably do not want to evaluate 
these.)

<<extractParameters,eval=FALSE>>=
# code here to get the parameters
@

<<selectTrainingSet,eval=FALSE>>=
# code here to split data into training and test sets
@

<<trainModel,eval=FALSE>>=
# code here to fit a model to training data
@

<<testModel,eval=FALSE>>=
# code here to see how well the model works
@

Then  you can put the pieces together, doing something like

<<runSplits,keep.source=TRUE,expand=FALSE>>=
for (i in 1:numberOfSplits) {
<<extractParameters>>
<<selectTrainingSet>>
<<trainModel>>
<<testModel>>
}
@

The "expand=FALSE" makes sure that the final report does not re-expand 
the lines of code in the displayed output, which allows you to focus on 
the structure of the algorithm.

There are still two weaknesses compared to Knuth's original idea:
[1] You cannot describe the overall algorithm first but wait until later 
to define the pieces. (Actually, I could be wrong about this; it just 
occurred to me that you might be able to manage this with yet another 
clever use of "eval=FALSE", but I haven't tried that.)

[2] The names that you assign to the code chunks do not appear in the 
report automatically, so you have to write text in front of them to make 
them show up. Without these, the references in the final piece do not 
necessarily make sense to the reader trying to follow the action.

Best,
	Kevin

I'm working on the next iteration of coxme.  (Rather slowly during the summer).
  
  This is the most subtle code I've done in S, both mathematically and 
technically, and seems a perfect vehicle for the "literate programming" paradym 
of Knuth.  The Sweave project is pointed at S output however, not source code.  
I would appreciate any pointers to an noweb type client that was R-aware.
  
  Other suggestions are welcome as well.  At the end of the day I'd like to have 
a good user guide, technical reference, and solid enough code documentation that 
others can begin to participate as well.  (Retirement in 10 years -- I don't 
expect to maintain this forever!)
  
  	Terry Therneau
  	therneau.terry at mayo.edu

______________________________________________
R-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

G'day Terry,

On Tue, 5 Aug 2008 09:38:23 -0500 (CDT)

I'm working on the next iteration of coxme.  (Rather slowly during
the summer). 
  This is the most subtle code I've done in S, both mathematically
and technically, and seems a perfect vehicle for the "literate
programming" paradym of Knuth.  The Sweave project is pointed at S
output however, not source code. I would appreciate any pointers to
an noweb type client that was R-aware. 

I would suggest you look at relax:
    http://www.wiwi.uni-bielefeld.de/~wolf/software/relax/relax.html

Cheers,
	
	Berwin

=========================== Full address =============================
Berwin A Turlach                            Tel.: +65 6515 4416 (secr)
Dept of Statistics and Applied Probability        +65 6515 6650 (self)
Faculty of Science                          FAX : +65 6872 3919       
National University of Singapore
6 Science Drive 2, Blk S16, Level 7          e-mail: statba at nus.edu.sg
Singapore 117546                    http://www.stat.nus.edu.sg/~statba

On Tue, 5 Aug 2008 09:38:23 -0500 (CDT),
Terry Therneau (TT) wrote:

> I'm working on the next iteration of coxme.  (Rather slowly during
  >   the summer).  This is the most subtle code I've done in S, both
  >   mathematically and technically, and seems a perfect vehicle for
  >   the "literate programming" paradym of Knuth.  The Sweave project
  >   is pointed at S output however, not source code.  I would
  >   appreciate any pointers to an noweb type client that was
  >   R-aware.
  
  >   Other suggestions are welcome as well.  At the end of the day
  > I'd like to have a good user guide, technical reference, and solid
  > enough code documentation that others can begin to participate as
  > well.  (Retirement in 10 years -- I don't expect to maintain this
  > forever!)
  
Why not use the original noweb in the first place? You can even
maintain Sweave files with it, the Sweave latex syntax was written for
exactly that purpose ...

ESS supported noweb before Sweave existed. In fact the emacs noweb
mode was the main reason I chose that syntax for Sweave, and the latex
syntax was added lateron because some people write whole packages using
noweb and would have had a syntax conflict in their vignettes.

Best,
Fritz