Guest post from Wayne on the MEGA65 User Guide Layout

Today we have another guest post, this time from Wayne, who is another of our documentation angels along with Edilbert.  Today, Wayne talks about some of the challenges to be able to produce a User Guide that visually is reminiscent of the C64 Programmer's Reference Guide / User Guide.  Over to Wayne...

One of the most remembered items that shipped with every Commodore 64 was the User Guide. This important book was the gateway for many of us to understanding the internals of the computer and how to program. We want to offer that same experience with the MEGA65. While there is always the option of simply creating online content and tutorials, nothing beats the experience of opening up your User Guide and working through learning your brand new computer.

As you can tell from the screenshots, we're trying to retain the spirit and style of the original Commodore 64 manual. Of course, all content, every word and illustration must be recreated entirely from scratch.

When the team first started on this sub project, the first ticket item was to create components and layouts that would provide a base for other content.

In terms of layout, Paul provided draft templates and styles. The next step was to come up with suitable and flexible components.

This was my trial of fire, my first time working with LaTeX. So I started work on the "Keys" component. For those that remember, when the C64 manual indicated a keypress, it would show something like:

This took a little time to work out, but eventually using the tcolorbox package I got it done. With this new confidence I started on the "Screen Output" component, used to show screen display output from the MEGA65 and for screen program listings.

I sank something like 20 hours into this. LaTeX is a fickle mistress. Much time was spent fighting with various packages and syntax. Thankfully with much help and advice from Edilbert and Paul, it got done.

Next component to tackle was the sprite grid component. I knew the guide would need one, and rather than put it off, it was best just to get started on it.

This resulted in around 40 hours of hard slog and frustration. I broke many typesetting rules to make it look close to the original sprite grid illustration that people would remember. Now we have both monochrome and multi-colour sprite grids at our disposal.

At the same time while all this was going on, Edilbert started chipping away at the BASIC 10 keywords chapter. The huge benefit of his work was that, once complete, programming chapters could be built (having documented the full BASIC 10 keyword set).

At this point I was getting pretty discouraged with LaTeX as a whole and figured we'd never get done until 2022. But the team agreed we should stick with it. A good job too because from here on in, the work became easier.

Chapters starting being produced more quickly because the available base elements like titles, sections, subsections, screen output listings, tables and so forth meant that writers could concentrate on the written content. So that was very encouraging.

Work has been progressing steadily on the User Guide. Recent completed sections include:

 - Setting up the MEGA65
 - Keyboard and the Screen Editor
 - ASCII Codes and Special Escape Sequences
 - Working with Decimal, Binary and Hexadecimal

As Edilbert showed in the last blog post, he has finally finished the completed set of BASIC 10 keywords. This means the development of Sprite and Sound chapters (and other programming chapters) will follow soon.

This has been a great sub-project to be involved with within the MEGA65 development team. We can always use more writers, or proof readers and people willing to work through the chapters looking for issues. Instructions for how to get involved, how to download the repo and set up the required LaTeX software is found at: https://github.com/MEGA65/mega65-user-guide