[PATCH] doc: various updates ahead of release

[PATCH] doc: various updates ahead of release

[Eric Wong]

Our mail provider has POP3 support, nowadays, and we need to
more strongly discourage the use of kgio.
---
 .olddoc.yml  |  3 +++
 ISSUES       | 21 +++++++++++++--------
 README       | 19 ++++++++++---------
 kgio.gemspec | 12 ++++--------
 4 files changed, 30 insertions(+), 25 deletions(-)

diff --git a/.olddoc.yml b/.olddoc.yml
index 6d355f5..9319cfe 100644
--- a/.olddoc.yml
+++ b/.olddoc.yml
@@ -11,6 +11,9 @@ noindex:
 nntp_url:
 - nntp://news.public-inbox.org/inbox.comp.lang.ruby.kgio
 - nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.kgio
+imap_url:
+- imaps://;AUTH=ANONYMOUS@yhbt.net/inbox.comp.lang.ruby.kgio.0
+- imap://;AUTH=ANONYMOUS@7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.kgio.0
 source_code:
 - git clone https://yhbt.net/kgio.git
 - torsocks git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/kgio.git
diff --git a/ISSUES b/ISSUES
index c26364f..8cbb624 100644
--- a/ISSUES
+++ b/ISSUES
@@ -1,13 +1,14 @@
 = Issues
 
-The kgio {mailing list}[mailto:kgio-public@yhbt.net] is the best
+The kgio {public mailbox}[mailto:kgio-public@yhbt.net] is the best
 place to report bugs, submit patches and/or obtain support after you
-have searched the mailing list archives at https://yhbt.net/kgio-public/
+have searched the mail archives at https://yhbt.net/kgio-public/
 and {documentation}[https://yhbt.net/kgio/].
 
 * Do not {top post}[http://catb.org/jargon/html/T/top-post.html] in replies
 * Quote only the relevant portions of the message you're replying to
-* Do not send any HTML mail at all
+* Do not send HTML mail, it's too expensive for our spam filters and
+  slow hardware
 
 If you don't get a response within a few days, we may have forgotten
 about it so feel free to ask again.
@@ -18,12 +19,16 @@ See the HACKING document (and additionally, the
 Documentation/SubmittingPatches document distributed with git) on
 guidelines for patch submission.
 
-== Mailing List Info
+== Public Mailbox Info:
 
-* subscribe: mailto:kgio-public+subscribe@yhbt.net
-* post: mailto:kgio-public@yhbt.net
+* post (plain-text only): mailto:kgio-public@yhbt.net
 
-== Mailing List Archives
+Subscription is strongly discouraged to avoid our SMTP server being a
+single point of failure.
 
-* https://yhbt.net/kgio-public/
+Mail archives can be mirrored using NNTP(S), IMAP(S), POP3(S);
+they can also be mirrored using git + HTTP(S):
+
+* git clone --mirror https://yhbt.net/kgio-public/
+* https://yhbt.net/kgio-public/_/text/mirror/#pop3
 * nntp://news.public-inbox.org/inbox.comp.lang.ruby.kgio
diff --git a/README b/README
index 0aedaf0..d3d1c07 100644
--- a/README
+++ b/README
@@ -1,9 +1,10 @@
-= kgio - kinder, gentler I/O for Ruby
+= kgio - a legacy I/O library that did a decade of damage to Ruby
 
-This is a legacy project, do not use it for new projects.  Ruby
-2.3 and later should make this obsolete.  kgio provides
-non-blocking I/O methods for Ruby without raising exceptions on
-EAGAIN and EINPROGRESS.
+This is a legacy project has discouraged improvements to Ruby itself.
+It has done a decade of harm to Ruby and continues to harm it by being
+used by (unfortunately) popular projects.  Ruby 2.3 and later makes
+this obsolete.  kgio provides non-blocking I/O methods for Ruby without
+raising exceptions on EAGAIN and EINPROGRESS.
 
 == Features
 
@@ -39,8 +40,8 @@ You may install it via RubyGems.org:
 You can get the latest source via git from the following locations
 (these versions may not be stable):
 
-  git://yhbt.net/kgio.git
-  git://repo.or.cz/kgio.git (mirror)
+  git clone https://yhbt.net/kgio.git
+  git clone https://repo.or.cz/kgio.git # mirror
 
 You may browse the code from the web and download the latest snapshot
 tarballs here:
@@ -54,8 +55,8 @@ from git.
 == Contact
 
 All feedback (bug reports, user/development dicussion, patches, pull
-requests) go to the mailing list/newsgroup.  See the ISSUES document for
-information on the {kgio mailing list}[mailto:kgio-public@yhbt.net]
+requests) go to the public mailbox/newsgroup.  See the ISSUES document for
+information on the {kgio public mailbox}[mailto:kgio-public@yhbt.net]
 
 For the latest on kgio releases, you may check our NEWS page (and
 subscribe to our Atom feed).
diff --git a/kgio.gemspec b/kgio.gemspec
index 8c15bd3..1c3f26a 100644
--- a/kgio.gemspec
+++ b/kgio.gemspec
@@ -3,21 +3,17 @@ manifest = File.readlines('.manifest').map! { |x| x.chomp! }
 
 Gem::Specification.new do |s|
   s.name = %q{kgio}
-  s.version = ENV["VERSION"].dup
+  s.version = (ENV["VERSION"] || '2.11.4').dup
   s.homepage = 'https://yhbt.net/kgio/'
   s.authors = ['kgio hackers']
-  s.description = <<EOF
-This is a legacy project, do not use it for new projects.  Ruby
-2.3 and later should make this obsolete.  kgio provides
-non-blocking I/O methods for Ruby without raising exceptions on
-EAGAIN and EINPROGRESS.
-EOF
+  summary, desc = *(File.read('README').split("\n\n"))
+  s.description = desc.strip
   s.email = %q{kgio-public@yhbt.net}
   s.extra_rdoc_files = IO.readlines('.document').map!(&:chomp!).keep_if do |f|
     File.exist?(f)
   end
   s.files = manifest
-  s.summary = 'kinder, gentler I/O for Ruby'
+  s.summary = summary.sub(/\A[^-]+ - /, '').strip
   s.test_files = Dir['test/test_*.rb']
   s.extensions = %w(ext/kgio/extconf.rb)