path: root/renumbas.1

.\" 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-07-12" "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] [\fB\-b\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 \fIGOTO\fP
\fI100\fP (or \fIGOSUB\fP, \fIRESTORE\fP, \fITRAP\fP, etc) will be updated with the new line
number.
.sp
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
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
would result in lines with numbers higher than this.
.sp
Atari BASIC allows fractional line numbers, such as \fIGOTO 123.4\fP\&.
These are rounded to the nearest integer when the program is
executed. \fBrenumbas\fP handles these correctly, although you\(aqre
not likely to run into them in real\-world programs.
.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 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.
.TP
.B \fB\-b\fP
Renumber program backwards (line numbers in descending
order). This option is completely useless, but exists for testing
purposes. Programs renumbered this way won\(aqt \fIRUN\fP correctly,
although they will \fILOAD\fP and \fILIST\fP\&. When using this option, set
\fB\-s\fP to a higher number than the default.
.UNINDENT
.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
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
100 GOTO 200+0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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
This shouldn\(aqt be a real\-world problem; did \fIyou\fP ever write code like
that in Atari BASIC?
.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
\fBa8cat\fP(1),
\fBa8eol\fP(1),
\fBa8xd\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdiffbas\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\fP(1),
\fBwhichbas\fP(1),
\fBxex1to2\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.
.