From b8ef6ed8b86ef47e19534d45512cb8be93e63be9 Mon Sep 17 00:00:00 2001
From: Thierry Parmentelat <thierry.parmentelat@inria.fr>
Date: Wed, 22 May 2013 16:13:32 +0200
Subject: [PATCH] provide example for 'sfi delegate' as well, refer to 'sfi
 myslice' plus more minor cosmetic changes for the online doc

---
 sfa/client/sfi.py | 47 ++++++++++++++++++++++++++++++++++-------------
 1 file changed, 34 insertions(+), 13 deletions(-)

diff --git a/sfa/client/sfi.py b/sfa/client/sfi.py
index af219b3e..6d30aadf 100644
--- a/sfa/client/sfi.py
+++ b/sfa/client/sfi.py
@@ -286,7 +286,9 @@ class Sfi:
         else:
             print line
             self.create_parser().print_help()
-        for (command, (doc, args_string, example)) in commands_dict.iteritems():
+        # preserve order from the code
+        for command in commands_list:
+            (doc, args_string, example) = commands_dict[command]
             if verbose:
                 print line
             doc=doc.replace("\n","\n"+35*' ')
@@ -304,7 +306,7 @@ class Sfi:
         print "\n==================== Specific usage for %s"%self.command
         self.command_parser.print_help()
         if example:
-            print "\n==================== %s example"%self.command
+            print "\n==================== %s example(s)"%self.command
             print example
 
     def create_command_parser(self, command):
@@ -533,7 +535,8 @@ use this if you mean an authority instead""")
                 config.add_section('sfi')
                 # sface users should be able to use this same file to configure their stuff
                 config.add_section('sface')
-                # manifold users should be able to specify their backend server here for sfi delegate
+                # manifold users should be able to specify the details 
+                # of their backend server here for 'sfi myslice'
                 config.add_section('myslice')
                 config.load(config_file)
                 # back up old config
@@ -793,7 +796,7 @@ use this if you mean an authority instead""")
     def version(self, options, args):
         """
         display an SFA server version (GetVersion)
-or version information about sfi itself
+  or version information about sfi itself
         """
         if options.version_local:
             version=version_core()
@@ -988,7 +991,7 @@ or version information about sfi itself
     def resources(self, options, args):
         """
         with no arg, discover available resources, (ListResources)
-or with an slice hrn, shows currently provisioned resources
+  or with an slice hrn, shows currently provisioned resources
         """
         server = self.sliceapi()
 
@@ -1046,7 +1049,7 @@ or with an slice hrn, shows currently provisioned resources
     @register_command("slice_hrn rspec","")
     def create(self, options, args):
         """
-        create or update named slice with given rspec
+        create or update named slice with given rspec (CreateSliver)
         """
         server = self.sliceapi()
 
@@ -1321,7 +1324,7 @@ or with an slice hrn, shows currently provisioned resources
     def redeem_ticket(self, options, args):
         """
         Connects to nodes in a slice and redeems a ticket
-(slice hrn is retrieved from the ticket)
+  (slice hrn is retrieved from the ticket)
         """
         ticket_file = args[0]
         
@@ -1378,10 +1381,24 @@ or with an slice hrn, shows currently provisioned resources
         GID(string=gid).save_to_file(filename)
          
 
-    @register_command("to_hrn","")
+    @register_command("to_hrn","""$ sfi delegate -u -p -s ple.inria.heartbeat -s ple.inria.omftest ple.upmc.slicebrowser
+
+  will locally create a set of delegated credentials for the benefit of ple.upmc.slicebrowser
+  the set of credentials in the scope for this call would be
+  (*) ple.inria.thierry_parmentelat.user_for_ple.upmc.slicebrowser.user.cred
+      as per -u/--user
+  (*) ple.inria.pi_for_ple.upmc.slicebrowser.user.cred
+      as per -p/--pi
+  (*) ple.inria.heartbeat.slice_for_ple.upmc.slicebrowser.user.cred
+  (*) ple.inria.omftest.slice_for_ple.upmc.slicebrowser.user.cred
+      because of the two -s options
+
+""")
     def delegate (self, options, args):
         """
         (locally) create delegate credential for use by given hrn
+  make sure to check for 'sfi myslice' instead if you plan
+  on using MySlice
         """
         if len(args) != 1:
             self.print_help()
@@ -1426,21 +1443,25 @@ or with an slice hrn, shows currently provisioned resources
             self.logger.info("delegated credential for %s to %s and wrote to %s"%(message,to_hrn,filename))
     
     ####################
-    @register_command("","""$ less +/myslice myslice sfi_config
+    @register_command("","""$ less +/myslice sfi_config
 [myslice]
 backend  = 'http://manifold.pl.sophia.inria.fr:7080'
+# the HRN that myslice uses, so that we are delegating to
 delegate = 'ple.upmc.slicebrowser'
+# platform - this is a myslice concept
+platform = 'ple'
+# username - as of this writing (May 2013) a simple login name
 user     = 'thierry'
 
 $ sfi myslice
 
   will first collect the slices that you are part of, then make sure
-  all your credentials are up-to-date (that is: refresh expired ones)
+  all your credentials are up-to-date (read: refresh expired ones)
   then compute delegated credentials for user 'ple.upmc.slicebrowser'
-  and upload them all on myslice backend, using manifold id as
-  specified in 'user'
+  and upload them all on myslice backend, using 'platform' and 'user'.
+  A password will be prompted for the upload part.
 """
-)
+) # register_command
     def myslice (self, options, args):
 
         """ This helper is for refreshing your credentials at myslice; it will
-- 
2.47.0