[PATCH 0/3] Earth Day changes!

[PATCH 0/3] Earth Day changes!

[Eric Wong]

Since most users are on horrible GUI browsers which default
to light backgrounds, implement the "dark216" color scheme
which saves power on OLED and CRT displays.  This still
respects "prefers-color-scheme:light" on newer browsers,
so users can burn their eyes out if they wish :P

While we're at it, switch to perlpod for our own documentation
since Perl5 and POD tooling is more common on most *nix systems
than pandoc.  Finally, update our documentation to avoid the
term "mailing list" because centralized subscriber lists hurt
forkability compared to an "archives first" approach to email.

Eric Wong (3):
  add dark216 color scheme for power savings
  doc: switch to perlpod for documentation
  doc: update wording to avoid "mailing list"

 Documentation/.gitignore                     |  1 +
 Documentation/GNUmakefile                    | 77 ++++++++++++++------
 Documentation/olddoc.1.pod                   | 21 ++++++
 Documentation/olddoc.1.txt                   | 21 ------
 Documentation/{olddoc.5.txt => olddoc.5.pod} | 19 ++---
 Documentation/podtxt2html                    | 54 ++++++++++++++
 GNUmakefile                                  |  2 +-
 README                                       | 27 ++++---
 Rakefile                                     |  2 +-
 lib/dark216.rb                               | 40 ++++++++++
 lib/olddoc.rb                                |  3 +-
 lib/oldweb.rb                                |  1 +
 lib/oldweb/_head.rhtml                       |  6 +-
 13 files changed, 202 insertions(+), 72 deletions(-)
 create mode 100644 Documentation/olddoc.1.pod
 delete mode 100644 Documentation/olddoc.1.txt
 rename Documentation/{olddoc.5.txt => olddoc.5.pod} (77%)
 create mode 100755 Documentation/podtxt2html
 create mode 100644 lib/dark216.rb

-- 
EW

[PATCH 1/3] add dark216 color scheme for power savings

[Eric Wong]

"oldweb" remains for compatibility and we still have minimal styling.

Some browsers (e.g. Firefox 67.0a1 via "ui.systemUsesDarkTheme") are
adding support for the "prefers-color-scheme" @media query.  So this
allows pages to respect user choice when it comes to dark or light
schemes.

OLED and CRT displays measure significant power savings when using
dark schemes.  Dark themes work better with less ambient light, so
favoring darkness can lead to overall power savings even with CCFL
and LED-lit displays.
---
 Documentation/olddoc.1.txt |  4 +++-
 GNUmakefile                |  2 +-
 README                     | 14 +++++++------
 lib/dark216.rb             | 40 ++++++++++++++++++++++++++++++++++++++
 lib/olddoc.rb              |  3 ++-
 lib/oldweb.rb              |  1 +
 lib/oldweb/_head.rhtml     |  6 +++++-
 7 files changed, 60 insertions(+), 10 deletions(-)
 create mode 100644 lib/dark216.rb

diff --git a/Documentation/olddoc.1.txt b/Documentation/olddoc.1.txt
index c294cdb..25bf88b 100644
--- a/Documentation/olddoc.1.txt
+++ b/Documentation/olddoc.1.txt
@@ -10,9 +10,11 @@ olddoc - old-fashioned RDoc HTML generator
 
 `rdoc` -f oldweb
 
+`rdoc` -f dark216
+
 # DESCRIPTION
 
-olddoc features oldweb, and old-fashioned RDoc HTML generator.
+olddoc features dark216, and old-fashioned RDoc HTML generator.
 You can also use "olddoc prepare" to generate NEWS files from
 git tags.
 
diff --git a/GNUmakefile b/GNUmakefile
index 038bc25..1df29ae 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -41,7 +41,7 @@ doc: $(placeholders)
 	$(MAKE) -C Documentation html
 	rm -rf doc
 	olddoc prepare
-	rdoc --debug -f oldweb
+	rdoc --debug -f dark216
 	olddoc merge
 	ln NEWS.atom.xml doc/
 
