ref: 83b1b96014f6e333c0987de230f7c87bc92b055b
parent: c5d8bcc3b4072c9de6c6a156cdbf007e1c27d40f
author: Ori Bernstein <ori@eigenstate.org>
date: Thu Dec 31 14:54:03 EST 2020
manpage: document format strings
--- a/nail.man
+++ b/nail.man
@@ -9,9 +9,13 @@
.B -Ts
]
[
-.B -f
+.B -m
.I maildir
]
+[
+.B -f
+.I format
+]
.SH DESCRIPTION
.PP
@@ -33,14 +37,21 @@
Disable threading
.PD 0
.TP
-.BI -f " maildir
+.BI -m " maildir
Open the maildir
.I maildir
instead of the default
-.I -s
+.PD 0
+.TP
+.BI -s
Accept sendmail plumb messages. By default, only
the Nail instance viewing /mail/fs/mbox will
accept plumb messages.
+.PD 0
+.TP
+.BI -f " format
+Define the format of individual messages in the list view
+(see "Format strings" below).
.PP
Nail presents a typical acme interface. When started,
@@ -55,7 +66,7 @@
.TP
.B Put
-Flush pending chnages back to
+Flush pending changes back to
.IR upasfs (4).
.PD 0
.TP
@@ -102,6 +113,82 @@
.TP
.B Post
Sends the message currently being composed.
+
+.SS Format strings
+The formatting of messages in the list view is controlled by the
+format string defined through the
+.I -f
+flag.
+The format string is composed of multiple directives: plain
+characters, which are displayed unchanged; indentation directives,
+which allows spacing based on thread depth; and messages directives,
+which display message fields.
+.PP
+Directives have the following format:
+.IP
+.B "% [width] verb
+.PP
+.IR width
+limits the number of characters displayed.
+If width is negative, text is aligned right instead of left.
+.PP
+Messages directives are:
+.PD 0
+.TP
+.B s
+Subject
+.PD 0
+.TP
+.B f
+From field
+.PD 0
+.TP
+.B F
+From field including sender's name
+.PD 0
+.TP
+.B t
+To field
+.PD 0
+.TP
+.B c
+Cc field
+.PD 0
+.TP
+.B r
+Reply-to field
+
+.PP
+Indentation directives are:
+.PD 0
+.TP
+.B i
+Adds spacing depending on message depth in thread but limited to a single level.
+If
+.IR width
+is not specified, adds a tabulation otherwise
+.IR width
+specifies the number of spaces to display.
+.PD 0
+.TP
+.B I
+Similar to
+.IR i
+but not limited to a single level.
+
+.PP
+Two special directives are also available:
+.PD 0
+.TP
+.B "[...]
+Text within the brackets is displayed if the message is not the toplevel message of a thread.
+.PD 0
+.TP
+.B "{...}+Text within the braces is used as the format string for tmfmt(2).
+
+.PP
+If the format string is invalid, Nail will exit with a description of the error.
.SH FILES