revise installation directions in INSTALL.txt

also revise release notes, samples.txt
add README.rst for PyPI and revise setup.py to use it
add links to slides and papers in README.md
add 'PyModel Tester' to TesterOptions.py

Author: jon-jacky

INSTALL.txt

@@ -14,13 +14,21 @@ or
 
  http://staff.washington.edu/jon/pymodel/www/
 
-Then unpack using a tar or zip utility.  Then you can run PyModel
-using the commands and modules in the unpacked distribution directory.
-Just put PyModel/bin on your execution PATH and PyModel/pymodel on
-your PYTHONPATH.  You can achieve this by executing the script
-PyModel/bin/pymodel_paths (or pymodel_paths.bat on Windows).  That
-script assumes the distribution directory is in your HOME directory
-and is named PyModel (not PyModel-1.0, so you many need to rename it).
+Then unpack it using a tar or zip utility.  
+
+Alternatively, if you have pip installed you can download
+PyModel-1.0.tar.gz from PyPI into the current directory, and then
+unpack it, with a single command:
+
+ pip install --no-install --build . PyModel
+
+Then you can run PyModel using the commands and modules in the
+unpacked distribution directory.  Just put PyModel/bin on your
+execution PATH and PyModel/pymodel on your PYTHONPATH.  You can
+achieve this by executing the script PyModel/bin/pymodel_paths (or
+pymodel_paths.bat on Windows).  That script assumes the distribution
+directory is in your HOME directory and is named PyModel (not
+PyModel-1.0, so you many need to rename it).
 
 Confirm that PyModel works for you by running some of the test scripts
 in the samples directories.  For example, in
@@ -32,15 +40,28 @@ The setup.py script included in the distribution now supports the
 install argument, so you can optionally install the PyModel python
 modules and commands in system directories (for example in
 /Library/Python/2.7/site-packages and /usr/local/bin, respectively).
-In the PyModel directory, type the command: sudo python setup.py
-install.    Then you should not need to execute pymodel_path, but 
-You still need to type the command: source tpath (in Windows, just tpath)
+In the PyModel directory, type the command: 
+
+ sudo python setup.py install
+
+Alternatively, if you have pip installed you can type the command:
+
+ sudo pip install --no-download --build . PyModel
+
+The pip utility maintains a registry of the packages it has installed,
+which makes it easy to review and uninstall packages.
+
+After installing you should not need to execute pymodel_path, but You
+still need to type the command: source tpath (in Windows, just tpath)
 in every session (terminal window).
 
-Most of the distribution is in the examples under PyModel/samples, and
-in the documentation under PyModel/notes, www, and talks, and in the
-README files in most directories.  Installation does not install these
-into any system directories; find them under the unpacked PyModel
-distribution directory.
+Most of the distribution contents is in the examples under
+PyModel/samples, and in the documentation under PyModel/notes, www,
+and talks, and in the README files in most directories.  Installation
+does not install these into any system directories; find them under
+the unpacked PyModel distribution directory.  This is why we
+recommend the pip --noinstall and --build switches.  The pip install
+command without these switches will not leave the unpacked
+distribution files available on your system.
 
 Revised May 2013

README.md

@@ -58,6 +58,12 @@ For more information, read the [notes](notes), browse the
 or try the [samples](samples).  There are README files in most of the
 directories.
 
+Here are the [slides](talks/pymodel-nwpd10.pdf) for
+talks on PyModel given at [NWPD10](http://www.seapig.org/NWPD10)
+and [SciPy 2011](http://conference.scipy.org/scipy2011/schedule.php).
+Here is the [paper](talks/pymodel-scipy2011.pdf) from the 
+SciPy 2011 Proceedings.
+
 You can [INSTALL](INSTALL.txt) PyModel.
 
 PyModel is also available at

README.rst

@@ -0,0 +1,72 @@
+
+PyModel: Model-based testing in Python
+======================================
+
+**PyModel** is an open-source model-based testing framework in Python.
+
+In model-based testing, you code a *model* that can generate as many
+test cases as needed.  The model also checks the test outcomes.
+Model-based testing is helpful where so many test cases are needed
+that it is not feasible to code them all by hand.
+ 
+In the samples included with PyModel, there are models and test
+scripts for network sockets, a communication protocol, embedded
+controllers, some data structures, a multithreaded application, and a
+web application.
+
+PyModel includes an analyzer for validating models, visualizing their
+behavior, and checking their safety properties.
+
+PyModel can generate *offline tests* which are similar to unit tests,
+but the typical way to use PyModel is *on-the-fly testing*, where the
+test runner uses the model to compute the test run as it executes, so
+test runs can be as long as needed.  On-the-fly testing can cope with
+nondeterminism and asynchrony in the system under test.
+
+PyModel can combine models using *composition*, guide tests through
+programmed *scenarios*, and focus test coverage according to
+programmed *strategies*.
+
+PyModel provides three main programs:
+
+- **pma**, PyModel analyzer: generates a finite state machine (FSM) 
+   and computes properties by exploring a model program, FSM, test suite, 
+   or a product of these.
+ 
+- **pmg**, PyModel graphics: generates a file of graphic commands from an FSM,
+   that can be processed by the Graphviz *dot* command to produce graphics
+   files in various formats including *svg*, *pdf*, and *ps*.
+ 
+- **pmt**, PyModel tester: displays traces, generates tests offline, 
+   executes offline tests, or generates and executes tests on-the-fly.
+
+There is also a fourth program:
+
+- **pmv**, PyModel viewer: invokes *pma*, *pmg*, and the Graphiz *dot*
+   command (to display the graphics generated by *pmg*).  The *pmv*
+   program provides brevity and convenience, so analysis and display
+   can be accomplished by a single command.
+
+Use *pma* and *pmg* (or *pmv*) to visualize and preview the behavior of *pmt*.
+Every path through the graph created by *pma* (and drawn by *pmg*) is a
+trace (test run) that may be generated by *pmt*, when *pma* and *pmt* are
+invoked with the same arguments.  The *pma* program is also useful on
+its own for visualization and safety analysis.
+
+PyModel work in progress is available at GitHub:
+https://github.com/jon-jacky/PyModel
+
+The PyModel distribution is also available at the
+author's web page: http://staff.washington.edu/jon/pymodel/www/
+
+PyModel requires Python 2.6 or higher (because it uses *itertools.product*)
+
+PyModel is influenced by NModel, but is not a translation or
+re-implementation.
+
+PyModel is covered by the BSD License.
+
+Code and documents are copyright (C) 2009-2013, Jonathan Jacky.
+
+
+Revised May 2013

notes/release-1.0.txt

@@ -50,7 +50,8 @@ Version 1.0 adds new functionality:
 
 - The revised setup.py now supports the install argument, to
   optionally install the PyModel python modules and commands in system
-  directories.
+  directories.  Now PyModel can be installed using distutils
+  (... setup.py install ...) or pip.
 
 Version 1.0 adds a new sample and revises all the others:
 

notes/samples.txt

@@ -14,12 +14,13 @@ To execute test.py (etc.), type the command
 
  trun test
 
-For this to work, the PyModel/pymodel directory must be on your Python
-path, the current directory must be on your Python path, and the
-PyModel/bin directory must be on your execution path.  To achieve all
-this, you can run the PyModel/pymodel/pymodel_paths command.
-Alternatively, if you have installed PyModel, these preliminaries may
-not be necessary. Just type: trun test
+(but not python test.py) For this to work, the PyModel/pymodel
+directory must be on your Python path, the current directory must be
+on your Python path, and the PyModel/bin directory must be on your
+execution path.  To achieve all this, you can run the
+PyModel/pymodel/pymodel_paths command.  Alternatively, if you have
+installed PyModel, these preliminaries may not be necessary.
+For more details see PyModel/INSTALL.txt
 
 Each test script contains commented command lines that demonstrate
 combinations of arguments and options.  Running each test script

pymodel/TesterOptions.py

@@ -6,17 +6,17 @@
 
 usage = """pmt [options] models  
 
-models is a list of one or more module names (with no .py suffix).
-Each module named in models must contain a model, that is: a model
-program, an FSM, or a test suite.  In addition, a module named in
-models can contain additional configuration information for a model
-program.  Multiple models (model programs including configuration,
-FSMs, and test suites) are composed into a product.  The tester
-generates traces by executing the product, at random or guided by the
-strategy option.  To just view the traces, omit the implementation
-option.  To use pmt as an offline test generator, omit the
-implementation option and use the output option to save the traces in
-a test suite module.  To execute tests, provide the implementation
+PyModel Tester.  models is a list of one or more module names (with no
+.py suffix).  Each module named in models must contain a model, that
+is: a model program, an FSM, or a test suite.  In addition, a module
+named in models can contain additional configuration information for a
+model program.  Multiple models (model programs including
+configuration, FSMs, and test suites) are composed into a product.
+The tester generates traces by executing the product, at random or
+guided by the strategy option.  To just view the traces, omit the
+implementation option.  To use pmt as an offline test generator, omit
+the implementation option and use the output option to save the traces
+in a test suite module.  To execute tests, provide the implementation
 option.  To execute tests generated offline, provide that test suite
 module as the single command argument.  To generate and execute tests
 on-the-fly, provide one or more model programs and/or scenario FSMs as

setup.py

@@ -46,7 +46,7 @@
     maintainer_email = 'jon.p.jacky@gmail.com',
     url = 'https://github.com/jon-jacky/PyModel',
     description = 'Model-based testing in Python',
-    long_description = open('README.md').read(),
+    long_description = open('README.rst').read(),
     download_url = 'https://pypi.python.org/pypi/PyModel',
     license = 'BSD License',