Presentations

Creating PRM-in-XML docs on Linux and macOS (2023): Notes

Creating PRM-in-XML documentation

Script and notes

Part 1 - Obtaining the tool

Setup

  • Prepare a Chrome browser for presentation.
  • Prepare a terminal window that we will use to work with the tool.
    • Ensure that the text has been scaled up appropriately.
    • Clear the terminal with scroll back.
  • Create a working directory for the demonstration
    • mkdir ~/prminxml-demo
    • cd ~/prminxml-demo
    • bash
    • clear
  • Ensure that ~/Downloads/POSIX* has been deleted

Script

This is a short introduction to the PRM-in-XML documentation tool. This tool is intended for generating documentation for RISC OS components. For the purposes of this video, you will need access to a Linux or macOS system to generate documentation.

Whilst the tools will work on RISC OS, that is not the intent of this demonstration.

The first thing we need to do, is to obtain a copy of the PRM-in-XML tool. These can be found on GitHub, so let's get it.

We want to go to the repository at https://github.com/gerph/riscos-prminxml-tool.

Enter the URL and press return

Here you can see all the sources for the tool, and the example documentation that is used to check that features work properly. However, we just want the latest version - I'm going to use the pre-release version because it will become the current version shortly.

Go to releases

We go to the Releases section, and we can see the latest pre-release version. There are also some example documents that have been generated which you can have a look at if you wish. For Linux and macOS, we want the POSIX release.

Download the archive

Now we move to a terminal so that we can extract the tool.

alt-tab to the terminal window

We need to move it from our downloads directory and extract the tool.

mv ~/Downloads/POSIX<tab> .
ls

To extract we just need a tar command - this will extract it to the same directory.

tar zxvf POSIX<tab>

And we can run the tool to see that it has installed properly.

./riscos-prminxml -h

There are quite a few options, and some text to help you work with the tool. Fuller documentation can be found in the docs directory in the supplied resources. If we scroll up to the help messages you can see there are a number of options, and some example command lines to explain common usages.

scroll down to the example commands

leave the skeleton example command in the middle of the screen

In order to use the tool, you will also require a copy of xsltproc and xmllint. If you are running macOS, these will already be installed. If you are running Ubuntu Linux, you can install these with

sudo apt-get install xsltproc libxml2

You could install the riscos-prminxml tool your path - copy it, and the resource directory, together and it will work just fine.

Part 2 - Building a new document

Setup

  • Continue from where we left off (previous setup applies).
  • Prepare an Editor so that we can load the document into.
    • The font size should be large enough that it's visible.
  • Start with the terminal focused, and the text editor ready to be switched to.

Script

Having obtained the tool, we can now create a new document. For simplicity, I'm just going to document a single SWI call. Usually you'd be documenting more than that, but you should find it relatively easy to expand from there.

First thing to do is to create a new skeleton document. Starting from a skeleton is a little easier than creating a document from scratch.

./riscos-prminxml -f skeleton -o myswi.xml

This has generated a new file - myswi.xml - which has examples which you can change to create your own documentation. It also shows you a command which can be used to create the HTML documentation.

Let's load up the file and have a see what we have.

Switch to the editor view and select the skeleton file.

I'm going to skim through the sections we're not interested in, deleting them as I go. There are only a few that we need to edit for this demonstration - feel free to examine them and change them at your leisure.

The first thing we need to include is the chapter title. As I'm only documenting the SWI call OS_Write0, I'm going to just give it the title 'Writing messages'. Normally you'd name the title after the module or functionality that you are describing.

Update the chapter title

There's usually an introduction in the chapter, which includes some words about the module or area that is being documented. I'll just write an example sentence here, but you'll probably explain more in a real document.

Write something like 'In RISC OS, you can print messages with different SWI calls. OS_Write0 is one example.'

We don't need any subsections to describe more things, so these can go.

delete the subsections

We don't need some of these - the overview, terminology and technical details can all go.

delete these 3 sections, making the VDU codes section visible

I'm not documenting the VDU codes, or system variables, or services.

select these 3 sections and delete them, bringing SWI calls to the top

There's a small paragraph here to guide you in what the SWI calls do. We don't want that.

delete the paragraph

Here we've got an example SWI definition here, which we can fill in. If you had more than one SWI to document you might copy the definition so that you can use it as a template for more calls.

Firstly there's the name of the SWI. That's OS_Write0.

Update the name to OS_Write0

The SWI number in hex is 2.

Update the number to 2

The SWI's description should help to identify it in a succinct line.

Update the description to 'Prints a 0-terminated message to the VDU stream'

The IRQ and FIQ state can be defined here. Usually these won't be changed as the IRQ state may be changed in many SWI calls, and FIQs will be left enabled. Similarly the processor mode is almost always SVC. Many SWIs are re-entrant, and OS_Write0 is one which is, so we can change this to 'yes'.

Update re-entrant to 'yes'

Next we have the registers that are set on entry - the values you pass to the SWI. There's only one register passed to OS_Write0. R0 is the string to print.

Update the register-use number to 0, and the description to be 'pointer to 0-terminated string to write'

The registers on exit are just as important. OS_Write0 returns a pointer to the byte after the terminator. The example includes a table, which we don't need.

Update the exit register use to say 'pointer to the byte after the terminator', and delete the other table content

The 'use' section describes what the SWI call does. You should be as descriptive as you need for the interface. If there is detail that is more general, it should go in the Technical Details section. But here, we just want to say what the call does so that people know how to use it.

Update the use p to say 'This SWI will write the supplied string to the output stream, via the WrchV vector'.

Sometimes interfaces will be extended, or bugs may be fixed. The compatibility section allows these changes to be described, together with what version of the system or module they apply to. We don't need it here.

delete the compatibility section

If you have other SWI calls that need documenting, you might include them in the related section. We'll skip this.

Ok, so we've documented our SWI. Now we need to delete the rest of the sections that we don't care about. For other interfaces, you might need them, but you can examine them later.

delete the other sections, mentioning them as we go

We don't need software vectors, or upcalls, or error messages, or wimp messages or anything to do with the toolbox, or * commands, or general examples.

At the bottom there's a section for document metadata. This might not seem important, but it's really useful to know what has changed - most documentation will be updated, and knowing which version of the document you are looking at sometimes helps.

I'll just fill some things in here.

Fill in Gerph, and gerph@gerph.org in the email section Update the disclaimer to Gerph, 2023 Update the revision fields with Gerph and 29 Jun 2023 Update the change with 'Document for presentation'

We can link to external documents, but I don't need them here.

delete the related section

Ok. We now have a document. Let's save it and see if we can create something for presentation.

Save document Return to the terminal

You can see when the document was created that it printed out a message saying how to process the document into HTML. So let's do that.

Copy and paste the ./riscos-prminxml command

This has created a new HTML file.

ls

We can load it into a browser and see what it shows.

open -a "Google Chrome" myswi.html

this shows the document with the contents and introduction visible

And there we are, we now have a HTML document which includes all the content that we described, together with a contents section that lets you jump to each part. If I scroll down you can see the SWI details are all present as we wrote them, and the metadata appears at the bottom.

That's the basics of how you can create documents using PRM-in-XML. There are more example PRM-in-XML documents available on GitHub - use the topic 'prminxml' to find them.

Go to https://github.com/topics/prminxml to show the repositories that are there

I hope this helps you produce useful documentation.