initial commit

1 files changed, 392 insertions, 0 deletions

diff --git a/unmac65.1 b/unmac65.1
new file mode 100644
index 0000000..71c29c9
--- /dev/null
+++ b/unmac65.1
@@ -0,0 +1,392 @@
+.\" 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 "UNMAC65" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+unmac65 \- Detokenize Atari 8-bit Mac/65 SAVEd files.
+.\" RST source for unmac65(1) man page. Convert with:
+.
+.\" rst2man.py unmac65.rst > unmac65.1
+.
+.\" rst2man.py comes from the SBo development/docutils package.
+.
+.SH SYNOPSIS
+.sp
+\fBunmac65\fP [\fI\-options\fP] \fIfile.m65\fP
+.SH DESCRIPTION
+.sp
+\fBunmac65\fP reads files created with Mac/65\(aqs SAVE command (usually called
+\&.M65 files) and converts them back to plain text assembly source.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B  \-a
+Use ATASCII EOLs. This option is not available in Atari version,
+since it already uses ATASCII.
+.TP
+.B  \-c
+Convert non\-printable characters constants to hex bytes.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fB\-cc\fP
+Convert all character constants to hex bytes.
+.TP
+.B \-e nnn[,iii]
+Renumber the program, starting at line \fInnn\fP, with increment \fIiii\fP\&.
+\fInnn\fP must be present, and must be an integer greater than or equal
+to zero. \fIiii\fP is optional, must be positive (non\-zero), and
+defaults to 10 if not given.
+.sp
+Mac/65\(aqs maximum line number is 65535. unmac65 will happily renumber
+lines with no upper bound (other than unsigned int overflow), so pay
+attention.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B  \-h
+Show command\-line help.
+.TP
+.B  \-i
+Convert inverse video (in comments and strings) to standard ASCII.
+Lines that were converted will get a comment "\fI; XXX inverse\fP" at
+the end. This option also enables the \-c option.
+.sp
+If the program contained any inverse\-video strings, the resulting
+output will \fInot\fP reassemble correctly; you\(aqll have to edit it to
+e.g. change the formerly inverse video strings to a list of hex
+bytes.
+.sp
+This option is not available in the Atari version.
+.TP
+.B  \-l
+Lowercase mnemonics and hex constants (but not labels or comments).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fB\-la\fP
+Lowercase mnemonics, hex constants, labels, and comments (but not
+strings or character constants).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B  \-n
+No line numbers in output.
+.TP
+.BI \-o \ file
+Output to \fIfile\fP (default = standard output).
+.TP
+.B  \-q
+Add closing single\-quote to character constants. Changes this:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+LDA #\(aqA
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\&...to this:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+LDA #\(aqA\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B  \-p
+Omit leading . (period) from pseudo\-ops (e.g. print BYTE for .BYTE).
+.TP
+.B  \-t
+Replace leading spaces with tabs.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fB\-ta\fP
+Replace spaces between all fields with tabs.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B  \-v
+Verbose output (dump tokens in hex). Useful for examining damaged
+\&.M65 files, or debugging unmac65 itself.
+.UNINDENT
+.SS Human\-readable Output Options
+.sp
+The \-m, \-r, and \-u options are not available for the Atari, and may or
+may not be useful on non\-Linux OSes.
+.INDENT 0.0
+.TP
+.B  \-m
+Print inverse video as pseudo\-underlined, using backspace and
+underscore. Useful for piping to more(1) or less(1). Can be combined
+with \-u.
+.TP
+.B  \-r
+Print inverse video as reverse video using xterm/ANSI compatible
+escape sequences. Can be combined with \-u. Useful for piping to
+less(1) provided its \-r or \-R option is used.
+.TP
+.B  \-u
+Print ATASCII control characters as their nearest Unicode
+equivalents (encoded in UTF\-8). Depending on your terminal,
+combining this option with \-r may not work properly. Also, depending
+on the font(s) your terminal is using, you may see boxes instead of
+control characters. If this happens, try a different font, or a
+different terminal (the author recommends rxvt\-unicode).
+.UNINDENT
+.sp
+Options may not be bundled (use "\-p \-t", not "\-pt").
+.sp
+Unlike most UNIX\-flavored programs, the CLI options are
+case\-insensitive. This is to make life easier for users of the Atari
+version, where uppercase is the normal way of doing things.
+.sp
+The \-c, \-cc, \-l, \-la, \-n, \-p, \-t, \-ta options are provided to assist in
+porting Mac/65 programs to other assemblers, such as ca65 or dasm.
+unmac65\(aqs output with none of these options (or with \-n only) is
+acceptable as input for the atasm assembler. This is true even if there
+are inverse video strings: they look funny when viewing the file, but
+atasm handles them correctly.
+.sp
+The \-v option prints the hex bytes for each line (preceded by ";;" and
+the line number) after that line\(aqs detokenized listing.
+.sp
+Note that the output from \-m, \-r, \-u is intended for humans to read.
+They\(aqre not very useful if you\(aqre trying to port Mac/65 code to a
+different assembler, as none of them know what to do with the
+underlines, ANSI codes, or pseudo\-ATASCII Unicode characters.
+.SH FILE FORMAT
+.sp
+A tokenized Mac/65 file consists of:
+.sp
+Header: 2 byte $FE $FE signature, followed by the 2 byte program length
+in LSB/MSB format. Length doesn\(aqt include the 4 header bytes.
+.sp
+The rest of the file consists of lines of code. Each line is:
+.sp
+Line number, 2 bytes (LSB/MSB format)
+.sp
+Line length, 1 byte. Total length, including the line number and length
+bytes.
+.sp
+Tokens. Length minus 3 bytes of tokens. If the line is labelled, the
+label will appear first, as a tokenized string (see below).
+.sp
+Whether or not there\(aqs a label, the next byte is the token for a
+mnemonic (or pseudo\-op). Lines containing only a comment will have a
+special token meaning "no mnemonic".
+.sp
+After the mnemonic token, 0 or more bytes of operands. Quoted strings or
+labels as operands are stored as a tokenized string. Hex or decimal
+constants are preceded by a token indicating the length (one or two
+bytes) and the type (hex or decimal).
+.sp
+If there is a comment, the last byte of the operand field will be an
+ASCII semicolon. The remaining bytes on the line are the comment in
+ASCII form.
+.sp
+Tokenized strings can occur in the label or operand parts of the line.
+The first byte is the length of the string in bytes, with the high bit
+set (e.g. $84 for a 4\-byte string), followed by that number of ASCII
+bytes. The length doesn\(aqt include the first byte, so e.g. the string
+"ABC" is stored as $83, $41, $42, $43. Mac/65 doesn\(aqt allow empty
+strings, so a zero\-length string (length byte $80) is an error.
+.sp
+There are separate sets of tokens for mnemonics/pseudo\-ops and operands.
+Mnemonic/pseudo\-op tokens run from 0 to $5F, and operand tokens run from
+0 to $4D (with 0\-$09 being "special", and a few invalid tokens in the
+range $0A\-$4D). See the C source for the full list (or a hex/ascii dump
+of the Mac/65 ROM, which is where I got the lists to put them in the C
+source). Also, you can run unmac65 with the \-v option to get a
+line\-by\-line hex dump of the tokens.
+.SH DIAGNOSTICS
+.sp
+unmac65: line XX contains NN non\-printable ATASCII characters <= $1F
+.sp
+Self\-explanatory. Depending on what you\(aqre going to use the converted
+file for, this may or may not be a problem. Non\-fatal. This warning
+doesn\(aqt occur in the Atari version of unmac65. Also, it doesn\(aqt occur if
+the \-u option is in use.
+.sp
+unmac65: line XX contains NN inverse ATASCII characters >= $80
+.sp
+Self\-explanatory. Depending on what you\(aqre going to use the converted
+file for, this may or may not be a problem. Non\-fatal. Use the \-i option
+to convert inverse video to normal. This warning doesn\(aqt occur in the
+Atari version of unmac65. Also, it doesn\(aqt occur if any of the \-i, \-m,
+or \-r options are in use.
+.sp
+unmac65: not a mac/65 file (missing $FEFE header)
+.sp
+Self\-explanatory. Fatal error.
+.sp
+unmac65: corrupt or truncated file?
+.sp
+The length of the last line in the file is longer that the number of
+bytes remaining in the file (according to the file header). Fatal error.
+.sp
+unmac65: unexpected EOF?
+.sp
+The file is shorter than the file header\(aqs program length. Probably the
+file is truncated; less probably, the length header got scrambled
+somehow. Fatal error.
+.sp
+unmac65: file is too short (N bytes)
+.sp
+The minimum length for a Mac/65 file is 4 bytes (which would be an empty
+program containing no lines). The input file was shorter than 4 bytes.
+Fatal error. (Actually, Mac/65 will never produce a 4\-byte file, it\(aqs
+just the theoretical minimum)
+.sp
+unmac65: file is valid but contains no lines of code
+.sp
+Self\-explanatory. Mac/65 creates a file like this if the SAVE command is
+given before entering any code (at startup or after a NEW). The SAVEd
+file will be 5 bytes in length, and utterly useless. Non\-fatal warning.
+.sp
+unmac65: line #lll <= prev line #mmm
+.sp
+The line numbers in the file are supposed to be stored in ascending
+order. Somehow this file has the line numbers out of order. Non\-fatal,
+but probably the rest of the file will be garbage.
+.sp
+unmac65: internal error, state n
+.sp
+This is a "this should never happen" error. It indicates a bug in the
+program. If you ever see this error, please notify the author, and send
+a copy of the Mac/65 program that caused it. This is a non\-fatal error,
+but the output might be garbage.
+.sp
+[$nn?] or <$nn?> in the output (where nn is 2 hex digits)
+.sp
+These indicate unknown/invalid tokens. Either the file is damaged, or
+there is a bug in the program. These are non\-fatal errors. If you ever
+see them, please contact the author, and send a copy of the Mac/65
+program that caused them.
+.sp
+unmac65: ignoring extra junk at EOF
+.sp
+The file contains more bytes than the program length header says it
+should. This usually means the file was stored on an old DOS disk or
+transferred with a broken XMODEM implementation, and was padded to the
+sector/block size. Alternately, the header bytes got corrupted somehow
+(this is highly unlikely, especially if there are no other
+errors/warnings). Non\-fatal error.
+.sp
+Other errors are possible (e.g. disk full, I/O error reading input), but
+they\(aqre not specific to unmac65; no need to list them all there.
+.sp
+Fatal errors result in unmac65 terminating. A non\-fatal error can
+usually be recovered from, though the line that caused it will probably
+be printed strangely.
+.sp
+It\(aqs probably worth mentioning also that Mac/65 source files can contain
+ATASCII graphics or escape codes, although it\(aqs not a very common
+practice. If you see strange stuff and/or your terminal misbehaves when
+writing to standard output, try writing to a file (\-o option) instead.
+See also the \-m, \-r, \-u options for human\-readable output. The Atari
+version will render ATASCII graphics just fine, of course.
+.SH EXIT STATUS
+.sp
+unmac65 will normally exit with a zero (success) status upon completion.
+A non\-zero status indicates a fatal error.
+.SH LIMITATIONS
+.sp
+The main difference between Mac/65\(aqs LIST output and unmac65\(aqs output is
+that Mac/65 lines up the label, mnemonic, and comment fields (if the
+field contents are short enough to fit in the allotted width), while
+unmac65 makes no attempt to do so. If the field alignment is important
+to you, try the \-t or \-ta options (which insert hard tabs, unlike
+mac65\(aqs spaces). A future version of unmac65 may correct this minor
+flaw, but as it stands, I\(aqve tested quite a few .M65 files by running
+them through unmac65, then ENTERing unmac65\(aqs listed file in Mac/65 and
+reSAVEing them... In all cases, the newly created tokenized files
+compare identically to the original .M65 file. If you come across a file
+that doesn\(aqt do this, yet is valid (can be assembled without error by
+Mac/65), please send it to me, so I can fix unmac65!
+.sp
+Although a few helpful options have been added for porting Mac/65
+sources to other assemblers, unmac65 doesn\(aqt completely automate the
+process. Depending on the assembler you\(aqre using, you may still have a
+lot of manual edits to make. A future version of unmac65 may add a few
+more options, but some hypothetical complex porting functions (like
+"convert to ca65 format") would require implementing a much more complex
+parser (such as a yacc\-based recursive descent parser). Most likely this
+will never happen, if only because I want the program to be usable on
+the Atari itself, with its limited memory and C compiler support.
+.sp
+There are a few ways that an invalid file can sneak past unmac65\(aqs error
+checking. The same files wouldn\(aqt load correctly in Mac/65 either, but
+generally don\(aqt cause any errors in Mac/65 (just silent failure). It\(aqd
+be nice if unmac65 could act as a "M65 lint" for Mac/65 users.
+.sp
+unmac65 is mostly developed/tested against the OSS Mac/65 v1.01
+cartridge. The various disk versions appear to use the same tokenized
+format, but haven\(aqt been well tested. If you have problems, please
+contact the author.
+.sp
+(A further limitation is that the documentation isn\(aqt very concise.
+Sorry about that.)
+.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
+\fBa8eol\fP(1),
+\fBa8utf8\fP(1),
+\fBatr2xfd\fP(1),
+\fBatrsize\fP(1),
+\fBaxe\fP(1),
+\fBblob2c\fP(1),
+\fBcart2xex\fP(1),
+\fBdasm2atasm\fP(1),
+\fBfenders\fP(1),
+\fBrom2cart\fP(1),
+\fBunmac65\fP(1),
+\fBxexcat\fP(1),
+\fBxexsplit\fP(1),
+\fBxfd2atr\fP(1).
+.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.
+.