misc documentation updates

Threading in Xapian is mostly supported by now; so start
documenting things.

replace references to lynx

Table rendering in lynx is crap compared to w3m and links.
However, we still use it for filtering HTML since the renderer
is otherwise nice...

search: index_sync allows specifying alternate HEAD

This should allow us to sync the index to a temporary head
to update the Xapian index before we update the real HEAD
index.

view: do not fold top-level messages in thread

This hopefully reduces clicking.  We may drop folding entirely
since we can use Xapian to make searching easier.

index: layout fix + title and Atom feed links at top

Add some spacing between topics to improve readability when
scanning or in case a subject gets too long.

The title and Atom feed may not be highly-visible otherwise.
While we're at it, use the proper "Atom feed" terminology since
some folks may not understand just what "atom" means.

search: bump schema version to 5 for subject_path

In "index: simplify main landing page if search-enabled",
subject normalization went a little farther to drop trailing
'.' characters, so we will need to re-index.

view: reduce memory usage when displaying large threads

We want to minimize the time any large objects or strings
are referenced.  We can do threading entirely from the
mini_mime-generated messages and lazilly load full messages
when rendering the display.

search: reject ghosts in all cases

We do not need ghost messages in any of our thread views

search: avoid needless decode

Email::MIME should handle everything for us and make things
work nicely with Xapian (assuming I understand how encoding
works in Perl).

While we're at it, reduce temporary strings and arrays by
using destructive operations and clobbering parts as we
iterate through them.

index: simplify main landing page if search-enabled

We can display /t/$MESSAGE_ID.html easily with a Xapian search
index, so rely on it instead of trying to display messages inline.

view: avoid nesting <a> tags from auto-linkification

It is wrong HTML to have <a> tags nested due to auto-linkification.

use tables for rendering comment nesting

This is more space efficient since we don't need to place padding
bytes in front of every line.  While this unfortunately does not
render well on lynx; w3m, links, elinks can all render tables
sanely.

Tables are also superior for long lines which require wrapping
inside <pre> containers.

feed: move timestamp parsing to view

We don't need share duplicate logic across both files.

feed: remove threading from index

We'll be making the index smarter for people with search
support enabled.  Otherwise, it'll be chronological and
a bit dumb.  At least it'll use less memory.

www: redirect /f/$MESSAGE_ID.txt links to /m/$MESSAGE_ID.txt

Some people (e.g. myself :p) may try to guess URLs and hit a
404.  Redirect to the /m/ version.

Note: we prefer to redirect to canonical URLs to improve
caching.

view: return empty string to avoid undefined values

Sometimes we have filter bugs and let HTML slip through...

view: fix spacing on missing ghosts

We must not prematurely indent if we have no message header to
display.

view: close anchor tag correctly before starting another

Noticed by tidy

public-inbox-index: exit with usage if not given an arg

I often forget how to use this myself :x

thread: another workaround for a Mail::Thread bug

Yay for monkey patching!

ref: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=795913
ref: https://rt.cpan.org/Ticket/Display.html?id=106498

search: bump SCHEMA_VERSION to 4

The following two commits affect indexing behavior, so
change the schema version to avoid compatibility problems
or missing messages:

search: common Subject: normalization for Re: prefixes
search: avoid creating ghosts for circular References

search: expose $PublicInbox::Search::LANG variable

This makes it easier to reconfigure for non-English users

search: common Subject: normalization for Re: prefixes

Drop German ("Aw:") support since it's non-standard and
is not supported by Mail::Thread and non-English prefixes
are more likely to conflict with prefixes used in Free Software
development where ("subsection:") prefixes are common and English is the
common language.

Anyways we don't filter "Vs: " (Finnish) or "Sv: "
(Norwegian, Swedish, Danish, Icelandic), either.

ref:
https://en.wikipedia.org/wiki/RE_(e-mail)#Abbreviations_in_other_languages

search: avoid creating ghosts for circular References

Some mail software incorrectly creates circular references
and causes us to create ghosts before the actual mail doc
is created.

view: cleaner Message-ID filtering for References

Avoid compiling a weird and potentially fragile regexp every
time and use the same logic as our search module to dedupe
References.

view: do not recompress already-compressed MID for anchors

This is merely for display, so on the off chance somebody does
send a 40-byte MID with nothing but hexadecimal characters,
the worst that could happen is we repeat an anchor name in the
rendered HTML.  This has no impact on git archival or Xapian
indexing.

search: simplify indexing operation

There's no need to make a transaction for each message when doing
incremental indexing against a git repository.  While we're at it,
simplify the interface for callers, too and do not auto-create
the Xapian database if it was not explicitly enabled.

public-inbox-{learn,mda}: automatically sync index

We'll ignore errors, for now, but should eventually warn or
log.  And yes, this is a dirty, dirty hack but we'll fix this
ASAP tomorrow.

view: always compress Message-IDs for anchors

Valid URLs do not make valid anchor ids.

search: bump schema version for '%' compression change

