Just a few gaps in the documentation

I suppose assuming the main file system would be ADFS and therefore always present wasn’t unreasonable, just unfortunate.

While we all make dumb mistakes (and I’d be a liar if I tried to tell you otherwise), this is more a case of a seemingly thoughtless “works for me, guv” assumption. My main filesystem was not ADFS on the RiscPC. It was (Simtec) IDEFS. On my A3000, the harddisc was a different (Armstrong/Walker/HCCS) IDEFS. The A5000 started with a partitioned 1GB SCSI drive and moved to an unholy array of partitioned IDE drives on the Simtec podule (some of which were simply transplanted as-is into the RiscPC). Pi has SDFS and the Beagle has…whatever USB devices turn up as, SCSI or something?
I think the only device where ADFS was primary was the A3000 when it used floppy discs, and the A5000 now the Simtec card is in the RiscPC!
That isn’t to say I never had ADFS harddiscs inside, I did in every machine with built-in IDE, but they just weren’t where the action was because the I/O speed was always so lacklustre, and on the older hardware it was useless with drives >0.5GB (notice how many times I use the word “partition”).

This begs the question – why didn’t the software look to see what the configured FileSystem was, and then use that as the assumed main filesystem?

This begs the question – why didn’t the software look to see what the configured FileSystem was, and then use that as the assumed main filesystem?

Or check for all available filesystems and act appropriately?

There is one long-standing omission that it’s quite difficult to get a list of currently accessible volumes.

For example, you can enumerate modules with names FileCore%xxxx to get a list of FileCore FSes, but you then have to make guesses about which FS::n.$ are available (with care, because you don’t want to cause ‘Please insert disc’ messages).

To get a list of Fileswitch FSes, you can do FS number to name by iterating through max 255 FSes. If there are ever going to be any more, this breaks. Plus you get a list which is full of things like PipeFS which aren’t really volumes in the conventional sense. And even if you have the list of FSes, you can’t easily ask NFS or FAT32FS what mounts they have without using some FS-specific code.

So when you want to present a dropdown with ‘Please backup …’ or ‘Please format …’ it’s actually quite awkward to populate it.

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.

I’ve had a go at adding a SpriteExtend module. The JPEG_* SWIs breadcrumb back to the module page. The extra OS_SpriteOp reason codes are listed on the module’s SWI Calls page, but link back to the main OS_SpriteOp page – they’re just duplicates of what’s already there. How does it look?

As far as I can see, all the modules have now been updated to the new format, and the List of Modules page is a bit more populated. I’ve retired a few Overview pages as I’ve gone along where they’ve seemed a bit superfluous, and corrected the odd typo, but otherwise the existing text hasn’t changed much.

Some queries for continuing the work:

- Should we reformat the OS_* calls in a similar way? Perhaps have a separate page, linked to from the PRM front page, titled ‘OS Modules’ or ‘OS Calls’, with the same breadcrumb/page format as the modules.

- Should we categorise the List of Modules page? I’m a bit wary of this, since the whole idea is to avoid having a complicated ‘contents’ style page, but it does look a bit monolithic at present. I’ve separated out the Toolbox modules to show how it might look. I wondered, as a first stab, about sub-headings along the following lines:

Core (kernel, and other central functions)
Desktop (Window Manager, Filter Manager, DragAThing, etc.)
File systems (FileSwitch, FileCore, FSs, etc.)
Graphics (Fonts, Draw, ColourTrans, Printing, etc.)
Networking
Hardware Support (Hardware Drivers, USB, etc.)
Programming (BASIC, C Library, etc.)
Sound
Toolbox

Any comments?

I’ve retired a few Overview pages as I’ve gone along where they’ve seemed a bit superfluous, and corrected the odd typo,

I haven’t looked all through but I noticed a few and amended them.

Any comments?

Probably a good case for both categorised AND alphabetic listing.

All that aside I’ve always thought the descriptions of the use are a bit brief.
The problem is that there is a lot of work to do to flesh things out into full guide rather than cryptic clues and the people with enough knowledge probably ought to be doing other things.

