Added official site

.gitignore

@@ -5,3 +5,5 @@ pom.xml
 *jar
 lib
 classes
+out
+webgen.cache

site/README

@@ -0,0 +1,10 @@
+description:
+  This skeleton of a webgen website provides a set of default files for every
+  created webgen website.
+
+  When using the standard settings, the sources are in the directory `src` and
+  the generated output goes into `out`. Extensions can be placed under `ext`.
+
+  For configuration purposes, use the config.yaml file.
+---
+note: This file can be deleted!

site/Rakefile

@@ -0,0 +1,69 @@
+# -*- ruby -*-
+#
+# This is a sample Rakefile to which you can add tasks to manage your website. For example, users
+# may use this file for specifying an upload task for their website (copying the output to a server
+# via rsync, ftp, scp, ...).
+#
+# It also provides some tasks out of the box, for example, rendering the website, clobbering the
+# generated files, an auto render task,...
+#
+
+require 'webgen/webgentask'
+require 'webgen/website'
+
+task :default => :webgen
+
+webgen_config = lambda do |config|
+  # you can set configuration options here
+end
+
+Webgen::WebgenTask.new do |website|
+  website.clobber_outdir = true
+  website.config_block = webgen_config
+end
+
+desc "Show outdated translations"
+task :outdated do
+  puts "Listing outdated translations"
+  puts
+  puts "(Note: Information is taken from the last webgen run. To get the"
+  puts "       useful information, run webgen once before this task!)"
+  puts
+
+  website = Webgen::Website.new(Dir.pwd, Webgen::Logger.new($stdout), &webgen_config)
+  website.execute_in_env do
+    website.init
+    website.tree.node_access[:acn].each do |acn, versions|
+      main = versions.find {|v| v.lang == website.config['website.lang']}
+      next unless main
+      outdated = versions.select do |v|
+         main != v && main['modified_at'] > v['modified_at']
+      end.map {|v| v.lang}.join(', ')
+      puts "ACN #{acn}: #{outdated}" if outdated.length > 0
+    end
+  end
+end
+
+desc "Render the website automatically on changes"
+task :auto_webgen do
+  puts 'Starting auto-render mode'
+  time = Time.now
+  abort = false
+  old_paths = []
+  Signal.trap('INT') {abort = true}
+
+  while !abort
+    # you may need to adjust the glob so that all your sources are included
+    paths = Dir['src/**/*'].sort
+    if old_paths != paths || paths.any? {|p| File.mtime(p) > time}
+      begin
+        Rake::Task['webgen'].execute({})
+      rescue Webgen::Error => e
+        puts e.message
+      end
+    end
+    time = Time.now
+    old_paths = paths
+    sleep 2
+  end
+end

site/config.yaml

@@ -0,0 +1,35 @@
+#####
+# This is the YAML configuration file for webgen used to set configuration options.
+#
+# The general syntax is:
+#
+#   configuration.option.name: value
+#
+# For example, to set a different default language, you would do:
+#
+#   website.lang: de
+#
+# Have a look at the documentation of the individual configuration options to see the allowed format
+# of the values. Since this is a YAML file, you can easily set configuration options as strings,
+# integers, dates, arrays, hashes and more.
+#
+# The available configuration options can be found on the homepage in the Configuration Option
+# Reference at
+#
+#     http://webgen.rubyforge.org/documentation/reference_configuration.html
+#
+# Some common use cases are shown below.
+#####
+
+## The default processing pipeline for page files. If you use a different markup language you need to
+## change 'markdown' to the short name of the content processor for the markup language.
+default_processing_pipeline:
+  Page: erb,tags,markdown,blocks,fragments
+
+## Setting the default language. The argument must be an ISO-639-1/2 language code.
+# website.lang: de
+
+## Adding some extensions to the copy source handler.
+# patterns:
+#   Copy:
+#     add: [**/*.pdf, **/*.djvu]

site/ext/init.rb

@@ -0,0 +1,10 @@
+# = webgen extensions directory
+#
+# All init.rb files anywhere under this directory get automatically loaded on a webgen run. This
+# allows you to add your own extensions to webgen or to modify webgen's core!
+#
+# If you don't need this feature you can savely delete this file and the directory in which it is!
+#
+# The +config+ variable below can be used to access the Webgen::Configuration object for the current
+# website.
+config = Webgen::WebsiteAccess.website.config

site/src/browserfix.css

@@ -0,0 +1,7 @@
+/**************** IE fixes ****************/
+
+html
+{overflow:hidden;}
+
+body
+{height:100%; width:100%; overflow:auto;}

site/src/default.css

