---

RISC OS PRMs on CD

The Programmers' Reference Manuals are once again available on CD. Mark Smith sees whether any lessons have been learned from the last attempt.

Call me old fashioned, but I've always preferred paper manuals to disc-based documentation. Why? Well, when your screen is full of editor windows that you're using to design your work of art, compose your prose or code your masterpiece, surely the last thing you want to do is plonk your software or technical documentation in a window on top of what you're trying to work on?

However, that said, documentation held in an electronic form has certain advantages over the paper variety, or at least it does in the majority of cases:

• Search facilities may help to locate what you're looking for faster.
• Hot links allow you to locate related information easily, without having to look it up in the index.
• You don't have to worry about keeping it open at the required page, especially if you're looking at several simultaneously.
• You don't have to clear a space on your desk to put it down.
• It's usually cheaper to buy, and certainly cheaper to mass produce.
• It saves space - a book shelf full of manuals can quite easily be held on a single CD.

New CDs for old

Documentation on a CD is nothing new in the RISC OS world. After all, the 'Tekkie Disc' from Emerald Publishing has been around for a good few years and that has the RISC OS 3 PRMs on it, together with manuals for DDE, Desktop C, Assembler and BBC BASIC.

So what about the new RISC OS PRM CD from RISC OS Ltd.? What does it provide that we don't already have?

Well, the first point is that there is a wider selection of manuals. Not only do you get volumes 1 to 4 of the PRMs, but you also get volume 5a which covers the differences in RISC OS v3.5 and 3.6 against v3.1. You also get the User Guide, Timecode, Internet & Omniclient manuals as well as manuals that accompany Desktop C/C++ rather than the Desktop C release 4 ones supplied with the original Tekkie Disc.

The next major improvement is the format in which the files are held. Whereas the Tekkie Disc uses a proprietary file format and librarian to view them (which isn't even StrongARM-compatible on the version that I have), RISC OS Ltd. has opted to provide the documentation in standard HTML and PDF formats. So why is this so important? Well, aside from being able to use your favourite browser to view the documentation, you don't even have to do it on your RISC OS machine. That means if you have a second non-RISC OS machine with its own monitor, you can neatly sidestep my initial objection, by using that to display the documentation whilst you dedicate the RISC OS machine to doing the work.

Finally, at £30 (£25 for Foundation members), it's much cheaper than the original price of the Tekkie Disc, and certainly much cheaper than paper manuals.

Better than paper?

So how does it shape up against the positive reasons that I listed above for using disc based documentation?

Well, good use has been made of the ability to link between pages in the HTML version, you can obviously open multiple browser sessions on different pages and not have to worry about keep a paper manual open, and it's also clearly much cheaper and economical on space.

Unfortunately, it falls down on the first point. Although most browsers will allow you to search within a page, there's no concept of a complete manual or set of manuals so you can't, say, search the entire PRMs for a particular piece of text. It's not a failing of the product, it's just simply not possible to provide searchability with HTML documentation without using additional software that may restrict the choice of browsers and/or prevent it being used on a non-Acorn platform.

Using Fresco, a cut down version of which is supplied on the CD, access to the pages is quick and easy. In fact, this seems to be a very competent conversion of the paper manuals into HTML format, aside from one link which I came across that didn't work.

But that's where the real limitations show. This is purely a conversion of the existing paper manuals and no more. There's no documentation on the differences in RISC OS 3.7, or more importantly 4.0 and even the RISC OS 3.5 and 3.6 differences are still out on their own in volume 5a, not integrated with the rest of the PRM in a logical fashion.

As well as a cut down version of Fresco, there is also a public domain PDF viewer supplied. However, using this to access the PDF manuals seems inordinately slow, even on a StrongARM Risc PC and I couldn't get the PRM volume 1 file to load at all. Combined with the fact that some of the manuals aren't supplied in PDF format and there is no means of following reference links, I can't really imagine that many people will want to use the PDF versions over the HTML on a RISC OS machine unless you happen to have alternative PDF viewing software. Things improve somewhat when accessing them using xpdf on Linux. This is a great deal faster and although there is still no link mechanism for following references, it is possible to search an entire manual for some text which you cannot do with the HTML.

Conclusion

So what's the final verdict? While it's a shame that we still have no documentation covering the additional and changed features in RISC OS 4, this is never-the-less a welcome alternative to those who wish to have access to the existing documentation, cheaply and easily.

As for me, I will probably continue to use my paper manuals. But then, I've already paid for them and they are already occupying space on my bookshelf.

Product details

Mark Smith