crabmail

Static HTML email archive viewer in Rust
git clone git://git.alexwennerberg.com/crabmail
Log | Files | Refs | README | LICENSE

commit 4382ca41c597ea6dbe3ac61eaaf490f7f6fe7f89
parent 22121dc69d707af4f7c93e045021cf7b4d2ae591
Author: alex wennerberg <alex@alexwennerberg.com>
Date:   Wed, 12 Jan 2022 19:31:34 -0800

Add manpages

Diffstat:
Adoc/crabmail-config.5 | 71+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Adoc/crabmail-config.5.scd | 52++++++++++++++++++++++++++++++++++++++++++++++++++++
Adoc/crabmail.1 | 68++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mdoc/crabmail.1.scd | 37++++++++++++++++++++++++++++++-------
Msrc/arg.rs | 4++--
5 files changed, 223 insertions(+), 9 deletions(-)

diff --git a/doc/crabmail-config.5 b/doc/crabmail-config.5 @@ -0,0 +1,71 @@ +.\" Generated by scdoc 1.11.2 +.\" Complete documentation for this program is not available as a GNU info page +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.nh +.ad l +.\" Begin generated content: +.TH "crabmail-config" "5" "2022-01-13" +.P +.SH NAME +.P +crabmail-config - configuration file formats for \fBcrabmail\fR(1) +.P +.SH CONFIGURATION +.P +Each file uses an \fIini\fR format defined as follows: key=valuen.\& Keys cannot +contain =.\& Values cannot contain n.\& There are no other restrictions.\& +.P +Section headers are defined by [brackets].\& These are optional, and can define +list-specific configuration +.P +This variables are often not escaped, so treat this file as trusted input (ie, +don'\&t fill in values from user input somehow).\& +.P +.SH CRABMAIL.CONF +.P +.SS GLOBAL +.P +\fBbase_url\fR +.RS 4 +The base URL where your list is hosted, used to generate atom feeds +.P +.RE +\fBemail_fmt\fR +.RS 4 +The structure of how emails are mapped to mail folders, for example +lists+%s@flounder.\&online will replace %s with the list name.\& You can +override this in list-specific configuration +.P +.RE +\fBdescription\fR +.RS 4 +A description for your homepage, will be displayed as a single line.\& HTML is +allowed if you want.\& +.P +.RE +.SS LISTS +.P +Each list is specified with a [subsection] header.\& +.P +\fBtitle\fR +.RS 4 +Title of the list.\& Default tile for lists is [list-name] mailing list.\& +.P +.RE +\fBemail\fR +.RS 4 +Email of this list.\& Overrides \fBemail_fmt\fR.\& +.P +.RE +\fBdescription\fR +.RS 4 +A description for your list.\& HTML is allowed.\& +.P +.RE +.SH SEE ALSO +.P +\fBcrabmail\fR(1) +.P +.SH AUTHORS +Alex Wennerberg <alex@alexwennerberg.\&com diff --git a/doc/crabmail-config.5.scd b/doc/crabmail-config.5.scd @@ -0,0 +1,52 @@ +crabmail-config(5) + +# NAME + +crabmail-config - configuration file formats for *crabmail*(1) + +# CONFIGURATION + +Each file uses an _ini_ format defined as follows: key=value\n. Keys cannot +contain =. Values cannot contain \n. There are no other restrictions. + +Section headers are defined by [brackets]. These are optional, and can define +list-specific configuration + +This variables are often not escaped, so treat this file as trusted input (ie, +don't fill in values from user input somehow). + +# CRABMAIL.CONF + +## GLOBAL + +*base_url* + The base URL where your list is hosted, used to generate atom feeds + +*email_fmt* + The structure of how emails are mapped to mail folders, for example + lists+%s@flounder.online will replace %s with the list name. You can + override this in list-specific configuration + +*description* + A description for your homepage, will be displayed as a single line. HTML is + allowed if you want. + +## LISTS + +Each list is specified with a [subsection] header. + +*title* + Title of the list. Default tile for lists is [list-name] mailing list. + +*email* + Email of this list. Overrides *email_fmt*. + +*description* + A description for your list. HTML is allowed. + +# SEE ALSO + +*crabmail*(1) + +# AUTHORS +Alex Wennerberg <alex@alexwennerberg.com diff --git a/doc/crabmail.1 b/doc/crabmail.1 @@ -0,0 +1,68 @@ +.\" Generated by scdoc 1.11.2 +.\" Complete documentation for this program is not available as a GNU info page +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.nh +.ad l +.\" Begin generated content: +.TH "crabmail" "1" "2022-01-13" +.P +.SH NAME +.P +crabmail - an HTML email archive generator +.P +.SH SYNOPSIS +.P +crabmail [-rR] [-c CONFIG] [-d OUT_DIR] maildir +.P +.SH DESCRIPTION +.P +Crabmail writes html pages for the maildir folders contained within \fBmaildir\fR +.P +\fB-r\fR +.RS 4 +Use relative timestamps ("2 hours ago") instead of absolute ones.\& This makes +your archive more readable, but only if the index is being updated frequently +.P +.RE +\fB-R\fR +.RS 4 +ALPHA Include a link to the raw email message, with many headers stripped.\& +Has several open issues at the moment.\& +.P +.RE +\fB-c CONFIG\fR +.P +.RS 4 +The config file to read from.\& Default is .\&/crabmail.\&conf +.P +.RE +\fB-d OUT_DIR\fR +.RS 4 +.P +The out dir to write HTML to.\& Defaults it .\&/site +.P +.RE +\fBmaildir\fR +.P +.RS 4 +Path to a maildir folder.\& All subfolders (with the exception of the special +maildir folders cur, new, tmp) will be rendered as sub-pages in your HTML +archive.\& +.P +.RE +Threads will be written to \fBOUT_DIR\fR/threads/[thread-id].\&html -- Thread IDs can +have basically any character in them, except for forward slashes, which are +replaced by semicolons: keep this in mind if you are using a non-unix +filesystem.\& +.P +Threading is determined by a combination of in-reply-to and subject headers.\& +.P +Caching is minimal at the moment and subject to change.\& +.P +.SH SEE ALSO +.P +\fBcrabmail-config\fR(5) +.P +.SH AUTHORS +Alex Wennerberg <alex@alexwennerberg.\&com> diff --git a/doc/crabmail.1.scd b/doc/crabmail.1.scd @@ -6,23 +6,46 @@ crabmail - an HTML email archive generator # SYNOPSIS -crabmail [-r] mbox-file +crabmail [-rR] [-c CONFIG] [-d OUT_DIR] maildir -# OPTIONS +# DESCRIPTION + +Crabmail writes html pages for the maildir folders contained within *maildir* *-r* Use relative timestamps ("2 hours ago") instead of absolute ones. This makes your archive more readable, but only if the index is being updated frequently -*mailto:...* - Opens the composer with the address in the "to" field. - If _aerc_ is already running, the composer is started in this instance, - otherwise _aerc_ will be started. +*-R* + ALPHA Include a link to the raw email message, with many headers stripped. + Has several open issues at the moment. + +*-c CONFIG* + + The config file to read from. Default is ./crabmail.conf + +*-d OUT_DIR* + + The out dir to write HTML to. Defaults it ./site + +*maildir* + + Path to a maildir folder. All subfolders (with the exception of the special + maildir folders cur, new, tmp) will be rendered as sub-pages in your HTML + archive. + +Threads will be written to *OUT_DIR*/threads/[thread-id].html -- Thread IDs can +have basically any character in them, except for forward slashes, which are +replaced by semicolons: keep this in mind if you are using a non-unix +filesystem. + +Threading is determined by a combination of in-reply-to and subject headers. + +Caching is minimal at the moment and subject to change. # SEE ALSO *crabmail-config*(5) # AUTHORS - Alex Wennerberg <alex@alexwennerberg.com> diff --git a/src/arg.rs b/src/arg.rs @@ -30,8 +30,8 @@ use std::process::exit; fn usage() -> ! { let name = env::args().next().unwrap(); eprintln!( - "usage: {} [maildir root] -FLAGS + "usage: {} [-rR] [-c CONFIG] [-d OUT_DIR] maildir +FLAGS: -r use relative timestamps -R include raw emails [ALPHA]