add index and guide pages

8 files changed, 96 insertions, 47 deletions

diff --git a/Makefile b/Makefile
index b1d7263..3a91ad9 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,11 @@ MODREFS=$(MODULES:lib/%.moon=docs/reference/%.html)
 
 .PHONY: docs clean
 
-docs: $(MODREFS) docs/reference/index.html
+docs: docs/index.html docs/guide.html $(MODREFS) docs/reference/index.html
+
+docs/%.html: docs/%.md extra/docs.moon extra/layout.moon
+	@echo "building page $<"
+	moon extra/docs.moon $@ markdown $<
 
 docs/reference/%.html: lib/%.moon extra/docs.moon extra/layout.moon
 	@echo "building docs for $<"
@@ -15,3 +19,4 @@ docs/reference/index.html: $(MODREFS) extra/docs.moon extra/layout.moon
 
 clean:
 	rm -rf docs/reference/*
+	rm docs/index.html docs/guide.html
diff --git a/README.md b/README.md
index 518dad9..0f1c359 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,12 @@ text-based language and works without special editor support.
 - [osc][osc]:               `luarocks install osc`
 - [socket][socket]:         `luarocks install luasocket`
 - [system][system]:         `luarocks install luasystem`
+- [discount][discount]:     `luarocks install discout` (optional, for docs)
 
+## docs
+
+with `make` the HTML documentation is generated in `docs/`.
+ 
 ## running
 
     $ moon init.moon <session.alv>
@@ -25,3 +30,4 @@ text-based language and works without special editor support.
 [osc]:        https://github.com/lubyk/osc
 [system]:     https://github.com/o-lim/luasystem
 [socket]:     http://w3.impa.br/~diego/software/luasocket/
+[discount]:   https://luarocks.org/modules/craigb/discount
diff --git a/core/builtin.moon b/core/builtin.moon
index c91e930..1ec6a9a 100644
--- a/core/builtin.moon
+++ b/core/builtin.moon
@@ -14,8 +14,8 @@ prints the docstring for sym in the console"
 
     result = L\push tail[1]\eval, scope
     with Result children: { def }
-      def = result\const!\unwrap!
-      L\print "(doc #{tail[1]\stringify!}):\n#{def.doc}\n"
+      value = result\const!
+      L\print "(doc #{tail[1]\stringify!}):\n#{value.doc}\n"
 
 class def extends Action
   @doc: "(def sym1 val-expr1
@@ -68,7 +68,7 @@ name-str has to be an eval-time constant."
     name = result\const!
 
     L\trace @, "loading module #{name}"
-    Result value: Value.wrap require "lib.#{name\unwrap 'str'}"
+    Result value: require "lib.#{name\unwrap 'str'}"
 
 class import_ extends Action
   @doc: "(import sym1 [sym2]...) - require and define modules
@@ -81,7 +81,7 @@ requires modules sym1, sym2, ... and defines them as sym1, sym2, ... in the curr
 
     for child in *tail
       name = (child\quote scope)\unwrap 'sym'
-      scope\set name, Result value: Value.wrap require "lib.#{name}"
+      scope\set name, Result value: require "lib.#{name}"
 
     Result!
 
@@ -97,7 +97,7 @@ requires modules sym1, sym2, ... and merges them into the current scope"
 
     for child in *tail
       name = (child\quote scope)\unwrap 'sym'
-      scope\use (Value.wrap require "lib.#{name}")\unwrap 'scope'
+      scope\use (require "lib.#{name}")\unwrap 'scope'
 
     Result!
 
diff --git a/docs/guide.md b/docs/guide.md
new file mode 100644
index 0000000..0fb596d
--- /dev/null
+++ b/docs/guide.md
@@ -0,0 +1,13 @@
+% getting started
+% - 
+% -
+# getting started with alive
+
+```
+(import* debug math)
+
+(out "a" (+ 1 2))
+(out "b" (+ 3 4))
+```
+
+*(this site is currently under construction)*
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f8a5cdd
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,6 @@
+# `alive` - livecoding with persistent expressions
+
+<iframe allowfullscreen="true" frameborder="0" height="315" width="560"
+  src="https://www.youtube.com/embed/z0XZYnY3Evc"></iframe>
+
+*(this site is currently under construction)*
diff --git a/extra/docs.moon b/extra/docs.moon
index a8438cf..9e478e9 100644
--- a/extra/docs.moon
+++ b/extra/docs.moon
@@ -1,45 +1,66 @@
 import Value, Scope from require 'core'
-import render, write from require 'extra.layout'
+import render, layout from require 'extra.layout'
 import section, h2, p, ul, li, a, code, r from require 'extra.dom'
 
 export OUT
 { OUT, command } = arg
 
-write switch command
+slurp = (file) ->
+  file = io.open file, 'r'
+  with file\read '*all'
+    file\close!
+
+spit = (file, str) ->
+  file = io.open file, 'w'
+  file\write str
+  file\close!
+
+spit OUT, switch command
   when 'module'
     { _, _, module, name } = arg
 
     name or= module
     module = Scope.from_table require module
 
-    title: "#{name} module reference"
-    body: section {
-      h2 (code name), ' reference'
-      ul for key, res in pairs module.values
-        li render key, res.value
-    }
+    layout
+      title: "#{name} module reference"
+      body: section {
+        h2 (code name), ' reference'
+        ul for key, res in opairs module.values
+          li render key, res.value
+      }
 
   when 'reference'
-    title: 'reference index'
-    body: {
-      section {
-        id: 'modules'
-        h2 a "module index", href: '#modules'
-        p "These modules can be imported using #{r 'require'}, #{r 'import'} and " ..
-          "#{r 'import*'}."
-        ul for file in *arg[3,]
-          module = file\match '^lib/(.*)%.moon$'
-          li a (code module), href: "#{module}.html"
-      }
-      section {
-        id: 'builtins'
-        h2 a "builtins", href: '#builtins'
-        p "These definitions are automatically loaded into the global Scope of
-          every alive session."
-        ul for key, val in pairs require 'core.builtin'
-          li render key, Value.wrap val
+    layout
+      title: 'reference'
+      body: {
+        section {
+          id: 'modules'
+          h2 a "module index", href: '#modules'
+          p "These modules can be imported using #{r 'require'}, #{r 'import'} and " ..
+            "#{r 'import*'}."
+          ul for file in *arg[3,]
+            module = file\match '^lib/(.*)%.moon$'
+            li a (code module), href: "#{module}.html"
+        }
+        section {
+          id: 'builtins'
+          h2 a "builtins", href: '#builtins'
+          p "These definitions are automatically loaded into the global Scope of
+            every alive session."
+          ul for key, val in opairs require 'core.builtin'
+            li render key, Value.wrap val
+        }
       }
-    }
+
+  when 'markdown'
+    import compile from require 'discount'
+
+    { _, _, file } = arg
+    contents = slurp file
+    require 'discount'
+
+    layout compile contents, 'githubtags', 'fencedcode'
 
   else
     error "unknown command '#{command}'"
diff --git a/extra/dom.moon b/extra/dom.moon
index 73dc743..7541fbd 100644
--- a/extra/dom.moon
+++ b/extra/dom.moon
@@ -1,6 +1,8 @@
 -- mmm.dom
 -- see https://mmm.s-ol.nu/meta/mmm.dom/
 
+export opairs
+
 -- ordered table iterator, for stable(r) renderers
 sort = (t, order_fn, only_strings) ->
   with index = [k for k,v in pairs t when (not only_strings) or 'string' == type k]
diff --git a/extra/layout.moon b/extra/layout.moon
index 1a4ee7b..71bbfb2 100644
--- a/extra/layout.moon
+++ b/extra/layout.moon
@@ -7,7 +7,7 @@ render = (name, value, prefix=nil) ->
 
   content = switch value.type
     when 'scope'
-      ul for k, result in pairs value!.values
+      ul for k, result in opairs value!.values
         li render k, result.value, id
     when 'opdef', 'builtin'
       p value!.doc
@@ -33,16 +33,11 @@ r = (name, page='') ->
   import a, code from require 'extra.dom'
   a (code name), href: "#{page}##{name}"
 
-spit = (file, str) ->
-  file = io.open file, 'w'
-  file\write str
-  file\close!
-
 -- layout and write a doc page
 -- opts:
 --  - title
 --  - body
-write = (opts) ->
+layout = (opts) ->
   import nav, div, span, b, code, i, a, article from require 'extra.dom'
 
   navigation = nav div {
@@ -53,16 +48,17 @@ write = (opts) ->
     a 'reference', href: abs 'reference/index.html'
   }
   body = article opts.body
+  title = if opts.title
+    "#{opts.title} - alive"
+  else
+    "alive documentation"
 
-  assert OUT, "OUT needs to be set"
-  spit OUT, "<!DOCTYPE html>
+  "<!DOCTYPE html>
 <html>
   <head>
-    <title>#{opts.title} - alive docs</title>
+    <title>#{title}</title>
     <link rel=\"stylesheet\" href=\"#{abs 'style.css'}\">
-    <style>
-
-    </style>
+    #{opts.css or ''}
   </head>
   <body>
     #{navigation}
@@ -74,5 +70,5 @@ write = (opts) ->
 {
   :r
   :render
-  :write
+  :layout
 }