Just a few gaps in the documentation

Since I often find myself wondering where to try and insert new pages into the old RISC OS 3 PRM hierarchy that the docs on the wiki are roughly based around, I thought it would be worthwhile to try and come up with a new structure. This isn’t replacing the old structure (or at least, not yet) – it’s just augmenting it, with an index of all the modules that are included in ROM images.

For this new structure I’m trying to keep things simple, so that list of modules is expecting the page name to be the same as the module name. That way people can (hopefully) find what they’re looking for just by typing in the URL manually or into the search box, like with any other wiki. But it does mean that most of the existing documentation isn’t showing up, e.g. the WindowManager page in the existing docs is actually called The Window Manager.

Overall I’m thinking about the new module pages having the following layout:

• The “Introduction” page for each module will be moved to the main page for that module. This will make general information about the module quicker to find, and might help to strike a balance between user documentation and programmer documentation. In-depth discussion of features, use, etc. will still be kept to sub-pages.
• The main page will have breadcrumbs leading back to the main PRM index and the module list
• Sub-pages will only have breadcrumbs leading back as far as the main module page. That way if/when we eventually have everything documented the main PRM page won’t have thousands of other pages listed in the “linked from” section. It’ll also make things a bit easier if we decide to restructure things in future, as we’ll only have to update the breadcrumbs in the module main pages instead of throughout all the sub-pages.
• The old PRM structure will gradually be removed. Only bits which don’t fit within specific modules (e.g. the filesystem writing guide, or the introduction section) will need to be kept around. So basically, no more obtuse wiki page names like Part 8
• Where necessary we should probably start using disambiguation pages. e.g. “ARM” may end up needing to be renamed to “ARM (Module)”, with a disambiguation page at “ARM” to differentiate between the company and the module.

Any comments on the above? And any volunteers for moving/updating pages or writing new ones are very welcome!

This is an excellent idea. I agree with the objective, and would be happy to help out.

Only bits which don’t fit within specific modules (e.g. the filesystem writing guide, or the introduction section) will need to be kept around.

This is the tricky bit, I guess. Most modules are fairly self-contained, and can be documented discretely. Other topics, like writing a filesystem or using the RISC OS sound system need broader guides that reference more than one module.

Perhaps one suggestion would be to divide your module page into two sections: 1. a simple list of modules as you propose, with each link leading to a complete reference for that module, including an introduction, SWI calls, etc., and 2. a list of Guides, along the lines of the extended chapters of the PRM or the old Application Notes, covering more wide-ranging topics. These wouldn’t provide details of SWI calls (to avoid duplication), but would be more discursive reference documents with worked examples, etc.

Presumably, once a format and style have been agreed for these, there’s no reason, in due course, why we can’t integrate the Individual Specifications and the HAL documents into a more rational structure.

e.g. the WindowManager page in the existing docs is actually called The Window Manager.

Can’t the wiki redirect?

As Chris mentions, there are concepts that span modules – USB requires information on DeviceFS, using graphics and fonts, and as Chris suggests, writing filing systems.
OS_Word, Vectors, and Service Calls likewise.
Describing all the modules is a good idea, but there is so much more besides.

Perhaps one suggestion would be to divide your module page into two sections:

Why would a “list of modules” page also contain a list of guides? Surely we should have a “list of guides” page as well? Or just list them all on the main PRM index page, depending on how many we end up with.

We’ve also got pages listing service calls, SWI calls, * commands, etc.

e.g. the WindowManager page in the existing docs is actually called The Window Manager.

Can’t the wiki redirect?

Yes, but it still needs someone to go in and set up the redirections.

Describing all the modules is a good idea, but there is so much more besides.

Modules are a convenient low-hanging fruit for the documentation project to get started on. They’re also the cornerstone to any high-level guide topics – how can you write a guide on how to write a filesystem if you don’t have any accurate/up-to-date documentation on FileSwitch or FileCore? If you base your guide around the information in the RISC OS 3 PRMs you might find that you’re recommending people to use APIs which are woefully out of date.

Of course if you’re offering to write some guides and add them to the wiki then I’m not going to stop you!

I’ve migrated the FilterManager docs to the new format. Let me know your thoughts!

Why would a “list of modules” page also contain a list of guides? Surely we should have a “list of guides” page as well? Or just list them all on the main PRM index page, depending on how many we end up with.

Ah, I think I misunderstood slightly. Yes, I think having the main PRM page re-jigged a bit (in due course) would be helpful, and the List of Modules page just sticking to what you propose. Is there any point in categorising the (long) list a bit? Or more trouble than it’s worth?

FilterManager format looks good to me. If others are happy, and time allows, I’ll see if I can update a few more.

I added a breadcrumb link back to the PRMs at the top, like the other ‘List of’ pages. OK?

It’s a bit odd that the wiki pages list every other linked page at the bottom – the Window Manager list is immense!

