From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-2.8 required=3.0 tests=ALL_TRUSTED,AWL,BAYES_00, URIBL_BLOCKED shortcircuit=no autolearn=unavailable version=3.3.2 X-Original-To: meta@public-inbox.org Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 737801F727 for ; Sat, 26 Dec 2015 23:00:09 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH 2/2] doc: minor updates to trim down the README Date: Sat, 26 Dec 2015 23:00:07 +0000 Message-Id: <1451170807-23970-3-git-send-email-e@80x24.org> In-Reply-To: <1451170807-23970-1-git-send-email-e@80x24.org> References: <1451170807-23970-1-git-send-email-e@80x24.org> List-Id: We'll continue developing and supporting ssoma, but it's unlikely to gain much adoption in its current form; so stop cluttering up our own README with it. --- HACKING | 10 +++++++- INSTALL | 3 ++- README | 84 ++++++++++++++++++++++++++--------------------------------------- 3 files changed, 44 insertions(+), 53 deletions(-) diff --git a/HACKING b/HACKING index ce04b3e..46f8a3e 100644 --- a/HACKING +++ b/HACKING @@ -1,7 +1,15 @@ hacking public-inbox -------------------- -Send all patches via to our self-hosting list at meta@public-inbox.org +Send all patches via to our self-hosting inbox at meta@public-inbox.org +It is archived at . + +Please consider our goals in mind: + + Accessibility, Compatibility, Performance + +These goals apply to everyone: users viewing over the web or NNTP, +sysadmins running public-inbox, and other hackers working public-inbox. See design_www.txt and design_notes.txt in the Documentation/ directory for design decisions made during development. diff --git a/INSTALL b/INSTALL index a2d9fdc..bb68294 100644 --- a/INSTALL +++ b/INSTALL @@ -1,7 +1,8 @@ public-inbox (server-side) installation --------------------------------------- This is for folks who want to setup their own public-inbox instance. -Clients should see http://ssoma.public-inbox.org/INSTALL.html instead. +Clients should see http://ssoma.public-inbox.org/INSTALL.html instead +if they want to import mail into their personal inboxes. TODO: this still needs to be documented better, also see the scripts/ and sa_config/ directories in the source tree diff --git a/README b/README index 8ae307a..4c405ac 100644 --- a/README +++ b/README @@ -2,10 +2,7 @@ public-inbox - an "archives first" approach to mailing lists ------------------------------------------------------------ public-inbox implements the sharing of an email inbox via git to complement or replace traditional mailing lists. Readers may -subscribe to a mailing list using ssoma[1] (a git-wrapper) to -import email from a git repository into an IMAP folder, Maildir, -or mbox. Readers may also read via NNTP, Atom feeds and HTML -archives. +read via NNTP, Atom feeds or HTML archives. public-inbox spawned around three main ideas: @@ -22,9 +19,8 @@ to run their own instances with minimal overhead. Implementation -------------- public-inbox uses ssoma[1], Some Sort Of Mail Archiver which implements -no policy of its own. By exposing an inbox via git, readers may follow -the inbox without subscribing via SMTP and have easy access to old -messages. +no policy of its own. By storing (and optionally) exposing an inbox +via git, it is fast and efficient to host and mirror public-inboxes. Traditional mailing lists use the "push" model. For readers, this requires commitment to subscribe and effort to unsubscribe. New readers @@ -32,42 +28,46 @@ may also have difficulty following existing discussions if archives do not expose Message-ID headers for responses. List server admins may be burdened with delivery failures. -public-inbox uses the "pull" model. Readers import mail into an mbox, -Maildir, or IMAP folder from git repositories periodically. If a reader -loses interest, they simply stop syncing. Since we use git, mirrors are -easy-to-setup, and lists are easy-to-relocate to different mail -addresses without losing/splitting archives. Dedicated readers only -need to install ssoma, a command-line tool[1] currently implemented in -Perl. +public-inbox uses the "pull" model. Casual readers may also follow +the list via NNTP, Atom feed or HTML archives. + +Users of the ssoma[1] command-line tool may import mail into an mbox, +Maildir, or IMAP folder from git repositories periodically. + +If a reader loses interest, they simply stop syncing. -Casual readers may also follow the list via NNTP, Atom feed or -HTML archives. +Since we use git, mirrors are easy-to-setup, and lists are +easy-to-relocate to different mail addresses without losing/splitting +archives. -_Anybody_ may also setup a delivery-only mailing list server to replay -a public-inbox git archive to subscribers via SMTP. +_Anybody_ may also setup a delivery-only mailing list server to +replay a public-inbox git archive to subscribers via SMTP. [1] http://ssoma.public-inbox.org/ Features -------- * anybody may participate via plain-text email -* stores email in git, readers have a complete archive of the inbox -* Atom feed allows casual readers to follow via feed reader -* Mail user-agent (MUA) users may use Maildir, mbox(5) and/or IMAP locally +* stores email in git, readers may have a complete archive of the inbox +* Atom feed and NNTP allows casual readers to follow via feed reader * uses only well-documented and easy-to-implement data formats Try it out now, see http://try.public-inbox.org/ -Requirements (Atom, read-only client) -------------------------------------- -* any feed reader capable of following Atom feeds +Requirements for reading: + +* any software capable of NNTP or following Atom feeds Any basic web browser will do for the HTML archives. +We primarily develop on w3m to maximize accessibility. Requirements (participant) -------------------------- -* ssoma - http://ssoma.public-inbox.org/ + * any MUA which may send text-only emails ("git send-email" works!) + Users are strongly encouraged to use the "reply-all" feature of + their mailers to reduce the impact of a public-inbox as a SPOF. + * participants do not need to install public-inbox, only server admins Requirements (server) @@ -96,31 +96,18 @@ subscription. This also makes it easier to rope in folks of tangentially related projects we depend on (e.g. git developers on git@vger.kernel.org). -You may subscribe via ssoma(1), LISTNAME is a name of your choosing: - - URL=git://public-inbox.org/meta - LISTNAME=public-inbox - - # to initialize a maildir (this may be a new or existing maildir, - # ssoma will not touch existing messages) - # If you prefer mbox, use "ssoma add mbox ..." instead - ssoma add $LISTNAME $URL maildir:/path/to/maildir/ +The archives are readable via NNTP or HTTP: - # read with your favorite MUA (only using mutt as an example) - mutt -f /path/to/maildir # (or /path/to/mbox) + nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta + http://public-inbox.org/meta/ - # to keep your mbox or maildir up-to-date, periodically run the following: - ssoma sync $LISTNAME +You may also clone all messages via git: - # your MUA may modify and delete messages from the maildir or mbox, - # this does not affect ssoma functionality at all + git clone --mirror git://public-inbox.org/meta.git - # to sync all your ssoma subscriptions via cronjob - ssoma sync --cron +Or pass the same git repository URL for ssoma using the instructions at: -HTML inbox archives are available: http://public-inbox.org/meta/ -The archives are also readable via NNTP: - nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta + http://ssoma.public-inbox.org/README.html Anti-Spam --------- @@ -128,12 +115,7 @@ The maintainer of public-inbox has found SpamAssassin a good tool for filtering his personal mail, and it will be the default spam filtering tool in public-inbox. -Readers may also use a custom mail-delivery-agent for delivery to enable -spam filtering by having ssoma deliver to a command via pipe. - -There is unlikely to be any tool which is 100% accurate at classifying -spam, so it is possible to remove messages using the ssoma-rm(1) tool -in ssoma. +See http://public-inbox/dc-dlvr-spam-flow.html for more info. Content Filtering ----------------- -- EW