From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-2.8 required=3.0 tests=ALL_TRUSTED,AWL,BAYES_00, URIBL_BLOCKED shortcircuit=no autolearn=unavailable version=3.3.2 X-Original-To: yahns-public@yhbt.net Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 637F3633811; Sun, 14 Feb 2016 21:33:08 +0000 (UTC) Date: Sun, 14 Feb 2016 21:33:08 +0000 From: Eric Wong To: yahns-public@yhbt.net Subject: [PATCH 3/2] doc: various doc and linkification improvements Message-ID: <20160214213308.GA27161@dcvr.yhbt.net> References: <20160214112856.GA17497@dcvr.yhbt.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20160214112856.GA17497@dcvr.yhbt.net> List-Id: 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 and other Rack launchers, it uses the -*Rack::Builder* DSL. +*Rack::Builder* DSL documented at: + +L =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 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 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 +All feedback welcome via plain-text mail to L No subscription is necessary to post to the mailing list. +List archives are available at L =head1 COPYRIGHT @@ -171,6 +172,7 @@ License: GPL-3.0+ L =head1 SEE ALSO -L, L, *Rack::Builder* ri/RDoc, +L, L, +L, L, -L +L 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 for documentation on the configuration file format. All feedback welcome via plain-text mail to L No subscription is necessary to post to the mailing list. +Mail archives are available at L =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 @@ -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 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 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 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 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 +No subscription is necessary to post to the mailing list. +List archives are available at L + =head1 COPYRIGHT Copyright (C) 2013-2016 all contributors L 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