diff --git a/doc/bulb.1 b/doc/bulb.1 new file mode 100644 index 0000000..4c4394f --- /dev/null +++ b/doc/bulb.1 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2024 Sasha Koshka +.\" +.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, +.\" visit . +.\" +.TH BULB 1 2024-10-11 +.SH NAME +bulb \(en bulletin board +.\" +.SH SYNOPSIS + +bulb +.RB [ -hlpu ] +.RB [ -b\ board ] +.RB [ -n\ number ] +.\" +.SH DESCRIPTION + +Read from and post to boards (text files) on the system. Posts are plain text, +multiline, and each one is tagged with the user name of its author. +.\" +.SH OPTIONS + +.IP \fB-h\fP +Prints the help text and exits. +.IP \fB-b\fP\ \fIboard\fP +Specifies a board other than \(lqgeneral\(rq. +.IP \fB-l\fP +Lists available boards and exits. +.IP \fB-n\fP\ \fInumber\fP +Takes a numeric argument as the amount of recent posts to print out, the default +being 8. +.IP \fB-p\fP +Posts a message read from the standard input. See the STANDARD INPUT section. +.IP \fB-u\fP +Operates undercover. All posts made will be under the name \(lqanonymous\(rq. +.\" +.SH STANDARD INPUT + +When the +.B -p +option is supplied, the standard input will be read until EOF. It will be posted +under the name of the current user in whichever board the user selected. +.\" +.SH STANDARD OUTPUT + +If the +.B -l +option is supplied, a list of available boards will be written to the standard +output. If not, the last +.B -n +messages in the selected board will be written. +.\" +.SH DIAGNOSTICS + +In the event of an I/O error, a debug message will be printed and the program +will exit with an error code. In the event of a bad invocation, a debug message +will be printed alongside usage text and the program will exit with an error +code. +.\" +.SH RATIONALE + +The commands +.BR talk (1p), +and +.BR write (1p), +and +.BR wall (1p) +can be used effectively for textual intra-system communication, but they require +that the receiving user(s) be both logged in and monitoring their terminal for +any messages to ever get through. The +.BR bulb (1) +command was written to support asynchronous, persistent conversations between +users of the same system. It is also possible to create bulletins, MOTDs, etc. +.\" +.SH AUTHOR + +Written by Sasha Koshka +.MT sashakoshka@tebibyte.media +.ME . +.\" +.SH COPYRIGHT + +Copyright \(co 2024 Sasha Koshka (pseudonymous). License GPLv3+: GNU GPL version +3 or later +\." +.SH SEE ALSO + +.BR talk (1p), +.BR write (1p), +.BR wall (1p)