[ESS] README organization
Rodney Sparapani
rsparapa at mcw.edu
Wed Dec 3 18:19:59 CET 2008
Re-sending due to bigness:
Rodney Sparapani wrote:
> Andreas Kiermeier wrote:
>> Hi Rodney,
>>
>> would it be possible to put a small table of contents at the top of
>> the README file - like the one you showed. That way people can see
>> what's covered in the file, and roughly where that is?
>>
>> Cheers,
>>
>> Andreas
>>
>
> Hi Andreas:
>
> Ok, that's another good suggestion. However, I am no makeinfo expert.
> But, this seems doable. For those that are makeinfo experts, or want
> to try this at home, here are the details (comments welcome):
>
> In Makeconf, comment out the following line
>
> MAKETXT = $(MAKEINFO) --no-validate --no-headers --no-split -o -
>
> and provide the following replacement
>
> MAKETXT = $(MAKEINFO) --no-validate --plaintext --no-split -o -
>
> then add the following Table of Contents to doc/readme.texi somewhere
> near the top (I put it after the intro, see below):
> @ifplaintext
> Table of Contents
>
> @itemize @bullet
> @item License
> @item Stability
> @item Requirements
> @item Latest Version
> @item Installation
> @item Starting an ESS Process
> @item New Features
> @item Current Features
> @item Reporting Bugs
> @item Mailing Lists
> @item Authors
> @end itemize
> @end ifplaintext
>
> and then in the doc directory do a
>
> make ../README
>
> or for us real Unix veterans
>
> gmake ../README
>
> If the comments are positive, then I'll commit this last suggestion
> (the other suggestion about re-organization will appear in 5.3.10).
>
> Thanks,
>
> Rodney
>
> 1 General Information: README
> *****************************
>
> This is the README file for the distribution of ESS version
>
> 5.3.9
>
> ESS is a GNU Emacs and XEmacs mode for interactive statistical
> programming and data analysis. Languages supported: the S family (S,
> S-PLUS and R), SAS, BUGS/JAGS, Stata and XLispStat. ESS grew out of the
> desire for bug fixes and extensions to S-mode and SAS-mode as well as a
> consistent union of their features in one package.
>
> Installation instructions are provided in sections for both Unix and
> Windows; see below.
>
> The current development team is led by Martin Maechler since August
> 2004. Former project leader A.J. (Tony) Rossini
> (<rossini at blindglobe.net>) did the initial port to XEmacs and has been
> the primary coder. Martin Maechler (<maechler at stat.math.ethz.ch>) and
> Kurt Hornik (<Kurt.Hornik at R-project.org>) have assisted with the S
> family and XLispStat. Stephen Eglen (<stephen at gnu.org>) has worked
> mostly on R support. Richard M. Heiberger (<rmh at temple.edu>) has
> assisted with S/S-PLUS development for Windows. Richard and Rodney A.
> Sparapani (<rsparapa at mcw.edu>) have done much of the work improving SAS
> batch and interactive support. Rodney has also extended ESS to support
> BUGS/JAGS and has an interest in improving Stata support.
>
> We are grateful to the previous developers of S-mode (Doug Bates, Ed
> Kademan, Frank Ritter, David M. Smith), SAS-mode (Tom Cook) and
> Stata-mode (Thomas Lumley).
>
> Table of Contents
>
> * License
>
> * Stability
>
> * Requirements
>
> * Latest Version
>
> * Installation
>
> * Starting an ESS Process
>
> * New Features
>
> * Current Features
>
> * Reporting Bugs
>
> * Mailing Lists
>
> * Authors
>
> 1.1 License
> ===========
>
> ESS is free software; you can redistribute it and/or modify it under
> the terms of the GNU General Public License as published by the Free
> Software Foundation; either version 2, or (at your option) any later
> version.
>
> ESS is distributed in the hope that it will be useful, but WITHOUT
> ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
> FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
> in the file COPYING in the same directory as this file for more details.
>
> 1.2 Stability
> =============
>
> Versions 5.3.x are meant to be release-quality versions. While some
> new features are being introduced, we are cleaning up and improving the
> interface. We know about some remaining documentation inconsistencies.
> Patches or suggested fixes with bug reports are much appreciated!
>
> 1.3 Requirements
> ================
>
> ESS has been tested with
>
> * R >=0.49
>
> * S-PLUS 3.3-4, 4.5, 2000, 5.0-1, 6.0-2, 7.0, 8.0
>
> * S4
>
> * SAS >=6.12
>
> * BUGS 0.5, 0.6
>
> * JAGS 1.0
>
> * Stata >=6.0 (command line only)
>
> on the following platforms
>
> * Linux/x86 (all)
>
> * Solaris (all)
>
> * MS Windows 98/NT/2000/XP (R, S-PLUS, SAS interactive only, and
> BUGS)
>
> * Apple Mac OS X 10.4-5 (R, JAGS, Stata)
>
> with the following versions of emacs
>
> * GNU Emacs 20.3-7, 21.1, 21.3-4, 22.1
>
> * XEmacs 21.4.0-8, 21.4.9-13(1), 21.4.14-15, 21.4.17-21 (betas not
> supported, but 21.5.23+ may work)
>
> ---------- Footnotes ----------
>
> (1) require the files.el patch to revert-buffer for the Local
> Variables updating problem
>
> 1.4 Getting the Latest Version
> ==============================
>
> The latest released version of ESS is always available on the web at:
> ESS web page (http://ess.r-project.org) or StatLib
> (http://lib.stat.cmu.edu/general/ESS/)
>
> The latest development version of ESS is available via
> `https://svn.R-project.org/ESS/', the ESS Subversion repository. If
> you have a Subversion client (see `http://subversion.tigris.org/'), you
> can download the sources using:
> % svn checkout https://svn.r-project.org/ESS/trunk PATH
> which will put the ESS files into directory PATH. Later, within
> that directory, `svn update' will bring that directory up to date.
> Windows-based tools such as TortoiseSVN are also available for
> downloading the files. Alternatively, you can browse the sources with a
> web browser at: ESS SVN site (https://svn.r-project.org/ESS/trunk).
> However, please use a subversion client instead to minimize the load
> when retrieving.
>
> If you remove other versions of ESS from your emacs load-path, you
> can then use the development version by adding the following to .emacs:
>
> (load "/path/to/ess-svn/lisp/ess-site.el")
>
> Note that https is required, and that the SSL certificate for the
> Subversion server of the R project is
>
> Certificate information:
> - Hostname: svn.r-project.org
> - Valid: from Jul 16 08:10:01 2004 GMT until Jul 14 08:10:01
> 2014 GMT
> - Issuer: Department of Mathematics, ETH Zurich, Zurich,
> Switzerland, CH
> - Fingerprint:
> c9:5d:eb:f9:f2:56:d1:04:ba:44:61:f8:64:6b:d9:33:3f:93:6e:ad
>
> (currently, there is no "trusted certificate"). You can accept this
> certificate permanently and will not be asked about it anymore.
>
> 1.5 Installation (from tar file)
> ================================
>
> 1.6 Unix installation
> =====================
>
> 1. `cd' to a directory where you keep emacs lisp files, or create a
> new directory (for example, `$HOME/ess') to hold the distribution.
> This directory will be referred to below as "the ESS distribution
> directory".
>
> _Note for XEmacs packages:_ ESS is no longer available as an
> XEmacs package. But, you can still install ESS into the XEmacs
> package system by choosing
> `ESSDIR'=`PREFIX/lib/xemacs/site-packages'. ESS requires that the
> XEmacs sumo tarball (all XEmacs packages combined) also be
> installed. For information on installing XEmacs packages, follow
> this link: Quickstart Package Guide
> (http://www.xemacs.org/Documentation/packageGuide.html).
>
> 2. Retrieve the latest version from ESS downloads area
> (http://ess.r-project.org/downloads/ess) to `ESSDIR'.
>
> 3. Extract the files from the disribution.
> If you are using GNU tar, `tar zxf ess-VERSION.tgz'.
> Otherwise, `gunzip < ess-VERSION.tgz | tar xf -',
>
> The `tar' command will create the subdirectory `ess-VERSION' and
> install the files there.
>
> 4. Edit the file `ESSDIR/ess-VERSION/lisp/ess-site.el' as explained
> in the comments section of that file.
>
> 5. If you are using GNU Emacs add the line
> (load "ESSDIR/ess-VERSION/lisp/ess-site")
> to `$HOME/.emacs'. For XEmacs, if you followed the XEmacs package
> system installation advice, add the line
> (require 'ess-site)
> to `$HOME/.xemacs/init.el'. Otherwise, for XEmacs, add the line
> (load "ESSDIR/ess-VERSION/lisp/ess-site")
> to `$HOME/.xemacs/init.el'.
>
> 6. That's it! ESS is now ready to use. (The remaining step below is
> only for a custom installation.) To edit statistical programs,
> just open files with the requisite extensions (`.R' for R, `.sas'
> for SAS, `.bug' for BUGS, etc.). To start a statistical process
> within emacs, such as R, type `M-x R'.
>
> 7. (OPTIONAL) READ THIS ITEM THOROUGHLY BEFORE STARTING:
>
> If you want to place the compiled files in other locations edit the
> `LISPDIR', `INFODIR' and `ETCDIR' entries in Section 1 of
> `Makeconf' in the `ESSDIR/ess-VERSION' directory (if you are using
> XEmacs, then uncomment the XEmacs subsection in Section 1).
>
> You can compile those files by:
> make all
>
> When that completes successfully, install the compiled files:
> make install
>
>
> 1.7 Microsoft Windows installation
> ==================================
>
> For Microsoft Windows installation, please follow the next steps.
>
> 1. `cd' to a directory where you keep emacs lisp files, or create a
> new directory (for example, `c:\ess\') to hold the distribution.
> This directory will be referred to below as "the ESS distribution
> directory".
>
> _Note for XEmacs packages:_ ESS is no longer available as an XEmacs
> package. But, you can still install ESS into the XEmacs package
> system by choosing `ESSDIR'=`PREFIX\XEmacs\site-packages'. ESS
> requires that the XEmacs sumo tarball (all XEmacs packages
> combined) also be installed. For information on installing XEmacs
> packages, follow this link: Quickstart Package Guide
> (http://www.xemacs.org/Documentation/packageGuide.html).
>
> 2. Retrieve the latest zip file (`ess-VERSION.zip') from ESS
> downloads area (http://ess.r-project.org/downloads/ess) and store
> it in the ESS distribution directory. Be aware that http browsers
> on Windows frequently change the "." and "-" characters in
> filenames to other punctuation. Please change the names back to
> their original form.
>
> 3. Extract all the files from `ess-VERSION.zip' into the ESS
> distribution directory as `c:\ess\ess-VERSION\'. (It is possible
> to unpack the zip archive in Windows Explorer by double clicking
> on the folder; you should then see a new folder called
> `ess-VERSION'. Drag that folder into your ESS distribution
> directory.)
>
> 4. If you are using GNU Emacs add the line
> (load "ESSDIR/ess-VERSION/lisp/ess-site")
> to `%HOME%\.emacs'. For XEmacs, if you followed the XEmacs
> package system installation advice, add the line
> (require 'ess-site)
> to `%HOME%\.xemacs\init.el'. Otherwise, for XEmacs, add the line
> (load "ESSDIR/ess-VERSION/lisp/ess-site")
> to `%HOME%\.xemacs\init.el'. _Note:_ Both GNU Emacs and XEmacs
> require that the HOME environment variable be set on your system,
> otherwise, your initialization file will not be utilized, and
> therefore, ESS will not work.
>
> After saving your initialization file, ESS is now installed.
> Start a new emacs and you should be ready to use ESS. For
> example, to edit statistical programs, load the files with the
> requisite extensions (".sas" for SAS, ".S" or "s" or "q" or "Q"
> for S-PLUS, ".r" or ".R" for R, and ".lsp" for XLispStat). One
> further step is needed if you wish to run statistical processes,
> see below.
>
> 5. To run statistical processes under ESS, Windows users will need to
> make sure that the directories for the software they will be using
> is in the PATH environment variable. On Windows 9x, add lines
> similar to the following to your `c:\autoexec.bat' file:
> path=%PATH%;c:\progra~1\insightful\splus70\cmd
> On Windows NT/2000/XP, add the directories to the PATH using the
> `My Computer/Control Panel/System/Advanced/Environment Variables'
> menu. Note that the directory containing the program is added to
> the PATH, not the program itself. One such line is needed for
> each software program. Be sure to use the abbreviation `progra~1'
> and not the long version with embedded blanks. Use backslashes
> "`\'".
>
> An alternative, for R users, is that rather than adjusting the PATH
> variable, you can add the following to your emacs initialization
> file (and restart emacs):
> (setq inferior-R-program-name
> "c:/progra~1/R/R-2.2.1/bin/Rterm.exe")
> This assumes that you have installed R-2.2.1 in the default
> location. Change the path otherwise to point to other locations.
>
> Windows users who place S-PLUS anywhere other than the default
> location will also need to add the following three lines (properly
> adjusted for their location) to their `%HOME%\.emacs' or
> `%HOME%\.xemacs\init.el' file:
> (setq-default inferior-S+6-program-name
> "c:/progra~1/Insightful/SPLUS70/cmd/Splus")
> (setq-default inferior-Sqpe+6-SHOME-name
> "c:/progra~1/Insightful/SPLUS70")
> (setq-default inferior-Sqpe+6-program-name
> "c:/progra~1/Insightful/SPLUS70/cmd/Sqpe.exe")
> The above example uses the default location of S-PLUS in
> `c:\progra~1\Insightful'. Please note that ESS considers S-PLUS
> 6, 7, and 8 to be variants of S+6.
>
> These users may also need to modify the emacs variable
> `ess-SHOME-versions' to match their installation in order to get
> the full set of S-PLUS versions on their machine into the `ESS'
> menu.
>
> To start the S-PLUS [678].x GUI from ESS under emacs:
> 1. If you use Cygwin bash as your primary shell, then
> M-x S
> (or `M-x S+6').
>
> 2. If you use the MSDOS prompt window as your primary shell, then
> M-x S+6-msdos
> You will then be asked for a pathname ("S starting data
> directory?"), from which to start the process. The prompt will
> propose your current directory as the default. ESS will start the
> S-PLUS GUI. There will be slight delay during which emacs is
> temporarily frozen. ESS will arrange for communication with the
> S-PLUS GUI using the DDE protocol. Send lines or regions from the
> emacs buffer containing your S program (for example, `myfile.s')
> to the S-PLUS Commands Window with the `C-c C-n' or `C-c C-r' keys.
> (If you are still using S-PLUS 4.x or 2000,\ then use `M-x S+4' or
> `M-x S+4-msdos'.)
>
> To start an S-PLUS [678].x session inside an emacs buffer--and
> without the S-PLUS GUI:
> M-x Sqpe
> (or `M-x Sqpe+6').
> This works with both the bash and msdos shells. You will then be
> asked for a pathname ("S starting data directory?"), from which to
> start the process. The prompt will propose your current directory
> as the default. You get Unix-like behavior, in particular the
> entire transcript is available for emacs-style search commands.
> Send lines or regions from the emacs buffer containing your S
> program (for example, `myfile.s') to the *S+6* buffer with the
> `C-c C-n' or `C-c C-r' keys. Interactive graphics are available
> with Sqpe by using the java library supplied with S-PLUS 6.1 and
> newer releases. Enter the commands:
> library(winjava)
> java.graph()
> Graphs can be saved from the `java.graph' device in several
> formats, but not PostScript. If you need a PostScript file you
> will need to open a separate `postscript' device. (If you are
> still using S-PLUS 4.x or 2000, then use `M-x Sqpe+4'.)
>
> To connect to an already running S-PLUS GUI (started, for example,
> from the S-PLUS icon):
> M-x S+6-existing
> or
> M-x S+6-msdos-existing
> You will then be asked for a pathname ("S starting data
> directory?"), from which to start the process. The prompt will
> propose your current directory as the default. ESS will arrange
> for communication with the already running S-PLUS GUI using the
> DDE protocol. Send lines or regions from the emacs buffer
> containing your S program (for example, `myfile.s') to the S-PLUS
> Commands Window with the `C-c C-n' or `C-c C-r' keys. (If you are
> still using S-PLUS 4.x or 2000, then use `M-x S+4-existing' or
> `M-x S+4-msdos-existing'.)
>
> If you wish to run R, you can start it with:
> M-x R
>
> XLispStat can not currently be run with
> M-x XLS
> Hopefully, this will change. However, you can still edit with
> emacs, and cut and paste the results into the XLispStat *Listener*
> Window under Microsoft Windows.
>
> 6. That's it!
>
More information about the ESS-help
mailing list