[PATCH 0/3] doc: extindex-related updates

[PATCH 0/3] doc: extindex-related updates

[Eric Wong]

I forgot some things :x

Eric Wong (3):
  doc: extindex: document current behavior + knobs
  doc: -clone|lei add-external: add bit about the Makefile
  doc: relnotes: 1.7.0: move extindex, note search results change

 Documentation/RelNotes/v1.7.0.wip       | 20 +++++++++++---------
 Documentation/lei-add-external.pod      |  2 ++
 Documentation/public-inbox-clone.pod    |  5 +++++
 Documentation/public-inbox-config.pod   | 16 ++++++++++++++++
 Documentation/public-inbox-extindex.pod | 17 +++++++++++++----
 5 files changed, 47 insertions(+), 13 deletions(-)

[PATCH 1/3] doc: extindex: document current behavior + knobs

[Eric Wong]

I'm not really sure if extindex writing to the config file
is a good idea (since -index doesn't, as -init exists).
Just document what it does and let the user handle it, since
the config file shouldn't be daunting to new users.
---
 Documentation/public-inbox-config.pod   | 16 ++++++++++++++++
 Documentation/public-inbox-extindex.pod | 17 +++++++++++++----
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
index a5bc67fd6328..43e54ed42d9d 100644
--- a/Documentation/public-inbox-config.pod
+++ b/Documentation/public-inbox-config.pod
@@ -358,6 +358,22 @@ more than once, in which case the values are merged.
 
 Default: none
 
+=item extindex.<name>.topdir
+
+The directory of an external index.  See
+L<public-inbox-extindex(1)> for more details.
+
+=item extindex.<name>.url
+
+Identical to L</publicinbox.E<lt>nameE<gt>.url>, but for
+external indices
+
+=item extindex.<name>.coderepo
+
+Identical to L</publicinbox.E<lt>nameE<gt>.coderepo>, but for
+external indices.  Code repos may be freely associated with
+any number of public inboxes and external indices.
+
 =back
 
 =head2 NAMED LIMITER (PSGI)
diff --git a/Documentation/public-inbox-extindex.pod b/Documentation/public-inbox-extindex.pod
index a0fca83c6255..9731dfb0d2a7 100644
--- a/Documentation/public-inbox-extindex.pod
+++ b/Documentation/public-inbox-extindex.pod
@@ -10,9 +10,6 @@ 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
@@ -70,7 +67,19 @@ L<public-inbox-extindex-format(5)>
 
 =head1 CONFIGURATION
 
-... TODO, see L<public-inbox-index(5)>
+public-inbox-extindex does not currently write to the
+L<public-inbox-config(5)> file, configuration may be entered
+manually.  The extindex name of C<all> is a special case which
+corresponds to indexing C<--all> inboxes.  An example for
+C<--all> is as follows:
+
+	[extindex "all"]
+		topdir = /path/to/extindex_dir
+		url = all
+		coderepo = foo
+		coderepo = bar
+
+See L<public-inbox-config(5)> for more details.
 
 =head1 ENVIRONMENT
 

[PATCH 2/3] doc: -clone|lei add-external: add bit about the Makefile

[Eric Wong]

It's pretty useful, I think.
---
 Documentation/lei-add-external.pod   | 2 ++
 Documentation/public-inbox-clone.pod | 5 +++++
 2 files changed, 7 insertions(+)

diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod
index 1ab65a1650a6..1761eed1ed78 100644
--- a/Documentation/lei-add-external.pod
+++ b/Documentation/lei-add-external.pod
@@ -29,6 +29,8 @@ Default: 0
 =item --mirror=URL
 
 Create C<LOCATION> by mirroring the public-inbox at C<URL>.
+C<LOCATION> will have a Makefile with a C<make update>
+target to update the external.
 
 =item --epoch=RANGE
 
diff --git a/Documentation/public-inbox-clone.pod b/Documentation/public-inbox-clone.pod
index efee01eec592..103260913d92 100644
--- a/Documentation/public-inbox-clone.pod
+++ b/Documentation/public-inbox-clone.pod
@@ -18,6 +18,11 @@ L<public-inbox-index(1)>.  Those commands must be run separately
 if serving/searching the mirror is required.  As-is,
 public-inbox-clone is suitable for creating a git-only backup.
 
+public-inbox-clone creates a Makefile with handy targets to update the
+inbox once indexed.  This Makefile may be edited by the user; it will
+not be rewritten by L<public-inbox-fetch(1)> unless it is removed
+completely.
+
 public-inbox-clone does not use nor require any extra
 configuration files (not even C<~/.public-inbox/config>).
 

[PATCH 3/3] doc: relnotes: 1.7.0: move extindex, note search results change

[Eric Wong]

extindex is a far more important feature than libgit2 support
(which is actually underperforming and might go away).  The
search results page is also improved (IMHO), nowadays.
---
 Documentation/RelNotes/v1.7.0.wip | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/Documentation/RelNotes/v1.7.0.wip b/Documentation/RelNotes/v1.7.0.wip
index fb2bcc9e2320..0207e94b46c1 100644
--- a/Documentation/RelNotes/v1.7.0.wip
+++ b/Documentation/RelNotes/v1.7.0.wip
@@ -14,15 +14,6 @@ Another big release focused on multi-inbox search and scalability.
 
   - "PRAGMA optimize" is now issued on commits for SQLite 3.18+
 
-* read-only public-inbox-daemon (-httpd, -nntpd, -imapd):
-
-  libgit2 may be used via Inline::C to avoid hitting system pipe
-  and process limits.  See public-inbox-tuning(7) manpage
-  for more details.
-
-* various memory usage reductions and workarounds for leaks in
-  Encode <3.15, these mainly affect PublicInbox::WWW
-
 * public-inbox-extindex
 
   A new Xapian + SQLite index able to search across several inboxes.
@@ -33,6 +24,15 @@ Another big release focused on multi-inbox search and scalability.
   See public-inbox-extindex-format(5) and
   public-inbox-extindex(1) manpages for more details.
 
+* read-only public-inbox-daemon (-httpd, -nntpd, -imapd):
+
+  libgit2 may be used via Inline::C to avoid hitting system pipe
+  and process limits.  See public-inbox-tuning(7) manpage
+  for more details.
+
+* various memory usage reductions and workarounds for leaks in
+  Encode <3.15, these mainly affect PublicInbox::WWW
+
 * public-inbox-nntpd
 
   - startup is 6x faster with 50K inboxes if using -extindex
@@ -47,6 +47,8 @@ Another big release focused on multi-inbox search and scalability.
 
   - manifest.js.gz generation is ~25x faster with -extindex
 
+  - minor navigation improvements in search results page
+
 * lei - local email interface
 
   An experimental, subject-to-change, likely-to-eat-your-mail tool for