[PUSHED] doc: switch to perlpod (from pandoc-flavored Markdown)

[PUSHED] doc: switch to perlpod (from pandoc-flavored Markdown)

[Eric Wong]

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.
---
 Documentation/.gitignore       |   3 +
 Documentation/GNUmakefile      |  27 +-
 Documentation/yahns-rackup.pod | 176 +++++++++++
 Documentation/yahns-rackup.txt | 152 ----------
 Documentation/yahns.pod        |  97 +++++++
 Documentation/yahns.txt        |  72 -----
 Documentation/yahns_config.pod | 641 +++++++++++++++++++++++++++++++++++++++++
 Documentation/yahns_config.txt | 584 -------------------------------------
 Rakefile                       |   5 +
 9 files changed, 945 insertions(+), 812 deletions(-)
 create mode 100644 Documentation/yahns-rackup.pod
 delete mode 100644 Documentation/yahns-rackup.txt
 create mode 100644 Documentation/yahns.pod
 delete mode 100644 Documentation/yahns.txt
 create mode 100644 Documentation/yahns_config.pod
 delete mode 100644 Documentation/yahns_config.txt

<snip>  Big indentation changes necessary, so it breaks
rename detection.  Full patch here:

	http://yhbt.net/yahns.git/patch?id=4ef59c7e5e49

[PATCH 1/2] doc: trim down documentation slightly

[Eric Wong]

The "threads:" option for the "listen" directive is worthless.
Having a dedicated thread per-process is already more than enough
(and ideal) for a multi-process setup.  Multiple acceptor threads
is still wrong for a single-process setup (even if we did not
have a GVL) as it still incurs contention with the worker
pool within the kernel.

So remove the documentation regarding "listen ... threads: ",
for now; at least until somebody can prove it's useful and not
taking up space.

Additionally, "atfork_parent" may be useful for restarting
background threads/connections if somebody wants to run
background jobs in the master process, so stop saying
it's completely useless.
---
 Documentation/yahns_config.pod    | 17 -----------------
 examples/yahns_rack_basic.conf.rb |  2 +-
 test/test_server.rb               |  8 ++++----
 3 files changed, 5 insertions(+), 22 deletions(-)

diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index ff04cb3..12ec75e 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -422,22 +422,6 @@ 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,
@@ -584,7 +568,6 @@ 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
 
diff --git a/examples/yahns_rack_basic.conf.rb b/examples/yahns_rack_basic.conf.rb
index 12bbc99..33ba619 100644
--- a/examples/yahns_rack_basic.conf.rb
+++ b/examples/yahns_rack_basic.conf.rb
@@ -16,7 +16,7 @@
     puts "#$$ yahns parent about to spawn"
   end
   atfork_parent do
-    puts "#$$ this is probably not useful"
+    puts "#$$ yahns parent done spawning"
   end
 end
 
diff --git a/test/test_server.rb b/test/test_server.rb
index 65a6ea1..87193e3 100644
--- a/test/test_server.rb
+++ b/test/test_server.rb
@@ -428,7 +428,7 @@ def test_mp_hooks
         worker_processes(1) do
           atfork_child { puts "af #$$ worker is running" }
           atfork_prepare { puts "af #$$ parent about to spawn" }
-          atfork_parent { puts "af #$$ this is probably not useful" }
+          atfork_parent { puts "af #$$ parent done spawning" }
         end
       }
       stderr_path err.path
@@ -457,7 +457,7 @@ def test_mp_hooks
     assert_equal("af #{pid} parent about to spawn", lines.shift)
 
     # child/parent ordering is not guaranteed
