update documentation

2 files changed, 57 insertions, 21 deletions

diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..0b78500
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,13 @@
+The file `errlist` contains a list of symbolic constants (AKA C macros) that
+can be expected to be found in `<errno.h>` on POSIX systems. Constants are
+listed one per line. A one-line AWK command transforms this into the bulk
+of `strerror.h`, along with some `printf` calls in `Makefile`.
+
+To add more errors (for instance, GNU or Linux specific stuff that doesn't
+exist in POSIX), just add them, one per line, to `errlist` and re-run `make`.
+Every constant (and I mean every, even standard C constants like `ERANGE` and
+`EDOM`) is only included in the list if it is defined, so there are no
+portability concerns with adding macros that don't exist.
+
+There is a problem with adding constants that expand to identical values,
+though, so don't do that.
diff --git a/README.md b/README.md
index 9be165a..d72db1a 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,53 @@
 # strerror
-describe system errors based on their numeric values
 
-# compilation
-`make`
+translate error numbers to strings or identifiers
 
-# use
+## Synopsis
 `strerror errno...`
 
-For example:
+## Description
 
-```
-$ ./strerror 1
-1: Operation not permitted [EPERM]
-```
+The `strerror` utility translates error numbers to strings (via the C
+function `strerror()`. If the number matches a symbolic constant defined in
+the header `<errno.h>`, `strerror` will also provide that name.
 
-# hacking
-The file `errlist` contains a list of symbolic constants (AKA C macros) that
-can be expected to be found in `<errno.h>` on POSIX systems. Constants are
-listed one per line. A one-line AWK command transforms this into the bulk
-of `strerror.h`, along with some `printf` calls in `Makefile`.
+## Operands
 
-To add more errors (for instance, GNU or Linux specific stuff that doesn't
-exist in POSIX), just add them, one per line, to `errlist` and re-run `make`.
-Every constant (and I mean every, even standard C constants like `ERANGE` and
-`EDOM`) is only included in the list if it is defined, so there are no
-portability concerns with adding macros that don't exist.
+The `strerror` utility supports the following operands:
 
-There is a problem with adding constants that expand to identical values,
-though, so don't do that.
+`errno`	A numeric error number, typically obtained from the value of the C
+	identifier `errno`.
+
+## STDIN
+
+Not used.
+
+## Input Files
+
+None.
+
+## STDOUT
+
+The `strerror` utility writes the translation of each operand, one per line,
+in the following format:
+
+`"%d: %s [%s]\n", /errno/, /error_string/, /ERROR_DEFINE/`
+
+In this, `/errno/` is the value provided as an operand, `/error_string/` is
+the string returned by the C function `strerror()`, and `/ERROR_DEFINE/` is
+the name of the symbolic constant defined to `/errno/` in `<errno.h>`. If
+`/errno/` does not match a known symbolic constant, `/ERROR_DEFINE/` will
+be `-`.
+
+## STDERR
+
+Not used.
+
+## Output Files
+
+None.
+
+## Exit Status
+
+ 0	Successful completion.
+ >0	An error occurred.