docs: split code from prose

19 files changed, 212 insertions, 184 deletions

diff --git a/doc/0_00_welcome.adoc b/doc/0_00_welcome.adoc
index 70bdc90d..12f974b2 100644
--- a/doc/0_00_welcome.adoc
+++ b/doc/0_00_welcome.adoc
@@ -38,7 +38,6 @@ But colm is also the driving force in http://www.colm.net/open-source/ragel/[the
 
 Colm's development started by https://twitter.com/ehdtee[Adrian Thurston] during his http://www.colm.net/files/colm/thurston-phdthesis.pdf[Ph.D. thesis] period after intensive study of http://research.cs.queensu.ca/~cordy/Papers/TC_SCAM06_ETXL.pdf[TXL].
 
-
 === When not to use Colm
 
 Colm is meant to create executables or object files that can be linked in other programs. 
diff --git a/doc/0_01_installing.adoc b/doc/0_01_installing.adoc
index a55bfa9c..af8fbf0d 100644
--- a/doc/0_01_installing.adoc
+++ b/doc/0_01_installing.adoc
@@ -16,11 +16,15 @@ sudo make install
 
 When we do:
 
- /opt/colm/bin/colm
+----
+/opt/colm/bin/colm
+----
 
 We get:
 
- error: colm: colm: no input file given
+----
+error: colm: colm: no input file given
+----
 
 It works!
 
diff --git a/doc/0_02_vim_syntax.adoc b/doc/0_02_vim_syntax.adoc
index f29ca33c..168747d4 100644
--- a/doc/0_02_vim_syntax.adoc
+++ b/doc/0_02_vim_syntax.adoc
@@ -14,4 +14,6 @@ au BufRead,BufNewFile *.lm set filetype=colm
 
 When we open an '.lm' file, we will see some colors
 
- vi src/colm.lm
+----
+vi src/colm.lm
+----
diff --git a/doc/0_03_commandline.adoc b/doc/0_03_commandline.adoc
index 9613ab11..980003b0 100644
--- a/doc/0_03_commandline.adoc
+++ b/doc/0_03_commandline.adoc
@@ -3,7 +3,9 @@ Commandline
 
 Let's start colm with the '--help' command line argument.
 
- colm --help
+----
+colm --help
+----
 
 NOTE: This reflects the development version 0.13.0.4;
 
diff --git a/doc/0_04_hello_world.adoc b/doc/0_04_hello_world.adoc
index 4f9bea29..0406a159 100644
--- a/doc/0_04_hello_world.adoc
+++ b/doc/0_04_hello_world.adoc
@@ -6,7 +6,7 @@ The obligatory 'hello world' program:
 [source,chapel]
 .hello_world.lm
 ----
-print "hello world" "\n"
+include::code/hello_world.lm[]
 ----
 
 We run it with:
@@ -24,15 +24,21 @@ This creates a executable chmod+x file with the same name:
 ls -l hello_world
 ----
 
- -rwxr-xr-x 1 peter peter 29848 Nov  2 10:06 /tmp/hello_world
+----
+-rwxr-xr-x 1 peter peter 29848 Nov  2 10:06 /tmp/hello_world
+----
 
 When we execute it:
 
- ./hello_world
+----
+./hello_world
+----
 
 We'll see:
 
- hello world
+----
+hello world
+----
 
 We can strip the file to check if we can reduce the executable.
 [source,bash]
@@ -41,13 +47,15 @@ strip ./hello_world
 ls -l hello_words
 ----
 
- -rwxr-xr-x 1 peter peter 10360 Nov  2 10:10 /tmp/hello_world
+----
+-rwxr-xr-x 1 peter peter 10360 Nov  2 10:10 /tmp/hello_world
+----
 
 == Deja-vu: python2-python3
 TIP: It turns out that print is also a function that can have multiple arguments.
 
 [source,chapel]
-.hello_world_ext.lm]
+.hello_world_ext.lm
 ----
 print( 'hello ', "world" "\r\n" )
 ----
diff --git a/doc/0_05_fizzbuzz.adoc b/doc/0_05_fizzbuzz.adoc
index c6f439d9..6e30279e 100644
--- a/doc/0_05_fizzbuzz.adoc
+++ b/doc/0_05_fizzbuzz.adoc
@@ -9,16 +9,7 @@ With some modifications we can reactivate this example.
 [source,chapel]
 .figure_44.lm
 ----
-i: int = 0
-j: int = i
-
-while ( i < 10 ) {
-    if ( i * ( 10 - i ) < 20 ) {
-        print ( "hello ", i, ' ', j , '\n' )
-        j = j+ 1
-    }
-    i = i + 1
-}
+include::code/figure_44.lm[]
 ----
 
 Please Note:
@@ -50,26 +41,7 @@ It is the next logical step to 'hello world'.
 [source,chapel]
 .fizzbuzz.lm
 ----
-int modulo( value:int, div:int) {
-    times:int = value / div
-    return value - ( times * div )
-}
-
-i:int = 0
-while( i < 20 ) {
-    mod5:int = modulo( i, 5 )
-    mod3:int = modulo( i, 3 )
-    if ( mod5 == 0 && mod3 == 0 ) {
-        print( "FizzBuzz\n" )
-    } elsif( mod5 == 0 ) {
-        print( "Buzz\n" )
-    } elsif( mod3 == 0 ) {
-        print( "Fizz\n" )
-    } else {
-        print( i, "\n" )
-    }
-    i = i + 1
-}
+include::code/fizzbuzz.lm[]
 ----
 
 It appears that there is no modulo operator ('%').
diff --git a/doc/0_06_scope.adoc b/doc/0_06_scope.adoc
index 5025052c..2c411a61 100644
--- a/doc/0_06_scope.adoc
+++ b/doc/0_06_scope.adoc
@@ -7,38 +7,7 @@ This forces us to clarify 'scope'.
 [source,chapel]
 ./scope.lm
 ----
-str d (where:str) {
-    print( "in D ", where, "\n")
-    where = "d"
-    print( "in D ", where, "\n")
-}
-
-str c ( ) {
-    print( "in C ", where_g, "\n")
-    where_g = "c"
-    print( "in C ", where_g, "\n")
-}
-
-str b ( where:str ) {
-    print( "in B ", where, "\n")
-    where = "b" 
-    print( "in B ", where, "\n")
-}
-
-str a( where:str ) {
-    print( "in A ", where, "\n")
-    where = "a" 
-    b( where )
-    print( "in A ", where, "\n")
-}
-
-where: str =  "global"
-print( "in global ", where, "\n")
-a( where )
-print( "in global ", where, "\n")
-global where_g:str
-c( )
-print( "in global ", where_g, "\n")
+include::code/scope.lm[]
 ----
 
 We run it with
@@ -66,28 +35,7 @@ The thesis also mentions that variables can be passed by reference instead of by
 [source,chapel]
 .nested_scope.lm
 ----
-str a( where:str ) {
-    print( "before block1 ", where, "\n" )
-    while(true) {
-        where = "block1"
-        print( "in block1 ", where, "\n" )
-        i:int = 0
-        while( true ) {
-            where =  where + "a"
-            print( "in loop ", where, "\n" )
-            break
-        }
-        print( "in block1 ", where, "\n" )
-        break
-    }
-    print( "in A ", where, "\n" )
-    return where
-}
-
-where: str =  "global"
-print( "in global ", where, "\n" )
-a( where )
-print( "in global ", where, "\n" )
+include::code/nested_scope.lm[]
 ----
 
 That gives us:
diff --git a/doc/1_04_functions.adoc b/doc/1_04_functions.adoc
index efd80131..262a206b 100644
--- a/doc/1_04_functions.adoc
+++ b/doc/1_04_functions.adoc
@@ -3,26 +3,15 @@ Functions
 
 The 'FizzBuzz' example gave us an good overview.
 
-
 == Arguments 'by reference'
 
 We can also pass parameters by reference.
 This enables us to change the variable with in the function.
 
-
 [source,chapel]
 ./reference.lm
 ----
-str sa( where:ref < str > ) {
-    print( "in SA ", where, "\n" )
-    where = "sa"
-    print( "in SA ", where, "\n" )
-}
-
-where: str =  "global"
-print( "in global ", where, "\n" )
-sa( where )
-print( "in global ", where, "\n" )
+include::code/reference.lm[]
 ----
 
 Compiling and running would give us:
diff --git a/doc/2_02_list_map_struct_alias.adoc b/doc/2_02_list_map_struct_alias.adoc
index f10c1ec8..adaccc7f 100644
--- a/doc/2_02_list_map_struct_alias.adoc
+++ b/doc/2_02_list_map_struct_alias.adoc
@@ -9,60 +9,7 @@ An example is probably much clearer then 1000 loc.
 [source,chapel]
 .poker.md
 ----
