listbas: add -r option, tweak doc.

1 files changed, 60 insertions, 3 deletions

diff --git a/listbas.1 b/listbas.1
index 40097e8..2104dfb 100644
--- a/listbas.1
+++ b/listbas.1
@@ -27,12 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "LISTBAS" 1 "2024-07-18" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "LISTBAS" 1 "2024-07-20" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 listbas \- List the source of a tokenized Atari 8-bit BASIC program
 .SH SYNOPSIS
 .sp
-listbas [\fB\-a\fP | \fB\-d\fP | \fB\-m\fP | \fB\-x\fP | \fB\-U\fP] [\fB\-B\fP] [\fB\-u\fP] [\fB\-i\fP] [\fB\-l\fP] [\fB\-n\fP | \fB\-C\fP] [\fB\-v\fP] [\fB\-c\fP \fIcolors\fP] \fBinput\-file\fP
+listbas [\fB\-a\fP | \fB\-d\fP | \fB\-m\fP | \fB\-x\fP | \fB\-U\fP] [\fB\-B\fP] [\fB\-u\fP] [\fB\-i\fP] [\fB\-l\fP] [\fB\-n\fP | \fB\-C\fP] [\fB\-v\fP] [\fB\-c\fP \fIcolors\fP] [\fB\-r\fP \fIline\-range\fP] \fBinput\-file\fP
 .SH DESCRIPTION
 .sp
 \fBlistbas\fP acts like the \fILIST\fP command in BASIC. It reads a
@@ -72,8 +72,17 @@ OSS BASIC XE.
 .sp
 See \fBBASIC DIALECTS\fP below for details.
 .TP
+.B \fB\-r\fP \fIline\-range\fP
+Show only part of the listing. \fIline\-range\fP can be a single line, or
+a comma\-separated pair of starting and ending line numbers (e.g. \fB100,200\fP).
+If the start line number is omitted (e.g. \fB,100\fP), it will be treated as
+\fB0\fP (meaning, list from the beginning of the program). If the ending line
+number is omitted (e.g. \fB100,\fP), it means "list until the end of the program".
+\fB\-r,\fP is equivalent to not using the \fB\-r\fP option at all.
+.TP
 .B \fB\-i\fP
-Include the immediate mode command (line 32768) in the output.
+Include the immediate mode command (line 32768) in the output. This option has no
+effect if the \fB\-r\fP option is used to stop listing before the end of the program.
 .TP
 .B \fB\-l\fP
 Do not print line numbers at the start of each line. \fBGOTO\fP, \fBGOSUB\fP,
@@ -282,6 +291,54 @@ Turbo BASIC, at least, will "max out" the indentation level at some
 point. Once there are 60 or so levels of indent, it stops adding
 more. \fBlistbas\fP doesn\(aqt emulate this behaviour (shouldn\(aqt be a
 problem, it\(aqs a pathological case).
+.sp
+BASIC XL actually does indentation within a line. If you write:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+10 IF A:IF B:IF C:REM
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\&...BXL lists it as:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+10   If A:  If B:  If C:Rem
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBlistbas\fP only indents at the start of a line, so this behaviour is
+not emulated.
+.sp
+One thing \fBlistbas\fP gets right: the \fBLIST\fP command in Turbo, A+,
+BXL, and BXE always starts out with 0 indent spaces, if you\(aqre only
+listing part of a program. BXE example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+10 While 1
+20   If Peek(764)<>255
+30     ? "SOMEONE PRESSED A KEY":Poke 764,255
+40   Endif
+50 Endwhile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\&...but if you give a \fBLIST 30\fP in BXE, you\(aqll get line 30 without any
+indentation. \fBlistbas\fP does this, too, if you use the \fB\-r\fP option.
 .SS Protected Programs
 .sp
 \fBlistbas\fP will refuse to operate on a LIST\-protected program with