initial revision

No tests yet, but the old "gossamer" and "rainbows" branches
seem to be basically working.

3 files changed, 194 insertions, 0 deletions

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 0000000..46679d6
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1,5 @@
+*.1
+*.5
+*.7
+*.gz
+*.html
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
new file mode 100644
index 0000000..e33c87f
--- /dev/null
+++ b/Documentation/GNUmakefile
@@ -0,0 +1,30 @@
+all::
+
+PANDOC = pandoc
+PANDOC_OPTS = -f markdown --email-obfuscation=none --sanitize-html
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+pandoc_html = $(pandoc) --toc -t html --no-wrap
+
+man1 := $(addsuffix .1,rainbows)
+html1 := $(addsuffix .html,$(man1))
+
+all:: html man
+
+html: $(html1)
+man: $(man1)
+
+install-html: html
+        mkdir -p ../doc/man1
+        install -m 644 $(html1) ../doc/man1
+
+install-man: man
+        mkdir -p ../man/man1
+        install -m 644 $(man1) ../man/man1
+
+%.1: %.1.txt
+        $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+%.1.html: %.1.txt
+        $(pandoc_html) < $< > $@+ && mv $@+ $@
+
+clean::
+        $(RM) $(man1) $(html1)
diff --git a/Documentation/rainbows.1.txt b/Documentation/rainbows.1.txt
new file mode 100644
index 0000000..6577203
--- /dev/null
+++ b/Documentation/rainbows.1.txt
@@ -0,0 +1,159 @@
+% UNICORN-RAINBOWS(1) Unicorn User Manual
+% The Unicorn Community <mongrel-unicorn@rubyforge.org>
+% September 15, 2009
+
+# NAME
+
+unicorn-rainbows - rackup-like command to launch Unicorn Rainbows
+
+# SYNOPSIS
+
+unicorn-rainbows [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
+
+# DESCRIPTION
+
+A rackup(1)-like command to launch Rack applications using Unicorn
+Rainbows.  It is expected to be started in your application root
+(APP_ROOT), but "Dir.chdir" may also be executed in the CONFIG_FILE or
+RACKUP_FILE.
+
+While Unicorn Rainbows takes a myriad of command-line options for
+compatibility with ruby(1) and rackup(1), it is recommended to stick
+to the few command-line options specified in the SYNOPSIS and use
+the CONFIG_FILE as much as possible.
+
+# RACKUP FILE
+
+This defaults to \"config.ru\" in APP_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+*Rack::Builder* DSL.
+
+Embedded command-line options are mostly parsed for compatibility
+with rackup(1) but strongly discouraged.
+
+# UNICORN OPTIONS
+-c, \--config-file CONFIG_FILE
+:   Path to the Unicorn-specific config file.  The config file is
+    implemented as a Ruby DSL, so Ruby code may executed (e.g.
+    "Dir.chdir", "Process::UID.change_privilege").  See the RDoc/ri
+    for the *Unicorn::Configurator* class for the full list of
+    directives available from the DSL.
+
+-D, \--daemonize
+:   Run daemonized in the background.  The process is detached from
+    the controlling terminal and stdin is redirected to "/dev/null".
+    Unlike many common UNIX daemons, we do not chdir to \"/\"
+    upon daemonization to allow more control over the startup/upgrade
+    process.
+    Unless specified in the CONFIG_FILE, stderr and stdout will
+    also be redirected to "/dev/null".
+
+-E, \--env RACK_ENV
+:   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+    for more details.
+
+-l, \--listen ADDRESS
+:   Listens on a given ADDRESS.  ADDRESS may be in the form of
+    HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+    and PATH is meant to be a path to a UNIX domain socket.
+    Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080)
+    For production deployments, specifying the "listen" directive in
+    CONFIG_FILE is recommended as it allows fine-tuning of socket
+    options.
+
+# RACKUP COMPATIBILITY OPTIONS
+-o, \--host HOST
+:   Listen on a TCP socket belonging to HOST, default is
+    "0.0.0.0" (all addresses).
+    If specified multiple times on the command-line, only the
+    last-specified value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-p, \--port PORT
+:   Listen on the specified TCP PORT, default is 8080.
+    If specified multiple times on the command-line, only the last-specified
+    value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-s, \--server SERVER
+:   No-op, this exists only for compatibility with rackup(1).
+
+# RUBY OPTIONS
+-e, \--eval LINE
+:   Evaluate a LINE of Ruby code.  This evaluation happens
+    immediately as the command-line is being parsed.
+
+-d, \--debug
+:   Turn on debug mode, the $DEBUG variable is set to true.
+
+-w, \--warn
+:   Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+-I, \--include PATH
+:   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+    The \':\' character may be used to delimit multiple directories.
+    This directive may be used more than once.  Modifications to
+    $LOAD_PATH take place immediately and in the order they were
+    specified on the command-line.
+
+-r, \--require LIBRARY
+:   require a specified LIBRARY before executing the application.  The
+    \"require\" statement will be executed immediately and in the order
+    they were specified on the command-line.
+
+# SIGNALS
+
+The following UNIX signals may be sent to the master process:
+
+* HUP - reload config file, app, and gracefully restart all workers
+* INT/TERM - quick shutdown, kills all workers immediately
+* QUIT - graceful shutdown, waits for workers to finish their
+  current request before finishing.
+* USR1 - reopen all logs owned by the master and all workers
+  See Unicorn::Util.reopen_logs for what is considered a log.
+* USR2 - reexecute the running binary.  A separate QUIT
+  should be sent to the original process once the child is verified to
+  be up and running.
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes.
+* TTIN - increment the number of worker processes by one
+* TTOU - decrement the number of worker processes by one
+
+See the [SIGNALS][4] document for full description of all signals
+used by Unicorn Rainbows.
+
+#  RACK ENVIRONMENT
+
+Accepted values of RACK_ENV and the middleware they automatically load
+(outside of RACKUP_FILE) are exactly as those in rackup(1):
+
+* development - loads Rack::CommonLogger, Rack::ShowExceptions, and
+                Rack::Lint middleware
+* deployment  - loads Rack::CommonLogger middleware
+* none        - loads no middleware at all, relying
+                entirely on RACKUP_FILE
+
+All unrecognized values for RACK_ENV are assumed to be
+"none".  Production deployments are strongly encouraged to use
+"deployment" or "none" for maximum performance.
+
+Note that the Rack::ContentLength and Rack::Chunked middlewares
+are never loaded by default.  If needed, they should be
+individually specified in the RACKUP_FILE, some frameworks do
+not require them.
+
+# SEE ALSO
+
+* unicorn(1)
+* *Rack::Builder* ri/RDoc
+* *Unicorn::Configurator* ri/RDoc
+* [Unicorn Rainbows RDoc][1]
+* [Rack RDoc][2]
+* [Rackup HowTo][3]
+
+[1]: http://rainbows.rubyforge.org/
+[2]: http://rack.rubyforge.org/doc/
+[3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
+[4]: http://rainbows.rubyforge.org/SIGNALS.html