What do we need for a "How to program the X16" book?

[DragWx]

We keep dancing around this, and there seems to be plenty of newcomers showing up, so let's actually discuss this, or at least say where these materials are if they exist already.

First, Commander X16 Reference Manual. This is a Github repository with all of the documentation and reference material for the X16. It doesn't teach you how to write a program, it just tells you what all of the equipment is, what all of the features are, and all of the memory addresses you need.

Next, the X16 has several programming environments available for it, and they all work differently:

• BASIC
• Assembly
• C
• Prog8

(Not an exhaustive list, just the ones I know of or have heard)

If someone wants to play around with X16 programming, what language should be used to introduce them? Should one "book" cover multiple languages?

I wasn't around for these, but I know there were books like "101 BASIC programs for your computer". Would one of those be good teaching material for the X16? What kinds of programs should be included?

I've been a huge fan of "let's learn how this computer/game console works by writing a bunch of games for it" books for the past few years now, and the ones I've read usually use assembly language, but with the development happening on a modern PC. So, this is another language and another style of teaching.

Next, what kinds of X16-specific programming topics/skills would we want to touch on? Keyboard input, joystick input, music and sound, graphics, file access, etc. What kinds of computer science skills? Data structures, algorithms, code organization, good habits, etc.

Finally, who's the target? Are we targeting people who've never written a line of code in their lives? People who dabble with modern (at the time) programming languages like Python, C#, JS, etc? Experienced super-programmers who can write their own operating system kernel in their sleep?




I know there's talk that the 65c816 upgrade path and ROM/firmware updates complicate materials like this, but we need to be able to work around these issues and have these materials available in spite of them.

We can work around the 65c816 by teaching 65c816-safe 65c02, as far as assembly is concerned.

A book for BASIC is likely safe as long as each BASIC command keeps doing the same thing, we just might miss out on newer commands. A book for assembly language would depend on each Kernal function doing what it's supposed to be doing. A book for other languages would vary, likely just a "make sure your toolchain is up-to-date" deal.

There might be some way to unit-test each code snippet to make sure a Kernal update didn't break things, and when things do break, there should be a strategy for getting corrected information out there. I like how the X16 documentation is a Github repository, so that might be a good way to maintain learning materials as well.

[TomXP411]

We don't need to re-invent the wheel. We just need to adapt it to fit our application.

I would start with the Commodore VIC-20 User's Guide, which does an excellent job teaching BASIC. Then I'd modify the machine-specific instructions to work with the Commander.

For example: the section that talks about loading a program from tape. Re-write this to explain how to navigate the SD card and run a program using the LOAD or DOS Wedge commands.

The second thing I'd do is look up Jim Butterfield's book on 6502 machine language. He actually wrote one that covers a range of Commodore 8-bit machines, so it would be easy to take the examples for that book and modify them to work on the Commander. (It would help to have a symbolic assembler available, too, with specific instructions on how to assemble and run a program built with the assembler.)

I've considered taking on the task of translating Butterfield's book, and I actually did convert a few examples. However, the VIC-20 guide is more complicated, and so far the user project to create a similar guide for the Commander has not gotten all that far. (Maybe re-starting that in a more common tool, like Google Docs, OpenOffice Write, or Scribus would draw more contributors.)

[mortarm]

If someone wants to play around with X16 programming, what language should be used to introduce them?

Where to begin depends on your target audience. Someone with little to no programming experience should start with BASIC. Once that's mastered, you could move to one of the more advanced high-level languages, saving ML/assembly for last. This is the way schools/colleges do it as each level builds upon another.

Should one "book" cover multiple languages?

No, that would just serve to confuse the reader.

I wasn't around for these, but I know there were books like "101 BASIC programs for your computer". Would one of those be good teaching material for the X16? What kinds of programs should be included?

I had a slew of these types of books, and they don't you anything, at least not directly. Over time you might pick up a few things, but that's not a good way to learn anything.

