Bounty proposal: PRM v2

This suggestion ought to be obvious from the title. ;-)

Currently, as I understand it, we have the PRMs 1-4 which cover from RISC OS 3.1 onwards; broken into sections (1-Kernel, 2-Filing, 3-Wimp, 4-Odds and sods). PRM 5 was added as a sort of disparate pile of stuff to bring this up to date for RISC OS 3.5.

Well.

We’re now on RISC OS 5. There’s a lot of information around, but it is scattered all around the place in forums and wiki pages. In writing BeagLEDs I used/abused both the wiki and the source code archives.

Would it not be better to update the four volumes of the PRMs to include PRM5 changes into the main text, plus bring up to date for RISC OS 5, plus describe the operation of the HAL?
These days, also, it might be relevant to describe clearly how RISC OS boots and what it expects on entry (anything specific in registers, at a specific address, with/out cache/MMU, etc).
Furthermore, since the OS source is now open, it makes no sense to hide stuff behind a “This call is for internal use only” messages.

For this, I have two questions:

• Obviously, is anybody interested in this?
• Do we have the data files for the content of the PRMs, and if so, what format are they in (Ovation? AcornDTP? Impression? Something else?)

Various people had a conversation about this at the SW Show – there’s certainly some interest in this area. There’s a similar issue regarding Welcome Guides.

The PRMs are in FrameMaker format. I’m not sure who has the files, but they do exist. I believe the say-so on what can be done with them is Castle’s. Justin Fletcher did the PRMinXML package, for producing various formats of PRM information from an XML file – that might be worth looking at if someone has a copy (his site no longer exists).

is anybody interested in this?

I’m sure there’s some interest. Some discussions regarding documentation updates took place at the 2012 Southwest show, primarily concerning the Welcome Guide.

Do we have the data files for the content of the PRMs, and if so, what format are they in?

It seems that ROOL has them in FrameMaker 7 format (few significant changes except for ObjAsm4 stuff). They’re copyrighted. I don’t think I’m alone in wishing for their contents to be released for use/modification under community ownership (free licence?) The migration of (reworded) contents to the ROOL wiki provides a useful resource but may not IMHO be the best long term solution.

It seems that ROOL has them in FrameMaker 7 format

I wonder how much work would be involved in translating this into something to run under OvationPro (if RISC OS preferred) or LibreOffice (otherwise)?

I don’t think I’m alone in wishing for their contents to be released for use/modification under community ownership

As they stand, they’re the best and most compact source of documentation we have. When you factor in the possibility of on-demand printing, it opens up opportunities for relevant up-to-date documentation in an accessible format (PDFs are useful, but I prefer printed).

Is the RISC OS Programmers Reference Manuals CD still available? It had PRM 1 to 4 in PDF form (and said it had PRM5a but I can’t find it on the CD at the moment although the index contains references to it). The PRM5a can be downloaded here (now edited to work)

