Adjust README.md to be more eplicit about osimctrl current goals and provide better instructions

infrastructure/control/osimctrl/README.md

@@ -1,23 +1,48 @@
 # README #
 
-A simple couple of scripts for starting components of OpenSimulator as a user rather
-than root.  Incorporates checks to avoid starting a component instance if one
-is already running.
+A simple couple of scripts for starting components of OpenSimulator.  This is an
+alternative to the /etc/init.d script found elsewhere in this repository.
 
-Starts named screen instances for the components.  To shutdown the components
-you need to connect to the appropriate screen instance and do this manually.
+These scripts work using screen instances.
 
-# Files #
+It would be possible to make these scripts much more sophisticated (e.g.
+automatic detection of whether the grid services are running before starting a
+simulator, etc.).  
 
-## simctrl.py ##
+However, currently they are deliberately being kept simple in order to keep the
+user close to what is really happening.  This is to facilitate debugging and the
+ability to deal with the many possible failure conditions.  This might change in
+the future.
 
-This will control a simulator.  It is the only file you need if you are running OpenSimulator in standalone mode
-
-## robustctrl.py ##
-
-This will control a robust instance.
+As part of this policy, there is currently no way to stop a component via the
+command line.  One has to attach to the screen and quit it via the OpenSimulator
+console.
 
 # Installation #
 
-1. Copy *.py files and the osimctrl/ directory to a location of your choice
-2. Edit configuration sections for your OpenSimulator paths and pid diles
+1. Copy src/* to a location of your choice
+2. If you are using a Python earlier than 2.7m you will need to copy argparse.py
+[1] into the same location.
+
+# Configuration #
+
+Before use, you will need to edit the binaryPath at the top of both files to
+point them at your OpenSimulator installation.  You may also want to set the
+PIDFile option in the [Startup] section of OpenSim.ini and Robust.ini to match
+the pidpath so that 
+
+1. The scripts can detect component instances that aren't in screens.
+2. Stop it complaining about PID files not being set.
+
+You can also change the screen name if you want to run more than one simulator
+on the same machine.
+
+# Files #
+
+## robustctrl.py, simctrl.py ##
+These files control a robust instance and a simulator respectively.
+
+Available commands are attach, start and status.  See --help for more details.
+
+# References #
+[1] http://argparse.googlecode.com/hg/argparse.py