Presentations

PRM-in-XML Presentation Styles (2024)

PRM-in-XML Presentation Styles

Script and notes

Part 3 - Different presentations

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 (use the one from Introduction).
    • Ensure that we have the myswi.xml file from the Introduction.

    • Ensure that the myswi.html has been generated and is loaded into chrome.

      ./riscos-prminxml -f html5 -o myswi.html myswi.xml

Script

Start on the Chrome window, showing the SWI document

In this video I will demonstrate some of the styling features of PRM-in-XML. The generated HTML files use CSS, which allows the layout of the documents to be changed relatively easily.

You can supply your own CSS if you want, but the tool has a number of variants to choose from. Here, I'll demonstrate how to use some of the different presentations.

We start out with the simple demonstration document which contains an definition of SWI OS_Write0.

This is the default style output by the tool. It is quite passable, using uses some standard fonts and a plain layout. It is fine for use on the web. We can use other variants.

Toggle to the terminal

The prminxml tool can pass parameters to the formatter. These parameters control features of the transformation. If we return to the terminal we can get some help on the parameters that are available:

./riscos-prminxml --help-params

This printed a lot of information about the different parameters. If we scroll up we can see some of them.

Scroll to the top

Each format has a different set of parameters, and the format that we're using is the html5 format, so let's look at those.

Scroll to html5, and point to the create-contents section

As you can see, it's possible to turn off the contents links from the top of the page. This might be useful if you want to link to the document externally, or are embedding the document in another page.

Scroll down so that css-variant is in the middle of the screen; point to it

There are many options but if we scroll down we can see the css-variant parameter, which allows us to specify which of the variants we want to use. You could also supply your own style sheet with the css-file parameter, but that's more advanced.

Scroll to the bottom of the terminal again

Let's try out some of these variants. The variants are actually a space-separated list of names that we can include in the produced HTML file, and they're supplied with the --param option.

The first variant I'll show is the prm variant.

The PRM variant applies a style that looks close to the RISC OS 3 manuals. It has a bigger effect when used in the generated PDF, which we'll look at later.

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm" myswi.xml

This command line is the same as the one we used before, but has an extra --param switch added, which configures the variant to use. The output has been generated so let's see what it looks like in the browser.

Switch to Chrome

This is the document as it was, without any variant applied. If we reload in the browser we'll see what the variant looks like.

Press ctrl-r to reload

As you can see, some of the content has changed in style, which is what we expect. The spacing has changed slightly, the weights of the fonts have changed and we've got some grey bars where they were solid black before.

There are other changes, but on this document they're not visible.

That was relatively simple, but we might also want to make the fonts a little more like the PRM.

Switch back to terminal

We can do that with some of the freely available Google fonts. In my examples I've used Fraunces and Raleway as good substitutes for the PRM fonts.

To do this we need to add in variants to tell the CSS to change the heading and body fonts, and that we want to use them as webfonts as they are not installed on my machine.

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm body-fraunces heading-raleway webfont-fraunces webfont-raleway" myswi.xml

Switch back to chrome and reload

We reload and we can see the style has changed slightly again - just the fonts this time, with the headings being a little thinner, and more flourished, and the body font is a little more fancy. If we have the Novarese font available, we could use it and get something even closer to the PRM, but Novarese costs money.

Anyhow, let's try another style - the prm variant can itself be modified to make it more like the RISC OS 2 manuals.

Switch back to terminal

If we add in the variant prm-ro2 we get a style that is closer to the RISC OS 2 manuals:

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm prm-ro2 body-fraunces heading-raleway webfont-fraunces webfont-raleway" myswi.xml

Switch back to chrome and reload

Reload again and the style has changed quite a bit more. We're still using the fonts that we selected before, but now the layout has changed considerably. The chapter title has a large separation from the main document.

The headings are on the left, with a divider line, and this makes the whole page more dense, despite losing space on the left. Although it is an older style, it is quite an attractive look.

Switch back to the terminal

In the later days, Acorn released some functional specifications for the NC, and for network components, which had a more distinctive style. Although these functional specifications were never used for full documentation, the feel of the style can be replicated. The variant name is acornfs, which replaces the prm-ro2 we just used.

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm acornfs" myswi.xml

I've removed the font specifications because Acorn just used standard fonts in their specs.

Switch back to chrome and reload

As before, we reload and again the look has changed. Headings are centred, dividers and links are green, there are grey highlighting bars for the definitions. The definition description, is also aligned right, which might be easier to skim through in a browser.

Part 4 - Obtaining Prince XML

