various documentation updates

We have an HTML homepage, OMG!

mda: rename PI_FAILBOX to PI_EMERGENCY

The emergency destination may be Maildir.  A Maildir emergency
destination is better for volatile data which is written to
and deleted-from frequently.

cgi: index pages allow iterating some pagination

This allows WWW readers to slowly page through the entire history
of the mailing list.

view: fix regression in standalone /^>$/ lines

The lack of trailing whitespace in quote prefixes threw us
off and cause t/view to fail.

This failure was caused by
commit fefea3d7d2484ffbf433aec0dd80026aa7120e07
("ensure per-message short quotes do not get too long")
and not caught before pushing because I failed to run
"make", only "prove" (and not even "prove -l" :x).

ensure per-message short quotes do not get too long

Sometimes a single long word or URL can lengthen the line
too much.

cgi: sort HTML index by most recent date

This is hopefully the most user-friendly method.

view: remove pointless self-linkage

It is pointless to link to ourselves.

view: fix title of HTML views

We need to take care to escape everything properly to avoid
HTML/JS injections.

add example for CGI with Ruby WEBrick

Some people like old-fashioned Ruby and WEBrick is in the Ruby
standard library, so widely available.

view: inline shorter quotes

Breaking up short quote messages at 1 line is too disconcerting,
try 5 lines as proper quotes shouldn't be too long.

cgi: implement suffix-less Message-ID redirects

This may be easier in some cases for copy+paste, but not 100%
reliable in case the .txt and .html suffixes are in the Message-ID
itself.

cgi: include HTTP status in error message body

This makes it slightly easier for out-of-the-box curl users since
curl does not report or show the error by default.

HTML: various encoding fixups

Feed: add bug note on memory cycle

This affects users of long-lived processes (FastCGI/Plack)

Revert "cgi: relax path restriction for top-level"

CGI mounts should probably handle this internally.  We're reverting
this since it adds too much potential for abuse with fake/extra
prefixes in the URL.  We also need to reorder our redirect handling
as a result.

This reverts commit c394de9f2c91c2c5ed1f7832a5a7cc0206120b7f.

cgi: correct links to folded quotes

Lightly tested, but this seems to work OK.

view: finish HTML in per-message pages

cgi: support /all.html page with inline threads

Maybe this increases readability for now.

HTML: use shorter URLs in indices

Long URLs are not needed for HTML pages, but may be for feeds since
they're often resyndicated and not consumed by the browser.

HTML: ensure hrefs are quoted properly

We may be breaking some parsers or allowing more breakage
to slip through without quotes.  We waste some bytes, though.

mda: encoding-aware From: for GIT_ authorship

Users with non-US-ASCII compatible names were not showing
up properly in "git log" output.

scripts/import_gmane_spool: preserve delivery order

Unfortunately, this means we get rid of parallelization,
as we need to preserve delivery order so HTML indices look
chronological.  Order may also affect spam filtering and
training, too.

doc: add notes on scalability

Fortunately, most mailing lists will never grow too large.

doc: fold philosophy into the README

Hopefully this makes the scope and intent of the project clearer.

rename list from "bugs" to "meta"

"bugs" might confuse and limit the discussion, so "meta" it is!

mda: add most RFC 2919 and 2369 headers

These probably make sense even though we do not handle
delivery ourselves.  It can aid in searching/filtering/tagging
of messages.

derive -primary_address in config

This may be useful for generating List-Id headers and HTML pages.

cgi: fix up top-level index

