about summary refs log tree commit homepage
diff options
context:
space:
mode:
-rwxr-xr-xDocumentation/common.perl65
-rw-r--r--Documentation/include.mk3
-rw-r--r--Documentation/lei-q.pod51
-rw-r--r--MANIFEST1
-rw-r--r--lib/PublicInbox/Search.pm8
5 files changed, 123 insertions, 5 deletions
diff --git a/Documentation/common.perl b/Documentation/common.perl
new file mode 100755
index 00000000..5fdbe8da
--- /dev/null
+++ b/Documentation/common.perl
@@ -0,0 +1,65 @@
+#!perl -w
+# Copyright (C) all contributors <meta@public-inbox.org>
+# License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+use strict;
+use Fcntl qw(SEEK_SET);
+my $have_search = eval { require PublicInbox::Search; 1 };
+my $addr = 'meta@public-inbox.org';
+for my $pod (@ARGV) {
+        open my $fh, '+<', $pod or die "open($pod): $!";
+        my $s = do { local $/; <$fh> } // die "read $!";
+        my $orig = $s;
+        $s =~ s!^=head1 COPYRIGHT\n.+?^=head1([^\n]+)\n!=head1 COPYRIGHT
+
+Copyright all contributors L<mailto:$addr>
+
+License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
+
+=head1$1
+                !ms;
+
+        $s =~ s!^=head1 CONTACT\n.+?^=head1([^\n]+)\n!=head1 CONTACT
+
+Feedback welcome via plain-text mail to L<mailto:$addr>
+
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
+
+=head1$1
+                !ms;
+        $have_search and $s =~ s!^=for\scomment\n
+                        ^AUTO-GENERATED-SEARCH-TERMS-BEGIN\n
+                        .+?
+                        ^=for\scomment\n
+                        ^AUTO-GENERATED-SEARCH-TERMS-END\n
+                        !search_terms()!emsx;
+        $s =~ s/[ \t]+$//sgm;
+        next if $s eq $orig;
+        seek($fh, 0, SEEK_SET) or die "seek: $!";
+        truncate($fh, 0) or die "truncate: $!";
+        print $fh $s or die "print: $!";
+        close $fh or die "close: $!";
+}
+
+sub search_terms {
+        my $help = eval('\@PublicInbox::Search::HELP');
+        my $s = '';
+        my $pad = 0;
+        my $i;
+        for ($i = 0; $i < @$help; $i += 2) {
+                my $pfx = $help->[$i];
+                my $n = length($pfx);
+                $pad = $n if $n > $pad;
+                $s .= $pfx . "\0";
+                $s .= $help->[$i + 1];
+                $s .= "\f\n";
+        }
+        $pad += 2;
+        my $padding = ' ' x ($pad + 4);
+        $s =~ s/^/$padding/gms;
+        $s =~ s/^$padding(\S+)\0/"    $1".(' ' x ($pad - length($1)))/egms;
+        $s =~ s/\f\n/\n/gs;
+        $s =~ s/^  //gms;
+        substr($s, 0, 0, "=for comment\nAUTO-GENERATED-SEARCH-TERMS-BEGIN\n\n");
+        $s .= "\n=for comment\nAUTO-GENERATED-SEARCH-TERMS-END\n";
+}
diff --git a/Documentation/include.mk b/Documentation/include.mk
index 5f3ffcc5..149f9e3c 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -80,6 +80,9 @@ Documentation/flow.txt : Documentation/flow.ge
         touch -r Documentation/flow.ge $@+
         mv $@+ $@
 
+Documentation/lei-q.pod : lib/PublicInbox/Search.pm Documentation/common.perl
+        $(PERL) -I lib -w Documentation/common.perl $@
+
 NEWS NEWS.atom NEWS.html : $(news_deps)
         $(PERL) -I lib -w Documentation/mknews.perl $@ $(RELEASES)
 
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 574c12eb..fe281d7b 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -245,6 +245,55 @@ Default: C<auto>
 
 =back
 
+=head1 SEARCH TERMS
+
+C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
+instances:
+
+=for comment
+AUTO-GENERATED-SEARCH-TERMS-BEGIN
+
+  s:       match within Subject  e.g. s:"a quick brown fox"
+  d:       match date-time range, git "approxidate" formats supported
+           Open-ended ranges such as `d:last.week..' and
+           `d:..2.days.ago' are supported
+  b:       match within message body, including text attachments
+  nq:      match non-quoted text within message body
+  q:       match quoted text within message body
+  n:       match filename of attachment(s)
+  t:       match within the To header
+  c:       match within the Cc header
+  f:       match within the From header
+  a:       match within the To, Cc, and From headers
+  tc:      match within the To and Cc headers
+  l:       match contents of the List-Id header
+  bs:      match within the Subject and body
+  dfn:     match filename from diff
+  dfa:     match diff removed (-) lines
+  dfb:     match diff added (+) lines
+  dfhh:    match diff hunk header context (usually a function name)
+  dfctx:   match diff context lines
+  dfpre:   match pre-image git blob ID
+  dfpost:  match post-image git blob ID
+  dfblob:  match either pre or post-image git blob ID
+  rt:      match received time, like `d:' if sender's clock was correct
+
+=for comment
+AUTO-GENERATED-SEARCH-TERMS-END
+
+Additional search prefixes which only affect the local lei/store:
+
+  L:       match the given label
+  kw:      match the given keywords
+
+See L<lei-tag(1)> for more info on labels and keywords.
+
+Most prefixes are probabilistic, meaning they support stemming
+and wildcards (C<*>).  Ranges (such as C<d:>) and boolean prefixes
+do not support stemming or wildcards.
+The upstream Xapian query parser documentation fully explains
+the query syntax: L<https://xapian.org/docs/queryparser.html>
+
 =head1 TIPS
 
 C<-f reply> is intended to aid in turning a cover letter
@@ -261,7 +310,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
diff --git a/MANIFEST b/MANIFEST
index 1e8f60fb..47eadad2 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -13,6 +13,7 @@ Documentation/RelNotes/v1.6.0.eml
 Documentation/RelNotes/v1.6.1.eml
 Documentation/RelNotes/v1.7.0.wip
 Documentation/clients.txt
+Documentation/common.perl
 Documentation/dc-dlvr-spam-flow.txt
 Documentation/design_notes.txt
 Documentation/design_www.txt
diff --git a/lib/PublicInbox/Search.pm b/lib/PublicInbox/Search.pm
index 600e6400..523003b3 100644
--- a/lib/PublicInbox/Search.pm
+++ b/lib/PublicInbox/Search.pm
@@ -155,9 +155,9 @@ my %prob_prefix = (
 our @HELP = (
         's:' => 'match within Subject  e.g. s:"a quick brown fox"',
         'd:' => <<EOF,
-match date range, git "approxidate" formats supported
-Open-ended ranges such as `d:last.week..' and `d:..2.days.ago'
-are supported
+match date-time range, git "approxidate" formats supported
+Open-ended ranges such as `d:last.week..' and
+`d:..2.days.ago' are supported
 EOF
         'b:' => 'match within message body, including text attachments',
         'nq:' => 'match non-quoted text within message body',
@@ -179,7 +179,7 @@ EOF
         'dfpost:' => 'match post-image git blob ID',
         'dfblob:' => 'match either pre or post-image git blob ID',
         'rt:' => <<EOF,
-match received time, like `d:' unless sender's clock was broken
+match received time, like `d:' if sender's clock was correct
 EOF
 );
 chomp @HELP;