diff options
Diffstat (limited to 'listamsb.1')
| -rw-r--r-- | listamsb.1 | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/listamsb.1 b/listamsb.1 new file mode 100644 index 0000000..b5e2213 --- /dev/null +++ b/listamsb.1 @@ -0,0 +1,377 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "LISTAMSB" 1 "2025-04-02" "0.2.2" "Urchlay's Atari 8-bit Tools" +.SH NAME +listamsb \- List the source of a tokenized Atari Microsoft BASIC program +.SH SYNOPSIS +.sp +listamsb [\fB\-U\fP] | [\fB\-C\fP [\fB\-k\fP]] | [\fB\-D\fP] | [[\fB\-L\fP] [\fB\-a\fP] [\fB\-c\fP] [\fB\-v\fP] [\fB\-h\fP] [\fB\-i\fP] [\fB\-u\fP] [\fB\-t\fP] [\fB\-m\fP] [\fB\-M\fP] [\fB\-n\fP] [\fB\-s\fP] [\fB\-r\fP \fIline\-range\fP] ...] [\fBinput\-file\fP] [\fBoutput\-file\fP] +.SH DESCRIPTION +.sp +\fBlistamsb\fP acts like the \fILIST\fP command in Atari Microsoft BASIC. It reads a +tokenized (SAVEd) AMSB program and prints the code in human\-readable +format. +.sp +\fBlistamsb\fP supports both versions of Atari Microsoft BASIC: the +disk\-based version 1 and the cartridge\-based version 2. The language +is the same for both versions, so there\(aqs no need to specify it. +.sp +\fBinput\-file\fP must be a tokenized AMSB program. If no \fBinput\-file\fP is given, +input is read from \fBstdin\fP\&. +.sp +Programs created with \fISAVE "filename" LOCK\fP are autodetected, +and will be listed normally. It\(aqs also possible to convert a LOCKed +program to an unencrypted one, with the \fB\-U\fP option. +.sp +Programs can be "crunched" and "decrunched" with the \fB\-C\fP and \fB\-D\fP +options. +.sp +If no \fBoutput\-file\fP is given, output is to \fBstdout\fP\&. When output +is to a file, the file will be overwritten without prompting if it +already exists. +.sp +By default, output is modern UTF\-8 equivalents of the ATASCII +character set, with ANSI control sequences for inverse video and +color. See the \fB\-M\fP, \fB\-a\fP, \fB\-i\fP, \fB\-u\fP, \fB\-t\fP, \fB\-m\fP, \fB\-s\fP +options to change the output style. +.sp +When listing in color (when the \fB\-M\fP option is not used), +\fBlistamsb\fP\(aqs output is piped through \fBcolorize\-amsb\fP, which must +be available in your \fBPATH\fP\&. +.sp +\fBlistamsb\fP will not write binary data (ATASCII or tokenized BASIC) +directly to a terminal, under any circumstances. +.SH OPTIONS +.SS Operation Modes +.INDENT 0.0 +.TP +.B \fB\-L\fP +LIST program. This is the default, so there\(aqs no need to give this option +normally. See next section for options that control the listing. +.TP +.B \fB\-C\fP +"Crunch" program: remove comments and spaces that occur outside of a +string. The resulting program is tokenized, and is usually 5 to 10 +percent smaller. It should RUN correctly, but will be difficult to +edit in AMSB because its parser requires the spaces. +.sp +The crunched program will always be unLOCKed. +.sp +If any comment\-only lines are the target of GOTO or GOSUB, the +program won\(aqt RUN correctly because all comment\-only lines are +removed. If this happens, you can use the \fB\-k\fP option (see below). +.sp +This option must be used with an \fBoutput\-file\fP, since seeking is done. +None of the other options have any effect with \fB\-C\fP\&. +.TP +.B \fB\-D\fP +"Decrunch" a crunched program. Puts spaces where they\(aqre required for +AMSB\(aqs parser. The resulting program is tokenized, and will be +editable in AMSB. Of course, any comments that were removed during +crunching will not magically be restored (they\(aqre gone). +.sp +The decrunched program will always be unLOCKed. +.sp +This option must be used with an \fBoutput\-file\fP, since seeking is done. +None of the other options have any effect with \fB\-D\fP\&. +.TP +.B \fB\-U\fP +UnLOCK or LOCK the the program. Locked programs are created with +\fISAVE "filename" LOCK\fP\&. The "encryption" is a reciprocal cipher: locking and +unlocking are the same operation (similar to ROT13). The output will +be the locked or unlocked tokenized program (rather than a listing). +.sp +This option must be used with an \fBoutput\-file\fP, a pipe, or +redirection: \fBlistamsb\fP will not write tokenized BASIC to a +terminal. None of the other options have any effect with \fB\-U\fP\&. +.UNINDENT +.SS Options for \fB\-L\fP (list) Mode +.sp +None of these options have any effect when used with \fB\-C\fP, \fB\-D\fP, +or \fB\-U\fP\&. +.INDENT 0.0 +.TP +.B \fB\-a\fP +Output raw ATASCII. This option must be used with an +\fBoutput\-file\fP, a pipe, or redirection: \fBlistamsb\fP will not write +ATASCII to a terminal. \fBcolorize\-amsb\fP is not used, with this option. +.TP +.B \fB\-c\fP +Check only. No output on \fBstdout\fP\&. Diagnostics are still printed on stderr, +and the exit status is unchanged. It\(aqs an error to give an \fBoutput\-file\fP with +this option. +.TP +.B \fB\-i\fP +Input uses Atari XL/XE International Character Set encoding, rather than +ATASCII graphics. +.TP +.B \fB\-u\fP +Use underlining for inverse video (see \fBa8cat\fP(1) for more detail). +.TP +.B \fB\-t\fP +Text mode (see \fBa8cat\fP(1) for more detail). +.TP +.B \fB\-m\fP +Magazine listing mode (see \fBa8cat\fP(1) for more detail). +.TP +.B \fB\-s\fP +Strip bit 7 (inverse video bit; see \fBa8cat\fP(1) for more detail). +.TP +.B \fB\-M\fP +Monochrome listing: disable color syntax highlighting, meaning \fBcolorize\-amsb\fP +is not used. +.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\- or hyphen\-separated pair of starting and ending line numbers (e.g. \fB100,200\fP, or +\fB1000\-2000\fP). +.sp +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 or \fB\-r\-\fP is equivalent to not using the \fB\-r\fP option at all. +.TP +.B \fB\-n\fP +No empty line. By default, \fBlistamsb\fP prints an empty line at the +start of the output, to match AMSB\(aqs LIST command. +.UNINDENT +.SS Options for \fB\-C\fP (crunch) Mode +.INDENT 0.0 +.TP +.B \fB\-k\fP +Keep comment\-only lines. Normally these are removed. If the program +gives UNDEF\(aqD LINE ERROR, it means the target line was a comment\-only +line that got removed. With \fB\-k\fP, these lines will be kept, although +the actual comments won\(aqt (\fI10 REM HELLO\fP will become \fI10 REM\fP). +.UNINDENT +.SS Utility Options +.INDENT 0.0 +.TP +.B \fB\-v\fP +Verbose output, on \fBstderr\fP\&. May be given twice for extra verbosity, +which shows each line number, its offset, length, and end\-of\-line pointer. +Can be used with any of the mode options (\fB\-C\fP, \fB\-D\fP, \fB\-L\fP, \fB\-U\fP). +.TP +.B \fB\-h\fP, \fB\-\-help\fP +Print built\-in help and exit. +.TP +.B \fB\-\-version\fP +Print version number and exit. +.UNINDENT +.SH DIAGNOSTICS +.sp +All error and warning messages are written to the standard error output. +.SS Fatal errors +.sp +These are errors in the program header at the start of the file. They +generally mean the input isn\(aqt actually an tokenized Atari Microsoft +BASIC file. +.INDENT 0.0 +.IP \(bu 2 +not an AMSB file: first byte not $00 or $01 +.sp +Pretty self\-explanatory: if the file doesn\(aqt begin with a \fI$00\fP or +\fI$01\fP byte, it\(aqs not a tokenized AMSB file. +.IP \(bu 2 +not an AMSB file: too big (\fIN\fP bytes), won\(aqt fit in Atari memory +.sp +The file can\(aqt be a tokenized AMSB file because there was no way +for it to be created. It must be some other kind of file that begins +with a \fI$00\fP byte. +.IP \(bu 2 +not an AMSB file: program size too small (\fIN\fP). Atari BASIC file? +.sp +The program header claims the file is 0, 1, 3, or 4 bytes long. This +is impossible, so this isn\(aqt an AMSB file. A lot of Atari BASIC +programs begin with three \fI$00\fP bytes, so that might be what this is. +.IP \(bu 2 +program length is 2, no code in file (SAVE after NEW) +.sp +Probably, someone did a SAVE when there was no program in memory. It +could also mean this isn\(aqt an AMSB file at all. +.UNINDENT +.SS Warnings +.sp +These are non\-fatal: \fBlistamsb\fP logs the warning to stderr, then +continues processing. +.INDENT 0.0 +.IP \(bu 2 +unexpected EOF, file truncated? +.sp +A tokenized AMSB file always ends with three null bytes (\fI$00\fP). +This file doesn\(aqt. Probably the rest of the file is missing. +.IP \(bu 2 +line \fIL\fP: EOL address \fIA\fP too (low|high) +.sp +Each line begins with the address of the next line. If the address +is below \fI$0700\fP, it\(aqs below the minimum value of \fIMEMLO\fP, which +is impossible. If it\(aqs above \fI$bc1f\fP, it would be in the display +list, screen memory, or OS ROM (also impossible). File is +corrupt, or not an AMSB file. +.IP \(bu 2 +line \fIL\fP: EOL address \fIA\fP <= previous \fIB\fP +.sp +Corrupt file, or not an AMSB file. +.IP \(bu 2 +line \fIL\fP is suspiciously long +.sp +The line is >128 bytes long, but less than 256. AMSB can execute +lines of this length, but it\(aqs impossible to actually enter them +in the editor, because a logical line can\(aqt be longer than 3 +screen lines. Possibly corrupted file. +.IP \(bu 2 +line \fIL\fP is impossibly long +.sp +The line is >= 256 bytes long. AMSB will crash, if you try to +LOAD the file. Corrupted file. +.IP \(bu 2 +line \fIL\fP EOL address doesn\(aqt match actual line length \fIN\fP +.sp +Corrupt file, or not an AMSB file. +.IP \(bu 2 +line number out of order +.sp +Corrupt file, or not an AMSB file. +.IP \(bu 2 +line number out range +.sp +The program contains a line number that\(aqs greater than \fI63999\fP\&. How +did that happen? +.IP \(bu 2 +line \fIL\fP has character \fIC\fP outside of a string. maybe Atari BASIC? +.sp +This happens when ATASCII codes 0 to 31 (\fI$1f\fP) appear in the program. +AMSB can create files like this, but at runtime, it\(aqs a syntax error. +More likely, it means this is an Atari BASIC file. +.IP \(bu 2 +program size doesn\(aqt match size in header +.sp +Might mean this isn\(aqt an AMSB file. If you\(aqre sure it is, it might +be truncated, or part of the file might have been overwritten with +\fI$00\fP bytes. It could also mean the length in the header has somehow +gotten corrupted. +.IP \(bu 2 +trailing garbage at end of file +.sp +Might mean this isn\(aqt an AMSB file. If you\(aqre sure it is, garbage +data has somehow gotten appended to the file, after the three \fI$00\fP +bytes that end the program. Maybe it was downloaded with a crappy +version of XMODEM that pads the last block. The good news is, +AMSB will just ignore the garbage when you LOAD the file, so it +won\(aqt hurt anything. +.IP \(bu 2 +file has \fIN\fP unknown tokens +.sp +Either the file is corrupt, or this is a file from some \fIother\fP variant +of Microsoft BASIC (e.g. Commodore, AppleSoft, GW\-BASIC, TRS\-80). If +you see this warning, you\(aqll also see \fIN\fP <unknown token \fIXX\fP> +messages in the actual listing. +.UNINDENT +.SH ENVIRONMENT +.INDENT 0.0 +.TP +.B \fBCOLORIZE_AMSB\fP +Path to the \fBcolorize\-amsb\fP executable. Can be the absolute path +or just the executable (searched for in \fBPATH\fP). If not set, +defaults to \fIcolorize\-amsb\fP\&. +.UNINDENT +.SH LIMITATIONS +.sp +\fBlistamsb\fP may behave strangely when fed something other than a +tokenized AMSB program, at least if the first byte in the file +is \fB$00\fP or \fB$01\fP\&. Unfortunately, tokenized Atari BASIC (and +variants like Turbo and BASIC XL) begin with \fB$00\fP\&. Usually +you\(aqll get this error: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +not an AMSB file: program size too small (0). Atari BASIC file? +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...but occasionally you may get a bunch of warnings and gibberish +output instead. +.SH EXIT STATUS +.sp +0 for success, 1 if there was an error reading the input (e.g. file +not found), or 2 if the input file had errors or warnings (see +\fBDIAGNOSTICS\fP). +.SH COPYRIGHT +.sp +WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. +.SH AUTHOR +.INDENT 0.0 +.IP B. 3 +Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +\fBa8cat\fP(1), +\fBa8eol\fP(1), +\fBa8xd\fP(1), +\fBatr2xfd\fP(1), +\fBatrsize\fP(1), +\fBaxe\fP(1), +\fBbas2aplus\fP(1), +\fBblob2c\fP(1), +\fBblob2xex\fP(1), +\fBcart2xex\fP(1), +\fBcxrefbas\fP(1), +\fBdasm2atasm\fP(1), +\fBdiffbas\fP(1), +\fBdumpbas\fP(1), +\fBf2toxex\fP(1), +\fBfenders\fP(1), +\fBlistbas\fP(1), +\fBlistamsb\fP(1), +\fBprotbas\fP(1), +\fBrenumbas\fP(1), +\fBrom2cart\fP(1), +\fBunmac65\fP(1), +\fBunprotbas\fP(1), +\fBvxrefbas\fP(1), +\fBwhichbas\fP(1), +\fBxex1to2\fP(1), +\fBxexamine\fP(1), +\fBxexcat\fP(1), +\fBxexsplit\fP(1), +\fBxfd2atr\fP(1), +\fBxex\fP(5), +\fBatascii\fP(7), +\fBfauxtari\fP(7). +.sp +Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference +Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. +.\" Generated by docutils manpage writer. +. |