# R for Macintosh FAQ/DOC

## Version for `R 1.3.1`

Changes specific to this version:

Added the "Config" menu

Fixed a bug in the lapack module. Complex functions are now available.

Added MPW makefiles to build standard libraries and modules

Added experimental script to build R via Apple's MRC compiler

Now R needs a new shared library "f2cLib" that will increase portability for all fortran based packages

Added support for apple events. R begins to be a scriptable application. Very limited support by now but will increase soon. Some demo scripts have been added.

link.html.help() function has been added by picking windows code.

rmac-FAQ.html
This is the ReadMe file of R for Macintosh Application.

We discuss here the following topics:

* NEWS
* THE NEW GUI
* EXTERNAL EDITOR INTERACTION
* MEMORY
* SPECIFING OPTIONS: the .Renviron file
* R HELPERS
* SYSTEM REQUIREMENTS
* FIXED BUGS
* KNOWN BUGS
* SHORT FAQ

NEWS
There are several enanchements in this release. Most of them concern the user interface of R application but one of the most important novelty is that now
R runs both on MacOS and MacOS X using Carbon technology. This means that when you run R from MacOS X it run natively under the new System without calling the Classic Compatibility Module. The use of R under MacOS X takes lots of advantages starting from the new Aqua look.

As this version is based on the new Carbon technology some new bugs can appear that we were'nt able to found before releasing R officially.

Any feedback is then welcome at stefano.iacus@unimi.it

THE NEW GUI
Several menus are now present from this release. The structure of the menus is as follows with a brief description.

Menu | Item | Shortcut | Brief description
Apple |  |  |
| About R |  | Opens the R information dialog
File |  |  |
| New Edit Window | N | Opens an empty editable window. You can usethis as an internal editor for R. If the current active window isa graphic device window than a new macintosh() device will be opened.
| Edit Object | E | Is the equivalent of "edit(object)"
| Source File | O | Opens a file and sources it. This is equivalent to "source(file)"
| Open File For Editing |  | Opens a file in an editable window.Useful when you want to modify an existing script and test it.
| File Show | F | Open a file in a non editable window. This isthe equivalent of R command "show.file(file)"
| Load Workspace File | L | If you want to load a wspace image otherthan ".RData"
| Save Workspace As |  | If you want to save an image file other the ".RData"
| Page Setup |  | Calls the printer driver page setup
| Print | P | Print the text window (R Console etc) or the imagein the graphic device window. The image is rescaled to the page dimension of your printer.
| Save | S | Save the window. This could be the content ofthe R Console i.e. your current R session any text window or the graphic device window.
| Save As... |  | Save the window. This could be the content ofthe R Console i.e. your current R session any text window or the graphicdevice window. This menu acts as a standard "Save As" menu so you have to specify each time the filename.
| Close | W | Closes the current window. If it is the R Console window than it is interpreted as quitting R.
| Quit | Q | This menu item is on the Apple Menu under OSX
Edit |  |  |
| Undo | Z |
| Cut | X |
| Copy | C | If you use it on a graphic device window theimage is copied to the clipboard (see also knownbugs)
| Paste | V |
| Copy & Paste |  | You copy some text and the resultis pasted into the R Console window. You use thiswhen you select a piece of R code of text windowand then you want to R to execute it. This is quite useful when you want to test part of your script of the examples of an help window
| Clear |  |
| Select All | A |
| Goto line |  | Active only for editable windows. It moves thecursor to a certain line
Tools |  |  |
| Show Workspace |  | It is equivalent to "ls()"
| Clear Workspace |  | It is equivalent to "rm(list=ls())"
| Load Workspace |  | Loads the ".RData" file; equivalentto load(".RData")
| Save Workspace |  | Save the workspace to ".RData"; equivalentto "save.image()"
| Load History |  | It is equivalent to "loadhistory()"
| Save History |  | It is equivalent to "savehistory()"
| Show History |  | It is equivalent to "history()"
| Change Working Directory | D | Allows the user to change the workingdirectory by using a standard dialog
| Show Working Directory |  | It is equivalent to "getwd()"
| Reset Working Directory |  | It is equivalent to "setwd(R.home())"
| Show Libraries |  | It is equivalent to "library()"
| Show DataSets |  | It is equivalent to "data()"
Windows |  |  |
| R Console |  | This menu contains by default only the "R Console" item and it is dynamically changed by appending/removingthe names of any new/closed window
Config |  |  |
| Allow Interrupt |  | It is equivalent to set the option "Interrupt=TRUE" in the .Renvironment config file but this can be changed at runtime.
| On Open Source |  | It is equivalent to set the option "OnOpenSource=TRUE" in the .Renvironment config file but this can be changed at runtime. Useful to work with external editor such as Alpha.
Help |  |  |
| R Help | ? | It is equivalent to "help.start()"
| Help On Topic |  | Opens a dialog where the user canspecify an item he or she wants to see. Equivalentto "help(topic)" or "?topic"
| Search Help On |  | Opens a dialog where the user can specifyan argument to have help on. It is equivalent to"help.search("topic")"
| Run An Example |  | Opens a dialog where the user can specifyan item of which he or she wants to run anexample of. It is equivalent to "example(topic)".

