doc: update release notes, marketing, and install

INSTALL now covers more of lei since I'm less uncomfortable
about it for 2.0 and points users towards the install/ helpers
if installing from source.

4 files changed, 107 insertions, 35 deletions

diff --git a/Documentation/RelNotes/v2.0.0.wip b/Documentation/RelNotes/v2.0.0.wip
index c473e8d7..53ef5fe5 100644
--- a/Documentation/RelNotes/v2.0.0.wip
+++ b/Documentation/RelNotes/v2.0.0.wip
@@ -6,7 +6,8 @@ Content-Disposition: inline
 
 This release includes several new features and fixes; mostly
 around improved integration between inboxes and coderepos for
-solver.  Portability and reliability is also improved.
+solver.  Portability and reliability is also improved, especially
+in the internal process management of lei.
 
 public-inbox-cindex is a new command to index coderepos for
 WWW search and perform automatic associations between
@@ -39,13 +40,22 @@ Compatibility:
   entries if `newsgroup' isn't specified) will also generate warnings
   since they break -extindex and the new -cindex (coderepo index).
 
+New users + hackers:
+
+  The install/ directory includes tools to automate installation and
+  removal of dependencies for stripped down or full setups.  See
+  install/README for more details
+
 treewide
 
   * support raw UTF-8 headers from SMTPUTF8 hosts
 
   * standardize on `#' prefix for stderr diagnostics (previously `I:')
 
-  * SHA-256 coderepos are fully-supported (inboxes not yet)
+  * SHA-256 coderepos are fully-supported (but not inboxes, yet)
+
+  * jemalloc (tested as an LD_PRELOAD) is recommended to reduce fragmentation
+    in long-running daemon processes serving unpredictable traffic
 
 PublicInbox::WWW
 
@@ -71,12 +81,18 @@ PublicInbox::WWW
 
   * add topics_(new|active).(html|atom) endpoints
 
+  * linkify peer public-inbox addresses in To/Cc headers
+
+public-inbox-watch:
+
+  * watching MH folders is now supported
+
 lei
 
   * use http.proxy / http.<remote>.proxy from system-wide git-config if
     unconfigured for lei
 
-  * improve IMAP error reporting
+  * improve IMAP and NNTP error reporting
 
   * reduce default IMAP connections to avoid overloading servers
 
@@ -94,10 +110,16 @@ lei
 
   * improved bash completion for labels (see contrib/completion)
 
+  * support for reading (but not writing) MH folders
+
+  * `lei index' accepts `+L:$LABEL' like `lei import' does
+
 solver (used by lei (rediff|blob), and PublicInbox::WWW)
 
   * handle copies in patches properly
 
+  * no longer redundantly parallelized within each WWW process
+
 portability
 
   * SIGWINCH is handled properly on less common architectures and OSes
@@ -112,6 +134,12 @@ portability
   * support Alpine Linux, Dragonfly, NetBSD and OpenBSD.  This resulted
     not only in bugfixes to our code, but also to Dragonfly and OpenBSD.
 
+  * Inline::C||Socket::MsgHdr no longer required for SCM_RIGHTS
+    with sendmsg/recvmsg on supported *BSDs.
+
+  * inotify support no longer requires Linux::Inotify2 XS package
+    for most architectures
+
 public-inbox-pop3d
 
   * support `limit=NUM' and `initial_limit=NUM' query parameters
@@ -144,9 +172,19 @@ Search improvements (lei and PublicInbox::WWW)
 
   * quoted text inside base-85 binary patches is no longer indexed
 
