[PATCH 0/3] doc: some extindex updates

[PATCH 0/3] doc: some extindex updates

[Eric Wong]

1-2/3 should make life easier for lintian users (Debian
developers).

3/3 - I'm still uncertain about some behavior of the command
w.r.t. config file updating and hoping they'll be fleshed out
as I start (ab)using it during lei(1) development

Eric Wong (3):
  doc: extindex-format: make lexgrog happy
  build: check with lexgrog(1) if available
  doc: start working on public-inbox-extindex(1) manpage

 .gitignore                                    |  1 +
 Documentation/include.mk                      |  3 +
 .../public-inbox-extindex-format.pod          |  2 +-
 Documentation/public-inbox-extindex.pod       | 84 +++++++++++++++++++
 MANIFEST                                      |  1 +
 Makefile.PL                                   |  8 +-
 6 files changed, 97 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/public-inbox-extindex.pod

[PATCH 1/3] doc: extindex-format: make lexgrog happy

[Eric Wong]

Based on commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55
("public-inbox-v[12]-format.pod: make lexgrog happy")
---
 Documentation/public-inbox-extindex-format.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/public-inbox-extindex-format.pod b/Documentation/public-inbox-extindex-format.pod
index 52eb8e85..d47e2102 100644
--- a/Documentation/public-inbox-extindex-format.pod
+++ b/Documentation/public-inbox-extindex-format.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-public-inbox extindex format description
+public-inbox-extindex-format - external index format description
 
 =head1 DESCRIPTION
 

[PATCH 2/3] build: check with lexgrog(1) if available

[Eric Wong]

This will make life easier for Debian package maintainers
running lintian.

cf. commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55
    ("public-inbox-v[12]-format.pod: make lexgrog happy")
---
 .gitignore               | 1 +
 Documentation/include.mk | 3 +++
 Makefile.PL              | 8 +++++++-
 3 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 7f4142ba..f7e4c595 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@
 *.gz
 .*.cols
 .*.check
+.*.lexgrog
 /NEWS.html
 /NEWS.atom
 /NEWS
diff --git a/Documentation/include.mk b/Documentation/include.mk
index df6c17e0..79bf460d 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -6,6 +6,7 @@ RSYNC = rsync
 RSYNC_DEST = public-inbox.org:/srv/public-inbox/
 AWK = awk
 MAN = man
+LEXGROG = lexgrog
 
 # this is "xml" on FreeBSD and maybe some other distros:
 XMLSTARLET = xmlstarlet
@@ -56,6 +57,8 @@ check_man = $(AWK) '{gsub(/\b./,"")}length>80{print;err=1}END{exit(err)}'\
 
 check-man :: $(check_80)
 
+check-lexgrog :: $(check_lexgrog)
+
 all :: $(docs)
 
 txt2pre = $(PERL) -I lib ./Documentation/txt2pre >$@
diff --git a/Makefile.PL b/Makefile.PL
index 613a72ae..c57491eb 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -65,8 +65,12 @@ for my $i (@sections) {
 		$t->{".$m.cols : $m.$i"} = [
 			"\@echo CHECK80 $m.$i;".
 			"COLUMNS=80 \$(MAN) ./$m.$i | \$(check_man)" ];
+		$t->{".$m.lexgrog: $m.$i"} = [
+			"\@echo LEXGROG $m.$i;" .
+			"\$(LEXGROG) ./$m.$i >\$\@+ && mv \$\@+ \$@" ];
 	}
 	push @{$v->{check_80}}, map { ".$_.cols" } @$ary;
+	push @{$v->{check_lexgrog}}, map { ".$_.lexgrog" } @$ary;
 	my $manuals = $v->{"man$i"} = [ map { "$_.$i" } @$ary ];
 	push @{$v->{manuals}}, @$manuals;
 	push @{$v->{mantxt}}, map { "Documentation/$_.txt" } @$ary;
@@ -121,6 +125,8 @@ my %man3 = map {; # semi-colon tells Perl this is a BLOCK (and not EXPR)
 	"lib/PublicInbox/$_" => "blib/man3/PublicInbox::$mod.\$(MAN3EXT)"
 } qw(Git.pm Import.pm WWW.pod SaPlugin/ListMirror.pod);
 my $warn_no_pod = @no_pod ? "\n\t\@echo W: missing .pod: @no_pod\n" : '';