About R windows.
Normally R opens windows to let 80 character/columns to be displayed. The size of the windows is calculated on the basis of the size of the font used.
For non fixed fonts the algorithm can fail so the window can result a bit larger or smaller then needed.
R windows are opened in cascade for each class (edit windows, file show windows and graphic windows). This functionality does not work on MacOS X yet.

EXTERNAL EDITOR INTERACTION
From release 7.4.1 of the famous Alpha editor, there is a (tcl) mode called S+/R.
When you open a file in Apha with the extension ".s" or ".r" this new mode will be installed and you will in the Alpha menu bar the "S+/R" menu. Of this menu you can use "Process File" or "Process Selection" to interact with R. By default Alpha sends an “open” command to R and by default R opens a file in a non editable window (equivalent to the “File Show” menu). If you want R to source a file you should modify the .Renviron file accordingly (see below). In particular, the option “OnOpenSource” is set by default to "FALSE". You should set it to "TRUE". You can change this when R is still running by simply editing the .Renviron file. Use "Open File For Editing" from the "File" menu and select the file ".Renviron". Find the keyword "OnOpenSource" and set it to "TRUE" (i.e. OnOpneSource=TRUE). The latest version of Alpha can be found at http://www.alpha.olm.net

MEMORY
Under MacOS you should reserve a fixed amount of memory to each application. As R is just an application, you need to set this to a bigger amount of memory if for some reason R went out of memory. To do this, go to the Finder and select the R aplication icon. Then with CMD+I key obtain the Information for R. Select "Memory" and the fix the amount of memeory you need. Under MacOS X, there is no need to reserve memory for R. R will used as much memory as it needs.

SPECIFING OPTIONS: the .Renviron file
In this file you can specify some of the options. This is not standard for general MacOS/X applications because it currently repleaces the Preferences one should expect. But, as we have not yet decided which and what number of preferences items the user can specify, for the time being this is the only flexible way to take care of user options.
The environment file is used by R application both to simulate the enviroment on a standard Unix or Windows system and both to set user options.
You can always use "Sys.getenv()" to see which options are enabled/set.
In this file you can specify font names for the R Console and for the graphic device as well as their sizes. The .Renviron file looks like this: an option is a "Rkey" with its "keyvalue" that you can specify in new separate line as follows RKey=keyvalue. Consider that RKey=keyvalue and RKey = keyvalue are different, that means that blanks/spaces are significant. "RKey" and "keyvalue" are case sensitive. A symbol "#" at the beginning of a line means that this is a commented out line.
You can find more details on that in the .Renviron file itself.

Here are the options you can specify:

Lenght of the history size:
---------------------------

# The history size
# Default: RHISTSIZE=512
RHISTSIZE=512

R behaviour when R application receive a "break" event:
-------------------------------------------------------

# R can handle user breaks to
# interrupt lengthy calculations
# or output. As this code is not
# yet optimized, by default R
# does not accept user breaks.
# If the "Interrupt" switch
# is set to TRUE then R intercept
# user breaks. With this swtich on
# R is a bit slower than with the
# switch off
# Default: Interrupt=FALSE
This can be changed at runtime also via the Config menu.

R behaviour when R application receive an "open" event:
-------------------------------------------------------

# Wheter to show or source a file
# You should set this to TRUE if you
# want Alpha be your external editor
# Default: OnOpenSource=FALSE
OnOpenSource=FALSE

This means that when you drag a file on top of the R icon or you submit something from an external editor, R application simply open it (FALSE) or sources it (TRUE). If the file is a worspace image file, then R loads that workspace. This can be changed at runtime also via the Config menu.

Tab size of text windows:
-------------------------

# The Tab size to use in text windows
# range [1,20]
# Default: TabSize=5
TabSize=5

Setting the text size of text and R Console windows:
----------------------------------------------------

# TextSize to be used in text windows
# range [8,14]
# Default: TextSize=12
TextSize=12

Macintosh device resolution:
----------------------------

# ScreenRes
# Useful values is only 72. Possibile other values
# are 144, 300, 600 but you should not use them unless
# you know exactly what you are doing ! So, please,
# don't change this parameter.
# Default: ScreenRes=72
ScreenRes=72

