Refactored some documentation; added lots of TODOs. It's not written …

…in stone yet, so please move things where you feel they should be.

Signed-off-by: why the lucky stiff <why@whytheluckystiff.net>

README

@@ -1,12 +1,13 @@
 == Camping, a Microframework
 
-Camping is a web framework which consistently stays at less than 4kb of code.
-You can probably view the complete source code on a single page.  But, you know,
-it's so small that, if you think about it, what can it really do?
+Camping is a web framework which consistently stays at less than 3kb of code.
+You can probably view the complete source code on a single page. But, you
+know, it's so small that, if you think about it, what can it really do?
 
-The idea here is to store a complete fledgling web application in a single file
-like many small CGIs.  But to organize it as a Model-View-Controller application
-like Rails does.  You can then easily move it to Rails once you've got it going.
+The idea here is to store a complete fledgling web application in a single
+file like many small CGIs. But to organize it as a Model-View-Controller
+application like Rails does. You can then easily move it to Rails once you've
+got it going.
 
 == A Camping Skeleton
 
@@ -46,74 +47,36 @@ A skeletal Camping blog could look like this:
       end
     end
   end
+
+== Installation
 
-Some things you might have noticed:
-
-* Camping::Models uses ActiveRecord to do its work.  We love ActiveRecord!
-* Camping::Controllers can be assigned URLs in the class definition.  Neat?
-* Camping::Views describes HTML using pure Ruby.  Markup as Ruby, which we
-  call Markaby.
-* You use Camping::goes to make a copy of the Camping framework under your
-  own module name (in this case: <tt>Blog</tt>.)
-
-<b>NOTE:</b> Camping auto-prefixes table names.  If your class is named
-<tt>Blog::Models::Post</tt>, your table will be called <b>blog_posts</b>.
-Since many Camping apps can be attached to a database at once, this helps
-prevent name clash.
-
-(If you want to see the full blog example, check out <tt>examples/blog/blog.rb</tt>
-for the complete code.)
-
-If you want to write larger applications with Camping, you are encouraged to
-split the application into distinct parts which can be mounted at URLs on your
-web server.  You might have a blog at /blog and a wiki at /wiki.  Each
-self-contained.  But you can certainly share layouts and models by storing them
-in plain Ruby scripts.
-
-Interested yet?  Okay, okay, one step at a time.
+Interested yet?  Luckily it's quite easy to install Camping:
 
-== Installation
+TODO: Requirements?
 
 * <tt>gem install camping</tt>
 
 Or for the bleeding edge:
 
-* <tt>gem install camping --source http://code.whytheluckystiff.net</tt>
-
-You are encourage to install Camping and SQLite3, since it is a small database
-which fits perfectly with our compact bylaws, works well with the examples.
+* <tt>gem install camping --source http://gems.judofyr.net</tt>
 
-* See http://code.whytheluckystiff.net/camping/wiki/BeAlertWhenOnSqlite3 for instructions.
+== Learning
 
