added README

1 files changed, 62 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..203a724
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# Groff Preprocessors and Tools
+
+This repository is home to an assortment of preprocessors and
+macros for the [GNU Troff](http://www.gnu.org/software/groff/) typesetting
+package.
+
+I have written all of them except `sequence.pic` which is part of the
+[UML Graph](http://www.umlgraph.org/) package and included here for convenience
+only.
+These scripts do not strive to be complete, well tested and fit for general usage - they
+are merely quick and dirty hacks that accumulated on my hard drive :-).
+
+## EBNF
+
+`ebnf.sno` is a [CSNOBOL4](http://www.snobol4.org/csnobol4/) program that compiles
+extended BNF descriptions into GNU pic code using macros from `syntax.pic`.
+This effectively allows you to embed EBNF grammars in Groff source code and
+have it rendered as (box and arrow) syntax diagrams.
+Most EBNF constructs and some extensions are supported, but I'm too lazy to document
+all of them now.
+
+To build the sample `select-from.ebnf`, type something like:
+  cat samples/select-from.ebnf | ./ebnf.sno | pic | groff -Tps >select-from.ps
+
+## HIGHLIGHT
+
+`highlight.sno` is a small preprocessor written in [CSNOBOL4](http://www.snobol4.org/csnobol4/)
+that processes blocks of source code embedded in your Groff document with
+[GNU Source-highlight](http://www.gnu.org/software/src-highlite/) to produce
+syntax highlighted text.
+
+The output is formatted according to `groff.outlang` which currently only works with
+the [mom macros](http://www.schaffter.ca/mom/).
+
+Example:
+  .QUOTE
+  .CODE
+  .HIGHLIGHT c
+  #include <stdio.h>
+
+  int main(int argc, char **argv)
+  {
+     printf("Hello world!\n");
+     return 0;
+  }
+  .HIGHLIGHT
+  .CODE OFF
+  .QUOTE OFF
+
+## UML
+
+`uml.sno` is a small preprocessor (again requires CSNOBOL4) that
+renders an embedded diagram with [PlantUML](http://plantuml.sourceforge.net/)
+and automatically emits the appropriate Mom `PDF_IMAGE` macro calls.
+
+## HTML Tables
+
+`htbl.tes` is a quick and dirty [SciTECO](http://plantuml.sourceforge.net/) script
+that can act as a drop-in replacement for the tbl preprocessor that generates
+proper HTML tables when the Groff html output device is used.
+With the original tbl preprocessor, tables are (and must be) rendered by the postscript
+device and will be embedded as images into the HTML page.