-alias Value_t map<int,str>
-values:Value_t = new Value_t()
-
-values->insert(0, "Ace")
-values->insert(1, "1")
-values->insert(2, "2")
-values->insert(3, "3")
-values->insert(4, "4")
-values->insert(5, "5")
-values->insert(6, "6")
-values->insert(7, "7")
-values->insert(8, "8")
-values->insert(9, "9")
-values->insert(10, "Ten")
-values->insert(11, "Jack")
-values->insert(12, "Queen")
-values->insert(13, "King")
-
-alias Suit_t map<int,str> 
-suit:Suit_t = new Suit_t()
-suit->insert(1, "hearts")
-suit->insert(2, "spades")
-suit->insert(3, "diamonds")
-suit->insert(4, "clubs")
-
-struct Card_t
-    s:int
-    v:int
-end
-
-alias Hand_t list<Card_t>
-
-struct Person_t
-    name:str
-    age:int
-    hand:Hand_t
-end
-
-john:Person_t
-
-john = new Person_t()
-john->name = "john"
-john->age = 18
-john->hand = new Hand_t()
-
-card:Card_t = new Card_t()
-card->s = 2
-card->v = 13
-john->hand->push(card)
-
-print("ok ", john->name, " ", john->age, "\n")
-for card:Card_t in john->hand {
-    print("\n\t", suit->find(card->s), " ", values->find(card->v), "\n")
-}
+include::code/poker.lm[]
 ----
 
 When we run this we get:
@@ -73,5 +20,4 @@ ok john 18
 	spades King
 ----
 
-
 NOTE: this also illustrates how to iterate through a 'list' and access elements in a 'map'.
diff --git a/doc/2_03_def.adoc b/doc/2_03_def.adoc
index bd3b87aa..0ef66ae8 100644
--- a/doc/2_03_def.adoc
+++ b/doc/2_03_def.adoc
@@ -8,27 +8,7 @@ Again one example is much more clearer.
 [source,chapel]
 .assign.lm
 ----
-lex start
-	token id / ('a' .. 'z' | 'A' .. 'Z' ) + /
-	token value / ( 'a' .. 'z' | 'A' .. 'Z' | '0' .. '9' )+ /
-	literal `= `;
-	ignore / [ \t\n] /
-end
-
-def assignment
-	[ id `=  value `;]
-
-	
-def assignment_list
-	[assignment assignment_list]
-|	[assignment]
-|	[]
-
-parse Simple: assignment_list[ stdin ]
-
-for I:assignment in Simple {
-	print( I.id, "->", I.value, "\n" )
-}
+include::code/assign.lm[]
 ----
 
 After the compilation we can pipe some input to it's stdin.
diff --git a/doc/9_00_q_and_a.adoc b/doc/9_00_q_and_a.adoc
index a143ab02..dea8126c 100644
--- a/doc/9_00_q_and_a.adoc
+++ b/doc/9_00_q_and_a.adoc
@@ -4,7 +4,9 @@ Q and A
 == FAQ
 
 .Q: I get this error
- error while loading shared libraries: libcolm-0.13.0.4.so: cannot open shared object file: No such file or directory
+----
+error while loading shared libraries: libcolm-0.13.0.4.so: cannot open shared object file: No such file or directory
+----
 
 *A*: You probably configured and installed colm with the '--prexix' argument
 You can find the dynamic library and symlink it to a familiar place.
