about summary refs log tree commit homepage
path: root/Documentation
DateCommit message (Collapse)
2024-03-16Fix some typos and language nits in docs and comments
2024-03-14doc: 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.
2024-03-12doc: tuning: note reduced fragmentation w/ jemalloc
I may be mistaken, but I suspect the reason jemalloc handles long-lived processes better than glibc is due to granularity reduction being scaled to larger size classes. This can waste 20% of an individual allocation, but increases the likelyhood of reuse (without splitting/consolidating into other sizes). In other words, glibc seems to try too hard to make the best fit for initial allocations. This ends up being suboptimal over time as those allocations are freed and similar (but not identical) allocations come in. jemalloc sacrifices the best initial fit for better fits over a long process lifetime.
2024-02-14doc: fix formatting for CLI switch aliases
`=item' elements in Pod need to be surrounded by empty lines. It's an unfortunate waste of vertical space, but Pod is still better than *roff and usually available out-of-the-box.
2024-02-14doc: config: cgit=rewrite isn't implemented, yet
It'll probably be done for another release, I doubt most cgit users are willing to completely replace it with our coderepo viewer just yet...
2024-01-30doc/lei-mail-formats: update MH read-only status
I'm not looking forward to dealing with synchronization problems if we end up dealing with writes...
2024-01-30watch: support incremental updates from MH
The good news (compared to lei) is we only have to worry about imports and don't care about the filename nor keywords, so it's immune to .mh_sequences writing inconsistencies across MH implementations and sequence number packing. We still assume the writer will write the mail file with one of: * rename(2) to create the final sequence number filename * a single write(2) if not relying on rename(2) mlmmj and mutt satisfy these requirements. Python's Lib/mailbox.py may, I'm not sure...
2024-01-10doc: txt2pre: linkify -extindex(1), dedupe -config(5)
I noticed the HTML manpages didn't have -extindex linkification while checking over the docs. While adding it, I also noticed -config(5) had two entries :x
2023-12-15doc: RelNotes: more 2.0 updates
But new ideas keep popping into muh brain :x
2023-12-01doc: config: fix grammar for nameIsUrl
Kyle Meyer <kyle@kyleam.com> wrote: > Eric Wong writes: > > +Treat the name of the public inbox as it's unqualified URL when > > s/it's/its/ Thanks, will push this fix out: -------8<------ Subject: [PATCH] doc: config: fix grammar for nameIsUrl Reported-by: Kyle Meyer <kyle@kyleam.com> Link: https://public-inbox.org/meta/87bkbazp5g.fsf@kyleam.com/
2023-11-30www_listing: support publicInbox.nameIsUrl
This is a convenient (and slightly memory-saving) alternative to specifying a `publicinbox.*.url' entry for every single inbox when using publicinbox.wwwListing.
2023-11-29doc: fix a few typos and wording issues
2023-11-29doc: -cindex: correct and unify -g GIT_DIR usage string and man page
Fixes: c76a20d75200 ("cindex: require `-g GIT_DIR' or `-r PROJECT_ROOT'")
2023-11-29lei q: fix --no-import-before completion + docs
--no-import-before skips importing entire messages, not just keywords, so it can cause permanent data loss if -o is pointed to precious data.
2023-11-29cindex: require `-g GIT_DIR' or `-r PROJECT_ROOT'
Accepting @ARGV without switches ends up being ambiguous with optional parameters for --join and --show. Requiring users to specify `--join=' or `--show=' is a bit awkward (as it with -clone --objstore= and the like, but that is historical baggage we need to carry at this point...)
2023-11-26doc/extindex: document --dedupe switch
We've had it since v1.7.0 when -extindex was introduced, but it was never documented outside of commit messages. Reviewed-by: Štěpán Němec <stepnem@smrk.net>
2023-11-22watch: support `watch=false' to negate watchspam
For users hosting read-only mirrors (via clone|fetch) and feeding inboxes via -watch
2023-11-21doc/cindex: point no-fsync,dangerous to -index(1)
There's no point in duplicating --no-fsync documentation across manpages. --dangerous can be useful for reducing SSD wear, so add a pointer to it as well.
2023-11-16extindex: warn and hint about --gc on bad ibx_id
Stale entries from newsgroup name changes (including adding a `publicinbox.<name>.newsgroup' entry when none existed before) can wreak havoc during a --reindex. So give the hint to users about running -extindex with --gc to clean up stale entries.
2023-11-14config: avoid eidx_key and newsgroup conflicts
Start lowercasing newsgroup names automatically since uppercase names are incompatible with IMAP and POP3 and also causes problems with both -extindex and -cindex. We'll also warn on eidx_key and newsgroup conflicts to avoid sometimes subtle breakage when using -extindex and -cindex.
2023-11-11mda|learn|watch: support dropUniqueUnsubscribe config
List-Unsubscribe headers with unique identifiers (such as those generated by our examples/unsubscribe.milter) should not end up in public archives. Add a new config knob to strip List-Unsubscribe headers if they have the `List-Unsubscribe-Post: List-Unsubscribe=One-Click' header. Unfortunately, this breaks DKIM signatures if the signature covers either of these List-Unsubscribe* headers. However, breaking DKIM is the lesser evil compared to any archive reader being able to stop archival by an independent archivist. As much as I would like this to be the default, it probably affects few users at the moment since very few mailing lists use unique identifiers in List-Unsubscribe (but that number has grown, recently).
2023-10-17doc: lei-q: drop stale TODO comment (fixed in 1f1b1f0e22f7)
Fixes: 1f1b1f0e22f7 ("doc: lei-q: document SEARCH TERMS prefixes")
2023-10-17doc: fix some typos and grammar
[ew: leave install/README unchanged pending wording changes]
2023-09-20makefile: avoid non-POSIX which(1)
which(1) isn't in POSIX so it's perhaps less likely to be available (although I don't think I've noticed a system without it in decades). So replace it with the POSIX `command -v', even though everyone seems to use which... Add a note about `lexgrog', too, since I'm not sure if it's packaged for various *BSDs.
2023-09-20makefile: avoid needless use of double-colon rules
This non-portable construct isn't needed for our own rules. I'm understanding them correctly, they have different semantics between *BSDs and GNU make.
2023-09-11treewide: favor Xapian (SWIG binding) over Search::Xapian
The Xapian SWIG bindings are favored by Xapian upstream for ease-of-maintenance compared to the XS version. While Debian lags on this front, the SWIG bindings are widely available on all *BSDs.
2023-09-08update docs + tests for xapian-delve use
Since -cindex uses the xapian-delve(1) command for `--prune' functionality, we'll rename our `xapian-compact' dependency to the Debian package name (xapian-tools) since `xapian-delve' is in the same package.
2023-09-02Clarify Inline::C dependency (optional on Linux, required elsewhere)
Link: https://public-inbox.org/meta/20230901110903.M876537@dcvr/ Link: https://public-inbox.org/meta/20230902194407.M464597@dcvr/ Fixes: 88c7c7c26b44 ("lei: wire up pure Perl sendmsg/recvmsg for Linux users") Fixes: acefd91b302d ("syscall: implement sendmsg+recvmsg in pure Perl")
2023-08-28doc: daemon: clarify TLS and well-known ports
Reported-by: Štěpán Němec <stepnem@smrk.net>
2023-08-28Fix some typos/grammar/errors in docs and comments
2023-08-17doc: extindex: note the use of `newsgroup' entries
We'll also be using this for -cindex for associating inboxes to coderepos.
2023-08-17doc: *index: fix misuse of apostrophe in `its'
Reported-by: Kyle Meyer <kyle@kyleam.com> Link: https://public-inbox.org/meta/87leeovmig.fsf@kyleam.com/
2023-08-16doc: clone: add a note about git 2.41+ and fetch.hideRefs
It's unusable for large mirrors, otherwise.
2023-08-16doc: add manpage for -cindex
It's similar to a combination of -index and -extindex but perhaps more refined this time around...
2023-06-15lei import: set +(L|kw) on already-imported blobs
When import hits blobs it's already seen, we'll add labels regardless in order to match the behavior of other inexact matches. This is useful when importing exact copies of messages which exist in multiple mailboxes. I noticed this when I had a message imported from my normal IMAP `INBOX', but also copied it to a different folder for future reference.
2023-06-15doc: lei q: document v2:$INBOX_DIR output format
This has been supported in every lei release, actually.
2023-04-14listener: support multi-accept like nginx
While accepting a single connection at-a-time is likely best for multi-worker and/or load-balanced deployments; accepting multiple connections at once should be less bad on overloaded single-worker systems. We can't automatically pick the best value here since worker counts are dynamic via SIGTTIN/SIGTTOU. Process managers (e.g. systemd) can also spawn multiple instances sharing a single listener with no knowledge sharing between listeners.
2023-03-18clone: support --purge to delete remotely-deleted repos
This lets us clean up disk space when repos are removed on the remote side.
2023-03-18doc: clone: note the default value of --remote-manifest=
It may not be immediately obvious to users unfamiliar with grokmirror.
2023-03-14doc: clone: fix typo in --remote-manifest= description
Reported-by: Kyle Meyer <kyle@kyleam.com> Link: https://public-inbox.org/meta/87v8j4ql8k.fsf@kyleam.com/
2023-03-13doc: clone: document --remote-manifest= option
2023-03-10doc: 2.0.0 release notes update
Did some stuff, still a ton of stuff to do :x
2023-03-10doc: lei config: update with --edit and --list examples
I typically use --edit/-e to make changes and --list/-l with git; and same with lei.
2023-03-10doc: lei import: add hints about nntp.* and imap.* config options
I'm setting up more imports and forgot about them :x
2023-03-10doc: technical: document weird stuff in our codebase
Hopefully this makes things less surprising to new hackers.
2023-03-10doc: technical/ds: update blurb to note more daemons
And add a note about the various wakeup modes of kqueue|epoll while we're at it; we use all of them!
2023-03-10doc: technical/memory: add note about mwrap-perl
It's already fixed memory usage problems not only in our codebase, but also the standard `Encode' XS module and `git pack-objects'.
2023-03-07doc: update public-inbox-clone examples and help
Basically, public-inbox-clone has become grok-pull without config files nor absolute paths.
2023-03-02doc: drop hosted.txt
I'll have to downsize the server due to increased hosting costs, so stop advertising these mirrors. The inboxes still exist, for now; but will probably be proxied behind an ssh tunnel via slow DSL connection, but it's not worth increasing traffic to.
2023-02-27doc: update clone+fetch with 2.0+ switches
Because old versions will exist for a long time and our latest documentation is visible on the web, we must document when a switch appears to avoid confusing users of old versions.