bring several README and notes files up-to-date

README.md in bin and pymodel directories, several .txt files in notes directory
bring them up to date with recently separated pymodel and bin directories

Author: jon-jacky

bin/README.md

@@ -6,7 +6,7 @@ This directory contains the commands for PyModel.
 
 To use PyModel, this directory must be on your execution *PATH*.
 Or, its contents must be installed in some directory that is on your
-execution *PATH*.
+execution *PATH*.  See *pymodel_paths* in this directory.
 
 There are two versions of some commands.  The version without a file
 type is a *bash* script for Unix/Linux/Mac; the version with *.bat* is

notes/commands.txt

@@ -1,69 +1,72 @@
 
 PyModel Commands
 
-PyModel provides three main programs:
+PyModel provides three main commands:
 
- pma.py, PyModel analyzer: generates a finite state machine (FSM) 
+ 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.py, PyModel graphics: generates a file of graphic commands from an FSM,
+ 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.py, PyModel tester: displays traces, generates tests offline, 
+ 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.py, PyModel viewer: invokes pma, pmg, and the Graphiz dot command
+ 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.
 
+For more about each of these programs, type the command to display its
+built-in help, for example: pma --help, or pma -h, or just pma (with
+no arguments).  This will print a brief description of the program and
+a list of its command line options.  (For convenience, this built-in
+help output appears in this directory in pma.txt etc.)
+
 Use pma, pmg, and dot (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.
 
 PyModel also provides these programs and scripts:
 
- dotsvg: converts dot file output from pmg.py to SVG file that can be displaye
+ dotsvg: converts dot file output from pmg to SVG file that can be displaye
          in a browser.
 
- dotps: converts dot file output from pmg.py to PostScript file that can be 
+ dotps: converts dot file output from pmg to PostScript file that can be 
          printed or displayed in PostScript viewer.
 
- dotpdf: converts dot file output from pmg.py to PDF file that can be 
+ dotpdf: converts dot file output from pmg to PDF file that can be 
          printed or displayed in a PDF viewer.
 
  (The pmv command invokes one of these dot commands)
 
- wsgirunner.py: runs WSGI-compliant web applications (for example
+ wsgirunner: runs WSGI-compliant web applications (for example
                 webapp.py in the WebApplication sample) on localhost
 
- trun.py: runs sample demonstrations and scripts that test PyModel itself.
+ trun: runs sample demonstrations and scripts that test PyModel itself.
 
- clogdiff: works with trun.py to execute and check regression tests on PyModel.
+ clogdiff: works with trun to execute and check regression tests on PyModel.
 
-You can invoke the four PyModel programs on the command line or in
-scripts by name, without using the .py extension (pmt not pmt.py).
-You can also include the .py extension; many of the test scripts
-included in the distribution use this form.
+To prepare to use the programs, put the PyModel/bin directory on your
+execution path.  Put the Pymodel/pymodel directory and the the current
+directory on the Python path.  To achieve all this, execute the
+PyModel/bin/pymodel_paths command, or put the commands it contains
+in your .profile or .bashrc.   (If you install PyModel so the commands
+and modules are put in some standard place, this may not be necessary.)
 
-To prepare to use the programs, put the pymodel directory on your
-execution path.  Put the current directory (whatever it is) on the
-PYTHONPATH by executing the tpath command ("source tpath" in bash,
-systems, just "tpath" in Windows).
+Invoke the four PyModel programs on the command line or in scripts by
+name, without using the .py extension (pmt not pmt.py).  You can also
+include the .py extension (pmt.py not just pmt); some older scripts you
+may still have used this form.  BUT to use this form, you must put
+PyModel/pymodel on your execution path (not just your Python path).
 
 For usage examples with many combinations of options and arguments,
 see the test*.py test script modules in the samples directories.
 
-For more about each program, type the command to display its built-in
-help, for example: pma --help, or pma -h, or just pma (with no
-arguments).  This will print a brief description of the program and a
-list of its command line options.  (For convenience, this built-in help
-output appears here in pma.txt etc.)
-
 
 Revised Apr 2013

notes/samples.txt

@@ -8,8 +8,18 @@ in the samples directory and in each sample subdirectory.
 
 Each sample subdirectory contains some test script modules: test.py,
 test_graphics.py etc.  These scripts demonstrate the samples, as well
-as testing PyModel itself.  The file test.txt provides detailed
-instructions for running the scripts.
+as testing PyModel itself.  
+
+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
 
 Each test script contains commented command lines that demonstrate
 combinations of arguments and options.  Running each test script

notes/test.txt

@@ -26,10 +26,13 @@ using the unittest module from the Python standard library.
 
 These directions apply to both Windows and Unix-like systems
 (including Linux and Mac OS X).  The directions assume that Python is
-already installed and your environment is configured so you can run
-it (if not, see http://docs.python.org/2/using/).  It also assumes 
-that PyModel is installed and its pymodel directory (containing trun.py, 
-pmt.py etc.) is on your execution path.  
+already installed and your environment is configured so you can run it
+(if not, see http://docs.python.org/2/using/).  It also assumes that
+PyModel is present on your system, the contents of its PyModel/pymodel
+directory are on your Python path, the current directory is on your
+Pyton path, and the contents of its PyModel/bin directory are on your
+execution path.  You can achieve this by executing
+PyModel/bin/pymodel_paths, or the commands therein.
 
 Quick Start
 Summary
@@ -41,17 +44,18 @@ Using other unit testing frameworks
 
 Quick Start
 
-In each subdirectory of samples, put the current directory
-(whatever it is) on the PYTHONPATH by executing the tpath command
-("source tpath" in bash, just "tpath" in Windows).  Then, type:
+In each subdirectory of samples, type:
 
  clogdiff trun test
 
 if there are more test*.py files besides test.py, you can run them too:
 
  clogdiff trun test_scenarios
 
-etc.  If messages indicate differences were found, there may be a problem.
+etc.  If messages indicate differences were found, there may be a
+problem.  Or maybe not (see below).  If messages indicate there is no
+.ref file, that means the test scripts are not deterministic and this
+test is not meaningful.
 
 Notice that we only show the command you type, we do not show the
 command prompt, for example usually ...> for the Windows cmd prompt
@@ -99,12 +103,11 @@ more easily coded with particular system-dependent commands (for
 example: setting the execution path, checking differences between
 files).
 
-These Python programs are typically used as commands: pma.py pmg.py pmt.py
-pmv.py trun.py and wsgirunner.py.  When used as commands, the .py
-suffix can be omitted.  For example you can type pmt -n 10 PowerSwitch
-instead of pmt.py ...  or trun test_graphics instead of trun.py ...
-Both forms work (in Windows as well as Unix-like systems), and both appear in
-test scripts.
+Invoke the four PyModel programs on the command line or in scripts by
+name, without using the .py extension (pmt not pmt.py).  You can also
+include the .py extension (pmt.py not just pmt); some older scripts you
+may still have used this form.  BUT to use this form, you must put
+PyModel/pymodel on your execution path (not just your Python path).
 
 
 Test scripts
@@ -122,18 +125,12 @@ Here are the contents of the script in samples/WebApplication/Model/test.py:
 
 cases = [
  ('Test: -a option includes only Initialize Action',
-  'pmt.py -n 10 -a Initialize WebModel'),
+  'pmt -n 10 -a Initialize WebModel'),
 
  ('Test: -e option excludes all Login, Logout actions',
-  'pmt.py -n 10 -e Login_Start -e Login_Finish -e Logout WebModel'),
+  'pmt -n 10 -e Login_Start -e Login_Finish -e Logout WebModel'),
 ]
 
-The PyModel commands in test scripts often include the .py suffix, as
-in pmt.py ... here.  The suffix is not required, recent test scripts 
-often use pmt ... etc.  (On Unix-like systems, you must execute 
-the symlinks command in the pymodel directory *once* after you install
-PyModel to enabled this).
-
 The trun module takes one argument, the module name of the script (NOT
 the file name, there is no path prefix or .py suffix).  The trun
 module imports the script, then iterates over the cases list, printing
@@ -144,14 +141,13 @@ contains modules to test.  This command executes it:
 
  trun test
 
-For this command to work, the pymodel directory must be on the
-execution PATH.  The current directory must be on the PYTHONPATH.
-This is necessary to enable PyModel tools (such as pmt) in the pymodel
-directory to import modules in the current directory.  The tpath
-command in the pymodel directory assigns the current directory to the
-PYTHONPATH (use 'source tpath' in bash).    It is NOT necessary to
-repeat the tpath command after a change directory command (cd)
-(checked on Mac OS X - this may differ under Windows).
+For this command to work, the pymodel directory must be on the Python
+path, and the current directory must be on the Python path.  This is
+necessary to enable PyModel tools (such as pmt) in the pymodel
+directory to import modules in the current directory.  The
+PyModel/bin/pymodel_paths command assigns these paths.  It is NOT
+necessary to repeat the tpath command after a change directory command
+(cd) (checked on Mac OS X - this may differ under Windows).
 
 Checking test script output
 
@@ -230,12 +226,12 @@ in Windows like Unix >& to redirect error output also.
 
 Output files
 
-The PyModel pmt.py program only writes to the terminal (to stdout and
-stderr), but other PyModel programs write output files: pma.py writes
-another module (.py file) that contains the generated FSM, pmg.py
+The PyModel pmt command only writes to the terminal (to stdout and
+stderr), but other PyModel commands write output files: pma writes
+another module (.py file) that contains the generated FSM, pmg
 writes a .dot file with commands for the Graphviz dot program, and the
 various dot commands (dotsvg etc.) write graphics files: .svg, .pdf,
-.ps etc.  The pmv.py program invokes all of these programs causes all
+.ps etc.  The pmv program invokes all of these programs causes all
 of these files to be written.
 
 The PyModel programs write all of these output files in the current
@@ -245,7 +241,7 @@ overwitten).  In the PyModel distribution, we provide copies of some
 of the output files we made (on our development system) so you can
 compare them to yours (that you generate when you repeat the tests on
 your system).  In some samples directories, there may be an fsmpy
-directory which contains FSM modules written by pma.py, and there may
+directory which contains FSM modules written by pma, and there may
 be an svg or pdf directory which contains .svg files written by pma +
 pmg + dot (or pmv).  You may wish to copy output files that you
 generate into these directories, so you can compare them to output
@@ -272,8 +268,8 @@ The popular unit test frameworks are not so well-suited for this kind
 of test.  However, you can use one of the popular frameworks if you
 prefer, as an alterative to our trun command and our test scripts.
 There is an example in the samples/populations directory.  The module
-test_populations.py there works with unittest to run the same tests
-as in tests.py.  That is, instead of
+test_populations there works with unittest to run the same tests
+as in tests.  That is, instead of
 
  trun tests  # test with our homemade framework
 

pymodel/README.md

@@ -7,7 +7,7 @@ This directory contains the Python modules for PyModel.
 To use PyModel, this directory must be on your Python path.
 The usual way to achieve this is to add it to your *PYTHONPATH*.  Or, its
 contents must be installed in some directory that is on your Python
-path.
+path.  See *pymodel_paths* in the *bin* directory.
 
 This directory does not need not be on your execution *PATH*, because
 its modules are usually invoked through the commands in the PyModel