Introduction

Greetings!

If you are reading this then you are either an insomniac like me, or you have a mild interest in maybe helping to update the SuperBASIC Online Manual.

Now, you might think that it will be difficult to do so, given all that fancy HTML and the like, but nothing could be further from the truth. The manual is written in a special form of plain text and converted to the glorious format that you see online, and indeed, can download for your own offline enjoyment.

The special format is known as ReStructuredText (yes, all one word!) and is pretty simple to use and understand, for the most part. And, as I’ve deliberately avoided using the more complex or esoteric features of ReStructuredText in the original files, you don’t have to worry about them!

How Can I Help?

There are a few different ways that you can help:

Just Email!

The easiest “fix” is to get someone else to do it for you! Just send an email, let’s say via the QL Users list where whatever is “wrong” can be discussed prior to fixing, if anything needs fixing. Obviously, you should provide as much detail as possible about:

  • What you think is wrong;

  • Where you think it is wrong;

  • What you think it should be;

  • Why you think this.

Log Bugs

Bugs can be logged against the source repository on GitHub using the issues tracker. As the owner of the repository, I will be informed and will be able to do something to fix them. For the sake of argument, a bug in this context is anything “wrong” with the Manual as it is. You could include:

  • Spelling errors;

  • Bad grammar;

  • Stuff that is downright incorrect;

  • Updates for new software which changes or adds to the existing commands;

  • New commands in the documented toolkits and/or emulators;

  • And so on.

Fix Bugs

You can, if you wish, fix any bugs - but check the issues log first to be sure that they have not been reported and maybe are in progress. Just in case.

How to fix a big? See below for details, but fork my repository, edit the files as appropriate and commit them to your own fork then issue a “Pull Request” to me to merge your fixes into the main repository.

Log Bugs on GitHub

The steps to log a bug are simple:

On the screen that appears:

Image showing how to log an issue in GitHub.
  • Fill in a descriptive title.

  • Fill in a good description of the problem as you see it. If possible, suggest fixes, changes etc. Give examples, if possible. Markdown formatting is allowed in the description - if you know how to use it, that is.

  • Over on the right, there’s a “gear wheel” icon next to “Labels”. Click it and select a category. Bug, Enhancement or Question are good ones. Click as many as you feel necessary and click the gear wheel again.

  • Go to the “Preview” tab and check it all looks right. Go back to the “Write” tab and make fixes if necessary.

  • Click “Submit new issue”.

Fix Bugs Yourself

If you have the desire to fix things, the process is quite simple too but it does require the use of a Windows, Mac or Linux computer - unless you are attempting to edit files actually in the browser - and the installation of the Git software.

  • Fork The SuperBASIC GitHub Repository. You will need a GitHub account for this, but it’s free, there’s no spam and you can have as many or as few repositories as you like.

  • Once forked, you can clone it to your computer, or edit things online, but to be honest, do it locally as it’s better that way.

  • Commit your changes.

  • Push your changes back to your repository on GitHub.

  • Raise a “pull request” to me, to examine and merge your changes into the main repository.

  • You can, if you wish, delete your fork of the repository, or keep it for later.

The steps above are covered in their own section later on in this “book”.

In order to actually do your own fixes, or adding new details to the manual, you will need some software, and sadly, our beloved QL and the various emulator children it has begat, are of no use I’m afraid. We need Linux, Windows and perhaps a Mac.