We do not have all messages in the top-level index
(and we need to adjust the test while we're at it).

cgi: 301 for list-indices without trailing slash

It is common to type upper-level URLs without the slash,
redirect users to the correct page for usability.

t/cgi: cleanup: no need for additional block

Not sure what I was thinking...

cgi: ensure we unescape MIDs correctly in URLs

MIDs may have strange characters in them, so we need to handle
escaping/unescaping properly to avoid broken links or worse.

cgi: avoid parsing ENV directly for PATH_INFO

This might make it easier to go to non-CGI things.

cgi: relax path restriction for top-level

We may have something like /foo.cgi/m/$MID.html in there.

cgi: rename to have .cgi suffix

This makes it easier to configure for systems which
determine a script is a CGI script based on suffix.

scripts/import_gmane_spool: misc updates

We may promote this to be a real script, since public-inbox-mda
is idempotent.

view: trim_message_id consistently

Message-IDs could have embedded '<' and '>'

config: support multiple addresses for a inbox

This makes it possible to gradually migrate to new address in case
of list name changes, and is one step closer to operating in
"stealth hijack mode" :)

add spam/ham learning wrapper script

This is essential for integrating into my inotify-based
spam training setup.

Documentation/design_notes: more updates

Laziness \o/

(Then impatience and hubris :)

filter: clarify regular expression

I often forget the subtleties of Perl regexps and newlines,
so I suspect others do, too.  Use explicit capture so it's
more familiar to users of non-Perl regexps.

cgi: wire up HTML pages for messages

These need better tests and verification, but it's something
for now.

cgi: update feed/view and tests for shorter URLs

Code should be consistent with the design docs
(and we will need better tests).

cgi: add one-line descriptions for subroutines

Hopefully it's slightly easier-to-follow this way.

cgi: /$LISTNAME/ and /$LISTNAME/index.html are equal

This prevents ambiguity when switching URLs between static
file servers and CGI.

The /$LISTNAME/index.html URL appearing in the wild is inevitable
because of our static file server support.  Worst yet, there's
no easy/consistent way to get all installations detect and 301
them to the shorter /$LISTNAME/.  So we make the CGI support
/$LISTNAME/index.html.

The downside of this is the potential duplicate entry in all caches.

cgi: be strict about UTF-8 encoding in HTML and XML

Hopefully this forces us to generate valid UTF-8 data.

filter: use IPC::Run and improve lynx error handling

We may occasionally encounter horrid HTML which lynx cannot
handle, so improve error reporting.

INSTALL: add lynx to install requirements

We need it for converting HTML, unfortunately.

INSTALL: update with Mail::Thread dependency

While we're at it, sort Makefile.PL and add a note to
update INSTALL, too.

cgi: implement get_mid_txt

This is essential when telling people to use something like:
curl $URL | git am

doc/design_www: add 301 URLs

We'll probably support these so they're easier-to-type and share.

cgi: wire up index + tests

Remove the specified /all.html while we're at it, we only have
/all.atom.xml because it's convenient for feed readers.

cgi: do not specify charset in Atom HTTP header

The feed itself already specifies it in XML, and we risk confusing
clients if XML::Atom::SimpleFeed changes in the future.  This also
increases consistency for CGI vs static-file serving.

cgi: remove some redundant logic

We'll be reusing more validation logic for per-message and
per-thread pages.

doc/design_www: shorten URLs as much as possible

Message-IDs are extremely long already, so try to keep them short here.

t/mda: additional precheck tests

We did not test as well as we should have.

mda: set GIT_AUTHOR_DATE in commits as well

While we're at it, write some quick tests.

mda: set GIT_{COMMITTER,AUTHOR}_{NAME,EMAIL} env

This can make it easy to query via "git log --author=..."
without extracting each message.

config: include listname on lookup

We will be using it when setting GIT_COMMITTER_NAME

mda: prevent duplicate Message-IDs from appearing

For practical purposes, Message-IDs are unique and duplicates
do not appear unless client software is broken.

Makefile.PL: add parallel test target

These tests were designed to run in parallel.

doc: split out philosophy to a different page

Hopefully a little easier to find for clients and not admins running
servers.  While we're at it, expand design_notes.

preliminary HTML index generation

Using JWZ threading might work decently for this.
Haven't checked in lynx, yet.

