aboutsummaryrefslogtreecommitdiff
path: root/telem.1
blob: b4520b154effcf63c2237c0c664e4ec755e0cb24 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
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 (?)
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