From ce201121b5785d9ecb2829d262c23050e537fa9e Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Thu, 13 Jun 2024 15:32:22 -0400
Subject: add renumbas.

---
 renumbas.rst | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 renumbas.rst

(limited to 'renumbas.rst')

diff --git a/renumbas.rst b/renumbas.rst
new file mode 100644
index 0000000..a0b79ba
--- /dev/null
+++ b/renumbas.rst
@@ -0,0 +1,116 @@
+========
+renumbas
+========
+
+-----------------------------------
+Renumber Atari 8-bit BASIC programs
+-----------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+renumbas [**-v**] [**-s** *start-lineno*] [**-i** *increment*] [**-f** *first-lineno*] *input-file* *output-file*
+
+DESCRIPTION
+===========
+**renumbas** reads a tokenized Atari 8-bit BASIC program and writes a
+renumbered copy of the program. 
+
+**input-file** must be a tokenized (SAVEd) Atari BASIC program. Use
+*-* to read from standard input, but **renumbas** will refuse to
+read from standard input if it's a terminal.
+
+**output-file** will be the renumbered BASIC program. If it already
+exists, it will be overwritten. Use *-* to write to standard output,
+but **renumbas** will refuse to write to standard output if it's a
+terminal (since tokenized BASIC is binary data and may confuse the
+terminal).
+
+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.
+
+Computed line numbers can't be updated (e.g. GOTO A or GOSUB
+1000+A*100). These will draw warnings on stderr, so you can fix them
+manually.
+
+Line numbers that don't exist will not be changed (e.g. TRAP 40000).
+
+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.
+
+OPTIONS
+=======
+
+Options may appear in any order. The first non-option argument is used
+for **input-file**; the second is **output-file**. A third non-option
+argument is an error.
+
+General Options
+---------------
+**--help**
+  Print usage message and exit.
+
+**--version**
+  Print version number and exit.
+
+**-v**
+  Verbose operation. When displaying a number in verbose mode, it will
+  be prefixed with *$* if it's in hex, or no prefix for decimal.
+
+Renumber Options
+----------------
+**-s** *start-lineno*
+  First line number in the renumbered program. Default: 10.
+
+**-i** *increment*
+  Line number increment between successive lines. Default: 10.
+
+**-f** *first-lineno*
+  Line number in original program where renumbering will start. Lines
+  numbered lower that this will not be renumbered. Default: 0.
+
+LIMITATIONS
+===========
+
+Computed line numbers with ON
+-----------------------------
+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::
+
+  100 ON X GOTO 10,20*Y,30
+
+The 10 will be changed to whatever line 10 got renumbered to, as expected. The 20
+will *not* be changed. **renumbas** just gives up, after the first computed
+line number.
+
+A pathological case::
+
+  100 ON X GOTO 10+0,20+0
+
+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 **renumbas** does constant folding.
+
+None of this should be a real-world problem: computed line numbers in
+ON/GOTO or ON/GOSUB are exceedingly rare. The whole *point* of ON is
+to avoid computing line numbers.
+
+Warning line numbers
+--------------------
+Any warning that includes a line number (such as "Computed line number") will
+have the original line number, *not* 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't known yet).
+
+EXIT STATUS
+===========
+
+0 for success, 1 for failure.
+
+.. include:: manftr.rst
-- 
cgit v1.2.3