Next, what kinds of X16-specific programming topics/skills would we want to touch on?

Again, this would depend on your target audience.
 

Finally, who's the target?

I'd start with beginners. These are the folks who'll need the most hand holding, and it'll make it easier to transition to more future books with more advanced topics.

We can work around the 65816 by teaching 65816-safe 65C02, as far as assembly is concerned.

Because the two chips are similar, both could be incorporated into a single book. I'd start with teach generic 6502, then move to chip specific capabilities of the 65C02 and 65816. Again, building on previous lessons.

A book for BASIC is likely safe as long as each BASIC command keeps doing the same thing, we just might miss out on newer commands. A book for assembly language would depend on each Kernal function doing what it's supposed to be doing. A book for other languages would vary, likely just a "make sure your toolchain is up-to-date" deal.

Which raises an interesting dilemma: How should this be published? Because of the dynamic nature of both the hardware and software, a traditional print book would be impractical, not to mention expensive as you'd have to periodically come out with new editions. So, what we need is a format that allows for easy updating and the ability to include things like diagrams, charts, images, variable typography, etc.

How ever it's done, writing a good technical book is no trivial matter. It takes time, patience, research, thorough knowledge of the subject, and the ability to write proper English grammar. And where technical books are concerned, emphasis on accuracy, both in text and program code; trying to get a faulty code example to work for a beginner can be frustrating, to say the least.

[Ed Minchau]

I would start with the Commodore VIC-20 User's Guide, which does an excellent job teaching BASIC. Then I'd modify the machine-specific instructions to work with the Commander.

I consider that book the gold standard.

[TomXP411]

I would start with the Commodore VIC-20 User's Guide, which does an excellent job teaching BASIC. Then I'd modify the machine-specific instructions to work with the Commander.

I consider that book the gold standard.

So if we were to start breaking down that book’s structure and re-creating a similar version for the X16, what would be people’s favorite format? Should this be web focused or print focused?

To encourage people contributing, what is the easiest format for people to work in? I’m tempted to go with a Google Docs or Libre Office file, using a Master Document and individual chapters per file.

I also have a great writing program called “Scrivener”, which is designed to work in bite-sized blocks, to allow you to easily organize chapters and scenes. The only problem there is Scrivener is not FOSS, and I don’t want to make people buy something in order to contribute.

[paulscottrobson]

First decide what it means. What is your "target market" ?

Commodore machines tended to have two manuals (according to Bagnall's book this was pushed through by the engineers for the Vic 20).

One was "An introduction to programming" which tends to have a very cheerful bunch of things to try, handicapped to some degree by the simplicity of BASIC 2.0, going back to basic sequencing concepts and "what are variables".

The other was the technical reference manual, which explains what everything does. To some degree, the X16 Documentation already does this. It is moot whether this needs "things to try" in the same way, written at a higher level, e.g. it assumes you can program already.

[paulscottrobson]

I would start with the Commodore VIC-20 User's Guide, which does an excellent job teaching BASIC. Then I'd modify the machine-specific instructions to work with the Commander.

I did a pretty exhaustive look over the manuals a while back. The two that stood out were the Vic 20 and the Sam Coupe as beginner orientated texts.

[DragWx]

If you're talking about the VIC-20 "Personal Computing Guide", I've read a few chapters of it and I like it so far. I think it'd be a relatively safe thing to print too, unless there are plans to completely change how the editor works, or how BASIC works on a fundamental level.

[mortarm]

I wouldn't recommend this to be a community project, otherwise your gonna run into the "too many cooks" problem and nothing will get done. Collaborations of two or three are more manageable.

[Edmond D]

I wouldn't recommend this to be a community project, otherwise your gonna run into the "too many cooks" problem and nothing will get done. Collaborations of two or three are more manageable.

I'd suggest 2-3 good editors and a community of writers submitting the bulk of the material.

As much as I'd like to help out, I know I just don't have the bandwidth for this effort at this time. My x16 has been sitting in it's shipping box for over 6 months now