KH-RFC-demos

				Dear Emacs, make this -*-Text-*- mode!

R currently comes with several R programs (``demos'') demonstrating its
capabilities; one of the demos additionally uses C code (dynload).  The
current mechanism is not very powerful.  Problems identified include

* Demos might interfere with the user's workspace (.GlobalEnv).

* There is no straightforward way to display explanatory information
  along the code being run, comments are typically truncated.  (Of
  course one could get by this using explicit file.show() steps.)

* There is no straightforward way of interacting with the user.

The last two items imply that we currently cannot easily write on-line
tutorials.  In addition, as Fritz recently pointed out to me, it would
be very useful to have a mechanism for producing `pretty' (e.g. LaTeX
with PostScript graphics) output from R code and explanatory comments.

Fritz and Peter had discussed a mechanism for writing enhanced demos
based on extended Rd markup.  Given recent discussions on documentation
objects and related issues, I think we need a more general literate
programming kind of approach.  Note that my experience with such tools
is primarily with the LaTeX 2e docstrip mechanism, hence what I have in
mind is closely related to this.

* Add a mechanism for keeping ``documentation'' along with the R code.
  The text would be in comment lines enclosed within SGML-style tags.
  Rather than assuming that this documentation must be plain text or
  would be written in some universal language, there should be a way to
  specify the kind of documentation (e.g., LaTeX, Rd, SGML, ...).  The
  docstrip-style processing mechanism would be smart enough to extract
  the right parts.

* In particular, R itself should we able to extract text it should
  display along with running a demo.

* Add R functions providing a toolkit for writing demos.  This could
  include e.g.

	demoAskConfirmation
	demoGetInput

  etc.

* (Preliminary.)  For tutorials we need a mechanism providing explain
  and run and display cycles.  That R knows what to do with <Rdemo>
  markup in comments is not good enough, because there is no point in
  having everything run over the screen.  Of course we can always write
  explicit R code to do this, but I think it is more convenient to have

  ## <Rdemocycle>
  ## <Rdemocycledoc>
  ## O.k., so we now want to do the following ...
  ## </Rdemocycledoc>
  ## <Rdemocyclecode>
  foo(bar, ...)
  ## </Rdemocyclecode>
  ## </Rdemocycle>

* Add R functions to ``pretty-print'' R objects in certain formats.
  E.g., when trying to create LaTeX output the mechanism could be like

  ## <LaTeX>
  ## We now do $$\alpha\beta\gamma ...$$
  ## </LaTeX>
  x <- doSomethingUsefulNow(args)
  LaTeX(x)

  but of course we need a way to specify that the LaTeX representation
  gets dumped to the same file the LaTeX ``documentation'' goes to.

  Similarly, there should be a mechanism for adding plots (e.g. have a
  plot counter, create subdir `images', when dumping a plot create file
  `fig$counter.eps' in the subdir and add \includegraphics{...} to the
  LaTeX file, increment the counter).


-k