Introduction
This document is intended to show some examples of the different styles of the Acorn manuals and some presentations using the PRM-in-XML formatted content. The content has been taken from scanned PDFs, for the original manuals, and the HTML and PDF generated by experimental versions of the PRM-in-XML. That is to say, it's not perfect, but it demonstrates some of the flexibility.
Example pages
To provide examples of the formatting of content, 3 sample pages have been selected from the manuals:
- The contents page
- The start of the introdution to RISC OS chapter
- The OS_Claim SWI definition.
These pages demonstrate many of the features of the manual. They should be easy to compare between the different versions.
Acorn manuals
The Acorn manuals that are being examined here cover a few years of development, during which time Acorn refined the style of the manuals considerably. The manuals which will be shown are:
- RISC OS 2 reference manual
- C release 4 reference manaul
- RISC OS 3 reference manual
- RISC OS 3 reference manual volume 5a
Other manuals exist within the timeline, with varying features, but these are most relevant to the intended use of the PRM-in-XML system.
PRM-in-XML formats
PRM-in-XML is flexible in how it can generate content, but the examples here will concentrate solely on the HTML 5/CSS format. This will vary only the CSS used within the content. Much greater flexibility is afforded by being able to configure the CSS as required but here only limited canned variants of the standard CSS template are being shown.
In addition to the HTML, the same content is passed to PrinceXML for conversion to a PDF. This is done without modification to the intermediate files. Other conversion solutions exist and could be used with the paged media CSS.
Some of the example content is incomplete - the images have some bad lines - and on some pages the contents and images have not been styled properly. These are artifacts of incomplete stylesheets, which can be addressed in time.
The PRM-in-XML tool has a configuration which allows for layering of CSS snippets on top of a base stylesheet. This configuration is used to change the presentation of the content. The variants which are available at the present time are:
| Variant | Meaning |
|---|---|
| prm | Closer to the RISC OS 3 PRMs for paged media and screen rendering. |
| acornfs | Acorn Functional Specification style. |
| prm-ro2 | Closer to the RISC OS 2 PRMs for paged media. Not complete for screen rendering. |
| numbered-sections | Apply numbers to the sections on the page. |
| body-novarese | Change body font to ITC Novarese (requires local installation of this commercial font). |
| body-fraunces | Change body font to Fraunces (requires local installation of this freely available Google font). |
| webfont-fraunces | Download the Fraunces font as required. Use in conjunction with 'body-fraunces'. |
| heading-raleway | Change heading font to Raleway (requires local installation of this freely available Google font). |
| webfont-raleway | Download the Raleway font as required. Use in conjunction with 'heading-raleway'. |
| large-bullets | Apply larger bullets to lists. This is closer in style to the reference manuals. |
| drop-character | Apply a drop character to the first letter of the first paragaph. |
| no-edge-index | Remove the grey region from the right pages. |
For reference, this document was generated with the standard settings, but an extra CSS file was added to give the images a rounded border.
riscos-prminxml -p css-file=extra.css -f html5 gallery.xml
Acorn: RISC OS 2 manuals
The RISC OS 2 manuals had some distinctive features which make it stand out from the later manuals. It is notable that these manuals use the Novarese font which was retained for later publications.
- Headings are restricted to the left of the page. Content is on the right.
- The whole manual uses a vertical dividing line to sepatate headings from the content.
- Chapter and sections are shown in the footers, together with the page number.
- Page numbers in the contents page line up vertically.
- An edge index is not used.
Compare this to the SunOS manuals of the same period.
Because of this separation of the content, there is a lot of space wasted on many pages. However, finding sections in the API definition pages is a lot easier. In the later versions of the manuals this left indent is still present (although not as large).
Example pages
Acorn: Acorn C Release 4
The Acorn C Release 4 manual is an updated style from that of the RISC OS 2 PRMs, and has many of the features of the later publications.
- The contents page uses grey horizontal bars, but only on some of the headings.
- The contents page has page numbers alongside the sections, which isn't as clear.
- The contents page not only references the chapter name, but also sections within the chapter.
- The first paragraph of each chapter has a drop initial applied to the first character.
Example pages
Acorn: RISC OS 3 manuals
The RISC OS 3 manuals were are probably what most people will remember.
- Whilst the earlier manuals appear to be square in their presentation, the RISC OS 3 manuals appear to use a slightly rectangular portrait layout.
- The contents page has dropped chapter sections, but now separates the manual into logical 'parts'.
- Page numbers now include a volume number, which is distinct from the 'part' of the manual.
- Parts of the manual are named and use the edge index to locate them.
- The drop initial used in the Acorn C Release 4 manual has been dropped.
- The style of the API definitions is basically unchanged from the RISC OS 2 manuals, save the headings now taking vertical space, instead of being in the margin.
- Page headers now alternate between the chapter name and the section name.
- Page footers only include the page number.
The vertical space used by the headings on the API definitions is arguably a poorer use of space than in the RISC OS 2 manuals. However, the style is familiar and therefore this usage is largely expected.
Example pages
Acorn: RISC OS 3 manual, volume 5a
Volume 5a was largely unchanged in style from the RISC OS 3 manuals, although some elements have been resized slightly.
Example pages
PRM-in-XML: Default configuration
The default configuration of PRM-in-XML is intended to take on the style of the original RISC OS 3 manuals, whilst being able to be used on a variety of desktop sizes. It is suitable for printing, but has not been tailored specifically for any given device size.
- The contents page is a similar style to that of the RISC OS 3 contents pages.
- Navigation bars are included on the contents to take you to index pages for each of the API definition types. Bars are included both at the top and bottom of the contents page.
- Documentation is organised into named sections, which may be nested arbitrarily.
- Horizontal bars divide sections within the chapters, in addition to the heading being left aligned.
- Chapters open with a navigation block which links to the sections present within the chapters.
- Bullets use the standard browser indentation, not the highly condensed form of the PRM.
- Links are just regular HTML links, which take you to the relevant section. No page numbers are used.
- The PDF generation uses page breaks to split the chapter content at section boundaries.
- The PDF has page numbers beside the links on the contents page, in italic to make them stand out.
- Within the chapter the PDF shows links together with the page number which contains the content.
Content mistakes here are easy to see, and will be present on all the PRM-in-XML examples. The SWI examples have excessive whitespace - this is an authoring error. The image on the intro chapter has a rogue line on the left for some reason.
Example pages (HTML)
Example pages (PDF)
PRM-in-XML: 'prm' configuration
The 'prm' configuration of PRM-in-XML tries to mimic the printed form of the reference manuals much more closely. Whilst the default style is intended for general use the 'prm' style is intended for cases where the look of the RISC OS 3 PRMs is desired.
The variant setting used in this configuration was:
- 'prm': PRM style
- 'body-novarese': Use ITC Novarese font for the body.
- 'heading-raleway': Use Raleway as a reasonable approximation.
- 'large-bullets': Use the larger bullets.
Features of this configuration:
- Font is slightly smaller than the default.
- Horizontal grey bars used to divide chapters and sections.
- Alignment of headings is closer to the original style.
- Relative sizes of headings are closer to the original style.
- Bullets sit closer to the left edge, and are themselves larger, closer to the original.
- The PDF generated pages are much closer to the original style.
- Within the PDF, the chapter heading is indented to match the text, leaving space for a chapter number (which is not currently implementated).
- Within the PDF, he edge index is present, and included the name of the document group configured within the chapter.
- When printed, the API definitions describe each related SWI on a separate line to make it easier to see the page numbers.
- In the PDF, the page headers include the chapter and section names, and footers include the page number.
Example pages (HTML)
Example pages (PDF)
PRM-in-XML: 'prm-ro2' configuration
The 'prm-ro2' configuration of PRM-in-XML tries to mimic the RISC OS 2 PRMs. It is not a complete configuration, but it is highly effective at present..
The variant setting used in this configuration was:
- 'prm': PRM style
- 'prm-ro2': RISC OS 2 style (layers on top of the base PRM style)
- 'body-fraunces': Use Fraunces font for the body.
- 'heading-raleway': Use Raleway as a reasonable approximation.
- 'large-bullets': Use the larger bullets.
Features of this configuration:
- Not really suitable for use on the desktop at the current time - really only for PDF.
- Separated headings and content style, like the RISC OS 2 PRMs is reproduced.
- Style is retained in both the contents and the chapter pages.
- Sometimes the layout of the headings on the left overlap when the sections are small. Some of this is avoided but it's not perfect.
- The HTML form has contents section that looks unsightly.
- PDF version lays out well.
- Page numbers are positioned appropriately in a vertical line away in the contents.
- API page looks very close to the original.
Example pages (HTML)
Example pages (PDF)
PRM-in-XML: 'c release 4' configuration
The 'C release 4' configuration of PRM-in-XML adds a few small things that match that manual. It is not a complete configuration, but it demonstrates the ability to vary the layout.
The variant setting used in this configuration was:
- 'prm': PRM style
- 'prm-ro2': RISC OS 2 style (layers on top of the base PRM style)
- 'body-fraunces': Use Fraunces font for the body.
- 'heading-raleway': Use Raleway as a reasonable approximation.
- 'large-bullets': Use the larger bullets.
- 'drop-character': Initial drop character on the first character of the first paragraph.
- Additionally the setting to include the sections in the contents was enabled in the contents generation, for a depth of 1 level.
Features of this configuration:
- Exhibits the same flaws as the PRM-ro2 version; there's only a few changes.
- Sections are expanded and linked in the contents page.
- Drop characters are present on the chapter pages.
- In the PDF, the links on the contents page are indented further for the sections.
Example pages (HTML)
Example pages (PDF)
PRM-in-XML: 'acornfs' configuration
The 'Acorn functional spec' configuration of PRM-in-XML tries to mimic the style of the functional specifications that Acorn produced in the later years It is not a complete configuration, but it demonstrates the ability to vary the layout.
The variant setting used in this configuration was:
- 'acornfs': Acorn Functional Specification variant
- 'body-fraunces': Use Fraunces font for the body.
- 'heading-raleway': Use Raleway as a reasonable approximation.
- 'large-bullets': Use the larger bullets.
Features of this configuration:
- Green dividing lines instead of grey.
- Green link text.
- Chapter and section headings are centred.
- All text is left aligned, with no indentation.
- Subsection, subsubsection, category are left aligned, with small indentations to show nesting.
- API page has a similar style to the PRMs, but is less indented.
- The API name is given a grey border.
- API description is right aligned and italic.
Example pages (HTML)
Example pages (PDF)
