Added a man page

Signed-off-by: Solderpunk <solderpunk@sdf.org>

1 files changed, 301 insertions, 0 deletions

diff --git a/telem.1 b/telem.1
new file mode 100644
index 0000000..8fd6172
--- /dev/null
+++ b/telem.1
@@ -0,0 +1,301 @@
+.\" Copyright (C) 2019 Ryan Kavanagh <rak@rak.ac>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are
+.\" met:
+.\"
+.\" * Redistributions of source code must retain the above copyright notice,
+.\"   this list of conditions and the following disclaimer.
+.\"
+.\" * Redistributions in binary form must reproduce the above copyright
+.\"   notice, this list of conditions and the following disclaimer in the
+.\"   documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+.\" IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.Dd July 17 2019
+.Dt TELEM 1
+.Os
+.Sh NAME
+.Nm telem
+.Nd bulletin board system (BBS) client
+.Sh SYNOPSIS
+.Nm
+.Sh DESCRIPTION
+.Nm
+is a text-based BBS client.
+A bulletin board is a collection of
+.Em boards ,
+which are topic-based collections of
+.Em threads .
+Each thread is a chronological list of plain-text messages with a common
+subject. Users interact with
+.Nm
+by entering commands when prompted.
+Commands to manipulate boards and customize
+.Nm
+are entered at the
+.Em command prompt .
+It has the form
+.Dl [BOOKS] COMMAND :>
+where the current board is given between square brackets. Board-related
+commands typically operate on the current board.
+.Sh FINDING BOARDS AND THREADS
+To list available boards, the user enters the
+.Dq l
+(list) command at the command prompt. Boards are equivalently identified
+by (case-insensitive) names and by numeric IDs. These data, along with
+the boards' topics and thread counts are given in the listing. It has
+the form:
+.Bd -literal -offset indent
+ID  Board name  Board topic                Thread count
+--------------------------------------------------------
+  1 ANNOUNCE    Announcements              [ 30 threads]
+  2 BOOKS       Things you read            [ 13 threads]
+  3 CYCLING     Life on two wheels         [ 12 threads]
+.Ed
+.Pp
+To list threads in the current board, the user enters the
+.Dq m
+(messages) command at the command prompt.
+.Nm
+will output a listing of the form:
+.Bd -literal -offset indent
+ID  Created  Creator          Subject
+-------------------------------------------------------------
+  1 06/27/19 solderpunk       The cat code (*)    [  3 posts]
+  2 06/23/19 cat              playable solitaire  [  3 posts]
+  3 06/07/19 solderpunk       Gopher client list  [  8 posts]
+.Ed
+Threads with unread messages are indicated by an asterisk
+.Dq (*)
+beside their subject.
+This listing can be customized using the commands described in
+.Sx CUSTOMIZATION .
+.Sh NAVIGATION
+To change the current board, the user enters the
+.Dq g
+(goto) command at the command prompt.
+.Nm
+will prompt the user to enter the desired board's numeric ID or name.
+.Pp
+To view a thread, the user enters the
+.Dq t
+(type) command followed by the thread's numeric ID.
+.Nm
+will display the most recent message, followed by the thread prompt:
+.Dl [f]irst, [n]ext, [p]rev, [l]ast, [w]hole, [r]eply, [s]ave, [d]one, [q]uit >
+From this prompt, the user can navigate between messages in the thread,
+view the entire thread, or reply to it. Thread-related commands are
+described below in
+.Sx Thread commands .
+.Sh SCANNING FOR RECENT ACTIVITY
+To list boards with unread threads, the user enters the
+.Dq s
+(scan) command at the command prompt.
+.Nm
+will output a listing with the number of unread threads per board:
+.Bd -literal -offset indent
+  1 Scanning ANNOUNCE            1 thread(s) updated!
+  2 Scanning AUDIO               No new posts
+  3 Scanning BOOKS               3 thread(s) updated!
+.Ed
+.Pp
+The user can also list the most-recently updated threads using the
+.Dq R
+(Recent) command.
+.Nm
+will produce a listing of the form:
+.Bd -literal -offset indent
+Most recently active threads:
+Board name           Thread topic           Latest post
+---------------------------------------------------------
+ZAIBATSU             Buster                 July 16, 2019
+CYCLING              Bicycle history        July 16, 2019
+HELP                 malicious commands     July 11, 2019
+---------------------------------------------------------
+.Ed
+These threads can then be accessed using the commands described in
+.Sx NAVIGATION .
+.Sh POSTING
+To create a new thread in the current board, the user enters the
+.Dq n
+(new) command at the command prompt.
+.Nm
+will prompt the user for a subject. The user can abort creating a new
+thread by entering an empty subject. Given a subject,
+.Nm
+will start a text editor with which the user can compose their message.
+After editing,
+.Nm
+will confirm with the user before posting. The user may change the text
+editor used by setting the
+.Ev BBSED
+environment variable described in
+.Sx ENVIRONMENT .
+.Pp
+A user can reply to a thread using the
+.Dq r
+(reply) command. When this command is entered at the command prompt,
+.Nm
+will prompt the user for the thread's numeric ID. When entered at the
+thread prompt,
+.Nm
+will post the reply to the current thread. As when creating new threads,
+.Nm
+will start a text editor and confirm with the user before posting the
+message.
+.Sh CUSTOMIZATION
+By default,
+.Nm
+uses ANSI escape sequences to colour its output. This behaviour can be
+toggled using the
+.Dq c
+(colour) command at the command prompt.
+.Pp
+By default,
+.Nm
+displays old threads. They can be hidden using the
+.Dq H
+(Hide) command at the command prompt. This command toggles the hiding
+behaviour.
+.Pp
+By default,
+.Nm
+lists threads with the most recent activity at the top of the thread
+listing. This ordering can be reversed using the
+.Dq o
+(order) command to show threads with the oldest messages at the top.
+.Sh COMMAND LISTING
+Commands fall into three categories:
+.Em board commands ,
+.Em thread commands ,
+and
+.Em user commands .
+Board commands are used to navigate between boards and to operate on
+them. Similarly, thread commands are used to navigate between messages
+in a thread and to operate on the current thread. User commands are used
+to customize
+.Nm .
+Board commands and user commands are entered at the command prompt,
+while thread commands are entered at the thread prompt.
+.Ss Board commands
+.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
+.It (l)ist
+List all available boards
+.It (g)oto
+Goto a board by name or index
+.It (m)essages
+List all messages in current board
+.It (s)can
+Scan for new messages since last scan/login
+.It (t)ype
+Display the contents of a message thread
+.It (r)eply
+Reply to a message thread
+.It (R)ecent
+List most recently updated messages
+.It (n)ew
+Start a new thread in current board
+.It (b)oard
+Create a new board
+.El
+.Ss Thread commands
+.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
+.It (f)irst
+Show the first message in the current thread.
+.It (n)ext
+Show the next message in the current thread.
+.It (p)rev
+Show the previous message in the current thread.
+.It (l)ast
+Show the last message in the current thread.
+.It (w)hole
+Show the entire thread in a pager.
+The choice of pager may be customized using the
+.Ev PAGER
+environment variable described in
+.Sx ENVIRONMENT
+below.
+.It (r)eply
+Compose and post a reply to this thread.
+The choice of editor may be customized using
+.Ev BBSED
+environment variable described in
+.Sx ENVIRONMENT
+below.
+.It (s)ave
+Save the entire thread to a file.
+.It (d)one
+Return to the current board.
+.It (q)uit
+Exit
+.Nm .
+.El
+.Ss User commands
+.Bl -tag -width xxxxxxxxxxxx -offset indent -compact
+.It (h)elp
+List available commands
+.It (?)
+Expanded help and information
+.It (!)
+A few simple rules of use for this board
+.It (c)olor
+Disable/Enable ANSI color codes
+.It (H)ide
+Disable/Enable hiding of old threads
+.It (o)rder
+Toggle order of message listing
+.It (w)ho
+List currently logged-in users
+.It (q)uit
+Immediately quit the board
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh ENVIRONMENT
+.Bl -tag -width PAGER
+.It Ev BBSED
+The name or path of the user's preferred editor for editing BBS posts.
+If
+.Ev BBSED
+is not set,
+.Nm
+falls back to the values of
+.Ev VISUAL,
+.Ev EDITOR,
+and
+.Xr nano 1 ,
+in that order.
+.It Ev PAGER
+The name or path of the user's preferred viewer for text files.
+If unset,
+.Nm
+uses
+.Xr less 1
+as its pager.
+.El
+.Sh AUTHORS
+.Nm
+is Copyright \(co 2018
+.An -nosplit Solderpunk
+.Aq Mt solderpunk@sdf.org
+and contributors.  This man page is Copyright \(co 2019
+.An Ryan Kavanagh
+.Aq Mt rak@rak.ac .
+They are distributed under a BSD-style license.
+.Sh BUGS
+.Nm
+is not yet packaged for distribution outside of the Circumlunar Space
+project. Its sources can be fetched from the Git repository
+.Lk git://circumlunar.space/telem