update doc.

4 files changed, 70 insertions, 18 deletions

diff --git a/linetab.c b/linetab.c
index 59a96e3..55a5c97 100644
--- a/linetab.c
+++ b/linetab.c
@@ -88,7 +88,7 @@ void computed_msg(unsigned short lineno) {
 			cmd = "???"; break;
 	}
 
-	fprintf(stderr, "Computed %s at line %d\n", cmd, lineno);
+	fprintf(stderr, "%s: Warning: Computed %s at line %d.\n", self, cmd, lineno);
 }
 
 CALLBACK(got_var) {
diff --git a/renumbas.1 b/renumbas.1
index f4b57a4..3252fab 100644
--- a/renumbas.1
+++ b/renumbas.1
@@ -100,6 +100,39 @@ Print version number and exit.
 Verbose operation. When displaying a number in verbose mode, it will
 be prefixed with \fI$\fP if it\(aqs in hex, or no prefix for decimal.
 .UNINDENT
+.SH DIAGNOSTICS
+.INDENT 0.0
+.TP
+.B Fatal: Program is code\-protected; unprotect it first.
+Use \fBunprotbas\fP to remove the protection, if you get this error.
+.TP
+.B Fatal: New line number \fInum\fP would be >32767.
+32767 is the highest line number BASIC allows.
+Use a lower starting line (\fB\-s\fP) and/or increment (\fB\-i\fP).
+.TP
+.B Warning: Computed \fIcmd\fP at line \fInum\fP\&.
+The line number for a \fIGOTO\fP, \fIGOSUB\fP, etc is normally adjusted to
+whatever the line got renumbered to. This warning means that \fBrenumbas\fP
+couldn\(aqt adjust the line number, because it\(aqs a computed value such as
+\fIGOTO A+100\fP\&. You\(aqll have to fix this manually. \fInum\fP is the original
+line number, not the renumbered one.
+.TP
+.B Warning: Line \fInum1\fP references nonexistent line \fInum2\fP\&.
+Usually indicates a bug in the BASIC program. Example: \fIGOTO 100\fP,
+but there is no line 100. \fInum1\fP is the original line number, not the
+renumbered one.
+.TP
+.B Renumbering line \fInum1\fP as \fInum2\fP (\fInum3\fP refs).
+Only seen when the \fB\-v\fP (verbose) option is used. Just an informational
+message.
+.UNINDENT
+.SS Warning line numbers
+.sp
+Any warning that includes a line number (such as "Computed line number") will
+have the original line number, \fInot\fP the renumbered one. This is because
+the warnings are generated while scanning the program to find line number
+references, which happens before the actual renumbering (so the new number
+isn\(aqt known yet).
 .SH LIMITATIONS
 .sp
 A pathological case:
@@ -120,13 +153,6 @@ the computation are constant. This is because neither Atari BASIC nor
 .sp
 This shouldn\(aqt be a real\-world problem; did \fIyou\fP ever write code like
 that in Atari BASIC?
-.SS Warning line numbers
-.sp
-Any warning that includes a line number (such as "Computed line number") will
-have the original line number, \fInot\fP the renumbered one. This is because
-the warnings are generated while scanning the program to find line number
-references, which happens before the actual renumbering (so the new number
-isn\(aqt known yet).
 .SH EXIT STATUS
 .sp
 0 for success, 1 for failure.
diff --git a/renumbas.c b/renumbas.c
index abe3029..ba26289 100644
--- a/renumbas.c
+++ b/renumbas.c
@@ -75,12 +75,12 @@ CALLBACK(renumber_line) {
 
 	if(lineno < limit || lineno == 32768) return;
 	if(newno >= 32768) {
-		fprintf(stderr, "%s: Fatal: New line number %d out of range, renumber failed.\n", self, newno);
+		fprintf(stderr, "%s: Fatal: New line number %d would be >32767.\n", self, newno);
 		exit(1);
 	}
 
 	if(verbose)
-		fprintf(stderr, "renumbering line %d as %d, %d refs\n", lineno, newno, refcounts[lineno]);
+		fprintf(stderr, "Renumbering line %d as %d (%d refs).\n", lineno, newno, refcounts[lineno]);
 
 	int2fp(newno, fpnewno);
 	for(i = 0; i < refcounts[lineno]; i++)
diff --git a/renumbas.rst b/renumbas.rst
index 7cef711..f71bf01 100644
--- a/renumbas.rst
+++ b/renumbas.rst
@@ -70,19 +70,31 @@ Renumber Options
 
 .. include:: genopts.rst
 
-LIMITATIONS
+DIAGNOSTICS
 ===========
 
-A pathological case::
+Fatal: Program is code-protected; unprotect it first.
+  Use **unprotbas** to remove the protection, if you get this error.
 
-  100 GOTO 200+0
+Fatal: New line number *num* would be >32767.
+  32767 is the highest line number BASIC allows.
+  Use a lower starting line (**-s**) and/or increment (**-i**).
 
-200+0 is considered a computed line number, even though the results of
-the computation are constant. This is because neither Atari BASIC nor
-**renumbas** does constant folding.
+Warning: Computed *cmd* at line *num*.
+  The line number for a *GOTO*, *GOSUB*, etc is normally adjusted to
+  whatever the line got renumbered to. This warning means that **renumbas**
+  couldn't adjust the line number, because it's a computed value such as
+  *GOTO A+100*. You'll have to fix this manually. *num* is the original
+  line number, not the renumbered one.
 
-This shouldn't be a real-world problem; did *you* ever write code like
-that in Atari BASIC?
+Warning: Line *num1* references nonexistent line *num2*.
+  Usually indicates a bug in the BASIC program. Example: *GOTO 100*,
+  but there is no line 100. *num1* is the original line number, not the
+  renumbered one.
+
+Renumbering line *num1* as *num2* (*num3* refs).
+  Only seen when the **-v** (verbose) option is used. Just an informational
+  message.
 
 Warning line numbers
 --------------------
@@ -92,6 +104,20 @@ the warnings are generated while scanning the program to find line number
 references, which happens before the actual renumbering (so the new number
 isn't known yet).
 
+LIMITATIONS
+===========
+
+A pathological case::
+
+  100 GOTO 200+0
+
+200+0 is considered a computed line number, even though the results of
+the computation are constant. This is because neither Atari BASIC nor
+**renumbas** does constant folding.
+
+This shouldn't be a real-world problem; did *you* ever write code like
+that in Atari BASIC?
+
 EXIT STATUS
 ===========