add cmdline doc to osmo_interact_* and osmo_verify_*

The tools are so far badly under-documented. Alleviate that by comprehensive
description and examples shown by -h option output. Hint at that from the
README.

Change-Id: I94dcad257558b917cb54fc877122594cd164f496

3 files changed, 137 insertions, 8 deletions

diff --git a/osmopy/osmo_interact/common.py b/osmopy/osmo_interact/common.py
index f7070ae..31f44a8 100644
--- a/osmopy/osmo_interact/common.py
+++ b/osmopy/osmo_interact/common.py
@@ -19,9 +19,9 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 '''
-Common code for osmo_interact_vty.py and osmo_interact_ctrl.py.
+Common code for VTY and CTRL interface interaction and transcript verification.
 This implements all of application interaction, piping and verification.
-osmo_interact_{vty,ctrl}.py plug VTY and CTRL interface specific bits.
+vty.py and ctrl.py plug VTY and CTRL interface specific bits.
 '''
 
 # Our setup.py currently wants everything to be parsable by both py2 and py3.
@@ -370,8 +370,9 @@ def verify_application(run_app_str, interact, transcript_file, verbose):
 
     return passed
 
-def common_parser():
-    parser = argparse.ArgumentParser()
+def common_parser(doc=None):
+    parser = argparse.ArgumentParser(description=doc,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('-r', '--run', dest='run_app_str',
                         help='command to run to launch application to test,'
                         ' including command line arguments. If omitted, no'
diff --git a/osmopy/osmo_interact/ctrl.py b/osmopy/osmo_interact/ctrl.py
index b752351..85e7554 100755
--- a/osmopy/osmo_interact/ctrl.py
+++ b/osmopy/osmo_interact/ctrl.py
@@ -87,7 +87,30 @@ class InteractCtrl(Interact):
         return split_responses
 
 def main_interact_ctrl():
-    parser = common_parser()
+    '''
+Run CTRL commands against a given application by stdin/stdout piping.
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, to start a session that allows typing CTRL commands on stdin:
+
+  osmo_interact_ctrl.py -p 4259 \\
+    -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db'
+
+Where 4259 is OsmoHLR's CTRL port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+  osmo_interact_ctrl.py -p 4259
+
+See also osmo_verify_transcript_vty.py, which allows verifying and updating
+complete CTRL session transcripts, in essence to write CTRL tests from a screen
+dump of a CTRL session.
+
+A VTY equivalent is osmo_interact_vty.py.
+'''
+    parser = common_parser(__doc__)
     parser_add_run_args(parser)
     args = parser.parse_args()
 
@@ -99,7 +122,44 @@ def main_interact_ctrl():
 
 
 def main_verify_transcript_ctrl():
-    parser = common_parser()
+    '''
+A CTRL transcript contains CTRL commands and their expected results.
+It looks like:
+
+"
+SET 1 var val
+SET_REPLY 1 var OK
+
+GET 2 var
+GET_REPLY 2 var val
+"
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, if above transcript example is in file test.ctrl, you can verify
+that OsmoHLR still shows this behavior by:
+
+  osmo_interact_ctrl.py -p 4259 \\
+    -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db' \\
+    test.ctrl
+
+Where 4259 is OsmoHLR's CTRL port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+  osmo_interact_ctrl.py -p 4259 test.ctrl
+
+If osmo-hlr has changed its behavior, e.g. some reply changed, the transcript
+can be automatically updated, which overwrites the file, like:
+
+  osmo_interact_ctrl.py -p 4259 -u test.ctrl
+
+See also osmo_interact_ctrl.py, which allows piping CTRL commands to stdin.
+
+A VTY equivalent is osmo_verify_transcript_vty.py.
+'''
+    parser = common_parser(__doc__)
     parser_add_verify_args(parser)
     parser.add_argument('-i', '--keep-ids', dest='keep_ids', action='store_true',
                         help='With --update, default is to overwrite the command IDs'
diff --git a/osmopy/osmo_interact/vty.py b/osmopy/osmo_interact/vty.py
index f34e87e..4704c09 100755
--- a/osmopy/osmo_interact/vty.py
+++ b/osmopy/osmo_interact/vty.py
@@ -156,7 +156,30 @@ def parser_add_vty_args(parser):
     return parser
 
 def main_interact_vty():
-    parser = common_parser()
+    '''
+Run VTY commands against a given application by stdin/stdout piping.
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, to extract the VTY reference XML file from osmo-hlr:
+
+  osmo_interact_vty.py -p 4258 --gen-xml-ref \\
+    -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db'
+
+Where 4258 is OsmoHLR's VTY port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+  osmo_interact_vty.py -p 4258 --gen-xml-ref
+
+See also osmo_verify_transcript_vty.py, which allows verifying and updating
+complete VTY session transcripts, in essence to write VTY tests from a screen
+dump of a VTY session.
+
+A Control interface equivalent is osmo_interact_ctrl.py.
+'''
+    parser = common_parser(__doc__)
     parser_add_vty_args(parser)
     parser_add_run_args(parser)
     parser.add_argument('-X', '--gen-xml-ref', dest='gen_xml', action='store_true',
@@ -178,7 +201,52 @@ def main_interact_vty():
                       args.cmd_files, interact)
 
 def main_verify_transcript_vty():
-    parser = common_parser()
+    '''
+A VTY transcript contains VTY commands and their expected results.
+It looks like a screen dump of a live VTY session:
+
+"
+OsmoHLR> enable
+
+OsmoHLR# subscriber show imsi 123456789023000
+% No subscriber for imsi = '123456789023000'
+OsmoHLR# subscriber show msisdn 12345
+% No subscriber for msisdn = '12345'
+
+OsmoHLR# subscriber create imsi 123456789023000
+% Created subscriber 123456789023000
+    ID: 1
+    IMSI: 123456789023000
+    MSISDN: none
+    No auth data
+"
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, if above transcript example is in file test.vty, you can verify
+that OsmoHLR still shows this behavior by:
+
+  osmo_interact_vty.py -p 4258 \\
+    -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db' \\
+    test.vty
+
+Where 4258 is OsmoHLR's VTY port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+  osmo_interact_vty.py -p 4258 test.vty
+
+If osmo-hlr has changed its behavior, e.g. some error message changed, the
+transcript can be automatically updated, which overwrites the file, like:
+
+  osmo_interact_vty.py -p 4258 -u test.vty
+
+See also osmo_interact_vty.py, which allows piping VTY commands to stdin.
+
+A Control interface equivalent is osmo_verify_transcript_ctrl.py.
+'''
+    parser = common_parser(__doc__)
     parser_add_vty_args(parser)
     parser_add_verify_args(parser)
     args = parser.parse_args()