path: root/listbas.1

.\" 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 "LISTBAS" 1 "2024-07-09" "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\-v\fP] [\fB\-i\fP] [\fB\-a\fP | \fB\-m\fP ] \fBinput\-file\fP
.SH DESCRIPTION
.sp
\fBlistbas\fP acts like the \fILIST\fP command in BASIC. It reads a
tokenized (SAVEd) BASIC program and prints the code in human\-readable
format.
.sp
By default, output is Unicode in UTF\-8 encoding, with ANSI/VT220
escape sequences for inverse video and color syntax highlighting.
.SH OPTIONS
.SS List options
.INDENT 0.0
.TP
.B \fB\-a\fP
Output raw ATASCII; no translation to the host character set. Must be
used with redirection; \fBlistbas\fP will not write ATASCII to the terminal.
.TP
.B \fB\-b\fP
Use bold, for color output. This may make it easier to read on
some terminals. Or, it may hurt your eyes...
.TP
.B \fB\-i\fP
Include the immediate mode command (line 32768) in the output.
.TP
.B \fB\-m\fP
Output "magazine listing". See the \fB\-m\fP option for \fBa8cat\fP for details.
.TP
.B \fB\-n\fP
No color. Has no effect if \fB\-a\fP or \fB\-m\fP are in effect, since these
modes don\(aqt support color anyway.
.UNINDENT
.SS General Options
.INDENT 0.0
.TP
.B \fB\-\-help\fP
Print usage message and exit.
.TP
.B \fB\-\-version\fP
Print version number and exit.
.TP
.B \fB\-v\fP
Verbose operation. When displaying a number in verbose mode, it will
be prefixed with \fI$\fP if it\(aqs in hex, or no prefix for decimal.
.UNINDENT
.SH COLORS
.sp
Color output only works on terminal emulators (or real terminals)
that support ANSI/VT220 style escape codes. This includes all modern
terminal emulators, and most not\-so\-modern ones in the UNIX world.
.sp
The color scheme is:
.INDENT 0.0
.TP
.B \fByellow\fP
Commands. Also "command operators" such as the \fBGOTO\fP in \fBON/GOTO\fP and
the \fBSTEP\fP in a \fBFOR\fP command. These are really operators as far as
BASIC is concerned, but it makes more sense to colorize them as commands.
.TP
.B \fBgreen\fP
Operators (except functions and "command operators").
.TP
.B \fBpurple\fP
Functions.
.TP
.B \fBred\fP
Numbers (except line numbers at the start of a line) and string
constants.
.TP
.B \fBcyan\fP
Line numbers at the start of a line, comments (\fBREM\fP text) and \fBDATA\fP elements.
.UNINDENT
.sp
Variable names and commas between \fBDATA\fP elements are not highlighted,
so they\(aqll appear in the default foreground color (usually white if the
terminal has a black background, or black if the background is white).
.sp
Note that nothing is highlighted in blue. This is because it\(aqs
difficult to read on many terminals. Also, black and white are not
used because presumably, one or the other is the background color of
the terminal.
.SH NOTES
.sp
\fBlistbas\fP will refuse to operate on a LIST\-protected program with
scrambled variable names. For code\-protected programs, it will stop at
the line with the invalid offset. Use \fBunprotbas\fP(1) to remove the
protection.
.sp
\fBlistbas\fP is similar to Jindroush\(aqs \fBchkbas\fP(1). The main differences are:
.INDENT 0.0
.IP \(bu 2
\fBlistbas\fP prints ATASCII graphics as Unicode equivalents, so the listing
looks very similar to how it would appear on the Atari.
.IP \(bu 2
\fBlistbas\fP does color syntax highlighting.
.IP \(bu 2
\fBlistbas\fP only supports Atari BASIC, not Turbo BASIC or BASIC XL/XE.
.IP \(bu 2
\fBlistbas\fP doesn\(aqt show information about the variables. Use \fBvxrefbas\fP(1)
for that.
.IP \(bu 2
\fBlistbas\fP will not write ATASCII data to your terminal. By default, it uses
\fBa8cat\fP(1) to convert the output to something human\-readable
that won\(aqt confuse the terminal. When outputting raw ATASCII (\fB\-a\fP option),
it refuses to run if standard output is a terminal.
.IP \(bu 2
\fBlistbas\fP only lists line 32768 (the immediate mode command) if
specifically asked to do so.
.IP \(bu 2
\fBlistbas\fP doesn\(aqt print a banner on startup.
.IP \(bu 2
\fBlistbas\fP tells you if the program is protected, and refuses to operate
on variable\-protected programs.
.UNINDENT
.sp
I thought about adding an HTML output option, but there\(aqs no need: if you want
a colorful listing of an Atari BASIC program, install \fBaha\fP(1) from
\fI\%https://github.com/theZiz/aha\fP (or your distro\(aqs package repo) and run
something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
listbas PROGRAM.BAS | aha > program.html
.ft P
.fi
.UNINDENT
.UNINDENT
.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 has invalid tokens (if this
happens, you will also see a warning about it on stderr).
.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),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\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).
.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.
.