From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00 shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 01BC31FB0F for ; Wed, 10 Mar 2021 13:23:46 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH 5/5] doc: start glossary for overlapping concepts Date: Wed, 10 Mar 2021 13:23:45 +0000 Message-Id: <20210310132345.28283-6-e@80x24.org> In-Reply-To: <20210310132345.28283-1-e@80x24.org> References: <20210310132345.28283-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: This is intended to keep track of concepts with different terms between NNTP, IMAP, config file, lei storage, and upcoming JMAP support. --- Documentation/public-inbox-glossary.pod | 95 +++++++++++++++++++++++++ Documentation/txt2pre | 1 + MANIFEST | 1 + Makefile.PL | 3 +- 4 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 Documentation/public-inbox-glossary.pod diff --git a/Documentation/public-inbox-glossary.pod b/Documentation/public-inbox-glossary.pod new file mode 100644 index 00000000..e188e563 --- /dev/null +++ b/Documentation/public-inbox-glossary.pod @@ -0,0 +1,95 @@ +=head1 NAME + +public-inbox-glossary - glossary for public-inbox + +=head1 DESCRIPTION + +public-inbox combines several independently-developed protocols +and data formats with overlapping concepts. This document is +intended as a guide to identify and clarify overlapping concepts +with different names. + +This is mainly intended for hackers of public-inbox, but may be useful +for administrators of public-facing services and/or users building +tools. + +=head1 TERMS + +=item IMAP UID, NNTP article number, on-disk Xapian docid + +A sequentially-assigned positive integer. These integers are per-inbox, +or per-extindex. This is the C column of the C table in +C + +=item tid, THREADID + +A sequentially-assigned positive integer. These integers are +per-inbox or per-extindex. In the future, this may be prefixed +with C for JMAP (RFC 8621) and RFC 8474. This may not be +strictly compliant with RFC 8621 since inboxes and extindices +are considered independent entities from each other. + +This is the C column of the C table in C + +=item blob + +For email, this is the git blob object ID (SHA-(1|256)) of an +RFC-(822|2822|5322) email message. + +=item IMAP EMAILID, JMAP Email Id + +To-be-decided. This will likely be the git blob ID prefixed with C +rather than the numeric UID to accomodate the same blob showing +up in both an extindex and inbox (or multiple extindices). + +=item newsgroup + +The name of the NNTP newsgroup, see L. + +=item IMAP (folder|mailbox) slice + +A 50K slice of a newsgroup to accomodate the limitations of IMAP +clients with L. This is the C +name with a C<.$INTEGER_SUFFIX>, e.g. a newsgroup named C +would have its first slice named C, and second slice +named C and so forth. + +If implemented, the RFC 8474 MAILBOXID of an IMAP slice will NOT have +the same Mailbox Id as the public-facing full JMAP mailbox. + +=item inbox name, public JMAP mailbox name + +The HTTP(S) name of the public-inbox +(CnameE.*>). JMAP will use this name +rather than the newsgroup name since public-facing JMAP will be +part of the PSGI code and not need a separate daemon like +L or L + +=item keywords, (IMAP|Maildir) flags, mbox Status + X-Status + +Private, per-message keywords or flags as described in RFC 8621 +section 10.4. These are conveyed in the C and +C headers for L, as IMAP FLAGS (RFC 3501 section 2.3.2), +or Maildir info flags. + +L ignores drafts and trashed (deleted) +messages. L ignores trashed (deleted) messages, +but it imports drafts. + +=item labels, private JMAP mailboxes + +For L users only. This will allow lei users to place +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. + +=head1 COPYRIGHT + +Copyright 2021 all contributors L + +License: AGPL-3.0+ L + +=head1 SEE ALSO + +L, L, +L, L diff --git a/Documentation/txt2pre b/Documentation/txt2pre index 3277531f..244dc50c 100755 --- a/Documentation/txt2pre +++ b/Documentation/txt2pre @@ -27,6 +27,7 @@ for (qw[lei(1) public-inbox-convert(1) public-inbox-daemon(8) public-inbox-edit(1) + public-inbox-glossary(7) public-inbox-httpd(1) public-inbox-imapd(1) public-inbox-index(1) diff --git a/MANIFEST b/MANIFEST index 8c9c86a0..8662d2c0 100644 --- a/MANIFEST +++ b/MANIFEST @@ -41,6 +41,7 @@ Documentation/public-inbox-daemon.pod Documentation/public-inbox-edit.pod Documentation/public-inbox-extindex-format.pod Documentation/public-inbox-extindex.pod +Documentation/public-inbox-glossary.pod Documentation/public-inbox-httpd.pod Documentation/public-inbox-imapd.pod Documentation/public-inbox-index.pod diff --git a/Makefile.PL b/Makefile.PL index 6da2ed70..21d3d6ea 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -48,7 +48,8 @@ $v->{-m1} = [ map { lei-forget-external lei-import lei-init lei-ls-external lei-q)]; $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format public-inbox-v2-format public-inbox-extindex-format) ]; -$v->{-m7} = [ qw(lei-overview public-inbox-overview public-inbox-tuning) ]; +$v->{-m7} = [ qw(lei-overview public-inbox-overview public-inbox-tuning + public-inbox-glossary) ]; $v->{-m8} = [ qw(public-inbox-daemon) ]; my @sections = (1, 5, 7, 8); $v->{check_80} = [];