path: root/telem.1

.\" 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