From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00 shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 0BF6320379 for ; Mon, 22 Apr 2019 01:49:07 +0000 (UTC) From: Eric Wong To: Subject: [PATCH 2/3] doc: switch to perlpod for documentation Date: Mon, 22 Apr 2019 01:49:05 +0000 Message-Id: <20190422014906.4253-3-e@80x24.org> In-Reply-To: <20190422014906.4253-1-e@80x24.org> References: <20190422014906.4253-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: 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 +# Copyright (C) 2015-2019 all contributors # License: GPL-3.0+ 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 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 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 +# License: GPL-3.0+ + +# 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 .
.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(#{sec}) + else + s.encode!(xml: :text) + s.gsub!(/\b(#{linkre})/mo) do |m| + manref = $1 + if url = links[manref] + %Q(#{manref}) + else + manref + end + end + s.rstrip! + s.empty? ? '' : "
#{s}
" + 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