Had a go at updating the Pinboard module. Have I understood the scheme correctly?

I’ve migrated the FilterManager docs to the new format. Let me know your thoughts!

A pre-filter is so-called because it is assigned to be called before a task calls Wimp_Poll. With a pre-filter, the event mask the task passes to Wimp_Poll can also be changed.

Should that assigned be designed in both the pre- and post-filter elements?

Why would a “list of modules” page also contain a list of guides? Surely we should have a “list of guides” page as well? Or just list them all on the main PRM index page, depending on how many we end up with.

Ah, I think I misunderstood slightly. Yes, I think having the main PRM page re-jigged a bit (in due course) would be helpful, and the List of Modules page just sticking to what you propose. Is there any point in categorising the (long) list a bit? Or more trouble than it’s worth?

Breaking up the list into a few different categories might be useful, I guess.

I added a breadcrumb link back to the PRMs at the top, like the other ‘List of’ pages. OK?

Yep, that’s fine.

Had a go at updating the Pinboard module. Have I understood the scheme correctly?

Looks good to me.

One thing I didn’t mention about the FilterManager changes was that I only bothered to rename the main FilterManager page – all the sub pages (SWI list, etc.) still use the old page names (i.e. “The Filter Manager SWI Calls”). I’m not yet sure if that’s a good thing or not – I guess we can always rename them later if we think shorter/more consistent page names are better.

I’ve migrated the FilterManager docs to the new format. Let me know your thoughts!

A pre-filter is so-called because it is assigned to be called before a task calls Wimp_Poll. With a pre-filter, the event mask the task passes to Wimp_Poll can also be changed.

Should that assigned be designed in both the pre- and post-filter elements?

Kinda. I’ve now rewritten it so that it should be clearer. Note that that text was copied from the original FilterManager introduction page – most of the errors aren’t mine ;)

Note that that text was copied from the original FilterManager introduction page – most of the errors aren’t mine ;)

Weird timing – I was saying just today “learning from your mistakes is good, learning from other peoples mistakes as well is even better” (A.P. sometime in the late ’60s – early ’70s)

As you said earlier this is about improving on what went before (I paraphrase)

I was saying just today “learning from your mistakes is good, learning from other peoples mistakes as well is even better” (A.P. sometime in the late ’60s – early ’70s)

I think Alan Partridge will still have been at school then:-)

Google finds the quote frequently, but no attribution!

Google finds the quote frequently, but no attribution!

My father¹ simply gave the advice, I listened.

¹ A.P 1932-1998

One thing I didn’t mention about the FilterManager changes was that I only bothered to rename the main FilterManager page – all the sub pages (SWI list, etc.) still use the old page names (i.e. “The Filter Manager SWI Calls”). I’m not yet sure if that’s a good thing or not – I guess we can always rename them later if we think shorter/more consistent page names are better.

I think it might be better to update the subpages, just for consistency. Looks a bit odd for the head page to use the module title and the subpages to be more verbose.

I’ve updated TaskWindow, ShellCLI and VFPSupport. Thought I’d work through the currently linked documents on the module list before going back for those that don’t yet link from the page.

Thought I’d work through the currently linked documents on the module list before going back for those that don’t yet link from the page.

Yikes, I’ve seen the result!
Man on a mission or what?

I think it might be better to update the subpages, just for consistency. Looks a bit odd for the head page to use the module title and the subpages to be more verbose.

Yeah, you’re right. I was just trying to be lazy :) I’ve now renamed the FilterManager sub-pages.

I’ve updated TaskWindow, ShellCLI and VFPSupport. Thought I’d work through the currently linked documents on the module list before going back for those that don’t yet link from the page.

And a few others it looks like. Nice work!

I’ll start working down from the top, and then I guess we’ll meet in the middle somewhere.

I’ll start working down from the top, and then I guess we’ll meet in the middle somewhere.

Cool.

Is Alan Robertson still active on the docs? He did sterling work adding content for things like the Window Manager, etc., and it would be good to get his feedback. I’ve not really edited his pages very much at all, except to bring them into line with the new structure.

Most of the time the ‘Overview’ page can be merged into the Introduction or Title page for the module, and I’ve done this with the modules I’ve looked at. That’s resulted in a few orphaned ‘Overview’ pages. Can these be deleted? I’m not sure how to delete pages, or whether it’s better just to let them sit around.

Also, when editing, I seem to get locked out quite a lot. Is this a glitch with the wiki, or something stupid I’m doing?

Is Alan Robertson still active on the docs?