All that aside I’ve always thought the descriptions of the use are a bit brief.

True enough. I think a lot of the content has been culled from StrongHelp pages, which are similarly terse. However, it’s surely better to have some documentation as a quick reference, especially as the PRMs aren’t likely to be updated any time soon. I think Alan’s done an excellent job with the modules he’s taken on, and Jeffrey’s provided essential docs for some of the newer developments.

I think it would be a good goal to get the OS more or less fully documented along these lines. There’s nothing to stop knowledgable users augmenting the content later, and it’s less of a job to add/edit stuff than to set up pages from scratch.

True enough. I think a lot of the content has been culled from StrongHelp pages, which are similarly terse.

Ah, I thought perhaps it was just me. I think OK as an aide-memoire but not as a tutorial probably covers it. Not a complaint, more a critique. I’m assuming people see where I going – we need to expand these things so that there is a decent set of text for newbies (and people like me who understand bits but should know more)

However, it’s surely better to have some documentation as a quick reference, especially as the PRMs aren’t likely to be updated any time soon. I think Alan’s done an excellent job with the modules he’s taken on, and Jeffrey’s provided essential docs for some of the newer developments.

Oh, definitely, but just because you and Jeffrey have spent time adding and amending doesn’t mean there is nothing else for other people to do. IYSWIM
In some cases people who can’t do anything else could check for typo’s and general sentence flow, grammar is a bit off track for most technical items but read on.
One simple technique I point out to people is to use a word processor with a grammar/spell check: just drop text in and look for what the wife refers to as red grass (spelling) and green grass (grammar)
Provided you aren’t colour blind the two stand out and if you are then the wiggly lines stand out.

Unless someone can quote a reason for an underscore followed by a space or two spaces in a row then those can be searched for. The main thing is that the formatting (embolden, and other styles) are already done so this is a proof reading and correction exercise.

Extension of the text is a future task.
Oh, and part of that future task would be adding example code in BASIC and C – like the Microsft pages, but with example code that actually works.

I think Alan’s done an excellent job with the modules he’s taken on, and Jeffrey’s provided essential docs for some of the newer developments.

Nice of you guys to say so. I really enjoyed putting it together. As you mentioned earlier, a lot of the SYS’s documentation was indeed lifted from Strong Help, as I believe a lot of it was more accurate than the PRM’s.

The main documentation (Overviews, etc) were all re-written with the PRM’s as the basis. Because Castle refuse to allow the PRM’s to be made available freely on the web site and regurgitated as a WIKI, we had no option to start from scratch. I started off with the Window Manager section because that was the area I knew most about after BASIC programming (Created a VB like way of managing windows: window.left = 200, window.top = 20, window.caption = “Example” etc..

I’ve had a look at the changes and very happy with the changes – progress is good :-)

Great! I’ve started (slowly) adding more documentation to the List of modules page, starting with the BufferManager. This is all drawn from the StrongHelp manuals. Once that’s done, I’ll link to your ‘Buffers’ document in the PRMs main section. This is probably how I see the overall manuals working – a series of discursive guides to important bits of the OS, backed up by detailed documentation at the module level. Any comments as this goes on are welcome.

As you’ll see, the bulk of the updates made have been to the structure of the PRMs rather than the content. My main stylistic observations (subjective, of course!) are:

- The Overview/Introduction pages at the module level have become redundant since the shift around. Each Module title page holds a short introductory text, together with links to SWIs, Service Calls, etc. If more details are needed to explain how to use the module, then it goes in a Technical Details section. If even more details are needed, then we should consider providing a dedicated ‘Guide’ section in the PRMs, and link the module docs to that.

