From 7b18f5b94e4ae4e4aaabb14e233bf43e560ba84a Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 22 Apr 2019 01:10:44 +0000 Subject: doc: switch to perlpod for documentation 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.pod | 21 +++++++++++++ Documentation/olddoc.1.txt | 23 -------------- Documentation/olddoc.5.pod | 36 ++++++++++++++++++++++ Documentation/olddoc.5.txt | 38 ----------------------- Documentation/podtxt2html | 54 ++++++++++++++++++++++++++++++++ Rakefile | 2 +- 8 files changed, 166 insertions(+), 86 deletions(-) create mode 100644 Documentation/olddoc.1.pod delete mode 100644 Documentation/olddoc.1.txt create mode 100644 Documentation/olddoc.5.pod delete mode 100644 Documentation/olddoc.5.txt 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.pod b/Documentation/olddoc.1.pod new file mode 100644 index 0000000..9d57da1 --- /dev/null +++ b/Documentation/olddoc.1.pod @@ -0,0 +1,21 @@ +=head1 NAME + +olddoc - old-fashioned RDoc HTML generator + +=head1 SYNOPSYS + +olddoc prepare + +rdoc -f oldweb + +rdoc -f dark216 + +=head1 DESCRIPTION + +olddoc features dark216, and old-fashioned RDoc HTML generator. +You can also use "olddoc prepare" to generate NEWS files from +git tags. + +=head1 SEE ALSO + +L diff --git a/Documentation/olddoc.1.txt b/Documentation/olddoc.1.txt deleted file mode 100644 index 25bf88b..0000000 --- a/Documentation/olddoc.1.txt +++ /dev/null @@ -1,23 +0,0 @@ -% olddoc(1) olddoc user manual - -# NAME - -olddoc - old-fashioned RDoc HTML generator - -# SYNOPSIS - -`olddoc` prepare - -`rdoc` -f oldweb - -`rdoc` -f dark216 - -# 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 - -olddoc(5) diff --git a/Documentation/olddoc.5.pod b/Documentation/olddoc.5.pod new file mode 100644 index 0000000..bda770f --- /dev/null +++ b/Documentation/olddoc.5.pod @@ -0,0 +1,36 @@ +=head1 NAME + +.olddoc.yml - olddoc config file format + +=head1 SYNOPSIS + +A YAML file in the top-level project directory named ".olddoc.yml" + +=head1 DESCRIPTION + +As olddoc favors consistency over configuration, there is minimal +configuration to deal with. + +=head1 KEYS + +`rdoc_url`, `cgit_url`, and `nntp_url` should be obvious + +`merge_html` is a key-value mapping of (empty) RDoc source files to an +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` + +As of olddoc 1.2.0, `ml_url` and `nntp_url` may be YAML arrays +with multiple URLs. + +As of olddoc 1.3.0, the `source_code` array may be any number of +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. + +=head1 SEE ALSO + +L diff --git a/Documentation/olddoc.5.txt b/Documentation/olddoc.5.txt deleted file mode 100644 index 8274330..0000000 --- a/Documentation/olddoc.5.txt +++ /dev/null @@ -1,38 +0,0 @@ -% olddoc(1) olddoc user manual - -# NAME - -.olddoc.yml - olddoc config file format - -# SYNOPSIS - -A YAML file in the top-level project directory named ".olddoc.yml" - -# DESCRIPTION - -As olddoc favors consistency over configuration, there is minimal -configuration to deal with. - -# KEYS - -`rdoc_url`, `cgit_url`, and `nntp_url` should be obvious - -`merge_html` is a key-value mapping of (empty) RDoc source files to an -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` - -As of olddoc 1.2.0, `ml_url` and `nntp_url` may be YAML arrays -with multiple URLs. - -As of olddoc 1.3.0, the `source_code` array may be any number of -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 - -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 +# 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) -- cgit v1.2.3-24-ge0c7