Added some documentation to the html namespace.

example-output/marg.html

@@ -2297,7 +2297,14 @@ <h2>Plus a few other goodies.</h2>
 </td><td class="codes"><pre class="brush: clojure">
 (defn replace-special-chars
   [s]
-  (str/replace s #&quot;-&amp;gt;&quot; &quot;&amp;rarr;&quot;))
+  (str/replace s #&quot;-&amp;gt;&quot; &quot;&amp;rarr;&quot;))</pre></td></tr><tr><td class="docs"><p>As a result of docifying then grouping, you'll end up with a seq like this one:</p>
+
+<p>[{:docs [{:docs-text &quot;Some doc text&quot;}]
+:codes [{code-text &quot;(def something \&quot;hi\&quot;)&quot;}]}]</p>
+
+<p><code>docs-to-html</code> and <code>codes-to-html</code> convert their respective entries into html,
+and <code>group-to-html</code> calls them on each seq item to do so.</p>
+</td><td class="codes"><pre class="brush: clojure">
 </pre></td></tr><tr><td class="docs"><p>Converts a docs section to html by threading each doc line through the forms
 outlined above.</p>
 
@@ -2357,9 +2364,18 @@ <h2>Plus a few other goodies.</h2>
 (defn inline-css [resource]
   (let [src (slurp-resource resource)]
     (html [:style {:type &quot;text/css&quot;}
-           (slurp-resource resource)])))</pre></td></tr><tr><td class="docs">
+           (slurp-resource resource)])))</pre></td></tr><tr><td class="docs"><p>Syntax highlighting is done a bit differently than docco.  Instead of embedding
+the higlighting metadata on the parse / html gen phase, we use <a href="http://alexgorbatchev.com/SyntaxHighlighter/">SyntaxHighlighter</a>
+to do it in javascript.</p>
+</td><td class="codes"><pre class="brush: clojure"></pre></td></tr><tr><td class="docs"><p>This function's the one that ties the whole html namespace together, and probably
+the only var you'll touch on.</p>
+
+<p>Notice that we're inlining the css &amp; javascript for <a href="http://alexgorbatchev.com/SyntaxHighlighter/">SyntaxHighlighter</a> (<code>inline-js</code>
+&amp; <code>inline-css</code>) to be able to package the output as a single file.  It goes without
+saying that all this is WIP and will prabably change in the future.</p>
 </td><td class="codes"><pre class="brush: clojure">
-(defn output-html [project-name groups]
+(defn output-html
+  [project-name groups]
   (html
    (doctype :html5)
    [:html
@@ -2368,7 +2384,8 @@ <h2>Plus a few other goodies.</h2>
      (inline-js &quot;shCore.js&quot;)
      (inline-js &quot;shBrushClojure.js&quot;)
      (inline-css &quot;shCore.css&quot;)
-     (inline-css &quot;shThemeEclipse.css&quot;)
+     (inline-css &quot;shThemeEclipse.css&quot;)</pre></td></tr><tr><td class="docs"><p>quick and dirty dsl for inline css rules, similar to hiccup.</p>
+</td><td class="codes"><pre class="brush: clojure">
      (css
       [:body {:margin 0
               :padding 0

src/marginalia/html.clj

@@ -35,6 +35,14 @@
   [s]
   (str/replace s #"->" "→"))
 
+;; As a result of docifying then grouping, you'll end up with a seq like this one:
+;;
+;;     [{:docs [{:docs-text "Some doc text"}]
+;;      :codes [{code-text "(def something \"hi\")"}]}]
+;;
+;; `docs-to-html` and `codes-to-html` convert their respective entries into html,
+;; and `group-to-html` calls them on each seq item to do so.
+
 
 (defn docs-to-html
   "Converts a docs section to html by threading each doc line through the forms
@@ -98,7 +106,18 @@
     (html [:style {:type "text/css"}
            (slurp-resource resource)])))
 
-(defn output-html [project-name groups]
+;; Syntax highlighting is done a bit differently than docco.  Instead of embedding
+;; the higlighting metadata on the parse / html gen phase, we use [SyntaxHighlighter](http://alexgorbatchev.com/SyntaxHighlighter/)
+;; to do it in javascript.
+
+(defn output-html
+  "This function's the one that ties the whole html namespace together, and probably
+   the only var you'll touch on.
+
+   Notice that we're inlining the css & javascript for [SyntaxHighlighter](http://alexgorbatchev.com/SyntaxHighlighter/) (`inline-js`
+   & `inline-css`) to be able to package the output as a single file.  It goes without
+   saying that all this is WIP and will prabably change in the future."
+  [project-name groups]
   (html
    (doctype :html5)
    [:html
@@ -108,6 +127,8 @@
      (inline-js "shBrushClojure.js")
      (inline-css "shCore.css")
      (inline-css "shThemeEclipse.css")
+
+     ;; quick and dirty dsl for inline css rules, similar to hiccup.
      (css
       [:body {:margin 0
               :padding 0