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

[Eric Wong <e@80x24.org>]

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