Re: [stella] HTML version of Stella Programmer's Guide

Subject: Re: [stella] HTML version of Stella Programmer's Guide
From: "B. Watson" <atari@xxxxxxxxxxxxxx>
Date: Sun, 16 Sep 2001 03:48:07 -0400 (EDT)
On Sat, 15 Sep 2001, Glenn Saunders wrote:

> Excellent work.
> My advice is to bite the bullet and table-convert the rest of the 
> document.  If you need help on this, let me know.

I'm already about halfway done with it, I just wanted to go ahead and put up
what I had, so people could see it (and also because I had done all I was
going to do, tonight). But thanks for the offer anyway.

> What I'd like to see from this is perhaps to begin grafting in more 
> information into the guide.  There is little need to preserve the integrity 
> of the original document anymore if the goal is just to use it to learn the 
> 2600.  It should be just part of a larger document, and once you get into 
> HTML, then it's quite easy to add stuff directly into this page or linked 
> from it.

That's something I'd thought of too. I hadn't decided whether I'd just add
stuff to the guide itself, or as external documents. I was trying to preserve
at least the flavor of the original document, minus the typos. What I was
thinking is that the guide can have lots of links to `How-to' documents,
clearly marked as external links. That way, someone who really wanted to get
a feel for the material in its original form could just ignore the links, or
look at them later.

Then again, though, if they want the document in its original form, they could
just print out the PDF version. Hmmm.

> For instance, you could the table of frequency and note values for the 
> sound registers, or the analysis of how the 2600 reacts to HMOVE at 
> particular clock counts that was done here on Stellalist.

Actually, I'd like to include large chunks of the Stella list archives. I'd
like to get permission from people before using their stuff, though I don't
imagine anyone will have a problem with it (considering it was posted to a
public mailing list).

> You could also have a full color chart with best-guess swatches (table cell 
> background colors in RGB).  This could be done for NTSC and PAL.

Hmm, 1x1 GIFs of the right color, scaled to fit a table cell, might work
better for this. There are still some people using browsers that don't do
colored table cells (Netscape 3.0, which I use on my laptop, doesn't).

> The guide also has no code samples.  Links to code samples would be very 
> useful.

Yes, and I'd want to make sure I included the highest quality code, which means
most of it wouldn't be written by me... or if I did write some of it, I'd want
expert opinions on it, as I'm still learning and don't know all the `secrets'
that I'd pick up if I'd been doing this for years instead of months.

> It would also be a good idea to split up the guide into chunks instead of 
> making it one big page.
> stellaguide_toc.html
> stellaguide_tia.html
> stellaguide_pia.html
> stellaguide_tia_tech.html
> stellaguide_registers.html
> You can still link internally to external links:
> ala
> href="stellaguide_registers.html#wsync"

Actually, I want to keep the all-in-one version. If you've got a fast
connection, or you're looking at it locally, it's handy to be able to use
your browser's search function on a large document. I do think it'd be a
good idea to have a split-up version available, which I will probably
generate with a perl script and some comment tags embedded in the HTML
(like <!-- begin part 1 -->text text text<!-- end part 1 -->).

I personally would prefer the all-in-one format anyway, even on a slow
connection, since I'd just be downloading it once. That's the real reason
I did it that way to start with.

> And all the diagram images should probably be links to the full image or 
> thumbnails, not inline fullsize images.

I started doing that, too (with the hand-drawn tech diagrams), and will
finish it. Thumbnails wouldn't be too useful, I wouldn't think, so I'll
just have links to the images.

Also, I used gv (ghostview) to render the PDF version, then took screenshots
of that, to make the images I used. I may get better results with Adobe's
Acrobat Reader, if the text in the images is actually text and not just
bitmapped graphics. I'll try that as soon as I get around to installing
Acrobat Reader (yes, there's a Linux version).

As for adding content... Code snippets would be good. So would explanations
in `laymans' terms, for some of the more technical stuff, and specific examples
of techniques from existing games, especially ones that have been disassembled
and commented by list members. A glossary might not be a bad idea (I already
knew what a `color clock' was from doing Atari 800 programming, years ago,
but a newbie might not). Also a hardware hackers' section would be cool, and
so would a development section (introduction to DASM syntax, how to set up
a build environment, etc.)... Most of this information is already available,
it'd just be a matter of getting it all in one document (or one linked set of

If enough people wanted to work on this, I'd be willing to set up a CVS
server, or maybe a SourceForge project, so we could all directly make changes.
Actually, something like this, a Wiki-style web site would work pretty well
(if you're not familiar with Wiki, go have a look at (which
seems to be down right now. Grr.))

Anyway, it's almost 4am, if I'm smart I'll go to bed now...




If a trainstation is the place where trains stop, what is a workstation?

Archives (includes files) at
Unsub & more at

Current Thread