+  * `public-inbox-cindex --join' prefers using Xapian's C++ API
+    directly to avoid Perl method dispatch overhead to get usable
+    performance assocating ~300 inboxes with over 1K coderepos
+    (and vice-versa).  Users needing this performance will need
+    a C++ compiler, pkg-config, and the Xapian development files
+    (see INSTALL).
+
+    This C++ helper will be used more heavily in the future
+    to enable query parser customizations and other functionality
+    unavailable from the Xapian SWIG or XS bindings.
 
 Thanks to all the bug reporters and users who made this release
-possible.
+possible, and thanks for bearing with my anxiety over making releases.
 
 Please report bugs via plain-text mail to: meta@public-inbox.org
 
diff --git a/Documentation/marketing.txt b/Documentation/marketing.txt
index 385e5172..8e4aa3b5 100644
--- a/Documentation/marketing.txt
+++ b/Documentation/marketing.txt
@@ -3,7 +3,9 @@ marketing guide for public-inbox
 TL; DR: Don't market this.
 
 If you must: don't be pushy and annoying about it.  Slow down.
-Please no superlatives, hype or BS.
+Please no superlatives, hype or BS.  Please keep all marketing
+materials text-only to be accessible to those on slow networks
+and ancient hardware.
 
 It's online and public, so it already markets itself.
 Being informative is not a bad thing, being insistent is.
@@ -25,3 +27,12 @@ than the adoption of any software.
 
 Every time somebody recognizes and rejects various forms of
 lock-in and centralization is already a victory for us.
+
+Please keep in mind:
+
+* Perl 5 is not a well-liked language
+* AGPL is not a well-liked license
+* maintainer is a shy introvert
+
+Be sure to mention these things in any marketing materials
+to avoid wasting time of people who hate Perl and/or AGPL.
diff --git a/INSTALL b/INSTALL
index c5d69d1b..b1d7fd1b 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,11 +1,15 @@
-public-inbox (server-side) installation
----------------------------------------
+public-inbox / lei installation
+-------------------------------
 
-This is for folks who want to set up their own public-inbox instance.
-Clients should use normal git-clone/git-fetch, IMAP or NNTP clients
-if they want to import mail into their personal inboxes.
+This is for people who want to run public-inbox on their server or
+lei as a command-line tool.  Any HTTP, IMAP, NNTP, or POP3 client can
+access public-inbox servers, as can git-{clone,fetch} on the HTTP(S)
+endpoint.
 
-As of 2023, public-inbox is packaged by several OS distributions,
+Since our marketing sucks, ease-of-installation is an important goal
+for this project and we only depend on distro-provided packages.
+
+As of 2024, public-inbox is packaged by several OS distributions,
 listed in alphabetical order: Debian, GNU Guix, NixOS, and Void Linux.
 
 public-inbox is developed on Debian GNU/Linux systems and will
@@ -14,12 +18,18 @@ the "oldstable" distribution, currently Debian 11.x ("bullseye"),
 but older versions of Debian remain supported (as are newer ones).
 
 Most packages are available in other GNU/Linux distributions,
-FreeBSD, NetBSD, and OpenBSD.  CentOS 7.x users will likely want
-newer git and Xapian for better performance and v2 inbox support:
+Alpine Linux, FreeBSD, NetBSD, OpenBSD, and DragonflyBSD.
+CentOS 7.x users will likely want newer git and Xapian for
+better performance and v2 inbox support:
 https://public-inbox.org/meta/20210421151308.yz5hzkgm75klunpe@nitro.local/
 
-TODO: this still needs to be documented better,
-also see the scripts/ and sa_config/ directories in the source tree
+As of 2.0, install/deps.perl makes it easier to install target
+dependencies needed for certain features.  See install/README in
+the source tree for more info.
+
+Also see sa_config/ directories in the source tree for recommended
+SpamAssassin configuration examples if using public-inbox-mda or
+public-inbox-watch.
 
 Requirements
 ------------
@@ -43,22 +53,10 @@ Beyond that, there is one non-standard Perl package required:
                                    rpm: perl-URI
                                    (for HTML/Atom generation)
 
-Plack and Date::Parse are optional as of public-inbox v1.3.0,
-but required for older releases:
-
-* Plack                            deb: libplack-perl
-                                   pkg: p5-Plack
-                                   rpm: perl-Plack, perl-Plack-Test,
-                                   (for HTML/Atom generation)
-
-- Date::Parse                      deb: libtimedate-perl
-                                   pkg: p5-TimeDate
-                                   rpm: perl-TimeDate
-                                   (for broken, mostly historical emails)
-
 Where "deb" indicates package names for Debian-derived distributions,
-"pkg" is for the FreeBSD package (and some other common BSDs, too), and
-"rpm" is for RPM-based distributions (only known to work on Fedora).
+"pkg" is for the FreeBSD package (and some other common BSDs, too),
+"pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
+distributions (only known to work on Fedora).
 
 Numerous optional modules are likely to be useful as well:
 
@@ -71,7 +69,14 @@ Numerous optional modules are likely to be useful as well:
                                    pkg: p5-Xapian (FreeBSD, NetBSD)
                                         xapian-bindings-perl (OpenBSD)
                                    rpm: perl-Search-Xapian
-                                   (lei; HTTP and IMAP search)
+                                   (required for lei; HTTP and IMAP search)
+
+Every effort has been to make everything else optional:
+
+- Plack                            deb: libplack-perl
+                                   pkg: p5-Plack
+                                   rpm: perl-Plack, perl-Plack-Test,
+                                   (for WWW interface, public-inbox-httpd(1))
 
 - Inline::C                        deb: libinline-c-perl
                                    pkg: p5-Inline-C
@@ -88,7 +93,7 @@ Numerous optional modules are likely to be useful as well:
 - Parse::RecDescent                deb: libparse-recdescent-perl
                                    pkg: p5-Parse-RecDescent
                                    rpm: perl-ParseRecDescent
-                                   (only for public-inbox-imapd(1))
+                                   (for public-inbox-imapd(1))
 
 - Mail::IMAPClient                 deb: libmail-imapclient-perl
                                    pkg: p5-Mail-IMAPClient
@@ -113,10 +118,19 @@ Numerous optional modules are likely to be useful as well:
 
 * xapian-tools                     deb: xapian-tools
                                    pkg: xapian-core
+                                   pkgin: xapian
                                    rpm: xapian-core
                                    (for public-inbox-compact(1) and
                                     public-inbox-cindex(1))
 
+* Xapian development files         deb: libxapian-dev
+                                   pkg: xapian-core
+                                   pkgin: xapian
+                                   apk: xapian-core-dev
+                                   rpm: xapian-core-devel / xapian14-core-libs
+                                   (for public-inbox-cindex(1) and future
+                                    performance enhancements)
+
 * curl (tool)                      deb, pkg, rpm: curl
                                    (for lei HTTP(S) externals with curl and
                                     public-inbox-clone(1))
@@ -124,11 +138,11 @@ Numerous optional modules are likely to be useful as well:
 - Linux::Inotify2                  deb: liblinux-inotify2-perl
                                    rpm: perl-Linux-Inotify2
                                    (for lei, public-inbox-watch and -imapd
-                                    on Linux)
+                                    on Linux; not required as of 2.0))
 
 - IO::KQueue                       pkg: p5-IO-KQueue
                                    (for lei, public-inbox-watch and -imapd
-                                    on *BSDs)
+                                    on *BSDs only)
 
 - Net::Server                      deb: libnet-server-perl
                                    pkg: p5-Net-Server
@@ -159,6 +173,11 @@ Uncommonly needed modules (see HACKING for development-only modules):
                                    pkg: p5-Crypt-CBC
                                    (for PublicInbox::Unsubscribe (rarely used))
 
+- Date::Parse                      deb: libtimedate-perl
+                                   pkg: p5-TimeDate
+                                   rpm: perl-TimeDate
+                                   (for broken, mostly historical emails)
+
 standard MakeMaker installation (Perl)
 --------------------------------------
 
diff --git a/install/README b/install/README
index dd652552..2cdac4d2 100644
--- a/install/README
+++ b/install/README
@@ -1,7 +1,11 @@
 tooling for mass package installation
 -------------------------------------
 
-TL;DR:        sudo ./install/deps.perl all
+TL;DR (as root or with sudo):
+
+        ./install/deps.perl all                # install everything
+        ./install/deps.perl lei                # only what's needed for lei
+        ./install/deps.perl www-search        # for hosting WWW search
 
 Files in this directory are designed for: