Issue #58: checkpoint [ci skip]

docs/clientInstallation.md

@@ -1,4 +1,7 @@
-##tODE Client Installation
+#tODE Client Installation
+
+**Before installing a remote client, you should seriously consider using [ssh X11 forwarding][8]. 
+With **[ssh X11 forwarding][8]**, you install an X11 client on the server, and install an X11 server on your client, instead of installing a tODE client.**
 
 tODE clients may be installed on **Linux**, **Mac** or **Windows**. 
 
@@ -58,3 +61,4 @@ Here's the [list of scripts that can be used on the client machine][7].
 [5]: images/descriptionWorkspace.png
 [6]: ../bin/stones
 [7]: ../bin/README.md#client-scripts
+[8]:

docs/osPrereqs/osPrereqs.md

@@ -1 +1,98 @@
-#OS prerequisites
+#Operating System Prerequisites
+
+##Required packages
+The GsDevKit server can be installed on Linux or Mac OS X.
+
+The following packages are required for a GsDevKit installation:
+- 32 bit libraries - needed to run Pharo (headless)
+- curl             - needed by FileTree
+- git              - needed by GsDevKit and tODE
+- PAM              - needed by GemStone server
+- ssl              - needed by GemStone server
+- unzip            - needed by FileTree
+- wget             - needed by bin/installGemStone script
+- gdb, pstack      - needed by GemStone to produce C stack traces
+- freetype         - needed by Pharo (headful) on Linux for using platform-specific (monospaced) fonts
+
+See the the prerequisite installation guide for your platform for detailed instructions on installing the required prerequisites:
+- [GsDevKit prerequisites for Ubuntu 12.04][55]
+- [GsDevKit prerequisites for Ubuntu 14.04][56]
+- [GsDevKit prerequisites for OS X10.9][57]
+
+##Optional Packages
+###Client/Server Configurations
+A [GemStone server][8] is made up of several different processes:
+
+![object server][9]
+
+In a GsDevKit installation the `Server Processes` in the diagram above are co-located on a single machine and I will use the term **stone** to refer to a the [GemStone server][8] processes.
+
+The `Application` in the diagram above corresponds to a tODE client.
+
+In general GemStone may be configured in 4 different ways, all processes co-located on a single machine]:
+1. [stone, gem and application (tODE) running on same machine][11].
+2. stone and gem running on the same machine, application (tODE) running on second machine.
+
+   ![gem process on server node][14]
+
+3. stone running on one machine, gem and application (tODE) running on second machine.
+
+   ![gem process on remote node][13]
+
+4. stone runninin on one machine, gem running on a second machine, and application (tODE) running on a third machine.
+
+   ![gem process and application process on remote nodes][12]
+
+With the [Community Edition License][15], you are not permitted to run with remote gem processes (options 3 and 4).
+
+The tODE client is written in Pharo and uses [GemBuilder for C][1] (GCI) for communicatine with the stone.
+
+
+tODE runs as an [RPC application][3] and establishes a network connection to the stone by initally connecting to a well-known port on the [GemStone netldi process][5].
+
+
+
+
+Basically you have three options:
+
+1. [Local display, local stone, local tODED](#)
+2. [Local display, remote stone, remote tODE](#)
+3. [Remote display, local stone, local tODE](#)
+
+####Local display, local stone, local tODE
+
+![local stone/gems][7]
+
+[Run tODE and stone on same node][4] where the GCI and X11 use the loopback interface for communication.
+
+####Local display, remote stone, remote tODE
+
+![local stone/gems][6]
+
+[Run tODE and stone on same node][4] where the GCI uses the loopback interface for communication and X11 uses the local area network (or WAN) for communication between the X11 client and server (on remote client). 
+
+####Remote display, local stone, local tODE
+
+![local stone/gems][7]
+
+[Run tODE and stone on different nodes][2] where the GCI communication uses the local area network (or WAN) and the tODE client uses the loopback interface (on remote client) for communication.
+
+
+[1]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-GemBuilderforC-3.2.pdf
+[2]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/3-Distributed.htm#88520
+[3]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/2-Clients.htm#pgfId-83078
+[4]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/2-Clients.htm#47882
+[5]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/3-Distributed.htm#pgfId-82455
+[6]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/3-Distributed-1.png
+[7]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/2-Clients-1.png
+[8]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/1-Server.htm#pgfId-1332187
+[9]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/1-Server-1.png
+
+[10]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/3-Distributed-3.png
+[11]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/2-Clients.htm#pgfId-82959
+
+[12]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/3-Distributed-8.png
+[13]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/3-Distributed-7.png
+[14]: http://downloads.gemtalksystems.com/docs/GemStone64/3.2.x/GS64-SysAdmin-3.2/resources/3-Distributed-6.png
+
+[15]: http://gemtalksystems.com/licensing/#CWELicensing

docs/osPrereqs/ubuntu14.04.md

@@ -1,12 +1,16 @@
 # GsDevKit prerequisites for Ubuntu 14.04 
-It is recommended that you [Install ssh (optional)](#install-ssh-optional), since you can [run a script to the install prerequisite packages](#osPrereqs-bash-script).
+It is recommended that you [Install ssh (optional)](#install-ssh-optional).
+Besides the obvious advantages of secure remote logins and secure remote file copying, ssh gives you flexibility to:
+  - run tODE locally and log into remote servers via **ssh port forwarding**
+  - run tODE on remote server and host display on local X server via **ssh X11 forwarding**
+  - use the osprereqs script to install the platform prerequisites
 
-If you decide not to [run the script](#osPrereqs-bash-script), then following the manual instrructions in each section:
+If you decide not to [run the script](#osPrereqs-bash-script), then following the manual instructions in each section:
 
 3. [Install ssh (optional)](#install-ssh-optional)
    - [osPrereqs bash script](#osPrereqs-bash-script)
 1. [Install Basic Prerequisites (required)](#install-basic-prerequisites-required)
-2. [Install X11 Client (optional)](#install-x11-client-optional)
+2. [X11 forwarding](#install-x11-forwarding-optional)
 
 ##Install ssh (optional)
 I recommend that you start by [installing ssh][2] on your server.
@@ -52,8 +56,7 @@ sudo apt-get -y install pstack
 sudo /bin/su -c "echo 'kernel.yama.ptrace_scope = 0' >>/etc/sysctl.d/10-ptrace.conf"
 ```
 
-##X11 Client (optional)
-If you want run the Pharo client using [X11 forwarding][1] with `ssh`, then you need to install the **X11 client**:
+##X11 forwardingIf you want run the Pharo client using [X11 forwarding][1] with `ssh`, then you need to install the **X11 client**:
 
 ```
 sudo apt-get -y install libgl1-mesa-dev:i386

docs/portForwardingForRemoteLogins.md

@@ -1,4 +1,4 @@
-# Using Port Forwading for Remote logins
+# Using Port Forwading for remote tODE clients
 
 1. [Intro](#intro)
 2. [Netldi Setup](#netldi-setup)
@@ -24,7 +24,7 @@ The *well-known `netldi` port number* is the port number specified in `netLDI` f
 
 Normally the *child process port* is randomly assigned, but since we need to set up the port forwarding ahead of time, we will have to use the `startnetldi` command's `-p` option to define a port range.
 In our case the *port range* will be a single port number and we'll use `55325` in this example.
-Before starting a `netldi` you need to make sure that all of the required environmental variables (**GEMSTONE**, **EMSTONE_NRS_ALL**, etc.) are defined.
+Before starting a `netldi` you need to make sure that all of the required environmental variables (**GEMSTONE**, **GEMSTONE_NRS_ALL**, etc.) are defined.
 
 ##SSH Port Forwarding Server-side