summary refs log tree commit diff
diff options
context:
space:
mode:
authorJune McEnroe <june@causal.agency>2020-05-01 12:36:24 -0400
committerJune McEnroe <june@causal.agency>2020-05-01 12:36:24 -0400
commit6391b773b79afda4b5baa4d336bd350e02ba4044 (patch)
tree1166f5a370e34d07c988ddad12a2ead22d25f17f
parentRemove +1s (diff)
downloadbubger-6391b773b79afda4b5baa4d336bd350e02ba4044.tar.gz
bubger-6391b773b79afda4b5baa4d336bd350e02ba4044.zip
Expand documentation
-rw-r--r--bubger.162
1 files 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 <head>
@@ -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 .