diff --git a/README.md b/README.md
index acddceb..35b5849 100644
--- a/README.md
+++ b/README.md
@@ -218,20 +218,33 @@ for example:
 
 These, if encountered, simply assign a value to an attribute on the parsed object.
 
-If no value is given `true` is assigned to indicate that the option/command is 
-present in the command-line.
+Any option/command can be passed a value, either explicitly (e.g. `-opt=123`) or 
+implicitly by first setting `.arg` (see examples below) and and then passing `-opt 123`.
+
+If no value is given `true` is assigned to option attribute on the parsed object 
+to indicate that the option/command is present in the command-line.
+
+Note that repeating a basic option/command will overwrite the previous value 
+unless `.collect` is set (see `-push` example below).
+
+Note that in general case option order in the command-line is not critical, 
+but option context can matter (see: [Active options/commands](#active-optionscommands) and [Nested parsers](#nested-parsers))
 
 ```javascript
 	'-bool': {
-		doc: 'if given set .bool to true' },
+		doc: 'if given, set .bool to true' },
 
 
 	// option with a value...
 	'-value': {
 		doc: 'set .x to X',
 
-		// 'X' (VALUE) is used for -help while 'x' (key) is where the 
-		// value will be written...
+		// 'X' (i.e. VALUE) is used to indicate the option value in -help 
+		// while 'x' (key) is the attribute where the value will be written...
+		//
+		// NOTE: if no .arg is set option attribute name is used.
+		//
+		// See the first example in "Calling the script" section below for output.
 		arg: 'X | x',
 
 		// the value is optional by default but we can make it required...
@@ -240,6 +253,9 @@ present in the command-line.
 
 
 	// setup an alias -r -> -required
+	//
+	// NOTE: aliases are used only for referencing, all naming is done via the 
+	//		actual option/command name.
 	'-r': '-required',
 
 	// a required option...
@@ -257,7 +273,7 @@ present in the command-line.
 	},
 
 
-	'-int': {
+	'-i': {
 		doc: 'pass an integer value',
 
 		// NOTE: if not key is given the VALUE name is used as a key, so the 
@@ -282,7 +298,7 @@ present in the command-line.
 
 	'-home': {
 		doc: 'set home path',
-		arg: 'HOME | home',
+		arg: 'PATH | home_path',
 
 		// get the default value from the environment variable $HOME...
 		env: 'HOME',
@@ -300,6 +316,10 @@ present in the command-line.
 	},
 ```
 
+For more info on available `.type` and `.collect` handlers see: 
+[`<option>.type`](#optiontype) and [`<option>.collect`](#optioncollect)
+respectively.
+
 
 ### Commands
 
@@ -338,6 +358,11 @@ And for quick-n-dirty hacking stuff together, a shorthand (_not for production u
 	},
 ```
 
+Option's `.handler(..)` only sees the `args` that follow it in the command line, 
+thus anything it may expect/get from the arguments must follow it (in the manner 
+it expects), `argv.js` poses no restrictions on full or partial manual handling
+of arguments by options/commands.
+
 
 ### Nested parsers
 
@@ -364,6 +389,10 @@ exits, then the parent parser will pick up where it left.
 Externally it is treated in exactly the same way as a normal _function_ handler, 
 essentially, the parent parser does not know the difference between the two.
 
+As with [Active options/commands](#active-optionscommands) the nested 
+parser (essentially an active option itself) only sees the arguments that 
+follow it in the command-line and may have arbitrary expectations of them.
+
 For more detail see the [Nested parsers](./ADVANCED.md#nested-parsers) section 
 in detailed docs.
 
@@ -471,8 +500,8 @@ Options:
              --bool             - if given set .bool to true
              --value=X          - set .x to X
                                   (required value)
-             --int=INT          - pass an integer value
-             --home=HOME        - set home path
+        -i=INT                  - pass an integer value
+             --home=PATH        - set home path
                                   (env: $HOME)
         -p,  --push=ELEM        - push elements to a .list
         -c                      - command
@@ -512,7 +541,7 @@ Parser {
   required_option_given: true,
   ...
   default: 'some value',
-  home: '...'
+  home_path: '...'
 }
 ```
 Notice the default values are set in the output above (output partially truncated
@@ -604,4 +633,4 @@ Copyright (c) 2016-2020, Alex A. Naanou,
 All rights reserved.
 
 
-<!-- vim:set ts=4 sw=4 spell : -->
+<!-- vim:set ts=4 sw=4 spell : -->
\ No newline at end of file
diff --git a/argv.js b/argv.js
index 130bdc6..e7c9976 100644
--- a/argv.js
+++ b/argv.js
@@ -266,6 +266,14 @@ function(attr, func){
 // 			- 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/examples/options.js b/examples/options.js
index 59a0a35..a6683da 100644
--- a/examples/options.js
+++ b/examples/options.js
@@ -13,18 +13,23 @@ argv.Parser({
 	author: 'John Smith <j.smith@some-mail.com>',
 	license: 'BSD-3-Clause',
 
-	footer: 'Written by $AUTHOR ($VERSION / $LICENSE).',
+	footer: 'Written by: $AUTHOR\nVersion: $VERSION / License: $LICENSE',
+	
 	
 	'-bool': {
-		doc: 'if given set .bool to true' },
+		doc: 'if given, set .bool to true' },
 
 
 	// option with a value...
 	'-value': {
 		doc: 'set .x to X',
 
-		// 'X' (VALUE) is used for -help while 'x' (key) is where the 
-		// value will be written...
+		// 'X' (i.e. VALUE) is used to indicate the option value in -help 
+		// while 'x' (key) is the attribute where the value will be written...
+		//
+		// NOTE: if no .arg is set option attribute name is used.
+		//
+		// See the first example in "Calling the script" section below for output.
 		arg: 'X | x',
 
 		// the value is optional by default but we can make it required...
@@ -50,7 +55,7 @@ argv.Parser({
 	},
 
 
-	'-int': {
+	'-i': {
 		doc: 'pass an integer value',
 
 		// NOTE: if not key is given the VALUE name is used as a key, so the 
@@ -73,10 +78,9 @@ argv.Parser({
 	},
 
 
-	// XXX this is misbehaving -- setting true instead of $HOME
 	'-home': {
 		doc: 'set home path',
-		arg: 'HOME | home',
+		arg: 'PATH | home_path',
 
 		// get the default value from the environment variable $HOME...
 		env: 'HOME',
@@ -112,6 +116,7 @@ argv.Parser({
 		// ...
 	},
 
+
 	'@nested': argv.Parser({
 			// ...
 		}).then(function(){
@@ -120,6 +125,7 @@ argv.Parser({
 	
 	'@bare': require('./bare').parser,
 
+
 	'-then': { 
 		handler: function(){
 			return argv.THEN } },
@@ -127,6 +133,7 @@ argv.Parser({
 		handler: function(){
 			return argv.STOP } },
 
+
 	'-error': {
 		handler: function(){
 			throw argv.ParserError('something went wrong.') } },
diff --git a/package.json b/package.json
index c8c7fb3..13893a6 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ig-argv",
-  "version": "2.10.3",
+  "version": "2.10.4",
   "description": "simple argv parser",
   "main": "argv.js",
   "scripts": {