Index: examples/python_tests/file_read_rt2/README
===================================================================
--- examples/python_tests/file_read_rt2/README	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
+++ examples/python_tests/file_read_rt2/README	(revision d6ff6f1f1ddc6d495b8cd228b000ced41a58cf5e)
@@ -1,10 +1,6 @@
-#!/bin/sh
-#
 #####################################################################
-# This example demonstrates using a parameters to control access to files based
-# on the attributes of the principals.  The script creates three principals
-# Alpha, Bob, Maryann and Joe and sets out the access policy.
-# 
-# files are named by URNs and are not principals.
+# This example demonstrates using a parameters to control access to 
+# files based on the attributes of the principals. files are named by 
+# URNs and are not principals.
 # 
 # A principal's access rights are controlled by the Alpha principal.  If a
@@ -13,84 +9,24 @@
 # a file can read it. (Presumably the owner can, too, but that is not encoded
 # here.)
+#
+# The setup.py file creates four principals Alpha, Bob, Maryann and Joe
 # 
-# The example below lays out the policy that the manager of the owner of a file
+# The attr.py file lays out the policy that the manager of the owner of a file
 # can read it in Credential 1. Credential 2 establishes Bob as the manager of
 # Joe. and Credential 3 establishes Joe as the owner of the file.
 #
-# The attached ./run_query file runs 2 queries.  First it confirms that Bob can read
+# The query.py file runs 2 queries.  First it confirms that Bob can read
 # fileA, then it confirms that Maryann cannot. 
 
-# file_read_rt2_typed
-
-# alpha.read(fileA) <-?- Bob
-#[keyid:Alpha].role:read([urn:'file://fileA']) <-?- [keyid:Bob] (yes)
-#[keyid:Alpha].role:read([urn:'file://fileA']) <-?- [keyid:Maryann] (yes)
-
-creddy --generate --cn Alpha
-creddy --generate --cn Bob
-creddy --generate --cn Maryann
-creddy --generate --cn Joe
-
-alpha_keyid=`creddy --keyid --cert Alpha_ID.pem`
-bob_keyid=`creddy --keyid --cert Bob_ID.pem`
-maryann_keyid=`creddy --keyid --cert Maryann_ID.pem`
-joe_keyid=`creddy --keyid --cert Joe_ID.pem`
-
-read_fileA="read([urn:'file://fileA'])"
-managerof_joe="managerOf([keyid:$joe_keyid])"
-ownerof_fileA="ownerOf([urn:'file://fileA'])"
-managerof_qE="managerOf([principal:?E[keyid:$alpha_keyid].role:ownerOf([urn:?F])])"
-
-# alpha.read(?F) <- alpha.managerOf(?E:alpha.ownerOf(?F))
+# file_read_rt2
+#
+# Credential 1 (alpha.read(?F) <- alpha.managerOf(?E:alpha.ownerOf(?F)))
 # [keyid:alpha].role:read([urn:?F])<-
 #    [keyid:alpha].role:managerOf([principal:?E[keyid:alpha].role:ownerOf([urn:?F])]
-# Credential 1
-creddy --attribute \
-       --issuer Alpha_ID.pem --key Alpha_private.pem --role "read([urn:?F])" \
-       --subject-cert Alpha_ID.pem --subject-role "$managerof_qE" \
-       --out Alpha_read_qF__alpha_managerof_qE_attr.der
 
 # Credential 2
 #[keyid:Alpha].role:managerOf([Keyid:Joe]) <- [keyid:Bob]
-creddy --attribute \
-        --issuer Alpha_ID.pem --key Alpha_private.pem --role "$managerof_joe" \
-        --subject-cert Bob_ID.pem \
-        --out Alpha_managerof_Joe__Bob_attr.der
 
 # Credential 3
 #[keyid:Alpha].role:ownerOf([urn:'file://fileA']) <- [keyid:Joe]
-creddy --attribute \
-        --issuer Alpha_ID.pem --key Alpha_private.pem --role "$ownerof_fileA" \
-        --subject-cert Joe_ID.pem \
-        --out Alpha_ownerof_fileA__Joe_attr.der
 
