What have we got?

RISC OS is documented in many different places these days.
 
Originally it was documented through the Programmers Reference Manuals ('PRMs'), a physical set of manuals in multiple volumes for each of the major areas. Over the years these have been augmented by updates in the form of volume 5/5a, application notes, specifications for some of the 'new' components that were never integrated into centralised documentation, and information that was noted by people and submitted to the StrongHelp manuals.
 
The PRMs were released as part of the 'Techie CD', which had a hypertext application which could be browsed on RISC OS. The content was the same as the physical books, with the same page numbers. Later, there were PDFs and HTML versions ¹ produced by RISCOS Ltd, which were more accessible, but had their own problems ².
 
The application notes and various specifications came out of Acorn which included some detailed documentation which covered usage notes and APIs for 'newer' features. These 'newer' features include such things as the URI/URL fetcher stack, nested window manager, redraw manager, and miscellaneous updates that followed on.
 
The StrongHelp manuals for SWIs and the like were originally written by Guttorm Vik, and maintained by myself for a few years, before being passed on to other people - they were never official. However, they included many of the fixes and notes about oddities within the PRM and the different implementations within various RISC OS versions. The StrongHelp manuals were the primary place for developers to refer to APIs whilst writing code, with reference to the PRMs when more detail was required. The main 'SWIs' StrongHelp manual contains links to the pages of the original form of the PRMs to aid in this process of escalating gathering information.
 
There is also a Wiki on the RISC OS Open site, which is very similar to the StrongHelp documentation in its detail and degree of authority.
 
So we have...

• Original PRMs, in printed, Techie CD, PDF and HTML forms.
• Random specifications produced officially and unofficially.
• Random user-sourced cheat-sheet documentation like StrongHelp (and later the RISC OS Open Wiki).

What did I want?

Back when I was doing RISC OS work in the dim past, after the RISCOS Ltd days, I felt that this situation was not ideal and needed to be addressed. So I tried to work out what the goal was, and what was problematic.
 
The goal...

• Produce documentation that's viewable on RISC OS and other systems.
• Manage the source as a living document that can be editable by developers, on RISC OS (or other) systems.
• A documentation system that was easy to work with, so that people without experience could produce documentation.

Introduction

It's my belief that when writing RISC OS software, people don't consider writing code that is testable (ie abstracting it to modules that have discrete testable elements)... which means that their code is mixed into the logic of the harness that it lives within (whether that be command line, RISC OS module, desktop tool or whatever), and thus means that they argue that it's not possible to do testing easily.
 
The argument that they cannot easily test desktop applications is reasonable - but only to that point. Testing an application in the desktop is a form of system testing, and requires you to actually be able to automate those operations that a user might perform. There are tools for RISC OS, like KeyStroke, which allow system testing, and of course others could be written. But it's not commonly done. Doing system testing, though, is a later state of automated testing, usually preceded by Unit testing and Integration testing.
 
Similarly, it is a fact that testing modules which execute in SVC mode can be difficult. If something goes wrong, the machine may just die. This is also a system test - the product is being tested as a whole.
 
Unit testing exercises the smallest units of the code. Integration testing brings those units together to test them in combination. Then system testing puts the whole together and tests the product's functionality. Usually there's system integration testing above that, where you're testing not just the product, but the product's interactions with the systems that it will actually be used in - the desktop, possibly in conjunction with real hardware.
 
Knowing what these are, how does this help with testing a module or desktop application? Well, all applications consist of interaction points where the user (who in the case of a module, might be another program) does something, and the application or module acts on it. In general these points are wired to the Wimp_Poll loop, or module entry points (SWIs, services, commands). Well structured applications and modules will have the work within those Poll entry and module entry points set up to just call internal functions. Those internal functions do the actual work, so it's easy to see how you might split off the code to test those internal functions.
 

• Are you tired of looking at the front page and seeing those same old articles from over a year ago?
• Have you noticed we haven't done anything new for April Fools day for several years?
• Have you noticed how most of our show announcements are dangerously close to being made too late?
• Do you have a keen interest in RISC OS?
• Are you capable of forming basic sentences?
• Do you enjoy working long hours for no pay and little reward?

Game over, man
 
The competition is nearly at an end, which can only mean one thing - tomorrow's article will be the conclusion, and will (hopefully!) feature a copy of the game to download.