Improve man page

cmd/bulb/main.ha

@@ -1,8 +1,8 @@
-use bulb;
 use errors;
 use fmt;
 use fs;
 use getopt;
+use internal::bulb;
 use io;
 use os;
 use path;

doc/bulb.1

@@ -35,12 +35,23 @@ 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 ENVIRONMENT
+
+The BULBPATH environment variable specifies a colon-separated list of
+directories (much like PATH) in which to search for boards. Directories at the
+start take precedence over directories at the end. It has a value of
+.I /var/bulb
+by default.
+.SH FILES
+.I /var/bulb/*
+.\"
 .SH STANDARD INPUT
 
 When the
 .B -p
-option is supplied, the standard input will be read until EOF. It will be posted
+option is supplied, the standard input will be read until EOF. The resulting
-under the name of the current user in whichever board the user selected.
+text will be posted under the name of the current user in whichever board is
+selected.
 .\"
 .SH STANDARD OUTPUT
 

internal/bulb/bulb.ha

@@ -6,6 +6,17 @@ use os;
 use path;
 use strings;
 
+// TODO
+// two issues:
+// A: posts are stored exactly as they are formatted
+// B: posts need to be sanitized from control chars going in and going out
+// C: specifying a number of posts to read only works with lines because it
+//    cant separate out the individual posts
+//
+// all of these can be fixed by escaping line breaks as the post is written to
+// the board, and then rendering them once they get to the reading stage.
+// sanitize the text at both stages.
+
 let bulb_path: []str = [];
 @init fn bulb_path() void = bulb_path = strings::split(os::tryenv("BULBPATH", "/var/bulb"), ":");
 @fini fn bulb_path() void = free(bulb_path);
@@ -29,6 +40,7 @@ export fn read(output: io::handle, board: str, number: int) (void | error) = {
 	// we add 1 to account for the blank line that will always be at the
 	// bottom
 	seek_to_nth_last_line(file, number + 1)?;
+	// TODO don't copy control characters!
 	io::copy(output, file)?;
 };