Merge branch 'master' into test-on-riscos

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-20.04
     container: ubuntu:18.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Build examples
         run: |
@@ -33,7 +33,7 @@ jobs:
 
       - uses: actions/upload-artifact@v2
         with:
-          name: Example-output
+          name: Test-Output
           path: test-output
 
   # Tests for different platforms
@@ -42,10 +42,11 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu:18.04", "ubuntu:20.04", "ubuntu:21.04", "centos:7", "centos:8", "debian:10"]
+        #os: ["ubuntu:18.04"]
     container: ${{ matrix.os }}
     needs: test-examples #  always run after the baseline tests
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Prerequisites for CentOS 8
         if: matrix.os == 'centos:8'
@@ -66,7 +67,7 @@ jobs:
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Install required packages
         run: |
@@ -93,7 +94,9 @@ jobs:
     needs: ["test-riscos", "test-platforms"]
     container: ubuntu:18.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Prerequisites
         run: |
@@ -122,7 +125,9 @@ jobs:
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Install required packages
         run: |
@@ -167,12 +172,26 @@ jobs:
         with:
           name: Tool-POSIX
 
+      - name: Download built binary (tests)
+        uses: actions/download-artifact@v1
+        with:
+          name: Test-Output
+
       # RISC OS version is already archived in a RISC OS archive format.
       - name: Archive the contents of the POSIX version
         run: |
           cd Tool-POSIX
+          # For some reason, the executable flag has been lost on the tool.
+          chmod +x riscos-prminxml
           tar zcvf ../PRMinXML-${{ needs.export-riscos.outputs.version }}.tar.gz *
 
+      - name: Archive the contents of the Test output
+        run: |
+          cd Test-Output
+          # We use zip here because most people using these tools will be RISC OS users
+          # and zip is more friendly to them.
+          zip ../TestOutput-${{ needs.export-riscos.outputs.version }}.zip *
+
       - name: Create Release
         id: create_release
         uses: actions/create-release@v1
@@ -209,3 +228,16 @@ jobs:
           asset_path: PRMinXML-${{ needs.export-riscos.outputs.version }}.tar.gz
           asset_name: POSIX-PRMinXML-${{ needs.export-riscos.outputs.version }}.tar.gz
           asset_content_type: application/gzip
+
+      - name: Upload Release Asset (Test output)
+        id: upload-release-asset-test-output
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # This pulls from the CREATE RELEASE step above, referencing it's ID to get its outputs object, which include a `upload_url`.
+          # See this blog post for more info: https://jasonet.co/posts/new-features-of-github-actions/#passing-data-to-future-steps 
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: TestOutput-${{ needs.export-riscos.outputs.version }}.zip
+          asset_name: Example-Output-${{ needs.export-riscos.outputs.version }}.zip
+          asset_content_type: application/zip

catalog/docs/PRMinXML.txt

@@ -66,7 +66,7 @@ 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, eg :
+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.
@@ -79,7 +79,7 @@ Message definition for Window_Info not found at
    /
    riscos-prm/
    chapter[@title='Pinboard']/
-   section[@title='Technical Details']/
+   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']/
@@ -834,21 +834,20 @@ the PRMs provide.
 
 
 Element:    swi-definition
-Attributes: name, number, offset, reason, reasonname,
+Attributes: name, number, offset, offset-base, reason, reasonname,
             description, internal, irqs, fiqs, processor-mode, re-entrant
-Children:   (entry?, exit?, use, declaration?, related?)
+Children:   (entry?, exit?, use, (example)*, declaration?, related?)
 
-name: the full name of this SWI, eg OS_Module
+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, eg 7
-        if a sub-reason code is required then it should be separated with 
-        comma and a space. e.g as '7, 1'
+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, eg FreeBlock
-description: one sentence description of the function provided by this
-             SWI
+       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
@@ -944,33 +943,26 @@ 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.
+structure as described in the Technical details.
 
 
 Element:    example
 Attributes: <none>
 Children:   (p | command | systemoutput | br)*
 
-The example element is used to enclose code or execution examples within a
 definition. The element can be repeated within the definition to give
 multiple unrelated examples.
 
-Examples might be command line execution, or short sections of code which
 use the definition.
 
 
 Element:    declaration
 Attributes: type
 Children:   (code | extended-example)*
 
-type: usage type for the declaration, with the following types defined:
-      'unknown' - should be used when the other types do not apply
       'prototype' - should be used for C prototypes for functions
       'structure' - should be used for C structure declarations
 
-The declaration element is used to describe an interface to a definition
-within a common library. It should give a short example of the declaration
-as a code element, or a longer one with the extended-example element.
 
 
 Element:    related
@@ -990,13 +982,15 @@ section to provide links.
 Element:    vector-definition
 Attributes: name, number, reason, reasonname,
             description, internal, irqs, fiqs, processor-mode, re-entrant
-Children:   (entry?, exit?, use, declaration?, related?)
+Children:   (entry?, exit?, use, declaration?, (example)*, related?)
 