diff --git a/doc/code/assign.lm b/doc/code/assign.lm
new file mode 100644
index 00000000..d8b40d76
--- /dev/null
+++ b/doc/code/assign.lm
@@ -0,0 +1,22 @@
+lex start
+	token id / ('a' .. 'z' | 'A' .. 'Z' ) + /
+	token value / ( 'a' .. 'z' | 'A' .. 'Z' | '0' .. '9' )+ /
+	literal `= `;
+	ignore / [ \t\n] /
+end
+
+def assignment
+	[ id `=  value `;]
+
+	
+def assignment_list
+	[assignment assignment_list]
+|	[assignment]
+|	[]
+
+parse Simple: assignment_list[ stdin ]
+
+for I:assignment in Simple {
+	print( I.id, "->", I.value, "\n" )
+}
+
diff --git a/doc/code/figure_44.lm b/doc/code/figure_44.lm
new file mode 100644
index 00000000..fab421ed
--- /dev/null
+++ b/doc/code/figure_44.lm
@@ -0,0 +1,10 @@
+i: int = 0
+j: int = i
+
+while ( i < 10 ) {
+    if ( i * ( 10 - i ) < 20 ) {
+        print ( "hello ", i, ' ', j , '\n' )
+        j = j+ 1
+    }
+    i = i + 1
+}
diff --git a/doc/code/fizzbuzz.lm b/doc/code/fizzbuzz.lm
new file mode 100644
index 00000000..b937be4a
--- /dev/null
+++ b/doc/code/fizzbuzz.lm
@@ -0,0 +1,21 @@
+int modulo( value:int, div:int) {
+    times:int = value / div
+    return value - ( times * div )
+}
+
+i:int = 0
+while( i < 20 ) {
+    mod5:int = modulo( i, 5 )
+    mod3:int = modulo( i, 3 )
+    if ( mod5 == 0 && mod3 == 0 ) {
+        print( "FizzBuzz\n" )
+    } elsif( mod5 == 0 ) {
+        print( "Buzz\n" )
+    } elsif( mod3 == 0 ) {
+        print( "Fizz\n" )
+    } else {
+        print( i, "\n" )
+    }
+    i = i + 1
+}
+
diff --git a/doc/code/hello_world.lm b/doc/code/hello_world.lm
new file mode 100644
index 00000000..5522c5e1
--- /dev/null
+++ b/doc/code/hello_world.lm
@@ -0,0 +1 @@
+print "hello world" "\n"
diff --git a/doc/code/nested_scope.lm b/doc/code/nested_scope.lm
new file mode 100644
index 00000000..e84c216a
--- /dev/null
+++ b/doc/code/nested_scope.lm
@@ -0,0 +1,23 @@
+str a( where:str ) {
+    print( "before block1 ", where, "\n" )
+    while(true) {
+        where = "block1"
+        print( "in block1 ", where, "\n" )
+        i:int = 0
+        while( true ) {
+            where =  where + "a"
+            print( "in loop ", where, "\n" )
+            break
+        }
+        print( "in block1 ", where, "\n" )
+        break
+    }
+    print( "in A ", where, "\n" )
+    return where
+}
+
+where: str =  "global"
+print( "in global ", where, "\n" )
+a( where )
+print( "in global ", where, "\n" )
+
diff --git a/doc/code/poker.lm b/doc/code/poker.lm
new file mode 100644
index 00000000..2e776a96
--- /dev/null
+++ b/doc/code/poker.lm
@@ -0,0 +1,55 @@
+alias Value_t map<int,str>
+values:Value_t = new Value_t()
+
+values->insert(0, "Ace")
+values->insert(1, "1")
+values->insert(2, "2")
+values->insert(3, "3")
+values->insert(4, "4")
+values->insert(5, "5")
+values->insert(6, "6")
+values->insert(7, "7")
+values->insert(8, "8")
+values->insert(9, "9")
+values->insert(10, "Ten")
+values->insert(11, "Jack")
+values->insert(12, "Queen")
+values->insert(13, "King")
+
+alias Suit_t map<int,str> 
+suit:Suit_t = new Suit_t()
+suit->insert(1, "hearts")
+suit->insert(2, "spades")
+suit->insert(3, "diamonds")
+suit->insert(4, "clubs")
+
+struct Card_t
+    s:int
+    v:int
+end
+
+alias Hand_t list<Card_t>
+
+struct Person_t
+    name:str
+    age:int
+    hand:Hand_t
+end
+
+john:Person_t
+
+john = new Person_t()
+john->name = "john"
+john->age = 18
+john->hand = new Hand_t()
+
+card:Card_t = new Card_t()
+card->s = 2
+card->v = 13
+john->hand->push(card)
+
+print("ok ", john->name, " ", john->age, "\n")
+for card:Card_t in john->hand {
+    print("\n\t", suit->find(card->s), " ", values->find(card->v), "\n")
+}
+
diff --git a/doc/code/reference.lm b/doc/code/reference.lm
new file mode 100644
index 00000000..122ab6f6
--- /dev/null
+++ b/doc/code/reference.lm
@@ -0,0 +1,11 @@
+str sa( where:ref < str > ) {
+    print( "in SA ", where, "\n" )
+    where = "sa"
+    print( "in SA ", where, "\n" )
+}
+
+where: str =  "global"
+print( "in global ", where, "\n" )
+sa( where )
+print( "in global ", where, "\n" )
+
diff --git a/doc/code/scope.lm b/doc/code/scope.lm
new file mode 100644
index 00000000..e559234c
--- /dev/null
+++ b/doc/code/scope.lm
@@ -0,0 +1,33 @@
+str d (where:str) {
+    print( "in D ", where, "\n")
+    where = "d"
+    print( "in D ", where, "\n")
+}
+
+str c ( ) {
+    print( "in C ", where_g, "\n")
+    where_g = "c"
+    print( "in C ", where_g, "\n")
+}
+
+str b ( where:str ) {
+    print( "in B ", where, "\n")
+    where = "b" 
+    print( "in B ", where, "\n")
+}
+
+str a( where:str ) {
+    print( "in A ", where, "\n")
+    where = "a" 
+    b( where )
+    print( "in A ", where, "\n")
+}
+
+where: str =  "global"
+print( "in global ", where, "\n")
+a( where )
+print( "in global ", where, "\n")
+global where_g:str
+c( )
+print( "in global ", where_g, "\n")
+