about summary refs log tree commit homepage
path: root/Documentation
DateCommit message (Collapse)
2021-02-27doc: lei-import: drop markup of "stdin"
stdin isn't placed in C<> elsewhere.
2021-02-27doc: lei: update manpages
Catch up with recent developments.
2021-02-26lei q: -tt marks direct hits as "flagged"
This can be used to quickly distinguish messages which were direct hits when doing thread expansion vs messages that were merely part of the same thread. This is NOT mairix-derived behavior, but I occasionally found it useful when looking at results in an MUA to know whether a message was a direct hit or not. This makes "-t" consistent with non-"-t" cases as far as keyword reading goes.
2021-02-26lei import: use --in-format/-F for consistency
Since we recommend $IN_FORMAT:$LOCATION, this is hopefully not intrusive (not that this is released software, yet). This is to be consistent with "lei convert" usage. We'll keep "-f" only for output formats, since that is used for "lei q" and "lei convert" for outputs
2021-02-23doc: lei: favor "-o format:$PATHNAME" over "-f"
The --format argument is redundant and may be dropped entirely. Update the lei manpages to prefer the format prefix. cf. https://public-inbox.org/meta/20210217044032.GA17934@dcvr/
2021-02-11doc: lei: update manpages
Catch up with recent developments.
2021-02-11doc: add lei-import(1)
2021-02-11doc: lei: prefer 'location' and 'dirname'
This follows the help output change in 52342875 (lei help: split out into separate file, 2021-02-06).
2021-02-11doc: lei q: use 'mfolder' as --output placeholder
'mfolder' is familiar to mairix users, and 'path' isn't a good choice because support will be added for IMAP. Link: https://public-inbox.org/meta/YCBh62OqkYnr5cqw@dcvr
2021-02-07lei: replace --thread with --threads
Nobody is expected to use long options, but for consistency with mairix(1), we'll use the pluralized option throughout (including existing PublicInbox::{Search,SearchView}). Link: https://public-inbox.org/meta/20210206090119.GA14519@dcvr/
2021-02-07lei: remove --mua-cmd alias for --mua
While "mua-cmd" may be more accurate, nobody is expected to type 4 extra characters. It's a needless ambiguity with no precedence or prior art to follow. Link: https://public-inbox.org/meta/20210206090119.GA14519@dcvr/
2021-02-03doc: lei-q: note "-a" and link to Xapian QueryParser
"-a" is supported by mairix, too. We should also note somewhere the query parsing features supported by Xapian.
2021-02-01doc: note optional BSD::Resource use
We've actually been capable of using this since 2019(*) in our spawn code for PSGI limiters. And it's been used since 2016 in our tests. It's a dependency of SpamAssassin, and Danga::Socket used it, too. (*) commit 721368cd04bfbd03c0d9173fff633ae34f16409a ("spawn: support RLIMIT_CPU, RLIMIT_DATA and RLIMIT_CORE")
2021-02-01doc: add lei-overview(7)
[ew: s/mboxrd/mboxcl2/ since that's what mutt uses]
2021-02-01doc: start manpages for lei commands
Add manpages for lei and the currently implemented subcommands. The included options and their descriptions follow to a large degree the --help output, dropping some options that are not currently wired up.
2021-01-26doc: start working on public-inbox-extindex(1) manpage
It's barely started, but I started writing this weeks ago, but I'm still unsure about some behavioral/usability things and hoping work on lei(1) can flush them out.
2021-01-26build: check with lexgrog(1) if available
This will make life easier for Debian package maintainers running lintian. cf. commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55 ("public-inbox-v[12]-format.pod: make lexgrog happy")
2021-01-26doc: extindex-format: make lexgrog happy
Based on commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55 ("public-inbox-v[12]-format.pod: make lexgrog happy")
2021-01-25doc: re-add missing 1.6 release notes
I missed these during the merge :x
2021-01-01update copyrights for 2021
Using "make update-copyrights" after setting GNULIB_PATH in my config.mak
2020-12-31public-inbox 1.6.1 - minor bugfix release v1.6.1
2020-12-26public-inbox-v[12]-format.pod: make lexgrog happy
The Debian package linter (lintian) emits the following warning: W: bad-whatis-entry N: N: A manual page should start with a NAME section, which lists the N: program name and a brief description. The NAME section is used to N: generate a database that can be queried by commands like apropos and N: whatis. You are seeing this tag because lexgrog was unable to parse N: the NAME section. N: N: Manual pages for multiple programs, functions, or files should list N: each separated by a comma and a space, followed by \- and a common N: description. N: N: Listed items may not contain any spaces. A manual page for a two-level N: command such as fs listacl must look like fs_listacl so the list is N: read correctly. N: N: Refer to the lexgrog(1) manual page, the groff_man(7) manual page, and N: the groff_mdoc(7) manual page for details. N: N: Severity: warning N: N: Check: documentation/manual N: N: Renamed from: manpage-has-bad-whatis-entry N: for public-inbox-v1-format and public-inbox-v2-format. Adapt the descriptions to make lexgrog and so lintian happy. (cherry picked from commit 1350f5ab09f72c75ac2cd6c88f6a2b9e198fef55)
2020-12-26doc: v2-format: drop repeated word
(cherry picked from commit 4df1904582c4d7bec64e05d1566cd48c8c2e888e)
2020-12-26nntp: delimit Newsgroup: header with commas
...instead of spaces. This is specified in RFC 5536 3.1.4. Include references to RFC 1036, 5536 and 5537 in our docs while we're at it. Reported-by: Andrey Melnikov <temnota.am@gmail.com> Link: https://public-inbox.org/meta/CA+PODjpUN5Q4gBFQhAzUNuMasVEdmp9f=8Uo0Ej0mFumdSwi4w@mail.gmail.com/ (cherry picked from commit 44227c2624e4f954943d632cd5335396351373be)
2020-12-26doc: post-1.6 updates, start 1.7
I should've dropped "PENDING" notes before the 1.6 release; they're dropped now, and a note is added to remind my future self to drop them before 1.7. (cherry picked from commit 3b5d3d1910f1db526a488142c01f42db5255ac72)
2020-12-26doc: txt2pre: more manpage URLs
We host our own -imapd manpage, and we started using a few more git commands (fast-import for ages). We'll also need to link to manpages.debian.org and live with long URLs for a few non-standard manpages in software we reference. (cherry picked from commit 31065006a3654968c0c4bbfe2d7399a3b326ce18)
2020-12-26doc: flow: include -imapd
It's another read-only daemon, and it may see more usage than -nntpd as more users have IMAP support than NNTP. (cherry picked from commit 1fcb5694c2fdd4200820f777f27f9f55cd51b6ae)
2020-12-24index: update [extindex "all"] by default, support -E
In most cases, this ensures users will only have to opt-in to using -extindex once and won't have to issue extra commands to keep external indices up-to-date when using public-inbox-index. Since we support arbitrary numbers of external indices for ease-of-development, we'll support repeating "-E" ("--update-extindex=") in case users want to test changes in parallel.
2020-12-22public-inbox-v[12]-format.pod: make lexgrog happy
The Debian package linter (lintian) emits the following warning: W: bad-whatis-entry N: N: A manual page should start with a NAME section, which lists the N: program name and a brief description. The NAME section is used to N: generate a database that can be queried by commands like apropos and N: whatis. You are seeing this tag because lexgrog was unable to parse N: the NAME section. N: N: Manual pages for multiple programs, functions, or files should list N: each separated by a comma and a space, followed by \- and a common N: description. N: N: Listed items may not contain any spaces. A manual page for a two-level N: command such as fs listacl must look like fs_listacl so the list is N: read correctly. N: N: Refer to the lexgrog(1) manual page, the groff_man(7) manual page, and N: the groff_mdoc(7) manual page for details. N: N: Severity: warning N: N: Check: documentation/manual N: N: Renamed from: manpage-has-bad-whatis-entry N: for public-inbox-v1-format and public-inbox-v2-format. Adapt the descriptions to make lexgrog and so lintian happy.
2020-12-22support multiple CODE_URLs
public-inbox.org will expire in a few years, so ensure Tor .onions can be known before then.
2020-12-12doc: v2-format: drop repeated word
2020-12-12doc: add public-inbox-extindex-format(5) manpage
The CLI tool still needs usability work, and "misc" is still in flux, but the core message indexing part is stable (since it's stolen from v2 :P).
2020-12-09treewide: replace {-inbox} with {ibx} for consistency
{ibx} is shorter and is the most prevalent abbreviation in indexing and IMAP code, and the `$ibx' local variable is already prevalent throughout. In general, the codebase favors removal of vowels in variable and field names to denote non-references (because references are "lighter" than non-references). So update WWW and Filter users to use the same code since it reduces confusion and may allow easier code sharing.
2020-11-05doc/standards: add RFCs for URL schemes
We linkify these in the WWW UI, and will support them in other places. These URL schemes may end up being stored in external/detached indices for indexing non-git-based mail stores.
2020-11-04nntp: delimit Newsgroup: header with commas
...instead of spaces. This is specified in RFC 5536 3.1.4. Include references to RFC 1036, 5536 and 5537 in our docs while we're at it. Reported-by: Andrey Melnikov <temnota.am@gmail.com> Link: https://public-inbox.org/meta/CA+PODjpUN5Q4gBFQhAzUNuMasVEdmp9f=8Uo0Ej0mFumdSwi4w@mail.gmail.com/
2020-09-20doc: post-1.6 updates, start 1.7
I should've dropped "PENDING" notes before the 1.6 release; they're dropped now, and a note is added to remind my future self to drop them before 1.7.
2020-09-19gcf2: wire up read-only daemons and rm -gcf2 script
It seems easiest to have a singleton Gcf2Client client object per daemon worker for all inboxes to use. This reduces overall FD usage from pipes. The `public-inbox-gcf2' command + manpage are gone and a `$^X' one-liner is used, instead. This saves inodes for internal commands and hopefully makes it easier to avoid mismatched PERL5LIB include paths (as noticed during development :x). We'll also make the existing cat-file process management infrastructure more resilient to BOFHs on process killing sprees (or in case our libgit2-based code fails on us). (Rare) PublicInbox::WWW PSGI users NOT using public-inbox-httpd won't automatically benefit from this change, and extra configuration will be required (to be documented later).
2020-09-19add gcf2 client and executable script
This should be able to replace multiple `git cat-file' for blob retrieval, but adjustments may be needed.
2020-09-18doc: txt2pre: more manpage URLs
We host our own -imapd manpage, and we started using a few more git commands (fast-import for ages). We'll also need to link to manpages.debian.org and live with long URLs for a few non-standard manpages in software we reference.
2020-09-18doc: flow: include -imapd
It's another read-only daemon, and it may see more usage than -nntpd as more users have IMAP support than NNTP.
2020-09-16public-inbox 1.6.0 v1.6.0
2020-09-14doc: TODO and release notes updates ahead of 1.6
Some more things have happened... And drop some items which are too expensive to support, such as automatic mirroring.
2020-09-14doc: Add piem to list of clients
2020-09-02doc: remove B<> (bold) markup from the remaining POD
B<> decreases readability of the POD source and is of dubious usefulness in the man page.
2020-09-02watch: add --help/-h support
And avoid unnecessary POD markup in the man page.
2020-09-02mda+learn: add --help / -h support
"use Getopt::Long" doesn't seem too slow on a hot page cache, and it's probably used frequently enough to be in cache. We'll also start reducing the amount of markup in the .pod and favoring verbatim text in documentation for readability in source form, since the bold text seems excessive.
2020-09-02edit+purge: support `--help' and `-h' like other commands
And while we're at it, note edit is *destructive* to encourage reading the fine manual.
2020-08-31doc: expand on indexBatchSize regarding fragmentation
And change the documentation reference in -tuning to point to the -index manpage while we're at it.
2020-08-28www: improve navigation around contemporary threads
Sometimes it's useful to quickly get to threads and messages which are contemporaries of the current thread/message being focused on. This hopefully improves navigation by making: a) the top line (where $INBOX_DIR/description) is shown a link to the latest topics in search results and per-thread/per-message views. b) providing a link to contemporaries ("~YYYY-MM-DD") at around the thread overview skeleton area for per-thread and per-message views
2020-08-28doc: watch: expand on NNTP and IMAP-specific knobs
There's a few more, but maybe they're too esoteric to be worth documenting at the moment (batch sizes, timeouts, etc).