Writing the Tiny BASIC Manual
Wednesday, 21st August 2019
Lots of people have documented Tiny BASIC already, and in various forms. But if I eventually want to publish my own version, I want it to have its own documentation rather than referring from others. Two good reasons for reinventing this wheel stand out among others.
Firstly, my own implementation has its own additional features. Comments, not present in the original Tiny BASIC specification, don't need much documenting. But the features surrounding omitted line numbers probably warrant some explanation.
Secondly, my implementation will have its own command line parameters that will need documenting. If I'm going to document these, I may as well do a proper job and document the handful of commands in the language.
But How?
That leaves the question of what form the manual should take. The language isn't big enough to warrant a book. Most previous documentation for it took the form of magazine articles, or a single web page. I decided that a Unix-style "man page" is probably a good fit for the type of information I need to present.
Man pages are the normal way of documenting Unix packages; the first thing a Unix user would probably think of is typing "man tinybasic" at the command line for information. But man pages can also be exported: you can make PDFs, HTML pages and plain text files out of them. So a man page would be a good starting point for the documentation.
But How?
One slight obstacle to me creating a man page: I'd not done one before. I was surprised to find that in my projects of two decades ago I'd created "info" documentation but no man pages. So I had to learn how to create and format a man page: not just the technical aspects, but the writing conventions too.
Luckily a couple of good links got me started: Writing Man Pages and Writing man Pages Using groff gave me most of the information I needed. Some technical formatting questions were resolved by trial and error, and by looking at the gawk manual page source.
The result is available for you to look at, if you're interested. I've uploaded the first draft of the Tiny BASIC Manual in PDF format to download or to view in your browser.