They’re included on the ROOL Developer CD (PRM1-5a, ABC, assembler, BASIC, C/C++, DDE, Style guide, Toolbox). The RO Foundation site that you link to (you need to prepend your link with http:// as it’s broken otherwise) has all of those available, though of course doesn’t include documentation of ROOL changes to the tools. ROL or other dealers may still have copies of their manuals CD (the main advantage over the downloads being, AFAICS, that they’re also included in HTML as well as PDF).

Rick, since you posted this in Bounties and not Wishlist, can I ask what you’d expect a developer to achieve for some paid work on this? For example, what would the deliverable be and what steps would be necessary to achieve it? It’s not a problem if some of it is unclear at this stage. Just trying to make you write down a bit about where you might want to end up and how you would get there…

One suggestion: PRM1-5a may well be copyright (but are easily available). So what we need is a set of corrections by page number.

One suggestion (to avoid copyright problems) is an overlay or replacement page for every correction. One possibility then is to export from the original PDF and replace affected pages by the given corrections and then reimport into a new PDF. Or wrtie a programme that would convert the original PDFs into corrected PDFs. Not sure what would work and/or be legal but that’s a suggestion.

Theo – brief reply because I’m at work. Perhaps this should have been in wishlist? I wanted to encourage discussion of a possible bounty towards documenting the platform, for the available documentation is either out of date or scattered around. Programmers don’t tend to concentrate on documentation as much as perhaps they should.

Task? Coalesc old PRM content and the various resources around to create an updated applies-to-RO5 version of PRMs 1-4 (I think 5 can be ditched once content is merged into 1-4). That, of course, will be the deliverable (as PDF (for users) and whatever editor format was used (for future mods)). It might be better as a group effort, though, with people knowledgeable in specific areas doing the work on those parts…

I asked Justin for the whereabouts of PRMinXML – he said he’ll have a look. Some of the files are available on Sourceforge. In essence it takes an XML file (eg agprotocol.xml) containing PRM documentation and transforms it (via the XSLT in prm-html.xsl) into HTML. It ‘just’ needs writing different XSLTs to make wiki or StrongHelp (Justin was already working on that) or RTF or iPhone or… For printed documentation one option is PDF via LaTeX (see this example of a website converted from XML to PDF). FrameMaker 7 will export XML, so there’s another XSLT needed to transform that into Justin’s PRM format. There’s the beginnings of a toolchain here, but stringing the tools together reliably is always a bigger deal than it sounds.

is anybody interested in this?

Yes. A bounty seems like a reasonable way of getting the documentation produced; there’s just so much that needs doing that if it’s just left to people doing it in their spare time on an ad-hoc basis (which is what I’ve been doing) then it might never be completed.

Of course the documentation also needs to be kept up to date with any source changes that happen as the documentation is being written, so we’d ideally want OS developers to have access to the documentation as it’s being written, so that whoever’s writing the docs doesn’t have to keep checking CVS every five minutes to see if anything new needs to be covered.

PRMInXML (or some other similar scheme, e.g. doxygen style markup in the source itself) sounds like an excellent way of handling things to me – each component in CVS could have its own XML file(s) providing documentation. Storing the documentation source in a machine-parseable format also opens the door to performing verification steps, e.g. looking at compiled code and making sure all the exported SWIs, C functions, etc. are all documented. Or you could have tags in the XML files indicating when the documentation was last updated, so the converter tools can easily check which documentation might be out of date wrt source changes and fire off warnings.

Guys, we did an analysis of the PRMs with a view to bringing them fully up-to-date, chopping out the cruft, fixing errors/omissions, etc. It looks like around 70 man weeks of effort for someone who really understands what they are writing about (and there aren’t too many people in that category). Even at minimum wage, you’d be talking about needing a bounty to reach something like £16,000. Looking at how none of our existing bounties have even reached £1000 for fundamental OS features, I can’t see this ever getting off the ground.

Mind you, if there’s someone out there with very deep pockets, clearly that might change – but would that person rather see – for the sake of argument – a) the PRMs updated or b) RISC OS supporting large disks, partitions and large files? I’ve certainly not seen any signs of such a rich benefactor thus far… :(

a) the PRMs updated or b) RISC OS supporting large disks, partitions and large files?

Good point, if the 70 man weeks can’t be trimmed.

rich benefactor

No takers at the Beeb@30 event, then?

Let me know if/when any of these docs become “open”. If it is a format I can work with, I’d look to updating the welcome guide (for bringing new users into the fold). All of our documentation is a little…stale.
I’d also be willing to take a crack at PRMs but I’m not sure I’m suitably qualified. I will, however, cry buckets when I reluctantly ^A and ^X the entire section on Econet. Waaaaaah!

This, of course, not being done for bounty (though if anybody wants to post me boxes of Tetley, that’s good! ;-) ).

Beer or tea?

The Iyonix welcome guide was produced in Ovation pro based on an OCR’d old Acorn copy. However, I’m not sure what the copywright etc. is on it, but it might be a start if no other copy is available. Did ROOL ever have a copy from Castle? If not, I might have a copy, but my Iyonix is currently packed for moving house so I can’t check at the moment. Permission for use from Castle would also be required of course.

Thanks – that’s useful. Castle should already have received emails concerning this (one very recently).

Brilliant! If you get a copy unwrapped, Trevor, please shoot one my way. I can do OPro under both RISC OS and Windows.

[thinks] Maybe these days we ought to preface the thing with a chapter on “Installing RISC OS”? Beagle xM is dead simple (see my blog). I think Beagle (orig) needs some scr files, but this stuff could be put on a website. How is it for the RPi? I’d imagine broadly similar – tweak uEnv and drop in “riscos”?
We might even be able to put up a zip containing the image and script files. Unarchive, dump on SD, boot it. [can’t rely upon SDCreate, newbies prob. won’t have a compatible box]

Fingers crossed, then perhaps I can contribute something when not currently running new-hardware RISC OS…

copy unwrapped

Obviously the previous Welcome Guide is copyrighted. We could really do with knowing under what conditions the guide can be worked on, and under what licence community amendments will be made. If/when things are clearer I expect there’ll be a thread here, but in the mean time I’ve copied the email to you. And I have RISC OS OPro too.

It has been almost a month. Has there been any progression on this?