- The title of each page is the name of the wiki page – in general, the content text doesn’t need to have another h2 heading repeating this (the exceptions are the SWI/Service Calls/*Command pages, where I haven’t altered the format at all). So I’ve removed a few headings here and there.

- I’ve also switched a few h2 headings down to h4, as otherwise the display looks a bit shouty, to my eyes. This is also for simplicity – most pages now have an h2 title, followed by text broken up by h4-headed sections. Aside from the odd italic or code-formatted text, this is the only formatting, making it easy to keep standard.

Very minor tweaks, then – let me know if you agree with them, or if you have any other comments on the layout stuff. When time allows, I’ll keep adding modules to the list. When we have a more or less complete list, it would be good to discuss how we might work on the main PRM contents page to tie everything together.

Oh, and part of that future task would be adding example code in BASIC and C – like the Microsft pages, but with example code that actually works.

And preferably the example code should handle error cases or unexpected results properly (or if the error handling would make it too long-winded, at least add comments for what/where the error handling should be)

And preferably the example code should handle error cases or unexpected results properly (or if the error handling would make it too long-winded, at least add comments for what/where the error handling should be)

Yes, however as I also said earlier:
“The problem is that there is a lot of work to do to flesh things out into full guide rather than cryptic clues and the people with enough knowledge probably ought to be doing other things.”

Can’t win really.

I’ve continued tinkering with the documentation. I’m quite keen to de-layer things a bit, and as far as possible to modularise the text. In the long run, this will make it easier to manage, and should lead to a simpler front page too.

I’ve updated the Buffers, Events and Interrupts pages in the first section of the PRM. The Buffers page now links to the BufferManager module reference. Since all of these are single-page documents, I’ve removed the intervening ‘Overview’ page, which seemed like an unnecessary layer. I’ve done some light edits on the text, which mostly involve removing the long breadcrumb hierarchy and moving h2 headings down to h4.

Before I do any more work along these lines, can I check that people are happy with these changes (in particular Alan, since I’m tinkering with your layout choices)? If anyone has any comments, or objects to the changes, they’d be easy to switch back. If people are happy, I’ll keep working through, adding modules as I go along.

Your changes look good to me.

I suspect you know this already, but one thing to look out for when updating pages is links to pages containing spaces. E.g.

[link1]SWI+Introduction#address

For these to work with the current wiki version the + needs changing to %20.

I’ll start work on updating the SWIs page – apart from updating it to the new format it also needs updating to discuss 26/32bit issues.

Random thought that’s going to cause us lots of pain – at the moment we’ve got lots of tables formatted like this to describe the format of packed structures:

But I’m wondering whether it would be better (in some cases at least) to format it like this:

• Chunk Offset Number – Identify individual SWIs in a chunk
• Chunk Number – Specifies a block of 64 consecutive SWIs for use by application or module
• Error Flag (X bit) – Determine the action taken on errors
• SWI Group – Specifies which part of the system implements the SWI. Possible values are shown in the table below
• OS Flag – Specify which OS the SWI expects to execute the SWI. RISC OS requires this bit to be zero

Of course fiddling with the format of things would be a lot easier if we were using a wiki which supported templates :(

Personally, I think the original is better, because the suggested format…
(a) duplicates information (eg ‘Chunk Offset Number’) which makes creating/updating more difficult,
(b) makes reading information about any item more difficult, as two places have to be read (one for the bits, and one for the description).

Better all on one line without duplication, I think.

I like Jeffrey’s method as you get a feel for how the word is put together. I would use a colon instead of ellipses and always include all 32 bits in the description. So I’d add bits 31:24 whatever the swi instruction bits are – can’t remember off hand.

If the current system is retained I’d reverse the order so the left side of the word is at the top ie you have:

31:24
23:20
19:18
Etc.

I tend to end up thinking in terms of the two values:

Number of bits to shift

Number of bits to read/write (masking)

So the ‘horizontal’ layout Jeffrey indicated would be good if it has a box for each bit, making the layouts easier to follow at a glance. Seeing 4 ‘bit slots’ as boxes is more graphic than seeing two values. The N:M method is also OK once in the habit of subtracting the values to get the number of bits in the value. But in my head I’d be converting either into
“Nshift:Nmasked”. :-)

Jim

I think Jeffrey’s formatting would tend to get rather convoluted if the word is split into more than five or six ‘things’. It does remind me a bit of the way the ARM ARM does things and would certainly help in cases where the meaning of various bits (and how the word is split up) depends upon the state of certain others, e.g. mode specifiers.