Add man page

doc/bulb.1

@@ -0,0 +1,91 @@
+.\" Copyright (c) 2024 Sasha Koshka <sashakoshka@tebibyte.media>
+.\"
+.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
+.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
+.\"
+.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 <https://gnu.org/licenses/gpl.html>
+\."
+.SH SEE ALSO
+
+.BR talk (1p),
+.BR write (1p),
+.BR wall (1p)