+chomp(my $lexgrog = `which lexgrog 2>/dev/null`);
+my $check_lexgrog = $lexgrog ? 'check-lexgrog' : '';
 
 WriteMakefile(
 	NAME => 'PublicInbox', # n.b. camel-case is not our choice
@@ -184,7 +190,7 @@ $VARS
 -include Documentation/include.mk
 $TGTS
 
-check-man ::$warn_no_pod
+check-man :: $check_lexgrog$warn_no_pod
 
 # syntax checks are currently GNU make only:
 %.syntax :: %

[PATCH 3/3] doc: start working on public-inbox-extindex(1) manpage

[Eric Wong]

It's barely started, but I started writing this weeks ago, but
I'm still unsure about some behavioral/usability things and
hoping work on lei(1) can flush them out.
---
 Documentation/public-inbox-extindex.pod | 84 +++++++++++++++++++++++++
 MANIFEST                                |  1 +
 2 files changed, 85 insertions(+)
 create mode 100644 Documentation/public-inbox-extindex.pod

diff --git a/Documentation/public-inbox-extindex.pod b/Documentation/public-inbox-extindex.pod
new file mode 100644
index 00000000..a92181e4
--- /dev/null
+++ b/Documentation/public-inbox-extindex.pod
@@ -0,0 +1,84 @@
+=head1 NAME
+
+public-inbox-extindex - create and update external search indices
+
+=head1 SYNOPSIS
+
+public-inbox-extindex [OPTIONS] EXTINDEX_DIR INBOX_DIR...
+
+public-inbox-extindex [OPTIONS] [EXTINDEX_DIR] --all
+
+=head1 DESCRIPTION
+
+FIXME: behavior not finalized  It should probably write to the
+config file the first time --all is used.
+
+public-inbox-extindex creates and updates an external search and
+overview database used by the read-only public-inbox PSGI (HTTP),
+NNTP, and IMAP interfaces.  This requires either the
+L<Search::Xapian> XS bindings OR the L<Xapian> SWIG bindings,
+along with L<DBD::SQLite> and L<DBI> Perl modules.
+
+=head1 OPTIONS
+
+=over
+
+=item --jobs=JOBS, -j
+
+... TODO, see L<public-inbox-index(5)>
+
+=back
+
+=head1 FILES
+
+L<public-inbox-extindex-format(5)>
+
+=head1 CONFIGURATION
+
+... TODO, see L<public-inbox-index(5)>
+
+=head1 ENVIRONMENT
+
+=over 8
+
+=item PI_CONFIG
+
+Used to override the default "~/.public-inbox/config" value.
+
+=item XAPIAN_FLUSH_THRESHOLD
+
+The number of documents to update before committing changes to
+disk.  This environment is handled directly by Xapian, refer to
+Xapian API documentation for more details.
+
+Setting C<XAPIAN_FLUSH_THRESHOLD> or
+C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
+L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
+L<public-inbox-watch(1)> tasks to wait long and unpredictable
+periods of time during C<--reindex>.
+
+Default: none, uses C<publicinbox.indexBatchSize>
+
+=back
+
+=head1 UPGRADING
+
+Occasionally, public-inbox will update it's schema version and
+require a full index by running this command.
+
+=head1 CONTACT
+
+Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
+
+The mail archives are hosted at L<https://public-inbox.org/meta/>
+and L<http://hjrcffqmbrq6wope.onion/meta/>
+
+=head1 COPYRIGHT
+
+Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+
+License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<Search::Xapian>, L<DBD::SQLite>
diff --git a/MANIFEST b/MANIFEST
index ddee1539..127b7caf 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -28,6 +28,7 @@ Documentation/public-inbox-convert.pod
 Documentation/public-inbox-daemon.pod
 Documentation/public-inbox-edit.pod
 Documentation/public-inbox-extindex-format.pod
+Documentation/public-inbox-extindex.pod
 Documentation/public-inbox-httpd.pod
 Documentation/public-inbox-imapd.pod
 Documentation/public-inbox-index.pod