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-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.
.