Overview
StrongHelp is the traditional hypertext manual format used on RISC OS. In the build environment, a manual is usually edited as a directory tree of page and resource files, then packaged into a single manual file of type &3D6.
This appendix summarises both the container form and the editable source-tree form that the build environment tools expose.
The source-tree form is the more complete part of the locally supplied documentation, so this appendix treats that as the canonical maintenance view and describes the binary container only to the extent that the shipped tools and references make it explicit.
StrongHelp formats
Container file
The packaged manual is a single file with StrongHelp filetype &3D6. The installed command help for riscos-strongcopy states that the file begins with the standard HELP header and then stores the manual content in StrongHelp directory blocks.
At a high level, the container consists of:
| Part | Occurrence | Contents |
|---|---|---|
| 1 | 1 | StrongHelp file header beginning with the text HELP. |
| 2 | 1 or more | Directory blocks describing pages, resources, and subdirectories. |
| 3 | variable | Stored page and resource file data. |
The build environment tools are intended to work with this format through extraction and rebuilding rather than by hand-editing the binary container.
In other words, the binary container is the publication form of a manual, not its preferred maintenance form within this environment.
The file header is:
| Offset | Size | Field | Contents |
|---|---|---|---|
| 0 | 4 | magic | The text HELP. |
| 4 | 4 | root_size | Size of the root directory block. |
| 8 | 4 | version | StrongHelp container version number. |
| 12 | 4 | free_list | Offset of the free-space list, or 0 if unused. |
| 16 | 4 | root_offset | Offset of the root directory block from the start of the file. |
Each directory block (the root, and any subdirectory) begins with a 12-byte header followed by a sequence of variable-length directory entries, one per contained file or subdirectory, running up to the block's declared used size:
| Offset | Size | Field | Contents |
|---|---|---|---|
| 0 | 4 | magic | The text DIR$. |
| 4 | 4 | dir_size | Total allocated size of the directory block. |
| 8 | 4 | dir_used | Bytes of the block actually used by directory entries (must not exceed dir_size, and must be at least 36 for a block containing one entry). |
| 12 | variable | entries | Directory entries, packed consecutively from offset 12 up to dir_used. |
Each directory entry has a fixed 24-byte header followed by a null-terminated leafname, the whole entry then padded so the next entry starts on a 4-byte boundary:
| Offset | Size | Field | Contents |
|---|---|---|---|
| 0 | 4 | object_offset | Offset from the start of the file to this entry's own data block (a nested DIR$ block for a subdirectory, or a DATA block for a file). |
| 4 | 4 | loadaddr | RISC OS load address. When bits 20-31 are all set, bits 8-19 hold the file's 12-bit RISC OS filetype. |
| 8 | 4 | execaddr | RISC OS execution address. |
| 12 | 4 | length | Length of the entry's data, including the 8-byte DATA block header for files. |
| 16 | 4 | flags | RISC OS attribute bits in the low byte, plus bit 8 set if this entry is a directory. |
| 20 | 4 | reserved | Reserved. |
| 24 | variable | leafname | Null-terminated object name. |
A file's own data block (pointed to by its directory entry's object_offset) begins with an 8-byte header:
| Offset | Size | Field | Contents |
|---|---|---|---|
| 0 | 4 | magic | The text DATA. |
| 4 | 4 | size | Total allocated size of the block, which must be at least the directory entry's length field. |
| 8 | variable | data | The file's content, length minus 8 bytes long. |
Editable source-tree form
For source control and host editing, the manual is represented as a directory tree. This is the form produced by riscos-shextract and consumed by riscos-strongcopy.
Common special files are:
| Name | Meaning |
|---|---|
| !Root | Required entry point page for the manual. |
| !Configure | Optional manual configuration for fonts and styles. |
| !Pre | Optional helper code for keyword lookup preprocessing. |
| !Menu | Optional iconbar menu definition for the main manual. |
| !root | Directory-local default page within a subdirectory. |
Page file structure
Each StrongHelp page is a text file. The local StrongHelp topic guidance describes the basic page structure as:
| Part | Occurrence | Contents |
|---|---|---|
| 1 | 1 line | Page title on the first line. |
| 2 | zero or more lines | Body text, formatting commands, links, and optional sub-pages. |
Formatting commands begin with # at the start of a line, or may appear in braces within text. Links are written in angle brackets. The local syntax guide recommends using #Parent on every page so that navigation remains consistent.
The supplied syntax reference further records:
| Construct | Meaning |
|---|---|
| #StyleName | Applies a named style such as #H1 or #Code. |
| #StyleName:Text | Applies a style to one inline span of text. |
| #Subpage | Begins a sub-page held within the same file. |
| #Tag tagname | Declares a target for tagged links. |
| #Include filename | Includes another file during processing. |
| {...} | Inline command form embedded within text. |
Links and page organisation
The common link forms include:
| Form | Meaning |
|---|---|
| <PageName> | Simple link to another page in the same manual. |
| <Display Text=>PageName> | Link with explicit displayed text. |
| <Display Text=>Manual:PageName> | External manual link. |
| <Display Text=>*OSCommand> | Link which runs a command. |
| <Display Text=>PageName#tagname> | Link to a named tag in a page. |
Large manuals may be organised flat in one directory, grouped by prefix, or grouped by first-letter ranges such as [a-z]. Empty files named OLDNAME>NEWNAME can be used as redirections.
The local structure guidance also notes that a !root file within a subdirectory acts as that directory's default page.
Filename constraints
StrongHelp reserves additional characters beyond normal host filesystem conventions. The local guidance notes that names needing characters such as !, <, >, or # should use !xx hexadecimal escaping in filenames, where xx is the character's 2-digit hexadecimal ASCII code. For example, a page named Q&A would be stored as Q!26A, since & is character code &26.
The local structure notes give a broader reserved-character set for StrongHelp maintenance names:
! [ ] \ < > . $ % & ? # :
When extracted in the build environment, resource files retain their RISC OS filetypes through host-side comma suffixes such as SpriteFile,ff9.
Tooling workflow
The normal tooling workflow is:
- inspect the manual with riscos-shextract --list;
- extract it to a directory tree with riscos-shextract --extract-dir;
- edit pages and resources in that directory;
- rebuild the container with riscos-strongcopy -o Manual,3d6.
This is also the boundary between the two StrongHelp-related command roles in the environment: riscos-shextract turns the binary container into an editable tree, and riscos-strongcopy turns that tree back into a container.
Extraction and rebuild workflow
Extracting and rebuilding a manual
This is the normal source-controlled StrongHelp workflow.
riscos-shextract --extract-dir ./Manual-src Manual,3d6
riscos-strongcopy -o Manual,3d6 Manual-src