Merge branch 'gh-pages' of github.com:vrld/hump into gh-pages

makedoc.lua

@@ -0,0 +1,256 @@
+function markup(str)
+	local function trim(tbl)
+		for i=#tbl,1,-1 do
+			if tbl[i] == ' ' then
+				tbl[i] = nil
+			else
+				return tbl
+			end
+		end
+	end
+
+	local parse, block, block2, element, code, url, title, def, dt, dd
+	function parse(out, next)
+		local c = next()
+		if not c then return out end
+		if c == ' ' or c == '\t' then return parse(out, next) end
+		out[#out+1] = '<p>'
+		if c == '[' then return element(out, next) end
+		out[#out+1] = c
+		return block(out, next)
+	end
+
+	function block(out, next)
+		local c = next()
+		if not c     then out[#out+1] = '</p>' return out end
+		if c == '['  then                      return element(out, next) end
+		if c == '\n' then                      return block2(out, next) end
+		out[#out+1] = c
+		return block(out, next)
+	end
+
+	function block2(out, next)
+		local c = next()
+		if not c     then out[#out+1] = '</p>' return out end
+		if c == '['  then                      return element(out, next) end
+		if c == '\n' then out[#out+1] = '</p>' return parse(out, next) end
+
+		if c ~= ' ' and c ~= '\t' then out[#out+1] = c
+		elseif out[#out] ~= ' '   then out[#out+1] = ' ' end
+		return block(out, next)
+	end
+
+	function element(out, next)
+		local c = assert(next(), 'markup error')
+		if c == '^' then out[#out+1] = '<a href="' return url(out, next) end
+		if c == '|' then out[#out+1] = '<dl>'      return def(out, next) end
+		if c == '%' then out[#out+1] = '<pre><code class="lua">' return code(out, next) end
+		out[#out+1] = '['..c
+		return block(out, next)
+	end
+
+	function url(out, next)
+		local c = assert(next(), 'markup error')
+		assert(c ~= ']', 'incomplete link definition')
+		if c == ' ' then out[#out+1] = '">' return title(out, next) end
+		out[#out+1] = c
+		return url(out, next)
+	end
+
+	function title(out, next)
+		local c = assert(next(), 'markup error')
+		if c == ']' then out[#out+1] = '</a>' return block(out, next) end
+		out[#out+1] = c
+		return title(out, next)
+	end
+
+	function def(out, next)
+		local c = assert(next(), 'markup error')
+		if c == ' ' or c == '\t' or c == '\n' then return def(out, next) end
+		if c == ']' then out[#out+1] = '</dl>' return block(out, next) end
+		out[#out+1] = '<dt>' .. c
+		return dt(out, next)
+	end
+
+	function dt(out, next)
+		local c = assert(next(), 'markup error')
+		if c == ':' then trim(out) out[#out+1] = '</dt><dd>' return dd(out, next) end
+		out[#out+1] = c
+		return dt(out, next)
+	end
+
+	function dd(out, next)
+		local c = assert(next(), 'markup error')
+		if c == '\n' then out[#out+1] = '</dd>' return def(out, next) end
+		out[#out+1] = c
+		return dd(out, next)
+	end
+
+	function code(out, next)
+		local c = assert(next(), 'markup error')
+		if c == ']' then out[#out+1] = '</code></pre>' return block(out, next) end
+		out[#out+1] = c
+		return code(out, next)
+	end
+
+	local function spans(m)
+		local cmd,rest = m:match('^{(.)(.+)}$')
+		if cmd == '#' then return '<code class="lua">'..rest..'</code>' end
+		if cmd == '*' then return '<em>'..rest..'</em>' end
+		if cmd == '!' then return '<span class="warning">'..rest..'</span>' end
+		return m
+	end
+
+	return table.concat(parse({}, str:gmatch('.'))):gsub('%b{}', spans):gsub('%b{}', spans)
+end
+
+
+-- PREPARE DOCUMENTATION MARKUP
+local DOC = { short = {}, long = {} }
+
+function Module(M)
+	for _,field in ipairs{'name', 'title', 'short', 'long'} do
+		assert(M[field], "Module: Required field `"..field.."' is missing")
+	end
+
+	DOC.short[#DOC.short+1] = ('<dt><a href="#%s">%s</a></dt><dd>%s</dd>'):format(M.title, M.name, M.short)
+
+	local long = {}
+	local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
+	F('<a name="%s" id="%s"></a>', M.title, M.title)
+	F('<div class="outer-block">') -- outer block>
+		F('<h3>%s<a class="top" href="#top">^ top</a></h3>', M.name)
+		F('<div class="preamble">') -- preamble>
+			F('<pre><code class="lua">%s = require "%s"</code></pre>', M.title:gsub("^(%w+)%W.+", "%1"), M.name)
+			F(markup(M.long))
+		F('</div>') -- <preamble
+		F('<div class="overview"><h4>Module overview</h4><dl>') -- overview>
+			for _,item in ipairs(M) do if item.short then F(item.short) end end
+		F('</dl></div>') -- <overview
+		for _,item in ipairs(M) do F(item.long) end
+	F('</div>') -- <outer block
+
+	DOC.long[#DOC.long+1] = table.concat(long):gsub('{{MODULE}}', M.title)
+end
+
+
+function Section(M)
+	for _,field in ipairs{'name', 'title', 'content'} do
+		assert(M[field], "Section: Required field `"..field.."' is missing")
+	end
+
+	local short = ('<dt><a href="#{{MODULE}}-%s">%s</a></dt><dd>%s</dd>'):format(M.name, M.name, M.title)
+
+	local long = {}
+	local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
+	F('<a name="{{MODULE}}-%s" id="{{MODULE}}-%s"></a>', M.name, M.name)
+	F('<div class="section-block"><h4>%s<a class="top" href="#{{MODULE}}">^ top</a></h4>', M.title) -- section block>
+	F(markup(M.content))
+	if M.example then
+		if type(M.example) ~= 'table' then M.example = {M.example} end
+		F('<div class="example">Example:')
+		for i=1,#M.example do
+			F('<pre><code class="lua">')
+			F(M.example[i])
+			F('</code></pre>')
+		end
+		F('</div>')
+	end
+	F('</div>') -- <section block
+
+	return {short = short, long = table.concat(long)}
+end
+
+function Function(M)
+	for _,field in ipairs{'name', 'short', 'long', 'params', 'returns', 'example'} do
+		assert(M[field], "Function: Required field `"..field.."' is missing")
+	end
+
+	if type(M.name)  ~= 'table' then M.name = {M.name} end
+	if type(M.short) ~= 'table' then M.short = {M.short} end
+	assert(#M.name >= #M.short)
+
+	local short = {}
+	for i=1,#M.short do
+		short[i] = ('<dt><a href="#{{MODULE}}-%s">%s()</a></dt><dd>%s</dd>'):format(M.name[i], M.name[i], M.short[i])
+	end
+	short = table.concat(short)
+
+	local args
+	if #M.params == 0 then
+		args = '()'
+	elseif M.params.table_argument then
+		args = {}
+		for i,p in ipairs(M.params) do
+			if p.name then
+				args[i] = p.name..' = '.. p[2]
+			else
+				args[i] = p[2]
+			end
+		end
+		args = '{'..table.concat(args, ', ')..'}'
+	else
+		args = {}
+		for i,p in ipairs(M.params) do
+			args[i] = p[2]
+		end
+		args = '('..table.concat(args, ', ')..')'
+	end
+
+	local long = {}
+	local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
+
+	-- header(s)
+	for i=1,#M.name do F('<a name="{{MODULE}}-%s" id="{{MODULE}}-%s"></a>', M.name[i], M.name[i]) end
+	F('<div class="ref-block">')
+	for i=1,#M.name do
+		F('<h4>function <span class="name">%s</span><span class="arglist">%s</span><a class="top" href="#{{MODULE}}">^ top</a></h4>', M.name[i], args) -- section block>
+	end
+
+	-- description
+	F(markup(M.long))
+
+	-- parameters
+	F('<div class="arguments">Parameters:<dl>')
+	if #M.params == 0 then F('<dt>None</dt>') end
+	for _,p in ipairs(M.params) do
+		F('<dt>%s <code>%s</code>%s</dt><dd>%s</dd>', p[1], p[2], p.optional and ' (optional)' or '', markup(p[3]):sub(4,-5))
+	end
+	F('</dl></div>')
+
+	-- return values
+	F('<div class="returns">Returns:<dl>')
+	if #M.returns == 0 then F('<dt>Nothing</dt>') end
+	for _,r in ipairs(M.returns) do
+		F('<dt>%s</dt><dd>%s</dd>', r[1], markup(r[2]):sub(4,-5))
+	end
+	F('</dl></div>')
+
+	-- example(s)
+	if type(M.example) ~= 'table' then M.example = {M.example} end
+	F('<div class="example">Example:')
+	for i=1,#M.example do
+		F('<pre><code class="lua">')
+		F(M.example[i])
+		F('</code></pre>')
+	end
+	F('</div>')
+
+	-- sketch
+	if M.sketch then
+		F('<div class="example">Sketch:<img src="%s" width="%s" height="%s" /></div>', M.sketch[1], M.sketch.width, M.sketch.height)
+	end
+
+	F('</div>') -- <section block
+
+	return {short = short, long = table.concat(long)}
+end
+
+dofile(...) -- magic
+
+-- ASSEMBLE DOCUMENTATION MARKUP
+io.write([[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><title>hump - L&Ouml;VE Helper Utilities for More Productivity</title><link rel="stylesheet" type="text/css" href="style.css" /><link rel="stylesheet" type="text/css" href="highlight.css" /><script type="text/javascript" src="highlight.pack.js"></script><script type="text/javascript">window.onload = function() {var examples = document.getElementsByTagName("code");for (i = 0; i < examples.length; ++i) {if (examples[i].className == "lua")hljs.highlightBlock(examples[i], "    ");}};</script></head><body><a name="top" id="top"></a><div id="header"><h1><a href="http://github.com/vrld/hump">hump</a><span class="small"> Helper Utilities for More Productivity</span></h1><ul id="main-nav"><li><a href="#intro">Introduction</a></li><li><a href="#doc">Documentation</a></li><li><a href="#license">License</a></li><li><a href="#download">Download</a></li></ul><h2>&nbsp;</h2></div><a name="intro" id="intro"></a><div class="outer-block"><h3>Introduction<a class="top" href="#top">^ top</a></h3><div class="preamble"><p><em>Helper Utilities for a Multitude of Problems</em> is a set of lightweight helpers for the <strong>awesome</strong> <a href="http://love2d.org/">L&Ouml;VE</a> Engine.</p><p><em>hump</em> differs from other libraries in that every component is independent of the remaining ones (apart from camera.lua, which does depends on vector-light.lua). <em>hump</em>'s footprint is very small and thus should fit nicely into your projects.</p></div></div><a name="doc"></a><div class="outer-block"><h3>Documentation<a class="top" href="#top">^ top</a></h3><div class="preamble">]])
+io.write('<dl>'..table.concat(DOC.short):gsub('Ö', '&Ouml;')..'</dl>')
+io.write([[</div></div>]])
+io.write(''..table.concat(DOC.long):gsub('Ö', '&Ouml;'))
+io.write[[<a name="license" id="license"></a><div class="outer-block"><h3>License<a class="top" href="#top">^ top</a></h3><div class="preamble"><p>Yay, <em>free software</em>:</p><blockquote><p>Copyright (c) 2010 Matthias Richter</p><p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p><p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p><p>Except as contained in this notice, the name(s) of the above copyright holders shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.</p><p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p></blockquote></div></div><a name="download" id="download"></a><div class="outer-block"><h3>Download<a class="top" href="#top">^ top</a></h3><div class="preamble"><p>You can view and download the individual modules on github: <a href="http://github.com/vrld/hump">vrld/hump</a>. You may also download the whole packed sourcecode either in <a href="http://github.com/vrld/hump/zipball/master">zip</a> or <a href="http://github.com/vrld/hump/tarball/master">tar</a> formats.</p><p>You can clone the project with <a href="http://git-scm.com">Git</a> by running: <pre>git clone git://github.com/vrld/hump</pre> Once done, you can check for updates by running <pre>git pull</pre></p></div></div></body>]]

style.css

@@ -39,6 +39,16 @@ h2 {
 	border-radius: 10px; -moz-border-radius: 10px;
 }
 
+#main-nav {
+	margin: 0;
+	float: right;
+}
+
+#main-nav li {
+	display:inline;
+	margin-right: 1em;
+}
+
 #nav {
 	width: 800px;
 	margin: 1em auto;
@@ -68,21 +78,12 @@ h2 {
 	color: #101010;
 }
 
-.module {
+.outer-block {
 	width: 800px;
 	margin: 1em auto;
 	padding: 0 0 0 1em;
 }
 
-.definition, .constructor {
-	font-weight: bold;
-	color: #444;
-}
-
-.definition .name, .constructor .name {
-	color: #000;
-}
-
 .arglist {
 	color: #102040;
 }
@@ -98,7 +99,7 @@ h2 {
 	margin-left: 2em;
 }
 
-.overview, .preamble, .function, .class, .module > .name, .caveats {
+h3, .preamble, .text-block, .overview, .ref-block, .tut-block, .section-block {
 	border: 1px solid #aaa;
 	border-radius: 5px; -moz-border-radius: 5px;
 	padding: .2em .5em;
@@ -106,7 +107,7 @@ h2 {
 	margin: 1em .2em;
 }
 
-.module > .name {
+h3 {
 	color: #050A10;
 	font-size: 1.5em;
 	font-weight: bold;
@@ -117,12 +118,28 @@ h2 {
 	margin-top: -1em;
 }
 
-.overview {
+.text-block, .section-block {
 	margin-bottom: 2em;
 }
-.caveats h3, .overview h3 {
+
+h4 {
 	margin: 0;
 	color: #405070;
+	font-size: 1.2em;
+	font-weight: bold;
+}
+
+.ref-block h4 {
+	color: #444;
+	font-size: 1em;
+}
+
+.ref-block h4 .name {
+	color: #721;
+}
+
+.ref-block h4 .arglist {
+	color: #151;
 }
 
 dl {
@@ -134,7 +151,7 @@ dt, dt a {
 }
 dt code {
 	font-size: 12pt;
-	color: #102040;
+	color: #151;
 }
 dd {
 	font-weight: normal;
@@ -160,7 +177,7 @@ dd {
 code {
 	font-family: "Bitstream Vera Sans Mono", fixed;
 	font-weight: bold;
-	color: #105020;
+	color: #333;
 }
 pre {
 	border: 1px solid #aaa;
@@ -169,6 +186,7 @@ pre {
 	padding: .2em;
 	margin: 1em 2em;
 	font-weight: normal;
+	max-height: 450px; overflow: auto;
 }
 pre code {
 	font-size: 11pt;