[DOCUMENTATION] Update as per discussion (- WIP #39 -)

Changes in file README.md:
 - updated CLI usage and python usage code (WIP)

README.md

@@ -35,6 +35,37 @@ Continuous integration testing is handled by github actions and the generous Cir
 [![Stable Code Coverage](https://codecov.io/gh/reactive-firewall/multicast/branch/stable/graph/badge.svg)](https://codecov.io/gh/reactive-firewall/multicast/branch/stable/)
 [![CodeQL](https://github.com/reactive-firewall/multicast/actions/workflows/codeql-analysis.yml/badge.svg?branch=stable)](https://github.com/reactive-firewall/multicast/actions/workflows/codeql-analysis.yml)
 
+## CLI Usage
+
+The CLI is actually not the best way to use this kind of library so it should not be considered the full implementation. For testing/prototyping though it is quite convenient, thus I begin with it.
+
+CLI should work like so:
+
+```plain
+multicast (SAY|RECV|HEAR) [-h|--help] [--use-std] [--daemon] [--port PORT] [--iface IFACE] [--pipe|-m MESSAGE|--message MESSAGE] [--group BIND_GROUP] [--groups [JOIN_MCAST_GROUPS ...]]
+```
+
+The commands are `SAY`, `RECV`, and `HEAR` for the CLI and are analogus to `send` listen/accept and echo functions of a 1-to-1 connection.
+
+### `SAY`
+
+The `SAY` command is used to send data messages via multicast diagrams.
+* Note: the `--daemon` flag has no effect on the `SAY` command.
+
+### `RECV`
+
+The `RECV` command is used to receive multicast diagrams by listening or "joining" a multicast group.
+* if the `--use-std` flag is set the output is printed to the standard-output
+* this command is purely for testing or interfacing with external components and not intended as a first-class API
+* Note: If the `--daemon` flag is used the process will loop after reporting each diagram until canceled, it has no effect on the `RECV` command.
+
+### `HEAR`
+
+The `HEAR` command is used to send data acknowledged messages via "HEAR" messages echoing select received multicast diagrams.
+* while mostly a testing function it is possible to use `HEAR` as a proxy for other send/recv instances by using the `--daemon` flag
+* note this will use the same port for sends and receives and can lead to data loss if less than two groups are used.
+* If more than one group is used via the `--groups` flag then all but the bind group (via `--group`) will be echoed to the bind group.
+
 ## FAQ
 
 ### How do I get this running?
@@ -45,16 +76,14 @@ Continuous integration testing is handled by github actions and the generous Cir
 # cd /MY-AWSOME-DEV-PATH
 git clone https://github.com/reactive-firewall/multicast.git multicast
 cd ./multicast
-# checkout stable
+git checkout stable
 # make clean ; make test ; make clean ;
 make install ;
 python3 -m multicast --help ;
 ```
-
 #### DONE
 
-if all went well multicast is installed and working
-
+If all went well `multicast` is now installed and working :tada:
 
 ### How do I use this to receive some UDP Multicast?
 
@@ -87,7 +116,7 @@ python3 -m multicast SAY --mcast-group 224.1.1.2 --port 5353 --message "Hello Wo
 ### What is the basic API via python (instead of bash like above):
 
 #### Caveat: this module is still a WIP
-[Here is how it is tested right now](https://github.com/reactive-firewall/multicast/blob/7ade479f043257af5416add428b4aaf71fe851e0/tests/test_usage.py#L184)
+[Here is how it is tested right now](https://github.com/reactive-firewall/multicast/blob/cdd577549c0bf7c2bcf85d1b857c86135778a9ed/tests/test_usage.py#L251-L554)
 
 ```python3
 import mulicast as mulicast
@@ -114,27 +143,40 @@ def printLoopStub(func):
 	for i in range( 0, 5 ):
 		print( str( func() ) )
 
-p = Process(target=inputHandle())
+p = Process(
+				target=multicast.__main__.McastDispatch().doStep,
+				name="HEAR", args=("HEAR", _fixture_HEAR_args,)
+			)
 p.start()
 
 # ... probably will return with nothing outside a handler function in a loop
 ```
 and elsewhere (like another function or even module) for the sender:
 ```python3
 
+# assuming already did 'import mulicast as mulicast'
+
 _fixture_SAY_args = [
 	"""--port""", _fixture_PORT_arg,
 	"""--mcast-group""", _fixture_mcast_GRP_arg,
 	"""--message""", """'test message'"""
 ]
-multicast.__main__.useTool("SAY", _fixture_SAY_args)  # could perhaps also call multicast.recv.saystep() directly
-
+try:
+	multicast.__main__.McastDispatch().doStep("SAY", _fixture_SAY_args)
+	# Hint: use a loop to repeat or different arguments to varry message.
+except Exception:
+	p.join()
+	raise RuntimeException("multicast seems to have failed, blah, blah")
+
+# clean up some stuff
 p.join() # if not already handled don't forget to join the process and other overhead
-
+didWork = (int(p.exitcode) <= int(0)) # if you use a loop and need to know the exit code
 
 ```
 #### Caveat: the above examples assume the reader is knowledgeable about general `IPC` theory and the standard python `multiprocessing` module and its use.
 
+
+
 ### What does exit code _x_ mean?
 
 #### Python function return code meanings
@@ -161,6 +203,7 @@ _(extra exit code meanings)_
 
 Other codes (such as `126`) may or may not have meanings (such as skip) but are not handled within the scope of the Multicast Project at this time.
 
+
 ## Considerations for usage:
 
 #### [CWE-183]
@@ -193,11 +236,11 @@ make clean ; # cleans up for next test
 
 ## Next steps:
 
-(UNSTABLE) clean up Proof-of-concept code into a recognizable python module project.
+--(UNSTABLE) clean up Proof-of-concept code into a recognizable python module project.--
 (WIP) might expand the documentation to be more user friendly to the non-network guru
 (WIP) might add tcp multicast ... who knows?
 
-#### Copyright (c) 2021-2023, Mr. Walls
+#### Copyright (c) 2021-2024, Mr. Walls
 
 [![License - MIT](https://img.shields.io/github/license/reactive-firewall/multicast.svg?maxAge=3600)](https://github.com/reactive-firewall/multicast/blob/stable/LICENSE.md)