From 1f10767c83fb70731e3cf1b4aeae3c1beb8f356b Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Tue, 18 Jun 2024 02:01:43 -0400
Subject: docs: move "General Options" to genopts.rst, include it where needed.

---
 renumbas.1 | 66 +++++++++++++++++++++++---------------------------------------
 1 file changed, 24 insertions(+), 42 deletions(-)

(limited to 'renumbas.1')

diff --git a/renumbas.1 b/renumbas.1
index 33d54db..e2c50d2 100644
--- a/renumbas.1
+++ b/renumbas.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "RENUMBAS" 1 "2024-06-16" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "RENUMBAS" 1 "2024-06-18" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 renumbas \- Renumber Atari 8-bit BASIC programs
 .SH SYNOPSIS
@@ -53,11 +53,13 @@ e.g. if line 100 gets changed to 200, any other line that does a GOTO
 100 (or GOSUB, RESTORE, TRAP, etc) will be updated with the new line
 number.
 .sp
-Computed line numbers can\(aqt be updated (e.g. GOTO A or GOSUB
-1000+A*100). These will draw warnings on stderr, so you can fix them
+Computed line numbers can\(aqt be updated (e.g. \fIGOTO A or GOSUB
+1000+A*100\fP). These will cause warnings on stderr, so you can fix them
 manually.
 .sp
-Line numbers that don\(aqt exist will not be changed (e.g. TRAP 40000).
+Valid line numbers (0 to 32767) that don\(aqt exist will not be changed,
+but will cause a warning. Invalid line numbers (e.g. \fITRAP 40000\fP)
+will be ignored (no change, no warning).
 .sp
 Remember that the maximum line number for Atari BASIC is 32767.
 Renumbering will fail, if the chosen start and increment values
@@ -67,19 +69,6 @@ would result in lines with numbers higher than this.
 Options may appear in any order. The first non\-option argument is used
 for \fBinput\-file\fP; the second is \fBoutput\-file\fP\&. A third non\-option
 argument is an error.
-.SS General Options
-.INDENT 0.0
-.TP
-.B \fB\-\-help\fP
-Print usage message and exit.
-.TP
-.B \fB\-\-version\fP
-Print version number and exit.
-.TP
-.B \fB\-v\fP
-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
 .SS Renumber Options
 .INDENT 0.0
 .TP
@@ -93,26 +82,20 @@ Line number increment between successive lines. Default: 10.
 Line number in original program where renumbering will start. Lines
 numbered lower that this will not be renumbered. Default: 0.
 .UNINDENT
-.SH LIMITATIONS
-.SS Computed line numbers with ON
-.sp
-If an ON/GOTO or ON/GOSUB uses computed line numbers (and causes a
-warning), none of the line numbers after the first computed one will
-be updated, even if they are constant. Example:
+.SS General Options
 .INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-100 ON X GOTO 10,20*Y,30
-.ft P
-.fi
-.UNINDENT
+.TP
+.B \fB\-\-help\fP
+Print usage message and exit.
+.TP
+.B \fB\-\-version\fP
+Print version number and exit.
+.TP
+.B \fB\-v\fP
+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
-.sp
-The 10 will be changed to whatever line 10 got renumbered to, as expected. The 20
-will \fInot\fP be changed. \fBrenumbas\fP just gives up, after the first computed
-line number.
+.SH LIMITATIONS
 .sp
 A pathological case:
 .INDENT 0.0
@@ -120,19 +103,18 @@ A pathological case:
 .sp
 .nf
 .ft C
-100 ON X GOTO 10+0,20+0
+100 GOTO 200+0
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-The 10+0 and 20+0 are considered computed line numbers, even though
-the results of the computation are constant. This is because neither
-Atari BASIC nor \fBrenumbas\fP does constant folding.
+200+0 is considered a computed line number, even though the results of
+the computation are constant. This is because neither Atari BASIC nor
+\fBrenumbas\fP does constant folding.
 .sp
-None of this should be a real\-world problem: computed line numbers in
-ON/GOTO or ON/GOSUB are exceedingly rare. The whole \fIpoint\fP of ON is
-to avoid computing line numbers.
+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
-- 
cgit v1.2.3