Revised Programmer's Reference Manuals (step 1 of 2)

Guide target £4,200

The Programmer’s Reference Manuals (PRMs for short) are the collection of 6 books totalling over 4000 pages describing the entire interface to RISC OS, right from lowest level register details right up to the format of a DrawFile and everything in between. The last coherent set of PRMs produced came out in 1992, this first bounty lays some of the groundwork to bringing them up to date.

Overview

At present a programmer in search of accurate technical information about RISC OS might have to search in several places

• Acorn’s 1992 PRMs
• The book 5 addition and corrections for RISC OS 3.50
• The book 5a additions and corrections for RISC OS 3.60
• The StrongHelp manuals
• Internal Acorn functional specifications, such as for Ursula
• Our wiki-fied version of selected parts of the PRM

with both a lack of certainty of which is the point of truth, and a lot of time spent piecing all the bits of information scattered around.

Initially, the chapters added in books 5 and 5a will be combined into the corresponding locations in the main books, either by transplanting the chapters wholesale (where new) or inserting the extra text (where an existing chapter was already present). Pre-existing errata and index cross references will be repaired.

We also have updating chapters resulting from the earlier Filing System bounty to cover how FileCore in particular works in RISC OS 5.

Technical details

Looking ahead to step 2 of this bounty, we do plan on offering a printed volume of the finished PRMs, and in order to simplify that workflow the master copies will be edited in FrameMaker. Therefore familiarity with FrameMaker 7 or later will be beneficial.

Some maintenance work was done in the early 2000’s to convert the PRMs to a newer version of FrameMaker, and these will be a good starting point. However, this maintenance also had to work around some display problems with the contemporary !PDF application which are no longer needed.

Once the master copy editing is complete it should become possible to export these for viewing either in a web browser or as a downloadable PDF for offline reading.

Working with the ROOL webmaster we can also optionally host copies in wiki format via bulk import. In the long term this will allow pages to be kept in sync, though at this stage only importing missing pages will be considered to avoid clashes with community edited pages.

Deliverables

• Updated PRM body texts in FrameMaker format
  • Output as PDF for download
  • Output as HTML for offline browsing
  • Script to translate SWIs to Textile markup

Donations	27
Guide target	£4,200.00
Total	£2,910.00 (69%)
State	Underway
Help	More information about the bounty scheme Bounty scheme discussion forum

All bounties