Setup

  • As for part 3.
  • Clean the terminal and scrollback.

  • Ensure that prince has been deleted.

    rm -rf prince*

  • The browser should be showing the acornfs style HTML page.

Script

Start on the browser

We've tried some different presentation styles, but not everyone wants to view documentation in their browser. Sometimes a PDF is better - it's possible that some people might want to print out chapters for reference, and PDF is much better for that.

The HTML that has been created is designed to be used as 'Paged media', for PDF and printed content. The best tool I have found to generate a PDF is PrinceXML. The tool is free for non-comercial and personal use.

The PRM-in-XML output has been tested with PrinceXML going back many years, and should remain compatible in the future.

If we go to PrinceXML.com we can use the Download link to find the right binaries to use.

Go to princexml.com and then click the Download link

Here we can see a number of links to releases for different platforms. I'm using macOS here, but there are versions released for Linux distributions as well.

Scroll to the macOS binary and download it

This will take a moment to download. Ok, now we need to extract in the terminal.

Switch to the terminal again

Move the file here, and extract it.

mv ~/Downloads/prince<tab> .
unzip prince<tab>
ls
ls prince<tab>

There is an installer present, which you can use if you want to install on your system, but I'm just going to use the tool directly for this demo. Let's check that it works.

prince-15.1-macos/lib/prince/bin/prince -h

Yup, that's working.

Part 5 - Generating PDFs from PRM-in-XML

Setup

  • As for part 4.
  • Ensure that the previewer tool hasn't been loaded.
  • Prince should be present.
  • Clear the terminal

Script

Start on the terminal

Let's rebuild our original document, using the PRM style and see what it looks like as a PDF.

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm" myswi.xml && prince-15.1-macos/lib/prince/bin/prince -o myswi.pdf myswi.html

We generate the document, with the prm variant, and if that's successful we run Prince on it, to create a PDF.

We get a small warning about a CSS feature that's not supported, but otherwise, we're working.

ls

There's the PDF we created. Let's see what it looks like.

open myswi.pdf

Ok, so we can see the document's been created and that it looks similar to the PRM.

Scroll so that the SWI calls page is at the top of the screen

As you can see, this is the same documentation, but formatted as a PDF.

If we scroll down you can see how it's got page headers and footers, together with page numbers. The document is split up with new pages at the start of each section and API definition, just like in the original manuals.

On the left you can see the contents of the document. These are PDF bookmarks, which let you jump to the each section of the document. The contents links that we saw in the HTML version are not present in the PDF - they aren't needed as the PDF format provides them itself.

What about other styles we demonstrated before? They work in the PDF format as well.

Switch back to the terminal

Let's try the RISC OS 2 style again, by adding in the prm-ro2 variant.

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm prm-ro2" myswi.xml && prince-15.1-macos/lib/prince/bin/prince -o myswi.pdf myswi.html

And we return to the viewer...

Switch back to preview and scroll to the top; the window may need to be resized

The document has automatically reloaded in the macOS previewer. As you can see, it looks very similar to the RISC OS 2 manuals. The page size has also been changed to be closer to the original size of those manuals. The page size is another configurable in the CSS, so is trivial to change if required.

Finally, there's a new variant that I have created which tries to bring in a more modern style to the manuals. It might not be 'right' for everyone, but it shows how the content can be modified to fit different needs.

switch back to the terminal

The new 'modern' style uses different fonts and lays out some elements differently. It takes some inspiration from the old functional specs, but largely it draws on the technical documentation produced by Intel...

./riscos-prminxml -f html5 -o myswi.html --param css-variant="prm prm-modern body-notosans heading-saira webfont-notosans webfont-saira" myswi.xml && prince-15.1-macos/lib/prince/bin/prince -o myswi.pdf myswi.html

And back to the viewer...

Switch back to the viewer and scroll to the top

As you can see, this has a different layout. Chapter heading is now top right, green, and all-caps. Headings in general are green and use a squarer font.

Scroll down to the SWI documentation

The arbitrary indent has gone - it's unnecessary as we use colour to delimit to sections. The body font is a sans-serif font, which is generally easier to read for technical documentation. As with the other styles, there are number of presentation features that aren't shown as this is such a simple document.

However, the styling of the document is flexible, and if something isn't desireable, it can be changed with a little CSS.

All these presentational changes are controlled by the CSS and by the transformation. That means that you can worry about what the documentation is, and not how it's presented. If you change your mind in the future, the layout is easy to change.

And of course, the tools are freely available and work on Linux and macOS. Whilst Prince isn't available for RISC OS, the HTML generation tools are, and any modern browser will be able to view the results.

I hope this has shown how different styles can be used for your documentation. Thank you for watching.