From e48e479c430985a108584397d73cdab09502c00d Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Sun, 9 Jun 2024 17:38:17 -0400 Subject: dumpbas: update man page. --- atascii.7 | 2 +- dumpbas.1 | 127 ++++++++---------------------------------------------------- dumpbas.rst | 98 ++++++++-------------------------------------- 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 =========== -- cgit v1.2.3