.\" Copyright (C) 2019 Ryan Kavanagh .\" 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 (?) Open this man page .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