From 739758781030f107f260f587a4f9c1e8bdf70f58 Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Sat, 8 Jun 2024 13:12:23 -0400
Subject: dumpbas: clean up code, work on doc.

---
 dumpbas.rst | 123 +++++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 88 insertions(+), 35 deletions(-)

(limited to 'dumpbas.rst')

diff --git a/dumpbas.rst b/dumpbas.rst
index 8b116c3..80b5653 100644
--- a/dumpbas.rst
+++ b/dumpbas.rst
@@ -53,52 +53,65 @@ Dump Options
   Don't dump lines after **start-lineno**. Default: *32768*.
 
 **-l** *lineno*
-  Only dump one line. This is exactly equivalent to "**-s** *num* **-e** *num*".
+  Only dump one line. This is exactly equivalent to "**-s** *lineno* **-e** *lineno*".
 
 FORMATTING
 ==========
 Every byte in the file is displayed in hex. However, they are grouped by line
 and statement, and certain tokens get marker characters to help keep track
-of what they're for. Strings are displayed in both hex and ASCII. Floating
+of what they're for. Strings are displayed in quotes, in both hex and ASCII. Floating
 point constants are displayed as 6 hex bytes with square brackets around them.
 
-If **dumpbas** is run on the following program::
+Line Header Markers
+-------------------
+**@**
+  Separates decimal line number from hex file offset.
 
-  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
+**^**
+  Prefix for line length.
 
-**Note:** The "PRESS ANY KEY" was entered in inverse video.
+**(**, **)**
+  Surrounds the 2 hex bytes for the line number.
 
-...it produces the following output::
+Statement Markers
+-----------------
+**>**
+  Prefix for next-statement offset. Every statement begins with this.
 
-     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 
+**!**
+  Prefix for a command token. Every line of BASIC code begins with a
+  command.
+
+**:**
+  Suffix for the *14* token; end of statement.
+
+**#**
+  Prefix for the *0e* token, which introduces a BCD floating point constant.
+
+**[**, **]**
+  Surrounds the 6 bytes of a BCD floating point constant.
+
+**$**
+  Prefix for the *0f* token, which introduces a string constant.
+
+**=**
+  Prefix for the string-length byte of a string constant.
+
+String Byte Markers
+-------------------
+**"**
+  A string constant is surrounded by double-quotes.
+
+**^**
+  Prefix for a control character. For instance, *03* is displayed as *^C*.
+
+**|**
+  Prefix for an inverse video character. Example: *c1* (inverse video *A*)
+  is displayed as *|A*. May be combined with *^*, for inverse control characters.
+
+**/**
+  Separates the printable ASCII representation of a character from its hex byte.
+  Example: *A/41*.
 
 Line header
 -----------
@@ -155,6 +168,46 @@ Line 20's first statement has an example of a floating point constant::
 
 - 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 
+
 EXIT STATUS
 ===========
 
-- 
cgit v1.2.3