From aca047222a47e8d5277466d2dcc0618f12bdf8de Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 8 Apr 2014 08:45:25 +0000 Subject: [PATCH] doc: various cleanups all around Most notably, the INSTALL is geared towards potential server admins, whereas the README is also for interested "drive-by" readers. --- Documentation/design_notes.txt | 2 +- INSTALL | 34 +++++++++++++++++++--------------- Makefile.PL | 3 ++- README | 25 +++++++++---------------- 4 files changed, 31 insertions(+), 33 deletions(-) diff --git a/Documentation/design_notes.txt b/Documentation/design_notes.txt index a5c0bba8..6805f046 100644 --- a/Documentation/design_notes.txt +++ b/Documentation/design_notes.txt @@ -76,7 +76,7 @@ Why email? Notes ----- -* Expose Message-Id in HTML views to encourage replies from drive-by +* Expose Message-ID in HTML views to encourage replies from drive-by contributors Copyright diff --git a/INSTALL b/INSTALL index dd85d5e0..2b6720eb 100644 --- a/INSTALL +++ b/INSTALL @@ -9,26 +9,30 @@ standard MakeMaker installation (Perl) make test make install # root permissions may be needed -Requirements (MUA client) -------------------------- -* git -* ssoma - http://ssoma.public-inbox.org/README -* Perl and several modules: - - Email::LocalDelivery - - Email::Filter - - Email::Simple - - Digest::SHA - Requirements (server MDA) ------------------------- * git +* ssoma - http://ssoma.public-inbox.org/README * SpamAssassin (spamc/spamd) * MTA - postfix is recommended -* ssoma - http://ssoma.public-inbox.org/README -* Perl and several modules: - - Email::Simple - - File::FcntlLock - - Digest::SHA +* Perl and several modules: (Debian package name) + - CGI perl-modules[1] + - Date::Parse libtimedate-perl + - Email::Address libemail-address-perl + - Email::Filter libemail-filter-perl + - Email::MIME libemail-mime-perl + - Email::MIME::ContentType libemail-mime-contenttype-perl + - Encode::MIME::Header perl + - File::Path::Expand libfile-path-expand-perl + - IPC::Open2 perl + - IPC::Run libipc-run-perl + - URI::Escape liburi-perl + - XML::Atom::SimpleFeed libxml-atom-simplefeed-perl + +[1] - Only required for serving/generating Atom and HTML pages. + Keep in mind this will be split into a separate Debian package + when CGI.pm is dropped from the Perl standard library. + Plack/PSGI, FastCGI, and mod_perl2 will all be supported. Copyright --------- diff --git a/Makefile.PL b/Makefile.PL index 5d2f5c57..7dac4924 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -7,7 +7,7 @@ WriteMakefile( NAME => 'public-inbox', VERSION => '0.0.0', AUTHOR => 'Eric Wong ', - ABSTRACT => 'public-inbox.org infrastructure', + ABSTRACT => 'public-inbox server infrastructure', EXE_FILES => [qw/public-inbox-mda public-inbox-cgi/], PREREQ_PM => { # note: we use ssoma(1) and spamc(1), @@ -21,6 +21,7 @@ WriteMakefile( 'Encode::MIME::Header' => 0, 'XML::Atom::SimpleFeed' => 0, 'IPC::Open2' => 0, + 'IPC::Run' => 0, 'File::Path::Expand' => 0, 'CGI' => 0, 'URI::Escape' => 0, diff --git a/README b/README index 28748145..fb03c6e8 100644 --- a/README +++ b/README @@ -20,7 +20,7 @@ Traditional mailing lists use the "push" model. List servers deliver content via SMTP to other mail servers used by readers of the mailing list. For readers, this requires commitment to subscribe to the list and extra effort to unsubscribe. New readers may also have difficulty -following existing discussions if archives do not expose Message-Id +following existing discussions if archives do not expose Message-ID headers for responses. List server admins are also burdened with occasional bounce messages. @@ -37,12 +37,12 @@ Casual readers may also follow the list via Atom feed or web archives. _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/ +[1] http://ssoma.public-inbox.org/README Features -------- -* anybody may participate by emailing the public address -* stores email in git, so readers have a full history of the mailing list +* anybody may participate via plain-text email to the public address +* stores email in git, readers have a full archive of the mailing list * Atom feed allows casual readers to follow via feed reader * Mail user-agent (MUA) users may use Maildir, mbox(5) and/or IMAP locally * uses only well-documented and easy-to-implement data formats @@ -53,20 +53,13 @@ Requirements (Atom, read-only client) Requirements (participant) -------------------------- -* ssoma - http://ssoma.public-inbox.org/ +* ssoma - http://ssoma.public-inbox.org/INSTALL * any MUA which may send text-only emails ("git send-email" works!) * participants do not need to install public-inbox, only server admins -Requirements (server MDA) -------------------------- -* git -* MTA - postfix is recommended -* Perl and several modules: - - Email::Filter - - XML::Atom::SimpleFeed -* ssoma - http://ssoma.public-inbox.org/ -* SpamAssassin (optional, recommended) -* CGI-capable HTTP server (optional, recommended for Atom feed and archives) +Requirements (server) +--------------------- +See INSTALL Hacking ------- @@ -81,7 +74,7 @@ Contact We are happy to see feedback of all types via plain-text email. public-inbox discussion is self-hosting on public-inbox.org Please send comments, user/developer discussion, patches, bug reports, -and pull requests to our public-inbox.org address at: +and pull requests to our public-inbox address at: bugs@public-inbox.org -- 2.44.0