From 4fb5c01b2bad18cb9f90819f151632aa69a8f26d Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Sun, 2 Aug 2020 20:28:56 +0300
Subject: [PATCH] docs cleanup...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 ADVANCED.md  |  9 +++++++++
 README.md    | 24 ++++++++++++++++--------
 argv.js      | 12 ++----------
 package.json |  2 +-
 4 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/ADVANCED.md b/ADVANCED.md
index a37e6fa..a5e3794 100644
--- a/ADVANCED.md
+++ b/ADVANCED.md
@@ -59,6 +59,8 @@ For basics see [README.md](./README.md)
 		- [`<parser>.handleErrorExit(..)`](#parserhandleerrorexit)
 		- [`<parser>.handle(..)`](#parserhandle)
 		- [`<parser>.setHandlerValue(..)`](#parsersethandlervalue)
+	- [External utilities](#external-utilities)
+		- [`normalizeIndent(..)` / `normalizeTextIndent(..)`](#normalizeindent--normalizetextindent)
 	- [More...](#more)
 
 
@@ -813,6 +815,13 @@ directly.
 
 This is not intended for overloading.
 
+## External utilities
+
+### `normalizeIndent(..)` / `normalizeTextIndent(..)`
+
+`argv.js` uses and exposes [`object.js`](https://github.com/flynx/object.js)' 
+text normalization functions for convenient text/code formatting, see [original documentation](https://github.com/flynx/object.js#normalizeindent--normalizetextindent) for more info.
+
 
 ## More...
 
diff --git a/README.md b/README.md
index cd39b95..6cfbc74 100644
--- a/README.md
+++ b/README.md
@@ -22,22 +22,22 @@ This code is an evolution of that parser.
   nested contexts
 - Option expansion  
   `-abc` expands to `-a -b -c` if `-abc` is not defined
-- Option/command value passing  
+- Option/command value asignment  
   implicit `-a 123` (requires either _definition_ or manual handling) or 
   explicit `-a=123`
-- Environment variable option/command value defaults
+- Read option/command value defaults from environment variables
 - Option/command value conversion
 - Option/command value collection
-- Multiple option prefix support
+- Multiple option prefix support (by default `-` and `+` are handled)
+- Dynamic option/command handling
+- Customizable error and stop condition handling
 - Reasonable defaults:
-  - Metadata defaults to `package.json`
+  - Metadata read from `package.json`
   - `-help` &ndash; generate and print help
   - `-version` &ndash; print version
   - `-quiet` &ndash; suppress printing
   - `-` &ndash; stop argument processing
-- Extensible:
-  - Hooks for dynamic option/command handling
-  - Customizable error and stop condition handling
+- Extensible
 
 
 ### Planned
@@ -190,7 +190,10 @@ Basic script description
 ```javascript
 	doc: 'Example script options',
 ```
-	
+
+Note that `argv.js` exposes [object.js](https://github.com/flynx/object.js)'s 
+[`normalizeIndent(..)` / `normalizeTextIndent(..)`](https://github.com/flynx/object.js#normalizeindent--normalizetextindent) for convenient text/code formatting.
+
 Metadata:
 ```javascript
 	// to make things consistent we'll take the version from package.json
@@ -428,6 +431,11 @@ To stop option processing either return `STOP` or `THEN` from the handler.
 				return argv.STOP } },
 	```
 
+	`STOP` is needed in cases where we want to stop the parser and not trigger 
+	it's main functionality (i.e. [`<parser>.then(..)`](./ADVANCED.md#parserthen)),
+	for example this is needed when printing `-help` and related tasks like 
+	listing commands and other script interface documentation/introspection.
+
 
 ### Error reporting
 
diff --git a/argv.js b/argv.js
index 3da477f..f1f6315 100644
--- a/argv.js
+++ b/argv.js
@@ -258,22 +258,14 @@ function(attr, func){
 // 		currently both '-' and '+' are supported.
 // NOTE: essentially this parser is a very basic stack language...
 //
-// XXX setting option value can overload and break existing API, for 
-// 		example:
+// XXX PROBLEM: setting option value can overload and break existing API, 
+// 		and break parsing, for example:
 // 			@options: {},
 // 		shadow .options(..) and break parsing...
 // 		...not sure how to handle this...
 // 			- isolate parsed from parser
 // 			- isolate option data from parser
 // 			- ...
-// XXX for this option:
-// 			'-verbose': {
-// 				env: 'VERBOSE',
-// 				handler: function(){
-// 					// ...
-// 				} },
-// 		need to be able to tell if -verbose was passed explicitly or not 
-// 		in the handler...
 // XXX should -help work for any command? ..not just nested parsers?
 // 		...should we indicate which thinks have more "-help"??
 var Parser =
diff --git a/package.json b/package.json
index 05fc745..71dbcec 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ig-argv",
-  "version": "2.11.1",
+  "version": "2.11.2",
   "description": "simple argv parser",
   "main": "argv.js",
   "scripts": {