Name of the font for the R Console or text windows:
---------------------------------------------------

# FontName: this is the font used in text windows.
# There are several possibilities for this.
# You can specify any font you like but you should
# prefere a monospaced font. If the Monaco will be used instead.
# Font names are not case sensitive i.e.
# FontName=monaco and FontName=MoNacO are the same.
# If your font name includes spaces you should provide them
# without using quotes, i.e.
# FontName=Times New Roman
# Default: FontName=monaco
FontName=monaco

Name of the font for the Macintosh graphic device:
--------------------------------------------------

# GraphFontName: this font is used for graphic windows.
# There are several possibilities for this.
# If the font is not usable by R application, then
# the font Helvetica will be used instead.
# Font names are not case sensitive i.e.
# FontName=monaco and FontName=MoNacO are the same.
# If your font name includes spaces you should provide them
# without including quotes, i.e.
# FontName=Times New Roman
# Default: GraphFontName=helvetica
GraphFontName=helvetica

R HELPERS
* If you want to use an external editor we suggest you to use Alpha version 7.4.1 or newer that contains a S+/R mode. Alpha home page is
http://www.alpha.olm.net
* You also need MacZip to use the unzip feature of R. MacZip home page is
http://ww.sitec.net/maczip

SYSTEM REQUIREMENTS

To run the R application you need at least 42MB of free memory for the application itself you work under MacOS but there is no limitations under MacOS X as virtual memory is always on.
You need the latest version of the CarbonLib library from Apple. At the time of this release, version 1.2.5 is the current non developer release. Normally it is included in System 9.1 and X.
Now R needs the f2cLib shared library to run. This library is distributed with R but in case you miss it you can found it here.
The minimum System version release is 8.6 (+ CarbonLib library).
You no longer need the WasteLib library.

FIXED BUGS
This version has several bugs fixed. Mostly GUI incongruencies and problems have been resolved and few R internal numerical bugs. You have signalled a bug but this has not yet been fixed, please "don't give up" but send us again your feedback (stefano.iacus@unimi.it)

- There was an annoying bug concerning the edit menus that on some (almost random) situations was disabled by R so no cut&paste was then possible.
- Edit object on non existent R obejct produced a grabbled edit window.
- Herhey fonts where not displayed correctly or at all unless the user clicked on the graphic window rotated fonts where cutted on top
- Numerical problems with gamma function and polyroot. Now R pass the tests
- Windows menus produced in some situations some strange
- The graphic device has been completely rewritten now it is faster and resizing of windows is handled correctly.
- Copying to the clipboard images will non longer produce graphic titles/texts printed twice.

KNOWN BUGS

- In some situations R stops execution giving an error like this:

Error in plot.xy(xy.coords(x, y), type = type, pch = pch, col = col, bg = bg, :
negative length vectors are not allowed
To solve this problem you just need to resize the device window to a bigger size

- On MacOS X copying to the clipboard an image or saving it in a file produces a picture without text in it. This problem is (probably) due to the fact that the fonts we use are saved as polygons/vectors and not as images.
- From version 1.2.2, at startup time you can run scripts by selecting input and output file and options (this is usefule when you want to run tests/checks). Both under MacOS and MacOS X you cannot choose a file that is outside the directory where the R application is. This problem is not due to the R application but to a bug in Sioux Interface provided by the compiler. This problem will be fixed with the next release of the compiler.
- For some reason MacZip does not intercat too much with R under MacOS X. Moreover MacZip has not yet been “carbonized” so when R calls it to uncompress items it also starts up Classic Environment. We suggest to uncompress the help and examples files directly by using Stuffit Expander that is part of the utilities provided with System X.
- This version of R and Adobe ATM are incompatible. We are looking at the problem. The solution is that you should switch ATM off before running R. (Thanks to R. Gill for feedback on this bug)
- Internet functionality is not available yet. We are working on this.
- Mathematical expressions are not yet well spaced moreover, mathemathic symbols are not rotated.

SHORT FAQ

Q | How can I work on a separate directory for each of my projects?
A | Under Unix you usually create a directory, go into it and launch R. Under MacOS you can create a directory and put all the files that you need there. You then (or before) run R in its own directory and use the menu item "Tools->Change Working Directory" to change the current working directory to directory you have created. You can then work as you do in Unix. You can save/load workspace image to this directory, as well as the command history files. You can then reload these next time you work.
Q | How can I interrupt lengthy operations or output ?
A | You can now use the standard Macintosh control break sequence, that is you should press "Cmd option" plus "." (dot). This will interrupt any R loops.
Q | How can I change memory settings for R ?
A | You cannot use the standard settings as on other platforms. You should assign memory to R from the Finder/Information dialog for R application. See Section "Memory" above.