From: Eric Wong <e@80x24.org>
Date: Wed, 3 Nov 2021 21:01:21 +0000 (+0000)
Subject: doc: add more 3rd-party refs, use Debian manpages for xapian
X-Git-Tag: v1.7.0~7
X-Git-Url: http://www.git.stargrave.org/?p=public-inbox.git;a=commitdiff_plain;h=0b73ad048e715065efc3ed3eb1c376e945957693

doc: add more 3rd-party refs, use Debian manpages for xapian

curl, torsocks, and gitglossary manpages are all newly
referenced, so make sure they're linkified properly in HTML.
We'll be using Debian's manpages as an ad-free, Tor-accessible
host for manpages as a fallback since hosting manpages for all
3rd-party projects we reference doesn't scale.
---

diff --git a/Documentation/extman.perl b/Documentation/extman.perl
deleted file mode 100755
index c6cfb4c5..00000000
--- a/Documentation/extman.perl
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/usr/bin/perl -w
-# Copyright (C) 2019-2021 all contributors <meta@public-inbox.org>
-# License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
-# prints a manpage to stdout
-use strict;
-my $xapmsg = 'See https://xapian.org/ for more information on Xapian';
-my $usage = "$0 /path/to/manpage.SECTION.txt";
-my $manpage = shift or die $usage;
-my $MAN = $ENV{MAN} || 'man';
-my @args;
-$manpage = (split('/', $manpage))[-1];
-$manpage =~ s/\.txt\z//;
-$manpage =~ s/\A\.//; # no leading dot (see Documentation/include.mk)
-$manpage =~ s/\.(\d+.*)\z// and push @args, $1; # section
-push @args, $manpage;
-
-# don't use UTF-8 characters which readers may not have fonts for
-$ENV{LC_ALL} = $ENV{LANG} = 'C';
-$ENV{COLUMNS} = '76'; # same as pod2text default
-$ENV{PAGER} = 'cat';
-my $cmd = join(' ', $MAN, @args);
-system($MAN, @args) and die "$cmd failed: $!\n";
-$manpage =~ /\A(?:copydatabase|xapian-compact)\z/ and
-	print "\n\n", $xapmsg, "\n";
-
-# touch -r $(man -w $section $manpage) output.txt
-if (-f \*STDOUT) {
-	open(my $fh, '-|', $MAN, '-w', @args) or die "$MAN -w broken?: $!\n";
-	chomp(my $path = <$fh>);
-	my @st = stat($path) or die "stat($path) failed: $!\n";
-	# 9 - mtime
-	utime($st[9], $st[9], \*STDOUT) or die "utime(STDOUT) failed: $!\n";
-}
diff --git a/Documentation/include.mk b/Documentation/include.mk
index 149f9e3c..af5f7f24 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -105,18 +105,16 @@ doc: $(docs)
 
 gz-doc: $(gz_docs)
 
-gz-xdoc: $(gz_xdocs)
-
 rsync-doc: NEWS.atom.gz
 	# /usr/share/doc/rsync/scripts/git-set-file-times{.gz} on Debian systems
 	# It is also at: https://yhbt.net/git-set-file-times
 	-git set-file-times $(docs) $(txt)
