diff options
| -rw-r--r-- | telem.1 | 301 |
1 files changed, 301 insertions, 0 deletions
@@ -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 |