doc: glossary: add information for dates and timestamps

These have been confusing to me in the past, too.

diff --git a/Documentation/public-inbox-glossary.pod b/Documentation/public-inbox-glossary.pod
index e188e563db12e5e042d3279b7cdd0a1483ab7eb4..61e1e9f8b1f777422ed8160779d3def9c67c2445 100644 (file)
--- a/Documentation/public-inbox-glossary.pod
+++ b/Documentation/public-inbox-glossary.pod
@@ -83,6 +83,20 @@ the same email into one or more virtual folders for
 ease-of-filtering.  This is NOT tied to public-inbox names, as
 messages stored by lei may not be public.
 
+=item IMAP INTERNALDATE, JMAP receivedAt, rt: search prefix
+
+The first valid timestamp value of Received: headers (top first).
+If no Received: header exists, the Date: header is used, and the
+current time if neither header(s) exist.  When mirroring via
+git, this is the git commit time.
+
+=item IMAP SENT*, JMAP sentAt, dt: and d: search prefixes
+
+The first valid timestamp value of the Date: header(s).
+If no Date: header exists, the time from the Received: header is
+used, and then the current time if neither header exists.
+When mirroring via git, this is the git author time.
+
 =head1 COPYRIGHT
 
 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>

diff --git a/lib/PublicInbox/Search.pm b/lib/PublicInbox/Search.pm
index 209969c57c94b6a1d515d60c33e08a079da4f6f5..c7d52dafc3f4f9e37491aea50c6ac13880ee8b62 100644 (file)
--- a/lib/PublicInbox/Search.pm
+++ b/lib/PublicInbox/Search.pm
@@ -13,9 +13,9 @@ use POSIX qw(strftime);
 # values for searching, changing the numeric value breaks
 # compatibility with old indices (so don't change them it)
 use constant {
-       TS => 0, # Received: header in Unix time (IMAP INTERNALDATE)
+       TS => 0, # Received: in Unix time (IMAP INTERNALDATE, JMAP receivedAt)
        YYYYMMDD => 1, # Date: header for searching in the WWW UI
-       DT => 2, # Date: YYYYMMDDHHMMSS
+       DT => 2, # Date: YYYYMMDDHHMMSS (IMAP SENT*, JMAP sentAt)
 
        # added for public-inbox 1.6.0+
        BYTES => 3, # IMAP RFC822.SIZE