User Guide small corrections

User Guide small corrections

This page was established to log subediting and other small corrections during the development of issue 1 of the RISC OS 5 User Guide, published in April 2018 in support of RISC OS 5.24, and available as a paperback book from ROOL here, and as a downloadable PDF file here. A big thank you to everyone for their careful checking!

You can now use this page to log suggested corrections to the latest published User Guide, whether resulting from mistakes in the text or from changes in the software that affect the use of the system or its built in applications.

Updates and corrections to the User Guide

If you have spotted any errors in the existing User Guide, or if you have any suggestions for new material suitable for inclusion, please add them below by editing this page (the wiki keeps previous page revisions too). Alternatively they can be sent to the address on the Reader’s Comments page at the back of the issue 1 book.

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.

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).

Due to a quirk of how the master document is stored in change control the page numbers in the index/contents are only periodically regenerated.

Guidelines for image submissions

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 and have no bleed area around them. Where menu trees are open the void space is solid white, not transparent.

Small corrections

Please preface your entry with “Chapter Title/Page Number” with a little context either side to help locating:

User Guide, issue 1, April 2018

Managing the desktop/78:
Add “Note 3: The system may be unstable after using System Monitor to quit a task. Save as much work as you can, then shut down and restart.”

The Boot application/118
“Commenting out lines in a Desktop boot file” should read “Commenting out lines in a Desktop settings file”.

Paint/355:
In the section “Create the middle of the flower”, the numbered list should start from 1 (not 3).

Chars/399:
“permissable” should be “permissible”.

Appendix B/Built in application options/513
This chapter refers to “the Desktop boot file” throughout. It should be called “the Desktop settings file”.

Appendix B/Built in application options/513/12:
When you configure and save Alarm choices (see page 389) they are saved in file PreDesk.Alarm. If you change the choices but do not save them, the changed values are saved in any Desktop boot file that you create and, if executed during a boot, will supersede those in PreDesk.Alarm.
Bug Tracker Enhancement Ticket 471 also refers Ed: Alarms now uses Choices, the file format is a private implementation detail

Appendix B/Built in application options/513:
Two of the options (“-timeout” and “-weekwork”) are mentioned but not described in detail. In addition, the “-format” option is described in a slightly repetitive fashion. A better layout would be something like:
-timeout: Number of seconds an Alarm beep sounds.
-weekwork: Days of the week that constitute “the working week”, represented as a single number (Sunday=1, Monday=2, Tuesday=4, Wednesday=8, Thursday=16, Friday=32, Saturday=64). The default setting is 62 (i.e. Monday+Tuesday+Wednesday+Thursday+Friday).
-format: The format of a user-defined clock display (see “Time and display formats” on page 392). The default setting is “%z12:%mi:%se %am. %zdy/%zmn/%yr”.
You may find it easier to set these options via the Alarm Choices window (see page 389).
Starting with Alarm version 2.94 (26 February 2020) Alarm choices are now held in “!Boot.Choices.Alarm”. The system variable (Alarm$Options) is still created by !Boot.Choices.Boot.Predesk.Alarm, but Alarm now appears to ignore its contents. It would probably be best to remove the Alarm section from Appendix B, or at the very least reduce it to “A Desktop Settings file may contain an entry of the form ‘SetAlarm$Options …’ but in practice this has no effect on the operation of Alarm itself.” Ed: A cleanup script at 5.28 will delete the redundant file

ChangeFSI/465
New/changed OS features (minor) – 4k/64k sprite generation

Changing the computer’s configuration/108
The window’s layout has changed. Ed: Looks same in version 0.16 (17-Oct-19)

Draw/337
-In the section on Printing part of a diagram, the first two
bullets under point 2 need to be combined as they work together. The third bullet is separate Ed: the text is correct, select/adjust don’t create a bounding box, they move the box by one of two corners

StarComms 19-Mar-2018

The “StarComms” file also needs updating. For example:
*Configure Dump – Options 0-3 are listed but the Pi defaults to option 4
*Configure Mode – This should be listed as an alias of *Configure WimpMode
*Configure MouseType – Options 0-3 are listed but the Pi defaults to option 7
*Configure RamFsSize – This command is effectively obsolete, as the largest RAMDisc it can declare is 1020kB. Users wishing to declare a RAMDisc should be directed to the appropriate Wimp features (“Configuration > Discs” or the Task Manager window).
*Opt 1 – PRM 5a-687 listed this command as “no longer supported” Ed: It’s supported, the PRM is referring to shortcoming in FileSwitch
*Opt 4 – *Opt 4,1 should be listed as “obsolete” and *Opt 4,3 should be annotated “for backward compatibility only”. Ed: While Opt4,2 is most common, the others are still supported

User Guide draft 29-Feb-2020

The desktop/67:
Objects pinned to the desktop are pinned relative to the bottom of the screen, not the top. If you increase the display resolution (e.g. from 800×600 to 1280×1024), an object previously pinned to the top of the screen will now appear part-way down the screen. Ed: Recovering icons lost on a mode change is covered in the table for ‘Pinboard menu options’

Appendix D/RISC OS file types/528
FDC is recognised by Filer as a resolvable absolute (not relative) reference, so why describe it as an unresolvable UNIX one? It’s one way of creating shortcuts within RISC OS. Ed: Sure? The only reference to FDC in the sources is NFS, when it can’t resolve a soft link

There are two chapters numbered “11”.

