split guide into guide and reference

19 files changed, 98 insertions, 61 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
index 9aad8c7..189bd90 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,4 +1,3 @@
 *.html
 ldoc.*
 internals/*.css
-reference
diff --git a/docs/gen/index b/docs/gen/index
index dff601a..20fb3bd 100755
--- a/docs/gen/index
+++ b/docs/gen/index
@@ -1,8 +1,8 @@
 #!/usr/bin/env moon
 require 'alv'
-import render, layout, autoref from require 'docs.gen.layout'
+import render, layout, autoref, subnav from require 'docs.gen.layout'
 import section, h1, h2, p, ul, li, a, code from require 'docs.gen.dom'
-import opairs from require 'alv.util'
+import compile from require 'discount'
 
 export OUT
 
@@ -16,34 +16,15 @@ spit = (file, str) ->
   file\write str
   file\close!
 
-{ OUT } = arg
+{ OUT, file } = arg
 
+md = slurp file
+for file in *arg[3,]
+  if mod = file\match '/module/(.*)%.html'
+    name = mod\gsub '/', '.'
+    md ..= "   - [`#{name}`](module/#{mod}.html)\n"
+
+content = compile (autoref md), 'githubtags', 'fencedcode'
+sub = subnav [a for a in *arg[3,]]
 spit OUT, layout
-  title: 'reference'
-  body: {
-    h1 (code 'alive'), " language reference"
-    p "This section documents all builtins and modules that are currently
-      available in the alive programming language."
-    p autoref "If you are new to alive, the [getting started guide][:../guide/:] is
-      the recommended place to start. If you are looking for
-      information on adding your own module or contributing to alive, check
-      out the [developer documentation][:../internals/index/:]."
-    section {
-      id: 'modules'
-      h2 a "module index", href: '#modules'
-      p autoref "These modules can be imported using [require][], " ..
-        "[import][] and [import*][]."
-      ul for file in *arg[2,]
-        path = file\match '^alv%-lib/(.*)%.moon$'
-        name = path\gsub '/', '.'
-        li a (code name), href: "#{path}.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 'alv.builtins').values
-        li render key, val.result
-    }
-  }
+  body: table.concat { sub, content.body }, '\n\n'
diff --git a/docs/gen/layout.moon b/docs/gen/layout.moon
index 1b1cdaa..7d3c4e1 100644
--- a/docs/gen/layout.moon
+++ b/docs/gen/layout.moon
@@ -67,7 +67,10 @@ link = (ref) ->
   return version.release if ref == '*release*'
 
   mod, sym = ref\match '^(.+)/(.*)$'
-  abs "reference/#{mod or 'index'}.html##{sym or ref}"
+  if mod
+    abs "reference/module/#{mod}.html##{sym or ref}"
+  else
+    abs "reference/builtins.html##{sym or ref}"
 
 -- link to a reference
 r = (text, ref) ->
@@ -88,10 +91,33 @@ autoref = (str) ->
 
 subnav = do
   split_name = (file) ->
-    href, label = file\match '^docs/(.*/([%w%-]+)%.html)'
+    if href = file\match '^docs/(.*/index.html)$'
+      return 'index', href
+
+    href, label = file\match '^docs/(.*/([%d%w-_]+)%.html)$'
+    label = (label\match '^[%d-]+_([%w-]+)$') or label
     label = label\gsub '-', ' '
     label, href
 
+  title = (file) ->
+    if file == 'docs/guide/index.html'
+      return "getting started guide"
+    if file == 'docs/reference/index.html'
+      return "<code>alv</code> language reference"
+    elseif mod = file\match '^docs/reference/module/(.*)%.html$'
+      return "<code>#{mod}</code> module reference"
+    elseif href = file\match '^docs/(.*/index.html)$'
+      error "index page without hardcoded name: #{href}"
+
+    num, label = file\match '/([%d-]+)_([%w%-]+)%.html$'
+    if num
+      num = num\gsub '%f[%d]0', ''
+      num = num\gsub '-', '.'
+      label = label\gsub '-', ' '
+      "#{num}. #{label}"
+    else
+      (file\match '/([%w%-]+)%.html$')
+
   subnav_link = (dir, file) ->
     import span, a, u from dom
 