precheck: stricter checks including min length

We should reject values which are too short to be useful or sane.

precheck: reject messages with no subject

Composers may screw up and leave the subject out, so
reject those messages.

feed: filter out each_recent_blob wrapper

We will need it for HTML indices, too.

design_notes: various updates, including "why git?"

Things to keep in mind when working on this.

scripts/report-spam: explain design decisions

Trying my best to not forget things I wrote this years ago.

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.

cgi: cleanup dependencies

We do not need to use CGI::Util internals here.

cgi: make internal interface more Plack-like

This should make it easier to support non-CGI uses,
as well as making it easier to generate static sites.

feed: generate takes a hashref for args

Passing a giant argument list is to error prone and
hard-to-document.

doc: design_www note /full/ namespace for messages

We serve the short, abridge-quote version by default since
it is (unfortunately) common practice to over-quote on mailing lists.

view: use "original" rather than "raw"

This wording is probably clearer to everyone, and also used by at
least one other mailing list WWW interface.

view: minor cleanups

Avoid adding extraneous whitespace in HTML content, as it
increases bandwidth usage of network, disk and memory.

feed: reuse view class to display message

This reduces duplicated/similar code and hopefully makes things more
consistent.

view: all content is assumed to be displayable text

Our Filter class now passes through application/octet-stream
if it looks like text (because some mailers suck); so we
cannot trust the specified Content-Type of a message.

Makefile.PL: update dependencies

This is lightly tested.

view: use URI::Escape to escape URIs

CGI::escape is not a documented subroutine, so the chances of
it going away are higher.

feed: remove unnecessary use

We no longer use DateTime::Format::Mail.

feed: use Date::Parse to parse dates

This is a smaller module dependency-wise and should be easier-to-install
for folks with limited packaging systems or network/disk capacity.
We do not need very powerful date parsing, as bad date formats are
likely the work of spammers.

get a basic CGI feed sender running

We should be able to wire up the rest, soon.

remove failrepo config

We will just use the fallback in Email::Filter to
reduce configuration knobs.  Failed messages are failed
messages, do not classify them beyond that.

public-inbox-mda: preliminary manpage documentation

This still needs to be fleshed out.

view: implement quote folding and flesh out tests

Unfortunately, quoting is often excessive, so hide multi-line quotes
by default and provide anchored links to full messages instead.

config: add shortcut for retrieving elements

Hopefully this makes for less ad-hoc hash access in case
our config format changes.

doc: add design documentation for WWW interface

Mainly, start with URL routes since that's what users usually
see, first.

view: update IRP and MID links

We'll go with .html and .txt suffixes on MIDs to benefit
static hosting setups.

flesh out MDA and simplify config setup

We will be reusing the config parsing code for the CGI
script, too.

precheck uses recipient argument

We will also be using the RECIPIENT env in the future, since
that takes aliases into account.

Reducing the possible callsites to check ENV means we can more
easily update the code in the future.

README: various updates

filter: use regexp to check multipart bodies

This should be safer than running file(1), which has had its share
of vulnerabilities this year (early 2014) We really only care about
diffs and maybe short log files, here.

filter: possibly keep PGP sigs only (not other types)

We may keep PGP signatures for messages we do not modify.
However, we have no way of verifying them on the server-side.

design_notes: with philosophy

filter: use file(1) to detect mime type if octet-stream

Some mailers do not correctly detect/set the Content-Type header; so
attempt to keep messages based on our server-detected MIME type if
application/octet-stream was specified.

config: revamp API and implement lookup

initial cut at Atom feed generation

This should make it easier for non-ssoma users to follow.

precheck: require Message-ID to be set

Valid emails should not arrive without a Message-ID.

view: add view module to be used for rendering HTML

This is to keep content accessible to search engines.

move pre-spamc checks to PublicInbox->precheck

We may add more checks before we go to spamc.

public-inbox-mda: reject messages without From header