yahns Ruby server user/dev discussion
 help / color / mirror / code / Atom feed
From: Eric Wong <e@80x24.org>
To: yahns-public@yhbt.net
Subject: [PATCH 3/2] doc: various doc and linkification improvements
Date: Sun, 14 Feb 2016 21:33:08 +0000	[thread overview]
Message-ID: <20160214213308.GA27161@dcvr.yhbt.net> (raw)
In-Reply-To: <20160214112856.GA17497@dcvr.yhbt.net>

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


      parent reply	other threads:[~2016-02-14 21:33 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-02-14 11:28 [PUSHED] doc: switch to perlpod (from pandoc-flavored Markdown) Eric Wong
2016-02-14 11:29 ` [PATCH 1/2] doc: trim down documentation slightly Eric Wong
2016-02-14 11:33 ` [PATCH 2/2] doc: document ssl_ctx for "listen" directive Eric Wong
2016-02-14 21:33 ` Eric Wong [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://yhbt.net/yahns/README

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20160214213308.GA27161@dcvr.yhbt.net \
    --to=e@80x24.org \
    --cc=yahns-public@yhbt.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://yhbt.net/yahns.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).