Add DIAGNOSTICS to alf man page.

1 files changed, 21 insertions, 0 deletions

diff --git a/src/alf.rst b/src/alf.rst
index 4b011aa..59dc2af 100644
--- a/src/alf.rst
+++ b/src/alf.rst
@@ -104,6 +104,27 @@ EXIT STATUS
 1
   Fatal error (I/O or bad command-line arguments).
 
+DIAGNOSTICS
+===========
+
+Besides the standard error messages such as "no such file or directory", **alf**
+can generate warnings about the filenames it's compressing:
+
+  **filename has underscore, OK on Sparta/MyDOS, not Atari DOS 2.x**
+    Not an actual problem, unless you try to extract this ALF file on
+    an Atari running Atari DOS 2.0/2.5, or any other DOS that doesn't
+    allow underscores in filenames.
+
+  **bad Atari filename** *<filename>* *<reason>*
+    The filename stored in the ALF header doesn't follow the rules for
+    Atari DOS filenames. *<reason>* will be something like "doesn't start
+    with A-Z" or "invalid character". The filename will be printed with
+    any unprintable characters as hex values (e.g. **$01**).
+
+The resulting *ALF* archive will extract with **unalf**, but will have
+problems with **DZ.COM** running on an Atari. Or you can just rename
+the files so they comply with Atari DOS filename restrictions.
+
 NOTES
 =====