From: Eric Wong <e@80x24.org>
To: meta@public-inbox.org
Subject: [PATCH] doc: lei-q: document SEARCH TERMS prefixes
Date: Tue, 2 Nov 2021 12:55:37 -1100 [thread overview]
Message-ID: <20211102235537.27745-1-e@80x24.org> (raw)
The new Documentation/common.perl file will be used for
all manpages in the future.
---
Documentation/common.perl | 65 +++++++++++++++++++++++++++++++++++++++
Documentation/include.mk | 3 ++
Documentation/lei-q.pod | 51 +++++++++++++++++++++++++++++-
MANIFEST | 1 +
lib/PublicInbox/Search.pm | 8 ++---
5 files changed, 123 insertions(+), 5 deletions(-)
create mode 100755 Documentation/common.perl
diff --git a/Documentation/common.perl b/Documentation/common.perl
new file mode 100755
index 000000000000..5fdbe8da055e
--- /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 5f3ffcc56937..149f9e3ce42e 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 574c12eb9d3a..fe281d7b0121 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 1e8f60fb41da..47eadad2e403 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 600e6400d4b6..523003b3c269 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;
next reply other threads:[~2021-11-02 23:55 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-02 23:55 Eric Wong [this message]
2021-11-03 0:28 ` [PATCH] doc: lei-q: document SEARCH TERMS prefixes Kyle Meyer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://public-inbox.org/README
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211102235537.27745-1-e@80x24.org \
--to=e@80x24.org \
--cc=meta@public-inbox.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/public-inbox.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).