dumpbas: update man page.

3 files changed, 34 insertions, 193 deletions

diff --git a/atascii.7 b/atascii.7
index 1ee4425..bda5be6 100644
--- a/atascii.7
+++ b/atascii.7
@@ -27,7 +27,7 @@ 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 "ATASCII" 7 "2024-06-08" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "ATASCII" 7 "2024-06-09" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 atascii \- Atari 8-bit character set
 .\" RST source for atascii(7) man page. Convert with:
diff --git a/dumpbas.1 b/dumpbas.1
index b973793..9890efd 100644
--- a/dumpbas.1
+++ b/dumpbas.1
@@ -27,7 +27,7 @@ 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 "DUMPBAS" 1 "2024-06-07" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "DUMPBAS" 1 "2024-06-09" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 dumpbas \- Formatted hexdump for tokenized Atari 8-bit BASIC files
 .SH SYNOPSIS
@@ -90,7 +90,7 @@ Separates decimal line number from hex file offset.
 .B \fB^\fP
 Prefix for line length.
 .TP
-.B \fB(\fP, \fB)\fP
+.B \fB(\fP \fB)\fP
 Surrounds the 2 hex bytes for the line number.
 .UNINDENT
 .SS Statement Markers
@@ -109,7 +109,7 @@ Suffix for the \fI14\fP token; end of statement.
 .B \fB#\fP
 Prefix for the \fI0e\fP token, which introduces a BCD floating point constant.
 .TP
-.B \fB[\fP, \fB]\fP
+.B \fB[\fP \fB]\fP
 Surrounds the 6 bytes of a BCD floating point constant.
 .TP
 .B \fB$\fP
@@ -140,145 +140,52 @@ Example: \fIA/41\fP\&.
 Each line number begins with the line number (decimal) and offset from
 the start of the file (hex), followed by the 2 hex bytes for the line
 number in parentheses, followed by the line length (hex, preceded by
-^). From the example:
+^). Example:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-10@0021 (0a 00): ^1b
+10@0018 (0a 00): ^19
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-The line number is \fI10\fP, the file offset is \fI0021\fP\&. The \fI0a 00\fP are 10 again, in
-hex, LSB first. The \fI^1b\fP is the line length.
+The line number is \fI10\fP, and the file offset is \fI0018\fP\&. The \fI0a 00\fP
+are 10 again, in hex, LSB first. The \fI19\fP is the line length.
 .SS Statements
 .sp
