[PATCH] misc doc updates

[PATCH] misc doc updates

[Eric Wong]

Generate pre-formatted HTML which gives us a consistent visual style
with our mailing list archives and enhance linkability.  <a>, <pre>,
and <title> are among the few useful HTML tags I'll use :P

Drop the AUTHORS file, it's pointless maintenance task and users can
just look at git history instead (and honestly, I have zero interest in
recognition; I only use my real name to deter GPL violations).
---
 AUTHORS           |  1 -
 INSTALL           |  5 +++--
 Makefile.am       | 23 +++++++++++++++++------
 Rakefile          |  4 ++++
 build-aux/txt2pre | 43 +++++++++++++++++++++++++++++++++++++++++++
 doc/design.txt    |  2 ++
 6 files changed, 69 insertions(+), 9 deletions(-)
 delete mode 100644 AUTHORS
 create mode 100755 build-aux/txt2pre

diff --git a/AUTHORS b/AUTHORS
deleted file mode 100644
index 53cc6d4..0000000
--- a/AUTHORS
+++ /dev/null
@@ -1 +0,0 @@
-* Eric Wong <normalperson@yhbt.net>
diff --git a/INSTALL b/INSTALL
index f66987c..408c59d 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,6 +1,7 @@
-Standard autotools installation
-*******************************
+cmogstored installation
+***********************
 
+cmogstored uses autotools, so the usual instructions apply:
 After unpacking the tarball:
 
   ./configure && make && make install
diff --git a/Makefile.am b/Makefile.am
index f78ff76..0272608 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -197,9 +197,12 @@ $(top_srcdir)/ChangeLog: configure.ac
 GZIP = gzip
 RSYNC = rsync
 RSYNC_DEST = bogomips.org:/srv/bogomips/cmogstored/
-WWW_DOC = README AUTHORS NEWS.atom.xml INSTALL $(extra_doc)
+HTML_DOC = README INSTALL $(extra_doc) doc/queues.txt doc/design.txt
+WWW_DOC = $(HTML_DOC) NEWS.atom.xml
 NEWS.atom.xml: configure.ac
 	$(AM_V_GEN)$(RAKE) -sq news_atom > $@.$$$$ && mv $@.$$$$ $@
+
+html = $${i%.txt}.html
 publish: NEWS.atom.xml NEWS ChangeLog
 	mkdir -p www/examples/
 # n.b. git set-file-times is non-standard, but distributed with rsync
@@ -207,11 +210,19 @@ publish: NEWS.atom.xml NEWS ChangeLog
 	$(INSTALL_DATA) -p $(addprefix $(top_srcdir)/,$(WWW_DOC)) www/
 	$(INSTALL_DATA) -p $(addprefix $(top_srcdir)/,$(examples)) \
 		www/examples/
-	set -e && cd www && for i in $(WWW_DOC) $(examples); do \
-		$(GZIP) < $$i > $$i.gz; \
-		test -s $$i.gz; \
-		touch -r $$i $$i.gz; \
-	done
+	set -e && cd www && \
+		for i in $(notdir $(WWW_DOC)) $(examples); do \
+			$(GZIP) < $$i > $$i.gz; \
+			test -s $$i.gz; \
+			touch -r $$i $$i.gz; \
+		done && \
+		for i in $(notdir $(HTML_DOC)); do \
+			i=$$(basename $$i); \
+			../build-aux/txt2pre $$i > $(html); \
+			test -s $(html); \
+			$(GZIP) < $(html) > $(html).gz; \
+			touch -r $(html) $(html).gz; \
+		done;
 	$(RSYNC) -av www/ $(RSYNC_DEST)
 
 .PHONY: publish
diff --git a/Rakefile b/Rakefile
index bb1c22a..b214af3 100644
--- a/Rakefile
+++ b/Rakefile
@@ -62,6 +62,10 @@ end
 
 desc 'prints news as a text file'
 task :news do
+  title = "cmogstored news"
+  puts title
+  puts('-' * title.length)
+  puts
   tags.each do |tag|
     time = tag[:time].tr!('T', ' ').gsub!(/:\d\dZ/, ' UTC')
     line = "#{tag[:tag].sub(/^v/, '')} / #{time}"
diff --git a/build-aux/txt2pre b/build-aux/txt2pre
new file mode 100755
index 0000000..bc42952
--- /dev/null
+++ b/build-aux/txt2pre
@@ -0,0 +1,43 @@
+#!/usr/bin/env perl
+# Copyright (C) 2015 all contributors <cmogstored-public@bogomips.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+#
+# Stupid script to make HTML from preformatted, utf-8 text versions,
+# only generating links for http(s).  Markdown does too much
+# and requires indentation to output preformatted text.
+use strict;
+use warnings;
+use CGI qw/escapeHTML/;
+use Encode qw/encode/;
+my $file = shift;
+my $str;
+if (defined $file) {
+	open my $fh, '<', $file or die "failed to open $file: $!\n";
+	local $/;
+	$str = <$fh>;
+} else {
+	$str = eval { local $/; <> };
+}
+
+$str = escapeHTML($str);
+$str = encode('us-ascii', $str, Encode::HTMLCREF);
+my ($title) = ($str =~ /\A([^\n]+)\n[^a-zA-Z]*\n/s);
+
+unless (defined $title) {
+	$title = $file;
+	$title =~ s,\A[^/]*/,,;
+	$title = "cmogstored - $title";
+}
+
+# temporarily swap &gt; for escape so our s!! to add href works.
+# there's probably a way to do this with only a single s!! ...
+$str =~ s!&gt;!\e!g;
+$str =~ s!\b((nntp|ftp|https?)://[\w+\+\&\?\.\%\;/#-]+)!<a
+href="$1"\n>$1</a>!g;
+
+$str =~ s!\e!&gt;!g; # swap escapes back to &gt;
+
+print '<html><head>',
+  '<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />',
+  "<title>$title</title>",
+  "</head><body>\n<pre>",  $str , '</pre></body></html>';
diff --git a/doc/design.txt b/doc/design.txt
index 495e1bf..6a158cb 100644
--- a/doc/design.txt
+++ b/doc/design.txt
@@ -1,3 +1,5 @@
+cmogstored design notes
+
 object relationships
 --------------------
 
-- 
EW