added readme

1 files changed, 42 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..bca1530
--- /dev/null
+++ b/README
@@ -0,0 +1,42 @@
+# badroff
+
+A basic typesetting system. As the name implies, it is a bad imitation
+of a basic idea of roff. Commands are structured like /^.\*$/, but they
+are not turing-complete or even fully handle boxes or glue and the like.
+Breaking a line does not use hyphenation or the like, instead only
+breaking on spaces. Non-breaking spaces are included, and some ad-hoc
+centering and leaders, so that I could create a specific document (it,
+`phrase-circuit.src` is included as an example and as a test).
+
+# Building
+
+Just run `make` (parallelism does work, so `make -j8` is recommended) to
+build the binary `badroff`.
+
+# Architecture
+
+`badroff.c` contains most of the ad-hoc logic, and `sb.c`, `buf.c`, and
+`ll.c` have helper data types. `buf.c` is a buffer, intended to be used
+on top of a file so that it can peek several bytes in without complex
+interfacing with other components (it also makes getting n characters
+out in a string easy). `ll.c` is a basic linked list for multiple
+strings, and `sb.c` is a "string buffer": a bunch of strings get added
+into the buffer and then decomposed into a single string.
+
+`badroff.c` starts with some helpers which fill buffers from a file with
+a couple of string manipulation helpers too. Then, the next section is
+composed mainly of typesetting commands available in a badroff file.
+`accumlines` is used with `endgroup` to create groupable statements
+like collecting multiple lines into one or typesetting multiple lines
+as if they were one. The final section is generic handling of commands,
+cleaning up trailing whitespace and nonbreaking spaces, the normal
+typesetting algorithm, classifying lines as command/non-command, and
+mainloop.
+
+# Bugs
+
+It mostly segfaults on line overfill (i.e. trying to center oversized
+text or unfoldable lines are completely unhandled). Error handling
+should probably be used, but that is a nontrivial addition.
+
+Nonexistent commands also cause segfaults.