about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <e@80x24.org>2016-02-14 09:33:34 +0000
committerEric Wong <e@80x24.org>2016-02-14 11:26:22 +0000
commit4ef59c7e5e49a21fdad0c3d6e3d78bf717c0e7e5 (patch)
tree56666d7d1440db0e0a40d4440357c9b723f9b3a5
parent631c3b6fd3e0b944b900d181cb51a8c847c14c09 (diff)
downloadyahns-4ef59c7e5e49a21fdad0c3d6e3d78bf717c0e7e5.tar.gz
pod2man(1) and pod2text(1) are already installed on most modern
GNU/Linix systems including Debian and RedHat-based systems;
pandoc(1) and Haskell are not, and we do not wish to waste
precious bandwidth and disk space of potential packagers.

perlpod(1) is also better standardized than any Markdown flavor,
especially when it comes to generating manpages.

Finally, I'm mildly proficient at Perl (it is similar to Ruby)
and can poke around at the source if I encounter breakage.
-rw-r--r--Documentation/.gitignore3
-rw-r--r--Documentation/GNUmakefile27
-rw-r--r--Documentation/yahns-rackup.pod176
-rw-r--r--Documentation/yahns-rackup.txt152
-rw-r--r--Documentation/yahns.pod97
-rw-r--r--Documentation/yahns.txt72
-rw-r--r--Documentation/yahns_config.pod641
-rw-r--r--Documentation/yahns_config.txt584
-rw-r--r--Rakefile5
9 files changed, 945 insertions, 812 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 3bfac8b..c9580a6 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -3,3 +3,6 @@
 *.1
 *.5
 *.7
+yahns_config.txt
+yahns.txt
+yahns-rackup.txt
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 9e92de2..6db8d49 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -3,9 +3,15 @@
 all::
 
 INSTALL = install
-PANDOC = pandoc
+POD2MAN = pod2man
+-include ../GIT-VERSION-FILE
+release := yahns $(VERSION)
 PANDOC_OPTS = -f markdown --email-obfuscation=none
-pandoc = $(PANDOC) $(PANDOC_OPTS)
+POD2MAN_OPTS = -v -r '$(release)' --stderr -d 1994-10-02 -c 'yahns user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
 
 m1 =
 m1 += yahns
@@ -43,8 +49,21 @@ install-man: man
         $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
         $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
         test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
-%.1 %.5 %.7 : %.txt
-        $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+
+%.1 %.5 %.7 : %.pod
+        $(pod2man) -s $(subst .,,$(suffix $@)) $< $@+ && mv $@+ $@
+
+mantxt = $(addsuffix .txt, $(m1) $(m5) $(m7))
+
+txt :: $(mantxt)
+
+all :: txt
+
+%.txt : %.pod
+        $(pod2text) $< $@+
+        -touch -r $< $@+ 2>/dev/null # GNU-ism
+        mv $@+ $@
 
 clean::
         $(RM) $(man1) $(man5) $(man7)
