# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used throughout the project for reading configuration
package PublicInbox::Config;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used by the web interface to link to messages outside of the our
+# public-inboxes. Mail threads may cross projects/threads; so
+# we should ensure users can find more easily find them on other
+# sites.
package PublicInbox::ExtMsg;
use strict;
use warnings;
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used for generating Atom feeds for web-accessible mailing list archives.
package PublicInbox::Feed;
use strict;
use warnings;
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
#
+# Used to filter incoming mail for -mda and importers
# This only exposes one function: run
# Note: the settings here are highly opinionated. Obviously, this is
# Free Software (AGPLv3), so you may change it if you host yourself.
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: GPLv2 or later (https://www.gnu.org/licenses/gpl-2.0.txt)
+#
+# Used to read files from a git repository without excessive forking.
+# Used in our web interfaces as well as our -nntpd server.
# This is based on code in Git.pm which is GPLv2, but modified to avoid
# dependence on environment variables for compatibility with mod_perl.
# There are also API changes to simplify our usage and data set.
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
#
-# represents a header value in various forms
+# represents a header value in various forms. Used for HTML generation
+# in our web interface(s)
package PublicInbox::Hval;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used by -nntpd for listen sockets
package PublicInbox::Listener;
use strict;
use warnings;
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# For the -mda script (mail delivery agent)
package PublicInbox::MDA;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Various Message-ID-related functions.
package PublicInbox::MID;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
-# Streaming interface for formatting messages as an mboxrd
+
+# Streaming interface for formatting messages as an mboxrd.
+# Used by the web interface
package PublicInbox::Mbox;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
-# bidirectional Message-ID <-> Article Number mapping
+
+# bidirectional Message-ID <-> Article Number mapping for the NNTP
+# and web interfaces. This is required for implementing stable article
+# numbers for NNTP and allows prefix lookups for partial Message-IDs
+# in case URLs get truncated from copy-n-paste errors by users.
+#
+# This is maintained by ::SearchIdx
package PublicInbox::Msgmap;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Each instance of this represents a NNTP client socket
package PublicInbox::NNTP;
use strict;
use warnings;
$self->do_write($data);
}
-# callbacks for by Danga::Socket
+# callbacks for Danga::Socket
sub event_hup { $_[0]->close }
sub event_err { $_[0]->close }
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used only by the NNTP server to represent a public-inbox git repository
+# as a newsgroup
package PublicInbox::NewsGroup;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
# based on notmuch, but with no concept of folders, files or flags
+#
+# Read-only search interface for use by the web and NNTP interfaces
package PublicInbox::Search;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
# based on notmuch, but with no concept of folders, files or flags
+#
+# Indexes mail with Xapian and our (SQLite-based) ::Msgmap for use
+# with the web and NNTP interfaces. This index maintains thread
+# relationships for use by Mail::Thread. This writes to the search
+# index.
package PublicInbox::SearchIdx;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: GPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
# based on notmuch, but with no concept of folders, files or flags
+#
+# Wraps a document inside our Xapian search index.
package PublicInbox::SearchMsg;
use strict;
use warnings;
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Displays search results for the web interface
package PublicInbox::SearchView;
use strict;
use warnings;
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used for displaying the HTML web interface.
+# See Documentation/design_www.txt for this.
package PublicInbox::View;
use strict;
use warnings;
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
#
+# Main web interface for mailing list archives
+#
# We focus on the lowest common denominators here:
# - targeted at text-only console browsers (w3m, links, etc..)
# - Only basic HTML, CSS only for line-wrapping <pre> text content for GUIs
#!/usr/bin/perl -w
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Initializes a public-inbox, basically a wrapper for git-init(1)
use strict;
use warnings;
my $usage = "public-inbox-init NAME GIT_DIR HTTP_URL ADDRESS [ADDRESS..]";
#!/usr/bin/perl -w
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used for training spam (via SpamAssassin) and removing messages from a
+# public-inbox
my $usage = "$0 (spam|ham) < /path/to/message";
use strict;
use warnings;
#!/usr/bin/perl -w
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Mail delivery agent for public-inbox, run from your MTA upon mail delivery
use strict;
use warnings;
my $usage = 'public-inbox-mda < rfc2822_message';
#!/usr/bin/perl -w
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Standalone NNTP server for public-inbox.
use strict;
use warnings;
require PublicInbox::Daemon;
#!/usr/bin/perl -w
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Enables using PublicInbox::WWW as a CGI script
use strict;
use warnings;
use IO::Handle;