[ESS] [Rather ancient] ESS documentation on 'script is the truth' ?

[Dirk Eddelbuettel]

On 8 May 2022 at 08:12, Tony Rossini wrote:
| ah...  might be the article Rich refers to...

No, Rich replies very kindly and promptly, but that wasn't it. 
 
| now that you've rejected a few proposals for what it could be, i do
| remember the text you are referring to.

Yay. So I am not (entirely) hallucinating. That's a start.
 
| but unfortunately, not where it's currently located??
| 
| I'm slowly going senile, or at least doing too much senior
| management/pointy-headed boss work these days to have a clue...
| 
| if you find it, let me, at least know, where you found it! best,

I think it was in the "old" doc/ directory which was, pre-cleanup, a little
more irregular. [...] So I just went nuclear and 'git reset --hard' some
twenty years ago. I may have been thinking of the old 'README.S' which
seemingly had a slightly longer discussion of a usage example than what is
left in the current manual. I include it below.

Thanks to all who pointed me to the manual. It is (in info mode) my main
reference too and had been and I should look closer.  The catch phrase I was
looking for ("The source code is real") was there after all, but I had
convinced myself I was looking for a non-manual text. 

Dirk


Philosophies for using ESS
==========================

The first is preferred, and configured for.  The second one can be
retrieved again, by changing emacs variables.

1: (preferred by the current group of developers):  The source code is 
   real.  The objects are realizations of the source code.  Source
   for EVERY user modified object is placed in a particular directory
   or directories, for later editing and retrieval.

2: (older version): S objects are real.  Source code is a temporary
   realization of the objects.  Dumped buffers should not be saved.
   _We_strongly_discourage_this_approach_.  However, if you insist,
   add the following lines to your .emacs file:

      (setq ess-keep-dump-files 'nil)
      (setq ess-delete-dump-files t)
      (setq ess-mode-silently-save nil)

The second saves a small amount of disk space.  The first allows for
better portability as well as external version control for code.


Scenarios for use
=================

We present some basic suggestions for using ESS to interact with S.
These are just a subset of approaches, many better approaches are
possible.  Contributions of examples of how you work with ESS are
appreciated (especially since it helps us determine priorities on
future enhancements)! (comments as to what should be happening are
prefixed by "##").

1:  ##    Data Analysis Example (source code is real)
    ## Load the file you want to work with
    C-x C-f myfile.s

    ## Edit as appropriate, and then start up S-PLUS 3.x
    M-x S+3

    ## A new buffer *S+3:1* will appear.  Splus will have been started
    ## in this buffer.  The buffer is in iESS [S+3:1] mode.

    ## Split the screen and go back to the file editing buffer.
    C-x 2 C-x b myfile.s

    ## Send regions, lines, or the entire file contents to S-PLUS.  For regions,
    ## highlight a region with keystrokes or mouse and then send with:
    C-c C-r

    ## Re-edit myfile.s as necessary to correct any difficulties.  Add
    ## new commands here.  Send them to S by region with C-c C-r, or
    ## one line at a time with C-c C-n.

    ## Save the revised myfile.s with C-x C-s.

    ## Save the entire *S+3:1* interaction buffer with C-c C-s.  You
    ## will be prompted for a file name.  The recommended name is
    ## myfile.St.  With the *.St suffix, the file will come up in ESS
    ## Transcript mode the next time it is accessed from Emacs.



2:  ## Program revision example (source code is real)

    ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) 
    M-x S+3

    ## Load the file you want to work with
    C-x C-f myfile.s
    
    ## edit program, functions, and code in myfile.s, and send revised
    ## functions to S when ready with
    C-c C-f
    ## or highlighted regions with
    C-c C-r
    ## or individual lines with
    C-c C-n
    ## or load the entire buffer with 
    C-c C-l

    ## save the revised myfile.s when you have finished
    C-c C-s



3:  ## Program revision example (S object is real)

    ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) 
    M-x S+3

    ## Dump an existing S object my.function into a buffer to work with
    C-c C-d my.function
    ## a new buffer named yourloginname.my.function.S will be created with
    ## an editable copy of the object.  The buffer is associated with the
    ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not
    ## exist after you log off.

    ## enter program, functions, and code into work buffer, and send
    ## entire contents to S-PLUS when ready
    C-c C-b

    ## Go to *S+3:1* buffer, which is the process buffer, and examine
    ## the results.
    C-c C-y
    ## The sequence C-c C-y is a shortcut for:  C-x b *S+3:1*

    ## Return to the work buffer (may/may not be prefixed)
    C-x C-b yourloginname.my.function.S
    ## Fix the function that didn't work, and resubmit by placing the
    ## cursor somewhere in the function and
    C-c C-f
    ## Or you could've selected a region (using the mouse, or keyboard 
    ## via setting point/mark) and 
    C-c C-r
    ## Or you could step through, line by line, using 
    C-c C-n
    ## Or just send a single line (without moving to the next) using
    C-c C-j
    ## To fix that error in syntax for the "rchisq" command, get help
    ## by
    C-c C-v rchisq


4:    Data Analysis (S object is real)
    ## Start up S-PLUS 3.x, in a process buffer (this will be *S+3:1*) 
    M-x S+3

    ## Work in the process buffer.  When you find an object that needs 
    ## to be changed (this could be a data frame, or a variable, or a 
    ## function), dump it to a buffer:
    C-c C-d my.cool.function

    ## Edit the function as appropriate, and dump back in to the
    ## process buffer  
    C-c C-b

    ## Return to the S-PLUS process buffer
    C-c C-y
    ## Continue working.

    ## When you need help, use 
    C-c C-v rchisq
    ## instead of entering:   help("rchisq")




-- 
dirk.eddelbuettel.com | @eddelbuettel | edd using debian.org