.Dd June 11, 2021 .Dt BUBGER 1 .Os . .Sh NAME .Nm bubger .Nd IMAP archive generator . .Sh SYNOPSIS .Nm .Op Fl iqv .Op Fl A Ar entries .Op Fl C Ar path .Op Fl H Ar head .Op Fl S Ar file .Op Fl T Ar title .Op Fl a Ar algo .Op Fl h Ar host .Op Fl m Ar addr .Op Fl p Ar port .Op Fl s Ar url .Op Fl u Ar base .Op Fl w Ar file .Op Fl y Ar css .Ar user .Op Ar mailbox . .Sh DESCRIPTION The .Nm utility renders an HTML, Atom and mboxrd archive of an IMAP mailbox arranged into threads. It requires the IMAP THREAD extension. Partial output is cached and reused by subsequent runs. The list of updated paths is written to standard output. . .Pp The arguments are as follows: . .Bl -tag -width Ds .It Fl A Ar entries Limit the number of entries in search Atom feeds. The default limit is 20. Thread Atom feeds always contain all entries. . .It Fl C Ar path Change directory to .Ar path before reading and writing files. . .It Fl H Ar head Append the contents of the file .Ar head to the .Sy element of HTML pages. . .It Fl S Ar file Read search definitions from .Ar file . Search definitions are documented in .Sx FILES . . .It Fl T Ar title Set the base title for search HTML pages and Atom feeds. The default title is the mailbox name. . .It Fl a Ar algo Set the threading algorithm to one of .Sy ORDEREDSUBJECT or .Sy REFERENCES . The default algorithm is .Sy REFERENCES . . .It Fl h Ar host Connect to IMAP on .Ar host . The default host is determined by SRV record lookup on the domain name of .Ar user . . .It Fl i Continually wait for new messages in the mailbox using IMAP IDLE. Writes to .Pa UIDNEXT indicate that the rendered archive has been updated. . .It Fl m Ar addr Add a .Dq write mailto link of .Ar addr to search page navigation. . .It Fl p Ar port Connect to IMAP on .Ar port . The default port is .Sy imaps .Pq 993 . TLS without STARTTLS is assumed. . .It Fl q Suppress output of updated paths and exit non-zero if the mailbox has not changed. . .It Fl s Ar url Add a .Dq subscribe link of .Ar url to search page navigation. . .It Fl u Ar base Set the base URL for links in Atom feeds. . .It Fl v Log IMAP protocol to standard error. . .It Fl w Ar file Read the IMAP password from .Ar file . By default the password is set by the .Ev BUBGER_IMAP_PASSWORD environment variable. . .It Fl y Ar css Use the stylesheet URL .Ar css . The default is an inline stylesheet. . .It Ar user Log in to IMAP as .Ar user . . .It Ar mailbox Render threads from .Ar mailbox . The default mailbox is .Qq Archive . .El . .Sh ENVIRONMENT .Bl -tag -width Ds .It Ev BUBGER_IMAP_PASSWORD The IMAP password. .El . .Sh FILES .Bl -tag -width Ds .It Pa *.atom, *.html Rendered Atom feeds and HTML pages for each search. .It Pa thread/*.atom , Pa thread/*.html , Pa thread/*.mbox Rendered Atom, HTML and mboxrd files for each thread. .It Pa attachment/*/*/*.* Attached files. .It Pa message/*.mbox Rendered mboxrd files for each message. .It Pa UID/*.atom , Pa UID/*.html , Pa UID/*.mbox Cached Atom, HTML and mboxrd fragments for each message. .It Pa UIDNEXT Stores the next UID of the mailbox. Remove this file to force re-render the search pages and feeds. .It Pa UIDVALIDITY Stores the mailbox UID validity. .It Pa SEARCH The default path to read search definitions from. .El . .Pp Each line of the .Pa SEARCH file defines a search for which an Atom feed and an HTML page will be generated. Blank lines and lines beginning with .Ql # are ignored. Each line consists of a search name and an IMAP search expression, separated by whitespace. If no .Pa index search is defined, the following default is used: .Bd -literal -offset indent index ALL .Ed . .Sh EXAMPLES Create or update an archive and copy new or updated files to a remote host: .Bd -literal -offset indent bubger -C archive list@example.org | rsync -a --files-from=- archive example.org:public_html/archive .Ed . .Pp Example .Pa SEARCH definitions: .Bd -literal -offset indent announce SUBJECT "[ANNOUNCE]" bubger TO "list+bubger@causal.agency" .Ed . .Sh STANDARDS .Bl -item .It .Rs .%A T. Berners-Lee .%A L. Masinter .%A M. McCahill .%T Uniform Resource Locators (URL) .%I IETF .%R RFC 1738 .%U https://tools.ietf.org/html/rfc1738 .%D December 1994 .Re .It .Rs .%A N. Borenstein .%A N. Freed .%T Format of Internet Message Bodies .%I IETF .%R RFC 2045 .%U https://tools.ietf.org/html/rfc2045 .%D November 1996 .Re .It .Rs .%A M. Crispin .%T INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1 .%I IETF .%R RFC 3501 .%U https://tools.ietf.org/html/rfc3501 .%D March 2003 .Re .It .Rs .%A M. Crispin .%A K. Murchison .%T Internet Message Access Protocol - SORT and THREAD Extensions .%I IETF .%R RFC 5256 .%U https://tools.ietf.org/html/rfc5256 .%D June 2008 .Re .It .Rs .%A S. Dorner .%A K. Moore .%A R. Troost .%T The Content-Disposition Header Field .%I IETF .%R RFC 2183 .%U https://tools.ietf.org/html/rfc2183 .%D August 1997 .Re .It .Rs .%A L. Esibov .%A A. Gulbrandsen .%A P. Vixie .%T A DNS RR for specifying the location of services (DNS SRV) .%I IETF .%R RFC 2782 .%U https://tools.ietf.org/html/rfc2782 .%D February 2000 .Re .It .Rs .%A P. Hoffman .%A L. Masinter .%A J. Zawinski .%T The mailto URL scheme .%I IETF .%R RFC 2368 .%U https://tools.ietf.org/html/rfc2368 .%D July 1998 .Re .It .Rs .%A B. Leiba .%T IMAP4 IDLE command .%I IETF .%R RFC 2177 .%U https://tools.ietf.org/html/rfc2177 .%D June 1997 .Re .It .Rs .%A E. Levinson .%T Content-ID and Message-ID Uniform Resource Locators .%I IETF .%R RFC 2392 .%U https://tools.ietf.org/html/rfc2392 .%D August 1998 .Re .It .Rs .%A P. Mockapetris .%T DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION .%I IETF .%R RFC 1035 .%U https://tools.ietf.org/html/rfc1035 .%D November 1987 .Re .It .Rs .%A K. Moore .%T Message Header Extensions for Non-ASCII Text .%I IETF .%R RFC 2047 .%U https://tools.ietf.org/html/rfc2047 .%D November 1996 .Re .It .Rs .%A M. Nottingham .%A R. Sayre .%T The Atom Syndication Format .%I IETF .%R RFC 4287 .%U https://tools.ietf.org/html/rfc4287 .%D December 2005 .Re .It .Rs .%A J. Snell .%T Atom Threading Extensions .%I IETF .%R RFC 4685 .%U https://tools.ietf.org/html/rfc4685 .%D September 2006 .Re .El . .Sh AUTHORS .An June McEnroe Aq Mt june@causal.agency . .Sh BUGS Send mail to .Aq Mt list+bubger@causal.agency .