1 files changed, 133 insertions, 0 deletions
diff --git a/renumbas.rst b/renumbas.rst
new file mode 100644
index 0000000..a442ccb
--- /dev/null
+++ b/renumbas.rst
@@ -0,0 +1,133 @@
+========
+renumbas
+========
+
+-----------------------------------
+Renumber Atari 8-bit BASIC programs
+-----------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+renumbas [**-v**] [**-s** *start-lineno*] [**-i** *increment*] [**-f** *first-lineno*] [**-b**] *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 cause warnings on stderr, so you can fix them
+manually.
+
+Valid line numbers (0 to 32767) that don't exist will not be changed,
+but will cause a warning. Invalid line numbers (e.g. *TRAP 40000*)
+will be ignored (no change, no warning).
+
+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.
+
+Atari BASIC allows fractional line numbers, such as *GOTO 123.4*.
+These are rounded to the nearest integer when the program is
+executed. **renumbas** handles these correctly, although you're
+not likely to run into them in real-world programs.
+
+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.
+
+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.
+
+**-b**
+  Renumber program backwards (line numbers in descending
+  order). This option is completely useless, but exists for testing
+  purposes. Programs renumbered this way won't *RUN* correctly,
+  although they will *LOAD* and *LIST*. When using this option, set
+  **-s** to a higher number than the default.
+
+.. include:: genopts.rst
+
+DIAGNOSTICS
+===========
+
+Fatal: Program is code-protected; unprotect it first.
+  Use **unprotbas** to remove the protection, if you get this error.
+
+Fatal: New line number *num* would be >32767.
+  32767 is the highest line number BASIC allows.
+  Use a lower starting line (**-s**) and/or increment (**-i**).
+
+Warning: Computed *cmd* at line *num*.
+  The line number for a *GOTO*, *GOSUB*, etc is normally adjusted to
+  whatever the line got renumbered to. This warning means that **renumbas**
+  couldn't adjust the line number, because it's a computed value such as
+  *GOTO A+100*. You'll have to fix this manually. *num* is the original
+  line number, not the renumbered one.
+
+Warning: Line *num1* references nonexistent line *num2*.
+  Usually indicates a bug in the BASIC program. Example: *GOTO 100*,
+  but there is no line 100. *num1* is the original line number, not the
+  renumbered one.
+
+Renumbering line *num1* as *num2* (*num3* refs).
+  Only seen when the **-v** (verbose) option is used. Just an informational
+  message.
+
+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).
+
+LIMITATIONS
+===========
+
+A pathological case::
+
+  100 GOTO 200+0
+
+200+0 is considered a computed line number, even though the results of
+the computation are constant. This is because neither Atari BASIC nor
+**renumbas** does constant folding.
+
+This shouldn't be a real-world problem; did *you* ever write code like
+that in Atari BASIC?
+
+EXIT STATUS
+===========
+
+0 for success, 1 for failure.
+
+.. include:: manftr.rst