I haven’t seem him around for a while, I’m afraid :(

Most of the time the ‘Overview’ page can be merged into the Introduction or Title page for the module, and I’ve done this with the modules I’ve looked at. That’s resulted in a few orphaned ‘Overview’ pages. Can these be deleted? I’m not sure how to delete pages, or whether it’s better just to let them sit around.

I think the only way we have of deleting a page is to use the ‘rename page’ option, but all that really does is move it elsewhere (and inserts a [[!redirects …]] tag in the new page to set up a redirect from the old one). I’ve tried manually inserting a [[!redirects tag into an existing page to see if I can get rid of an obsolete page elsewhere, but that didn’t seem to work. So I’ve just been leaving a short note in any orphaned pages pointing people towards the new location, like this

Also, when editing, I seem to get locked out quite a lot. Is this a glitch with the wiki, or something stupid I’m doing?

Just a glitch I’d assume – although everything’s been working fine for me.

Looks like we’ve met in the middle (very glad you took on FileSwitch!). Some of the remaining pages are in a slightly different format (MUSBDriver, etc.), but as these are documents in progress I thought it best to leave them alone. I’ll make a start on adding some more modules from the main PRM page, working from the top.

I think the formatting and consistency of the pages is very good – Alan’s done an excellent job. I’ve occasionally standardised the section/table headings to h4, in preference to h5 or h2, just to make things simpler. The only exceptions are the headings for SWI Calls, *Commands, etc., which have remained as they are.

I’ve started work on migrating the WindowManager docs, so don’t be surprised if they’re in a bit of a state of flux over the next few days.

I just started updating the ‘ATAPI’ entry from the SWIs list, before realising there’s no such module listed on my system. Is the SWI call ATAPI_GetDrives supplied by the CDFSSoftATAPI module? Is there any documentation for this anywhere?

Is the SWI call ATAPI_GetDrives supplied by the CDFSSoftATAPI module? Is there any documentation for this anywhere?

Yes the SWI is from CDFSSoftATAPI. BTW. Info below pulled from RPC using Verma (it also appears in RPCEmu with the current IOMD ROM)

Module info
===
Generated by : !Verma 0.27 (03 Dec 2008)
Generated on : Wed 04 Dec 2013. 10:46 AM

Title : CDFSSoftATAPI
Help : CDFSSoftATAPI 1.50 (17 Jun 1999) © 1995-99 J W Ballance/Castle
Technology

Flags :
Don’t free module’s code area after module is quit.
32-bit ready : (No)

Services :
Has RISC OS 4 style fast service handler.
&42680

SWIs :
&4A740 ATAPI_GetDrives

No Commands or Keywords provided by this module.

Ta – I’ll update.

(Always nicer when module names and SWI prefixes are the same, though.)

(Always nicer when module names and SWI prefixes are the same, though.)

Cuff round ear for John B? :-)

BTW. ADFS modules on OMAP boards are a bit rare too. Noticed that when I was playing with the 32 bit hack of !Blackhole and transferred from RPCEmu to beagle. So you probably need both old and new to check through the documentation.

Just sitting chilling and avoiding doing anything work related¹. This counts as peripheral so tomorrow is a pub tour (and some Xmas shopping) using local transport so the end result could be blurry.

¹ First non-work period since August, they have no network support until next week.

(Always nicer when module names and SWI prefixes are the same, though.)

Another one to watch out for is SpriteExtend, which as well as providing a bunch of extra OS_SpriteOp reason codes it also provides the JPEG_* SWIs.

FileSwitch is another annoying one, as all the SWIs it provides have the OS prefix, and in some cases it’s only a couple of reason codes which it provides (at least according to the wiki – I haven’t checked any official docs yet). But I think that for consistency all OS SWIs should have their breadcrumbs leading back to a main listing of the OS SWIs, rather than leading back to the module which implements them.

BTW. ADFS modules on OMAP boards are a bit rare too.

Where “A bit rare” = non-existent :) ADFS is used for talking to IDE controllers and floppy controllers (and ST-506 controllers back in the day). Since OMAP boards have none of those interfaces there’s no point including the module in the ROM.

BTW. ADFS modules on OMAP boards are a bit rare too.

Where “A bit rare” = non-existent :) ADFS is used for talking to IDE controllers and floppy controllers (and ST-506 controllers back in the day). Since OMAP boards have none of those interfaces there’s no point including the module in the ROM.

Indeed, it does however hightlight the habit of programmers assuming that specific SWIs will always be available. In the case of the Blackhole¹ RunImage, it calls ADFS_DescribeDisc and ADFS_DiscOp, but it’s ADFS_Drives that sends things base over apex during startup as it tries to build the menu and calls SYS&43079 (I just love these mixed SWI number / SWI name items when I trying to read through and figure stuff out – not).
I suppose assuming the main file system would be ADFS and therefore always present wasn’t unreasonable, just unfortunate.

¹ Seems perfectly stable on RPCEmu, RPC and Beagle(post surgery on RunImage) provided the Singularity module is tweaked. The screensavers need a newer CompoSupport module before they work – rather fast refresh.