add renumbas.

1 files changed, 184 insertions, 0 deletions

diff --git a/renumbas.1 b/renumbas.1
new file mode 100644
index 0000000..3cd0e65
--- /dev/null
+++ b/renumbas.1
@@ -0,0 +1,184 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "RENUMBAS" 1 "2024-06-13" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+renumbas \- Renumber Atari 8-bit BASIC programs
+.SH SYNOPSIS
+.sp
+renumbas [\fB\-v\fP] [\fB\-s\fP \fIstart\-lineno\fP] [\fB\-i\fP \fIincrement\fP] [\fB\-f\fP \fIfirst\-lineno\fP] \fIinput\-file\fP \fIoutput\-file\fP
+.SH DESCRIPTION
+.sp
+\fBrenumbas\fP reads a tokenized Atari 8\-bit BASIC program and writes a
+renumbered copy of the program.
+.sp
+\fBinput\-file\fP must be a tokenized (SAVEd) Atari BASIC program. Use
+\fI\-\fP to read from standard input, but \fBrenumbas\fP will refuse to
+read from standard input if it\(aqs a terminal.
+.sp
+\fBoutput\-file\fP will be the renumbered BASIC program. If it already
+exists, it will be overwritten. Use \fI\-\fP to write to standard output,
+but \fBrenumbas\fP will refuse to write to standard output if it\(aqs a
+terminal (since tokenized BASIC is binary data and may confuse the
+terminal).
+.sp
+Line number references are changed in every line where they occur, so
+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
+manually.
+.sp
+Line numbers that don\(aqt exist will not be changed (e.g. TRAP 40000).
+.sp
+Remember that the maximum line number for Atari BASIC is 32767.
+Renumbering will fail, if the chosen start and increment values
+would result in lines with numbers higher than this.
+.SH OPTIONS
+.sp
+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
+.B \fB\-s\fP \fIstart\-lineno\fP
+First line number in the renumbered program. Default: 10.
+.TP
+.B \fB\-i\fP \fIincrement\fP
+Line number increment between successive lines. Default: 10.
+.TP
+.B \fB\-f\fP \fIfirst\-lineno\fP
+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:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+100 ON X GOTO 10,20*Y,30
+.ft P
+.fi
+.UNINDENT
+.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.
+.sp
+A pathological case:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+100 ON X GOTO 10+0,20+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.
+.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.
+.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.
+.SH COPYRIGHT
+.sp
+WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
+.SH AUTHOR
+.INDENT 0.0
+.IP B. 3
+Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBa8eol\fP(1),
+\fBa8utf8\fP(1),
+\fBatr2xfd\fP(1),
+\fBatrsize\fP(1),
+\fBaxe\fP(1),
+\fBblob2c\fP(1),
+\fBblob2xex\fP(1),
+\fBcart2xex\fP(1),
+\fBdasm2atasm\fP(1),
+\fBdumpbas\fP(1),
+\fBf2toxex\fP(1),
+\fBfenders\fP(1),
+\fBprotbas\fP(1),
+\fBrenumbas\fP(1),
+\fBrom2cart\fP(1),
+\fBunmac65\fP(1),
+\fBunprotbas\fP(1),
+\fBvxrefbas\fP(1),
+\fBxexamine\fP(1),
+\fBxexcat\fP(1),
+\fBxexsplit\fP(1),
+\fBxfd2atr\fP(1),
+\fBxex\fP(5),
+\fBatascii\fP(7).
+.sp
+Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
+Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
+.\" Generated by docutils manpage writer.
+.