docs cleanup...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

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...
 

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` – generate and print help
   - `-version` – print version
   - `-quiet` – suppress printing
   - `-` – stop argument processing
-- Extensible:
+- Extensible
-  - Hooks for dynamic option/command handling
-  - Customizable error and stop condition handling
 
 
 ### 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
 

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 
+// XXX PROBLEM: setting option value can overload and break existing API, 
-// 		example:
+// 		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 =

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": {