-    assert_equal 1, lines.grep(/\Aaf #{pid} this is probably not useful\z/).size
+    assert_equal 1, lines.grep(/\Aaf #{pid} parent done spawning\z/).size
     assert_equal 1, lines.grep(/\Aaf #{worker_pid} worker is running\z/).size
   ensure
     quit_wait(master_pid)
@@ -479,7 +479,7 @@ def test_mp_hooks_worker_nr
         worker_processes(1) do
           atfork_child { |nr| puts "af.#{nr} #$$ worker is running" }
           atfork_prepare { |nr| puts "af.#{nr} #$$ parent about to spawn" }
-          atfork_parent { |nr| puts "af.#{nr} #$$ this is probably not useful" }
+          atfork_parent { |nr| puts "af.#{nr} #$$ parent done spawning" }
         end
       }
       stderr_path err.path
@@ -503,7 +503,7 @@ def test_mp_hooks_worker_nr
 
     # child/parent ordering is not guaranteed
     assert_equal 1,
-        lines.grep(/\Aaf\.0 #{pid} this is probably not useful\z/).size
+        lines.grep(/\Aaf\.0 #{pid} parent done spawning\z/).size
     assert_equal 1,
         lines.grep(/\Aaf\.0 #{worker_pid} worker is running\z/).size
   ensure
-- 
EW

[PATCH 2/2] doc: document ssl_ctx for "listen" directive

[Eric Wong]

With the advent of Let's Encrypt, we'll see more users
interested in using yahns with OpenSSL support.
So document how a listener may be passed an SSLContext.
---
 Documentation/yahns_config.pod | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index 12ec75e..858aaf1 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -422,6 +422,37 @@ ref: https://lwn.net/Articles/542629/
 
 Default: false (unset)
 
+=item ssl_ctx: OpenSSL::SSL::SSLContext Ruby object
+
+To enable TLS connections, you must configure this yourself.
+See documentation for OpenSSL::SSL::SSLContext
+for more information:
+
+L<http://docs.ruby-lang.org/en/trunk/OpenSSL/SSL/SSLContext.html>
+
+Default: none
+
+An example which seems to work is:
+
+  require 'openssl'
+  ctx = OpenSSL::SSL::SSLContext.new
+  ctx.cert =
+    OpenSSL::X509::Certificate.new(
+      IO.read('/etc/ssl/certs/example.crt')
+    )
+  ctx.extra_chain_cert = [
+    OpenSSL::X509::Certificate.new(
+      IO.read('/etc/ssl/certs/chain.crt')
+    )
+  ]
+  ctx.key = OpenSSL::PKey::RSA.new(
+    IO.read('/etc/ssl/private/example.key')
+  )
+
+  app(:rack, "/path/to/my/app/config.ru") do
+    listen 443, ssl_ctx: ctx
+  end
+
 =item umask: MODE
 
 Sets the file mode creation mask for UNIX sockets.  If specified,
-- 
EW

[PATCH 3/2] doc: various doc and linkification improvements

[Eric Wong]

Correctly link to subsections within the same page, and include
a link to mailing list archives.

Also, use "ssl_ctx" consistently as a local variable as
we internally use "ctx" for other purposes.
---
 Documentation/yahns-rackup.pod    | 18 ++++++++++--------
 Documentation/yahns.pod           |  3 +--
 Documentation/yahns_config.pod    | 31 +++++++++++++++++--------------
 examples/yahns_rack_basic.conf.rb |  7 ++++++-
 4 files changed, 34 insertions(+), 25 deletions(-)

diff --git a/Documentation/yahns-rackup.pod b/Documentation/yahns-rackup.pod
index fc724e6..efdfb6d 100644
--- a/Documentation/yahns-rackup.pod
+++ b/Documentation/yahns-rackup.pod
@@ -1,5 +1,3 @@
-% yahns-rackup(1) yahns user manual
-
 =head1 NAME
 
 yahns-rackup - a rackup-like command to launch yahns
@@ -17,7 +15,9 @@ It is expected to start in your application root (APP_ROOT).
 
 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.
+*Rack::Builder* DSL documented at:
+
+L<http://www.rubydoc.info/github/rack/rack/Rack/Builder>
 
 =head1 YAHNS OPTIONS
 
@@ -90,7 +90,7 @@ also be redirected to "/dev/null".
 
 =item -E, --env RACK_ENV
 
-Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+Run under the given RACK_ENV.  See the L</RACK ENVIRONMENT> section
 for more details.
 
 =item -o, --host HOST
@@ -107,7 +107,7 @@ use of "-l"/"--listen" switch is recommended instead.
 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,
+This option only exists for compatibility with the L<rackup(1)> command,
 use of "-l"/"--listen" switch is recommended instead.
 
 =back
@@ -161,8 +161,9 @@ See rackup documentation for more details.
 
 =head1 CONTACT
 
-All feedback welcome via plain-text mail to L<yahns-public@yhbt.net>
+All feedback welcome via plain-text mail to L<mailto:yahns-public@yhbt.net>
 No subscription is necessary to post to the mailing list.
+List archives are available at L<http://yhbt.net/yahns-public/>
 
 =head1 COPYRIGHT
 
@@ -171,6 +172,7 @@ 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<yahns(1)>, L<yahns_config(5)>,
+L<Rack::Builder RDoc|http://www.rubydoc.info/github/rack/rack/Rack/Builder>,
 L<Rack RDoc|http://www.rubydoc.info/github/rack/rack/>,
-L<Rackup HowTo|https://wiki.github.com/rack/rack/tutorial-rackup-howto>
+L<Rackup HowTo|https://github.com/rack/rack/wiki/tutorial-rackup-howto>
diff --git a/Documentation/yahns.pod b/Documentation/yahns.pod
index bad468e..dc21638 100644
--- a/Documentation/yahns.pod
+++ b/Documentation/yahns.pod
@@ -1,5 +1,3 @@
-% yahns(1) yahns user manual
-
 =head1 NAME
 
 yahns - multi-threaded, non-blocking application server for Ruby
@@ -86,6 +84,7 @@ See L<yahns_config(5)> for documentation on the configuration file format.
 
 All feedback welcome via plain-text mail to L<mailto:yahns-public@yhbt.net>
 No subscription is necessary to post to the mailing list.
+Mail archives are available at L<http://yhbt.net/yahns-public/>
 
 =head1 COPYRIGHT
 
diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index 858aaf1..cc1ea71 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -1,5 +1,3 @@
-% yahns_config(5) yahns user manual
-
 =head1 NAME
 
 yahns_config - configuration file description for L<yahns(1)>
@@ -28,7 +26,7 @@ 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
+See the L</APP-LEVEL DIRECTIVES> section for details on what goes into
 the &BLOCK.
 
 This directive may be specified multiple times for different or
@@ -37,7 +35,7 @@ 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
+For Rack HTTP applications, see L</RACK APP ARGUMENTS> for more
 information.
 
 =item before_exec &BLOCK
@@ -104,7 +102,7 @@ Default: none
 
 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.
+assumed.  See the L</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
@@ -418,7 +416,7 @@ 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/
+ref: L<https://lwn.net/Articles/542629/>
 
 Default: false (unset)
 
@@ -435,22 +433,21 @@ Default: none
 An example which seems to work is:
 
   require 'openssl'
-  ctx = OpenSSL::SSL::SSLContext.new
-  ctx.cert =
-    OpenSSL::X509::Certificate.new(
-      IO.read('/etc/ssl/certs/example.crt')
-    )
-  ctx.extra_chain_cert = [
+  ssl_ctx = OpenSSL::SSL::SSLContext.new
+  ssl_ctx.cert = OpenSSL::X509::Certificate.new(
+    IO.read('/etc/ssl/certs/example.crt')
+  )
+  ssl_ctx.extra_chain_cert = [
     OpenSSL::X509::Certificate.new(
       IO.read('/etc/ssl/certs/chain.crt')
     )
   ]
-  ctx.key = OpenSSL::PKey::RSA.new(
+  ssl_ctx.key = OpenSSL::PKey::RSA.new(
     IO.read('/etc/ssl/private/example.key')
   )
 
   app(:rack, "/path/to/my/app/config.ru") do
-    listen 443, ssl_ctx: ctx
+    listen 443, ssl_ctx: ssl_ctx
   end
 
 =item umask: MODE
@@ -645,6 +642,12 @@ See the examples/ directory in the git source tree.
 
   git clone git://yhbt.net/yahns.git
 
+=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.
+List archives are available at L<http://yhbt.net/yahns-public/>
+
 =head1 COPYRIGHT
 
 Copyright (C) 2013-2016 all contributors L<mailto:yahns-public@yhbt.net>
diff --git a/examples/yahns_rack_basic.conf.rb b/examples/yahns_rack_basic.conf.rb
index 33ba619..f3f8e6a 100644
--- a/examples/yahns_rack_basic.conf.rb
+++ b/examples/yahns_rack_basic.conf.rb
@@ -31,7 +31,12 @@
 end
 
 app(:rack, "config.ru", preload: false) do
-  listen 8080
+  listen 80
+
+  # See yahns_config(5) and OpenSSL::SSL::SSLContext on configuring
+  # HTTPS support
+  # listen 443, ssl_ctx: ...
+
   client_max_body_size 1024 * 1024
   input_buffering true
   output_buffering true # this lazy by default
-- 
EW