-== Running Camping Apps
-
-The blog example above and most Camping applications look a lot like CGI scripts.
-If you run them from the commandline, you'll probably just see a pile of HTML.
-
-Camping comes with an tool for launching apps from the commandline:
-
-* Run: <tt>camping blog.rb</tt>
-* Visit http://localhost:3301/ to use the app.
-
-== How the Camping Tool Works
-
-If your application isn't working with the <tt>camping</tt> tool, keep in mind
-that the tool expects the following conventions to be used:
-
-1. You must have SQLite3 and SQLite3-ruby installed.  (Once again, please see
-   http://code.whytheluckystiff.net/camping/wiki/BeAlertWhenOnSqlite3 for instructions.)
-2. If your script is called <tt>test.rb</tt>, Camping expects your application to
-   be stored in a module called <tt>Test</tt>.  Case is not imporant, though.  The
-   module can be called <tt>TeSt</tt> or any other permutation.
-3. Your script's postamble (anything enclosed in <tt>if __FILE__ == $0</tt>) will be
-   ignored by the tool, since the tool will create an SQLite3 database at 
-   <tt>~/.camping.db</tt>.  Or, on Windows, <tt>$USER/Application Data/Camping.db</tt>.
-4. If your application's module has a <tt>create</tt> method, it will be executed before
-   the web server starts up.
-
-== The Rules of Thumb
-
-Once you've started writing your own Camping app, I'd highly recommend that you become familiar
-with the Camping Rules of Thumb which are listed on the wiki: 
-http://code.whytheluckystiff.net/camping/wiki/CampingRulesOfThumb
+* Start by reading the documentation in {the Camping module}[link:classes/Camping.html]
+  - it should get you started pretty quick.
+* {The wiki}[http://wiki.github.com/why/camping] is the place for all tiny,
+  useful tricks that we've collected over the years.  Don't be afraid to
+  share your own discoveries; the more, the better!
+* Still wondering?  Subscribe to {the mailing list}[http://rubyforge.org/mailman/listinfo/camping-list].
+  This is where it's all happening!  Don't worry, though, the volume is just
+  as micro as Camping itself.  
+
+== Authors
+
+Camping was originally started by{why the lucky stiff}[http://en.wikipedia.org/wiki/Why_the_lucky_stiff],
+but is now maintained by the _community_.  This simply means that if we like your
+patch, it will be applied.  Everything is managed through {the mailing list}[http://rubyforge.org/mailman/listinfo/camping-list],
+so just subscribe and you'll become a contributor too.  Remember: writing the
+code is just half the job, without some serious thinking from you we won't get
+any further.
 

Rakefile

@@ -5,12 +5,12 @@ require 'rake/rdoctask'
 require 'rake/testtask'
 require 'fileutils'
 begin
-  gem 'rdoc', '~> 2.2'
+  gem 'rdoc', '~> 2.2.0'
   require 'rdoc'
   $:.unshift 'extras'
 rescue Gem::LoadError
   puts "RDoc 2.2 required to build docs"
-  puts "Please run `gem install rdoc`"
+  puts "Please run `gem install rdoc --version 2.2`"
 end
 include FileUtils
 

lib/camping-unabridged.rb

@@ -12,6 +12,8 @@
 #
 # == Requirements
 #
+# TODO: Move into README. Also, they're not true dependecies...
+#
 # Camping requires at least Ruby 1.8.2.
 #
 # Camping depends on the following libraries.  If you install through RubyGems,
@@ -34,7 +36,11 @@ def meta_def(m,&b) #:nodoc:
   end
 end
 
-# == Camping 
+# == Camping
+# TODO: Tutorial: Camping.goes, MVC (link to Controllers, Models, Views where
+#       they're described in detail), Camping Server (for development), Rack
+#       (for production). the create-method. Service overload too, perhaps?
+#       Overriding r404, r500 and r501.
 #
 # The camping module contains three modules for separating your application:
 #
@@ -47,6 +53,7 @@ def meta_def(m,&b) #:nodoc:
 # * Camping::Helpers which can be used in controllers and views.
 #
 # == The Camping Server
+# TODO: Only for development.
 #
 # How do you run Camping apps?  Oh, uh... The Camping Server!
 #
@@ -84,13 +91,15 @@ def meta_def(m,&b) #:nodoc:
 #     end
 #   end 
 #
+# TODO: Wiki is down.
 # For more tips, see http://code.whytheluckystiff.net/camping/wiki/GiveUsTheCreateMethod.
 module Camping
   C = self
   S = IO.read(__FILE__) rescue nil
   P = "<h1>Cam\ping Problem!</h1><h2>%s</h2>"
   U = Rack::Utils
   Apps = []
+  # TODO: @input[:page] != @input['page']
   # An object-like Hash.
   # All Camping query string and cookie variables are loaded as this.
   # 
@@ -125,7 +134,8 @@ def method_missing(m,*a)
     end
     undef id, type
   end
-
+
+  # TODO: Fair enough. Maybe complete the ActionPack example?
   # Helpers contains methods available in your controllers and views.  You may add
   # methods of your own to this module, including many helper methods from Rails.
   # This is analogous to Rails' <tt>ApplicationHelper</tt> module.
@@ -251,6 +261,7 @@ def URL c='/',*a
   # Forgivable, considering that it's only really a handful of methods and accessors.
   #
   # == Treating controller methods like Response objects
+  # TODO: I don't think this belongs here. Either Controllers or Camping.
   #
   # Camping originally came with a barebones Response object, but it's often much more readable
   # to just use your controller as the response.
@@ -424,6 +435,7 @@ def initialize(env, m) #:nodoc:
       end
     end
 
+    # TODO: The wiki is down. Service overload should probably go in Camping.
     # All requests pass through this method before going to the controller.  Some magic
     # in Camping can be performed by overriding this method.
     #
@@ -435,7 +447,8 @@ def service(*a)
       self
     end
   end
-
+
+  # TODO: @input & @cookies at least.
   # Controllers is a module for placing classes which handle URLs.  This is done
   # by defining a route to each class using the Controllers::R method.
   #
@@ -588,7 +601,8 @@ def method_missing(m, c, *a)
       k.service(*a)
     end
   end
-
+  
+  # TODO: More examples.
   # Views is an empty module for storing methods which create HTML.  The HTML is described
   # using the Markaby language.
   #
@@ -597,7 +611,8 @@ def method_missing(m, c, *a)
   # If your Views module has a <tt>layout</tt> method defined, it will be called with a block
   # which will insert content from your view.
   module Views; include X, Helpers end
- 
+  
+  # TODO: Migrations
   # Models is an empty Ruby module for housing model classes derived
   # from ActiveRecord::Base.  As a shortcut, you may derive from Base
   # which is an alias for ActiveRecord::Base.

lib/camping/server.rb

@@ -2,6 +2,7 @@
 require 'rack'
 require 'camping/reloader'
 
+# TODO: I guess we should documentate this too...
 class Camping::Server
   attr_reader :reloader
   attr_accessor :conf

lib/camping/session.rb

@@ -1,4 +1,5 @@
 # == About camping/session.rb
+# TODO: Clean everything up. Lots of just plain wrong stuff in here.
 #
 # This file contains two modules which supply basic sessioning to your Camping app.
 # Again, we're dealing with a pretty little bit of code: approx. 60 lines.