@@ -119,7 +145,7 @@ subnav = do
 
     div {
       class: 'subheader'
-      h1 (split_name OUT)
+      h1 (title OUT)
       nav {
         subnav_link 'l', all[c-1]
         subnav_link 'r', all[c+1]
@@ -129,7 +155,7 @@ subnav = do
 aopts = (href, pat) ->
   {
     href: abs href
-    class: if OUT\match "^docs/#{pat}" then 'active'
+    class: if OUT\match pat then 'active'
   }
 
 -- layout and write a doc page
@@ -149,10 +175,10 @@ layout = (opts) ->
       ' documentation'
     }
     div class: 'grow'
-    a 'home', aopts 'index.html', 'index.html$'
-    a 'guide', aopts 'guide/getting-started-guide.html', 'guide'
-    a 'reference', aopts 'reference/index.html', 'reference'
-    a 'internals', aopts 'internals/index.html', 'ldoc'
+    a 'home', aopts 'index.html', '^docs/index.html$'
+    a 'guide', aopts 'guide/index.html', '^docs/guide'
+    a 'reference', aopts 'reference/index.html', '^docs/reference'
+    a 'internals', aopts 'internals/index.html', '^docs/ldoc'
   }
   body = article opts.body
   title = if opts.title
diff --git a/docs/gen/module b/docs/gen/module
index d726845..77336cf 100755
--- a/docs/gen/module
+++ b/docs/gen/module
@@ -1,7 +1,7 @@
 #!/usr/bin/env moon
-import Scope from require 'alv'
-import render, layout from require 'docs.gen.layout'
-import section, h2, h3, ul, li, code from require 'docs.gen.dom'
+import Constant from require 'alv'
+import render, layout, subnav from require 'docs.gen.layout'
+import h2, h3, ul, li, code from require 'docs.gen.dom'
 import opairs from require 'alv.util'
 
 export OUT, require
@@ -26,11 +26,13 @@ spit = (file, str) ->
 { OUT, module, name } = arg
 
 name or= module
-module = Scope.from_table require module
+const = Constant.wrap require module
+module = const\unwrap!
 
 spit OUT, layout
-  title: "#{name} reference"
-  body: section {
+  title: "#{name} module reference"
+  body: table.concat {
+    subnav [a for a in *arg[4,]]
     h2 (code name), ' module reference'
     h3 'index'
     ul for key, node in opairs module.values
@@ -38,4 +40,4 @@ spit OUT, layout
     h3 'details'
     ul for key, node in opairs module.values
       li render key, node.result
-  }
+  }, ''
diff --git a/docs/guide/installation.md b/docs/guide/01_installation.md
index 5a192fa..5a192fa 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/01_installation.md
diff --git a/docs/guide/hello-world.md b/docs/guide/02_hello-world.md
index 7f1517d..7f1517d 100644
--- a/docs/guide/hello-world.md
+++ b/docs/guide/02_hello-world.md
diff --git a/docs/guide/working-with-the-copilot.md b/docs/guide/03_working-with-the-copilot.md
index f40d82d..f40d82d 100644
--- a/docs/guide/working-with-the-copilot.md
+++ b/docs/guide/03_working-with-the-copilot.md
diff --git a/docs/guide/syntax.md b/docs/guide/04_syntax.md
index 93f1c61..93f1c61 100644
--- a/docs/guide/syntax.md
+++ b/docs/guide/04_syntax.md
diff --git a/docs/guide/basic-types.md b/docs/guide/05_basic-types.md
index c22929c..c22929c 100644
--- a/docs/guide/basic-types.md
+++ b/docs/guide/05_basic-types.md
diff --git a/docs/guide/importing-operators.md b/docs/guide/06_importing-operators.md
index 4321e7a..4321e7a 100644
--- a/docs/guide/importing-operators.md
+++ b/docs/guide/06_importing-operators.md
diff --git a/docs/guide/defining-symbols.md b/docs/guide/07_defining-symbols.md
index 5fb6d3f..5fb6d3f 100644
--- a/docs/guide/defining-symbols.md
+++ b/docs/guide/07_defining-symbols.md
diff --git a/docs/guide/making-sound.md b/docs/guide/08_making-sound.md
index 1987dac..1987dac 100644
--- a/docs/guide/making-sound.md
+++ b/docs/guide/08_making-sound.md
diff --git a/docs/guide/getting-started-guide.md b/docs/guide/index.md
index 9ca2f63..6933717 100644
--- a/docs/guide/getting-started-guide.md
+++ b/docs/guide/index.md
@@ -7,19 +7,21 @@ tools, `alive` takes the role of a 'conductor', telling the other tools what to
 play when by sending commands to them using a variety of protocols, such as OSC
 and MIDI.
 
