Expanded documentation in preparation for release.

Many changes to the documentation:

* The documentation has been checked with LanguageTool.
* Advanced usage section describing how to use parameters.
* The CSS has been tidied up a little and small mistake with the
  Novarese font fixed (it was preferring ITC Novarese Std, which
  meant that many things were italic for me).
* New CSSVariants.md document describing all the different
  variants which are available and how they relate to one another.
* Links to the downloadable versions in the main README.md.

README.md

@@ -1,5 +1,11 @@
 # PRM-in-XML tool and transforms
 
+[![Download: RISC OS](https://img.shields.io/badge/Download-RISC_OS-blue)](https://github.com/gerph/riscos-prminxml-tool/releases/download/v1.03.65.html5-css.258/RISCOS-PRMinXML-1.03.65.html5-css.258.zip)
+[![Download: POSIX](https://img.shields.io/badge/Download-POSIX-blue)](https://github.com/gerph/riscos-prminxml-tool/releases/download/v1.03.65.html5-css.258/POSIX-PRMinXML-1.03.65.html5-css.258.tar.gz)
+[![Download: Examples](https://img.shields.io/badge/Download-Example_Documents-blue)](https://github.com/gerph/riscos-prminxml-tool/releases/download/v1.03.65.html5-css.258/Example-Output-1.03.65.html5-css.258.zip)
+[![Documentation: Usage](https://img.shields.io/badge/Documentation-Usage-yellow)](catalog/docs/HowTo.md)
+[![Documentation: File format](https://img.shields.io/badge/Documentation-File_Format-yellow)](catalog/docs/PRMinXML.txt)
+
 ## Introduction
 
 PRM-in-XML is a specialised XML format for writing RISC OS documentation in the style
@@ -12,26 +18,27 @@ of the Programmers Reference Manuals. The format is designed with 4 major goals:
 
 This repository contains the PRM-in-XML tool and the transformations necessary to
 convert the format into HTML and other formats. The primary transformation is HTML 2 with
-tables, with a HTML 5/CSS transformation coming in later versions.
+tables, with an HTML 5/CSS transformation coming in later versions.
 
 The tool, `riscos-prminxml`, is intended to be used to process XML files into other
 formats.
 
+For more information on the rationale for the PRM-in-XML format, see the article on [Iconbar](https://www.iconbar.com/articles/RISC_OS_Documentation/index1700.html).
+
+
 ## Installation on POSIX systems
 
-The release archives contain the tool ready to be installed into your `PATH` (on POSIX
-systems). Copy the `riscos-prminxml` file and `riscos-prminxml-resources` directory
+The release archives contain the tool ready to be installed into your `PATH`. Copy the `riscos-prminxml` file and `riscos-prminxml-resources` directory
 to a location where they can be executed from, such as `/usr/local/bin` or `~/bin`.
 
 ## Installation on RISC OS systems
 
 The RISC OS archive contains a set of tools to place somewhere that they can be
 executed, such as within your library. A common installation would be to copy all
-the files and directories from `Tools.XML` into your library, eg `!Boot.Library`.
+the files and directories from `Tools.XML` into `!Boot.Library`.
 
-The distribution for RISC OS includes the `perl`, `xsltproc` and `xmllint` binaries.
-The version of perl supplied is suitable for use with the tool only. These must be
-available on the path.
+The distribution for RISC OS includes the `xsltproc` and `xmllint` binaries.
+The version of Perl supplied is suitable for use with the tool only.
 
 
 ## Requirements
@@ -59,7 +66,9 @@ For installation on macOS:
 
 ## Usage
 
-The tool contains help on the its usage. However, the most common usage of the tool
+### Basic operations
+
+The tool contains help on its usage. However, the most common usage of the tool
 (on a POSIX-like system) would be something like:
 
     riscos-prminxml myfile.xml
@@ -93,6 +102,59 @@ Individual tags within the documentation format can be described with a command:
 
     riscos-prminxml --help-tag chapter
 
+### Advanced usage
+
+The `riscos-prminxml` tool can be supplied parameters for the transformation
+to use. As each format has its own implementation, these parameters will be specific to the transformation. A list of the transformations which are
+supported for each format can be listed with a help switch:
+
+    riscos-prminxml --help-params
+
+The parameters option may be specified multiple times with different parameters
+
+For example, in the `html` and `html5` formats, the parameter `create-contents`
+can be used to modify whether the links to each of the sections will be
+created at the top of the document. To disable this table of contents for the
+document, use:
+
+    riscos-prminxml --param "create-contents=no" myfile.xml
+
+Most commonly this switch would be used to control the type of CSS content
+used by the `html5` format. There are three parameters which are generally
+used to control the styling of the HTML 5 documents:
+
+* `css-base` - used to specify the base style for the document. The value
+  `standard` will use the built in CSS styling. The value `none` will omit
+  the built in CSS styling entirely.
+* `css-file` - includes the supplied CSS file.
+* `css-variant` - specifies a variant to apply on top of the CSS as a space-separated list of variant names. The variants are defined in the `prm-css.xml` file.
+
+The default CSS style is suitable for viewing within a desktop browser, but
+for a style which is closer to the PRM you might apply the `prm` variant:
+
+    riscos-prminxml --param "css-variant=prm" myfile.xml
+
+To modify this to be produce documentation in the style of the
+RISC OS 2's PRMs:
+
+    riscos-prminxml --param "css-variant=prm prm-ro2" myfile.xml
+
+More information about the CSS variants which can be applied can be found in the [`CSSVariants.md` document](catalog/docs/CSSVariants.md).
+
+
+To introduce your own CSS styling on top of the standard, you might
+create a small CSS file to change the features you felt needed changing,
+and apply this with the `css-file` parameter:
+
+    riscos-prminxml --param "css-file=my.css" myfile.xml
+
+
+### Video guides
+
+Some video guides have been produced which explain how to use the PRM-in-XML
+tool. See https://presentation.riscos.online/prminxml/index.html for more details.
+
+
 ## Tested platforms
 
 The PRM-in-XML tool is tested and known to work on a number of platforms:
@@ -111,11 +173,38 @@ macOS.
 
 The PRM-in-XML format is documented within the text files in the [`catalog/docs`](catalog/docs)
 directory. A skeleton document is available in [`catalog/gerph/skeleton.xml`](catalog/gerph/skeleton.xml)
-which can be used to construct new documents or as a guide for creating them. A 'HowTo' document
+which can be used to construct new documents or as a guide for creating them. A '[How To](catalog/docs/HowTo.md)'
 in the documentation directory describes the process of creating new documents.
 
 ## Examples
 
-The PRM-in-XML format contains some [example documents](examples) which are used to check the
+Example PRM-in-XML documents can be found on GitHub tagged with the `prmxinml` topic.
+
+In particular, there are example documents in a repository at https://github.com/gerph/riscos-prminxml-examples
+
+The Releases section includes built HTML and PDF documents within the archives.
+
+As part of the work towards making available more RISC OS documentation, many existing documents have been converted to PRM-in-XML format. Whilst these are incomplete or do not have their own place to be stored, these can be found in the `riscos-prminxml-staging` repository.
+
+This can be found at: https://github.com/gerph/riscos-prminxml-staging
+
+Again, the Releases section includes built versions of the documentation.
+
+
+### Test example files
+
+This repository contains some [example documents](examples) which are used to check the
 behaviour of the tool. These show some of the elements that can be used by the PRM-in-XML
-format. A larger set of examples can be found in the repository at https://github.com/gerph/riscos-prminxml-examples.
+format.
+
+The example documents can be built from POSIX systems with the following commands:
+
+    cd crosscompile
+    ./build-examples.sh
+
+To build with PDF output, using Prince XML (personal and non-commercial use is
+a valid use of Prince XML - see https://www.princexml.com/purchase/license_faq/), use:
+
+    env PRINCEXML_I_HAVE_A_LICENSE=1 ./build-examples.sh
+
+This will process the indexed documents in the `examples` directory to generate the different forms of output in the `test-output` directory.

catalog/ReadMe.txt

@@ -2,17 +2,19 @@ Catalog files
 =============
 
 This directory contains the files necessary to build the PRM documents
-provided here.
+provided here. If you are using the `riscos-prminxml` tool, these will
+be handled for you. However, if you are using the catalog directory, you
+must set system/environment variables:
 
-Under RISC OS, you should set XML$CatalogFiles to point to the root/xml
+* Under RISC OS, you should set `XML$CatalogFiles` to point to the `root/xml`
 file.
-Under Linux, you should set XML_CATALOG_FILES to point to the root.xml
+* Under Linux, you should set `XML_CATALOG_FILES` to point to the `root.xml`
 file.
 
 Documentation can be found in the docs directory:
 
-    - docs/PRMinXML.txt - documents the elements and usage of the PRM-in-XML format.
-    - docs/BNF.txt - documents the BNF elements which can be used by PRM-in-XML.
-    - docs/HowTo.md - describes how you can use the tool and build documentation.
+    - `docs/PRMinXML.txt` - documents the elements and usage of the PRM-in-XML format.
+    - `docs/BNF.txt` - documents the BNF elements which can be used by PRM-in-XML.
+    - `docs/HowTo.md` - describes how you can use the tool and build documentation.
 
-A skeleton PRM-in-XML document can be found in gerph/skeleton.xml.
+A skeleton PRM-in-XML document can be found in `gerph/skeleton.xml`.