diff --git a/README b/README
index 4b5aa1f..b9538e7 100644
--- a/README
+++ b/README
@@ -3,15 +3,17 @@
 olddoc contains old-fashioned document generators for those who do not
 wish to impose bloated, new-fangled web cruft on their readers.
 
-olddoc contains oldweb, an HTML generator without any images, frames,
-CSS, or JavaScript.  It is designed for users of text-based browsers
-and/or low-bandwidth connections.  oldweb focuses on text as it is
-the lowest common denominator for accessibility and compatibility
+olddoc contains dark216, a HTML generator without any images, frames,
+or JavaScript.  It is designed for users of text-based browsers
+and/or low-bandwidth connections; yet respects user preference for
+light color schemes in new CSS browsers while favoring darkness for
+power savings on OLED and CRT displays.  dark216 focuses on text as
+it is the lowest common denominator for accessibility and compatibility
 with people and hardware.
 
 == Reasons
 
-* No CSS.  Encouraging users to use CSS leads to problems like
+* No CSS required.  Encouraging users to use CSS leads to problems like
   copy-paste hijacking: https://thejh.net/misc/website-terminal-copy-paste
   External CSS also increases page load time as it often blocks page
   rendering.  Asynchronous loading of CSS also causes accessibility
@@ -38,7 +40,7 @@ missing out!
 
 	gem install olddoc
 	cd $ANY_RDOC_USING_RUBY_PROJECT
-	rdoc -f oldweb
+	rdoc -f dark216
 
 You can also use olddoc to generate NEWS entries
 assuming you have git tags, a README file and .olddoc.yml
