* [ANN] olddoc 1.7.0 - old-fashioned RDoc generator
@ 2019-04-22 2:06 6% Eric Wong
0 siblings, 0 replies; 3+ results
From: Eric Wong @ 2019-04-22 2:06 UTC (permalink / raw)
To: ruby-talk, olddoc-public
olddoc contains old-fashioned document generators for those who do not
wish to impose bloated, new-fangled web cruft on their readers.
olddoc contains dark216, a HTML generator without any images, frames,
or JavaScript. It is designed for users of text-based browsers
and/or low-bandwidth connections; yet respects user preference for
light color schemes in new CSS browsers while favoring darkness for
power savings on OLED and CRT displays. dark216 focuses on text as
it is the lowest common denominator for accessibility and compatibility
with people and hardware.
Changes:
Since most users are on horrible GUI browsers which default
to light backgrounds, implement the "dark216" color scheme
which saves power on OLED and CRT displays. This still
respects "prefers-color-scheme:light" on newer browsers,
so users can burn their eyes out if they wish :P
While we're at it, switch to perlpod for our own documentation
since Perl5 and POD tooling is more common on most *nix systems
than pandoc. Finally, update our documentation to avoid the
term "mailing list" because centralized subscriber lists limit
forkability compared to an "archives first" approach to email.
3 changes since v1.6.0 (2019-01-07):
add dark216 color scheme for power savings
doc: switch to perlpod for documentation
doc: update wording to avoid "mailing list"
* https://80x24.org/olddoc/ - homepage + sample
* https://80x24.org/olddoc-public/ - mail archives
* nntp://news.public-inbox.org/inbox.comp.lang.ruby.olddoc
* olddoc-public@80x24.org - public inbox (no subscription)
* license: GPL-3.0+
* git clone https://80x24.org/olddoc.git
^ permalink raw reply [relevance 6%]
* [PATCH 2/3] doc: switch to perlpod for documentation
2019-04-22 1:49 7% [PATCH 0/3] Earth Day changes! Eric Wong
@ 2019-04-22 1:49 5% ` Eric Wong
0 siblings, 0 replies; 3+ results
From: Eric Wong @ 2019-04-22 1:49 UTC (permalink / raw)
To: olddoc-public
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
^ permalink raw reply related [relevance 5%]
* [PATCH 0/3] Earth Day changes!
@ 2019-04-22 1:49 7% Eric Wong
2019-04-22 1:49 5% ` [PATCH 2/3] doc: switch to perlpod for documentation Eric Wong
0 siblings, 1 reply; 3+ results
From: Eric Wong @ 2019-04-22 1:49 UTC (permalink / raw)
To: olddoc-public
Since most users are on horrible GUI browsers which default
to light backgrounds, implement the "dark216" color scheme
which saves power on OLED and CRT displays. This still
respects "prefers-color-scheme:light" on newer browsers,
so users can burn their eyes out if they wish :P
While we're at it, switch to perlpod for our own documentation
since Perl5 and POD tooling is more common on most *nix systems
than pandoc. Finally, update our documentation to avoid the
term "mailing list" because centralized subscriber lists hurt
forkability compared to an "archives first" approach to email.
Eric Wong (3):
add dark216 color scheme for power savings
doc: switch to perlpod for documentation
doc: update wording to avoid "mailing list"
Documentation/.gitignore | 1 +
Documentation/GNUmakefile | 77 ++++++++++++++------
Documentation/olddoc.1.pod | 21 ++++++
Documentation/olddoc.1.txt | 21 ------
Documentation/{olddoc.5.txt => olddoc.5.pod} | 19 ++---
Documentation/podtxt2html | 54 ++++++++++++++
GNUmakefile | 2 +-
README | 27 ++++---
Rakefile | 2 +-
lib/dark216.rb | 40 ++++++++++
lib/olddoc.rb | 3 +-
lib/oldweb.rb | 1 +
lib/oldweb/_head.rhtml | 6 +-
13 files changed, 202 insertions(+), 72 deletions(-)
create mode 100644 Documentation/olddoc.1.pod
delete mode 100644 Documentation/olddoc.1.txt
rename Documentation/{olddoc.5.txt => olddoc.5.pod} (77%)
create mode 100755 Documentation/podtxt2html
create mode 100644 lib/dark216.rb
--
EW
^ permalink raw reply [relevance 7%]
Results 1-3 of 3 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2019-04-22 1:49 7% [PATCH 0/3] Earth Day changes! Eric Wong
2019-04-22 1:49 5% ` [PATCH 2/3] doc: switch to perlpod for documentation Eric Wong
2019-04-22 2:06 6% [ANN] olddoc 1.7.0 - old-fashioned RDoc generator Eric Wong
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).