rewritten part of the doc...

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

Slang/slang.js

@@ -384,20 +384,40 @@ var NAMESPACE = {
 // NOTE: hate how JS handles multi-line strings...
 var BOOTSTRAP = [
 '(------------------------------------------------------------------------------',
-' For a quick intro, Slang ([S]tack [lang]uage) consists of:',
+'',
-'	- Code',
+' Slang is a simple and complete [S]tack [lang]uage).',
+'',
+' Slang was designed for three main reasons:',
+'	- a means to experiment with several aspects of language design,',
+'	- an educational tool, to illustrate several programming language',
+'	  concepts in a simple, hands-on manner,',
+'	- fun!',
+'',
+'',
+'-------------------------------------------------------------------------------',
+'',
+' The system consists of:',
 '	- Stack',
+'	- Code',
 '	- Namespace',
+'	- basic runtime',
+'',
+' 	                 { NAMESPACE }',
+'	                       ^',
+'	                       |',
+' 	[ .. STACK .. ] <-- runtime -- [ .. CODE .. ]',
+'',
 '',
 ' A namespace is a basic key/value store.',
 '',
-' Entities from the code scream are read one by one and depending on',
+' The runtime "reads" entities from the code stream one by one and depending on',
-' their type are either pushed on the stack or evaluated.',
+' whether an entity exists in the namespace it is either pushed on the stack',
+' or evaluated.',
 '',
-' The later entity is traditionally called a "word" (function in',
+' The evaluated entity is traditionally called a "word" (function in non-stack',
-' non-stack languages).',
+' languages).',
 ' The only thing that makes a word different from any other entity is',
-' that it matches a key in the namespace.',
+' that it matches a key in the namespace, as mentioned above.',
 '',
 ' In Slang evaluation is done simply by executing the value of the matched',
 ' key/value pair in the namespace. An over-simplified way to explain',
@@ -410,8 +430,8 @@ var BOOTSTRAP = [
 '	- User words -- defined within the system (like this bootstrap code).',
 '',
 ' Words may read and affect any of the three system parts:',
-'	- Code',
 '	- Stack',
+'	- Code',
 '	- Namespace (not yet fully implemented)',
 '',
 ' Traditioannly, in stack languages words affect only the stack, this is',
@@ -425,18 +445,9 @@ var BOOTSTRAP = [
 '',
 '-----------------------------------------------------------------------------',
 '',
-'',
+' Traditionally, stack languages use a "stack effect" notation to document how',
-' To expalin stack and code effect some words here will use a not so',
+' words affect the stack state, a kind of before-after transformation. here is',
-' traditional notation, the "|" will indicate the split between the stack',
+' a basic example showing how the word "add" works:',
-' and code, here is a representation of the system:',
-'',
-' 	                 { NAMESPACE }',
-'',
-' 	[ .. STACK .. ] <-- runtime -- [ .. CODE .. ]',
-'',
-'',
-' And here is the new notation representing the states while we run through a',
-' word, "add" in this case:',
 '',
 '		stack   code',
 '		      | 1 2 add',
@@ -445,14 +456,19 @@ var BOOTSTRAP = [
 '		1 2 [add]			(a)',
 '		    3 |				(b)',
 '',
-' With stack effect is written like this:',
+'',
+' Here the stack effect represents the difference between two states: the',
+' moment when the word is "read" (a) and the stack state after it is',
+' evaluated (b) and is written like this:',
 '',
 '		( a b -- c )',
 '',
 '',
-' In traditional stack effect notation we indicate the difference between',
+' But, due to the fact that in Slang all three of the stack, code and namespace',
-' states (a) ans (b), but when we need to explain something like _swap we\'ll',
+' can be affected by words, we need an extended stack effect notation. to',
-' also affect the code, so the process will go like this (expanding "+" word):',
+' include at least the second most common case, the "code effect".',
+' To illustrate, here is an example of a word that has a simple code effect,',
+' the "+":',
 '',
 '		stack   code',
 '		      | 1 + 2',
@@ -460,20 +476,17 @@ var BOOTSTRAP = [
 '		   1 [+] 2			(a)',
 '		    3 |				(b)',
 '',
-' So here what "+" actually does is the difference between steps (a) and (b)',
+'',
-' thus the notation:',
+' Here we see that in addition to affecting the stack, 2 is "pulled" from the',
+' code stream. To indicate this we will use "|" that splits the stack (left)',
+' and code (right) states, and write the stack effect for the word "+" like',
+' this:',
 '',
 '		( a | b -- c |  )',
 '',
 '',
-' Just for illustration, here is how _swap ( a | b -- b | a ) works:',
+' NOTE: this notation is currently used as a means to documenting words and is',
-'',
+' not interpreted in any way.',
-'		stack   code',
-'		      | a _swap b',
-'		    a | _swap b',
-'		 a [_swap] b			(a)',
-'		    b | a			(b)',
-'',
 '',
 '------------------------------------------------------------------------------)',
 '--',