diff --git a/lib/dark216.rb b/lib/dark216.rb
new file mode 100644
index 0000000..a01584c
--- /dev/null
+++ b/lib/dark216.rb
@@ -0,0 +1,40 @@
+# Copyright (C) 2019 all contributors <olddoc-public@80x24.org>
+# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
+
+# Loosely derived from Darkfish in the main rdoc distribution
+require_relative 'oldweb'
+
+# dark216 is an \RDoc template and not intended as a programming API.
+# It respect prefers-color-scheme:light on newer browsers with CSS
+# support, but favors darkness for power-savings.
+# You may specify it as an \RDoc formatter:
+#
+#   rdoc -f dark216 ...
+class Dark216 < Oldweb
+  RDoc::RDoc.add_generator(self) # :nodoc:
+  include ERB::Util # :nodoc:
+
+  # description of the generator
+  DESCRIPTION = 'minimal dark HTML generator'
+
+  # default to a dark, web-safe (216 color) palette for power-savings.
+  # Color-capable browsers can respect the prefers-color-scheme:light
+  # @media query (browser support a work-in-progress)
+  STYLE = <<''.gsub(/^\s*/m, '').delete!("\n") # :nodoc:
+@media screen {
+  *{background:#000;color:#ccc}
+  a{color:#69f}
+  a:visited{color:#96f}
+}
+@media screen AND (prefers-color-scheme:light) {
+  *{background:#fff;color:#333}
+  a{color:#00f}
+  a:visited{color:#808}
+}
+
+  def initialize(*args) # :nodoc:
+    super
+    @oldweb_style = STYLE
+  end
+end
+# :startdoc:
diff --git a/lib/olddoc.rb b/lib/olddoc.rb
index 3061e73..d5d6b37 100644
--- a/lib/olddoc.rb
+++ b/lib/olddoc.rb
@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
+# Copyright (C) 2015-2019 all contributors <olddoc-public@80x24.org>
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 module Olddoc # :nodoc:
   autoload :Gemspec, 'olddoc/gemspec'
@@ -16,3 +16,4 @@ module Olddoc # :nodoc:
   end
 end
 require_relative 'oldweb'
+require_relative 'dark216'
diff --git a/lib/oldweb.rb b/lib/oldweb.rb
index ccc37f7..5b55019 100644
--- a/lib/oldweb.rb
+++ b/lib/oldweb.rb
@@ -91,6 +91,7 @@ class Oldweb
       cgit_url << '#n%d' # lineno
       @old_vcs_url = cgit_url
     end
+    @oldweb_style = nil # used by dark216
   end
 
   def generate # :nodoc:
diff --git a/lib/oldweb/_head.rhtml b/lib/oldweb/_head.rhtml
index 720fd95..15a428e 100644
--- a/lib/oldweb/_head.rhtml
+++ b/lib/oldweb/_head.rhtml
@@ -8,4 +8,8 @@ type="application/atom+xml" /><%
 end
 %><meta
 http-equiv="Content-Type"
-content="text/html; charset=<%= @options.charset %>">
+content="text/html; charset=<%= @options.charset %>"><%
+if @oldweb_style
+%><style><%= @oldweb_style %></style><%
+end
+%>
-- 
EW

[PATCH 2/3] doc: switch to perlpod for documentation

[Eric Wong]

Perl5 and POD tools is installed on far more *nix-like systems
than Haskell or pandoc.  Furthermore, POD is better-specified for
generating manpages than the particular flavor of Markdown used
by pandoc.

podtxt2html was written to maintain anchor compatibility.
---
 Documentation/.gitignore                     |  1 +
 Documentation/GNUmakefile                    | 77 ++++++++++++++------
 Documentation/{olddoc.1.txt => olddoc.1.pod} | 18 ++---
 Documentation/{olddoc.5.txt => olddoc.5.pod} | 14 ++--
 Documentation/podtxt2html                    | 54 ++++++++++++++
 Rakefile                                     |  2 +-
 6 files changed, 123 insertions(+), 43 deletions(-)
 rename Documentation/{olddoc.1.txt => olddoc.1.pod} (57%)
 rename Documentation/{olddoc.5.txt => olddoc.5.pod} (90%)
 create mode 100755 Documentation/podtxt2html

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index c618f1a..356a4ba 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -2,3 +2,4 @@
 *.1
 *.5
 *.html
+*.txt
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 0de5043..2d6475b 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -1,26 +1,32 @@
-# Copyright (C) 2015-2016 all contributors <olddoc-public@80x24.org>
+# Copyright (C) 2015-2019 all contributors <olddoc-public@80x24.org>
 # License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
 all::
 
 INSTALL = install
-PANDOC = pandoc
-PANDOC_OPTS = -f markdown --email-obfuscation=none
-pandoc = $(PANDOC) $(PANDOC_OPTS)
-pandoc_html = $(pandoc) --toc -t html --no-wrap
+POD2MAN = pod2man
+-include ../GIT-VERSION-FILE
+release := olddoc $(VERSION)
+POD2MAN_OPTS = -v -r '$(release)' --stderr -d 1994-10-02 -c 'olddoc user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
 
+m1 =
+m1 += olddoc.1
 
-man1 := olddoc.1
-man5 := olddoc.5
-man7 :=
+m5 =
+m5 += olddoc.5
 
-html1 := $(addsuffix .html, $(man1))
-html5 := $(addsuffix .html, $(man5))
-html7 := $(addsuffix .html, $(man7))
+m7 =
+
+man1 := $(m1)
+man5 := $(m5)
+man7 := $(m7)
 
 all:: man
 
 man: $(man1) $(man5) $(man7)
-html: $(html1) $(html5) $(html7)
 
 prefix ?= $(HOME)
 mandir ?= $(prefix)/share/man
@@ -30,24 +36,47 @@ man7dir = $(mandir)/man7
 
 gem-man: man
 	$(INSTALL) -d -m 755 ../man
-	test -z "$(man1)" || $(INSTALL) -m 644 $(man1) ../man
-	test -z "$(man5)" || $(INSTALL) -m 644 $(man5) ../man
+	$(INSTALL) -m 644 $(man1) ../man
+	$(INSTALL) -m 644 $(man5) ../man
 	test -z "$(man7)" || $(INSTALL) -m 644 $(man7) ../man
 
 install-man: man
-	$(INSTALL) -d -m 755 $(DESTDIR)$(mandir)
-	test -z "$(man1)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
-	test -z "$(man5)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
 	test -z "$(man7)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
-	test -z "$(man1)" || $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
-	test -z "$(man5)" || $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
+	$(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
+	$(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
 	test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
 
-%: %.txt
-	$(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+%.1 : %.1.pod
+	$(pod2man) -s 1 $< $@+
+	mv $@+ $@
+
+%.5 : %.5.pod
+	$(pod2man) -s 5 $< $@+
+	mv $@+ $@
+
+%.7 : %.7.pod
+	$(pod2man) -s 7 $< $@+
+	mv $@+ $@
+
+mantxt = $(addsuffix .txt, $(m1) $(m5) $(m7))
+
+txt :: $(mantxt)
+
+all :: txt
+
+%.txt : %.pod
+	$(pod2text) $< $@+
+	touch -r $< $@+
+	mv $@+ $@
 
-%.html : %.txt
-	$(pandoc_html) < $< > $@+ && mv $@+ $@
+html : podtxt2html $(mantxt)
+	./podtxt2html $(mantxt)
 
 clean::
-	$(RM) $(man1) $(man5) $(man7) $(html1) $(html5) $(html7)
+	$(RM) $(man1) $(man5) $(man7)
+	$(RM) $(addsuffix .txt.gz, $(m1) $(m5) $(m7))
+	$(RM) $(addsuffix .txt, $(m1) $(m5) $(m7))
+	$(RM) $(addsuffix .html, $(subst .,_,$(m1) $(m5) $(m7)))
+	$(RM) $(addsuffix .html.gz, $(subst .,_,$(m1) $(m5) $(m7)))
diff --git a/Documentation/olddoc.1.txt b/Documentation/olddoc.1.pod
similarity index 57%
rename from Documentation/olddoc.1.txt
rename to Documentation/olddoc.1.pod
index 25bf88b..9d57da1 100644
--- a/Documentation/olddoc.1.txt
+++ b/Documentation/olddoc.1.pod
@@ -1,23 +1,21 @@
-% olddoc(1) olddoc user manual
-
-# NAME
+=head1 NAME
 
 olddoc - old-fashioned RDoc HTML generator
 
-# SYNOPSIS
+=head1 SYNOPSYS
 
-`olddoc` prepare
+olddoc prepare
 
-`rdoc` -f oldweb
+rdoc -f oldweb
 
-`rdoc` -f dark216
+rdoc -f dark216
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 olddoc features dark216, and old-fashioned RDoc HTML generator.
 You can also use "olddoc prepare" to generate NEWS files from
 git tags.
 
-# SEE ALSO
+=head1 SEE ALSO
 
-olddoc(5)
+L<olddoc(5)>
diff --git a/Documentation/olddoc.5.txt b/Documentation/olddoc.5.pod
similarity index 90%
rename from Documentation/olddoc.5.txt
rename to Documentation/olddoc.5.pod
index 8274330..bda770f 100644
--- a/Documentation/olddoc.5.txt
+++ b/Documentation/olddoc.5.pod
@@ -1,19 +1,17 @@
-% olddoc(1) olddoc user manual
-
-# NAME
+=head1 NAME
 
 .olddoc.yml - olddoc config file format
 
-# SYNOPSIS
+=head1 SYNOPSIS
 
 A YAML file in the top-level project directory named ".olddoc.yml"
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 As olddoc favors consistency over configuration, there is minimal
 configuration to deal with.
 
-# KEYS
+=head1 KEYS
 
 `rdoc_url`, `cgit_url`, and `nntp_url` should be obvious
 
@@ -33,6 +31,6 @@ commands or URLs.  This allows users of arbitrary version
 control systems to specify instructions for getting the code
 and not assume users are familiar with any particular system.
 
-# SEE ALSO
+=head1 SEE ALSO
 
-olddoc(1)
+L<olddoc(1)>
diff --git a/Documentation/podtxt2html b/Documentation/podtxt2html
new file mode 100755
index 0000000..03c45b5
--- /dev/null
+++ b/Documentation/podtxt2html
@@ -0,0 +1,54 @@
+#!/usr/bin/ruby
+# Copyright (C) 2019 all contributors <olddoc-public@80x24.org>
+# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
+
+# pod2html isn't to my liking, and we need to generate anchors
+# compatible with what pandoc was generating to avoid breaking
+# links.  Takes pod2text-generated text and transforms it to
+# an HTML fragment
+
+txts = ARGV
+links = {}
+txts.each do |f|
+  if f =~ /(\A[\w\-]+)\.(\d)\.txt\z/
+    base = $1
+    section = $2
+    links["#{base}(#{section})"] = "#{base}_#{section}.html"
+  else
+    abort "#{f} is not of <BASE>.<SECTION>.txt\n"
+  end
+end
+
+linkre = links.keys.map { |x| Regexp.escape(x) }.join('|')
+
+sections = '[A-Z][A-Z ]+'
+txts.each do |f|
+  str = File.read(f)
+  str = str.split(/^(#{sections})$/mo)
+  str = str.map! do |s|
+    case s
+    when /\A(#{sections})$/o
+      # this is to be compatible with HTML fragments pandoc used
+      sec = $1
+      anchor = sec.downcase.tr(' ', '-')
+      %Q(<h1\nid=#{anchor}>#{sec}</h1>)
+    else
+      s.encode!(xml: :text)
+      s.gsub!(/\b(#{linkre})/mo) do |m|
+        manref = $1
+        if url = links[manref]
+          %Q(<a\nhref="#{url}">#{manref}</a>)
+        else
+          manref
+        end
+      end
+      s.rstrip!
+      s.empty? ? '' : "<pre>#{s}</pre>"
+    end # case s
+  end.join
+
+  html = f.sub(/.txt\z/, '.html')
+  tmp = html + '+'
+  File.open(tmp, 'w') { |f| f.write(str) }
+  File.rename(tmp, html)
+end
diff --git a/Rakefile b/Rakefile
index aaba8cb..3a32e47 100644
--- a/Rakefile
+++ b/Rakefile
@@ -21,7 +21,7 @@ task :rsync_docs do
     gz
   end
 
-  files = `git ls-files Documentation/*.txt`.split(/\n/)
+  files = `git ls-files -o Documentation/*.txt`.split(/\n/)
   files.concat(top)
   files.concat(%w(NEWS NEWS.atom.xml))
   files.concat(Dir["doc/*.html"].to_a)
-- 
EW

[PATCH 3/3] doc: update wording to avoid "mailing list"

[Eric Wong]

The concept of a "mailing list" infers the existence of a
centralized subscriber list, and hurts forkability.  Mail
archives are easily forkable, subscriber lists are not.
---
 Documentation/olddoc.5.pod |  5 ++---
 README                     | 13 +++++++------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/olddoc.5.pod b/Documentation/olddoc.5.pod
index bda770f..6e03e3a 100644
--- a/Documentation/olddoc.5.pod
+++ b/Documentation/olddoc.5.pod
@@ -19,9 +19,8 @@ configuration to deal with.
 HTML file that will be merged into RDoc after-the-fact.  It is useful
 for merging non-RDoc generated HTML into the project.
 
-`ml_url` is the mailing list archive location.
-`public_email` is the email address of a publically archived mailing list
-at `ml_url`
+`ml_url` is the mail archive location.
+`public_email` is the email address of a mail archived at `ml_url`
 
 As of olddoc 1.2.0, `ml_url` and `nntp_url` may be YAML arrays
 with multiple URLs.
diff --git a/README b/README
index b9538e7..e902589 100644
--- a/README
+++ b/README
@@ -64,14 +64,15 @@ with git(7)) and send them via email to <olddoc-public@80x24.org>
 == Contact
 
 All feedback (comments, results, feature requests, bug reports, patches,
-pull-requests) via plain-text mail to the mailing list is very much
-appreciated.
+pull-requests) via plain-text email is very much appreciated.
 
-Please send plain-text mail to the list at <olddoc-public@80x24.org>
+Please send plain-text email to us at <olddoc-public@80x24.org>
+Use reply-to-all as we do not require any sort of subscription.
 HTML will not be read.  olddoc is for GUI-phobes, by GUI-phobes.
-Mailing list archives available at https://80x24.org/olddoc-public/
-and nntp://news.public-inbox.org/inbox.comp.lang.ruby.olddoc
-No subscription will ever be necessary to post to the mailing list.
+We archive all of our mail publically at:
+
+	https://80x24.org/olddoc-public/
+	nntp://news.public-inbox.org/inbox.comp.lang.ruby.olddoc
 
 == License
 
-- 
EW