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://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0b73ad048e715065efc3ed3eb1c376e945957693;p=thirdparty%2Fpublic-inbox.git

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 c6cfb4c58..000000000
--- 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 149f9e3ce..af5f7f24d 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 1761eed1e..7afcad637 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 25f1daf5f..ad769084c 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 fe281d7b0..fd8296554 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 103260913..c80c3c5fd 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 1890ae759..c78ffc0bc 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 f6b2ad966..def544731 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 47eadad2e..46e0e099d 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 8c8c0235f..b7851adae 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->{$_};