about summary refs log tree commit homepage
path: root/Documentation
DateCommit message (Collapse)
2020-01-02doc: fix a few spelling errors in user-facing docs
Found by codespell, there's a few more in comments and some debatable ones, but user-facing stuff is more important.
2020-01-02doc/txt2pre: flush output before utime()
Otherwise our utime() change is overridden when the flush happens at exit.
2020-01-02doc: release notes: set Date for 1.2.0, start 1.3.0
Seems like a lot's happened since 1.2, but it's mostly internal stuff...
2020-01-02build: remove NEWS from dist-git target
mknews doesn't require any optional dependencies a user wouldn't normally have. We can save storage and bandwidth costs by letting cgit serve the exact tar.gz which "git archive | gzip -n" generates.
2020-01-02doc: allow NEWS file to be built without Plack::Util
Plack pulls in a lot of dependencies which can be time-consuming to install. It should not be necessary for somebody who just wants to run -mda/-watch and -nntpd and forego WWW.
2019-12-11build: support doc generation w/o GNU make
We can replace the GNU-isms for building docs with Perl5 equivalents. The only downside is the resulting Makefile gets larger, but that's the price of portability.
2019-12-11tests: don't repeatly validate NEWS.atom
We can create a stamp to avoid rerunning the check unless NEWS.atom changes (and it will, soon, I hope :>).
2019-11-15doc: check-man: save the result of successful runs
We can keep a stamp around if the corresponding manpage hasn't changed to avoid re-running man(1) and awk(1).
2019-11-14doc: mknews: support Email::MIME <1.930
Email::MIME::header_str is not available until 1.930, so the rest of our code uses Email::MIME::header for compatibility with distros, since CentOS 7.x only has 1.926.
2019-11-09doc: drop a repeated word
2019-11-08doc: actually document publicinboxwatch.watchspam
Instead of copy-pasting the documentation for `spamcheck'.
2019-11-03public-inbox v1.2.0 v1.2.0
2019-11-03build: add "git-dist" target for making gzipped tarballs
Since MANIFEST is tied to files tracked by git, adding generated files such as NEWS to that is more effort than its worth (esp. when I'm wondering if MakeMaker is useful compared to only using GNU make). I also have trouble reading CamelCase, so lower-case names are nicer and more consistent with previous releases (which were all generated with "git archive"); but did not include NEWS.
2019-11-03doc: mknews: force plain-text NEWS to UTF-8
We'll have non-7-bit ASCII in the 1.2.0 release notes.
2019-11-03doc: add public-inbox.cgi(1) manpage
Yet another case of documenting things which should NOT be used :>
2019-11-02doc: add public-inbox-purge(1) manpage
Tools intended for end users need manpages, and doubly so to convince potential users NOT to use them :)
2019-10-30doc: add public-inbox-learn(1) manpage
Tools intended for end users need manpages.
2019-10-22doc: clean-doc: remove generated standards.txt
I need to remove all the generated documentation files before running "git-set-file-times" for rsync to our website.
2019-10-21doc: update 1.2 work-in-progress release notes
Will be updating this further after some reindex and multi-header bugs are fixed.
2019-10-17doc: v2-format: get man output under 80 cols
We need to better ensure our manpage output is readable with a standard terminal width. And fix some wording while we're at it: * use "inbox" instead of "list" for our storage * replace the last "$PART" reference with "$SHARD"
2019-10-17public-inbox-v2-format(5): fix formatting
This was being rendered as a paragraph, so line breaks weren't preserved and it was unreadable in man.
2019-10-17Merge remote-tracking branch 'origin/inboxdir'
* origin/inboxdir: config: remove redundant inboxdir check config: support "inboxdir" in addition to "mainrepo" examples/grok-pull.post_update_hook: use "inbox_dir"
2019-10-17doc: enable "check-man" target via "check" in gmake
man(1) on FreeBSD supports pathnames as operands just fine, so there's hope other BSDs follow suit and we can enable this check target everywhere.
2019-10-17doc: avoid [<directory>] arg for git-clone(1)
While it is possible to host source code from the root of a URL using git-http-backend(1), the lack of pathname in the URL can also be confusing to users. So just add the path name of the project into the URL itself so users can invoke "git clone" with one command-line argument instead of two. Of course, previously documented URLs continue to work as normal.
2019-10-17doc: update public-inbox-overview(7) for v2
The overview was v1-specific and probably confusing/misleading to new users since v2 is favored. Hopefully improve wording while we're at it and avoid overloading terms like "parts" (which could be confused with Xapian "shards"). Using the word "directly" after "Mirroring mailing lists" did not make sense to me, either.
2019-10-16doc: check-man: use COLUMNS env for width
That's the environment documented in ncurses(3) and man(1) from the man-db.nongnu.org distribution of man.
2019-10-16config: support "inboxdir" in addition to "mainrepo"
"mainrepo" ws a bad name and artifact from the early days when I intended for there to be a "spamrepo" (now just the ENV{PI_EMERGENCY} Maildir). With v2, "mainrepo" can be especially confusing, since v2 needs at least two git repositories (epoch + all.git) to function and we shouldn't confuse users by having them point to a git repository for v2. Much of our documentation already references "INBOX_DIR" for command-line arguments, so use "inboxdir" as the git-config(1)-friendly variant for that. "mainrepo" remains supported indefinitely for compatibility. Users may need to revert to old versions, or may be referring to old documentation and must not be forced to change config files to account for this change. So if you're using "mainrepo" today, I do NOT recommend changing it right away because other bugs can lurk. Link: https://public-inbox.org/meta/874l0ice8v.fsf@alyssa.is/
2019-10-16doc: check-man: ignore backspace char
man(1) on FreeBSD unconditionally emits backspace characters for the bold effect despite its output being piped to awk(1). Also tested with the man-db.nongnu.org version provided with Debian (and presumably most other Linux systems).
2019-10-16mda: support --no-precheck option
Since -mda now supports List-ID to better support mirroring of existing mailing lists, it probably makes sense to support disabling the precheck function to provide more accurate (though potentially spammier) mirrors of lists
2019-10-16Merge branch 'listid'
* listid: wwwtext: show listid config directive(s) mda, watch: wire up List-ID header support config: allow "0" as a valid mainrepo path config: avoid unnecessary '||' use config: simplify lookup* methods config: we always have {-section_order} Config.pm: Add support for mailing list information
2019-10-16doc: "check-man" target to ensure we stay <=80 cols
This should prevent future documentation changes from exceeding the limit of standard terminals.
2019-10-16doc: check-NEWS.atom fails gracefully on FreeBSD make(1)
We should also note that the package "xmlstarlet" on FreeBSD installs a command "xml" (but not "xmlstarlet") on FreeBSD.
2019-10-15mda, watch: wire up List-ID header support
This also adds watchheader tests for -watch, which we never had before :x
2019-10-15doc: remove unnecessary dependency on RelNotes directory
It was causing unnecessary rebuilds of NEWS* files
2019-10-10doc: explain publicinbox.<name>.watchheader
It wasn't clear to me exactly what this does -- in particular, what happens if it isn't specified? Does it support multiple values? A very brief explanation can answer both of these questions without making somebody look at the code.
2019-10-09doc: use local modules to generate NEWS*
We shouldn't need installed modules to generate NEWS* files.
2019-10-07doc: generate NEWS, NEWS.atom, and NEWS.html
We'll use our Documentation/RelNotes directory and internal APIs to generate these files for website use (the website should be completely reproducible).
2019-10-05doc: add manpage for public-inbox-init(1)
This old command was lacking a manpage, so (finally) create one.
2019-10-01doc: avoid redundant mkdir(1) calls
GNU make has order-only prerequisites, so use it to avoid redundant mkdir(1) calls since our homepage requires GNU make to build anyways.
2019-09-18doc: add release notes directory
The v1.2.0 is a work-in-progress, while the others are copied out of our mail archives. Eventually, a NEWS file will be generated from these emails and distributed in the release tarball. There'll also be an Atom feed for the website reusing our feed generation code.
2019-09-15doc: update config manpage for "publicinbox.grokmanifest"
It's a bit of an esoteric option, but maybe somebody out there can find it useful.
2019-09-14doc: update nntpd with NNTPS and STARTTLS examples
NNTPS and STARTTLS seems to be working for several months without incident on news.public-inbox.org, so consider it a success and maybe others can try using it. HTTPS technically works, too, but isn't documented at the moment since I can't recommend production deployments without varnish protecting it.
2019-09-09doc daemon: note the --listen directive is not always required
Users of socket activation don't need it, and hopefully other init systems support it, too.
2019-09-09doc edit: move =for comment after item
Quiets down pod2man complaining
2019-09-09run update-copyrights from gnulib for 2019
2019-09-09doc config: document indexlevel directive
It was never documented, before.
2019-06-14doc: rename our Xapian "partitions" to "shards"
For consistency with Xapian documentation (in the "master" branch).
2019-06-14Merge remote-tracking branch 'origin/reshard' into next
* origin/reshard: xcpdb: support resharding v2 repos xcpdb: use destination shard as progress prefix xapcmd: preserve indexlevel based on the destination v2writable: use a smaller default for Xapian partitions
2019-06-14Merge remote-tracking branch 'origin/edit' into next
* origin/edit: edit: unlink temporary file when done v2writable: replace: kill git processes before reindexing edit: drop unwanted headers before noop check edit|purge: improve output on rewrites edit: new tool to perform edits doc: document the --prune option for -index admin: expose ->config AdminEdit: move editability checks from -purge admin: beef up resolve_inboxes to handle purge options purge: start moving common options to AdminEdit module admin: remove warning arg for unconfigured inboxes v2writable: implement ->replace call import: switch to "replace_oids" interface for purge import: extract_author_info becomes extract_commit_info v2writable: consolidate overview and indexing call
2019-06-14xcpdb: support resharding v2 repos
v2 repos are sometimes created on machines where CPU parallelization exceeds the capability of the storage devices. In that case, users may reshard the Xapian DB to any smaller, positive integer to avoid excessive overhead and contention when bottlenecked by slow storage. Resharding can also be used to increase shard count after hardware upgrades.