Add manuals for blm(1), blq(1), xii(1) and mboxu(5)

5 files changed, 177 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 0e67462..90e7260 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,4 @@
 install:
 	install blm blq xii /usr/bin/
 	install -m 644 blq.1 blm.1 xii.1 /usr/share/man/man1/
+	install -m 644 mboxu.5 /usr/share/man/man5/
diff --git a/blm.1 b/blm.1
new file mode 100644
index 0000000..32c17b6
--- /dev/null
+++ b/blm.1
@@ -0,0 +1,29 @@
+.Dd $Mdocdate$
+.Dt blm 1
+.Os
+.
+.Sh NAME
+.Nm blm
+.Nd
+.Xr mboxu 5
+translator for
+.Xr blq 1
+.
+.Sh SYNOPSIS
+.Nm
+.
+.Sh DESCIPTION
+.Pp
+.Nm
+translates JSON from
+.Xr blq 1 ,
+received on standard input, into
+.Xr mboxu 5 .
+
+The results can be saved in a file and opened successfully with most mail readers.
+.
+.Sh AUTHORS
+.Pp
+.Nm
+was written by John Ankarström
+.Aq Mt john (at) ankarstrom.se .
diff --git a/blq.1 b/blq.1
new file mode 100644
index 0000000..8ddaa3b
--- /dev/null
+++ b/blq.1
@@ -0,0 +1,47 @@
+.Dd $Mdocdate$
+.Dt blq 1
+.Os
+.
+.Sh NAME
+.Nm blq
+.Nd search utility for Blocket.se
+.
+.Sh SYNOPSIS
+.Nm
+.Op Fl r
+.Ar query
+.
+.Sh DESCIPTION
+.Pp
+.Nm
+is a script for searching Blocket.se, the Swedish equivalent to Craigslist, without the need for a web browser.
+
+If no command-line flags are present,
+.Nm
+outputs the search results in JSON format.
+The results can be processed with a utility like
+.Xr jq 1
+or the included
+.Xr blm 1 ,
+which translates them into
+.Xr mboxu 5
+format.
+
+If
+.Fl r
+is present,
+.Nm
+automatically invokes
+.Xr blm 1
+and opens the resulting mbox file in
+.Xr mutt 1 ,
+.Xr mailx 1
+or the value of
+.Ev MAILER .
+The temporary mbox file is automatically deleted.
+.
+.Sh AUTHORS
+.Pp
+.Nm
+is written by John Ankarström
+.Aq Mt john (at) ankarstrom.se .
diff --git a/mboxu.5 b/mboxu.5
new file mode 100644
index 0000000..1380282
--- /dev/null
+++ b/mboxu.5
@@ -0,0 +1,57 @@
+.Dd $Mdocdate$
+.Dt mboxu 5
+.Os
+.
+.Sh NAME
+.Nm mboxu
+.Nd mbox in UTF-8
+.
+.
+.Sh DESCIPTION
+.Pp
+.Nm
+is a simple and readable mbox-like format, in which messages are encoded directly in UTF-8.
+
+Messages are differentiated from one another via a line beginning with
+.Ql From\  ,
+.Em followed by at least one header line .
+
+Otherwise,
+.Nm
+is identical to traditional mbox.
+.
+.Sh RATIONALE
+.Pp
+.Nm
+has two goals:
+.Bl -enum
+.It
+to be easily writable and readable by humans, and
+.It
+to be easily generated and parsed by machines.
+.El
+.Pp
+Normally, non-ASCII e-mail messages must be encoded in base64 or quoted-printable, rendering them more or less unreadable in raw form.
+Mailboxes using
+.Nm ,
+on the other hand, do not require any decoding to be read by a human.
+
+Likewise,
+.Nm
+is much easier to generate and manually write than standard mbox.
+.
+.Sh FUTURE
+.Pp
+In the future, a readable alternative to multipart messages may be added, where non-canonical parts are stored in separate files and referenced via some
+.Ql Attachment:
+header.
+.Pp
+If that is added, a translator between
+.Nm
+and standard mbox might be desirable.
+.
+.Sh AUTHORS
+.Pp
+.Nm
+is created by John Ankarström
+.Aq Mt john (at) ankarstrom.se .
diff --git a/xii.1 b/xii.1
new file mode 100644
index 0000000..d79b3a9
--- /dev/null
+++ b/xii.1
@@ -0,0 +1,43 @@
+.Dd $Mdocdate$
+.Dt xii 1
+.Os
+.
+.Sh NAME
+.Nm xii
+.Nd X-Image viewer
+.
+.Sh SYNOPSIS
+.Nm
+.
+.Sh DESCIPTION
+.Pp
+.Nm
+downloads and views images specified in any number of
+.Ql X-Image
+headers contained in any number of e-mail messages given on standard input.
+Any line not containing an
+.Ql X-Image
+header is ignored.
+
+This means that you can conveniently pipe messages from
+.Xr mailx 1
+into
+.Nm
+to display any referenced remote images.
+
+.Ql X-Image
+headers serve as a way of referencing (remote) images in an e-mail message without MIME.
+They are used in the output of
+.Xr blm 1 .
+
+.Nm
+views images in
+.Xr fbi 1 ,
+an image viewer for the Linux framebuffer,
+or
+.Ev VIEWER .
+.Sh AUTHORS
+.Pp
+.Nm
+is written by John Ankarström
+.Aq Mt john (at) ankarstrom.se .