olddoc user/dev discussion/patches/bugs/etc
 help / color / mirror / code / Atom feed
From: Eric Wong <e@80x24.org>
To: <olddoc-public@80x24.org>
Subject: [PATCH 2/3] doc: switch to perlpod for documentation
Date: Mon, 22 Apr 2019 01:49:05 +0000	[thread overview]
Message-ID: <20190422014906.4253-3-e@80x24.org> (raw)
In-Reply-To: <20190422014906.4253-1-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


  parent reply	other threads:[~2019-04-22  1:49 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-04-22  1:49 [PATCH 0/3] Earth Day changes! Eric Wong
2019-04-22  1:49 ` [PATCH 1/3] add dark216 color scheme for power savings Eric Wong
2019-04-22  1:49 ` Eric Wong [this message]
2019-04-22  1:49 ` [PATCH 3/3] doc: update wording to avoid "mailing list" Eric Wong

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://80x24.org/olddoc/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190422014906.4253-3-e@80x24.org \
    --to=e@80x24.org \
    --cc=olddoc-public@80x24.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/olddoc.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).