-Each statement within the line is displayed separately. Line 10\(aqs first statement:
+Each statement within the line is displayed separately. For this line of code:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
->17 !28 $0f =0e "H/48 O/4f W/57  /20 M/4d A/41 N/4e Y/59  /20 T/54 I/49 M/4d E/45 S/53" 15 14:
+10 ? "HELLO":A=1
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-This looks cryptic, but it includes a lot of information.
-.INDENT 0.0
-.IP \(bu 2
-\fI>\fP is the marker for the statement offset (\fI17\fP).
-.IP \(bu 2
-\fI!\fP marks a command token (unmarked tokens are operator
-tokens). \fI28\fP is the token for \fB?\fP (short form of PRINT, which has a
-separate token).
-.IP \(bu 2
-\fI$\fP marks the string\-constant token (\fI0f\fP).
-.IP \(bu 2
-\fI=\fP marks the string length byte (\fI0e\fP).
-.IP \(bu 2
-The string itself is printed inside double quotes, with each character in
-both ASCII and hex (e.g. \fIH/48\fP).
-.IP \(bu 2
-The \fI15\fP is unmarked. It\(aqs the semicolon after the string.
-.IP \(bu 2
-There\(aqs a \fI:\fP at the end of the line (after the \fI14\fP, which is the end\-of\-statement
-token).
-.UNINDENT
-.sp
-Line 10\(aqs second statement:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
->1b !02 80 16
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fI80\fP is a token for a variable (variable tokens always have bit 7 set, so they\(aqre
-always >= 80 hex). The \fI16\fP is the end\-of\-line token.
-.sp
-Line 20\(aqs first statement has an example of a floating point constant:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-#0e [40 01 00 00 00 00]
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP \(bu 2
-\fI#\fP marks the token for a FP constant.
-.IP \(bu 2
-The actual 6\-byte constant is surrounded with \fI[\fP and \fI]\fP\&.
-.IP \(bu 2
-The last token is \fI16\fP, which is BASIC\(aqs end\-of\-line token.
-.UNINDENT
-.SH EXAMPLE
-.sp
-If \fBdumpbas\fP is run on the following program:
+The dump looks like:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-10 ? "HOW MANY TIMES";:INPUT N
-20 FOR I=1 TO N
-30 ? "HELLO ";:? I;"/";N:NEXT I
-40 REM WAIT FOR KEY
-50 POKE 764,255
-60 ? "PRESS ANY KEY"
-70 IF PEEK(764)=255 THEN 70
-80 POKE 764,255:GOTO 10
+10@0018 (0a 00): ^19
+ >0d !28 $0f =05 "H/48 E/45 L/4c L/4c O/4f" 14:
+ >19 !36 80 2d #0e [40 01 00 00 00 00] 16
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-\fBNote:\fP The "PRESS ANY KEY" was entered in inverse video.
-.sp
-\&...it produces the following output:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-   10@0021 (0a 00): ^1b
-    >17 !28 $0f =0e "H/48 O/4f W/57  /20 M/4d A/41 N/4e Y/59  /20 T/54 I/49 M/4d E/45 S/53" 15 14:
-    >1b !02 80 16
-   20@003c (14 00): ^11
-    >11 !08 81 2d #0e [40 01 00 00 00 00] 19 80 16
-   30@004d (1e 00): ^1d
-    >0f !28 $0f =06 "H/48 E/45 L/4c L/4c O/4f  /20" 15 14:
-    >19 !28 81 15 $0f =01 "//2f" 15 80 14:
-    >1d !09 81 16
-   40@006a (28 00): ^12
-    >12 !00 57 41 49 54 20 46 4f 52 20 4b 45 59 9b
-   50@007c (32 00): ^15
-    >15 !1f #0e [41 07 64 00 00 00] 12 #0e [41 02 55 00 00 00] 16
-   60@0091 (3c 00): ^15
-    >15 !28 $0f =0d "|P/d0 |R/d2 |E/c5 |S/d3 |S/d3 | /a0 |A/c1 |N/ce |Y/d9 | /a0 |K/cb |E/c5 |Y/d9" 16
-   70@00a6 (46 00): ^20
-    >20 !07 46 3a #0e [41 07 64 00 00 00] 2c 22 #0e [41 02 55 00 00 00] 1b #0e [40 70 00 00 00 00] 16
-   80@00c6 (50 00): ^1f
-    >15 !1f #0e [41 07 64 00 00 00] 12 #0e [41 02 55 00 00 00] 14:
-    >1f !0a #0e [40 10 00 00 00 00] 16
-32768@00e5 (00 80): ^0f
-    >0f !19 $0f =07 "H/48 :/3a B/42 ./2e B/42 A/41 S/53" 16
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
+There are two statements. The first one ends with token \fI14\fP (the
+end\-of\-statement or tokenized colon) and the second ends with \fI16\fP
+(the end\-of\-line token). The string \fI"HELLO"\fP is visible, and so is
+the floating point constant \fI1\fP\&.
 .SH EXIT STATUS
 .sp
 0 for success, 1 for failure.
diff --git a/dumpbas.rst b/dumpbas.rst
index 80b5653..aabff21 100644
--- a/dumpbas.rst
+++ b/dumpbas.rst
@@ -70,7 +70,7 @@ Line Header Markers
 **^**
   Prefix for line length.
 
-**(**, **)**
+**(** **)**
   Surrounds the 2 hex bytes for the line number.
 
 Statement Markers
@@ -88,7 +88,7 @@ Statement Markers
 **#**
   Prefix for the *0e* token, which introduces a BCD floating point constant.
 
-**[**, **]**
+**[** **]**
   Surrounds the 6 bytes of a BCD floating point constant.
 
 **$**
@@ -118,95 +118,29 @@ Line header
 Each line number begins with the line number (decimal) and offset from
 the start of the file (hex), followed by the 2 hex bytes for the line
 number in parentheses, followed by the line length (hex, preceded by
-^). From the example::
+^). Example::
 
-     10@0021 (0a 00): ^1b 
+     10@0018 (0a 00): ^19
 
-The line number is *10*, the file offset is *0021*. The *0a 00* are 10 again, in
-hex, LSB first. The *^1b* is the line length.
+The line number is *10*, and the file offset is *0018*. The *0a 00*
+are 10 again, in hex, LSB first. The *19* is the line length.
 
 Statements
 ----------
-Each statement within the line is displayed separately. Line 10's first statement::
+Each statement within the line is displayed separately. For this line of code::
 
-      >17 !28 $0f =0e "H/48 O/4f W/57  /20 M/4d A/41 N/4e Y/59  /20 T/54 I/49 M/4d E/45 S/53" 15 14: 
+  10 ? "HELLO":A=1
 
-This looks cryptic, but it includes a lot of information.
+The dump looks like::
 
-- *>* is the marker for the statement offset (*17*).
+   10@0018 (0a 00): ^19 
+    >0d !28 $0f =05 "H/48 E/45 L/4c L/4c O/4f" 14:
+    >19 !36 80 2d #0e [40 01 00 00 00 00] 16
 
-- *!* marks a command token (unmarked tokens are operator
-  tokens). *28* is the token for **?** (short form of PRINT, which has a
-  separate token).
-
-- *$* marks the string-constant token (*0f*).
-
-- *=* marks the string length byte (*0e*).
-
-- The string itself is printed inside double quotes, with each character in
-  both ASCII and hex (e.g. *H/48*).
-
-- The *15* is unmarked. It's the semicolon after the string.
-
-- There's a *:* at the end of the line (after the *14*, which is the end-of-statement
-  token).
-
-Line 10's second statement::
-
-      >1b !02 80 16 
-
-The *80* is a token for a variable (variable tokens always have bit 7 set, so they're
-always >= 80 hex). The *16* is the end-of-line token.
-
-Line 20's first statement has an example of a floating point constant::
-
-  #0e [40 01 00 00 00 00]
-
-- *#* marks the token for a FP constant.
-
-- The actual 6-byte constant is surrounded with *[* and *]*.
-
-- The last token is *16*, which is BASIC's end-of-line token.
-
-EXAMPLE
-=======
-If **dumpbas** is run on the following program::
-
-  10 ? "HOW MANY TIMES";:INPUT N
-  20 FOR I=1 TO N
-  30 ? "HELLO ";:? I;"/";N:NEXT I
-  40 REM WAIT FOR KEY
-  50 POKE 764,255
-  60 ? "PRESS ANY KEY"
-  70 IF PEEK(764)=255 THEN 70
-  80 POKE 764,255:GOTO 10
-
-**Note:** The "PRESS ANY KEY" was entered in inverse video.
-
-...it produces the following output::
-
-     10@0021 (0a 00): ^1b 
-      >17 !28 $0f =0e "H/48 O/4f W/57  /20 M/4d A/41 N/4e Y/59  /20 T/54 I/49 M/4d E/45 S/53" 15 14: 
-      >1b !02 80 16 
-     20@003c (14 00): ^11 
-      >11 !08 81 2d #0e [40 01 00 00 00 00] 19 80 16 
-     30@004d (1e 00): ^1d 
-      >0f !28 $0f =06 "H/48 E/45 L/4c L/4c O/4f  /20" 15 14: 
-      >19 !28 81 15 $0f =01 "//2f" 15 80 14: 
-      >1d !09 81 16 
-     40@006a (28 00): ^12 
-      >12 !00 57 41 49 54 20 46 4f 52 20 4b 45 59 9b 
-     50@007c (32 00): ^15 
-      >15 !1f #0e [41 07 64 00 00 00] 12 #0e [41 02 55 00 00 00] 16 
-     60@0091 (3c 00): ^15 
-      >15 !28 $0f =0d "|P/d0 |R/d2 |E/c5 |S/d3 |S/d3 | /a0 |A/c1 |N/ce |Y/d9 | /a0 |K/cb |E/c5 |Y/d9" 16 
-     70@00a6 (46 00): ^20 
-      >20 !07 46 3a #0e [41 07 64 00 00 00] 2c 22 #0e [41 02 55 00 00 00] 1b #0e [40 70 00 00 00 00] 16 
-     80@00c6 (50 00): ^1f 
-      >15 !1f #0e [41 07 64 00 00 00] 12 #0e [41 02 55 00 00 00] 14: 
-      >1f !0a #0e [40 10 00 00 00 00] 16 
-  32768@00e5 (00 80): ^0f 
-      >0f !19 $0f =07 "H/48 :/3a B/42 ./2e B/42 A/41 S/53" 16 
+There are two statements. The first one ends with token *14* (the
+end-of-statement or tokenized colon) and the second ends with *16*
+(the end-of-line token). The string *"HELLO"* is visible, and so is
+the floating point constant *1*.
 
 EXIT STATUS
 ===========