Appendix38Appendix D: PRM-in-XML 1.03 File Format

Document declaration and catalog version

PRM-in-XML documents are ordinary XML files. A 1.03 source file normally begins with an XML declaration and the 1.03 public DTD identifier:

<?xml version="1.0"?>

<!DOCTYPE riscos-prm PUBLIC "-//Gerph//DTD PRM documentation 1.03//EN"

                            "http://gerph.org/dtd/103/prm.dtd">

The local command-line tool selects the same transform family with catalog version 103: the digits are the DTD version number with the separating dot removed, so catalog version 103 and DTD version 1.03 identify the same release. The installed tool help records this as the current default catalog for the shipped transforms and stylesheets. For automated generation within GitHub CI, see Appendix Y: GitHub CI Actions which describes the gerph/riscos-prminxml-action.

Root structure

The DTD defines the top-level document model as:

riscos-prm ::= chapter* , meta

That is, the root element is always riscos-prm, it contains zero or more chapter elements, and it ends with one meta element. In practice, most source files in this manual contain one chapter followed by one metadata block.

The DTD declaration for the root is:

<!ELEMENT riscos-prm ((chapter)*, meta)>

Chapter-level structure

The normal document hierarchy is:

The structural content models from the DTD are:

chapter ::= (section | import)*

section ::= (p | subsection | subsubsection | category | %definitions; | extended-example | import)*

subsection ::= (p | subsubsection | category | import)*

subsubsection ::= (p | category | import)*

category ::= (p | import)*

Two practical consequences follow from this:

• paragraphs are the main free-form content block;
• deeper structural elements can only appear where the DTD allows them, so valid nesting matters and cannot be treated as decorative.

Standard sections and chapter rhythm

The 1.03 reference does not require a fixed section list, but it documents a conventional PRM ordering that most chapters should follow unless there is a good reason to diverge. Common sections are:

1. Introduction or Introduction and Overview;
2. Overview or Terminology where needed;
3. Technical details;
4. definition sections such as System variables, Service calls, SWI calls, Software vectors, Wimp messages, Toolbox methods, or Commands;
5. Examples.

Only the sections that are relevant to the documented component need to be kept. The reference and HowTo guides both recommend deleting irrelevant placeholder sections from skeleton documents rather than leaving empty headings behind.

That conventional ordering is most useful for component, interface, and tool reference chapters. In a manual set such as this one, appendices can use a lighter structure: an Overview section at the start, then main sections named for the appendix content, and a final Examples section only when worked examples actually add clarity. A Related information section can also be a better fit than examples when the appendix mainly supports navigation to other manual chapters.

Metadata

Every PRM-in-XML document ends with a meta block. The Dtd content model is:

meta ::= (maintainer | history | disclaimer | related)*

The main metadata elements are:

The installed reference stresses that the metadata must be kept up to date, especially the history and maintainer information, because it is the primary record of how a document has evolved.

References and document inclusion

References are one of the core features of PRM-in-XML. The reference element links to interfaces, headings, or external resources. Its main attributes are:

For type="document" references, the installed reference documentation says that the href should not include a file extension. The stylesheet adds the appropriate suffix where needed.

The DTD also defines an import element:

import ::= EMPTY

attributes: document, path

This allows one document to import elements from another using a document path and an XPath expression. The format reference recommends using this conservatively, mainly for reconstructed or amalgamated documents rather than routine authoring.

For example, to pull just the "Run a remote test" subsection out of this book's own common-workflows appendix into another document, illustrating the two attributes together:

<import document="../appendix/common-workflows.xml"

        path="//subsection[@title='Run a remote test']"/>

document is a relative path to the source document; path is the XPath expression evaluated against that document, and every node it matches is imported in place of the import element itself.

Entities and inline technical elements

The 1.03 DTD defines a number of entities intended to keep documents portable and stylistically consistent. Important entities include:

Frequently used inline technical elements are:

The DTD also defines styling and utility elements such as strong, em, sup, sub, br, fixme, and image.

Paragraphs, lists, and examples

Paragraphs use the p element and can contain text, tables, inline technical elements, compatibility blocks, references, lists, and imports. The DTD allows:

p ::= (#PCDATA | %tables; | %parameters; | %inline; | %link; | compatibility | import)*

Lists use list and item, with the list type attribute set to either ordered or unordered.

Longer code or shell fragments use extended-example, whose type may be unknown, shell, pseudo, c, basic, asm, or format.

Input descriptions

The format can describe keyboard and mouse actions through the input, key, and mouse elements.

The reference lists standard key names such as shift, ctrl, return, and function keys, and standard mouse names such as select, menu, adjust, and scrollwheel.

Structured tables

PRM-in-XML provides a small family of structured tables for describing data in a machine-readable way:

The child elements for these tables are respectively bit, value, offset, message, definition, and version. Several of these carry optional header attributes so that the stylesheet can render more precise column titles.

For example, the DTD attributes for offset-table and offset allow explicit control of the labels and field states:

Definition families

The DTD groups the API-definition elements as:

%definitions; ::= swi-definition | service-definition | upcall-definition |

                  message-definition | command-definition | sysvar-definition |

                  error-definition | entry-definition | vector-definition |

                  vdu-definition | tboxmessage-definition | tboxmethod-definition

These families can be summarised as follows:

The reference documentation repeatedly stresses that the use element carries the behavioural meaning of a definition, while the more structural entry, exit, and table elements describe the actual interface shape.

Registers, declarations, and compatibility

Several helper elements recur across the definition families:

The version element used in compatibility blocks can qualify behaviour by module version, RISC OS version, supplier, hardware, and architecture. The DTD currently defines architecture values arch32, aarch64, and x64.

Command syntax elements

Command-like definitions use a small syntax description language based on syntax, switch, optional, alternates, userreplace, and parameter.

The key elements are:

This is the mechanism used throughout this manual's Part 4 reference chapters for wrapper commands and CLI tools.

Validation and transforms

The installed 1.03 documentation distinguishes between two forms of correctness:

Documents may sometimes render despite validity problems, but the format reference strongly recommends maintaining both well-formedness and validity so that future transforms and tools remain reliable. The installed tool provides formats for:

The routine structural check during authoring is:

riscos-prminxml -f lint prminxml/mycomponent.xml

Minimal valid chapter file

This example shows a compact but structurally complete PRM-in-XML chapter source.

<?xml version="1.0"?>

<!DOCTYPE riscos-prm PUBLIC "-//Gerph//DTD PRM documentation 1.03//EN"

                            "http://gerph.org/dtd/103/prm.dtd">

<riscos-prm>

 <chapter title="Example">

  <section title="Introduction and Overview">

   <p>Example text.</p>

  </section>

 </chapter>

 <meta>

  <maintainer><email name="Example" address="example@example.invalid" /></maintainer>

  <disclaimer><p>Example disclaimer.</p></disclaimer>

  <history><revision number="1" author="EX" date="13 Jun 2026" title="Initial version"><change>Created document.</change></revision></history>

 </meta>

</riscos-prm>