Add README.md and license header.

2 files changed, 88 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c86f143
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+## What is `ger2err`?
+
+`ger2err` stands for "Gerrit to Errors": it refers to converting Gerrit
+review comments into a format which looks like the error output from a
+a compiler. Text editors can read this so that you can navigate
+through the error list and fix the reviewer comments, as if you were
+fixing compiler errors.
+
+## Demo Example
+
+First, set up the environment. Alternatively, these parameters can be passed as
+command line arguments. **NOTE** The Gerrit credentials here are not the same as those
+used to log in to the Gerrit web interface. These are entirely separate
+HTTPS credentials for the API, that you can create inside Gerrit.
+
+Here `$` represents your shell prompt:
+
+    $ export GER2ERR_SERVER=https://your.intranet.local/gerrit
+    $ export GER2ERR_USERID=yuzer
+    $ export GER2ERR_PASSWORD=ApTKT7YA16sg5cza31mx
+
+Now we can get some comments:
+
+    $ ger2err I62b7e3e79fbeaece243eff2f369b3a90fae9628d
+    comments from patch set 1
+    lib/parser/scan.c:1357:20: unresolved comment by Co Worker (co.worker)
+            Where is this variable initialized?
+    lib/parser/parse.y:935:35: unresolved comment by Co Worker (co.worker)
+            This doesn't have to be a separate rule; it's a minor
+            variation in the foo_phrase grammar production.
+
+This output can be captured and used by your editor. For instance,
+a simple way to use it in Vim is to send it to a file called `errors.err`
+and then run `vim -q`.  There is a way to do it within Vim.
+
+Each comment consists of a main line which gives the source location
+info and identifies the commenter. Then the actual comment lines
+follow that, prefixed with a tab character, so they look like
+continuation lines.
+
+## Installation
+
+`ger2err` requires TXR 279 or later. It is a hash bang script which uses `env`
+to look for `txrlisp` in the `PATH`. Just make it executable and use it.
+
+You can compile it if you want.
+
+    $ txr --compile=ger2err:ger2err.out
+
+Now `ger2err.out` is a compiled version you can install as `ger2err`
+instead of the original.
+
+## Documentation
+
+`ger2err` has a `--help` option; that's it.
+
+## License
+
+`ger2err` is offered under a BSD license; see the comment header in the
+`ger2err` file.
+
diff --git a/ger2err b/ger2err
index 172290b..4452729 100755
--- a/ger2err
+++ b/ger2err
@@ -1,6 +1,33 @@
 #!/usr/bin/env txrlisp
 ;; vim:filetype=tl:lisp:
 
+;; Gerrit to Error ("ger2err")
+;; Copyright 2022 Kaz Kylheku <kaz@kylheku.com>
+;;
+;; BSD-2 License
+;;
+;; Redistribution and use in source and binary forms, with or without
+;; modification, are permitted provided that the following conditions are met:
+;;
+;; 1. Redistributions of source code must retain the above copyright notice,
+;;    this list of conditions and the following disclaimer.
+;;
+;; 2. Redistributions in binary form must reproduce the above copyright notice,
+;;    this list of conditions and the following disclaimer in the documentation
+;;    and/or other materials provided with the distribution.
+;;
+;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+;; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+;; IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+;; ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+;; LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+;; CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+;; SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+;; INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+;; CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+;; ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+;; POSSIBILITY OF SUCH DAMAGE.
+
 (defvarl %prog% *load-path*)
 
 (defvar *gerrit-curl*)