From 6391b773b79afda4b5baa4d336bd350e02ba4044 Mon Sep 17 00:00:00 2001 From: "C. McEnroe" Date: Fri, 1 May 2020 12:36:24 -0400 Subject: Expand documentation --- bubger.1 | 62 +++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/bubger.1 b/bubger.1 index 99984a8..7ff6767 100644 --- a/bubger.1 +++ b/bubger.1 @@ -1,10 +1,10 @@ -.Dd April 30, 2020 +.Dd May 1, 2020 .Dt BUBGER 1 .Os . .Sh NAME .Nm bubger -.Nd IMAP archive renderer +.Nd IMAP archive generator . .Sh SYNOPSIS .Nm @@ -29,6 +29,9 @@ The utility renders an HTML, Atom and mboxrd archive of an IMAP mailbox arranged into threads. +It requires the IMAP SORT and THREAD extensions. +Partial output is cached and reused +by subsequent runs. . .Pp The arguments are as follows: @@ -54,7 +57,7 @@ The default algorithm is .Sy REFERENCES . . .It Fl h Ar head -Add the contents of the file +Append the contents of the file .Ar head to the .Sy @@ -62,7 +65,8 @@ element of HTML pages. . .It Fl m Ar addr Set the mailto and reply Cc address for the archive. -The default address is the username. +The default address is +.Ar user . . .It Fl p Ar port Connect to IMAP on @@ -73,14 +77,18 @@ The default port is TLS without STARTTLS is assumed. . .It Fl q -Exit non-zero if no changes are made. +Exit non-zero if the mailbox has not changed. . .It Fl s Ar url -Set the subscribe URL link -to be added to the index page navigation. +Add a +.Dq subscribe +link of +.Ar url +to the index page navigation. . .It Fl t Ar title -Set the base title for HTML pages. +Set the base title for HTML pages +and the index Atom feed. The default title is the mailbox name. . .It Fl u Ar base @@ -99,13 +107,13 @@ environment variable. .It Ar host Connect to IMAP on .Ar host . - +. .It Ar user Log in to IMAP as .Ar user . . .It Ar mailbox -Render messages from +Render threads from .Ar mailbox . The default mailbox is .Qq Archive . @@ -119,20 +127,32 @@ The IMAP password. . .Sh FILES .Bl -tag -width Ds -.It Pa UIDVALIDITY -Stores the mailbox UID validity. -.It Pa UIDNEXT -Stores the next UID of the mailbox. -.It Pa UID/*.atom , Pa UID/*.html , Pa UID/*.mbox -Cached Atom, HTML and mboxrd fragments for each message. -.It Pa attachment/*/*/* +.It Pa index.atom +Rendered Atom feed of all messages. +.It Pa index.html +Rendered HTML index of all threads. +.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 thread/*.atom , Pa thread/*.html , Pa thread/*.mbox -Rendered Atom, HTML and mboxrd files for each thread. +.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 +thread and index pages and feeds. +.It Pa UIDVALIDITY +Stores the mailbox UID validity. .El . +.Sh EXAMPLES +.Bd -literal +bubger -q imap.example.org list@example.org \e +&& rsync -a index.* message thread attachment example.org:public_html/ +.Ed +. .Sh STANDARDS .Bl -item .It @@ -229,3 +249,7 @@ Rendered Atom, HTML and mboxrd files for each thread. . .Sh AUTHORS .An June Bug Aq Mt june@causal.agency +. +.Sh BUGS +Send mail to +.Aq Mt list+bubger@causal.agency . -- cgit 1.4.1