+        $(RM) $(addsuffix .txt.gz, $(m1) $(m5) $(m7))
diff --git a/Documentation/yahns-rackup.pod b/Documentation/yahns-rackup.pod
new file mode 100644
index 0000000..fc724e6
--- /dev/null
+++ b/Documentation/yahns-rackup.pod
@@ -0,0 +1,176 @@
+% yahns-rackup(1) yahns user manual
+
+=head1 NAME
+
+yahns-rackup - a rackup-like command to launch yahns
+
+=head1 SYNOPSIS
+
+yahns-rackup [-E RACK_ENV] [-O worker_threads=NUM] [RACKUP_FILE]
+
+=head1 DESCRIPTION
+
+A L<rackup(1)>-like command to launch Rack applications using yahns.
+It is expected to start in your application root (APP_ROOT).
+
+=head1 RACKUP FILE
+
+This defaults to "config.ru" in APP_ROOT.  It should be the same
+file used by L<rackup(1)> and other Rack launchers, it uses the
+*Rack::Builder* DSL.
+
+=head1 YAHNS OPTIONS
+
+=over
+
+=item -O client_timeout=SECONDS
+
+Defines the timeout expiring idle connections.
+
+Increase this if your application takes longer to run than the
+default timeout.  Lower this if you run out of FDs.
+
+Default: 15 (seconds)
+
+=item -O listen=ADDRESS[,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:9292" (all addresses on TCP port 9292).
+Multiple addresses may be separated with commas.
+
+=item -O stderr_path=PATHNAME
+
+Allow redirecting $stderr to a given path.  Unlike doing this from
+the shell, this allows the yahns process to know the path its
+writing to and rotate the file if it is used for logging.  The
+file will be opened with the O_APPEND flag and writes
+synchronized to the kernel (but not necessarily to _disk_) so
+multiple processes can safely append to it.
+
+If you are daemonizing and using the default logger, it is important
+to specify this as errors will otherwise be lost to /dev/null.
+Some applications/libraries may also triggering warnings that go to
+stderr, and they will end up here.
+
+Default: /dev/null if daemonized, controlling terminal if not
+
+=item -O stdout_path=PATH
+
+Same as stderr_path, except for $stdout.  Not many applications
+write to $stdout, but any that do will have their output written here.
+It is safe to point this to the same location a stderr_path.
+Like stderr_path, this defaults to /dev/null when daemonized.
+
+Default: /dev/null if daemonized, controlling terminal if not
+
+=item -O worker_threads=INTEGER
+
+This controls the number of threads for application processing.
+Each queue has its own thread pool.  Increase this number if your
+applications are able to use more threads effectively or if either
+(or both) input/output buffering are disabled.  Lower this number if
+you do not need multi-thread concurrency at all.
+
+Default: 7
+
+=back
+
+=head1 RACKUP OPTIONS
+
+=over
+
+=item -D, --daemonize
+
+Run daemonized in the background.  The process is detached from
+the controlling terminal and stdin is redirected to /dev/null.
+Unless specified via stderr_path and stdout_path, stderr and stdout will
+also be redirected to "/dev/null".
+
+=item -E, --env RACK_ENV
+
+Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+for more details.
+
+=item -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 L<rackup(1)> command,
+use of "-l"/"--listen" switch is recommended instead.
+
+=item -p, --port PORT
+
+Listen on the specified TCP PORT, default is 9292.
+If specified multiple times on the command-line, only the last-specified
+value takes effect.
+This option only exists for compatibility with the Lrackup(1)> command,
+use of "-l"/"--listen" switch is recommended instead.
+
+=back
+
+=head1 RUBY OPTIONS
+
+=over
+
+=item -e, --eval LINE
+
+Evaluate a LINE of Ruby code.  This evaluation happens
+immediately as the command-line is being parsed.
+
+=item -d, --debug
+
+Turn on debug mode, the $DEBUG variable is set to true.
+
+=item -w, --warn
+
+Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+=item -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.
+
+=item -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.
+
+=back
+
+=head1 SIGNALS
+
+See L<yahns(1)>
+
+=head1 FILES
+
+See Rack documentation for a description of the rackup file format.
+
+=head1 ENVIRONMENT VARIABLES
+
+The RACK_ENV variable is set by the aforementioned -E switch.
+If RACK_ENV is already set, it will be used unless -E is used.
+See rackup documentation for more details.
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to L<yahns-public@yhbt.net>
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2013-2016 all contributors L<mailto:yahns-public@yhbt.net>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<yahns(1)>, L<yahns_config(5)>, *Rack::Builder* ri/RDoc,
+L<Rack RDoc|http://www.rubydoc.info/github/rack/rack/>,
+L<Rackup HowTo|https://wiki.github.com/rack/rack/tutorial-rackup-howto>
diff --git a/Documentation/yahns-rackup.txt b/Documentation/yahns-rackup.txt
deleted file mode 100644
index 902e6d1..0000000
--- a/Documentation/yahns-rackup.txt
+++ /dev/null
@@ -1,152 +0,0 @@
-% yahns-rackup(1) yahns user manual
-
-# NAME
-
-yahns-rackup - a rackup-like command to launch yahns
-
-# SYNOPSIS
-
-yahns-rackup [-E RACK_ENV] [-O worker_threads=NUM] [RACKUP_FILE]
-
-# DESCRIPTION
-
-A rackup(1)-like command to launch Rack applications using yahns.
-It is expected to start in your application root (APP_ROOT).
-
-# 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.
-
-# YAHNS OPTIONS
--O client_timeout=SECONDS
-:   Defines the timeout expiring idle connections.
-
-    Increase this if your application takes longer to run than the
-    default timeout.  Lower this if you run out of FDs.
-
-    Default: 15 (seconds)
-
--O listen=ADDRESS[,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:9292" (all addresses on TCP port 9292).
-    Multiple addresses may be separated with commas.
-
--O stderr_path=PATHNAME
-:   Allow redirecting $stderr to a given path.  Unlike doing this from
-    the shell, this allows the yahns process to know the path its
-    writing to and rotate the file if it is used for logging.  The
-    file will be opened with the O_APPEND flag and writes
-    synchronized to the kernel (but not necessarily to _disk_) so
-    multiple processes can safely append to it.
-
-    If you are daemonizing and using the default logger, it is important
-    to specify this as errors will otherwise be lost to /dev/null.
-    Some applications/libraries may also triggering warnings that go to
-    stderr, and they will end up here.
-
-    Default: /dev/null if daemonized, controlling terminal if not
-
--O stdout_path=PATH
-:   Same as stderr_path, except for $stdout.  Not many applications
-    write to $stdout, but any that do will have their output written here.
-    It is safe to point this to the same location a stderr_path.
-    Like stderr_path, this defaults to /dev/null when daemonized.
-
-    Default: /dev/null if daemonized, controlling terminal if not
-
--O worker_threads=INTEGER
-:   This controls the number of threads for application processing.
-    Each queue has its own thread pool.  Increase this number if your
-    applications are able to use more threads effectively or if either
-    (or both) input/output buffering are disabled.  Lower this number if
-    you do not need multi-thread concurrency at all.
-
-    Default: 7
-
-# RACKUP OPTIONS
--D, \--daemonize
-:   Run daemonized in the background.  The process is detached from
-    the controlling terminal and stdin is redirected to /dev/null.
-    Unless specified via stderr_path and stdout_path, 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.
-
--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 9292.
-    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.
-
-# 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
-
-See yahns(1)
-
-# FILES
-
-See Rack documentation for a description of the rackup file format.
-
-# ENVIRONMENT VARIABLES
-
-The RACK_ENV variable is set by the aforementioned \-E switch.
-If RACK_ENV is already set, it will be used unless \-E is used.
-See rackup documentation for more details.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to <yahns-public@yhbt.net>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright (C) 2013-2016 all contributors <yahns-public@yhbt.net>
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-yahns(1), yahns_config(5)
-
-* *Rack::Builder* ri/RDoc
-* [Rack RDoc][1]
-* [Rackup HowTo][2]
-
-[1]: http://rdoc.info/gems/r#/gems/rack/frames
-[2]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
diff --git a/Documentation/yahns.pod b/Documentation/yahns.pod
new file mode 100644
index 0000000..bad468e
--- /dev/null
+++ b/Documentation/yahns.pod
@@ -0,0 +1,97 @@
+% yahns(1) yahns user manual
+
+=head1 NAME
+
+yahns - multi-threaded, non-blocking application server for Ruby
+
+=head1 SYNOPSYS
+
+yahns -c CONFIG_FILE [-D|--daemonize]
+
+=head1 DESCRIPTION
+
+L<yahns(1)> is the primary interface for launching a yahns application
+server.  The configuration file is documented in L<yahns_config(5)>.
+yahns hosts Rack HTTP applications, but may support others in the
+future such as DRb.
+
+=head1 SIGNALS
+
+The following UNIX signals may be sent to the running yahns process.
+If yahns is configured for worker_processes (optional), signals should
+only be sent to the master process.
+
+=over
+
+=item INT/TERM/QUIT
+
+Graceful shutdown.  If repeated (any of these signals
+is sent twice), shutdown occurs immediately.
+
+=item USR1
+
+Reopen all logs owned by the master and all workers.
+This scans the Ruby ObjectSpace for all open File objects with the
+O_APPEND file flag and buffering disabled (IO#sync==false)
+
+=item 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.
+
+=item HUP
+
+If worker_processes are not used, this will reexecute the running
+binary and gracefully exit the running process.  If worker_processes are
+used, this will reload config file, app, and gracefully restart all workers
+
+=item WINCH
+
+Gracefully stops workers but keep the master running.
+This will only work for daemonized processes and only if the
+worker_processes configuration directive is used.
+
+=item TTIN
+
+Increment the number of worker processes by one
+(only if the worker_processes directive is used)
+
+=item TTOU
+
+Decrement the number of worker processes by one
+(only if the worker_processes directive is used)
+
+=back
+
+=head1 ENVIRONMENT
+
+L<yahns(1)> itself requires no special environment variables.  However,
+environment variables such as RACK_ENV and RAILS_ENV can affect Rack and
+Rails applications it hosts.  Ruby and C library implementation-specific
+environment variables will also affect it.
+
+yahns will update the PWD (current working directory) env if the
+working_directory directive is set (see L<yahns_config(5)>).
+
+LISTEN_FDS and LISTEN_PID variables are used in our emulation
+of L<sd_listen_fds(3)> function.   See L<sd_listen_fds(3)> manpage
+for more details.
+
+=head1 FILES
+
+See L<yahns_config(5)> for documentation on the configuration file format.
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to L<mailto:yahns-public@yhbt.net>
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2013-2016 all contributors L<mailto:yahns-public@yhbt.net>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<yahns-rackup(1)>, L<yahns_config(5)>, L<sd_listen_fds(3)>
diff --git a/Documentation/yahns.txt b/Documentation/yahns.txt
deleted file mode 100644
index dd388b4..0000000
--- a/Documentation/yahns.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-% yahns(1) yahns user manual
-%
-
-# NAME
-
-yahns - multi-threaded, non-blocking application server for Ruby
-
-# SYNOPSYS
-
-yahns -c CONFIG_FILE [-D|--daemonize]
-
-# DESCRIPTION
-
-yahns(1) is the primary interface for launching a yahns application
-server.  The configuration file is documented in yahns_config(5).  yahns
-hosts Rack HTTP applications, but may support others in the future such
-as DRb.
-
-# SIGNALS
-
-The following UNIX signals may be sent to the running yahns process.
-If yahns is configured for worker_processes (optional), signals should
-only be sent to the master process.
-
-* INT/TERM/QUIT - graceful shutdown.  If repeated (any of these signals
-  is sent twice), shutdown occurs immediately.
-* USR1 - reopen all logs owned by the master and all workers.
-  This scans the Ruby ObjectSpace for all open File objects with the O_APPEND
-  file flag and buffering disabled (IO#sync==false)
-* USR2 - reexecute the running binary.  A separate QUIT should be sent to
-* HUP - if worker_processes are not used, this will reexecute the running
-  binary and gracefully exit the running process.  If worker_processes are
-  used, this will reload config file, app, and gracefully restart all workers
-* WINCH - gracefully stops workers but keep the master running.
-  This will only work for daemonized processes and only if the
-  worker_processes configuration directive is used.
-* TTIN - increment the number of worker processes by one
-  (only if the worker_processes directive is used)
-* TTOU - decrement the number of worker processes by one
-  (only if the worker_processes directive is used)
-
-# ENVIRONMENT
-
-yahns(1) itself requires no special environment variables.  However,
-environment variables such as RACK_ENV and RAILS_ENV can affect Rack and
-Rails applications it hosts.  Ruby and C library implementation-specific
-environment variables will also affect it.
-
-yahns will update the PWD (current working directory) env if the
-working_directory directive is set (see yahns_config(5)).
-
-LISTEN_FDS and LISTEN_PID variables are used in our emulation
-of sd_listen_fds(3) function.   See sd_listen_fds(3) manpage
-for more details.
-
-# FILES
-
-See yahns_config(5) for documentation on the configuration file format.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to <yahns-public@yhbt.net>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright (C) 2013-2016 all contributors <yahns-public@yhbt.net>
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-yahns-rackup(1), yahns_config(5), sd_listen_fds(3)
diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
new file mode 100644
index 0000000..ff04cb3
--- /dev/null
+++ b/Documentation/yahns_config.pod
@@ -0,0 +1,641 @@
+% yahns_config(5) yahns user manual
+
+=head1 NAME
+
+yahns_config - configuration file description for L<yahns(1)>
+
+=head1 DESCRIPTION
+
+Since yahns is a Ruby application server, its configuration file is
+implemented in Ruby syntax, making it dependent on the version of
+Ruby it is running under.
+
+=head1 TOP-LEVEL DIRECTIVES
+
+=over
+
+=item app :TYPE, *APP_ARGUMENTS, &BLOCK
+
+This defines an application context for yahns to run.  :TYPE defines
+the type of application it runs.  yahns will eventually support
+application types other than :rack, but for now, only :rack is
+supported.
+
+The &BLOCK given configures the which sockets the app listens on,
+buffering and logging settings.
+
+An app with the same :TYPE and APP_ARGUMENTS may be defined multiple
+times with different &BLOCK contents (with different listeners and
+buffering settings).
+
+See the APP-LEVEL DIRECTIVES section for details on what goes into
+the &BLOCK.
+
+This directive may be specified multiple times for different or
+identical applications.
+
+If the "working_directory" directive is used, all app directives may
+only be specified after setting "working_directory".
+
+For Rack HTTP applications, see RACK APP ARGUMENTS for more
+information.
+
+=item before_exec &BLOCK
+
+This runs &BLOCK before Kernel#exec (L<execve(2)> wrapper).  The command
+array to be passed to Kernel#exec may be modified within this hook:
+
+  before_exec do |cmd|
+    # you may modify ENV here inside the child process
+    ENV["MALLOC_ARENA_MAX"] = ENV["MALLOC_ARENA_TEST"] = "1"
+
+    # You may change to a different installation of Ruby or yahns
+    # by doing an in-place modification of cmd:
+    cmd.replace(%W(/another/install/of/yahns -c cfg.rb))
+  end
+
+Default: (none)
+
+=item client_expire_threshold {INTEGER|FLOAT}
+
+yahns will start expiring idle clients when it hits this threshold.
+If the threshold is a floating point number, it is that fraction of
+the soft open file limit (RLIMIT_NOFILE ir `ulimit -S -n` in shell).
+Thus if the soft open file limit is 1024 (a typical value) and the
+client_expire_threshold is 0.3, yahns will start expiring clients once
+it hits 307 clients (0.3 * 1024).
+
+If given a positive integer, yahns will start expiring clients once it
+its this absolute threshold of connected clients.
+
+If given a negative integer, yahns will start expiring clients once it
+reaches N clients away from the the soft file limit.  That is, if
+client_expire_threshold is -666 and the soft open file limit is 1024,
+it will start expiring once it hits 358 clients.
+
+Clients are expired when the configured client_timeout for their
+app context is hit.
+
+Default: 0.5
+
+=item logger LOGGER
+
+Sets LOGGER as the default logger of the process.  The new
+LOGGER must respond to the following methods:
+
+  debug, info, warn, error, fatal
+
+The default logger will log its output to the path specified
+by stderr_path.  If you're running yahns daemonized, then
+you must specify a path to prevent error messages from going
+to /dev/null
+
+A per-APP &BLOCK logger may also be configured inside an app &BLOCK.
+
+Default: Logger.new($stderr)
+
+=item pid PATHNAME
+
+Sets the path of the PID file for use with management/init scripts.
+
+Default: none
+
+=item queue [NAME] &BLOCK
+
+As a top-level directive, this configures or defines a queue.
+If no NAME is specified, a default queue (named :default) is
+assumed.  See the QUEUE-LEVEL DIRECTIVES section for details.
+
+A &BLOCK must be given if used as a top-level directive.  This
+behaves slightly differently inside an app &BLOCK.  This may also
+be given without a block to associate an app block with a named
+queue.
+
+Usually, only one queue is necessary.  Each queue corresponds to
+an epoll descriptor and worker thread pool.
+
+Default: NAME defaults to :default
+
+=item stderr_path PATHNAME
+
+Allow redirecting $stderr to a given path.  Unlike doing this from
+the shell, this allows the yahns process to know the path its
+writing to and rotate the file if it is used for logging.  The
+file will be opened with the O_APPEND flag and writes
+synchronized to the kernel (but not necessarily to _disk_) so
+multiple processes can safely append to it.
+
+If you are daemonizing and using the default logger, it is important
+to specify this as errors will otherwise be lost to /dev/null.
+Some applications/libraries may also triggering warnings that go to
+stderr, and they will end up here.
+
+Default: /dev/null if daemonized, controlling terminal if not
+
+=item stdout_path PATHNAME
+
+Same as stderr_path, except for $stdout.  Not many applications
+write to $stdout, but any that do will have their output written here.
+It is safe to point this to the same location a stderr_path.
+Like stderr_path, this defaults to /dev/null when daemonized.
+
+Default: /dev/null if daemonized, controlling terminal if not
+
+=item working_directory PATHNAME
+
+Sets the working directory for the process.  This ensures SIGUSR2 will
+start a new instance of yahns in this directory.  This may be
+a symlink, a common scenario for Capistrano users.  Unlike
+all other yahns configuration directives, this binds immediately
+for error checking and cannot be undone by unsetting it in the
+configuration file and reloading.
+
+This must be specified before any "app" directives
+
+Default: / if daemonized, current working directory if not
+
+=back
+
+=head2 QUEUE-LEVEL DIRECTIVES
+
+=over
+
+=item max_events INTEGER
+
+This controls the number of events a worker thread will fetch at
+once via L<epoll_wait(2)>.  There is no good reason to change this
+unless you use very few (e.g. 1) worker_threads.  Leaving this at
+1 will give the fairest load balancing behavior with epoll.
+
+Default: 1
+
+=item worker_threads INTEGER
+
+This controls the number of threads for application processing.
+Each queue has its own thread pool.  Increase this number if your
+applications are able to use more threads effectively or if either
+(or both) input/output buffering are disabled.  Lower this number if
+you do not need multi-thread concurrency at all.
+
+Default: 7
+
+=back
+
+=head2 APP-LEVEL DIRECTIVES
+
+=over
+
+=item atfork_prepare, atfork_parent, atfork_child
+
+These are identical to the methods defined in WORKER_PROCESSES-LEVEL
+DIRECTIVES, however they are available inside the app blocks for
+convenience in case it is easier to organize per-app hooks.
+
+Default: (none)
+
+=item check_client_connection BOOLEAN
+
+When enabled, yahns will check the client connection by writing
+the beginning of the HTTP headers before calling the application.
+
+This can prevent calling the application for clients who have
+disconnected while their connection was waiting for a free
+worker thread.
+
+This only affects clients connecting over Unix domain sockets and
+TCP via loopback (127.*.*.*).  It is unlikely to detect disconnects
+if the client is on a remote host (even on a fast LAN).
+
+This has no effect for (rare) HTTP/0.9 clients.
+
+Default: false
+
+=item client_body_buffer_size INTEGER
+
+This controls the maximum size of a request body before it is
+buffered to the filesystem (instead of memory).  This has no effect
+if input_buffering is false.  This also governs the size of an
+individual L<read(2)> system call when reading a request body.
+
+There is generally no need to change this value and this directive
+may be removed in the future.
+
+Default: 8192 bytes (8 kilobytes)
+
+=item client_header_buffer_size INTEGER
+
+This controls the size of a single L<read(2)> syscall for reading
+client request headers.  Increase this as needed if your application
+uses large cookies or long URLs.  Lowering this may reduce GC and
+memory allocator overhead.
+
+Default: 4000 bytes
+
+=item client_max_body_size {INTEGER|nil}
+
+This controls the maximum request body size before a client is
+rejected with an HTTP 413 error.
+
+Setting this to nil will allow unlimited-sized inputs.
+
+Default: 1048576 bytes (one megabyte)
+
+=item client_timeout SECONDS
+
+Defines the timeout expiring idle connections.
+
+If input_buffering is false or :lazy, this defines the maximum
+amount of time a worker thread will wait synchronously for a client
+request body.
+
+If output_buffering is false, this defines the maximum amount of
+time a worker thread will wait synchronously for a client socket
+to become writable.
+
+It makes sense to lower this to a low value (e.g. 5 seconds) if
+either output or input buffering are disabled.  The default value
+of 15 seconds is suitable for configurations with both input and
+output buffering enabled and assumes all application dispatch
+finishes in less than 15 seconds.
+
+Default: 15 (seconds)
+
+=item errors {IO|PATHNAME}
+
+For Rack applications, this controls the env["rack.errors"]
+destination.  If given a PATHNAME, it will be a writable file
+opened with O_APPEND without userspace buffering, making it suitable
+for concurrent appends by multiple processes and threads, as well as
+making it eligible for reopening via SIGUSR1 after log rotation.
+
+Default: $stderr
+
+=item input_buffering {:lazy|true|false}[, OPTIONS]
+
+This controls buffering of the HTTP request body.
+
+=over
+
+=item true
+
+Fully buffers the request before application dispatch.  This is
+most suitable for slow and untrusted clients which may trickle
+the request to the server.
+
+=item :lazy
+
+Provides streaming, but rewindable input.  This is suitable
+for fast, trusted clients and is fully-compatible with Rack 1.x
+specifications.  :lazy buffering may also be suitable for slow and
+untrusted clients if you are able and willing to run a queue with
+many worker threads.
+
+=item false
+
+Disable input buffering completely.  This violates the
+Rack 1.x spec and is only suitable for fast, trusted clients or
+queues with many worker threads.
+
+HTTP request headers are always buffered in memory.
+
+Do not be tempted to disable any buffering because it improves
+numbers on a synthetic benchmark over a fast connection.
+Slow, real-world clients can easily overwhelm servers without both
+input and output buffering.
+
+=back
+
+Default: true
+
+The following OPTIONS may be specified for input_buffering:
+
+=over
+
+=item tmpdir: DIRECTORY
+
+Specify an alternative temporary directory of input_buffering is
+:lazy or true.  This can be used in case the normal temporary
+directory is too small or busy to be used for input buffering.
+
+Default: Dir.tmpdir (usually from TMPDIR env or /tmp)
+
+=back
+
+=item listen ADDRESS [, OPTIONS]
+
+Adds an ADDRESS to the existing listener set.  May be specified more
+than once.  ADDRESS may be an Integer port number for a TCP port, an
+"IP_ADDRESS:PORT" for TCP listeners or a pathname for UNIX domain sockets.
+
+  # listen to port 3000 on all TCP interfaces
+  listen 3000
+
+  # listen to port 3000 on the loopback interface
+  listen "127.0.0.1:3000"
+
+  # listen on the given Unix domain socket
+  listen "/path/to/.unicorn.sock"
+
+  # listen to port 3000 on the IPv6 loopback interface
+  listen "[::1]:3000"
+
+When using Unix domain sockets, be sure:
+
+=over
+
+=item 1. the path matches the one used by nginx
+
+=item 2. uses the same filesystem namespace as the nginx process
+
+=back
+
+For systemd users using PrivateTmp=true (for either nginx or yahns),
+this means Unix domain sockets must not be placed in /tmp
+
+The following OPTIONS may be specified (but are generally not needed):
+
+=over
+
+=item backlog: INTEGER
+
+This is the backlog of the L<listen(2)> syscall.
+
+Some operating systems allow negative values here to specify the
+maximum allowable value.  In most cases, this number is only
+recommendation and there are other OS-specific tunables and
+variables that can affect this number.  See the L<listen(2)>
+syscall documentation of your OS for the exact semantics of
+this.
+
+If you are running unicorn on multiple machines, lowering this number
+can help your load balancer detect when a machine is overloaded
+and give requests to a different machine.
+
+Default: 1024
+
+=item ipv6only: BOOLEAN
+
+This option makes IPv6-capable TCP listeners IPv6-only and unable
+to receive IPv4 queries on dual-stack systems.  A separate IPv4-only
+listener is required if this is true.
+
+Enabling this option for the IPv6-only listener and having a
+separate IPv4 listener is recommended if you wish to support IPv6
+on the same TCP port.  Otherwise, the value of env["REMOTE_ADDR"]
+will appear as an ugly IPv4-mapped-IPv6 address for IPv4 clients
+(e.g ":ffff:10.0.0.1" instead of just "10.0.0.1").
+
+Default: Operating-system dependent
+
+=item sndbuf / rcvbuf: INTEGER
+
+Maximum receive and send buffer sizes (in bytes) of sockets.
+
+These correspond to the SO_RCVBUF and SO_SNDBUF settings which
+can be set via the L<setsockopt(2)> syscall.  Some kernels
+(e.g. Linux 2.4+) have intelligent auto-tuning mechanisms and
+there is no need (and it is sometimes detrimental) to specify them.
+
+See the socket API documentation of your operating system
+to determine the exact semantics of these settings and
+other operating system-specific knobs where they can be
+specified.
+
+Defaults: operating system defaults
+
+=item reuseport: BOOLEAN
+
+This enables multiple, independently-started yahns instances to
+bind to the same port (as long as all the processes enable this).
+
+This option must be used when yahns first binds the listen socket.
+It cannot be enabled when a socket is inherited via SIGUSR2
+(but it will remain on if inherited), and it cannot be enabled
+directly via SIGHUP.
+
+Note: there is a chance of connections being dropped if
+one of the yahns instances is stopped while using this.
+
+This is supported on *BSD systems and Linux 3.9 or later.
+
+ref: https://lwn.net/Articles/542629/
+
+Default: false (unset)
+
+=item threads: INTEGER
+
+Used to control the number of threads blocking on the L<accept(2)>
+or L<accept4(2)> system call (per listen socket).
+
+Usually, only one thread here is necessary, especially when
+multiple worker_processes are configured (as there'll be one
+thread per-process).  Having extra threads may increase
+contention with epoll and FD allocation within one process.
+
+Note: do not confuse this option with worker_threads for queues,
+each queue has their own thread pool and it makes sense to
+have multiple threads there.
+
+Default: 1
+
+=item umask: MODE
+
+Sets the file mode creation mask for UNIX sockets.  If specified,
+this is usually in octal notation.
+
+Typically UNIX domain sockets are created with more liberal
+file permissions than the rest of the application.  By default,
+we create UNIX domain sockets to be readable and writable by
+all local users to give them the same accessibility as
+locally-bound TCP listeners.
+
+This has no effect on TCP listeners.
+
+Default: 0000 (world-read/writable)
+
+=back
+
+=item logger LOGGER
+
+Configures a logger within the current app &BLOCK.
+This behaves the same as the logger directive described in
+TOP-LEVEL DIRECTIVES
+
+Default: uses the top-level logger
+
+=item output_buffering BOOLEAN [, OPTIONS]
+
+This enables or disables buffering of the HTTP response.  If enabled,
+buffering is only performed lazily.  In other words, buffering only
+happens if socket buffers (in the kernel) are filled up, and yahns
+will continously try to flush the buffered data to the socket while
+it is buffering.
+
+Disabling output buffering is only recommended if ALL clients
+connecting to this application context are fast, trusted or
+you are willing and able to run many worker threads.
+
+Do not be tempted to disable any buffering because it improves
+numbers on a synthetic benchmark over a fast connection.
+Slow, real-world clients can easily overwhelm servers without both
+input and output buffering.
+
+If output buffering is disabled, client_timeout controls the maximum
+amount of time a worker thread will wait synchronously.
+
+Default: true
+
+The following OPTIONS may be specified for output_buffering:
+
+=over
+
+=item tmpdir: DIRECTORY
+
+Specify an alternative temporary directory of output_buffering is
+enabled.  This can be used in case the normal temporary directory
+is too small or busy to be used for output buffering.
+
+Default: Dir.tmpdir (usually from TMPDIR env or /tmp)
+
+=back
+
+=item persistent_connections BOOLEAN
+
+Enable or disables persistent connections and pipelining for HTTP
+connections.  Persistent connections only expire when the global
+client_expire_threshold is hit and a client hits its client_timeout.
+
+Default: true
+
+=item user USER [,GROUP]
+
+Runs application process(es) as the specified USER and GROUP.
+
+If using worker_processes, this only affects the workers and the
+master stays running as the user who started it.  This switch will
+occur before calling the atfork_child hook(s).
+
+GROUP is optional and will not change if unspecified.
+
+Default: none (no user switching is done)
+
+=item queue [NAME or &BLOCK]
+
+If given a NAME-only, this will associate this app &BLOCK with an
+existing queue.
+
+If given a &BLOCK-only, this will create an anonymous queue for this
+application context only.  If given a &BLOCK, this takes the same
+parameters (worker_threads and max_events) as described in
+L</QUEUE-LEVEL DIRECTIVES>.
+
+NAME and &BLOCK may not be combined inside an app &BLOCK.
+
+Default: uses the global, :default queue if none is specified
+
+=item shutdown_timeout SECONDS
+
+This defines the timeout for gracefully exiting the process if there
+are still connected clients.  This should generally be higher or equal
+to the app with the highest client_timeout value.
+
+Increase this if your application has slow endpoints which may take
+longer than the default timeout.
+
+Default: max client_timeout value of all apps in the process
+
+=item worker_processes INTEGER [&BLOCK]
+
+This directive allows yahns to use a master/worker configuration to
+use multiple processes.  Specifying any numeric value (including 1)
+here means yahns will enable yahns to use a master/worker process
+model instead of a single process.
+
+If an optional &BLOCK is given, it may be used to configure
+L<pthread_atfork(3)>-style hooks.
+See L</WORKER_PROCESSES-LEVEL DIRECTIVES> for details.
+
+Using worker_processes is strongly recommended if your application
+relies on using a SIGCHLD handler for reaping forked processes.
+Without worker_processes, yahns must reserve SIGCHLD for rolling
+back SIGUSR2 upgrades, leading to conflicts if the appplication
+expects to handle SIGCHLD.
+
+Default: nil (single process, no master/worker separation)
+
+=back
+
+=head2 WORKER_PROCESSES-LEVEL DIRECTIVES
+
+Note: all of the atfork_* hooks described here are available inside the
+"app" blocks, too.
+
+=over
+
+=item atfork_prepare &BLOCK
+
+This &BLOCK is executed in the parent before L<fork(2)> operation.
+This may be useful for app directives which specify "preload: true"
+to disconnect from databases or otherwise close open file descriptors
+to prevent them from being shared with the children.
+
+Default: none
+
+=item atfork_parent &BLOCK
+
+This &BLOCK is executed in the parent after the L<fork(2)> operation.
+This may not be useful, but exists in case somebody finds a use for it.
+
+Default: none
+
+=item atfork_child &BLOCK
+
+This &BLOCK is executed in the child after the L<fork(2)> operation.
+
+This may be useful for app directives which specify "preload: true"
+to reconnect to databases or reopen closed file descriptors which
+were closed in the atfork_prepare hook.
+
+Default: none
+
+=back
+
+=head1 RACK APP ARGUMENTS
+
+Rack applications take a PATHNAME to the L<rackup(1)> config file
+(e.g.  "config.ru") as its first argument.
+
+The only supported keyword argument is:
+
+=over
+
+=item preload: BOOLEAN
+
+preload: only makes sense if worker_processes are configured.
+Preloading an app allows memory to be saved under a copy-on-write GC,
+but will often require atfork_* hooks to be registered when configuring
+worker_processes.  preload: defaults to false for maximum out-of-the-box
+compatibility.
+
+=back
+
+=head2 RACK APP EXAMPLE
+
+  app(:rack, "/path/to/config.ru", preload: false) do
+    # APP-LEVEL DIRECTIVES GO HERE
+  end
+
+=head1 EXAMPLES
+
+See the examples/ directory in the git source tree.
+
+  git clone git://yhbt.net/yahns.git
+
+=head1 COPYRIGHT
+
+Copyright (C) 2013-2016 all contributors L<mailto:yahns-public@yhbt.net>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<yahns(1)>
diff --git a/Documentation/yahns_config.txt b/Documentation/yahns_config.txt
deleted file mode 100644
index c7c78d7..0000000
--- a/Documentation/yahns_config.txt
+++ /dev/null
@@ -1,584 +0,0 @@
-% yahns_config(5) yahns user manual
-%
-
-# NAME
-
-yahns_config - configuration file description for yahns(1)
-
-# DESCRIPTION
-
-Since yahns is a Ruby application server, its configuration file is
-implemented in Ruby syntax, making it dependent on the version of
-Ruby it is running under.
-
-# TOP-LEVEL DIRECTIVES
-
-* app :TYPE, *APP_ARGUMENTS, &BLOCK
-
-    This defines an application context for yahns to run.  :TYPE defines
-    the type of application it runs.  yahns will eventually support
-    application types other than :rack, but for now, only :rack is
-    supported.
-
-    The &BLOCK given configures the which sockets the app listens on,
-    buffering and logging settings.
-
-    An app with the same :TYPE and APP_ARGUMENTS may be defined multiple
-    times with different &BLOCK contents (with different listeners and
-    buffering settings).
-
-    See the APP-BLOCK DIRECTIVES section for details on what goes into
-    the &BLOCK.
-
-    This directive may be specified multiple times for different or
-    identical applications.
-
-    If the "working_directory" directive is used, all app directives may
-    only be specified after setting "working_directory".
-
-    For Rack HTTP applications, see RACK APP ARGUMENTS for more
-    information.
-
-* before_exec &BLOCK
-
-    This runs &BLOCK before Kernel#exec (execve(2) wrapper).  The command
-    array to be passed to Kernel#exec may be modified within this hook:
-
-        before_exec do |cmd|
-          # you may modify ENV here inside the child process
-          ENV["MALLOC_ARENA_MAX"] = ENV["MALLOC_ARENA_TEST"] = "1"
-
-          # You may change to a different installation of Ruby or yahns
-          # by doing an in-place modification of cmd:
-          cmd.replace(%W(/another/install/of/yahns -c cfg.rb))
-        end
-
-    Default: (none)
-
-* client_expire_threshold {INTEGER|FLOAT}
-
-    yahns will start expiring idle clients when it hits this threshold.
-    If the threshold is a floating point number, it is that fraction of
-    the soft open file limit (RLIMIT_NOFILE ir `ulimit -S -n` in shell).
-    Thus if the soft open file limit is 1024 (a typical value) and the
-    client_expire_threshold is 0.3, yahns will start expiring clients once
-    it hits 307 clients (0.3 * 1024).
-
-    If given a positive integer, yahns will start expiring clients once it
-    its this absolute threshold of connected clients.
-
-    If given a negative integer, yahns will start expiring clients once it
-    reaches N clients away from the the soft file limit.  That is, if
-    client_expire_threshold is -666 and the soft open file limit is 1024,
-    it will start expiring once it hits 358 clients.
-
-    Clients are expired when the configured client_timeout for their
-    app context is hit.
-
-    Default: 0.5
-
-* logger LOGGER
-
-    Sets LOGGER as the default logger of the process.  The new
-    LOGGER must respond to the following methods:
-
-      debug, info, warn, error, fatal
-
-    The default logger will log its output to the path specified
-    by stderr_path.  If you're running yahns daemonized, then
-    you must specify a path to prevent error messages from going
-    to /dev/null
-
-    A per-APP &BLOCK logger may also be configured inside an app &BLOCK.
-
-    Default: Logger.new($stderr)
-
-* pid PATHNAME
-
-    Sets the path of the PID file for use with management/init scripts.
-
-    Default: none
-
-* queue [NAME] &BLOCK
-
-    As a top-level directive, this configures or defines a queue.
-    If no NAME is specified, a default queue (named :default) is
-    assumed.  See the QUEUE-LEVEL DIRECTIVES section for details.
-
-    A &BLOCK must be given if used as a top-level directive.  This
-    behaves slightly differently inside an app &BLOCK.  This may also
-    be given without a block to associate an app block with a named
-    queue.
-
-    Usually, only one queue is necessary.  Each queue corresponds to
-    an epoll descriptor and worker thread pool.
-
-    Default: NAME defaults to :default
-
-* stderr_path PATHNAME
-
-    Allow redirecting $stderr to a given path.  Unlike doing this from
-    the shell, this allows the yahns process to know the path its
-    writing to and rotate the file if it is used for logging.  The
-    file will be opened with the O_APPEND flag and writes
-    synchronized to the kernel (but not necessarily to _disk_) so
-    multiple processes can safely append to it.
-
-    If you are daemonizing and using the default logger, it is important
-    to specify this as errors will otherwise be lost to /dev/null.
-    Some applications/libraries may also triggering warnings that go to
-    stderr, and they will end up here.
-
-    Default: /dev/null if daemonized, controlling terminal if not
-
-* stdout_path PATHNAME
-
-    Same as stderr_path, except for $stdout.  Not many applications
-    write to $stdout, but any that do will have their output written here.
-    It is safe to point this to the same location a stderr_path.
-    Like stderr_path, this defaults to /dev/null when daemonized.
-
-    Default: /dev/null if daemonized, controlling terminal if not
-
-* working_directory PATHNAME
-
-    Sets the working directory for the process.  This ensures SIGUSR2 will
-    start a new instance of yahns in this directory.  This may be
-    a symlink, a common scenario for Capistrano users.  Unlike
-    all other yahns configuration directives, this binds immediately
-    for error checking and cannot be undone by unsetting it in the
-    configuration file and reloading.
-
-    This must be specified before any "app" directives
-
-    Default: / if daemonized, current working directory if not
-
-# QUEUE-LEVEL DIRECTIVES
-
-* max_events INTEGER
-
-    This controls the number of events a worker thread will fetch at
-    once via epoll_wait(2).  There is no good reason to change this
-    unless you use very few (e.g. 1) worker_threads.  Leaving this at
-    1 will give the fairest load balancing behavior with epoll.
-
-    Default: 1
-
-* worker_threads INTEGER
-
-    This controls the number of threads for application processing.
-    Each queue has its own thread pool.  Increase this number if your
-    applications are able to use more threads effectively or if either
-    (or both) input/output buffering are disabled.  Lower this number if
-    you do not need multi-thread concurrency at all.
-
-    Default: 7
-
-## APP-BLOCK DIRECTIVES
-
-* atfork_prepare, atfork_parent, atfork_child
-
-    These are identical to the methods defined in WORKER_PROCESSES-LEVEL
-    DIRECTIVES, however they are available inside the app blocks for
-    convenience in case it is easier to organize per-app hooks.
-
-    Default: (none)
-
-* check_client_connection BOOLEAN
-
-    When enabled, yahns will check the client connection by writing
-    the beginning of the HTTP headers before calling the application.
-
-    This can prevent calling the application for clients who have
-    disconnected while their connection was waiting for a free
-    worker thread.
-
-    This only affects clients connecting over Unix domain sockets and
-    TCP via loopback (127.*.*.*).  It is unlikely to detect disconnects
-    if the client is on a remote host (even on a fast LAN).
-
-    This has no effect for (rare) HTTP/0.9 clients.
-
-    Default: false
-
-* client_body_buffer_size INTEGER
-
-    This controls the maximum size of a request body before it is
-    buffered to the filesystem (instead of memory).  This has no effect
-    if input_buffering is false.  This also governs the size of an
-    individual read(2) system call when reading a request body.
-
-    There is generally no need to change this value and this directive
-    may be removed in the future.
-
-    Default: 8192 bytes (8 kilobytes)
-
-* client_header_buffer_size INTEGER
-
-    This controls the size of a single read(2) syscall for reading
-    client request headers.  Increase this as needed if your application
-    uses large cookies or long URLs.  Lowering this may reduce GC and
-    memory allocator overhead.
-
-    Default 4000 bytes
-
-* client_max_body_size {INTEGER|nil}
-
-    This controls the maximum request body size before a client is
-    rejected with an HTTP 413 error.
-
-    Setting this to nil will allow unlimited-sized inputs.
-
-    Default: 1048576 bytes (one megabyte)
-
-* client_timeout SECONDS
-
-    Defines the timeout expiring idle connections.
-
-    If input_buffering is false or :lazy, this defines the maximum
-    amount of time a worker thread will wait synchronously for a client
-    request body.
-
-    If output_buffering is false, this defines the maximm amount of
-    time a worker thread will wait synchronously for a client socket
-    to become writable.
-
-    It makes sense to lower this to a low value (e.g. 5 seconds) if
-    either output or input buffering are disabled.  The default value
-    of 15 seconds is suitable for configurations with both input and
-    output buffering enabled and assumes all application dispatch
-    finishes in less than 15 seconds.
-
-    Default: 15 (seconds)
-
-* errors {IO|PATHNAME}
-
-    For Rack applications, this controls the env["rack.errors"]
-    destination.  If given a PATHNAME, it will be a writable file
-    opened with O_APPEND without userspace buffering, making it suitable
-    for concurrent appends by multiple processes and threads, as well as
-    making it eligible for reopening via SIGUSR1 after log rotation.
-
-    Default: $stderr
-
-* input_buffering {:lazy|true|false}[, OPTIONS]
-
-    This controls buffering of the HTTP request body.
-
-    + true - fully buffers the request before application dispatch.  This is
-      most suitable for slow and untrusted clients which may trickle
-      the request to the server.
-
-    + :lazy - provides streaming, but rewindable input.  This is suitable
-      for fast, trusted clients and is fully-compatible with Rack 1.x
-      specifications.  :lazy buffering may also be suitable for slow and
-      untrusted clients if you are able and willing to run a queue with
-      many worker threads.
-
-    + false - disable input buffering completely.  This violates the
-      Rack 1.x spec and is only suitable for fast, trusted clients or
-      queues with many worker threads.
-
-    HTTP request headers are always buffered in memory.
-
-    Do not be tempted to disable any buffering because it improves
-    numbers on a synthetic benchmark over a fast connection.
-    Slow, real-world clients can easily overwhelm servers without both
-    input and output buffering.
-
-    Default: true
-
-    The following OPTIONS may be specified:
-
-      + tmpdir: DIRECTORY
-
-        Specify an alternative temporary directory of input_buffering is
-        :lazy or true.  This can be used in case the normal temporary
-        directory is too small or busy to be used for input buffering.
-
-        Default: Dir.tmpdir (usually from TMPDIR env or /tmp)
-
-* listen ADDRESS [, OPTIONS]
-
-    Adds an ADDRESS to the existing listener set.  May be specified more
-    than once.  ADDRESS may be an Integer port number for a TCP port, an
-    "IP_ADDRESS:PORT" for TCP listeners or a pathname for UNIX domain sockets.
-
-      listen 3000 # listen to port 3000 on all TCP interfaces
-      listen "127.0.0.1:3000"  # listen to port 3000 on the loopback interface
-      listen "/path/to/.unicorn.sock" # listen on the given Unix domain socket
-      listen "[::1]:3000" # listen to port 3000 on the IPv6 loopback interface
-
-    When using Unix domain sockets, be sure:
-    1) the path matches the one used by nginx
-    2) uses the same filesystem namespace as the nginx process
-    For systemd users using PrivateTmp=true (for either nginx or yahns),
-    this means Unix domain sockets must not be placed in /tmp
-
-    The following OPTIONS may be specified (but are generally not needed):
-
-      + backlog: INTEGER
-
-        This is the backlog of the listen(2) syscall.
-
-        Some operating systems allow negative values here to specify the
-        maximum allowable value.  In most cases, this number is only
-        recommendation and there are other OS-specific tunables and
-        variables that can affect this number.  See the listen(2)
-        syscall documentation of your OS for the exact semantics of
-        this.
-
-        If you are running unicorn on multiple machines, lowering this number
-        can help your load balancer detect when a machine is overloaded
-        and give requests to a different machine.
-
-        Default: 1024
-
-      + ipv6only: BOOLEAN
-
-        This option makes IPv6-capable TCP listeners IPv6-only and unable
-        to receive IPv4 queries on dual-stack systems.  A separate IPv4-only
-        listener is required if this is true.
-
-        Enabling this option for the IPv6-only listener and having a
-        separate IPv4 listener is recommended if you wish to support IPv6
-        on the same TCP port.  Otherwise, the value of env["REMOTE_ADDR"]
-        will appear as an ugly IPv4-mapped-IPv6 address for IPv4 clients
-        (e.g ":ffff:10.0.0.1" instead of just "10.0.0.1").
-
-        Default: Operating-system dependent
-
-      + sndbuf / rcvbuf: INTEGER
-
-        Maximum receive and send buffer sizes (in bytes) of sockets.
-
-        These correspond to the SO_RCVBUF and SO_SNDBUF settings which
-        can be set via the setsockopt(2) syscall.  Some kernels
-        (e.g. Linux 2.4+) have intelligent auto-tuning mechanisms and
-        there is no need (and it is sometimes detrimental) to specify them.
-
-        See the socket API documentation of your operating system
-        to determine the exact semantics of these settings and
-        other operating system-specific knobs where they can be
-        specified.
-
-        Defaults: operating system defaults
-
-      + reuseport: BOOLEAN
-
-        This enables multiple, independently-started yahns instances to
-        bind to the same port (as long as all the processes enable this).
-
-        This option must be used when yahns first binds the listen socket.
-        It cannot be enabled when a socket is inherited via SIGUSR2
-        (but it will remain on if inherited), and it cannot be enabled
-        directly via SIGHUP.
-
-        Note: there is a chance of connections being dropped if
-        one of the yahns instances is stopped while using this.
-
-        This is supported on *BSD systems and Linux 3.9 or later.
-
-        ref: https://lwn.net/Articles/542629/
-
-        Default: false (unset)
-
-      + threads: INTEGER
-
-        Used to control the number of threads blocking on the accept(2)
-        or accept4(2) system call (per listen socket).
-
-        Usually, only one thread here is necessary, especially when
-        multiple worker_processes are configured (as there'll be one
-        thread per-process).  Having extra threads may increase
-        contention with epoll and FD allocation within one process.
-
-        Note: do not confuse this option with worker_threads for queues,
-        each queue has their own thread pool and it makes sense to
-        have multiple threads there.
-
-        Default: 1
-
-      + umask: MODE
-
-        Sets the file mode creation mask for UNIX sockets.  If specified,
-        this is usually in octal notation.
-
-        Typically UNIX domain sockets are created with more liberal
-        file permissions than the rest of the application.  By default,
-        we create UNIX domain sockets to be readable and writable by
-        all local users to give them the same accessibility as
-        locally-bound TCP listeners.
-
-        This has no effect on TCP listeners.
-
-        Default: 0000 (world-read/writable)
-
-* logger LOGGER
-
-    Configures a logger within the current app &BLOCK.
-    This behaves the same as the logger directive described in
-    TOP-LEVEL DIRECTIVES
-
-    Default: uses the top-level logger
-
-* output_buffering BOOLEAN [, OPTIONS]
-
-    This enables or disables buffering of the HTTP response.  If enabled,
-    buffering is only performed lazily.  In other words, buffering only
-    happens if socket buffers (in the kernel) are filled up, and yahns
-    will continously try to flush the buffered data to the socket while
-    it is buffering.
-
-    Disabling output buffering is only recommended if ALL clients
-    connecting to this application context are fast, trusted or
-    you are willing and able to run many worker threads.
-
-    Do not be tempted to disable any buffering because it improves
-    numbers on a synthetic benchmark over a fast connection.
-    Slow, real-world clients can easily overwhelm servers without both
-    input and output buffering.
-
-    If output buffering is disabled, client_timeout controls the maximum
-    amount of time a worker thread will wait synchronously.
-
-    Default: true
-
-    The following OPTIONS may be specified:
-
-      + tmpdir: DIRECTORY
-
-        Specify an alternative temporary directory of output_buffering is
-        enabled.  This can be used in case the normal temporary directory
-        is too small or busy to be used for output buffering.
-
-        Default: Dir.tmpdir (usually from TMPDIR env or /tmp)
-
-* persistent_connections BOOLEAN
-
-    Enable or disables persistent connections and pipelining for HTTP
-    connections.  Persistent connections only expire when the global
-    client_expire_threshold is hit and a client hits its client_timeout.
-
-    Default: true
-
-* user USER [,GROUP]
-
-    Runs application process(es) as the specified USER and GROUP.
-
-    If using worker_processes, this only affects the workers and the
-    master stays running as the user who started it.  This switch will
-    occur before calling the atfork_child hook(s).
-
-    GROUP is optional and will not change if unspecified.
-
-    Default: none (no user switching is done)
-
-* queue [NAME or &BLOCK]
-
-    If given a NAME-only, this will associate this app &BLOCK with an
-    existing queue.
-
-    If given a &BLOCK-only, this will create an anonymous queue for this
-    application context only.  If given a &BLOCK, this takes the same
-    parameters (worker_threads and max_events) as described in
-    QUEUE-LEVEL DIRECTIVES.
-
-    NAME and &BLOCK may not be combined inside an app &BLOCK.
-
-    Default: uses the global, :default queue if none is specified
-
-* shutdown_timeout SECONDS
-
-    This defines the timeout for gracefully exiting the process if there
-    are still connected clients.  This should generally be higher or equal
-    to the app with the highest client_timeout value.
-
-    Increase this if your application has slow endpoints which may take
-    longer than the default timeout.
-
-    Default: max client_timeout value of all apps in the process
-
-* worker_processes INTEGER [&BLOCK]
-
-    This directive allows yahns to use a master/worker configuration to
-    use multiple processes.  Specifying any numeric value (including 1)
-    here means yahns will enable yahns to use a master/worker process
-    model instead of a single process.
-
-    If an optional &BLOCK is given, it may be used to configure
-    pthread_atfork(3)-style hooks.  See WORKER_PROCESSES-LEVEL DIRECTIVES
-    for details.
-
-    Using worker_processes is strongly recommended if your application
-    relies on using a SIGCHLD handler for reaping forked processes.
-    Without worker_processes, yahns must reserve SIGCHLD for rolling
-    back SIGUSR2 upgrades, leading to conflicts if the appplication
-    expects to handle SIGCHLD.
-
-    Default: nil (single process, no master/worker separation)
-
-## WORKER_PROCESSES-LEVEL DIRECTIVES
-
-Note: all of the atfork_* hooks described here are available inside the
-"app" blocks, too.
-
-* atfork_prepare &BLOCK
-
-    This &BLOCK is executed in the parent before fork(2) operation.
-    This may be useful for app directives which specify "preload: true"
-    to disconnect from databases or otherwise close open file descriptors
-    to prevent them from being shared with the children.
-
-    Default: none
-
-* atfork_parent &BLOCK
-
-    This &BLOCK is executed in the parent after the fork(2) operation.
-    This may not be useful, but exists in case somebody finds a use for it.
-
-    Default: none
-
-* atfork_child &BLOCK
-
-    This &BLOCK is executed in the child after the fork(2) operation.
-
-    This may be useful for app directives which specify "preload: true"
-    to reconnect to databases or reopen closed file descriptors which
-    were closed in the atfork_prepare hook.
-
-    Default: none
-
-# RACK APP ARGUMENTS
-
-Rack applications take a PATHNAME to the rackup(1) config file (e.g.
-"config.ru") as its first argument.
-
-The only supported keyword argument is the preload: BOOLEAN.
-
-preload: only makes sense if worker_processes are configured.
-Preloading an app allows memory to be saved under a copy-on-write GC,
-but will often require atfork_* hooks to be registered when configuring
-worker_processes.  preload: defaults to false for maximum out-of-the-box
-compatibility.
-
-## RACK APP EXAMPLE
-
-    app(:rack, "/path/to/config.ru", preload: false) do
-      # APP-BLOCK DIRECTIVES GO HERE
-    end
-
-# EXAMPLES
-
-See the examples/ directory in the git source tree.
-
-    git clone git://yhbt.net/yahns.git
-
-# COPYRIGHT
-
-Copyright (C) 2013-2016 all contributors <yahns-public@yhbt.net>
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-yahns(1)
diff --git a/Rakefile b/Rakefile
index 28172a6..cbf5964 100644
--- a/Rakefile
+++ b/Rakefile
@@ -12,6 +12,8 @@ task rsync_docs: gendocs do
   # Also available at: http://yhbt.net/git-set-file-times
   # on Debian systems: /usr/share/doc/rsync/scripts/git-set-file-times.gz
   sh("git", "set-file-times", "Documentation", "examples", *top)
+  make = ENV['MAKE'] || 'make'
+  sh(%Q(#{make} -C Documentation))
 
   do_gzip = lambda do |txt|
     gz = "#{txt}.gz"
@@ -26,6 +28,9 @@ task rsync_docs: gendocs do
   files = `git ls-files Documentation/*.txt`.split(/\n/)
   files.concat(top)
   files.concat(gendocs)
+  files.concat(%w(yahns yahns-rackup yahns_config).map! { |x|
+    "Documentation/#{x}.txt"
+  })
   gzfiles = files.map { |txt| do_gzip.call(txt) }
   files.concat(gzfiles)