-####################################################################################
-# note:
-# 
-# alpha.read(?F) <- alpha.manager(?E:alpha.owner(?F))
-# [keyid:alpha].role:read([urn:?F])<-
-#       #[keyid:alpha].role:manager([principal:?E[keyid:alpha].role:owner([urn:?F])])
-# 
-# alpha.read(?F) <- alpha.manager(?E) 
-# and alpha.owner(?F) <- ?E
-# 
-# [keyid:alpha].role:read([urn:?F])<-[keyid:?M]
-#     [keyid:alpha].role:manager([principal:?E])<-[keyid:?M]
-#     [keyid:alpha].role:owner([urn:?F])<-[keyid:?E]
-# 
-# isMember(M,role(alpha,read,F)) :-
-#       isMember(M, role(alpha,manager,E)),
-#       isMember(E, role(alpha,owner,F))  <-- constraining rule
-# 
-# alpha.read(?F) <- alpha.manager(?E)
-# alpha.owner(?F) <- ?E
-# 
-# condition like this,
-#          ?E:A.r  needs to be translate into constraining rule,  A.r<-?E
-# 
-# query,
-# alpha.read(fileA) <-?- Bob
-# needs
-# alpha.manager(Joe)<-Bob
-# alpha.owner(fileA)<-Joe
-
Index: examples/python_tests/file_read_rt2/attr.py
===================================================================
--- examples/python_tests/file_read_rt2/attr.py	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
+++ examples/python_tests/file_read_rt2/attr.py	(revision d6ff6f1f1ddc6d495b8cd228b000ced41a58cf5e)
@@ -2,5 +2,6 @@
 
 """
-  to test with python
+See README in this directory for the semantics of the example.  This file
+constructs the credentials described and puts copies into this directory
 
 cmd1:env keystore=`pwd` ./attr.py 
@@ -10,10 +11,12 @@
 import ABAC
 
-keystore=os.environ["keystore"]
-
 ctxt = ABAC.Context()
 print "ABAC version %s" % ctxt.version()
 
-ctxt.load_directory(keystore)
+# Keystore is the directory containing the principal credentials.
+# Load existing principals and/or policy credentials
+if (os.environ.has_key("keystore")) :
+    keystore=os.environ["keystore"]
+    ctxt.load_directory(keystore)
 
 out = ctxt.context_principals()
@@ -29,4 +32,5 @@
 print "\n"
 
+# retrieve principals' keyid value from local credential files
 alphaID=ABAC.ID("Alpha_ID.pem")
 alphaID.id_load_privkey_file("Alpha_private.pem");
@@ -47,4 +51,6 @@
 
 ################################################
+# Credential 1, demostrates role constraint on a file, 
+#               manager of the owner of a file can also read that file
 # [keyid:alpha].role:read([urn:?F])<-
 #    [keyid:alpha].role:managerOf([principal:?E[keyid:alpha].role:ownerOf([urn:?F])]
@@ -52,14 +58,28 @@
 head = ABAC.Role(alpha,"read")
 head.role_add_data_term(param)
+
+# create variable data term
 param=ABAC.DataTerm("urn", "F")
-condoset=ABAC.Role(alpha,"ownerOf")
-condoset.role_add_data_term(param)
-cond=ABAC.Constraint(condoset)
+
+# create the constraining role structure
+condrole=ABAC.Role(alpha,"ownerOf")
+condrole.role_add_data_term(param)
+
+# create the constraint
+cond=ABAC.Constraint(condrole)
+
+# build the parameter with constraint
 param=ABAC.DataTerm("principal", "E", cond)
 tail = ABAC.Role(alpha,"managerOf")
 tail.role_add_data_term(param)
+
+# compose attribute policy
 attr=ABAC.Attribute(head, 1800)
 attr.attribute_add_tail(tail)
+
+# finalize the policy
 attr.attribute_bake()
+
+# write out to external file
 attr.attribute_write_cert("Alpha_read_qF__alpha_managerof_qE_attr.der")
 ctxt.load_attribute_file("Alpha_read_qF__alpha_managerof_qE_attr.der")
@@ -69,4 +89,5 @@
 
 #################################################
+# Credential 2, Bob is Joe's manager
 # [keyid:Alpha].role:managerOf([Keyid:Joe]) <- [keyid:Bob]
 #
@@ -85,4 +106,5 @@
 
 #################################################
+# Credential 3, Joe is file's owner
 #[keyid:Alpha].role:ownerOf([urn:'file://fileA']) <- [keyid:Joe]
 #
@@ -100,5 +122,2 @@
 print "\n"
 
-
-ctxt.dump_yap_db()
-##
Index: examples/python_tests/file_read_rt2/file.save
===================================================================
--- examples/python_tests/file_read_rt2/file.save	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
+++ examples/python_tests/file_read_rt2/file.save	(revision d6ff6f1f1ddc6d495b8cd228b000ced41a58cf5e)
@@ -1,3 +1,14 @@
 % Restoring file /usr/local/lib/Yap/startup.yss
+
+...final principal set...
+(pAlpha,keyid,y) 
+(pBob,keyid,y) 
+(pJoe,keyid,y) 
+(pMaryann,keyid,y) 
+
+...final policy attribute set...
+pAlpha.managerOf(pJoe) <- pBob
+pAlpha.ownerOf('file://fileA') <- pJoe
+pAlpha.read(F) <- pAlpha.managerOf(E:pAlpha.ownerOf(F))
 
 ===good============ alpha.read(fileA) <- Bob
@@ -9,17 +20,2 @@
 ===bad============ alpha.read(fileA) <- Maryann
 YAP query failed
-
-...final principal set...
-(pAlpha,keyid,y) 
-(pBob,keyid,y) 
-(pJoe,keyid,y) 
-(pMaryann,keyid,y) 
-
-
-
-...final policy attribute set...
-pAlpha.managerOf(pJoe) <- pBob
-pAlpha.ownerOf('file://fileA') <- pJoe
-pAlpha.read(F) <- pAlpha.managerOf(E:pAlpha.ownerOf(F))
-
-
Index: examples/python_tests/file_read_rt2/query.py
===================================================================
--- examples/python_tests/file_read_rt2/query.py	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
+++ examples/python_tests/file_read_rt2/query.py	(revision d6ff6f1f1ddc6d495b8cd228b000ced41a58cf5e)
@@ -2,5 +2,5 @@
 
 """
