This is an unofficial User's Guide for the Commander X16 (https://www.commanderx16.com) written by by the community. It aims to be considered good enough to be adopted officially by 8-Bit Industries and the Commander X16 project team.
This User's Guide takes inspiration (often shamelessly) from the Commodore VIC-20 User's Guide. This was chosen for multiple reasons, not least of which is the reputation that the VIC-20 User's Guide holds in the retro computing community for being one of the best computer manuals ever printed. When David Murray (the 8-Bit Guy) released his first Building my Dream Computer video, he introduced us to the project by explaining his experience as a 6-year-old going through the Commodore VIC-20 manual. In his second Building my Dream Computer video he explained how the VIC-20 was now a major inspiration for the Commander X16's new hardware design. Because the concept and the hardware already draw inspiration from the VIC-20, it only makes sense that the User's Guide follow suit.
One of the most important features of the VIC-20 User's Guide is that it specifically targets a wide audience of both experienced computer users and programmers, as well as people who have never even touched a computer before. Therefore it needed to explain usage of the computer with no prior knowledge of computers, starting with many things we take for granted nowadays. The Commander X16 User's Guide should likewise not make any assumptions. After all, the Commander X16 is intended to provide the experience David had as a 6-year-old in dawn of the home computing era. The User's Guide must be something that an inquisitive 6-year-old can read, even if they've never touched a keyboard before.
Another feature of the VIC-20 User's Guide was that it allowed the reader to skip to any chapter they may find interesting. All that was required was that the user read the first introductory chapter, and then they were encouraged to explore the capabilities of the computer that captivated them the most. The X16 User's Guide should be structured likewise. There is a chapter for understanding the basics of operating the computer, and then there are chapters for diving into the specifics. Each of these chapters begins with a short type-in BASIC program that gives the user a preview of what they are going to learn, and then the rest of the chapter explains what they did in detail. This pattern should be followed all througout the book.
This project uses texlive, and specifically the xelatex program for
compiling into a PDF. On Debian/Ubuntu systems all dependencies can be installed with:
sudo apt-get install -y texlive-xetex texlive-bibtex-extra biber
A custom Makefile exists in the root directory, and it does not require any build system like autotools or CMake. Simply type:
make
The Commander X16 User's Guide is written in LaTeX, a document typesetting
language often used in academic settings. It is not necessary that you know
or understand LaTeX in order to contribute to this User's Guide. The
maintainer's are more than happy to accept unformatted content and then apply
the proper LaTeX formatting later. Simply find the file you wish to edit, make
the changes and additions you feel are necessary, and then submit a pull
request. For example, if you wish to add a simple type-in program to the
chapter on graphics, you would locate the graphics.tex file in the source
code, write your example program and explanations in plaintext in your text
editor of choice, and then submit a pull request in the usual fashion. The
maintainer(s) will then either accept and merge your PR (creating a GitHub
issue for applying formatting as they do so), or apply the formatting directly
in your branch before merging. Of course, properly formatted contributions
will also be appreciated, but it is important to point out that it is not
required.
For those who wish to contribute formatted LaTeX code, there already exist several conventions to make it easier. For both LaTeX and Markdown files, a standard of two spaces between sentences should be used. This makes it easy to delimit sentences for editing purposes.
When you need to display a key to the reader, you can use one of the predefined
key formats. Keys can be used anywhere text is used, including type in boxes,
bubble boxes, tips, notes, and in the middle of sentances. Before using one of
the key commands, it's best to set the color using \keybackgroundcolor and
\keytextcolor.
For regular keys on the keyboard, such as letters, it's best to use the key command:
\keybackgroundcolor{white}
\keytextcolor{black}
\key{p} \key{r} \key{i} \key{n} \key{t}\\
This will print a representation of the keys:
For keys that are wider than most keys, you can use the \widekey command.
Also note that you should try to match the color of the official keyboard
(https://www.wasdkeyboards.com/commander16-by-the-8-bit-guy.html):
\keybackgroundcolor{gray}
\keytextcolor{black}
\widekey{shift}
For keys where it's important to display both the shifted and unshifted values,
use the \doublekey command, making sure to include a \\ for a line break
between the top and bottom:
\doublekey{"\\'}
Some keys are use so often, that it's more convenient just to define custom commands for them, including setting the correct text and background colors. In addition to using one of the key types, the following predefined key commands are available:
\clrhomekey\shiftkey\altkey\ctrlkey\returnkey\backspacekey\spacebar\runstopkey
The type in example at the beginning of each chapter is such a common feature
that the entire page can be produced using a predefined LaTeX command called
\chaptertypein. Here is an example of how this is used in the introductory
chapter:
\chaptertypein{
\keybackgroundcolor{gray}
\keytextcolor{black}
1 PRINT "X16" \widekey{return}\\\\
2 GOTO 1 \widekey{return}\\
}
This produces an entire chapter type-in page as shown here:
Often you will want to annotate these examples with helper bubbles. For details see the the section on Bubbles below.
There is also a \largechaptertypein command for larger screens that can
display longer type-in programs.
Sometimes you would like to display a mock-X16 screen, but not at the beginning
of a chapter as a type-in example. For that purpose, there is a much more
re-usable command \screenbox. To use this command, specify a width, height,
and content:
\screenbox{2.75in}{2in}{
**** X16 BASIC ****\\
512k HIGH RAM\\
38655 BASIC BYTES FREE\\\\
READY.\\
\cursor
}
When screens, type in examples, or diagrams need annotating, there are several
sizes of text bubbles that are predefined; \bubble, \smallbubble, and
\tinybubble. Each one also includes a single arrow that can be pointed
anywhere on the page. These bubbles are intended to be used inside of a
tikzpicture block. For example, to annotate the chapter type in example
above:
\chaptertypein{
\keybackgroundcolor{gray}
\keytextcolor{black}
1 PRINT "X16" \widekey{return}\\\\
2 GOTO 1 \widekey{return}\\
}
\begin{tikzpicture}
\hyphenpenalty=10000
\bubble{2.5in}{2.5in}{4.8}{6.3}{
This line tells the X16 to print what's between the quotation marks.}
\bubble{2.5in}{1.75in}{4.0}{5.2}{
This line tells the X16 to go back to Line 1 and print it again.}
\bubble{2.5in}{1.1in}{6.0}{2.0}{
Typing the word RUN makes the program run.}
\end{tikzpicture}
Which produces:
The first two arguments of a bubble are the bubble's (X,Y) coordinates from the
lower left of the tikzpicture block, given in whatever units you choose. The
second two arguments are the (X,Y) coordinates of where the arrow is drawn to,
from the lower left corner of the tikzpicture block, unfortunately specified
custom tikzpicture unit (see tikzpicture's documentation for details, but
it's easy enough to figure out).
Sometimes it is nice to have a note in the middle of the chapter for
clarification, but it often needs to be lengthier than a simple footnote at the
bottom of a page. For this purpose, there is a predefined \note command that
creates a note box:
\note{
If you are not using an official Commander X16 keyboard, then you probably
won't have a \widekey{return} key, but instead have an \widekey{enter} key.
Don't worry, they are the same thing.
}
Tip boxes are useful when the information is not strictly necessary, but that a user might find helpful. Tips are very similar to notes, except that you can specify a title for the tip to help the user scan the page and find it later if need be:
\tip{Clearing The Screen}{
Clearing the screen will be one of the most frequent things you do
while working on your Commander X16. It is worth memorizing the
\widekey{shift} \doublekey{CLR\\HOME} key combination so that you don't
have to reference this manual every time you want to start with a fresh
screen.\\
You can also clear the screen by typing the {\ttfamily CLS} command and
pressing \widekey{return}, but most people prefer to use \widekey{shift}
\doublekey{CLR\\HOME}.
}
Sometimes you may want to encourage the reader to try something out for
themselves. The \tryit command will create a box with a "Try It Yourself!"
header that you can fill with whatever you would like the reader to try:
\tryit{
Type in the above program and see if you can figure out what number needs
to be entered in order to exit the program!
}
Often you will want to display code examples as either short snippets or full
type-in programs. For both these purposes, a standard \codeblock command has
been defined:
\codeblock{
10 PRINT " X16";\\
20 GOTO 10\\
}
This is simply a convenience method for printing text in a fixed-width font, but it should always be used for code examples in case additional styling is added in the future.