imap+nntp: share COMPRESS implementation

[public-inbox.git] / Documentation / public-inbox-v1-format.pod

diff --git a/Documentation/public-inbox-v1-format.pod b/Documentation/public-inbox-v1-format.pod
index 2a6b8d3c6f1c07b4073b827323c3a2a47022de90..db223fd9388b090557c17d9db1d20cf2b7203673 100644 (file)
--- a/Documentation/public-inbox-v1-format.pod
+++ b/Documentation/public-inbox-v1-format.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-public-inbox v1 git repository and tree description (aka "ssoma")
+public-inbox-v1-format - git repository and tree description (aka "ssoma")

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -104,6 +104,10 @@ SQLite3 database maintaining a stable mapping of Message-IDs to NNTP
 article numbers.  Used by L<public-inbox-nntpd(1)> and created
 and updated by L<public-inbox-index(1)>.
 
 article numbers.  Used by L<public-inbox-nntpd(1)> and created
 and updated by L<public-inbox-index(1)>.
 

+Users of the L<PublicInbox::WWW> interface will find it
+useful for attempting recovery from copy-paste truncations of
+URLs containing long Message-IDs.
+

 Automatically updated by L<public-inbox-mda(1)>,
 L<public-inbox-learn(1)> and L<public-inbox-watch(1)>.
 
 Automatically updated by L<public-inbox-mda(1)>,
 L<public-inbox-learn(1)> and L<public-inbox-watch(1)>.
 


@@ -127,13 +131,21 @@ Automatically updated by L<public-inbox-mda(1)>,
 L<public-inbox-learn(1)> and L<public-inbox-watch(1)>.
 
 This directory can always be regenerated with L<public-inbox-index(1)>.
 L<public-inbox-learn(1)> and L<public-inbox-watch(1)>.
 
 This directory can always be regenerated with L<public-inbox-index(1)>.

-If lost or damaaged, there is no need to back it up unless the
+If lost or damaged, there is no need to back it up unless the

 CPU/memory cost of regenerating it outweighs the storage/transfer cost.
 
 Since SCHEMA_VERSION 15 and the development of the v2 format,
 the "overview" DB also exists in the xapian directory for v1
 repositories.  See L<public-inbox-v2-format(5)/OVERVIEW DB>
 
 CPU/memory cost of regenerating it outweighs the storage/transfer cost.
 
 Since SCHEMA_VERSION 15 and the development of the v2 format,
 the "overview" DB also exists in the xapian directory for v1
 repositories.  See L<public-inbox-v2-format(5)/OVERVIEW DB>
 

+Our use of the L</OVERVIEW DB> requires Xapian document IDs to
+remain stable.  Using L<public-inbox-compact(1)> and
+L<public-inbox-xcpdb(1)> wrappers are recommended over tools
+provided by Xapian.
+
+This directory is large, often two to three times the size of
+the objects stored in a packed git repository.
+

 =item $GIT_DIR/ssoma.index
 
 This file is no longer used or created by public-inbox, but it is
 =item $GIT_DIR/ssoma.index
 
 This file is no longer used or created by public-inbox, but it is


@@ -157,12 +169,13 @@ there may be many files.
 
 It is impossible to completely expunge messages, even spam, as git
 retains full history.  Projects may (with adequate notice) cycle to new
 
 It is impossible to completely expunge messages, even spam, as git
 retains full history.  Projects may (with adequate notice) cycle to new

-repositories/branches with history cleaned up via L<git-filter-branch(1)>.
+repositories/branches with history cleaned up via L<git-filter-repo(1)>
+or L<git-filter-branch(1)>.

 This is up to the administrators.
 
 =head1 COPYRIGHT
 
 This is up to the administrators.
 
 =head1 COPYRIGHT
 

-Copyright 2013-2019 all contributors L<mailto:meta@public-inbox.org>
+Copyright 2013-2021 all contributors L<mailto:meta@public-inbox.org>

 
 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 
 
 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>