-  to test with python
+Run the queries described in README
 
 cmd1:env keystore=`pwd` ./query.py 
@@ -14,10 +14,14 @@
 ctxt = ABAC.Context()
 
-# print "ABAC version %s" % ctxt.version()
+# Keystore is the directory containing the principal credentials.
+# Load existing principals and/or policy credentials
+if (os.environ.has_key("keystore")) :
+    keystore=os.environ["keystore"]
+    ctxt.load_directory(keystore)
+else:
+    print("keystore is not set...")
+    exit(1)
 
-keystore=os.environ["keystore"]
-
-ctxt.load_directory(keystore)
-
+# retrieve principals' keyid value from local credential files
 alphaID=ABAC.ID("Alpha_ID.pem")
 alphaID.id_load_privkey_file("Alpha_private.pem");
@@ -37,4 +41,17 @@
 
 ##########################################################################
+# dump the loaded principals/policies
+#
+out = ctxt.context_principals()
+print "\n...final principal set..."
+for x in out[1]:
+    print "%s " % x.string()
+out = ctxt.context_credentials()
+print "\n...final policy attribute set..."
+for c in out[1]:
+    print "%s <- %s" % (c.head_string(), c.tail_string())
+
+##########################################################################
+# can Bob read fileA ?
 # role=[keyid:Alpha].role:read([urn:'file://fileA']) 
 # p=[keyid:Bob]
@@ -49,4 +66,5 @@
 
 ##########################################################################
+# can Maryann read fileA ?
 # role=[keyid:Alpha].role:read([urn:'file://fileA']) 
 # p=[keyid:Maryann]
@@ -59,17 +77,2 @@
     print "%s <- %s" % (c.head_string(), c.tail_string())
 
-
-##########################################################################
-# dump the loaded principals/policies 
-#
-out = ctxt.context_principals()
-print "\n...final principal set..."
-for x in out[1]:
-    print "%s " % x.string()
-print "\n"
-out = ctxt.context_credentials()
-print "\n...final policy attribute set..."
-for c in out[1]:
-    print "%s <- %s" % (c.head_string(), c.tail_string())
-print "\n"
-
Index: examples/python_tests/file_read_rt2/run_test
===================================================================
--- examples/python_tests/file_read_rt2/run_test	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
+++ examples/python_tests/file_read_rt2/run_test	(revision d6ff6f1f1ddc6d495b8cd228b000ced41a58cf5e)
@@ -1,7 +1,3 @@
 #!/bin/sh 
-
-ABAC_PROVER_PATH="/home/mei/Deter/abac/libabac"
-export ABAC_PROVER_PATH
-
 
 echo '---setup principals'
Index: examples/python_tests/file_read_rt2/setup.py
===================================================================
--- examples/python_tests/file_read_rt2/setup.py	(revision 669b4810acfbeee6bdec4a2443a99b2994efedc8)
+++ examples/python_tests/file_read_rt2/setup.py	(revision d6ff6f1f1ddc6d495b8cd228b000ced41a58cf5e)
@@ -2,7 +2,6 @@
 
 """
-  to test with python
-
-
+See README for the semantics.  This creates principals
+used by the example.
 """
 import os
