Ophis/doc/preface.sgm

<preface>
  <title>Preface</title>
  <para>
    The Ophis project started on a lark back in 2001.  My graduate
    studies required me to learn Perl and Python, and I'd been playing
    around with Commodore 64 emulators in my spare time, so I decided
    to learn both languages by writing a simple cross-assembler for
    the 6502 chip the C-64 used in both.
  </para>
  <para>
    The Perl one&mdash;uncreatively
    dubbed <quote>Perl65</quote>&mdash;was quickly abandoned, but the
    Python one saw more work. When it came time to name it, one of the
    things I had been hoping to do with the assembler was to produce
    working Apple II programs.  <quote>Ophis</quote> is Greek
    for <quote>snake</quote>, and a number of traditions also use it
    as the actual <emphasis>name</emphasis> of the serpent in the
    Garden of Eden.  So, Pythons, snakes, and stories involving really
    old Apples all combined to name the
    assembler.<footnote><para>Ironically, cross-platform development
    for the Apple II is extremely difficult, and while Ophis has been
    very successfully used to develop code for the Commodore 64,
    Nintendo Entertainment System, and Atari 2600, it has yet to
    actually be deployed on any of the Apples which inspired its
    name.</para></footnote>
  </para>
  <para>
    Ophis slowly grew in scope and power over the years, and by 2005
    was a very powerful, flexible macro assembler that saw more use
    than I'd expect.  In 2007 Ophis 1.0 was formally released.
    However, Ophis was written for Python 2.1 and this became more and
    more untenable as time has gone by. As I started receiving patches
    for parts of Ophis, and as I used it for some projects of my own,
    it became clear that Ophis needed to be modernized and to become
    better able to interoperate with other toolchains. It was this
    process that led to Ophis 2.
  </para>
  <para>
    This is an updated edition of <emphasis>Programming With
    Ophis</emphasis>, including documentation for all new features
    introduced and expanding the examples to include simple
    demonstration programs for platforms besides the Commodore 64. It
    also includes updated versions of the <emphasis>To HLL and
    Back</emphasis> essays I wrote using Ophis and Perl65 as example
    languages.
  </para>

  <section>
    <title>Getting a copy of Ophis</title>
    <para>
      As of this writing, the Ophis assembler is hosted at Github. The
      latest downloads and documentation will be available
      at <ulink url="http://github.com/michaelcmartin/Ophis"></ulink>. If
      this is out-of-date, a Web search on <quote>Ophis 6502
      assembler</quote> (without the quotation marks) should yield its
      page.
    </para>
    <para>
      Ophis is written entirely in Python and packaged using the
      distutils.  The default installation script on Unix and Mac OS X
      systems should put the files where they need to go.  If you are
      running it locally, you will need to install
      the <literal>Ophis</literal> package somewhere in your Python
      package path, and then put the <command>ophis</command> script
      somewhere in your path.
    </para>
    <para>
      For Windows users, a prepackaged system made
      with <command>py2exe</command> is also available.  The default
      Windows installer will use this.  In this case, all you need to
      do is have <command>ophis.exe</command> in your path.
    </para>
  </section>

  <section>
    <title>About the examples</title>
    <para>
      Versions of the examples in this book are available from the Ophis site. Windows users will find them packaged with the distribution; all other users can get them as a separate download or pull them directly from github.
    </para>
    <para>
      The code in this book is available in
      the <literal>examples/</literal> subdirectory, while extra
      examples will be in subdirectories of their own with brief
      descriptions.
    </para>
    <para>
      Most examples will require use of <emphasis>platform
      headers</emphasis>&mdash;standardized header files that set
      useful constants for the target system and, if needed, contain
      small programs to allow the program to be loaded and run. These
      are stored in the <literal>platform/</literal> subdirectory.
    </para>
  </section>
</preface>