log in | register | forums
The Icon Bar is the longest running RISC OS portal. The sensibilities that Acorn instilled in us still influence our interests and writing.

Buy swag
Got news?
Let us know!
Bob and Trev: Resurrection
Bob and Trev: Resurrection
A dystopian Acron roguelike written in 7 days and 32K
Subscriptions RSS Feeds
RSS 2.0 | 1.0 | 0.9
Atom 0.3
Misc RDF | CDF
View on Mastodon
Subscribe | iTunes | List
Latest MP3
Site Search
Article archives

RISC OS Documentation

Posted by Charles Justin Ferguson on 09:00, 9/8/2021 |

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 1 produced by RISCOS LtdInfo, which were more accessible, but had their own problems 2.
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).
That's the current state of the documentation - it hasn't really changed in the last 15 years, as far as I can see.

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.

Continue reading "RISC OS Documentation" | 18 comments in the forums

Testing on RISC OS

Posted by Charles Justin Ferguson on 09:00, 28/5/2021 | ,


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.

Continue reading "Testing on RISC OS" | Comment in the forums

The state of PackMan in 2018

Posted by Jeffrey Lee on 21:30, 20/8/2018 | , , , , ,
In a previous article we've looked at what software is available via !PackMan. But what if you're a developer who wants to get your software listed - where do you start?
Continue reading "The state of PackMan in 2018" | Comment in the forums

A fresh look at the Desktop Development Environment Manuals

Posted by Mark Stephens on 10:28, 1/2/2017 | , , ,
TheDesktop Development Environment manual is the essential documentation to make the most of the Desktop Development Environment. Both have been adopted and are now updated by RISC OS Open. The manuals come free with the DDE and are also available to buy in printed manual form.
The first edition of the manuals was produced in 1994 and it has been revised several times. As you would expect from professional developers, RISC OS Open includes a changelog so you can see what exact changes have been made. Last major update was in 2015. The manuals have also been rebranded with the RISC OS Open cog logo and company name.
There are 3 manuals in the set.
The Desktop Tools manual (329 pages) covers all the tools in the DDE (Make, Squeeze, SrcEdit, ABC, etc). There is a nice introductory section at the start telling you how to setup and start using the tools.
There are lots of screenshots to show the features in action. It should not be regarded as a tutorial but there is lots of material on using them. The Desktop Debugging tool includes 60 pages explaining how to use it.
The last 100 pages are Appendices which cover a summary of changes added over the years and information which you would need to use the tools (Library file formats, alignment details, file syntax,etc).
The Acorn Assembler manual (159 pages) shows you how to use ObjAsm. It includes some details on ARM Assembler instructions but it is not a tutorial (it does include some good further reading suggestions for you to learn ARM code). The focus is on using the tool and its features (ie labels, macros compilation). There are also some short chapters on writing RISC OS modules and interacting with C.
The Acorn C/C++ manual (438 pages) provides provides detailed coverage of the C and C++ language features supported by the Compiler (as well as the libraries) and some useful details and tips on writing RISC OS applications from C or C++. The languages are cleanly separated out so you only want to write C, it is easy to skip the non-relevent items. Again it is not a tutorial on coding, but a detailed summary of all the details you need to develop code.
All three manuals include an index at the back to help you to navigate as well as very detailed section descriptions at the start and a clear structure.
All three books are part of the DDE or available in a printed version (discounts for registered developers). The printed package makes a fairly bulky doorstop (and a great table stand for my MacBookPro!). I also find that it is the sort of programming content which I like to read and reread offscreen.
Further details on the DeskTop Tools Manual can be purchased from RISC OS Open website or they usually have some copies as Show events. Maybe something to check out at the South West Show later this month.
If you are looking to write software, you should also consider the Style Guide which tells you how the software should look and act to fit into RISC OS nicely.
Comment in the forums

Getting FAT32FS working on a RiscPC with a Castle USB Card

Posted by Jon Robinson on 14:57, 28/6/2014 | , , , ,
I have a RISC OS 4.39 RiscPC with a CastleInfo USB card and Compact Flash card reader attached. This uses Castle‘s !SoftSCSI to access the flash cards.
For a long time, I have been frustrated by its inability to mount any flash card larger then 2 GB in size. I really wanted to use a single flash card, to back up my 40 GB hard drive, as having to use a pocket full of 2 GB cards is a real pain.
I had been put off experimenting with Jeff Doggett‘s FAT32FS before, because I had read somewhere that it only works with the USB stack on the Iyo.
But, as it‘s the only solution, I did have a go at trying to get FAT32FS working on my RiscPC, recently. And, luckily, it turns out that the USB podule card on the RiscPC, is sufficiently similar to the one in the Iyonix, that it does, in fact, work.
It did take a bit of experimentation, however, to work out how to do it.
Continue reading "Getting FAT32FS working on a RiscPC with a Castle USB Card" | Comment in the forums

The Icon Bar needs YOU

Posted by Jeffrey Lee on 22:40, 24/4/2014 | ,
  • 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?
If you answered YES to all of the above, then good news! We're looking for new writing staff to supplement the current lot, most of whom left the RISC OS scene behind a long time ago, or are far too busy with other things to update the site on a regular schedule.
At The Icon Bar we're primarily interested in delivering original content in the form of news, articles and reviews, rather than just regurgitating press releases all the time. So if that fits your bill then feel free to get in touch, either via the contact form or by posting in the thread below. And if you're lucky, we'll get back to you before you die of old age!
3 comments in the forums

What is the point of RISCOS Ltd?

Posted by Jeffrey Lee on 19:00, 7/11/2009 | , , , , , , , ,
What is the point of RISCOS Ltd?After hearing the news that videos from the recent RISC OS London Show are now available online, I decided to take a look at what RISCOS Ltd had to say in their presentation. The results I found to be quite shocking...
Disclaimer: Although I've obviously been doing a lot of work for RISC OS Open recently, I am not a member of ROOL, nor am I speaking on behalf of ROOL (or The Icon Bar). The opinions expressed below are mine and mine alone, and any likeness or resemblence to any other person's opinions is entirely coincidental.
Continue reading "What is the point of RISCOS Ltd?" | 197 comments in the forums

Bob and Trev: Resurrection: Just in time

Posted by Jeffrey Lee on 00:15, 17/3/2007 | , , , , , , , ,
498 bytes free memoryPreviously, on Bob and Trev: Resurrection...
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.
...and here it is.
Continue reading "Bob and Trev: Resurrection: Just in time" | 19 comments in the forums

Monster AI

Read article... | Comment in the forums


Read article... | 7 comments in the forums

Visibility and pathfinding

Read article... | Comment in the forums

The level generator

Read article... | 3 comments in the forums

Static game data

Read article... | Comment in the forums

How to fit a roguelike in 32k

Read article... | 10 comments in the forums
Recent discussions
- PinBoard 2.05 released (News:2)
- Rougol Talk July 2024 - Nathan Atkinson (News:2)
- Rougol August 2024 meeting on monday (News:)
- Rougol July 2024 meeting on monday (News:2)
- Sunday coding session with Gerph on Sunday (News:1)
- Livestream coding session with Gerph this sunday (News:2)
- WROCC July 2024 meeting - Draw/ROD double bill (News:)
- WROCC July 2024 meeting on... Hughes and Peter Richmond (News:)
- July developer 'fireside' chat is on saturday night (News:)
- June 2024 News Summary (News:)
- Free ads
- Web hosting
Sites we like
- Ars Technica
- Ganymede & Titan
- pagetable.com
- Daring Fireball
- Kotaku