diff options
Diffstat (limited to 'unmac65.1')
| -rw-r--r-- | unmac65.1 | 392 |
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. +. |