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.

diff --git a/Documentation/design_notes.txt b/Documentation/design_notes.txt
index a5c0bba846a22a6a9db7c702858a7bbe334dd467..6805f046d4370d62a3f535e4fee14cf15a679c09 100644 (file)
--- a/Documentation/design_notes.txt
+++ b/Documentation/design_notes.txt
@@ -76,7 +76,7 @@ Why email?
 Notes
 -----
 
 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
   contributors
 
 Copyright

diff --git a/INSTALL b/INSTALL
index dd85d5e0a04474ff485c882efa24c29db1fba0e8..2b6720eb471445e1305291ceaf6a812efa4943d6 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -9,26 +9,30 @@ standard MakeMaker installation (Perl)
        make test
        make install # root permissions may be needed
 
        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
 Requirements (server MDA)
 -------------------------
 * git

+* ssoma - http://ssoma.public-inbox.org/README

 * SpamAssassin (spamc/spamd)
 * MTA - postfix is recommended
 * 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
 ---------
 
 Copyright
 ---------

diff --git a/Makefile.PL b/Makefile.PL
index 5d2f5c572bc4ca5133089fd09b3d5250f6dd73a0..7dac4924a7791aa524829c5516bf2b4f19b64429 100644 (file)
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -7,7 +7,7 @@ WriteMakefile(
        NAME => 'public-inbox',
        VERSION => '0.0.0',
        AUTHOR => 'Eric Wong <normalperson@yhbt.net>',
        NAME => 'public-inbox',
        VERSION => '0.0.0',
        AUTHOR => 'Eric Wong <normalperson@yhbt.net>',

-       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),
        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,
                'Encode::MIME::Header' => 0,
                'XML::Atom::SimpleFeed' => 0,
                'IPC::Open2' => 0,

+               'IPC::Run' => 0,

                'File::Path::Expand' => 0,
                'CGI' => 0,
                'URI::Escape' => 0,
                'File::Path::Expand' => 0,
                'CGI' => 0,
                'URI::Escape' => 0,

diff --git a/README b/README
index 28748145400388d699139545ab1d7e6bc31c5af3..fb03c6e8604f805f1c8002c8bd14edc38e74f51e 100644 (file)
--- 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
 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.
 
 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.
 
 _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
 --------
 
 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
 * 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)
 --------------------------
 
 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
 
 * 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
 -------
 
 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,
 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
 
 
        bugs@public-inbox.org