@@ -0,0 +1,16 @@
+html,body{margin:0;padding:0;height:100%;}
+body{background:#F5F5DC;font-family:Georgia, Times, serifs;}
+a:link{color:#B88A00;text-decoration:none;}
+a:visited{color:#6B1B00;font-weight:900;}
+#floater{position:relative;float:left;height:50%;margin-bottom:-300px;width:1px;}
+#centered{position:relative;clear:left;height:600px;width:80%;max-width:800px;min-width:400px;margin:0 auto;}
+#bottom{position:absolute;bottom:0;right:0;}
+#nav{position:absolute;left:0;top:0;bottom:0;right:70%;padding:20px;margin:10px;}
+#content{position:absolute;left:30%;right:0;top:0;bottom:0;overflow:auto;height:340px;padding:20px;margin:10px;}
+.mainbookpage{width:95%;line-height:110%;font-size:11px;color:#333;background:#F5F5DC;}
+p.lawbook{text-indent:25px;text-align:justify;padding-left:10px;padding-right:9px;}
+.showme{border:1px solid #F5F5DC;}
+.leftcol{float:left;width:47%;background:#F5F5DC;padding-top:10px;padding-right:0;padding-bottom:10px;padding-left:10px;}
+.rightcol{float:right;width:47%;background:#F5F5DC;padding-top:10px;padding-right:10px;padding-bottom:10px;padding-left:0;}
+.rightmiddle{float:right;width:50%;font-size:12px;text-align:right;padding-top:10px;padding-right:0;padding-bottom:10px;padding-left:5px;}
+.leftmiddle{float:left;width:50%;font-size:12px;text-align:left;padding-top:10px;padding-right:5px;padding-bottom:10px;padding-left:0;}

site/src/default.template

@@ -0,0 +1,114 @@
+--- pipeline:erb,tags,blocks,head
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Marginalia Home</title>
+    <meta name="description" content="Marginalia - ultra-lightweight literate programming for Clojure"/>
+    <meta name="keywords" content="contracts programming, clojure, eiffel"/>
+    <meta name="author" content="Fogus"/>
+    <meta name="generator" content="webgen - http://webgen.rubyforge.com/"/>
+    <meta name="robots" content="index,follow,archive"/>
+
+    <link rel="icon" href="http://blog.fogus.me/images/labyrinth.ico" type="image/x-icon"/>
+    <link href="{relocatable: default.css}" rel="stylesheet" type="text/css"/>
+  </head>
+
+  <body>
+    <div id="floater"></div>
+    <div id="centered">
+      <!-- **************************************************************
+           The class showme allows us to turn on the borders
+           in this page. To turn off the borders change the font color 
+           of SHOWME to the same color as the background.
+           Using the SHOWME we can see where the boxes are positioned.
+           Everything here is a box. When we can see the box with the borders colobeige
+           we can identify any area that spills. 
+           And, it will likely spill. The code is size sensitive. I tried more percentages
+           and a more fluid layout  but some of the code requibeige specifying exact sizes 
+           to create a good example. 
+           The DOCTYPE impacts the page in IE and Firefox. 
+           10px font size in IE is readable. 
+           10px font size in Firefox is not readable (use ctrl + to enlarge font size) 
+           THINGS YOU MIGHT WANT TO CHANGE
+           1. Change the height="257"  on the spacer gif for the inside bold text.
+           2. Change the height="498"  on the spacer gif for the outside frame box
+           3. Change the color beige   to any color
+           4. Change the width:430px   to change the width of the book page
+           5. Change the font-size:8px  to any font size.
+           6. Change the font-size:10px to any font size.
+           7. Change the text-indent:25px to the amount you want to indent paragraphs.
+           8. Change the border:1px solid red to any color so that you can see the boxes. 
+           **************************************************************-->  
+      <!-- **************************************************************
+           DIV FOR TOP 
+           **************************************************************-->  
+      <DIV class="mainbookpage showme"> 
+
+        <!-- **************************************************************
+             DIV 1     FLOAT TO THE RIGHT 
+             **************************************************************-->  
+
+        <div class="rightcol showme">
+          <img src="images/spacer.gif" width="1" height="559" align="right" border="0" style="border:1px solid beige;"/>
+
+          <p class="lawbook">
+            <webgen:block name="top_right"/>      
+          </p>
+
+          <div class="leftmiddle showme"><img src="images/spacer.gif" width="1" height="257" align="right" border="0" style="border:1px solid beige;"/>
+            <p class="lawbook">
+              <webgen:block name="center_right"/>
+            </p>
+          </div>
+
+          <p class="lawbook">  
+            <webgen:block name="bottom_right"/> 
+          </p>
+        </div> 
+
+
+        <!-- **************************************************************
+             DIV 2: FLOAT TO THE LEFT      
+             **************************************************************-->  
+        <div class="leftcol showme">
+          <img src="images/spacer.gif" width="1" height="559" align="left" border="0" style="border:1px solid beige;"/>
+          <p class="lawbook showme">
+            <webgen:block name="top_left"/>
+          </p> 
+
+          <!-- notice the spacer.gif cheat here -->
+          <div class="rightmiddle showme"><img src="images/spacer.gif" width="1" height="257" align="right" border="0" style="border:1px solid beige;"/>
+            <p class="lawbook"><webgen:block name="content"/></p>
+          </div>
+
+          <p class="lawbook">
+            <webgen:block name="bottom_left"/>
+          </p> 
+        </div> 
+
+
+        <span style="color:beige;">You will not see this line but it is needed. Take it out to see the background color beige 
+          disappear from the center. Surely there is a better way. Thinkity, thinkity</span> 
+      </DIV>
+    </div>
+
+    <div id="bottom">
+      <p>
+	Copyright &copy; 2011 Fogus based on a design by Mandarin Designs (<i>RIP</i>).
+      </p>
+    </div>
+  </div>
+
+  <script type="text/javascript"> 
+    var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+    document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+  </script> 
+  <script type="text/javascript"> 
+    try {
+    var pageTracker = _gat._getTracker("UA-921112-2");
+    pageTracker._trackPageview();
+    } catch(err) {}
+  </script> 
+</body>
+</html>

site/src/index.page

@@ -0,0 +1,82 @@
+---
+title: Marginalia
+routed_title: The Marginalia Manifesto
+---
+
+[user guide](https://github.com/fogus/marginalia/wiki)
+
+[example output](uberdoc.html)
+
+[source code](https://github.com/fogus/marginalia)
+
+[bug reports](https://github.com/fogus/marginalia/issues)
+
+#### Features
+
+* HTML generation from Clojure source
+* Markdown support within comments and docstrings
+* Latex formatting support (via [MathJax](http://www.mathjax.org/))
+* Leiningen and Cake support
+
+--- name:center_right
+
+**the one true way**
+
+1. Start by running Marginalia against your code
+2. Cringe at the sad state of your code commentary
+3. Add docstrings and code comments as appropriate
+4. Generate the documentation again
+5. Read the resulting documentation
+6. Make changes to code and documentation so that the "dialog" flows sensibly
+7. Repeat from step #4 until complete
+
+
+--- name:top_right
+
+<br/>
+<br/>
+<br/>
+
+### A new way to think about programs
+
+What if your code and its documentation were one and the same?
+
+Much of the philosophy guiding literate programming is the realization of the answer to this question.  However, if literate programming stands as a comprehensive programming methodology at one of end of the spectrum and no documentation stands as its antithesis, then Marginalia falls somewhere between.  That is, you should always aim for comprehensive documentation, but the shortest path to a useful subset is the commented source code itself.
+
+--- name:bottom_right
+
+### The art of Marginalia
+
+If you're fervently writing code that is heavily documented, then using Marginalia for your Clojure projects is as simple as running it on your codebase.  However, if you're unaccustomed to documenting your source, then the guidelines herein will help you make the most out of Marginalia for true-power documentation.
+
+Following the guidelines will work to make your code not only easier to follow -- it will make it better.  The very process of using Marginalia will help to crystalize your understanding of problem and its solution(s).  
+
+The quality of the prose in your documentation will often reflect the quality of the code itself thus highlighting problem areas.  The elimination of problem areas will solidify your code and its accompanying prose.  Marginalia provides a virtuous circle spiraling inward toward maximal code quality.
+
+--- name:top_left
+
+# Marginalia
+
+([example output](uberdoc.html))
+
+In late 2010 I was motivated by posts by [Tom Preston-Werner][rdd], [Reginald Braithwaite][reg], and [Luigi Montanez][ddd] to create a Clojure clone of the excellent [Docco](http://jashkenas.github.com/docco/) documentation generator written in [CoffeeScript](http://jashkenas.github.com/coffee-script/).  The byproduct of this motivation was [Marginalia](https://github.com/fogus/marginalia).  The goal of Marginalia was to create a full-blown [literate programming][literate] system with Docco-esque functionality as a way-station along the way.
+
+[reg]: https://github.com/raganwald/homoiconic/blob/master/2010/11/docco.md
+
+[literate]: http://www.literateprogramming.com/
+
+I have a very strong opinion regarding the importance of clear and complete documentation.  My reaction to poorly documented code, products, and services is visceral to the point that I often refuse to release even the most humble library without code comments, examples, tests, invariant definitions, a logo, and an "official website".  
+
+[ddd]: http://luigimontanez.com/2010/reading-code-is-good-writing-documentation-is-better/
+
+[rdd]: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
+
+--- name:bottom_left
+
+However, time is not always on my side for personal projects, so I am constantly looking for ways to minimize the amount of work required to generate well-documented software without sacrificing quality.  Marginalia is a step in that direction.  However, I piddled around with a comment parser and created the code that builds a tree of code-lines associated with comment lines.  Having scratched that particular itch I then took a detour into researching literate programming proper, leaving behind a half-baked mess.
+
+### Enter Zachary Kim
+
+You may already know [Zachary Kim](http://zacharykim.com/) as the creator of the excellent [ClojureDocs](http://clojuredocs.org/) website; an invaluable resource for finding Clojure API examples.  Zachary resurrected my original source for Marginalia and single-handedly molded it into a tool worth using.  Marginalia would be nothing without his vision and hard-work.  I would also like to thank [Justin Balthrop](http://ninjudd.com/) and [Brenton Ashworth](http://formpluslogic.blogspot.com/) for their support and code contributions.
+
+*If you find Marginalia useful (or even just cool), then please do visit [ClojureDocs](http://clojuredocs.org/) and donate some of your time to enhancing its existing examples and/or fill in the holes as you find them.*