PRMinXML.txt

                      Structure of PRM documentation (1.03)
                      =====================================

Introduction
------------

This document describes the structure of the XML documentation format to be
used by myself and others. The aims of the documentation format are simple :

  * To be structured
  * To provide a flexible base for documentation
  * To be translatable to other formats easily
  * To provide cross-referencing facilities

These aims have been, for the most part, met by the current DTD and reference
transformation (HTML).

Within this document, descriptions of elements are made with pseudo-SGML
entity description notation. This is mostly to simplify description. Where
the DTD and the descriptions in this document differ, the DTD should be
regarded as correct, with this document merely giving guidance on the use
of elements.


HTML transformation
-------------------
There are two major HTML transformations present in this release of the
PRM-in-XML stylesheets - the HTML 3.2 transformation (called `prm-html`
in the stylesheet and `html` in the riscos-prminxml tool) and
the HTML 5/CSS transformation (called `prm-html5` in the stylesheet, and
`html5` in the riscos-prminxml tool).

The transformation provided by the HTML stylesheets is intended to be as close
to that of the PRMs themselves. The HTML 3.2 is intended for use on legacy
browsers where stylesheets are not available. The HTML 5 layout, however,
can be used with modern browsers and takes advantage of many CSS features
as part of its layout. As such it is much more flexible than the original
transformation.

Whilst the HTML transformations are the current reference transformations,
there is no reason why others, such as StrongHelp or Impression DDF could
not be created.


Document validation
-------------------
XML has two primary definitions of correctness of documents.
'Well-formedness' is the term used where all the element start and end tags
match up and are correctly written. All XML documents must be well-formed.
The second form is that of 'validity'. This is where the structure is laid
out in a manner which is consistent with the DTD - all the tags occur in the
orders they should, and no attribute values have been added which are not
understood.

For the document to be translated, they need only be well-formed. However,
we strongly encourage all authors to ensure that their documents are both
well-formed and valid to reduce the likelihood of problems in the future.

In addition to this, the HTML transformation will apply a number of checks
itself on the document content. Where a problem is encountered, a message
will be displayed to indicate the issue which has been identified. Some
issues may not be a problem for the author - for example a reference to
an external document whose name has not been given (href="?...") which is
purely a placeholder until the document exists. Some messages will indicate
more serious problems. Authors should read the messages that are presented
to ensure they understand any issues that the transformation has raised.

When locating faults, the transformation will display an XPath like description
of the fault location. This can take one of two forms (depending on the
configuration of the stylesheet). The first of these forms is the simple
index form, for example :

Message definition for Window_Info not found at
   /riscos-prm/chapter/section[2]/subsection[2]/subsubsection[3]/category[5]/p/list/item[3]/reference.

This form indicates the relative position of elements within the document,
whilst retaining the names of the elements and is quite compact. The
alternate, and default, form of describing the position is more verbose :

Message definition for Window_Info not found at
   /
   riscos-prm/
   chapter[@title='Pinboard']/
   section[@title='Technical details']/
   subsection[@title='The iconise protocol']/
   subsubsection[@title='Shift held down when the close tool of a window is clicked']/
   category[@title='New application']/
   p/
   list/
   item[3]/
   reference[@name='Window_Info'].

This form splits across multiple lines for clarity, but provides a more
human-readable description of the location of the fault.

For further information on fault-finding, see the section on 'Finding
mistakes'.


Entities
--------
The DTD describes a number of entities which should be used within the PRM
documentation. The DTD will contain the most up-to-date examples of entities
that are required. It is expected that the list of entities expected in this
file be expanded with time, and as they are found to be necessary.

Some of the entities that can be used are :

        no-breaking space, for keeping words together.
   ×   multiplication symbol. Do not use 'x'.
   &ne;      not equal. Do not use '!=' or '<>'
   &equiv;   equivalence. Try to get the difference between equality and
             equivalence correct.
   &le;      less than, or equal to. Do not use '<='.
   &ge;      greater than, or equal to. Do not use '>='.
   &micro;   micro symbol (u with a stick). Do not use 'u'.
   &implies; implies symbol (rightward arrow, generally). Try to avoid if
             possible. Symbols are less obvious than words.
   &hex;     hex value follows. Try not to use &amp; to precede hex symbols
             as this ties the output to RISC OS. Changing the definition
             of &hex; should be all that is required to change the indicator
             of a hex constant from & to 0x, or 16_ or some similar prefix.
             This precludes the use of H suffixed, but we'll just suffer
             that.
   &lsl;     logical shift left (bitwise)
   &lsr;     logical shift right (bitwise)
   &asr;     arithmetic shift right (bitwise, sign extending)

If you require some other entities, please contact me at gerph@gerph.org
and I'll decide whether it might be better to represent things with a
different form or to accept the entity. Most of the time text is
sufficient, but for certain applications this will be impossible.


Structural elements
-------------------
The PRMs have a number of structural elements which provide the basic
framework upon which the rest of the information exists.

Structurally, the document consists of :

 <riscos-prm>
  <chapter title="Component title">
   <section title="Section title">
    <p />
    <subsection title="SubSection title">
     <p />
     <subsubsection title="SubSubSection title">
      <p />
      <category title="Category title">
       <p />
      </category>
     </subsubsection>
    </subsection>
   <section>
  <chapter>

  <meta>
   <maintainer>
    <email name="someone" address="a@b.c" />
   </maintainer>
   <disclaimer>
    <p />
   </disclaimer>
   <history>
    <revision number="1" author="initials" title="Release name">
     <change>Description</change>
    </revision>
   </history>
   <related>
    <reference type="document" href="file" name="Document title">
   </related>
  </meta>
 </riscos-prm>

Element:    riscos-prm
Attributes: (none)
Children:   (chapter*), meta

The riscos-prm element is the top level element, within which other PRM
elements are contained.


Element:    chapter
Attributes: title, docgroup, docgroup-part
Children:   section*

The chapter equates to a chapter in the PRMs. The 'title' attribute should
be set to the title of the chapter. This is usually the component name, for
example 'Window Manager', 'ChangeFSI'. Whilst multiple chapters can be held
in a single file, it is expected that usually only a single chapter will be
held in the file at any one time.