+This guide will get you up and running with `alv` and [Pilot][pilot], explaining
+most of the basics along the way. For more complete documentation on the `alv` 
+language and features like functions, loops, etc. take a look at the
+[language reference](../reference/index.html).
+
 ## contents
 
-1.  [installation](installation.html)
-2.  [hello world](hello-world.html)
-3.  [working with the copilot](working-with-the-copilot.html)
-4.  [syntax](syntax.html)
-5.  [basic types](basic-types.html)
-6.  [importing operators](importing-operators.html)
-7.  [defining symbols](symbols.html)
-8.  [scopes](scopes.html)
-9.  [functions](functions.html)
-10. [evaltime and runtime](evaltime-and-runtime.html)
-11. [making sound](making-sound.html)
+1. [installation](01_installation.html)
+2. [hello world](02_hello-world.html)
+3. [working with the copilot](03_working-with-the-copilot.html)
+4. [syntax](04_syntax.html)
+5. [basic types](05_basic-types.html)
+6. [importing operators](06_importing-operators.html)
+7. [defining symbols](07_symbols.html)
+8. [making sound](08_making-sound.html)
 
 [supercollider]: https://supercollider.github.io/
 [pilot]:         https://github.com/hundredrabbits/Pilot
diff --git a/docs/index.md b/docs/index.md
index cd79c99..08c7573 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,11 +20,11 @@ it to).
 [on github][:*repo*:], and is licensed under [GPLv3][license].
 
 If you want to learn more or try out `alv` yourself, the
-[getting started][guide] page is a good place to start. On the other hand, if
+[getting started guide][guide] is a good place to start. On the other hand, if
 you are a curious about the motivations and concepts behind `alv`, you can find
 more in-depth information on these topics in the
 ['persistent expressions' article][rationale].
 
-[guide]: guide/getting-started-guide.html
+[guide]: guide/index.html
 [rationale]: https://s-ol.nu/alivecoding
 [license]: https://github.com/s-ol/alive/blob/master/LICENSE
diff --git a/docs/guide/evaltime-and-runtime.md b/docs/reference/02_evaltime-and-runtime.md
index e718cf3..e718cf3 100644
--- a/docs/guide/evaltime-and-runtime.md
+++ b/docs/reference/02_evaltime-and-runtime.md
diff --git a/docs/guide/scopes.md b/docs/reference/03-1_symbol-resolution.md
index 87568ef..87568ef 100644
--- a/docs/guide/scopes.md
+++ b/docs/reference/03-1_symbol-resolution.md
diff --git a/docs/guide/functions.md b/docs/reference/03-3_functions.md
index 917b8d4..917b8d4 100644
--- a/docs/guide/functions.md
+++ b/docs/reference/03-3_functions.md
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 0000000..cfa8fdc
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,26 @@
+__This section is currently under construction.__
+
+This reference manual documents the `alv` langauge and its standard facilities
+in detail. If you are new to alive, the [getting started guide][guide] is the
+recommended place to start. If you are looking for information on adding your
+own module or contributing to alive, check out the
+[developer documentation](../internals/index.html).
+
+[guide]: (../guide/index.html)
+
+## contents
+
+1. syntax
+2. [evaltime and runtime](02_evaltime-and-runtime.html)
+3. evaltime
+   1. [symbol resolution](03-1_symbol-resolution.html)
+   2. if and switch
+   3. [functions](03-3_functions.html)
+   4. dynamic symbols
+   5. loops
+   6. modules and loading
+4. runtime
+   1. result kinds
+   2. pure operators
+5. [builtin listing](builtins.html)
+6. included modules
diff --git a/docs/style.css b/docs/style.css
index 51fddef..e3238e9 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -62,9 +62,10 @@ a {
 
 ul, ol {
   margin: 0.5em 0;
-  padding-left: 0.6em;
+  padding-left: 1em;
 }
 ul, .ldoc ol { list-style: '- '; }
+li > ul, li > ol { margin: 0; }
 
 header {
   position: fixed;