-	$(MAKE) gz-doc gz-xdoc
-	$(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(rsync_xdocs) $(RSYNC_DEST)
+	$(MAKE) gz-doc
+	$(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(RSYNC_DEST)
 
 clean-doc:
 	$(RM_F) $(man1) $(man5) $(man7) $(man8) $(gz_docs) $(docs_html) \
-		$(mantxt) $(rsync_xdocs) \
+		$(mantxt) \
 		NEWS NEWS.atom NEWS.html Documentation/standards.txt \
 		Documentation/flow.html Documentation/flow.html.gz \
 		Documentation/flow.txt.gz
diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod
index 1761eed1..7afcad63 100644
--- a/Documentation/lei-add-external.pod
+++ b/Documentation/lei-add-external.pod
@@ -69,7 +69,7 @@ Suppress feedback messages.
 
 =item --no-torsocks
 
-Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
+Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
 
 Default: C<auto>
 
diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 25f1daf5..ad769084 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -77,7 +77,7 @@ Import already seen IMAP and NNTP articles.
 
 =item --no-torsocks
 
-Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
+Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
 
 Default: C<auto>
 
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index fe281d7b..fd829655 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -237,7 +237,7 @@ Suppress feedback messages.
 
 =item --no-torsocks
 
-Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
+Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
 
 Default: C<auto>
 
diff --git a/Documentation/public-inbox-clone.pod b/Documentation/public-inbox-clone.pod
index 10326091..c80c3c5f 100644
--- a/Documentation/public-inbox-clone.pod
+++ b/Documentation/public-inbox-clone.pod
@@ -67,7 +67,7 @@ Increases verbosity, also passed to L<git-fetch(1)>.
 
 =item --no-torsocks
 
-Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
+Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
 
 Default: C<auto>
 
diff --git a/Documentation/public-inbox-fetch.pod b/Documentation/public-inbox-fetch.pod
index 1890ae75..c78ffc0b 100644
--- a/Documentation/public-inbox-fetch.pod
+++ b/Documentation/public-inbox-fetch.pod
@@ -71,7 +71,7 @@ Increases verbosity, also passed to L<git-fetch(1)>.
 
 =item --no-torsocks
 
-Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
+Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
 
 Default: C<auto>
 
diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index f6b2ad96..def54473 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -76,11 +76,6 @@ for (qw[lei(1)
 	$xurls{$n} = "$n.html";
 }
 
-for (qw[copydatabase(1) xapian-compact(1)]) {
-	my ($n) = (/([\w\-\.]+)/);
-	$xurls{$_} = ".$n.1.html"
-}
-
 for (qw[make(1) flock(2) setrlimit(2) vfork(2) tmpfs(5)]) {
 	my ($n, $s) = (/([\w\-]+)\((\d)\)/);
 	$xurls{$_} = "http://www.man7.org/linux/man-pages/man$s/$n.$s.html";
@@ -103,6 +98,7 @@ for (qw[git(1)
 	git-init(1)
 	git-send-email(1)
 	gitrepository-layout(5)
+	gitglossary(7)
 ]) {
 	my ($n) = (/([\w\-\.]+)/);
 	$xurls{$_} = "https://kernel.org/pub/software/scm/git/docs/$n.html"
@@ -118,6 +114,7 @@ for (qw[
 	$xurls{$_} = "https://www.freedesktop.org/software/systemd/man/$n.html";
 }
 
+# favor upstream docs if they exist, use manpages.debian.org if they don't
 $xurls{'netrc(5)'} = 'https://manpages.debian.org/stable/ftp/netrc.5.en.html';
 $xurls{'mbsync(1)'} =
 	'https://manpages.debian.org/stable/isync/mbsync.1.en.html';
@@ -135,6 +132,13 @@ $xurls{'cgitrc(5)'} = 'https://git.zx2c4.com/cgit/tree/cgitrc.5.txt';
 $xurls{'prove(1)'} = 'https://perldoc.perl.org/prove.html';
 $xurls{'mbox(5)'} = 'https://manpages.debian.org/stable/mutt/mbox.5.en.html';
 $xurls{'mmdf(5)'} = 'https://manpages.debian.org/stable/mutt/mmdf.5.en.html';
+$xurls{'torsocks(1)'} =
+	'https://manpages.debian.org/stable/torsocks/torsocks.1.en.html';
+$xurls{'curl(1)'} = 'https://manpages.debian.org/stable/curl/curl.1.en.html';
+$xurls{'copydatabase(1)'} =
+ 'https://manpages.debian.org/stable/xapian-tools/copydatabase.1.en.html';
+$xurls{'xapian-compact(1)'} =
+ 'https://manpages.debian.org/stable/xapian-tools/xapian-compact.1.en.html';
 
 my $str = do { local $/; <STDIN> };
 my ($title) = ($str =~ /\A([^\n]+)/);
diff --git a/MANIFEST b/MANIFEST
index 47eadad2..46e0e099 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -17,7 +17,6 @@ Documentation/common.perl
 Documentation/dc-dlvr-spam-flow.txt
 Documentation/design_notes.txt
 Documentation/design_www.txt
-Documentation/extman.perl
 Documentation/flow.ge
 Documentation/flow.txt
 Documentation/hosted.txt
diff --git a/Makefile.PL b/Makefile.PL
index 8c8c0235..b7851ada 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -101,23 +101,6 @@ $v->{gz_docs} = [ map { "$_.gz" } (@{$v->{docs}},@{$v->{docs_html}}) ];
 $v->{rsync_docs} = [ @{$v->{gz_docs}}, @{$v->{docs}},
 	@{$v->{docs_html}}, qw(NEWS.atom NEWS.atom.gz)];
 
-# external manpages which we host ourselves, since some packages
-# (currently just Xapian) doesn't host manpages themselves.
-my @xman = qw(copydatabase.1 xapian-compact.1);
-$v->{xdocs} = [ map { "Documentation/.$_.txt" } @xman ];
-$v->{xdocs_html} = [ map { "Documentation/.$_.html" } @xman ];
-for (@{$v->{xdocs}}) {
-	$t->{"$_:"} = [
-		'$(PERL) -w Documentation/extman.perl $@ >$@+',
-		'mv $@+ $@'
-	];
-	my $html = $_;
-	$html =~ s/\.txt\z/.html/;
-	$t->{"$html : $_"} = [ "\$(txt2pre) <$_" ];
-}
-$v->{gz_xdocs} = [ map { "$_.gz" } (@{$v->{xdocs_html}}, @{$v->{xdocs}}) ];
-$v->{rsync_xdocs} = [ @{$v->{gz_xdocs}}, @{$v->{xdocs_html}}, @{$v->{xdocs}} ];
-
 my $TGTS = join("\n", map {;
 	my $tgt_prereq = $_;
 	my $cmds = $t->{$_};