Update cliparser.md

doc/cliparser.md

@@ -1,12 +1,33 @@
-# cliparser - proxmark3-rrg
+# Cliparser
+
+The old style with mixed custom commandline parsing of user parameters or options was messy and confusing.  You can find all kinds in the Proxmark3 client.
+Samples
+```
+data xxxx h
+script run x.lua -h
+hf 14a raw -h
+hf 14b raw -ss
+lf search 1
+lf config h H
+```
+In order to counter this and unify it,  there was discussion over at the official repository a few years ago (link to issue)  and there it became clear a change is needed. Among the different solutions suggested @merlokk's idea of using the lib cliparser was agreed upon. The lib was adapted and implemented for commands like 
+```
+emv
+hf fido
+```
+And then it fell into silence since it wasn't well documented how to use the cliparser.  Looking at source code wasn't very efficient.  However the need of a better cli parsing was still there. Fast forward today,  where more commands has used the cliparser but it still wasn't the natural way when adding a new client command to the Proxmark3 client.  After more discussions among @doegox, @iceman1001 and @mrwalker the concept became more clear on how to use the cliparser lib in the _preferred_ way.   The aftermath was a design and layout specfied which lead to a simpler implemtentation of the cliparser in the client source code while still unfiy all helptexts with the new colours support and a defined layout. As seen below, the simplicity and clearness. 
+
+![sample of new style helptext](http://www.icedev.se/proxmark3/helptext.png)
+
+
 
 ## cliparser setup and use
 
-*** Draft notes - needs work ***
+The parser will format and color and layout as needed.
-
+It will also add the `-h --help` option automatic.
-Note: the parser will format and color and layout as needed.
 
 ## design comments
+
 * where possiable all options should be lowercase.  
 * extended options preceeded with -- should be short  
 * options provided directly (without an option identifier) should be avoided.  
@@ -14,6 +35,8 @@ Note: the parser will format and color and layout as needed.
 * with --options the equal is not needed (will work with and without) so dont use '='  
   e.g. cmd --cn 12345
 
+
+
 ## common options
     -h --help       : help
     --cn            : card number
@@ -25,6 +48,10 @@ Note: the parser will format and color and layout as needed.
     -v --verbose    : flag when output should provide more information, not conidered debug.
     -1 --buffer     : use the sample buffer
 
+
+
+## How to implement in source code
+
 ### setup the parser data structure
 Header file to include
 
@@ -61,6 +88,9 @@ e.g. lf indala clone -r a0000000a0002021 -> this uses .....
         arg_param_end
     };
 
+_All options has a parameter index,  since `-h --help` is added automatic, it will be assigned index 0.
+Hence all options you add will start at index 1 and upwards._
+
 **Notes:**  
 booleen : arg_lit0 ("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>)