Updated PRM-in-XML documentation tool and resources

Recently I released significant updates to my documentation tools and resources.

The PRM-in-XML tools are intended to provide the means by which documentation for RISC OS components can be created. The format is designed with 4 major goals:

• To be structured
• To provide a flexible base for documentation
• To be translatable to other formats easily
• To provide cross-referencing facilities

The recent release of 1.03 of the PRM-in-XML tool contains over a year’s development work to make the format more useful for real-world documentation, and to look good. The tool has been tested on multiple operating systems and is known to work on Linux (Ubuntu 18-22, Debian 10, CentOS 7 & 8, Mint 18-21), macOS and RISC OS.

A video demonstrating how to use the tools on Linux and macOS has been made available recently, generously edited and published by Paolo through the RISC OS Community On GitHub . A couple of follow-up videos show how to use the tool on RISC OS and the different presentation formats, which will appear in due course.

The GitHub repository of example documents contains some examples to demonstrate the format’s functionality and provide examples for people to work from. It has been updated to use the latest release and is now automatically published to a website containing content generated by those examples as HTML and PDFs. Each document is presented individually, to demonstrate the standalone generation of the content.

The GitHub repository containing staged PRM-in-XML documents contains documents converted from other sources and aren’t quite ready for integration into the main PRMs yet. Like the example documents, this has been updated to use the latest version of the tool, and now publishes to a website containing the staged documents . This repository publishes the documents as a collected publication, using the five major styles provided by the tool.

PRM-in-XML is of course very flexible, and the recent update to version 1.03 has introduced many more features than the prior releases:

• Can generate HTML 5/CSS content, which is suitable for use as paged media content such as PDF.
• Can be styled in a number of different ways to present the content in different forms – in particular a RISC OS 3 style PRM, RISC OS 2 style PRM, and a more modern style are available.
• Still supports output to plain HTML in the form of unstyled tables for compatibility with legacy RISC OS browsers.
• Improved documentation on the tool itself.
• Contains a working RISC OS distribution.

New features of the PRM-in-XML format include:

• API declarations are more consistent, with consistent use of sections within them.
• New input, key and mouse elements to represent input actions.
• New actionbutton element to complement the menuoption element.
• offset-table and message-table elements can now be supplied with data sizes.
• New definition-table to avoid overloading of the value-table (which is intended to define numeric values).
• New alternates element to allow for non-optional alternations in command definitions.
• reference elements for SWIs now prefix with the text SWI.
• image elements are better supported and allow multiple in a row.
• Indexed content now allows cover content and front matter to be specified.
• New compatibility, version-table and version elements allow interfaces to state their evolution over time, or through different suppliers.

If you just want the latest release of the tool, it’s here: https://github.com/gerph/riscos-prminxml-tool/releases

And the documentation can be found on the GitHub site and supplied within the release.

These tools and resources have been updated with help, testing and suggestions from Alan Robertson and Bernard Boase. Many thanks to them both.