about summary refs log tree commit homepage
path: root/Documentation
DateCommit message (Collapse)
2020-03-22rename PublicInbox::SearchMsg => PublicInbox::Smsg
Since the introduction of over.sqlite3, SearchMsg is not tied to our search functionality in any way, so stop confusing ourselves and future hackers by just calling it "PublicInbox::Smsg". Add a missing "use" in ExtMsg while we're at it.
2020-03-20doc: standards: add references to RFC 5322 (and RFC 822)
RFC 5322 is the latest one in this line, but much documentation and even command-line options in other programs (e.g. git) refer to RFC 2822 or even RFC 822.
2020-03-01doc: design_www: document offline friendliness
This isn't anything new and has been a part of the design since the beginning, but it may not be apparent to some folks.
2020-02-27doc: 1.4.0 release notes update
Perhaps 1.4.0 will be a small release, after all (and also smaller in terms of memory use :)
2020-02-24doc: technical: document data structures
Can't code without data structures, and we emphasize data over code just about everywhere.
2020-02-23doc: improve wording of "inbox" vs "repository"
Since v2 inboxes contain multiple git repositories, avoid the use of the word "repository" when referring to inboxes as a whole in most places.
2020-02-17doc: design_www: document solver endpoint
The blob regeneration (solving) part has been stable and performant for over a year with no problems, even with web crawlers constantly hitting it without needing rate limits. All the other stuff is open to bikeshedding (as long as my crappy hardware supports it :P)
2020-02-09doc: update v1.3.0.eml with actual headers, start v1.4.0
Bigger changes coming :>
2020-02-10public-inbox 1.3.0 v1.3.0
2020-02-08doc: more 1.3.0 release notes updates
2020-02-08doc: mark some TODO items as done
NNTP TLS and COMPRESS support and cgit spawning from the WWW interface were implemented last year. Given the lack of syscall number stability guarantee on the OpenBSD and FreeBSD, I don't think supporting a pure-Perl kevent is feasible. Inline::C may still be an option since IO::KQueue is abandoned, though, as it is for some Linux-only syscalls and maybe some POSIX ones not covered by POSIX.pm.
2020-02-08doc: update copyright for standards.perl
It was missing "(C)", so gnulib update-copyright missed it.
2020-02-06treewide: run update-copyrights from gnulib for 2019
I didn't wait until September to do it, this year!
2020-02-06doc: v1: add a reference to git-filter-repo(1), too
The git-filter-branch(1) manpage itself recommends git-filter-repo, nowadays due to performance and safety problems.
2020-02-06doc: txt2pre: auto-linkify manpage references
This can be more convenient for people browsing HTML docs remotely or locally.
2020-02-06doc: remove .x/ subdirectory for Xapian manpages
There's no need to keep Xapian manpage renderings in a separate subdirectory, after all. Eliminating this difference between the local FS and URL path will allow relative URLs to the Xapian manpages in our local HTML documentation to work smoothly, since there was never any ".x/" path component for files served from public-inbox.org
2020-02-06doc: add data flow diagram using Graph::Easy
Maybe this can make it easier for new and potential users to understand what's going on.
2020-02-04doc: recommend -compact after --reindex
It's likely a user will be low on space after running --reindex, so recommend the use of public-inbox-compact afterwards. And add a few more notes about using public-inbox-compact to clarify it's for inboxes-only (and not any old Xapian DBs) that using xapian-compact(1) directly is error-prone and likely to break things.
2020-02-04doc: spellling fixes for manpages
The wording for publicinbox.nntpserver was awkward, too, and I took this as opportunity to hopefully clarify it and favor "hostname" for Internet addresses, because we already use "address" to mean "email address" in the config.
2020-02-02doc: -convert: document switches
These switches have always been there, but were not documented until now.
2020-02-01doc: more 1.3.0 release notes updates
Some updates with recent bugfixes and a few wording/formatting improvements.
2020-01-25s/news.gmane.org/news.gmane.io/
gmane still has a NNTP server, so update links to point to it. cf. https://lars.ingebrigtsen.no/2020/01/06/whatever-happened-to-news-gmane-org/
2020-01-25spelling: favor `publicly' over `publically'
While both can be correct, the former seems more common, is shorter, and is also consistent with the spelling found in the AGPL-3.0 text.
2020-01-25doc: avoid needless rebuilds of NEWS
Repeatedly rebuilding `NEWS' because the mtime of `NEWS' is synched to the latest release .eml is a bit annoying, but necessary to save bandwidth for the website. So we'll also update the mtime of the source .eml file when reading them. It's kinda gross to be setting mtimes of source .eml files in Documentation/RelNotes/, but I can't think of anything better at the moment...
2020-01-19doc: some 1.3.0 release notes updates
2020-01-11doc: technical/ds.txt: describe PublicInbox::DS divergences
Danga::Socket 1.62 was released a few months back and the maintainer indicated it would be the last release. We've diverged significantly in incompatible ways... While most of this should've already been documented in commit messages, putting it all into one document could make it easier-to-digest. It's also a strange design for anybody used to conventional event loops. Maybe this is an unconventional project :P
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.