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=-3.5 required=3.0 tests=ALL_TRUSTED,AWL,BAYES_00, FUZZY_DR_OZ shortcircuit=no autolearn=no 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 34BB61F981 for ; Fri, 24 May 2019 02:58:00 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH 5/7] doc: generate manpages for some Xapian commands Date: Fri, 24 May 2019 02:57:56 +0000 Message-Id: <20190524025758.32261-6-e@80x24.org> In-Reply-To: <20190524025758.32261-1-e@80x24.org> References: <20190524025758.32261-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: They're nowhere to be found on Xapian.org, and links to external services are either too long (for manpages.debian.org) or have privacy-invasive tracking JS on them. --- Documentation/.gitignore | 1 + Documentation/extman.perl | 33 +++++++++++++++++++++++++++++++++ Documentation/include.mk | 34 ++++++++++++++++++++++++++++++++-- 3 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 Documentation/extman.perl diff --git a/Documentation/.gitignore b/Documentation/.gitignore index e78a0d3..4d2ca22 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,2 +1,3 @@ /public-inbox-*.txt /standards.txt +/.x diff --git a/Documentation/extman.perl b/Documentation/extman.perl new file mode 100644 index 0000000..a72caca --- /dev/null +++ b/Documentation/extman.perl @@ -0,0 +1,33 @@ +#!/usr/bin/perl -w +# Copyright (C) 2019 all contributors +# License: AGPL-3.0+ +# 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 5b793fb..b064f29 100644 --- a/Documentation/include.mk +++ b/Documentation/include.mk @@ -8,6 +8,11 @@ all:: # Maybe it's not worth it to support non-GNU make, though... RSYNC = rsync RSYNC_DEST = public-inbox.org:/srv/public-inbox/ +MAN = man + +# same as pod2text +COLUMNS = 76 + txt := INSTALL README COPYING TODO HACKING dtxt := design_notes.txt design_www.txt dc-dlvr-spam-flow.txt hosted.txt dtxt += marketing.txt @@ -106,6 +111,26 @@ html: $(docs_html) gz_docs := $(addsuffix .gz, $(docs) $(docs_html)) rsync_docs := $(gz_docs) $(docs) $(docs_html) +# external manpages which we host ourselves, since some packages +# (currently just Xapian) doesn't host manpages themselves. +xtxt := +xtxt += .copydatabase.1 +xtxt += .xapian-compact.1 +xtxt := $(addprefix Documentation/.x/, $(addsuffix .txt, $(xtxt))) +xdocs := $(xtxt) +xdocs_html := $(addsuffix .html, $(subst .txt,,$(xtxt))) +gz_xdocs := $(addsuffix .gz, $(xdocs) $(xdocs_html)) +rsync_xdocs := $(gz_xdocs) $(xdocs_html) $(xdocs) +xdoc: $(xdocs) $(xdocs_html) + +Documentation/.x/%.txt:: + @-mkdir -p $(@D) + $(PERL) -w Documentation/extman.perl $@ >$@+ + mv $@+ $@ + +Documentation/.x/%.html: Documentation/.x/%.txt + $(txt2pre) + doc: $(docs) %.gz: % @@ -114,14 +139,19 @@ doc: $(docs) mv $@+ $@ gz-doc: $(gz_docs) + +gz-xdoc: $(gz_xdocs) + rsync-doc: # /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 - $(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(RSYNC_DEST) + $(MAKE) gz-doc gz-xdoc + $(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(rsync_xdocs) $(RSYNC_DEST) + clean-doc: $(RM) $(man1) $(man5) $(man7) $(gz_docs) $(docs_html) $(mantxt) + $(RM) $(gz_xdocs) $(xdocs_html) $(xdocs) clean :: clean-doc -- EW