-name: the full name of this vector, eg ColourV
+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, eg 2
+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, eg FreeBlock
+      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
@@ -1017,13 +1011,13 @@ 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, declaration?, related)
+Children:   (entry?, exit?, use, declaration?, (example)*, related)
 
-name: the full name of this code, eg FileEntry_MiscOp
+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, eg 23
+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, eg MountAlienSpaceship
+      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
@@ -1045,13 +1039,15 @@ such as callbacks.
 Element:    service-definition
 Attributes: name, number, reason, reasonname,
             description, internal
-Children:   (entry, exit, use, declaration?, related)
+Children:   (entry, exit, use, declaration?, (example)*, related)
 
-name: the name of this service, eg ShutDown
+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, eg 2
+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, eg Intialising
+            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
@@ -1066,13 +1062,15 @@ prefixed by 'Service_' to indicate its lineage.
 Element:    upcall-definition
 Attributes: name, number, reason, reasonname,
             description, internal
-Children:   (entry, exit, use, declaration?, related)
+Children:   (entry, exit, use, declaration?, (example)*, related)
 
-name: the name of this UpCall, eg FileModified
+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, eg 257
+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, eg Renaming
+            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
@@ -1086,9 +1084,9 @@ to indicate its lineage.
 
 Element:    sysvar-definition
 Attributes: name, description
-Children:   (use, related)
+Children:   (use, example?, related)
 
-name: the full name of this system variable, eg System$Path
+name: the full name of this system variable; for example 'System$Path'
 description: one sentence description of the function provided by this
              system variable
 
@@ -1101,7 +1099,7 @@ Attributes: number, name, description
 Children:   (use, related)
 
 number: the number of this error in hex
-name: the symbolic name of this error, eg BadPathVariable
+name: the symbolic name of this error for example 'BadPathVariable'
 description: one sentence description of the function provided by this
              system variable
 
@@ -1114,7 +1112,7 @@ Attributes: name, number, description, source, destination,
             recorded, broadcast
 Children:   (message-table, use, declaration?, related)
 
-name: the name of this message, eg DataOpen
+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,
@@ -1144,7 +1142,7 @@ Element:    tboxmessage-definition
 Attributes: name, number, description
 Children:   (message-table, use, declaration?, related)
 
-name: the name of this message, eg ColourMenu_HasBeenHidden
+name: the name of this message; for example 'ColourMenu_HasBeenHidden'
 description: one sentence description of the function provided by this
              message
 
@@ -1156,13 +1154,13 @@ 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?, related)
+Children:   (entry, exit, use, declaration?, (example)*, related)
 
-name: the name of this service, eg ColourMenu_SetTitle
+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, eg 2
+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, eg Intialising
+            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
@@ -1175,7 +1173,7 @@ Element:    command-definition
 Attributes: name, description
 Children:   ((syntax)*, (parameter)*, use, (example)*, related)
 
-name: the name of this command, eg DataOpen
+name: the name of this command; for example 'DataOpen'
 description: one sentence description of the function provided by this
              command
 
@@ -1189,7 +1187,7 @@ Element:    vdu-definition
 Attributes: name, number, description
 Children:   ((syntax)*, (parameter)*, use, (example)*, related)
 
-name: the name of this command, eg DataOpen
+name: the name of this command; for example DataOpen
 description: one sentence description of the function provided by this
              command
 

crosscompile/setup-riscos-tests.sh

@@ -60,10 +60,8 @@ rm -rf "${downloaddir}/Lib"
 # Put our tool in the top level
 "${scriptdir}/build-riscos-tool.sh" "${downloaddir}"
 
-# Put the examples in there (only if they are present)
-if [[ -d "${rootdir}/examples" ]] ; then
-    cp -R "${rootdir}/examples" "${downloaddir}/examples"
-fi
+# Put the examples in there
+cp -R "${rootdir}/examples" "${downloaddir}/examples"
 
 # Put the !Install tool in there
 cp "${rootdir}/Resources/!Install,feb" "${downloaddir}/"

examples/lists.xml

@@ -8,6 +8,7 @@
 <section title="Unordered list">
 
 <p>Regular text before.</p>
+<p>
 <list>
     <item>Item 1</item>
     <item>Item 2</item>
@@ -16,11 +17,13 @@
     <item><p>Item 5 in a paragraph</p><p>With a second paragraph</p></item>
     <item>Item 6</item>
 </list>
+</p>
 <p>Regular text after.</p>
 </section>
 
 <section title="Ordered list">
 <p>Regular text before.</p>
+<p>
 <list type='ordered'>
     <item>Item 1</item>
     <item>Item 2</item>
@@ -29,12 +32,14 @@
     <item><p>Item 5 in a paragraph</p><p>With a second paragraph</p></item>
     <item>Item 6</item>
 </list>
+</p>
 <p>Regular text after.</p>
 </section>
 
 <section title="Unordered nested lists">
 
 <p>Regular text before.</p>
+<p>
 <list>
     <item>Item 1</item>
     <item>Item 2</item>
@@ -46,6 +51,7 @@
     </item>
     <item>Item 4</item>
 </list>
+</p>
 <p>Regular text after.</p>
 </section>