user/dev discussion of public-inbox itself
 help / color / mirror / code / Atom feed
* [PATCH] doc: lei-q: document SEARCH TERMS prefixes
@ 2021-11-02 23:55 Eric Wong
  2021-11-03  0:28 ` Kyle Meyer
  0 siblings, 1 reply; 2+ messages in thread
From: Eric Wong @ 2021-11-02 23:55 UTC (permalink / raw)
  To: meta

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;

^ permalink raw reply	[flat|nested] 2+ messages in thread

* Re: [PATCH] doc: lei-q: document SEARCH TERMS prefixes
  2021-11-02 23:55 [PATCH] doc: lei-q: document SEARCH TERMS prefixes Eric Wong
@ 2021-11-03  0:28 ` Kyle Meyer
  0 siblings, 0 replies; 2+ messages in thread
From: Kyle Meyer @ 2021-11-03  0:28 UTC (permalink / raw)
  To: Eric Wong; +Cc: meta

Eric Wong writes:

> +=for comment
> +AUTO-GENERATED-SEARCH-TERMS-BEGIN

Looks great, thanks.  By the way, this takes care of a to-do in this
file:

  =for comment
  TODO: Give common prefixes, or at least a description/reference.

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2021-11-03  0:29 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-11-02 23:55 [PATCH] doc: lei-q: document SEARCH TERMS prefixes Eric Wong
2021-11-03  0:28 ` Kyle Meyer

Code repositories for project(s) associated with this 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).