The 'docgroup' may be set to some prefix that declares the category of
the documentation. By default, this is set to "RISC OS Programmers
Reference Manuals". Because of the diversity of the documentation that may
be produced, this value can be modified to suit the class being documented.
Examples of documentation groups might be :

  Network Protocols
  Zap Developer Documentation
  Bogons Ltd Internal Documentation

The 'docgroup-part' is used to separate groups of documentation, such as
by volumes. For example this might be set to 'III' for the 3rd volume of
the documentation. By default, this is an empty string, which removes any
sequence number.


Element:    section
Attributes: title
Children:   (p | subsection | category | %apis;)*

The section equates to the 'new page and large heading' in the PRMs. The
'title' attribute should be set to the title of the section. Usually
sections are given in the order :

  Introduction
    - a brief introduction to what the component does

  Overview      (sometimes these are joined to make Introduction and
                 Overview)
    - an overview of how the component is viewed by the outside world;
      what it does and the manner in which it does it.

  Terminology
    - any terminology specific to this chapter which is assumed knowledge
      for readers. Most components do not require the terms to be defined.

  Technical details
    - technical details about how to operate the component; this is usually
      the largest section and fleshes out the summaries described above
      and in the following sections with the 'whys', the 'hows' and the
      specifics on the usage.

  VDU codes
    - lists the VDU codes, using vdu-definition, which are provided by
      this component.

  System variables
    - lists the system variables, using sysvar-definition, which are used
      by this component.

  Service calls
    - lists the service calls, using service-definition, which are defined
      or used by this component.

  SWI calls
    - lists the SWI calls, using swi-definition, which are defined or used
      by this component.

  Software vectors
    - lists the vector calls, using vector-definition, which are defined or
      used by this component.

  UpCalls
    - lists the UpCalls, using upcall-definition, which are generated by
      this component.

  Entry points
    - lists the Entry-points, using entry-definition, which are used by
      this component. These would usually describe the entry points of
      functions registered with your component.

  Error messages
    - lists the errors, using error-definition, which are reported by this
      component.

  Wimp messages
    - lists the Wimp messages, using message-definition, which are generated
      or received by this component.

  Toolbox methods
    - method calls for Toolbox components, described using
      tboxmethod-definition.

  Toolbox events
    - events generated by Toolbox components, described using
      tboxmessage-definition. The element name reflects the derivation (both
      in implementation and documentation from the message-definition block,
      rather than the more usually documented term 'event'.

  *Commands
    - lists the CLI commands, using command-definition, which are provided
      by this component.

  Examples
    - any long examples which describe the overall use of the components
      APIs

This does not preclude the use of any other order or sections being added,
but is a helpful convention to follow.


Element:    subsection
Attributes: title
Children:   (p | subsubsection | category)*

The subsection equates to the 'left of the page heading' in the PRMs. The
'title' attribute should be set to the title of the subsection. A subsection
describes something within the section, breaking it down into smaller
chunks. Examples of subsections (given for the 'Technical details' section)
might be 'Implementation', 'Interaction with xxx', 'Data formats', etc.


Element:    subsubsection
Attributes: title
Children:   (p | category)*

The subsubsection equates to the 'half indented headings' in the PRMs. Like
the subsection within a section, these describe something within a
subsection, breaking it into smaller chunks. An example of a subsubsection
might be individual data block descriptions within a 'Data formats'
subsection.


Element:    category
Attributes: title
Children:   (p)*

The category equates to the 'text level heading' in the PRMs. A category
does not truly equate to a subsubsubsection, but is intended to be used to
provide a distinction between different descriptions within the body of
the text. Categories tend to be used to describe alternate operation under
different circumstances, or to further describe particular features
which would be cumbersome to explain in the middle of a body of text;
for example, to define a term and provide examples - this allows it to be
found more easily via the contents page.


Element:    p
Attributes: <none>
Children:   (<many>)*

The p equates to a paragraph in the PRMs. It is used as the primary
descriptive block. In some cases it is also used as the holder for alternate
meanings, but these will be described where necessary.


Element:    meta
Attributes: <none>
Children:   (maintainer | history | disclaimer | related)*

The meta element describes meta-information about the document itself.
Metadata must be included at the end of the document, and should provide
sufficient detail about the document to describe what it's for and its
lineage. It must also describe who to contact about the document.


Document metadata
-----------------

Document metadata, held within the 'meta' element must be present within
the document to provide general information about the document itself.
It is very important that this section be kept up to date, particularly
with reference to the history of the document and the maintainers contact
details.

Metadata will usually be presented by the stylesheet at the bottom of the
document (or on a separate page, if the stylesheet allows this). This
ensures that is it easily accessible, without distracting from the content
of the document.


Element:    maintainer
Attributes: <none>
Children:   email*

The maintainer provides information on who maintains the document and should
be contacted for details about it. More than one maintainer may be provided,
where the document has been designed by, or is maintained by, more than one
person.


Element:    history
Attributes: <none>
Children:   revision*

The history provides information about the development of the document,
allowing users of the document to identify differences between different
documents without having to manually check for every change.


Element:    revision
Attributes: number, date, author, title
Children:   change*

number: describes the revision number of the document; these should be
        in increasing value, and will usually be numeric. An alphabetic
        character may be appended to indicate a minor revision whilst a
        work is in progress.
date: may optionally provide a date on which the revision was made, in
      the form 'dd mmm yyyy'.
author: should be the authors initials - the entity releasing the revision
        should be given here
title: may optionally provide a title for the change. This should only
       be provided where there is a distinct name for the release of
       the documentation; for example, it may coincide with a component
       release, in which case it should be appropriately named.
       Intermediate changes will probably not require a title.

The revision element marks a major revision of the document. Each revision
indicates a distinct version of the document. Whilst earlier revisions need
not be kept by the maintainers, the revision history indicates the changes
that have taken place, thus allowing readers of the document to be aware of
the changes between those revisions.


Element:    change
Attributes: <none>
Children:   <text>

The change element describes an individual change of the document. Multiple
changes will usually apply to a single revision. It is expected that a
sentence or paragraph be used to describe the change. Examples of such
changes might be 'Updates Toaster_Heat API to include a flags word' or
'Removed restriction in the section documenting buffers that users of the
buffer hold their breath whilst the operations are performed. This was
resulting in the death of too many programmers during development'. Both API
and documentation changes should be noted within the change element.

Remember, the only indication of how things have developed is this record.
If something important is modified, and users of the document must be very
aware of the change, then drawing attention to it within the change element
is vital.


Element:    disclaimer
Attributes: <none>
Children:   (<many>)*

The disclaimer element provides a block of text where copyright
information, trademark acknowledgements, and statements of rights may
be made. You should ensure that all relevant information is included here.


References
----------

References are a means of linking one section of the document to another.
They can exist between local and external sections of documents. Because
the references need to refer to particular instances within the document
regularly, a 'type' is provided to indicate the object being referred to.
This will usually modify the manner in which the reference is presented,
although the methods used by the HTML transformation are preferred for
consistency.


Element:    reference
Attributes: type, href, name, reason, use-description
Children:   <text>?

type: may be one of :
       link - an external link, given by 'href', with its description
              as 'name'. The link will not be interpreted by the stylesheet
              and may be any URI.
       swi  - a reference to a SWI whose name (and possibly reason code)
              is given by 'name' and 'reason'.
       sysvar - a reference to a System variable given by 'name'.
       command - a reference to a *Command, given by 'name'.
       vector - a reference to a Vector, given by 'name' and possibly
              'reason'.
       upcall - a reference to an UpCall, given by 'name' and possibly
              'reason'.
       service - a reference to a Service call, given by 'name' and
              possibly 'reason'.
       entry - a reference to an Entry point, given by 'name' and
              possibly 'reason'.
       message - a reference to a Wimp Message, given by 'name' and
              possibly 'reason'.
       document - a reference to a document, given by 'href', with its
              description as 'name'. The document referenced should
              not include any extension; one will be added by the
              stylesheet should it be necessary.
       error - a reference to an error message, given by 'name'
       tboxmessage - a reference to a Toolbox message
       tboxmethod - a reference to a Toolbox method
       chapter - a reference to a chapter element, given by the 'title'.
       section - a reference to a section element, given by the 'title'.
       subsection - a reference to a subsection element, given by the 'title'.
       subsubsection - a reference to a subsection element, given by the 'title'.
       category - a reference to a subsection element, given by the 'title'.
name: describes the thing referred to (for non-link elements).
reason: describes a reason code on the referenced section (for non-link
        elements)
use-description: may be one of :
       yes  - If the referenced element exists locally, then the link text
              will be the description as given in the definition. This does
              not apply to 'link' type references.
href: should point to the document referenced, if the reference is external.
      If the reference is external, but no external document is known to
      exist for it to point to, the href '?' should be used as the first
      character to allow easy searching for these - this will be relied on
      in the XSLT for providing warnings.

References may have content if they wish to override the default link
text associated with the element type being referenced. Where possible,
the stylesheet may warn over the bad use of references.

A failed reference may raise a warning on the console. This takes the form
of the path through the document to reach the faulty element. An example
might be :

SWI definition for CompressJPEG_WriteLiner not found at
   /riscos-prm/chapter/section/p[4]/reference[2].

This means that there is a reference to CompressJPEG_WriteLiner for which
no corresponding local definition exists. To find the element, you start
at the root of the document and step through :

* Find the first root riscos-prm element.
* Inside this, find the 1st element; this is a chapter.
* Inside this, find the 1st element; this is a section.
* Inside this, find the 4th element; this is a p.
* Inside this, find the 2nd element; this is a reference.
* This is the faulty element.


Document inclusion
------------------

Under some circumstances, references to other documents are unsuitable, and
the document needs to include information from another in its own body.
Rather than duplicating the information within the document, the import
element gives an opportunity to import elements from elsewhere.

The primary uses for this kind of import would be to provide an amalgamated
document, comprising different sections from related documents, or to
produce a different view on to the document.


Element:    import
Attributes: document, path
Children:   <none>

document: path to the document being included, relative to the current
          document.
path:     XPath string describing the nodes to be imported

Imported elements can be used in many different places within the document
structure. This allows much greater freedom in producing documents than the
plain XML-based structure. You should use import with extreme care and only
to reconstruct documents, not as a matter of course.


Linking to external resources
-----------------------------

At present only one external resource is explicitly given; that of an email
reference.

Element:    email
Attributes: name, address
Children:   <none>

name: optional (but recommended) name of the recipient.
address: email address to send to.

The Email element provides a means for contacting people.


Technical elements
------------------

There are a number of elements that may be used within a normal body of
text to indicate a technical feature or instance. Examples of these are
file names, replaceable text, and system variables.


Element:    userinput
Attributes: <none>
Children:   (<text> | userreplace)*

User input is something that the user might give, by way of a short example
which is not a fully formed example.


Element:    userreplace
Attributes: <none>
Children:   <text>

The userreplace is represented in the PRMs by italic text. This element
describes something that the user is expected to replace with something else,
or is variable.
Example: <userreplace>FileSystem</userreplace>_DiscOp


Element:    systemoutput
Attributes: <none>
Children:   (<text> | userreplace)*

The systemoutput is represented in the PRMs by typewriter text. This element
describes the output from the system, usually in response to *Commands or
other command-like user interaction.


Element:    menuoption
Attributes: <none>
Children:   (<text> | userreplace)*

The menuoption is not represented in the PRMs. This element describes a
menu option. Its representation in a transformation is undefined; it may be
used only as an indexing entry.


Element:    actionbutton
Attributes: <none>
Children:   (<text>)*

The actionbutton is not represented in the PRMs. This element describes a
button in the interface. Its representation in a transformation is undefined;
it may be used only as an indexing entry.


Element:    filename
Attributes: type
Children:   (<text> | userreplace)*

type: (optional) type of filename represented:
          riscos - a RISC OS filename (default)
          windows - a Windows filename
          unix - a Unix (POSIX) filename
          uri - a URI

The filename is usually represented in the PRMs by typewriter text. This
element describes a filename which should be, or can be, supplied to the
system. Because filenames may be transferred from different systems, and
some filenames may need to be given in alternative formats, the type should
be used to differentiate the semantics of the filename.


Element:    variable
Attributes: <none>
Children:   (<text> | userreplace)*

The variable is usually represented in the PRMs by typewriter text. This
element describes a variable which should be, or can be, supplied to the
system.


Element:    command
Attributes: <none>
Children:   (<text> | userreplace)*

The command is usually represented in the PRMs by typewriter text. This
element describes a command that might be issued by the user, or programmer.


Element:    function
Attributes: <none>
Children:   (<text> | userreplace)*

The function is usually represented in the PRMs by typewriter text. This
element describes a command that might be issued by a programmer in a
programming language, including C, BASIC, Pascal or Assembler. The
distinction between function and routine is not made by this element -
a PROC in basic will be referenced as a function.


Element:    code
Attributes: type
Children:   (<text> | userreplace | br)*

type: the type of the code which is described, which may be one of :
          c - C code
          basic - BASIC code
          asm - assembler code
          format - a file format
          pseudo - pseudocode in no particular language

The code element is usually represented in the PRMs by typewriter text.
This element describes a section of code which can be used to provide
a particular function either as an example or as a means of describing
file formats. This element is recommended for example code sections
for single-line or simple examples.


Element:    extended-example
Attributes: type
Children:   <text>*

type: the type of the code which is described, which may be one of :
          c - C code
          basic - BASIC code
          asm - assembler code
          format - a file format
          pseudo - pseudocode in no particular language

The extended-example element is usually represented in the PRMs by a block
of typewriter text which may be a code fragment.
This element describes a section of code which can be used to provide
a particular function either as an example or as a means of describing
file formats. This element is recommended for example code sections
for multi-line examples, where pre-formatted text is expected.


Element:    sysvar
Attributes: <none>
Children:   (<text> | userreplace)*

The sysvar is usually represented in the PRMs by typewriter text. This
element describes a system variable. Where the system variable can be
indexed, we recommend you use <reference type="sysvar" ...>.


Element:    input
Attributes: <none>
Children:   (key | mouse)*

The input element contains a sequence of input device actions. The two
input device actions currently supported, key and mouse, may be placed
within this element to describe an actions sequence.


Element:    key
Attributes: name, repeat, action
Children:   <none>

name: the name of the keyboard button which is being activated. The
      standard named keys may be used, in lower case. Regular keys
      may also be used but will not be translated to the presentation
      format. Standard key names:
        shift       ctrl        alt         meta        fn
        up          down        left        right       pageup
        pagedown    backspace   tab         return      escape
        enter       insert      delete      home        end
        copy        print       break       capslock    scrolllock
        numlock     space
        f1          f2          f3          f4          f5
        f6          f7          f8          f9          f10
        f11         f12
repeat: number of repetitions, which may be 1 (the default), 2, 3 or
      4. Higher numbers of repetitions should be explained manually.
action: the action which the user performs. Named actions should be
      used:
        click       press       release     hold

The key element is used to represent a key action (such as a key
press and release) which is performed by the user. The keys are given
standard names so that they may be transformed appropriately by
stylesheets for a given presentational style. Capitalised strings
should be used for the names of special buttons, or standard letter
keys.


Element:    mouse
Attributes: name, repeat, action
Children:   <none>

name: the name of the mouse input which is being activated. The
      standard named buttons may be used, in lower case. Additional
      buttons should be described in upper case. Standard button
      names:
        select      menu        adjust
        scrollwheel
repeat: number of repetitions, which may be 1 (the default), 2, 3 or
      4. Higher numbers of repetitions should be explained manually.
action: the action which the user performs. Named actions should be
      used:
        click       press       release     hold        drag
        up          down        left        right

The mouse element is used to present a mouse action which is being
performed by the user. The standard RISC OS names should be used
where possible - the physical position of the buttons should only
be used when describing a translation between other operating
systems and uses, or the specific behaviour of a given mouse
driver.

The scrollwheel name is intended for use when describing the actions
of the scroll wheel which may be horizontal or vertical. The actions
should be the direction that the scroll wheel is moved.


Data structures
---------------

There are a few types of data structures provided by this definition. These
are the 'bitfield-table', 'value-table', 'offset-table', 'message-table'
and 'definition-table'.
These are grouped into table/value pairs :

  bitfield-table & bit
  value-table & value
  offset-table & offset
  message-table & message
  definition-table & definition
  version-table & version

message-tables are solely for use within descriptions of Wimp message
blocks.

value-tables are intended for numeric data, whilst definition-tables are
indented for textual definitions.

version-tables are for describing compatibility and differences in
behaviour between versions of a component or protocol.


Element:    bitfield-table
Attributes: <none>
Children:   (bit)*

The bitfield element is conventionally represented as a table of bits and
their meanings. Usually the table is headed by 'Bit' and 'Meaning if set'
(and possibly 'name' where name values are given). If the bits within the
table have 'state' elements then the 'Meaning if set' title changes to
'Meaning'. You should format your descriptions accordingly.


Element:    bit
Attributes: number, name, state
Children:   <text>

number: the number of the bits, or a range of bits separated by a hyphen.
name: (optional) a name to assign to this bit (or range of bits).
state: (optional) describes the state of the bit. There are a few ways
       to use this :
         content  : the default, refers to the content as being the only
                    information for this bit
         set      : the content describes the meaning if the bit is set
         clear    : the content describes the meaning if the bit is unset
         reserved : this bit is reserved and must be zero.

A bit is an element of a bitfield-table, describing one or more bits. Usually
it is represented as a component of a table comprising the bit values. The
meaning of the bit is described by the content of the element. The meaning
is implicitly the meaning if that bit is set if none of the bit elements
have a 'state' attribute. For a range of bits it is conventional to provide
a value-table, or describe the meaning within the body of the description.


Element:    value-table
Attributes: head-number, head-name, head-value
Children:   (value)*

head-number: (optional) a heading for the number field
head-name: (optional) a heading for the name field
head-value: (optional) a heading for the value field (the body of the
            element)

The value-table element is conventionally represented as a table of values
and their meanings. Usually the table is headed by 'value' and 'meaning'
(and possibly 'name' where name values are given). Where heading values are
given, these will be used to provide further indication of the fields.
Whilst it is possible to subvert the meaning of the value-table by changing
these headings, this should only be done with care.


Element:    value
Attributes: number, name
Children:   <text>

number: the value, or a range of values separated by a hyphen.
name: (optional) a name to assign to this value (or range of values).

A value is an element of a value-table, describing the meaning of one or
more values. Usually it is represented as a component of a table comprising
the values. The meaning of the value is described by the content of the
element.


Element:    offset-table
Attributes: head-number, head-name, head-data-size, head-value
Children:   (offset)*

head-number: (optional) a heading for the number field
head-name: (optional) a heading for the name field
head-data-size: (optional) a heading for the data-size field
head-value: (optional) a heading for the value field (the body of the
            element)

The offset-table element is conventionally represented as a table of offsets
and their meanings. Usually the table is headed by 'offset' and 'contents'.
There may also be columns to name the offset, and to give the size of the data.
Where heading values are given, these will be used to provide further
indication of the fields.
Whilst it is possible to subvert the meaning of the offset-table by changing
these headings, this should only be done with care.


Element:    offset
Attributes: number, data-size, name, state
Children:   <text>

number: the offset, or a range of offsets separated by a hyphen.
name: (optional) a name to assign to this offset (or range of offsets).
data-size: (optional) a width to use for the field, in bytes.
state: (optional) describes the state of the field. There are a few ways
       to use this :
         content  : the default, refers to the content as being the only
                    information for this field
         reserved : this field is reserved and must be zero
         undefined : this field is undefined and its value is should not
                     be interpreted

An offset is an element of a offset-table, describing the meaning of one or
more offsets into a structure. Usually it is represented as a component of a
table comprising the structure offsets. The meaning of the offset is
described by the content of the element. In the translated version, offsets
will always be described preceded by a '+' symbol to indicate that they
are offsets.


Element:    message-table
Attributes: <none>
Children:   (message)*

The message-table element is conventionally represented as a table of
offsets into a message block and their meanings. The table is headed by
'offset' and 'contents'.


Element:    message
Attributes: offset, data-size, name, state
Children:   <text>

offset: the offset, or a range of offsets separated by a hyphen.
name: (optional) a name to assign to this offset (or range of offsets).
data-size: (optional) a width to use for the field, in bytes.
state: (optional) describes the state of the field. There are a few ways
       to use this :
         content  : the default, refers to the content as being the only
                    information for this field
         reserved : this field is reserved and must be zero
         undefined : this field is undefined and its value is should not
                     be interpreted

A message is an element of a message-table, describing the meaning of one or
more offsets into a message block. Usually it is represented as a component
of a table comprising the message block. The meaning of the offset is
described by the content of the element. In the translated version, offsets
will always be described preceded by 'R1+' to indicate that they are from
the message block pointer in register 1 (as supplied to
Wimp_SendMessage/Wimp_Poll[Idle])


Element:    definition-table
Attributes: head-name, head-extra, head-value
Children:   (value)*

head-name: (optional) a heading for the number field
head-exra: (optional, but recommended) a heading for the extra field
head-value: (optional) a heading for the value field (the body of the
            element)

The definition-table element is conventionally represented as a table of
textual definitions. Usually the table is headed by 'name' and 'meaning'
(and possibly 'extra' when an extra field is supplied). Where heading
values are given, these will be used to provide further indication of
the fields. The definition-table is intended to make it possible to
describe terms and labels, whilst the value-table is intended for numbers.


Element:    definition
Attributes: name, extra
Children:   <text>

name: the textual string being defined
extra: (optional) an additional field if required in the table

A definition is an element of a definition-table, describing the meaning
of one or more terms. Usually it is represented as a component of a
table comprising the definitions. The meaning of the definition is
described by the content of the element.


Element:    version-table
Attributes: <none>
Children:   (version)*

The version-table element is represented as a set of rows describing
the differences between different versions of a component or protocol.
Unlike the other tables above, this information is not (in the standard
layout) presented as tabular data, but as an indented list.


Element:    version
Attributes: module-name, module-lt, module-eq, module-ge,
            riscos-lt, riscos-eq, riscos-ge,
            supplier, hardware, architecture,
            state

module-name: (optional) The name of a module within which this version applies
            (defaults to not saying the module, assumed to be the one
            documented in the chapter)
module-lt: (optional) The documentation details versions up to the version
            given.
module-eq: (optional) The documentation details an explicit version.
module-ge: (optional) The documentation details versions after the version given.
riscos-lt: (optional) The documentation details versions of the OS up to the
            version given.
riscos-eq: (optional) The documentation details an explicit version of the OS.
riscos-ge: (optional) The documentation details versions of the OS after the
            version given.
supplier: (optional) Qualifies the supplier of the component (RISC OS/module).
            For example, to discuss RISC OS Ltd versions, RISC OS Open versions,
            RISC OS Direct versions (for the OS), or the supplier of a module
            as might be the case for different hardware manufacturers of some
            modules (like Joystick).
hardware: (optional) Qualifies the behaviour on specific hardware.
architecture: (optional) Describes the processor architectures to which it
            applies (defaulting to AArch32) as a comma separated list of
            aarch32, aarch64, x64.
state: 'supported', 'unsupported' or 'content' ('content' is the default
            and includes any child content)

The version element describes the compatibility of a component, API or
protocol in different versions. The attributes of the element differentiate
which version the description applies. There are 5 dimensions in which
the version may be differentiated:

    module - differentiating a given module by version (giving its name,
            and bounds for the version.
    riscos - differentiating by the version of the operating system.
    supplier - differentiating by the supplier of a module, OS, or hardware.
    hardware - differentiating by the type of hardware.
    architecture - differentiating by the CPU architecture.

The 'state' may be stated as simply 'supported' or 'unsupported' to give
a simple statement of the support of the feature. If these are not used,
the content describing the compatibility will be taken from the child
elements.


API definitions
---------------

There are a number of different API descriptions for which templates are
provided within the documentation format. These are the commonly used
definition types that comprise most of the PRMs themselves :

  swi-definition
  entry-definition
  service-definition
  upcall-definition
  command-definition
  sysvar-definition
  message-definition
  vector-definition
  error-definition
  vdu-definition
  tboxmessage-definition
  tboxmethod-definition

Each of these has their own particular stylisation of the template which
the PRMs provide.


Element:    swi-definition
Attributes: name, number, offset, offset-base, reason, reasonname,
            description, internal, irqs, fiqs, processor-mode, re-entrant
Children:   (entry?, exit?, use, (example)*, declaration?, related?)

name: the full name of this SWI; for example 'OS_Module'
number: (optional) the number of this SWI in hex
offset: (optional) the offset of this SWI from a given base
offset-base: (optional) the name of base for this SWI offset
reason: (optional) the reason code for this SWI in decimal.
        If a sub-reason code is required, it should be separated with a
        comma; for example '127,1'
reasonname: (optional) the name of this reason code as a capitalised name,
       without spaces; for example 'FreeBlock'
description: one sentence description of the function provided by this SWI
internal: 'yes' if this is an internal SWI (all other content will be
          ignored)
irqs: state of IRQs during this call, usually 'enabled', 'disabled', or
      'undefined'
fiqs: state of FIQs during this call, usually 'enabled', 'disabled', or
      'undefined'
processor-mode: processor mode for the duration of this call, 'SVC', 'USR'
      or 'undefined'
re-entrant: whether this call is re-entrant or not, 'undefined', 'yes',
      or 'no'

The swi-definition is one of the most important structures in the entire
PRM. Within the PRMs these are laid out on a new page, with the name and
number usually aligned to the top right. Headed sections indicate the
conditions on entry, exit and during the call.

The name and number are used as references where such information can be
given (for example in index or content pages). The reason and reasonname
allow the definition to be split into multiple entries, each describing a
particular reason code of a call. It is expected that reasonname and the swi
name should be usable as symbol names in a language, so their use is
restricted to names without spaces, usually capitalised to indicate word
breaks, and succinctly named to provide a simple to remember and type symbol.

The SWI definition may be given as an offset, and an offset-base. This is
useful when a collection of SWIs are defined which have a common base,
as is the case with the DCI Drivers.

The provision for internal SWIs is important. Whilst the full XML
documentation may be publicly available and therefore any API you 'hide'
within a call marked as internal is actually available to all, it is very
important that such calls are correctly marked. Internal calls are not
to be relied on; they can and will change without notice and may even
change in their purpose. The internal marker explicitly declares this fact
to the world. Anyone using them runs the same risk they would using
undocumented calls, even though the API might actually be documented.

If a call takes a number of different reason codes it is usual to give each
of the reason codes in a value-table within the entry element and provide
references to each of the reasons with a 'use-description' reference.


Element:    entry
Attributes: <none>
Children:   (register-use | processor-flag)*

The entry element is a headed element containing descriptions of the content
of registers on entry to the call it exists in.


Element:    exit
Attributes: <none>
Children:   (register-use | processor-flag)*

The exit element is a headed element containing descriptions of the content
of registers on exit from the call it exists in.


Element:    register-use
Attributes: number, state
Children:   <text>

number: register number being described
state: (optional) describes the state of the register, for exit contexts
       'preserved', 'corrupted', 'undefined' or 'content'. If unset or
       'content' is used, the content of this element is used.

The register-use element is used to describe a register (or group of
registers). Where a register may take a number of values, it is conventional
to provide a value-table, or a bitfield-table. Where a structure is used,
it is conventional to refer back to a table described in the Technical
Details section.


Element:    processor-flag
Attributes: name, state
Children:   <text>

name: the processor flag (N, C, V or Z) being described
state: (optional) describes the state of the register, for exit contexts
       'preserved', 'corrupted', 'undefined' or 'content'. If unset or
       'content' is used, the content of this element is used.

The processor-flag element is used to describe the state of a processor
flag, usually on exit from a call. The most common use for this will be
to indicate flag states on exit that are relevant, or the explicit
corruption of flags on return.


Element:    use
Attributes: <none>
Children:   <text>

The use element describes how the definition functions, its effect and any
other details relevant to its use which are not part of the overall component
structure as described in the Technical details.


Element:    compatibility
Attributes: <none>
Children:   <version>*

The compatibility element describes the support of the definition within
different versions. It is equivalent to the version-table element, but as
an explicit section within the API definition.


Element:    example
Attributes: <none>
Children:   (p | command | systemoutput | br)*

definition. The element can be repeated within the definition to give
multiple unrelated examples.

use the definition.


Element:    declaration
Attributes: type
Children:   (code | extended-example)*

      'prototype' - should be used for C prototypes for functions
      'structure' - should be used for C structure declarations



Element:    related
Attributes: <none>
Children:   (reference)*

The related element generally lives at the bottom of the page of a
definition, providing links to other APIs which may help in the
understanding or use of this element.

Within the PRMs only three types of related API were generally provided, but
within this description format we expect much greater degree of
cross-referencing. Any of the reference types may be used within the related
section to provide links.


Element:    vector-definition
Attributes: name, number, reason, reasonname,
            description, internal, irqs, fiqs, processor-mode, re-entrant
Children:   (entry?, exit?, use, compatibility?, declaration?, (example)*, related?)

name: the full name of this vector; for example 'ColourV'
number: the number of this vector in hex
reason: (optional) the reason code for this vector in decimal.
        If a sub-reason code is required, it should be separated with a
        comma; for example '127,1'
reasonname: (optional) the name of this reason code as a capitalised name
      without spaces; for example 'OutputBufferEmpty'
description: one sentence description of the function provided by this
             vector
internal: 'yes' if this is an internal vector (all other content will be
          ignored)
irqs: state of IRQs during this call, usually 'enabled', 'disabled', or
      'undefined'
fiqs: state of FIQs during this call, usually 'enabled', 'disabled', or
      'undefined'
processor-mode: processor mode for the duration of this call, 'SVC', 'USR',
      'IRQ' or 'undefined'
re-entrant: whether this call is re-entrant or not, 'undefined', 'yes',
      or 'no'

The vector definition follows the same semantics as the SWI definition. It
is used to describe the standard RISC OS vectors.


Element:    entry-definition
Attributes: name, number, reason, reasonname,
            description, internal, irqs, fiqs, processor-mode, re-entrant
Children:   (entry?, exit?, use, compatibility?, declaration?, (example)*, related)

name: the full name of this code; for example 'FileEntry_MiscOp'
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this entry point in decimal.
reasonname: (optional) the name of this reason code as a capitalised name
      without spaces; for example 'MountAlienSpaceship'
description: one sentence description of the function provided by this
             code
internal: 'yes' if this is an internal entry (all other content will be
          ignored)
irqs: state of IRQs during this call, usually 'enabled', 'disabled', or
      'undefined'
fiqs: state of FIQs during this call, usually 'enabled', 'disabled', or
      'undefined'
processor-mode: processor mode for the duration of this call, 'SVC', 'USR'
      or 'undefined'
re-entrant: whether this call is re-entrant or not, 'undefined', 'yes',
      or 'no'

The entry definition follows the same semantics as the SWI definition. It is
used to declare entry points for routines registered with your component,
such as callbacks.


Element:    service-definition
Attributes: name, number, reason, reasonname,
            description, internal
Children:   (entry, exit, use, compatibility?, declaration?, (example)*, related)

name: the name of this service; for example 'ShutDown'
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this service in decimal.
        If a sub-reason code is required, it should be separated with a
        comma; for example '127,1'
reasonname: (optional) the name of this reason code as a capitalised name
            without spaces; for example 'Intialising'
description: one sentence description of the function provided by this
             service
internal: 'yes' if this is an internal service (all other content will be
          ignored)

The service-definition is very similar to the swi-definition but lacks some
of the more extensive options. entry, exit, use and related elements are
exactly as provided by swi-definition. When written, the name is always
prefixed by 'Service_' to indicate its lineage.


Element:    upcall-definition
Attributes: name, number, reason, reasonname,
            description, internal
Children:   (entry, exit, use, compatibility?, declaration?, (example)*, related)

name: the name of this UpCall; for example 'FileModified'
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this entry point in decimal.
        If a sub-reason code is required, it should be separated with a
        comma; for example '127,1'
reasonname: (optional) the name of this reason code as a capitalised name
            without spaces; for example 'Renaming'
description: one sentence description of the function provided by this
             upcall
internal: 'yes' if this is an internal upcall (all other content will be
          ignored)

The upcall-definition is nearly identical to the service-definition. entry,
exit, use and related elements are exactly as provided by
service-definition. When written, the name is always prefixed by 'UpCall_'
to indicate its lineage.


Element:    sysvar-definition
Attributes: name, description
Children:   (use, compatibility?, example?, related)

name: the full name of this system variable; for example 'System$Path'
description: one sentence description of the function provided by this
             system variable

The sysvar-definition is a simplified form of the upcall-definition. use
and related elements are as provided by upcall-definition.


Element:    error-definition
Attributes: number, name, description
Children:   (use, compatibility?, related)

number: the number of this error in hex
name: the symbolic name of this error for example 'BadPathVariable'
description: one sentence description of the function provided by this
             system variable

The error-definition is similar to the sysvar-definition, for describing
errors that may be returned from a call.


Element:    message-definition
Attributes: name, number, description, source, destination,
            recorded, broadcast
Children:   (message-table, use, compatibility?, declaration?, related)

name: the name of this message; for example 'DataOpen'
description: one sentence description of the function provided by this
             message
source: the name of the task, or group of tasks that send this message,
        with * meaning 'all'. If omitted, no reference will be given.
destination: the name of the task, or group of tasks that receives this
             message, with '*' meaning all. If omitted, no reference will
             be given.
broadcast: whether the message should be broadcast or not. Takes the
           values :
              'may' - the message can be broadcast or sent directly
              'must' - the message must be broadcast
              'never' - the message should never be broadcast
           The default if no value is specified is 'never'.
recorded: whether the message should be sent recorded delivery. Takes
          the values :
              'may' - the message can be send recorded (18) or normally (17)
              'must' - the message must be sent recorded (18)
              'never' - the message must only be sent normally (17)
          The default if no value is specified is 'never'.

The message-definition is an extended form the sysvar-definition. use
and related elements are as provided by sysvar-definition. The message-table
element is described in the Data structures section.


Element:    tboxmessage-definition
Attributes: name, number, description
Children:   (message-table, use, compatibility?, declaration?, related)

name: the name of this message; for example 'ColourMenu_HasBeenHidden'
description: one sentence description of the function provided by this
             message

The tbox-message-definition is a restricted form of the message-definition.
The source and destination make no sense and have been removed - the source
is always the Toolbox and the destination is always your task.


Element:    tboxmethod-definition
Attributes: name, number, reason, reasonname,
            description, internal
Children:   (entry, exit, use, declaration?, (example)*, related)

name: the name of this service; for example 'ColourMenu_SetTitle'
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this toolbox method in decimal.
reasonname: (optional) the name of this reason code as a capitalised name
            without spaces; for example 'Intialising'
description: one sentence description of the function provided by this
             service
internal: 'yes' if this is an internal service (all other content will be
          ignored)

The tboxmethod-definition is very similar to the service-definition.


Element:    command-definition
Attributes: name, description
Children:   ((syntax)*, (parameter)*, use, compatibility?, (example)*, related)

name: the name of this command; for example 'DataOpen'
description: one sentence description of the function provided by this
             command

The command-definition is similar to the sysvar-definition, but with some
extra elements to describe the particular format of this command. The command
name will always have a * prefix added to it.



Element:    vdu-definition
Attributes: name, number, description
Children:   ((syntax)*, (parameter)*, use, compatibility?, (example)*, related)

name: the name of this command; for example DataOpen
description: one sentence description of the function provided by this
             command

The vdu-definition is similar to the command-definition, but with an extra
value for the number of the call. The command name will always have a 'VDU'
prefix added to it.


Element:    syntax
Attributes: <none>
Children:   (switch | optional | alternates | text | userreplace)*

The syntax element describes the syntax of the *Command, giving a breakdown
of the syntax. If the syntax cannot be described in a single example,
multiple syntax blocks may be supplied.

In 1.02, the syntax for vdu-definitions had to be prefixed by the VDU number.
In 1.03, the syntax for vdu-definitions only documents the additional parameters.


Element:    switch
Attributes: name
Children:   (userreplace)*

name: name of the switch

The switch element allows you to introduce a switch to the syntax of a
command. If the element is empty, no associated parameter is expected.
If the element contains a name, this is used as the parameter name. The
switch is always prefixed by '-'.

Note: Aliases for switches are given in the 'parameter' element.


Element:    optional
Attributes: alternates
Children:   (alternates | switch | userreplace | text)*

alternates: (optional) 'true' if the content of this element are mutually
            exclusive alternates.

The optional element indicates that its contents are not required, but that
they can be omitted from the command.


Element:    alternates
Children:   (optional | switch | userreplace | text)*

The alternates element indicates that the elements within it are mutually
exclusive. This element can be used in a similar way to the
<optional alternates='true'> element, but one of the alternates must be
specified.


Element:    parameter
Attributes: name, switch, switch-alias, label
Children:   <text>

name: (optional) parameter name that we are describing
switch: (optional) switch name associated with this parameter
switch-alias: (optional) alias for the primary switch; usually an
              abbreviated version of the switch
label: (optional) label name associated with this parameter

The parameter element provides an explanation of the use of a particular
parameter to a command. A parameter element should be given for each of the
parameters to a command. Whereas switches are preceded by a '-' character,
labels are not. Labels are discouraged, but certain commands may require the
use of labels rather than switches (for example, IFConfig).


Miscellaneous elements
----------------------

Finally, there are a number of elements which do not fit into the above
categories. These are minor-structural elements, or elements which I am
still unsure about.


Element:    br
Attributes: <none>
Children:   <none>

The br element is equivalent to that in HTML. It provides an immediate line
break. Unlike a paragraph break, this can be used to divide information
which is not strictly part of an ordered list, but needs to be separated.


Element:    image
Attributes: src, type, width, height, caption
Children:   image

src: a relative location of the graphic with any necessary extension
type: the type of graphic being represented - only `png`, `gif, `draw`
      and `svg` are presently defined.
width: the width of the image when displayed (in pixels)
height: the height of the image when displayed (in pixels)
caption: a caption describing the image

The image element refers to a graphical file which cannot be represented
using the current markup. If a particular image type cannot be represented,
the next image type will be used instead. This allows for the
possibility of fall back graphic types. All nested image elements should
represent the same information.


Element:    bnf (namespace: http://gerph.org/dtd/bnf/100/bnf.dtd)
Attributes: caption
Children:   <bnf-elements>

caption: a caption describing the bnf

The bnf element describes the format of a structure in accordance with the
Augmented BNF description presented in RFC2234, transcribed in XML as
documented in the BNF-Structure.txt document. It is used as a namespaced
element, in the form :

<bnf xmlns="http://gerph.org/dtd/bnf/100/bnf.dtd"
     caption="Syntax for BogoMips description Format">
 <rule-def name="thing">
  <rule-use name="other-thing" />
 </rule-def>
</bnf>

Although BNF is in another namespace, and can be re-used externally to
the PRM documentation, this is the expected use of the format.


Element:    strong
Attributes: <none>
Children:   <text>

The strong element provides a strong emphasis. Its use is not defined and
should be avoided where possible.


Element:    sup & sub
Attributes: <none>
Children:   <text>

The sub and sup element provides a means if indicating super- and
sub-script. Be careful when using them.


Element:    list
Attributes: type
Children:   (item)*

type: 'ordered', 'unordered', defaulting to 'unordered'

The list element allows you to build a structured ordered or unordered list
of paragraphs.


Element:    item
Attributes: <none>
Children:   (p)*

The item element allows you to include bulleted entries within a list.


Element:    text
Attributes: <none>
Children:   <none>

The text element has no meaning. It is merely useful to provide a context
around which an alternation may be performed using the optional element on
text values.


Element:    fixme
Attributes: <none>
Children:   <text>?

The fixme element indicates a fault in the documentation that needs
resolving. It may have content describing the fix necessary, or may be
empty to indicate that a general fix is required.


Notes on finding mistakes
-------------------------

In addition to using the tools provided (xsltproc and xmllint) to format and
check the document, you may find the following checks useful in finding
mistakes in the document. It may not always be obvious from the output from
lint where the fault occurs, and knowing these common mistakes can be
useful :

1. Check each tag has a matching tag, either by </tag> or <tag />. If a
   mismatch error occurs, the likeliest cause is a missing end-tag, so if it
   fails this check and there are a sequence of mismatches,

2. Check that there are no <s nested within existing tags. This would
   indicate that there is a missing bracket, i.e.
   <prm-xml <section title="etc">

3. Check that there are an even number of "s in a tag bracket.

4. If a tag bracket has passed the above test, check for the presence of
   equals signs. If you get something like <section title"Hello"> the parser
   should be able to work out that title is a valid attribute, and that a "
   would be expected after the equals sign, so in that context the likeliest
   fault is a missing = sign.


Changes from 1.02 to 1.03
-------------------------
* prm-html5 style sheet now exists, which uses HTML 5 features and CSS for the
  presentation of elements.
* syntax elements on vdu-definition are now expected to document the parameters
  to the definition, not the whole definition. This is in line with the use of
  syntax within the command-definition.
* All code-like and message-like definitions now allow the use of the
  declaration element to describe the declarations in C for that definition.
  Declaration was introduced in 1.02 but not documented.
* input, key and mouse elements are now available, which allow the representation
  of sequences of keyboard and mouse actions.
* actionbutton element added to match the menuoption element.
* offset and message elements now have optional data-size attributes.
  offset-table now allows a head-data-size to describe this column.
* vector-definitions can now have processor mode IRQ.
* systemoutput is now an inline element. In 1.02, the element had been a block
  element, so would start a new line, which was at odds with its description
  and declaration in the DTD. Uses of systemoutput will need to be checked
  carefully to make sure they do not disrupt the formatting of the content.
* Entity &ellipsis; can now be used for a '...' sequence as a character.
* filename elements can now have a type attribute to differentiate the system
  they are used on.
* definition-tables can now be used in place of value-tables, for non-numeric
  definitions.
* offset and message now have a state attribute, to allow them to be marked as
  being undefined or reserved.
* chapter has docgroup and docgroup-part attributes to distinguish the
  document. In 1.02 the docgroup was documented as being present on the
  riscos-prm element, but had always been an attribute of chapter (as doc-group).
* references can now be made to chapter, as well as documents, which may make
  the references read more clearly.
* bit elements which have state and name attributes no longer repeat the attribute
  name if they are identical.
* alternates element added to allow for alternates which are not optional.
* reference SWI elements with generated text will be prefixed by 'SWI'.
* reference elements with explicit text in their body will no longer be
  prefixed (previously would be prefixed by the usual prefixes, like 'UpCall_'.
* image elements are better supported now and allow multiple images to be
  aligned in a row.
* compatibility, version-table and version elements added to provide information
  about the support for given features.
* indexed content now supports cover and front-matter elements.
* processor-flag is now allowed in entry, but this is only for the legacy
  BBC interfaces; it probably shouldn't be used in other interfaces.