commit 0fea7793b22efd2596983283947ee43687e0cfac
("mid: compress Message-IDs with '%' in them")
requires re-indexing of repositories with '%' in Message-IDs :<

mid: compress Message-IDs with '%' in them

Some HTTP servers (apache2 2.2.22-13+deb7u5) on my system
apparently do not handle "%25" correctly.  I'm not yet sure if
it's something weird with my rewrite rules or what....

search: apply mid_compression to subject paths, too

Otherwise we'll be wasting space in our index for long
subjects.

drop bodies and messages ASAP after processing

We can rely on reference counting to lower memory usage for
big messages.

feed: disable the generator statement

No need to waste bandwidth, here

search: use raw headers without MIME decoding

This should be less error-prone in case somebody tries to screw with
us and our thread_id mechanism or somehow waste our resources.
Unfortunately Mail::Thread isn't smart enough for this, yet, so we
may need to downgrade to Email::Simple objects as a workaround.

Or simply not worry about the display so much if somebody is
intentionally trying to make it thread badly/incorrectly.

terminology: replies => followups

Replies are only direct replies, but followups could be any message
further down the thread.  The latter is more useful.

www: simplify parameter passing to feed

No need to create a new hash when we can reuse the existing one
more.

WWW: eliminate "top" parameter for feeds

This parameter hasn't been used since
commit 5adf8d639e9b5abd4cbac975d70ddc0fb76541fc
("feed: dead code elimination around dropped endpoints")

favor /t/ to /s/, since subjects may change mid-thread

/t/ always falls back to subject path searching anyways,
so there's little lost besides perhaps more readable URLs.
Unfortunately people still use non-compliant mail clients which fail
to set In-Reply-To or References headers :<

feed: remove unnecesary time paramenter in index state

We no longer do "smart" time displays as of
commit ea0e8649f90d1fd0850a41c0ca16642faadf4f14
("view: simplify timestamp generation").

In retrospect, that commit also made us more cache-friendly, too.

skip search test if search support is missing

We will not require Search::Xapian to be installed.

Merge remote-tracking branch 'origin/search'

* origin/search:
  view: deduplicate common code for loading search results
  SearchMsg: ensure metadata for ghost messages mid
  implement /s/$SUBJECT_PATH.html lookups
  search: remove unnecessary xpfx export
  www: /t/$MESSAGE_ID.html for threads
  view: hoist out index_walk function
  view: reply threading adjustment
  thread: common sorting code
  view: display replies in per-message view
  search: make search results more OO
  extract redundant Message-ID handling code
  search: implement index_sync to fixup indexer
  initial search backend implementation

view: kill leading empty lines correctly

Was too sleepy to be coding last night :x

view: cleaner killing of leading/trailing whitespace

No point in wasting bytes even if gets compressed over
the wire, it'll use more memory when rendering on the
client.

view: hoist out index_walk function

We will reuse it for thread views when powered by Xapian.

view: deduplicate common code for loading search results

More to come later.

SearchMsg: ensure metadata for ghost messages mid

Ghosts have no document data in them.
Perhaps we should just rely on terms for Message-ID
and avoid storing that in the document data...

implement /s/$SUBJECT_PATH.html lookups

Quick-and-dirty wiring up of to Subject: paths.
This may prove more memorizable and easier-to-share than
/t/$MESSAGE_ID.html links, but less strict.

This changes our schema version to 1, since we now
use lower-case subject paths.

search: remove unnecessary xpfx export

SearchMsg calls it with the full module path anyways.

www: /t/$MESSAGE_ID.html for threads

This should bring up nearly the entire thread a given
Message-ID is linked to.

view: hoist out index_walk function

We will reuse it for thread views when powered by Xapian.

view: reply threading adjustment

Give changes in subject their own line to reduce line wrapping,
but avoid showing any redundant subjects by maintaining a hash
of subjects already displayed.

thread: common sorting code

We'll be sharing the same threading, so it makes sense to sort
replies using the same code and message headers without repeating
ourselves.

This also standardizes on sorting on X-PI-TS (Unix epoch in seconds)
instead over using X-PI-Date differently in two different places

view: display replies in per-message view

This can be used to quickly scan for replies in a message without
displaying an entire thread.

search: make search results more OO

This will relieve callers of the need to decode the data
we store internally in Xapian

extract redundant Message-ID handling code

Quit repeating ourselves and use a common MID module
instead.

search: implement index_sync to fixup indexer

We need to make the indexer executable and installable
while we're at it.

initial search backend implementation

This shall allow us to search for replies/threads more easily.

view: consistent ordering of Cc: addresses

This fixes a minor test failure in t/cgi.t

Tested with perl 5.18.2-2ubuntu1 on Ubuntu 14.04.3 LTS

view: remove unused $enc_mime Encoding object

Unneeded since commit e022d3377fd2c50fd9931bf96394728958a90bf3
("huge refactor of encoding handling")

view: pass fallback encoding to enc_for

This fixes the fallback to message encoding if the message
itself was not UTF-8

