about summary refs log tree commit homepage
diff options
context:
space:
mode:
-rw-r--r--.olddoc.yml2
-rw-r--r--Documentation/.gitignore4
-rw-r--r--Documentation/GNUmakefile33
-rw-r--r--Documentation/rainbows.1.txt161
-rw-r--r--GNUmakefile25
-rw-r--r--man/man1/rainbows.1193
6 files changed, 207 insertions, 211 deletions
diff --git a/.olddoc.yml b/.olddoc.yml
index a10528a..2e0f170 100644
--- a/.olddoc.yml
+++ b/.olddoc.yml
@@ -2,7 +2,7 @@
 cgit_url: https://yhbt.net/rainbows.git/
 rdoc_url: https://yhbt.net/rainbows/
 merge_html:
-  rainbows_1: Documentation/rainbows.1.html
+  rainbows_1: man/man1/rainbows.1.html
   Summary: Documentation/comparison.html
 public_email: rainbows-public@yhbt.net
 noindex:
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 46679d6..0a3b033 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -1,5 +1,3 @@
-*.1
-*.5
-*.7
 *.gz
 *.html
+*.txt
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
deleted file mode 100644
index df5c706..0000000
--- a/Documentation/GNUmakefile
+++ /dev/null
@@ -1,33 +0,0 @@
-all::
-
-PANDOC = pandoc
-PANDOC_OPTS = -f markdown --email-obfuscation=none
-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 $@+ $@
-
-comparison.html: comparison.haml
-        haml -t ugly < $< > $@+ && mv $@+ $@
-
-clean::
-        $(RM) $(man1) $(html1) comparison.html
diff --git a/Documentation/rainbows.1.txt b/Documentation/rainbows.1.txt
deleted file mode 100644
index 94adb8a..0000000
--- a/Documentation/rainbows.1.txt
+++ /dev/null
@@ -1,161 +0,0 @@
-% rainbows(1) Rainbows! User Manual
-% Rainbows! Hackers <rainbows-public@yhbt.net>
-% December 3, 2009
-
-# NAME
-
-rainbows - rackup-like command to launch Rainbows!
-
-# SYNOPSIS
-
-rainbows [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
-
-# DESCRIPTION
-
-A rackup(1)-like command to launch Rack applications using Rainbows!.
-It is expected to be started in your application root (APP_ROOT),
-but the "working_directory" directive may be used in the CONFIG_FILE.
-
-While 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.
-    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.
--N, \--no-default-middleware
-:   Disables loading middleware implied by RACK_ENV.  This bypasses the
-    configuration documented in the RACK ENVIRONMENT section, but still
-    allows RACK_ENV to be used for application/framework-specific purposes.
-
-# 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 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 the Rack::ContentLength and Rack::Chunked middlewares are also
-loaded by "deployment" and "development", but no other values of
-RACK_ENV.  If needed, they must 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
-* [Rainbows! RDoc][1]
-* [Rack RDoc][2]
-* [Rackup HowTo][3]
-
-[1]: https://yhbt.net/rainbows/
-[2]: http://rdoc.info/gems/r#/gems/rack/frames
-[3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
-[4]: https://yhbt.net/rainbows/SIGNALS.html
diff --git a/GNUmakefile b/GNUmakefile
index 70cc708..3a739b3 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -4,28 +4,27 @@ RSYNC_DEST := yhbt.net:/srv/yhbt/rainbows
 rfpackage := rainbows
 PLACEHOLDERS := rainbows_1 Summary
 
-man-rdoc: man html
-        $(MAKE) -C Documentation comparison.html
-doc:: man-rdoc
-include pkg.mk
+Documentation/comparison.html: Documentation/comparison.haml
+        haml < $< >$@+ && mv $@+ $@
+
+# only for the website
+doc :: Documentation/comparison.html
+doc :: man/man1/rainbows.1.html
 
-base_bins := rainbows
-bins := $(addprefix bin/, $(base_bins))
-man1_bins := $(addsuffix .1, $(base_bins))
-man1_paths := $(addprefix man/man1/, $(man1_bins))
+include pkg.mk
+man1 := man/man1/rainbows.1
 
 clean:
         -$(MAKE) -C Documentation clean
+        $(RM) $(man1) $(html1)
 
-man html:
-        $(MAKE) -C Documentation install-$@
+pkg_extra += $(man1) lib/rainbows/version.rb
 
-pkg_extra += $(man1_paths) lib/rainbows/version.rb
+%.1.html: %.1
+        $(OLDDOC) man2html -o $@ $<
 
 lib/rainbows/version.rb: GIT-VERSION-FILE
 
 all:: test
 test: lib/rainbows/version.rb
         $(MAKE) -C t
-
-.PHONY: man html
diff --git a/man/man1/rainbows.1 b/man/man1/rainbows.1
new file mode 100644
index 0000000..f7aa43d
--- /dev/null
+++ b/man/man1/rainbows.1
@@ -0,0 +1,193 @@
+.TH "rainbows" "1" "December 3, 2009" "Rainbows! User Manual" ""
+.SH NAME
+.PP
+rainbows \- rackup\-like command to launch Rainbows!
+.SH SYNOPSIS
+.PP
+rainbows [\-c CONFIG_FILE] [\-E RACK_ENV] [\-D] [RACKUP_FILE]
+.SH DESCRIPTION
+.PP
+A rackup(1)\-like command to launch Rack applications using Rainbows!.
+It is expected to be started in your application root (APP_ROOT), but
+the "working_directory" directive may be used in the CONFIG_FILE.
+.PP
+While 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.
+.SH RACKUP FILE
+.PP
+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 \f[I]Rack::Builder\f[] DSL.
+.PP
+Embedded command\-line options are mostly parsed for compatibility with
+rackup(1) but strongly discouraged.
+.SH UNICORN OPTIONS
+.TP
+.B \-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.
+See the RDoc/ri for the \f[I]Unicorn::Configurator\f[] class for the
+full list of directives available from the DSL.
+.RS
+.RE
+.TP
+.B \-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".
+.RS
+.RE
+.TP
+.B \-E, \-\-env RACK_ENV
+Run under the given RACK_ENV.
+See the RACK ENVIRONMENT section for more details.
+.RS
+.RE
+.TP
+.B \-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.
+.RS
+.RE
+.TP
+.B \-N, \-\-no\-default\-middleware
+Disables loading middleware implied by RACK_ENV.
+This bypasses the configuration documented in the RACK ENVIRONMENT
+section, but still allows RACK_ENV to be used for
+application/framework\-specific purposes.
+.RS
+.RE
+.SH RACKUP COMPATIBILITY OPTIONS
+.TP
+.B \-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.
+.RS
+.RE
+.TP
+.B \-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.
+.RS
+.RE
+.TP
+.B \-s, \-\-server SERVER
+No\-op, this exists only for compatibility with rackup(1).
+.RS
+.RE
+.SH RUBY OPTIONS
+.TP
+.B \-e, \-\-eval LINE
+Evaluate a LINE of Ruby code.
+This evaluation happens immediately as the command\-line is being
+parsed.
+.RS
+.RE
+.TP
+.B \-d, \-\-debug
+Turn on debug mode, the $DEBUG variable is set to true.
+.RS
+.RE
+.TP
+.B \-w, \-\-warn
+Turn on verbose warnings, the $VERBOSE variable is set to true.
+.RS
+.RE
+.TP
+.B \-I, \-\-include PATH
+specify
+\f[I]L\f[]\f[I]O\f[]\f[I]A\f[]\f[I]D\f[]~\f[I]P\f[]~\f[I]A\f[]\f[I]T\f[]\f[I]H\f[].\f[I]P\f[]\f[I]A\f[]\f[I]T\f[]\f[I]H\f[]\f[I]w\f[]\f[I]i\f[]\f[I]l\f[]\f[I]l\f[]\f[I]b\f[]\f[I]e\f[]\f[I]p\f[]\f[I]r\f[]\f[I]e\f[]\f[I]p\f[]\f[I]e\f[]\f[I]n\f[]\f[I]d\f[]\f[I]e\f[]\f[I]d\f[]\f[I]t\f[]\f[I]o\f[]LOAD_PATH.
+The \[aq]:\[aq] 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.
+.RS
+.RE
+.TP
+.B \-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.
+.RS
+.RE
+.SH SIGNALS
+.PP
+The following UNIX signals may be sent to the master process:
+.IP \[bu] 2
+HUP \- reload config file, app, and gracefully restart all workers
+.IP \[bu] 2
+INT/TERM \- quick shutdown, kills all workers immediately
+.IP \[bu] 2
+QUIT \- graceful shutdown, waits for workers to finish their current
+request before finishing.
+.IP \[bu] 2
+USR1 \- reopen all logs owned by the master and all workers See
+Unicorn::Util.reopen_logs for what is considered a log.
+.IP \[bu] 2
+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.
+.IP \[bu] 2
+WINCH \- gracefully stops workers but keep the master running.
+This will only work for daemonized processes.
+.IP \[bu] 2
+TTIN \- increment the number of worker processes by one
+.IP \[bu] 2
+TTOU \- decrement the number of worker processes by one
+.PP
+See the SIGNALS (https://yhbt.net/rainbows/SIGNALS.html) document
+for full description of all signals used by Rainbows!.
+.SH RACK ENVIRONMENT
+.PP
+Accepted values of RACK_ENV and the middleware they automatically load
+(outside of RACKUP_FILE) are exactly as those in rackup(1):
+.IP \[bu] 2
+development \- loads Rack::CommonLogger, Rack::ShowExceptions, and
+Rack::Lint middleware
+.IP \[bu] 2
+deployment \- loads Rack::CommonLogger middleware
+.IP \[bu] 2
+none \- loads no middleware at all, relying entirely on RACKUP_FILE
+.PP
+All unrecognized values for RACK_ENV are assumed to be "none".
+Production deployments are strongly encouraged to use "deployment" or
+"none" for maximum performance.
+.PP
+Note the Rack::ContentLength and Rack::Chunked middlewares are also
+loaded by "deployment" and "development", but no other values of
+RACK_ENV.
+If needed, they must be individually specified in the RACKUP_FILE, some
+frameworks do not require them.
+.SH SEE ALSO
+.IP \[bu] 2
+unicorn(1)
+.IP \[bu] 2
+\f[I]Rack::Builder\f[] ri/RDoc
+.IP \[bu] 2
+\f[I]Unicorn::Configurator\f[] ri/RDoc
+.IP \[bu] 2
+Rainbows! RDoc (https://yhbt.net/rainbows/)
+.IP \[bu] 2
+Rack RDoc (http://rdoc.info/gems/r#/gems/rack/frames)
+.IP \[bu] 2
+Rackup HowTo (http://wiki.github.com/rack/rack/tutorial-rackup-howto)
+.SH AUTHORS
+Rainbows! Hackers <rainbows-public@yhbt.net>.