Windows/16/
Close icon: add that if Ctrl and Alt are pressed then clicking the Close icon removes all open windows from the desktop except those that have unsaved data.
Iconise icon: add that its presence depends upon a Windows Configuration option (p.108) and that the miniature version can go to the icon bar if the Pinboard Configuration (p.99) specifies that. Ed: Added to Part 2 ‘The desktop’ advanced chapter rather than Part 1 ‘Windows’

Using discs/134
‘not all memory card sockets honour the slide’s setting and may permit writing to the disc in either position’ – this should probably say ‘card’ rather than ‘disc’. Ed: Would repeat ‘card’ 4 times in one paragraph

Other storage devices and filing systems/139
‘It is possible to use the CD player like a juke box’ – according to the OED, ‘jukebox’ is a single word.

Changing the computer’s configuration/81
New/changed OS features (minor) – Disc setup 0.13 fades floppy when unavailable
New/changed OS features (minor) – Boot setup 0.10 button name

User Guide draft 08-Mar-2020

Appendix B/Built in application options/519:
Edit’s configure string is unlike the others’ in that the single character flags (R,D,O,T) are turned on/off by their presence/absence rather than by appending plus/minus. This is not really explained. (Better possibly might be the ~ (tilde) convention used by Filer).

Appendix B/Built in application options/520:
Edit’s N (font name) option can also take a spec like ‘N\FCorpus.Bold\ELatin1’ when an encoding is needed. (And also \M matrix definition, I wonder?).

Appendix E/Old-type screen modes/532:
Move the list of monitor types to the “Monitor types” section on page 535. Amend the text of this section to reference the new location of the list.

Appendix E/Old-type screen modes/535:
Add a new sub-heading “Low-colour modes”. Some platforms – notably the Raspberry Pi – cannot display modes with fewer than 256 colours. In this instance, choosing an old-style screen mode with fewer than 256 colours will cause the corresponding 256-colour mode to be used instead (e.g. mode 31 requested, mode 32 delivered). Programs that fail to take account of this substitution could misbehave as a result. In addition, a program minimally modified to produce the correct colours (in the mistaken belief that mode 31 was a 256-colour mode) would misbehave when transferred to a platform that can display low-colour screen modes. Ed: Added, but phrased in a non platform specific manner

Appendix E/Old-type screen modes/535:
In the “Monitor types” section, add a note that a monitor type of “Auto” is typically restricted to the modes supported by monitor type 4 (SuperVGA) in the table. (This won’t be true in all cases, but the vast majority of monitors will support VESA modes, which correspond most closely to “SuperVGA” in the table.) Ed: Screen setup plug-in recommends to use Auto or EDID, and the appendix cross refers to that, so no need to duplicate

OmniClient/167
New/changed OS features (minor) – Save choices, ellipsis after ‘Free…’

User Guide draft 15-Mar-2020

The Desktop/45:
Changing the computer’s configuration/90:
describes the option of ‘Double click and hold’ for opening an application directory. Since this offers an ergonomic improvement, its existence should be mentioned elsewhere, i.e.
The desktop/48:
‘To open an application directory’ and ‘You can Shift double-click to close any directories’.
The Boot application/115
‘loading it into Edit (Shift double-click)’ twice on this page.
The Boot application/117
‘loading it into Edit (Shift double-click)’
Edit/271
‘Shift double-click on its icon’
ChangeFSI/466 ‘shift double-click on !ChangeFSI’ (and should be ‘Shift’)
Editors have not up to now made use of footnotes, but either use them or insert ‘See also p.90’. Ed: Extra index cross references will appear when the index is next regenerated, table for Configure plugin bolstered

New/changed OS features (minor) – Filer 2.44 creates intermediate directories for ‘New directory’
New/changed OS features (minor) – Filer 2.47 check menu screenshots for ^R shortcut
New/changed OS features (minor) – Various filer screenshots need checking for ellipsis after ‘Free…’

StarComms 29-Feb-2020

*Delete – This can be used to delete directories as well as files. Only empty directories can be deleted.
*RMTidy – From RISC OS 3.5 onwards, this command does nothing.

User Guide draft 22-Mar-2020

Maestro/403
New/changed OS features (major) – User interface overhaul. Rest position improvements. (Chris, by email)

User Guide draft 29-Mar-2020

Draw/277
New/changed OS features (major) – Drag & drop, clipboard, Duplicate object menu entry, choices (Sprow, by email)

*WimpScroll now in StarComms listing

User Guide draft 27-Apr-2020

New/changed OS features (minor) – Mouse setup plugin scroll wheel settings

Command line appendix description of traversing the directory structure (Stuart, by email)

User Guide draft 04-May-2020

Paint/349
New/changed OS features (major) – Drag & drop, clipboard, colour arrangements, zoom/resize, fg/bg swatch, keyboard shortcuts, new sprite dialogue (Sprow, by email)

Managing the desktop/76
The ‘system memory allocation’ screenshot has the ‘Tasks’ heading off-centre (the other screenshots don’t). Admittedly I haven’t checked this against a real system, but it doesn’t look right!

User Guide draft 25-May-2020

New/changed OS features (major) – Drag & drop, clipboard in Wimp icons

Saving Edit application preferences/273
The sentence starting “You can set features of this type…” should mention “Save choices” on the Edit icon bar menu as the preferred way of saving changes. Also it would need to mention that a Desktop settings file will override any choices saved via Edit itself.

Edit$Options/274
The sentence starting “If you have not changed any display features…” should reference a desktop settings file, not a boot file. Ed: Now saved in Choices

User Guide draft 01-Jun-2020

No known issues!