public-inbox-learn: preserve headers for ham injection

We must inject headers properly for injecting ham, otherwise
List-Id headers get dropped.

view: simplify timestamp generation

It's seems less ambiguous to parse a consistent in quiet lists
where messages are sparse.

feed: extract subroutines for threading

We'll be using this in the future for displaying per-thread
views.

scripts/dc-dlvr.pre: ensure stderr gets back to the MTA

We want to be able to reject errors back to the MTA.

reject HTML loudly and automatically

This should hopefully reduce the delay between when a user fails
to send plain-text to when an admin such as myself notices the
HTML mail in a sea of spam.

Unfortunately, this can lead to backscatter, so avoid doing it
until its passed through spamc, at least.

feed: compile regexps only once

This avoids some runtime penalties associated with recompiling
a regexp based on a constant local variable.

view: reduce empty <a>, use "id" instead of "name" attributes

This is probably more compliant, and saves us a few bytes
on the uncompressed HTML.

feed: close body tag correctly in index

Oops, noticed by manual inspection.  One day we'll run tidy in tests
to validate.

public-inbox-mda: preserve SpamAssassin headers in spam

We want to be able to prioritize spam downstream to check for
borderline cases.

view: fix linkification and quote-folding conflicts

We can't add newlines to links, unfortunately, because
quote-folding is line-based and (being regexp-based) needs
to happen after linkification.

view: generate links for common protocols in browsers

SpamAssassin queries URI blacklists, so it's probably OK
to enable this without being used as a linkfarm.

doc/design_www: remove item for auto-generated links

SpamAssassin queries URI blacklists, so it's probably OK
to start generating links in the future...

import_slrnspool: fork a process for each message

This prevents process growth when importing large messages.
Memory growth could be due to the sliding sbrk window in glibc malloc
or a circular reference in the Email::* Perl code somewhere.

import_slrnspool: load private config key

PublicInbox::Config->lookup won't return unknown keys

import_slrnspool: graceful exit for interruptibility

This should alleviate fears of interrupting the process.

import_slrnspool: make filtering optional

import_slrnspool: use ssoma-mda instead

Some mailing lists (e.g. git@vger.kernel.org) accept messages
via Bcc: and possibly other things which get rejected by
the strict PublicInbox::Filter rules.  So rely on ssoma-mda
instead.

This prefers a recent revision of ssoma-mda (commit 7fce38e9
onwards) to display subject/author/date information in the
commit message.

.gitignore: relax MYMETA pattern

Newer systems may use .json instead of .yml

filter: handle missing Content-Type

Some mailers may omit the Content-Type header entirely,
so do detection and try to get the message through.

*slrnspool* old gmane archives set Original-To

Apparently it's not a problem with recent archives.

import_slrnspool: fix off-by-one error

We start with zero and only store the next valid ID.

scripts/import_slrnspool: new incremental importer

This allows incremental imports of slrn spools, ideal for
tracking lists via gmane.

doc: generate README.html instead of index.html

This allows us to generate links without caring about discoverability
and remains reasonably WYSIWYG for folks editing our documentation in
their favorite $EDITOR

Documentation/txt2pre: support #fragments and ftp://

Occasionally we'll use these for links.

-learn: nuke HTML portions when training as ham

Sometimes people send HTML email and I forget to fixup in my
MUA during moderation.  Automatically strip out HTML portions
instead.

view: account for filter bugs which leak HTML into the repo

Ugh, apparently there's a (yet-to-be-fixed) bug in the Filter
code which caused an HTML message portion of a multipart message
to be displayed on the web UI.  Account for that and nuke it.

view: add time to entries older than one day

This is occasionally useful and we're not as starved for screen
space now now that sender+timestamps are on a separate line.

view: rename "permalink" to "threadlink"

These may not be permanent, after all.
Better threading support can be done for message views, so
and the current index layout is still too busy and suboptimal.

examples/public-inbox.psgi: add usage to comments

I often forget how to run this

view: show raw message link as "raw"

"original" is a bit misleading, since we strip needless junk
like HTML from messages before it ever hits git.

TODO: add mlmmj integration item

Because some folks will want to receive email.

doc: add TODO to the website

TODO: add a placeholder for search

While we're at it, fix up a typo.

view: tweak attribution line

This reduces unnecessary white space and consistently places
the attribution under the Subject.

view: make the thread index less claustrophobic

At the cost of some vertical whitespace.

More bikeshedding...

public-inbox-init: fix multi-address setup

We must support multi-address mailing lists, so we do not
clobber existing addresses.  However, we need to ensure
idempotency and ensure existing addresses are not reset.

Furthermore, we were not parsing the existing config correctly
due to a leaking $/.

view: relax line break detection

Often times any succession of "---" denotes the rest of the
message is too long to review at once.

public-inbox-init: manages the config files

This hopefully allows easier setup.

filter: ensure CRs do not show up in lynx conversions

Unix line endings are LF-only, so do not introduce or preserve
CRLF line endings when reading from lynx.