Introduction and Overview
This chapter covers the tools and workflows used to create, validate, transform, and maintain structured documentation sources inside the build environment. It focuses on authoring PRM-in-XML and StrongHelp source trees, plus the related interface-generation helpers that are commonly part of documentation maintenance work.
PRM-in-XML workflow
riscos-prminxml
riscos-prminxml generates and validates new PRM-in-XML documentation. The normal workflow is:
- create a skeleton with -f skeleton;
- edit the XML source;
- lint it with -f lint;
- build HTML with -f html5+xml into a separate output directory.
That sequence looks like this in practice. The HTML-building step needs its output directory to exist beforehand, since riscos-prminxml does not create it automatically:
riscos-prminxml -f skeleton -o prminxml/mycomponent.xml
Created prminxml/mycomponent.xml
riscos-prminxml -f lint prminxml/mycomponent.xml
Processing prminxml/mycomponent.xml -> ./mycomponent
mkdir -p html
riscos-prminxml -f html5+xml -O html prminxml/mycomponent.xml
Processing prminxml/mycomponent.xml -> html/mycomponent.html
Copying -> html/mycomponent.xml
The tool can also generate other output formats, including command-help text, generated headers, StrongHelp source trees, and indexed multi-document sets. For automated generation within GitHub CI, see Appendix Y: GitHub CI Actions which describes the gerph/riscos-prminxml-action.
Interface generation from Def files
Generating OSLib interfaces with riscos-defmod
riscos-defmod is aimed at a different documentation-and-code generation problem: it reads a Def interface description and generates source or help output for the SWIs described there. Within OSLib-style workflows, one compact Def file can be kept in source control and used to derive C headers, ObjAsm veneers, assembler headers, SrcEdit help, or StrongHelp content.
The tool reads the Def source from standard input. Most output forms are written to standard output, while the directory-producing forms use the path supplied with -o. That makes it easy to keep the Def source as the reviewed artefact and generate the derived files as part of the build.
The common workflow is:
- edit the Def file which describes the interface types, constants, and SWI signatures;
- generate the required output form, such as a C header with -h or veneers with -s or -l;
- for directory-producing outputs such as -l or -cstrong, supply an output directory with -o;
- use -byte_wide when the interface refers to externally-defined byte-sized types and veneer generation needs to know their width.
In practice this often looks like. The redirected forms write through the shell, not through DefMod itself, so the destination directories (h/ and s/ here) must exist first. The -l directory form also does not create its destination tree: it expects the subdirectories needed for the requested outputs to already exist underneath the -o directory, here s/ for the generated veneer sources plus o32/ and o/ for the assembled 32-bit and 26-bit objects requested by -32bit and -26bit:
mkdir -p h s
riscos-defmod -h < InterfaceDef > h/interface
riscos-defmod -s -byte_wide bytewide.txt < InterfaceDef > s/interface
mkdir -p LibraryOut/s LibraryOut/o32 LibraryOut/o
riscos-defmod -l -o LibraryOut -26bit -32bit < InterfaceDef
Assembling LibraryOut/s/0x54320x-000 [32bit]
Assembling LibraryOut/s/0x54320x-000 [26bit]
Assembling LibraryOut/s/0x54320-000 [32bit]
Assembling LibraryOut/s/0x54320-000 [26bit]
riscos-defmod -h and -s are silent on success and write only to the redirected output file; the example above used the worked Def file from Appendix R: DefMod file format to produce the captured -l output shown.
The Def input language itself is summarised in Appendix R: DefMod file format.
Authoring PRM-in-XML documents
Working with PRM-in-XML documentation
PRM-in-XML is intended for structured interface documentation in the style of the Programmer's Reference Manuals. The practical workflow described by the installed help and the upstream HowTo guide is to begin from a skeleton, trim away irrelevant sections, populate the chapter around the interfaces you are actually documenting, and lint regularly rather than relying only on HTML output.
Creating a new document
Start by creating a skeleton file, then update the chapter title, maintainer details, disclaimer, and history block before filling in the content. The HowTo guide also recommends removing placeholder definition sections that the component does not need, so that the chapter structure stays focused.
This is the usual starting point:
mkdir -p prminxml
riscos-prminxml -f skeleton -o prminxml/mycomponent.xml
Writing the chapter
The main narrative normally lives in Introduction and Overview and one or more task-based sections chosen to suit the workflow being documented. The HowTo guide recommends using those sections to explain what the component is for, how it fits into the system, the important concepts, and how the interfaces relate to one another. Specific interfaces should then be documented in the relevant -definition blocks such as swi-definition, command-definition, or message-definition.
Structured tables such as offset-table, value-table, and definition-table are preferable when a prose paragraph would otherwise hide important data layout or enumerated values. Cross-references should use <reference> elements so that generated output can link related interfaces and chapters properly.
Checking structure and building output
The PRM-in-XML reference material distinguishes between well-formed XML and DTD-valid XML. Documents may sometimes render as HTML even when the structure is not valid, so the normal workflow should always include a lint step.
The most useful commands during authoring are (again, html must already exist before the HTML-building step):
riscos-prminxml -f lint prminxml/mycomponent.xml
riscos-prminxml -f html5+xml -O html prminxml/mycomponent.xml
riscos-prminxml --help-tag reference
riscos-prminxml --help-params
The installed tool help also points to the resource directory under /riscos-resources/Install/Tools/Linux/riscos-prminxml-resources/docs/, where HowTo.md gives the practical authoring workflow, PRMinXML.txt gives the element and structure reference, and related files such as BNF.txt and CSSVariants.md describe specialised parts of the format and HTML presentation.
For the structure of the 1.03 format itself, see ../appendix/prminxml-file-format.
StrongHelp workflows
Creating and extracting StrongHelp manuals
Although PRM-in-XML is the preferred format for interface documentation, the environment also includes tools for maintaining StrongHelp manuals. A normal workflow is to extract an existing manual into a source tree, edit the text and resource files there, and then rebuild the manual container.
Extracting an existing manual
Use riscos-shextract to inspect or unpack a StrongHelp manual file of type &3D6. Listing the contents first is useful when you want to confirm the internal page and resource names before extracting.
For example:
riscos-shextract --list Manual,3d6
Name Type Length
--------------------------------------------------
$.!Root Text 97
$.Topics Text 44
riscos-shextract --extract-dir ./Manual-src Manual,3d6
Extracting $.!Root
Extracting $.Topics
Editing and rebuilding the source tree
Once extracted, the source form is a directory tree of page and resource files. The topic help for StrongHelp recommends treating each page as a text file whose first line is the page title, keeping !Root as the manual entry point, using #Parent consistently for navigation, and preserving any resource files with their host-side comma suffixes.
Rebuild the manual with riscos-strongcopy:
riscos-strongcopy -o Manual,3d6 Manual-src
PRM-in-XML can also generate a StrongHelp directory skeleton with riscos-prminxml -f stronghelp when you need a StrongHelp presentation derived from PRM-in-XML source rather than a hand-authored manual.
For the underlying StrongHelp container and source-tree format, see ../appendix/stronghelp-file-format.