Software information: User Guide (Rev #22, changes)

Showing changes from revision #21 to #22: Added | Removed | Changed

RISC OS User Guide

About the User Guide download

From this page you can download a PDF version of the working copy of the User Guide. It is based on Acorn’s original RISC OS 3.70 User Guide exported as a PDF that should be sufficient for people to start looking at what edits need to be made.

The PDF was generated from RISC OS Open’s master FrameMaker document, which was copied straight off a DO (the Acorn Drawing Office) backup CD. There only seemed to be one issue number in there so is presumed to be the latest. As far as we can tell, Acorn didn’t print the 3.70 User Guide on paper, it was only ever released as HTML (likely exported from FrameMaker).

About the update project

We have uploaded the Acorn document to allow the community to assist RISC OS Open with the work involved in updating this (rather large!) document to address everything that has changed in RISC OS 5, which is almost twenty years of development. From time to time, ROOL will update the working version of the RISC OS 5 User Guide, as updates are folded into the master document.

This is our suggested plan of attack for bringing the User Guide fully up to date:

1. Scan the cover image
2. Milestone: Recreated RISC OS 3.70 manual
3. Delete the dead chapters (eg.!PhotoView) & fix up any cross references
4. Note new sections required where dead chapters were relevant (e.g. !CDPlayer is now integrated into CDFSFiler but we just deleted !CDPlayer chapter)
5. Add new chapters for wholly new stuff
6. Rework existing chapters where radically different, e.g. !Configure
7. Integrate relevant text from the Welcome Guide, this covers primitives like using the mouse to control the filer, and is presupposed by the filer chapter (which just says “in the Welcome guide you learned how to…”)
8. Tone down dated references, e.g. “RISC OS 3 PRMs” → “RISC OS PRMs”
9. Edit technical inaccuracies (e.g. the description of how to map out a defect predates large >512MB drives)Edit technical inaccuracies (e.g. the description of how to map out a defect predates large >512MB drives)
10. Top and tail with new Copyright blocks & trademark boilerplate, etc.
11. Milestone: RISC OS 5.2x topics completeMilestone: RISC OS 5.2x topics complete
12. Review whether the chapter grouping still makes sense (it may not any more) in light of new material
13. Check the nesting of the PDF index is sane, sprinkle index markers on new text
14. Review cycles
15. Make the cover artwork & print

Our strong suggestion here is that the community would be most valuable contributing to items 4, 5, 6 6, 11 and 14 of the above. Please send submissions touserguide@riscosopen.org. If anyone wishes to be added to the userguide@ email address, so they too get a copy of emails sent to that address, let us know – via an email to that address. There is also a forum thread for general discussion of this work.

Guidelines for textual submissions

Please read and adhere to the Tech Pubs Style Guide – for example, the text needs to use the correct tense, with no Americanizations, and you certainly don’t want no double negatives. You may suggest further subediting standards not covered in that guide by adding to the page User Guide style conventions?. The Editor may leave suggestions in clear or, if not agreed with, struck through.

Each new or updated chapter should be created as a child of this wiki page to allow community updates. Discussion relating to updates can be held on the forum thread.

Please avoid putting too much work into the formatting of the wiki pages; ROOL will need to redo all of this when the work is folded into the master document so anything more than a gentle hint in the wiki pages will just create more work for ROOL (unformatting it all first).

Guidelines for image submissions

Email any updated/new images to the userguide@riscosopen.org address and include information about where they should appear in the User Guide. As the icon set has changed since the RISC OS 3 User Guide it is likely that most screenshots will need to be touched to some degree.

Before capturing screenshots you must

• Install the Manuals theme which is based heavily on the Sovereign desktop theme with alternative window furniture
• Use Homerton 12 point as the desktop font
• Disable the Wimp’s background tiling for all screenshots
• Turn off the iconise icon
• Capture in EX1 EY1 screen modes

These settings must be used for the whole manual to be consistent and for there to be consistency across the whole range of RISC OS books that ROOL publish. They are chosen so the icons are easily visible and print well in greyscale.

Images should be supplied in 24bpp colour PNG format with have no bleed area around them. Where menu trees are open the void space is solid white, not transparent.

Once an updated image is submitted to ROOL, please mark the relevant location(s) in the wiki document as “updated” so other community members know not to generate/update the same images.

Update submissions

The page User Guide update submissions? provides a growing list of topics that correspond either to existing Chapters or to newly required Chapters which are the subject of volunteers’ updates.

Small corrections

User Guide small corrections is a page on which contributors can log small editing errors (e.g. spelling and punctuation) that they have spotted in the current draft User Guide. Please report potential corrections under the date of the User Guide version you are reading, together with the sequential page number (of the PDF), the ‘printed’ page number, and some immediate context (rather than a line number).