Presentations

Creating PRM-in-XML docs on RISC OS (2023)

Creating PRM-in-XML documentation on RISC OS

Script and notes

Part 1 - Obtaining the tool

Setup

  • Prepare a Chrome browser for presentation.
  • Create a working directory for the demonstration in the RPCEmu hostfs
    • mkdir ~/Documents/Windows\ Applications/RPCEmu/hostfs/prminxml/
    • cd ~/Documents/Windows\ Applications/RPCEmu/hostfs/prminxml/
    • bash
    • clear
    • Ensure that the prminxml directory is empty.
    • Ensure that the ~/Downloads/RISCOS-PRMinXML files have been deleted.
  • Have a RPCEmu ready.
    • The 0.9.4 on macOS seems to have a menu key that works in the normal way - that's called RPCEmu-Recompiler in my system.
    • RISC OS 4, cut down, with the MDF in the root of the disc.
    • Enter the desktop.
    • F12 then:
      • *LoadModeFile $.MDF
      • *Set Wimp$Font Homerton.Medium
    • In Display manager select mode 1024x768.
    • Prepare a Zap, and related resources in the Zap directory.
    • Ensure that that !ZapUser has been run.
    • Run !Zap.
    • Leave the filer window for prminxml open.

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 RISC OS system to generate documentation. A prior video has described how you use the tool on macOS or Linux.

The first thing we need to do, is to obtain a copy of the PRM-in-XML tool. This can be found on GitHub, so let's get it. I'm going to do this on macOS, but you can download the archive in whatever way that you want.

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 released version.

Go to releases

We go to the Releases section, and we can see the latest version of 1.03. There are also some example documents that have been generated which you can have a look at if you wish. We want the RISC OS release.

Download the archive

I'm going to move the tool to RISC OS so that it can be extracted there.

alt-tab to the terminal window

mv ~/Downloads/RISCOS-PRM<tab> ~/Documents/Windows\ Applications/RPCEmu/hostfs/prminxml/

Ok, so over to RISC OS so that we can extract the archive. You should decompress the zip file into a directory using whatever tools you like.

I've created a directory called prminxml here, but you can place this where you like.

Alt-Tab to switch to the emulator, click in the window and move in and out a couple of times to ensure that the pointer is synchronised

Menu over the Filer window to 'Refresh' the prminxml directory

There's the archive that we want to extract.

Open a taskwindow in zap, and size to full screen

I'm using the command line on RISC OS Select, so I'll use miniunzip to decompress the archive, but you can use SparkFS or other tools to extract the files.

*.
*Miniunzip RISCOS<tab>
*.

There are a few tools in the Tools.XML directory.

*.Tools.XML

Those tools can be copied into your library - just copy everything from inside Tools.XML to somewhere in your library. I'm only demonstrating this, so I'll just make them part of the filesystem library for the purposes of the demo.

*lib Tools.XML

Let's have a look at the help.

*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 up to the top of the commands, and then down to the example commands

leave the skeleton example command in the middle of the screen

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 using Zap here, as this is the editor I know - you should use whatever editor you are familiar with.

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 09 Sep 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, or retype, the riscos-prminxml command: *riscos-prminxml -f html5 -o skel/html skel/xml

This has created a new HTML file.

*.

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

Switch back to the terminal

I'm switching back to the host browser, as I don't have a RISC OS browser on this system.

open -a "Google Chrome" ~/Documents/Windows\ Applications/RPCEmu/hostfs/prminxml/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.