initial commit

1 files changed, 244 insertions, 0 deletions

diff --git a/dasm2atasm.1 b/dasm2atasm.1
new file mode 100644
index 0000000..c4738ad
--- /dev/null
+++ b/dasm2atasm.1
@@ -0,0 +1,244 @@
+.\" 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 "DASM2ATASM" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+dasm2atasm \- Convert 6502 assembly source from dasm syntax to atasm or ca65 syntax.
+.\" RST source for dasm2atasm(1) man page. Convert with:
+.
+.\" rst2man.py dasm2atasm.rst > dasm2atasm.1
+.
+.\" rst2man.py comes from the SBo development/docutils package.
+.
+.SH SYNOPSIS
+.sp
+dasm2atasm \fB\-[aclmr]\fP \fIinfile.dasm\fP [\fIoutfile.m65\fP]
+.SH DESCRIPTION
+.sp
+\fBdasm2atasm\fP tries its best to convert \fBdasm\fP\(aqs syntax into something  that
+\fBatasm\fP or \fBca65\fP can use.  Since \fBatasm\fP\(aqs syntax is 99% compatible with that
+of \fBMAC/65\fP, \fBdasm2atasm\fP can be used for that as well.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B  \-a
+Atari EOLs. The output will have all UNIX \fB\en\fP characters replaced
+with the EOL character \fB0x9b\fP used on the Atari.
+.TP
+.B  \-c
+ca65 output. See \fBCA65 NOTES\fP, below.
+.TP
+.B  \-l
+Line  numbers.  Each  line  in the output file will be numbered,
+starting from \fB1000\fP and counting by \fB10\fP\&.
+.TP
+.B  \-m
+MAC/65 mode. Shortcut for \fB\-a \-l\fP\&. Output  will  be  suitable  for
+loading in MAC/65 with the ENTER command (not LOAD!).
+.TP
+.B  \-r
+Process  include  files  recursively. This is done by spawning a
+new \fBdasm2atasm\fP process for each included file, which is somewhat
+resource\-intensive if there are lots of nested include files.
+.UNINDENT
+.SH NOTES
+.sp
+\fBdasm2atasm\fP is written in Perl, so it requires a Perl interpreter
+to be available at runtime. If your installed perl binary is not located
+at \fB/usr/bin/perl\fP, simply edit the \fBdasm2atasm\fP script and
+change the location of perl in the first line (the one beginning with
+\fI#!/usr/bin/perl\fP). Alternatively, you may run \fBdasm2atasm\fP with
+a command like \fBperl dasm2atasm\fP, though the \fB\-r\fP option will
+not work correctly in that case.
+.sp
+There are a few \fBdasm\fP pseudo\-ops that just aren\(aqt present in
+\fBatasm\fP:
+.INDENT 0.0
+.TP
+.B \fIprocessor\fP
+\fBdasm\fP supports several target CPUs with different instruction sets,
+and requires a \fBprocessor\fP directive in the source code to set the
+CPU type. \fBatasm\fP only supports the 6502. \fBdasm2atasm\fP includes
+the \fBprocessor\fP directive as a comment, in the output file.
+echo
+.sp
+\fBdasm\fP\(aqs \fBecho\fP directive allows multiple arguments, and can interpolate
+values. Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+echo $100\-*, " bytes of zero page left"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBatasm\fP\(aqs closest equivalent is \fB\&.warn\fP, but it only accepts one
+argument, which it treats as a constant string. \fBdasm2atasm\fP includes
+all \fBecho\fPs in the input as comments in the output.
+.TP
+.B \fIseg, seg.u\fP
+\fBatasm\fP doesn\(aqt support these at all. \fBdasm2atasm\fP\(aqs output will
+include them as comments.
+.UNINDENT
+.sp
+\fIsta.w, sty.w, stx.w\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBatasm\fP doesn\(aqt provide a way to force word addressing, when the operand
+of a store instruction will allow zero page addressing to be used. You\(aqll
+run into this a lot in Atari 2600 code, or any other 6502 code that has to
+maintain sync with an external piece of hardware: using word addressing
+causes the 6502 to use an extra CPU cycle, which is a commonly used
+method of adding a 1\-cycle delay.
+.sp
+\fBdasm2atasm\fP will convert any such instructions into \fB\&.byte\fP
+pseudo\-ops that will generate the correct code. Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+;;;;; dasm2atasm: was \(gasta.w COLUPF\(aq, using .byte to generate opcode
+\&.byte $8d, <COLUPF, >COLUPF
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBdasm\fP actually supports the \fI\&.w\fP and \fI\&.b\fP extensions to
+most instructions and a few pseudo\-ops. \fBdasm2atasm\fP doesn\(aqt handle
+this in the general case.
+.UNINDENT
+.UNINDENT
+.sp
+\fI\&. (dot) as program counter\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBdasm\fP allows the use of either \fB\&.\fP or \fB*\fP for the current
+program counter. \fBatasm\fP only allows \fB*\fP\&. \fBdasm2atasm\fP doesn\(aqt
+attempt to translate this, as it doesn\(aqt include a full expression parser.
+.UNINDENT
+.UNINDENT
+.sp
+\fI( ) (parentheses)\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBdasm\fP allows parentheses or square brackets in expressions:
+\fI(1+2)*3\fP and \fI[1+2]*3\fP are equivalent. \fBatasm\fP
+only allows square brackets. \fBdasm2atasm\fP does not attempt to
+translate this currently, though a future version may.
+.UNINDENT
+.UNINDENT
+.sp
+\fImacro arguments\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBdasm\fP uses \fB{1}\fP, \fB{2}\fP, etc. to refer to macro arguments
+within a macro definition. \fBatasm\fP uses \fB$1\fP, \fB$2\fP, etc.
+\fBdasm2atasm\fP makes no attempt to translate these.
+.UNINDENT
+.UNINDENT
+.SH CA65 NOTES
+.sp
+\fBca65\fP output is actually the same as the \fBatasm\fP output, with
+the addition of \fB\&.FEATURE pc_assignment\fP and
+\fB\&.FEATURE labels_without_colons\fP at the beginning of the source.
+.sp
+Most Atari source written with \fBdasm\fP is intended to be assembled
+with the \fB\-f3\fP option (raw output). The equvalent option for
+\fBatasm\fP is \fB\-r\fP, and for \fBca65\fP (and its linker,
+\fBld65\fP) it is \fB\-t none\fP\&.
+.sp
+However, \fBca65\fP\(aqs linker (\fBld65\fP) will not correctly handle
+files with multiple \fBORG\fP directives, when using \fB\-t none\fP\&. Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+start ORG $0600 ; or *= $0600 in atasm
+ ; 5 bytes of code here
+ LDA #1 ; example code, doesn\(aqt do anything useful
+ STA 0
+ RTS
+
+; dasm or atasm will include 251 bytes of filler here
+; (dasm fills with $00 by default; atasm fills with $ff)
+
+ORG $0700 ; or *= $0700 in atasm
+ ; 5 more bytes of code here
+ LDA #2
+ STA 1
+ RTS
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+With \fBdasm \-f3\fP or \fBatasm \-r\fP, the output will be 261 bytes of
+object code. With \fBca65 \-t none\fP and \fBld65 \-t none\fP, the filler
+bytes will not be included, and the output will be only 10 bytes long.
+The correct solution to this would be to rewrite the code so that it
+doesn\(aqt include any Atari\-specific header information (e.g. binary
+load headers as data bytes), then use \fB\-t atari\fP to have \fBca65\fP
+generate the binary load headers (though as far as the author knows,
+\fBca65\fP doesn\(aqt know how to generate other records such as Atari
+boot disk or cartridge headers).
+.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.
+.