                      Structure of PRM documentation (1.00)
                      =====================================

(draft document, updated 28 Apr 2002)

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
translation (HTML).

Within the 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 translation
----------------
The major translation which is performed at present is that of XML to HTML
using XSLT. The translation provided by the HTML is intended to be as close
to that of the PRMs themselves. It should also be degradable to HTML 3. The
major restriction that prevents degradation to HTML 2 is the use of tables
for laying out structural tables.

Whilst the HTML translation is the current reference translation, there is
no reason why other translations, 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 translation 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 place holder 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 translation has raised.

When locating faults, the translation 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, eg :

Message definition for Window_Info not found at
   /riscos-prm/chapter/section[2]/subsection[2]/subsubsection[3]/category[5]/p/list/p[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/
   p[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 :

   &times;   multiplication symbol. Do not use 'x'.
   &ne;      not equal. Do not use '!=' or '<>'
   &equiv;   equivilence. Try to get the difference between equality and
             equivilence corrent.
   &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 preceed 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 preclude 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 and I'll decide
whether it might be better to represent things with a differnt 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" />
   </mainatiner>
   <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: doc-group
Contents:   (chapter*),meta

The riscos-prm element is the top level element, within which everthing else
is contained. 'doc-group' mau 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


Element:    chapter
Attributes: title
Contents:   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.


Element:    section
Attributes: title
Contents:   (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
  
  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.
  
  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.
  
  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.

  Wimp messages
    - lists the Wimp messages, using message-definition, which are generated
      or received by this component.
  
  *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
Contents:   (p | subsubsection | category)*

The section 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
Contents:   (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 SExample of a subsubsection
might be individual data block descriptions within a 'Data formats'
subsection.


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

The category equates to the 'text level heading' in the PRMs. A category
does not truely equate to a subsubsubsection, but is intended to be use to
provide a destinction 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 a particular features 
which it would be clumbersome 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>
Contents:   (<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>
Contents:   (maintainer | history | disclaimer | related)*

The meta element describes meta-information about the document itself.
Meta data 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 meta data
------------------

Document meta data, 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.

Meta data 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>
Contents:   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>
Contents:   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
Contents:   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>
Contents:   <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 documentational 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 elemnt
is vital.


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

The disclaimer element provides an region of text where copyright
information, trademark acknowledgements, and statements of IPR 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 translation are preferred for
consistency.


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

type: may be one of :
       link - an external link
       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'
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
Contains:   <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
Contains:   <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
filenames, replacable text, and system variables.


Element:    userinput
Attributes: <none>
Contains:   (<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>
Contains:   <text>

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


Element:    systemoutput
Attributes: <none>
Contains:   (<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>
Contains:   (<text> | <userreplace>)*

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


Element:    filename
Attributes: <none>
Contains:   (<text> | <userreplace>)*

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.


Element:    command
Attributes: <none>
Contains:   (<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>
Contains:   (<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:    sysvar
Attributes: <none>
Contains:   (<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" ...>.


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

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

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

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


Element:    bitfield-table
Attributes: <none>
Contains:   (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
Contains:   <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 couple of
       was 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
Contains:   (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
Contains:   <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-value
Contains:   (offset)*

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 offset-table element is conventionally represented as a table of offsets
and their meanings. Usually the table is headed by 'offset' and 'contents'
(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 offset-table by changing
these headings, this should only be done with care.


Element:    offset
Attributes: number, name
Contains:   <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).

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 preceeded by a '+' symbol to indicate that they
are offsets.


Element:    message-table
Attributes: <none>
Contains:   (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
Contains:   <text>

offset: the offset, or a range of offsets separated by a hyphen.

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 preceeded by 'R1+' to indicate that they are from
the message block pointer in register 1 (as supplied to
Wimp_SendMessage/Wimp_Poll[Idle])



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

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


Element:    swi-definition
Attributes: name, number, reason, reasonname,
            description, internal, irqs, fiqs, processor-mode, re-entrant
Contains:   (entry?, exit?, use, related?)

name: the full name of this SWI, eg OS_Module
number: the number of this SWI in hex
reason: (optional) the reason code for this SWI, eg 7
reasonname: (optional) the name of this reason code as an unspaced
            capitalised name, eg 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 unspaced names, usually capitalised to indicate word breaks,
and succinctly named to provide a simple to remember and type symbol.

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 use of
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>
Contains:   (register-use)*

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>
Contains:   (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
Contains:   <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 provided 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: flag state
Contains:   <text>

flag: 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>
Contains:   <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:    related
Attributes: <none>
Contains:   (reference)*

The reference 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
Contains:   (entry?, exit?, use, related?)

name: the full name of this vector, eg ColourV
number: the number of this vector in hex
reason: (optional) the reason code for this vector, eg 2
reasonname: (optional) the name of this reason code as an unspaced
            capitalised name, eg FreeBlock
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'
      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
Contains:   (entry?, exit?, use, related)

name: the full name of this code, eg FileEntry_MiscOp
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this entry point, eg 23
reasonname: (optional) the name of this reason code as an unspaced
            capitalised name, eg 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
Contains:   (entry, exit, use, related)

name: the name of this service, eg ShutDown
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this entry point, eg 2
reasonname: (optional) the name of this reason code as an unspaced
            capitalised name, eg 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
Contains:   (entry, exit, use, related)

name: the name of this UpCall, eg FileModified
number: the number of this entry, if applicable, in hex
reason: (optional) the reason code for this entry point, eg 257
reasonname: (optional) the name of this reason code as an unspaced
            capitalised name, eg 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
Contains:   (use, related)

name: the full name of this system variable, eg 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
Contains:   (use, related)

number: the number of this error in hex
name: the symbolic name of this error, eg 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
Contains:   (message-table, use, related)

name: the name of this message, eg 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.

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:    command-definition
Attributes: name, description
Contains:   ((syntax)*, (parameter)*, use, (example)*, related)

name: the name of this command, eg 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:    syntax
Attributes: <none>
Contains:   (switch | optional | 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.


Element:    switch
Attributes: name
Contains:   (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
Contains:   (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:    parameter
Attributes: name, switch, switch-alias, label
Contains:   <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
paramter to a command. A parameter element should be given for each of the
parameters to a command. Whereas switches are preceeded 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>
Contains:   <none>

The br element is equivilent 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
Contains:   image

src: a relative location of the graphic with any necessary extension
type: the type of graphic being represented - only png and draw 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,
it the next image form in will be used instead. This allows for the
possibility of fallback graphic types. All nested image elements should
represent the same information.


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

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


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

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


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

list: 'ordered', 'unordered', defaulting to 'unordered'

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


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

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


Element:    text
Attributes: <none>
Contains:   <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>
Contains:   <none>

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, ie.
   <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.
