io7m | single-page | multi-page | epub | xstructural 1.8.0

xstructural 1.8.0

CREATOR Mark Raynsford
DATE 2021-06-27T00:00:00Z
DESCRIPTION User documentation for the com.io7m.xstructural package.
IDENTIFIER 59c00e65-2e1e-4e86-97b5-b4b1a650eea5
LANGUAGE en
RIGHTS Public Domain
TITLE xstructural 1.8.0
The xstructural package provides an XSLT 2.0 implementation of the structural documentation language.
In contrast to other systems such as DocBook, the structural language only defines elements concerning the structure of the document and not the semantics of the elements. The intention is that higher level languages will produce structural documents as output and then use the provided stylesheets to get various services such as table of contents generation, chapter numbering, footnotes, et cetera, without having to re-implement all of those features for each new language.
The following sections provide informative descriptions of the available language elements. The actual language is defined as an XSD schema, and this is provided in the Schema section.
The structural language is designed in a manner that is intended to confirm to Semantic Versioning 2.0.0. More specifically:

1.1.3.2. Versioning Rules

  • If a document D was written using schema version (x, y), where x is the schema major version and y is the schema minor version, then if the schema version declaration in D is changed to (x, z) for any existing schema minor version z, then D is guaranteed to validate against the new schema version.
  • If a document D was written using schema version (x, y), where x is the schema major version and y is the schema minor version, then if the schema version declaration in D is changed to (a, b) for any existing schema major version a and minor version b such that a ≠ x, then D is NOT guaranteed to validate against the new schema version.
Informally: Minor version changes indicate compatible changes; if you update your document to use the latest minor version of the same major version schema, then you will not have to modify your document to get it to validate. Major version changes indicate incompatible changes; if you update your document to use the latest major version schema, then you may have to make changes to your document in order to get it to validate.
The Document element describes the top-level structure of a document. A document consists of metadata, and a set of top-level sections or subsections (but not both).
A Document must carry a schema version declaration that indicates to which version of the structural language the document is expected to confirm. This is achieved with the use of an xmlns attribute on the Document element. The currently published language versions are:

1.2.1.3. Language Versions

Language Identifier
Structural 7.0 urn:com.io7m.structural:7:0
Structural 8.0 urn:com.io7m.structural:8:0
Renderers encountering a Document element will typically generate a table of contents for the entire document. The tableOfContentsDepth attribute on the Document instructs renderers as to how far into the list of sections or subsections the rendering algorithm should recurse in order to generate the table of contents. For example, an author may choose to only include top-level Section elements in the table of contents and would therefore specify tableOfContentsDepth="1".
Many elements within a Document may be assigned unique identifiers. A unique identifier is a UUID value specified using the id attribute. It is possible to then link to those elements from within the document text using the Link element, and the schema will guarantee the integrity of internal links at validation time.
As described in the Identities section, many significant elements in a document may be the target of the Link element. The structural language distinguishes between different types of links in order to apply varying degrees of integrity checking, and to allow renderers to render links differently based on types. The following kinds of links are currently supported:

1.2.4.2. Link Types

  • Link - a link to a document element. Subject to integrity checks at validation time.
  • LinkExternal - a link to an external document such as a web site. Not subject to integrity checks.
  • LinkFootnote - a link to a footnote. Subject to integrity checks at validation time.
Most elements within documents allow for the specification of type attributes. The type attribute is used to add semantic tags to elements that can be interpreted by renderers in various ways. Typically, the type attribute is translated directly to a CSS class. The attributes can also be consumed by document processors that are trying to extract other semantic information from documents. For example, in this documentation, the term xstructural is always expressed as a Term element with a type attribute set to package. This is intended to indicate to a document processor that the term means "a software package named xstructural". Document authors that are not interested in semantic information can use the type attribute purely for formatting, or alternatively can ignore it entirely.

1.2.6.1. Document Example

<Document xmlns="urn:com.io7m.structural:8:0" tableOfContentsDepth="2" id="14ab90da-7947-420c-a5f8-d9c9c87fbddc">
  ...
</Document>
The Metadata element describes the metadata of a document. The element consists of a sequence of zero or more Dublin Core elements [1], followed by a sequence of zero or more MetaProperty elements [2]. Metadata is not considered to contribute to the semantics of a document. That is, a document with all of the metadata removed is still considered to be semantically valid if the original document was valid. Metadata is typically used to influence the behaviour of any renderers that are processing the document, and are also used to communicate information to external systems that may be, for example, indexing the document for use in a document retrieval system. Metadata can appear in tables in rendered documents, although this can be controlled using the boolean visible attribute (which defaults to false).
Some MetaProperty names are significant to renderers and, where those renderers are known (such as by being part of the xstructural package), the significance of names is documented in the following subsections.
Document authors are strongly recommended to namespace their MetaProperty names using reverse domain name notation, ideally using a domain that they control. MetaProperty names must contain at least two segments consisting of characters taken from the set [a (U+0061), z (U+007A)] ∪ [0 (U+0030), 9 (U+0039)] ∪ { _ (U+005F) } ∪ { _ (U+002D) } , separated by . (U+002E).
This section documents the property names used by the EPUB renderer included with xstructural 1.3.0 and newer.
The contents of this property denote the relative (to the input document) filename of the cover image that will be used for the book. The renderer will translate this name into the correct resource name within the EPUB during rendering.
The contents of this property denote the relative (to the input document) filename of an XHTML file that will be inserted into the colophon page of the generated EPUB.
The contents of this property add an extra file to the manifest. The property can be specified multiple times to add multiple resources. The resources are resolved relative to the source directory of the document.
The contents of this property denote a file that contains a list of extra resources to add to the manifest. The file name is resolved relative to the source directory of the document. The file must contain one resource file per line. For example, if a file named extra-files.txt contains the following text:

1.3.2.5.2. Example File List

file0.txt
file1.txt
file2.txt
Then the following MetaProperty declarations are effectively equivalent:

1.3.2.5.4. Example File List

<MetaProperty name="com.io7m.xstructural.epub.resource-list">extra-files.txt</MetaProperty>

1.3.2.5.5. Example Files

<MetaProperty name="com.io7m.xstructural.epub.resource">file0.txt</MetaProperty>
<MetaProperty name="com.io7m.xstructural.epub.resource">file1.txt</MetaProperty>
<MetaProperty name="com.io7m.xstructural.epub.resource">file2.txt</MetaProperty>

1.3.2.6.1. EPUB Example

<Document xmlns="urn:com.io7m.structural:8:0"
          xmlns:dc="http://purl.org/dc/elements/1.1/">
  <Metadata>
    <dc:title>Example Document</dc:title>
    <MetaProperty name="com.io7m.xstructural.epub.colophon">colophon_extra.xml</MetaProperty>
    <MetaProperty name="com.io7m.xstructural.epub.cover">cover.jpg</MetaProperty>
    <MetaProperty name="com.io7m.xstructural.epub.resource">file0.txt</MetaProperty>
    <MetaProperty name="com.io7m.xstructural.epub.resource">file1.txt</MetaProperty>
    <MetaProperty name="com.io7m.xstructural.epub.resource">file2.txt</MetaProperty>
    <MetaProperty name="com.io7m.xstructural.epub.resource-list">extra-files.txt</MetaProperty>
  </Metadata>
...
This section documents the property names used by the web renderer included with xstructural 1.3.0 and newer.
The contents of this property denote the relative (to the input document) filename of an XHTML file f that will be inserted verbatim as the first element of the XHTML body element.
The contents of this property denote the relative (to the input document) filename of an XHTML file f that will be inserted verbatim as the last element of the XHTML body element.

Footnotes

1
The Dublin Core elements are optional, but some renderers may require them in order to produce sensible output. The title of a Document is specified using the dc:title element, for example.
References to this footnote: 1
2
The MetaProperty elements were added in version 8.0 of the structural language.
References to this footnote: 1
The Section element describes the most structurally significant division of a document. A Section is analogous to a chapter in printed books and it is expected that the majority of documents will consist of a set of top-level Section elements.
Renderers that output multiple files and/or pages are required to treat Section elements as page-breaking. That is, when a renderer encounters a new Section element, it completes rendering of the existing content and then begins an entirely new page and/or output file. This is in contrast to Subsection elements which are required NOT to trigger the generation of new files and/or pages.
Section elements are automatically numbered by the renderers, and may be assigned unique identifiers. Section elements may be nested recursively, and are numbered recursively with respect to other Section elements.
Section elements must include titles, and renderers use these titles when populating tables of content.
Renderers may optionally produce tables of content within rendered sections. The default behaviour is to always produce tables of content, but this may be influenced using the tableOfContents and tableOfContentsDepth attributes. If the tableOfContents attribute is set to false, then no table is generated. If the tableOfContents attribute is set to true, then a table will be generated containing Section and Subsection elements up to a maximum depth of tableOfContentsDepth.

1.4.3.1. Section Example

<Section xmlns="urn:com.io7m.structural:8:0"
         id="4e035356-53d9-4d09-ab6b-ec2c683218f5"
         title="Section">
  <Section title="Another Section">
    ...
  </Section>
  <Section title="Yet Another Section" id="6c311772-c7c8-4c28-979f-a5815795643b">
    ...
  </Section>
</Section>
The Subsection element describes a subdivision of a Section.
Renderers that output multiple files and/or pages are required to treat Subsection elements as non-page-breaking. That is, when a renderer encounters a new Subsection element, it completes rendering of the existing content and then begins rendering of the Subsection on the current page and/or output file. This is in contrast to Section elements which are required to trigger the generation of new files and/or pages.
Subsection elements are automatically numbered by the renderers, and may be assigned unique identifiers. Subsection elements may be nested recursively, and are numbered recursively with respect to other Section and Subsection elements.
Subsection elements must include titles, and renderers use these titles when populating tables of content.

1.5.2.1. Subsection Example

<Subsection xmlns="urn:com.io7m.structural:8:0"
         id="1f56418e-f724-47ad-be10-db92b3e55295"
         title="Subsection">
  <Subsection title="Another Subsection">
    ...
  </Subsection>
  <Subsection title="Yet Another Subsection" id="49698ed6-466b-4917-90be-45480d78719c">
    ...
  </Subsection>
</Subsection>
The Paragraph element describes a subdivision of a Section or Subsection.
Paragraph elements consist entirely of inline content.
Paragraph elements are numbered with respect to other Paragraph and FormalItem elements within the same Section or Subsection.

1.6.2.1. Paragraph Example

<Subsection xmlns="urn:com.io7m.structural:8:0"
         id="0636fa84-2bd5-4cb5-acc5-10ca70948bbf"
         title="Subsection">
  <Paragraph>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam id
consectetur nunc. Donec nisi augue, pulvinar eu condimentum at,
pellentesque a libero. Fusce sed tortor quam. Donec et ipsum diam.
Sed eget molestie lacus, non rutrum risus. Orci varius natoque
penatibus et magnis dis parturient montes, nascetur ridiculus mus.
Class aptent taciti sociosqu ad litora torquent per conubia nostra,
per inceptos himenaeos. Nullam pellentesque est eu augue faucibus
molestie. Pellentesque habitant morbi tristique senectus et netus
et malesuada fames ac turpis egestas. Vivamus sed tincidunt justo.
Sed venenatis enim ac quam euismod, eget semper augue congue.
Integer interdum porttitor porta. Vestibulum eget neque vitae est
congue fringilla. Fusce ac dui suscipit, porttitor velit eu,
rutrum massa. Quisque quis fringilla felis.
  </Paragraph>
  <Paragraph>
Nunc et volutpat arcu. Donec mi nisi, sodales eget egestas sed,
suscipit eget arcu. Cras nibh ligula, maximus eu urna sit amet,
efficitur tempus elit. Sed nec massa auctor, blandit risus in,
dapibus purus. In et neque dignissim, pharetra elit ac, auctor
diam. Ut nisl odio, imperdiet sit amet purus quis, laoreet cursus
dui. Fusce dui neque, aliquet eu augue nec, pharetra laoreet odio.
Sed in scelerisque erat, sit amet sagittis turpis. In suscipit
mauris mauris, ut elementum nulla lacinia quis. Duis tristique
placerat porttitor. Cras vitae convallis purus. Aenean sed
suscipit leo, non dapibus lectus. Proin ac luctus lectus.
  </Paragraph>
</Subsection>
The FormalItem element is analogous to a Paragraph except that it has a defined title. A FormalItem element is commonly used to represent an object similar to a figure in printed books.
FormalItem elements consist entirely of inline content.
FormalItem elements are numbered with respect to other FormalItem and Paragraph elements within the same Section or Subsection.
This example is, itself, a FormalItem element.

1.7.2.2. FormalItem Example

<Subsection xmlns="urn:com.io7m.structural:8:0"
         id="0636fa84-2bd5-4cb5-acc5-10ca70948bbf"
         title="Subsection">
  <FormalItem title="FormalItem Example">
    <Image source="http://www.example.com/image.png">
      An example image.
    </Image>
  </FormalItem>
</Subsection>
The Footnote element describes a footnote.
Footnotes a rendered at the end of the Section within which they are declared, and may be referenced using LinkFootnote elements.

1.8.2.1. Footnote Example

<Footnote id="7c66cd52-4ace-4fd6-a05d-fd0255e441bb">
  The Dublin Core elements are optional, but some renderers may require them in order to produce sensible output. The
  title of a <Link target="a49dac27-48f0-4504-8e03-8f0b73cd9c46">Document</Link> is specified using the
  <LinkExternal target="https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/title">dc:title</LinkExternal>
  element, for example.
</Footnote>
The Link element describes a link to an element that was assigned a unique identifier. The text contents of the Link element are used as the anchor text when generating hyperlinks in rendered documents.
The Link element is subject to integrity checking; documents that declare links to nonexistent elements will fail validation and renderers will refuse to process them.
The LinkExternal element describes a link to an external resource such as a web site. The text contents of the LinkExternal element are used as the anchor text when generating hyperlinks in rendered documents.
The LinkFootnote element describes a link to a Footnote element.
Footnote links are expected to be rendered in the traditional style. That is, a link to a footnote is rendered as the number of the footnote enclosed in square brackets.
The ListOrdered element describes a list within which the order of the items is significant.
The ListUnordered element describes a list within which the order of the items is not significant.
The Item element describes an item within a ListUnordered or ListOrdered element.
The Table element defines a table as a set of rows and columns. It is analogous to a simplified form of the XHTML table element.
The Term element denotes a single word or sentence as being significant.
The xstructural package provides a command-line interface for performing tasks such as validating input documents, and transforming documents to various output formats. The base xstructural command is broken into a number of subcommands which are documented over the following sections.

2.1.2. Command-Line Overview

xstructural: Main: INFO: Arguments required.
Usage: xstructural [options] [command] [command options]
  Options:
    --verbose
      Set the minimum logging verbosity level
      Default: info
      Possible Values: [trace, debug, info, warn, error]
  Commands:
    epub      Transform a structural document to an EPUB
      Usage: epub [options]
        Options:
          --messagesFile
            The output file for XSLT messages
        * --outputDirectory
            The output directory
          --outputFileName
            The output file name
        * --sourceFile
            The source document
          --traceFile
            The output file for trace messages
          --verbose
            Set the minimum logging verbosity level
            Default: info
            Possible Values: [trace, debug, info, warn, error]

    schema      Export the structural schemas to files
      Usage: schema [options]
        Options:
        * --outputDirectory
            The output directory
          --replace
            Replace output files if they already exist
            Default: false
          --verbose
            Set the minimum logging verbosity level
            Default: info
            Possible Values: [trace, debug, info, warn, error]

    validate      Validate a structural document
      Usage: validate [options]
        Options:
        * --sourceFile
            The source document
          --verbose
            Set the minimum logging verbosity level
            Default: info
            Possible Values: [trace, debug, info, warn, error]

    validate-xhtml      Validate an XHTML document
      Usage: validate-xhtml [options]
        Options:
        * --sourceDirectory
            The source directory
          --verbose
            Set the minimum logging verbosity level
            Default: info
            Possible Values: [trace, debug, info, warn, error]

    xhtml      Transform a structural document to XHTML
      Usage: xhtml [options]
        Options:
          --brandingFile
            The branding XML file
          --copyResources
            Should resources (such as CSS) be copied into the output 
            directory? 
            Default: true
          --messagesFile
            The output file for XSLT messages
        * --outputDirectory
            The output directory
        * --sourceFile
            The source document
          --stylesheet
            The stylesheet
            Default: SINGLE_FILE
            Possible Values: [SINGLE_FILE, MULTIPLE_FILE, EPUB]
          --traceFile
            The output file for trace messages
          --verbose
            Set the minimum logging verbosity level
            Default: info
            Possible Values: [trace, debug, info, warn, error]
epub - Produce an EPUB file
The epub command produces a self-contained EPUB file for the given input document. The produced EPUB file is unconditionally checked with EPUBCheck.

2.2.2.2. Parameters

Parameter Type Required Description
--messagesFile Path false A file that will contain XSLT debugging messages.
--traceFile Path false A file that will contain XSLT trace messages.
--sourceFile Path true The path to the input document.
--outputDirectory Path true The directory to which output files will be written.
--outputFileName Path true The name of the output file.

2.2.3.1. Example

$ xstructural epub \
  --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml \
  --outputDirectory out \
  --outputFileName example.epub
xstructural: XSValidator: INFO: validate (xstructural) com.io7m.xstructural.documentation/target/documentation/main.xml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e168.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e311.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e33.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/colophon.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/cover.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e109.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e331.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e14.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e16.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e168.xhtml out/epub/OEBPS/d2e168.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e311.xhtml out/epub/OEBPS/d2e311.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e33.xhtml out/epub/OEBPS/d2e33.xhtml
xstructural: XSEPUBCreator: INFO: copy out/colophon.xhtml out/epub/OEBPS/colophon.xhtml
xstructural: XSEPUBCreator: INFO: copy out/cover.xhtml out/epub/OEBPS/cover.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e109.xhtml out/epub/OEBPS/d2e109.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e331.xhtml out/epub/OEBPS/d2e331.xhtml
xstructural: XSEPUBCreator: INFO: copy out/toc.xhtml out/epub/OEBPS/toc.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e14.xhtml out/epub/OEBPS/d2e14.xhtml
xstructural: XSEPUBCreator: INFO: copy out/d2e16.xhtml out/epub/OEBPS/d2e16.xhtml
xstructural: XSEPUBCreator: INFO: zip entry mimetype
xstructural: XSEPUBCreator: INFO: zip entry content.opf
xstructural: XSEPUBCreator: INFO: zip entry META-INF/container.xml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e168.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e311.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e33.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/colophon.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/cover.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e109.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e331.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/toc.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e14.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/d2e16.xhtml
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/reset.css
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/structural-epub.css
xstructural: XSEPUBCreator: INFO: zip entry OEBPS/document.css
xstructural: XSEPUBCreator: INFO: validating out/example.epub
xstructural: XSEPUBCreator: INFO: epubcheck: stdout: Validating using EPUB version 3.2 rules.
xstructural: XSEPUBCreator: INFO: epubcheck: stdout: No errors or warnings detected.
xstructural: XSEPUBCreator: INFO: epubcheck: stdout: Messages: 0 fatals / 0 errors / 0 warnings / 0 infos
xstructural: XSEPUBCreator: INFO: epubcheck: stdout:
xstructural: XSEPUBCreator: INFO: epubcheck: stdout: EPUBCheck completed

$ ls -alF out/
total 128
drwxr-xr-x  3 xs xs  4096 Jun 26 12:59 ./
drwxr-xr-x 15 xs xs  4096 Jun 26 12:59 ../
-rw-r--r--  1 xs xs   713 Jun 26 12:59 colophon.xhtml
-rw-r--r--  1 xs xs   566 Jun 26 12:59 cover.xhtml
-rw-r--r--  1 xs xs  6256 Jun 26 12:59 d2e109.xhtml
-rw-r--r--  1 xs xs  3572 Jun 26 12:59 d2e14.xhtml
-rw-r--r--  1 xs xs  4077 Jun 26 12:59 d2e16.xhtml
-rw-r--r--  1 xs xs 10530 Jun 26 12:59 d2e168.xhtml
-rw-r--r--  1 xs xs  3767 Jun 26 12:59 d2e311.xhtml
-rw-r--r--  1 xs xs  7158 Jun 26 12:59 d2e33.xhtml
-rw-r--r--  1 xs xs 36763 Jun 26 12:59 d2e331.xhtml
drwxr-xr-x  4 xs xs  4096 Jun 26 12:59 epub/
-rw-r--r--  1 xs xs     0 Jun 26 12:59 epub-resources.txt
-rw-r--r--  1 xs xs 19337 Jun 26 12:59 example.epub
-rw-r--r--  1 xs xs    99 Jun 26 12:59 messages.log
-rw-r--r--  1 xs xs  2460 Jun 26 12:59 toc.xhtml
-rw-r--r--  1 xs xs  2501 Jun 26 12:59 trace.xml
schema - Export schemas
The schema command exports the Structural schema files into a specified directory.

2.3.2.2. Parameters

Parameter Type Required Description
--outputDirectory Path true The path to the output directory.
--replace Boolean false If set to true, any existing files will be replaced.

2.3.3.1. Example

$ xstructural schema --outputDirectory xsd

$ ls -alF xsd/
total 40
drwxr-xr-x  2 xs xs  4096 Apr 28 09:59 ./
drwxr-xr-x 13 xs xs  4096 Apr 28 09:59 ../
-rw-r--r--  1 xs xs  4944 Apr 28 09:59 dc.xsd
-rw-r--r--  1 xs xs  4726 Apr 28 09:59 xml.xsd
-rw-r--r--  1 xs xs 15599 Apr 28 09:59 xstructural-1.xsd

$ xstructural schema --outputDirectory xsd
xstructural: XSCommandSchema: INFO: output file xsd/dc.xsd already exists, ignoring
xstructural: XSCommandSchema: INFO: output file xsd/xml.xsd already exists, ignoring
xstructural: XSCommandSchema: INFO: output file xsd/xstructural-1.xsd already exists, ignoring

$ echo hello > xsd/xstructural-1.xsd

$ ls -alF xsd/
total 40
drwxr-xr-x  2 xs xs  4096 Apr 28 09:59 ./
drwxr-xr-x 13 xs xs  4096 Apr 28 09:59 ../
-rw-r--r--  1 xs xs  4944 Apr 28 09:59 dc.xsd
-rw-r--r--  1 xs xs  4726 Apr 28 09:59 xml.xsd
-rw-r--r--  1 xs xs     6 Apr 28 10:13 xstructural-1.xsd

$ xstructural schema --outputDirectory xsd --replace true

$ ls -alF xsd/
total 40
drwxr-xr-x  2 xs xs  4096 Apr 28 10:14 ./
drwxr-xr-x 13 xs xs  4096 Apr 28 10:10 ../
-rw-r--r--  1 xs xs  4944 Apr 28 10:14 dc.xsd
-rw-r--r--  1 xs xs  4726 Apr 28 10:14 xml.xsd
-rw-r--r--  1 xs xs 15599 Apr 28 10:14 xstructural-1.xsd
validate - Validate input documents
The validate command validates a given document against the Structural schema.

2.4.2.2. Parameters

Parameter Type Required Description
--sourceFile Path true The path to the input document.

2.4.3.1. Example

$ xstructural validate --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml
xstructural: XSValidator: INFO: validate (xstructural) com.io7m.xstructural.documentation/target/documentation/main.xml

$ echo $?
0

$ xstructural validate --sourceFile README-CHANGES.xml
xstructural: XSValidator: INFO: validate (xstructural) README-CHANGES.xml
xstructural: validation: ERROR: README-CHANGES.xml:2:82: cvc-elt.1.a: Cannot find the declaration of element 'c:changelog'.
xstructural: XSValidator: ERROR: one or more validation errors occurred
xstructural: Main: ERROR: com.io7m.xstructural.api.XSValidationException: Document README-CHANGES.xml is not a valid structural document

$ echo $?
1
validate-xhtml - Validate XHTML
The validate-xhtml command validates XHTML pages. The command performs validation against a published XHTML 1.1 XSD schema, and also performs extra integrity checking for internal links.

2.5.2.2. Parameters

Parameter Type Required Description
--sourceDirectory Path true The directory containing XHTML files.

2.5.3.1. Example

$ xstructural validate-xhtml \
  --sourceDirectory out
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/index.xhtml
The validate-xhtml command was added in xstructural 1.3.0.
xhtml - Produce XHTML
The xhtml command produces XHTML pages for the given input document.

2.6.2.2. Parameters

Parameter Type Required Description
--brandingFile Path false The path to the branding document.
--copyResources Boolean false If set to true, resources such as the default Structural CSS files will be copied to the output directory.
--messagesFile Path false A file that will contain XSLT debugging messages.
--traceFile Path false A file that will contain XSLT trace messages.
--sourceFile Path true The path to the input document.
--outputDirectory Path true The directory to which output files will be written.
--stylesheet Stylesheet false The XSLT stylesheet that will be used.

2.6.3.1. Example

$ xstructural xhtml \
  --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml \
  --stylesheet SINGLE_FILE \
  --outputDirectory out
xstructural: XSValidator: INFO: validate (xstructural) com.io7m.xstructural.documentation/target/documentation/main.xml
xstructural: XSTransformer: INFO: copy resource reset.css
xstructural: XSTransformer: INFO: copy resource structural.css
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/index.xhtml

$ ls -alF out/
total 116
drwxr-xr-x  2 xs xs  4096 Apr 28 10:26 ./
drwxr-xr-x 14 xs xs  4096 Apr 28 10:26 ../
-rw-r--r--  1 xs xs 30783 Apr 28 10:26 index.xhtml
-rw-r--r--  1 xs xs   272 Apr 28 10:26 messages.log
-rw-r--r--  1 xs xs  6138 Apr 28 10:26 reset.css
-rw-r--r--  1 xs xs  6881 Apr 28 10:26 structural.css
-rw-r--r--  1 xs xs 57239 Apr 28 10:26 trace.xml

$ xstructural xhtml \
  --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml \
  --stylesheet MULTIPLE_FILE \
  --outputDirectory out
xstructural: XSValidator: INFO: validate (xstructural) com.io7m.xstructural.documentation/target/documentation/main.xml
xstructural: XSTransformer: INFO: copy resource reset.css
xstructural: XSTransformer: INFO: copy resource structural.css
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e104.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e298.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e300.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e12.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e163.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e28.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/index-m.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/index.xhtml
xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/d2e14.xhtml

$ ls -alF out/
total 172
drwxr-xr-x  2 xs xs  4096 Apr 28 10:35 ./
drwxr-xr-x 14 xs xs  4096 Apr 28 10:26 ../
-rw-r--r--  1 xs xs  7187 Apr 28 10:35 d2e104.xhtml
-rw-r--r--  1 xs xs  5251 Apr 28 10:35 d2e12.xhtml
-rw-r--r--  1 xs xs  5914 Apr 28 10:35 d2e14.xhtml
-rw-r--r--  1 xs xs  7405 Apr 28 10:35 d2e163.xhtml
-rw-r--r--  1 xs xs  8016 Apr 28 10:35 d2e28.xhtml
-rw-r--r--  1 xs xs  3175 Apr 28 10:35 d2e298.xhtml
-rw-r--r--  1 xs xs  3366 Apr 28 10:35 d2e300.xhtml
-rw-r--r--  1 xs xs  5746 Apr 28 10:35 index-m.xhtml
-rw-r--r--  1 xs xs 30783 Apr 28 10:26 index.xhtml
-rw-r--r--  1 xs xs     0 Apr 28 10:35 messages.log
-rw-r--r--  1 xs xs  6138 Apr 28 10:35 reset.css
-rw-r--r--  1 xs xs  6881 Apr 28 10:35 structural.css
-rw-r--r--  1 xs xs 60237 Apr 28 10:35 trace.xml
The xstructural package provides a Maven plugin for transforming documents as part of a Maven build.
The Maven plugin has a simple interface that mostly matches the command-line interface.

3.2.2. POM Definitions

<build>
    <plugins>
      ...

      <!-- Generate documentation in various formats. -->
      <plugin>
        <groupId>com.io7m.xstructural</groupId>
        <artifactId>com.io7m.xstructural.maven_plugin</artifactId>
        <version>1.8.0</version>
        <executions>
          <execution>
            <id>xhtml-single</id>
            <phase>package</phase>
            <goals>
              <goal>xhtml-single</goal>
            </goals>
            <configuration>
              <brandingFile>src/main/xml/brand.xml</brandingFile>
              <sourceFile>src/main/xml/main.xml</sourceFile>
              <outputDirectory>target/documentation</outputDirectory>
            </configuration>
          </execution>
          <execution>
            <id>xhtml-multi</id>
            <phase>package</phase>
            <goals>
              <goal>xhtml-multi</goal>
            </goals>
            <configuration>
              <brandingFile>src/main/xml/brand.xml</brandingFile>
              <sourceFile>src/main/xml/main.xml</sourceFile>
              <outputDirectory>target/documentation</outputDirectory>
            </configuration>
          </execution>
          <execution>
            <id>epub</id>
            <phase>package</phase>
            <goals>
              <goal>epub</goal>
            </goals>
            <configuration>
              <brandingFile>src/main/xml/brand.xml</brandingFile>
              <sourceFile>src/main/xml/main.xml</sourceFile>
              <outputDirectory>target/epub</outputDirectory>
              <outputFileName>documentation.epub</outputFileName>
            </configuration>
          </execution>
        </executions>
      </plugin>

    </plugins>
  </build>
Execution of the plugin may be skipped by setting the xstructural.skip system property to true.

4.1.1. Usage

var factory =
  ServiceLoader.load(XSProcessorFactoryType.class)
    .findFirst()
    .orElseThrow(() -> new IllegalStateException("Missing factory service"));

final var request =
  XSProcessorRequest.builder()
    .setOutputDirectory(Paths.get(...))
    .setSourceFile(Paths.get(...))
    .setTask(Task.TRANSFORM_XHTML)
    .setStylesheet(Stylesheet.SINGLE_FILE)
    .build();

final var processor = processors.create(request);
processor.execute();
Please see the included JavaDoc for API reference documentation.
The structural language is defined by a strict XSD schema. Documents not conforming to the schema MUST be rejected by renderers.

5.2. xstructural 8.0 Schema

<?xml version="1.0" encoding="UTF-8" ?>

<!--
  Copyright © 2021 Mark Raynsford <code@io7m.com> https://www.io7m.com

  Permission to use, copy, modify, and/or distribute this software for any
  purpose with or without fee is hereby granted, provided that the above
  copyright notice and this permission notice appear in all copies.

  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            elementFormDefault="qualified"
            xmlns:dc="http://purl.org/dc/elements/1.1/"
            xmlns:s="urn:com.io7m.structural:8:0"
            targetNamespace="urn:com.io7m.structural:8:0">

  <xsd:import namespace="http://purl.org/dc/elements/1.1/"
              schemaLocation="dc.xsd"/>
  <xsd:import namespace="http://www.w3.org/XML/1998/namespace"
              schemaLocation="xml.xsd"/>

  <xsd:simpleType name="uuidType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A UUID value.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="imageTextType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of text that appears in image elements. This is required to be of non-zero length in order to ensure
        that authors add useful text that will then be used in the 'alt' elements of XHTML generated from the document
        sources.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:minLength value="1"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="typeType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of type names. Type names are used to categorize elements and are somewhat analogous to CSS classes,
        except that they are intended to be used for more than just styling documents.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[a-zA-Z][a-zA-Z0-9_\.\-]*"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:attributeGroup name="standardXMLAttributes">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The standard elements expected to appear in XML texts.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute ref="xml:base"/>
    <xsd:attribute ref="xml:lang"/>
  </xsd:attributeGroup>

  <xsd:attributeGroup name="tableOfContentAttributes">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The attributes used to describe tables of content.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attribute name="tableOfContents"
                   use="optional"
                   default="true"
                   type="xsd:boolean">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          If the value of the attribute is 'true', then a table of contents will be generated in the respective element.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="tableOfContentsDepth"
                   use="optional"
                   default="3"
                   type="xsd:positiveInteger">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The maximum relative depth of sections and subsections that will appear in a generated table of contents.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:attributeGroup>

  <xsd:complexType mixed="true"
                   name="ImageType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An element used to describe an image. The text content of the image element SHOULD be used to provide an
        accessible description of the image. This description is expected to be used by screen readers, and may also be
        displayed by browsers if the referenced image cannot be loaded for any reason.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:simpleContent>
      <xsd:extension base="s:imageTextType">
        <xsd:attributeGroup ref="s:standardXMLAttributes"/>

        <xsd:attribute name="type"
                       type="s:typeType"
                       use="optional">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The type of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
        <xsd:attribute name="width"
                       type="xsd:nonNegativeInteger"
                       use="optional">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The width of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
        <xsd:attribute name="height"
                       type="xsd:nonNegativeInteger"
                       use="optional">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The height of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
        <xsd:attribute name="source"
                       type="xsd:anyURI"
                       use="required">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The source location of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
      </xsd:extension>
    </xsd:simpleContent>
  </xsd:complexType>

  <xsd:element name="Image"
               type="s:ImageType"/>

  <xsd:complexType name="ItemType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An item appearing in a list.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:ListContent"/>
    </xsd:sequence>
    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the list item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Item"
               type="s:ItemType"/>

  <xsd:group name="ListContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The elements that may appear in list items.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Image"/>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Term"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="ListOrderedType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An ordered list.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Item"/>
    </xsd:sequence>
    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="ListOrdered"
               type="s:ListOrderedType"/>

  <xsd:complexType name="ListUnorderedType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An unordered list.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Item"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="ListUnordered"
               type="s:ListUnorderedType"/>

  <xsd:complexType name="ColumnType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A description of a column in a table.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the column.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Column"
               type="s:ColumnType"/>

  <xsd:complexType name="ColumnsType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A set of table column descriptions.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Column"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the columns.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Columns"
               type="s:ColumnsType"/>

  <xsd:group name="TableContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that may appear in table cells.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:Term"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="CellType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A cell in a table.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:TableContent"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the cell.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Cell"
               type="s:CellType"/>

  <xsd:complexType name="RowType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A row of cells in a table.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Cell"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the row.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Row"
               type="s:RowType"/>

  <xsd:complexType name="TableType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A table. A table consists of a list of column definitions, followed by a sequence of rows consisting of the
        table cells.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:element ref="s:Columns"/>
      <xsd:sequence minOccurs="1"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Row"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the table.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Table"
               type="s:TableType"/>

  <xsd:complexType name="TermType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A term acts as a simple container of one or more words in a sentence. Term elements can be used to denote the
        semantics of words, such as wrapping the name of a mathematical function in a &lt;Term type="function"&gt;
        element.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="s:typeType"
                   name="type"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the term.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Term"
               type="s:TermType"/>

  <xsd:complexType name="LinkType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Link element describes a link to an element within the current document. Links may only refer to elements that
        contain an appropriate 'id' attribute.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="s:uuidType"
                   name="target"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The target of the link, which must be an element with an appropriate 'id' attribute.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the link.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Link"
               type="s:LinkType"/>

  <xsd:complexType name="LinkFootnoteType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A LinkFootnote element describes a link to a footnote within the current section.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="s:uuidType"
                   name="target"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The target of the link, which must be a Footnote with a matching 'id' attribute.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the link.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="LinkFootnote"
               type="s:LinkFootnoteType"/>

  <xsd:complexType name="LinkExternalType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A LinkExternal element describes a link to an external URI.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="xsd:anyURI"
                   name="target"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The target URI.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the link.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="LinkExternal"
               type="s:LinkExternalType"/>

  <xsd:complexType name="VerbatimType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Verbatim element contains text that should be reproduced exactly, with almost all whitespace intact. Renderers
        are permitted to trim leading and trailing whitespace.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the verbatim text.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Verbatim"
               type="s:VerbatimType"/>

  <xsd:group name="FormalItemContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that can appear in formal items.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Image"/>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Table"/>
      <xsd:element ref="s:Term"/>
      <xsd:element ref="s:Verbatim"/>
    </xsd:choice>
  </xsd:group>

  <xsd:group name="ParagraphContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that can appear in paragraphs.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:Term"/>
    </xsd:choice>
  </xsd:group>

  <xsd:simpleType name="MetaPropertyNameType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of meta property names.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="([a-z0-9_\-]+)(.([a-z0-9_\-]+))+"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:complexType name="MetaPropertyType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A metadata property.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attribute name="name"
                   use="required"
                   type="s:MetaPropertyNameType"/>
    <xsd:attribute name="visible"
                   use="optional"
                   default="false"
                   type="xsd:boolean"/>
  </xsd:complexType>

  <xsd:element name="MetaProperty"
               type="s:MetaPropertyType"/>

  <xsd:complexType name="MetadataType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An element containing document metadata.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:group ref="dc:elementsGroup"/>
      <xsd:sequence minOccurs="0"
                    maxOccurs="unbounded">
        <xsd:element ref="s:MetaProperty"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
  </xsd:complexType>

  <xsd:element name="Metadata"
               type="s:MetadataType"/>

  <xsd:complexType name="ParagraphType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A paragraph denotes a self-contained series of sentences.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:ParagraphContent"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the paragraph.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional"/>
  </xsd:complexType>

  <xsd:element name="Paragraph"
               type="s:ParagraphType"/>

  <xsd:complexType name="FormalItemType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A formal item is analogous to a "figure" in printed text. Formal items are used to significant images, tables of
        data, code listings, and other important objects into texts. They are considered to be at the same level of
        structural significance as paragraphs.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:group ref="s:FormalItemContent"/>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the formal item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the formal item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="title"
                   type="xsd:string"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The title of the formal item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="FormalItem"
               type="s:FormalItemType"/>

  <xsd:group name="SubsectionContent">
    <xsd:choice>
      <xsd:element ref="s:Paragraph"/>
      <xsd:element ref="s:FormalItem"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="SubsectionType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Subsection is a structural element that denotes a part of the document similar to a chapter.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:sequence minOccurs="1"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Subsection"/>
      </xsd:sequence>
      <xsd:sequence minOccurs="1"
                    maxOccurs="unbounded">
        <xsd:group ref="s:SubsectionContent"/>
      </xsd:sequence>
    </xsd:choice>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the subsection.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the subsection.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="title"
                   type="xsd:string"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The title of the subsection.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Subsection"
               type="s:SubsectionType"/>

  <xsd:group name="FootnoteContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that may appear in footnotes.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Image"/>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Table"/>
      <xsd:element ref="s:Term"/>
      <xsd:element ref="s:Verbatim"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="FootnoteType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Footnote is a note of referenc or comment usually placed at the bottom of a page. Footnotes may be referenced
        by LinkFootnote elements.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:FootnoteContent"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the footnote.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Footnote"
               type="s:FootnoteType"/>

  <xsd:complexType name="SectionType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Section is a structural element that denotes a part of the document similar to a chapter. Renderers that
        produce multiple pages MUST insert whatever is analogous to a page break at the end of a section.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:choice>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Section"/>
        </xsd:sequence>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Subsection"/>
        </xsd:sequence>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:group ref="s:SubsectionContent"/>
        </xsd:sequence>
      </xsd:choice>
      <xsd:sequence minOccurs="0"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Footnote"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attributeGroup ref="s:tableOfContentAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the section.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the section.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="title"
                   type="xsd:string"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The title of the section.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Section"
               type="s:SectionType">

    <xsd:unique name="SectionFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnotes within a section must have unique identifiers.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:selector xpath="s:Footnote"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:keyref name="SectionFootnoteReferencesParagraph"
                refer="s:SectionFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnote links in paragraphs must refer to footnotes that exist in this section.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:selector xpath="s:Paragraph/*/s:LinkFootnote"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>

    <xsd:keyref name="SectionFootnoteReferencesSubsection"
                refer="s:SectionFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnote links in subsections must refer to footnotes that exist in this section.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:selector xpath="s:Subsection/*/s:LinkFootnote"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>
  </xsd:element>

  <xsd:complexType name="DocumentType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The Document element represents the top-level structure of a document. The name 'document' is somewhat of a
        misnomer, as nothing prevents the document from being structured as a book (with chapters, etc). The document
        begins with standard Dublin Core metadata, and contains _either_ a series of sections _or_ a series of
        subsections (but not both).
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:element ref="s:Metadata"/>
      <xsd:choice>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Section"/>
        </xsd:sequence>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Subsection"/>
        </xsd:sequence>
      </xsd:choice>
      <xsd:sequence minOccurs="0"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Footnote"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attributeGroup ref="s:tableOfContentAttributes"/>
  </xsd:complexType>

  <xsd:element name="Document"
               type="s:DocumentType">
    <xsd:unique name="ItemIDsAreUnique">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All 'id' attributes specified on objects within the document must be unique.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath=".//s:FormalItem|.//s:Paragraph|.//s:Subsection|.//s:Section|.//s:Footnote"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:unique name="LinkReferencesAreUnique">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All 'id' attributes specified on objects within the document must be unique.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath=".//s:FormalItem|.//s:Paragraph|.//s:Subsection|.//s:Section"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:keyref name="LinkReferences"
                refer="s:LinkReferencesAreUnique">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All Link elements must refer to elements with existing 'id' attributes.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath=".//s:Link"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>

    <xsd:unique name="DocumentFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All 'id' attributes specified on footnotes within the document must be unique.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath="s:Footnote"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:keyref name="DocumentFootnoteReferences"
                refer="s:DocumentFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnote references must refer to footnotes that exist.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath="s:Subsection/*/s:LinkFootnote"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>
  </xsd:element>

</xsd:schema>

5.3. xstructural 7.0 Schema

<?xml version="1.0" encoding="UTF-8" ?>

<!--
  Copyright © 2021 Mark Raynsford <code@io7m.com> https://www.io7m.com

  Permission to use, copy, modify, and/or distribute this software for any
  purpose with or without fee is hereby granted, provided that the above
  copyright notice and this permission notice appear in all copies.

  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            elementFormDefault="qualified"
            xmlns:dc="http://purl.org/dc/elements/1.1/"
            xmlns:s="urn:com.io7m.structural:7:0"
            targetNamespace="urn:com.io7m.structural:7:0">

  <xsd:import namespace="http://purl.org/dc/elements/1.1/"
              schemaLocation="dc.xsd"/>
  <xsd:import namespace="http://www.w3.org/XML/1998/namespace"
              schemaLocation="xml.xsd"/>

  <xsd:simpleType name="uuidType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A UUID value.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="imageTextType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of text that appears in image elements. This is required to be of non-zero length in order to ensure
        that authors add useful text that will then be used in the 'alt' elements of XHTML generated from the document
        sources.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:minLength value="1"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="typeType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of type names. Type names are used to categorize elements and are somewhat analogous to CSS classes,
        except that they are intended to be used for more than just styling documents.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[a-zA-Z][a-zA-Z0-9_\.\-]*"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:attributeGroup name="standardXMLAttributes">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The standard elements expected to appear in XML texts.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:attribute ref="xml:base"/>
    <xsd:attribute ref="xml:lang"/>
  </xsd:attributeGroup>

  <xsd:attributeGroup name="tableOfContentAttributes">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The attributes used to describe tables of content.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attribute name="tableOfContents"
                   use="optional"
                   default="true"
                   type="xsd:boolean">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          If the value of the attribute is 'true', then a table of contents will be generated in the respective element.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="tableOfContentsDepth"
                   use="optional"
                   default="3"
                   type="xsd:positiveInteger">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The maximum relative depth of sections and subsections that will appear in a generated table of contents.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:attributeGroup>

  <xsd:complexType mixed="true"
                   name="ImageType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An element used to describe an image. The text content of the image element SHOULD be used to provide an
        accessible description of the image. This description is expected to be used by screen readers, and may also be
        displayed by browsers if the referenced image cannot be loaded for any reason.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:simpleContent>
      <xsd:extension base="s:imageTextType">
        <xsd:attributeGroup ref="s:standardXMLAttributes"/>

        <xsd:attribute name="type"
                       type="s:typeType"
                       use="optional">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The type of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
        <xsd:attribute name="width"
                       type="xsd:nonNegativeInteger"
                       use="optional">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The width of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
        <xsd:attribute name="height"
                       type="xsd:nonNegativeInteger"
                       use="optional">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The height of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
        <xsd:attribute name="source"
                       type="xsd:anyURI"
                       use="required">
          <xsd:annotation>
            <xsd:documentation xml:lang="en">
              The source location of the image.
            </xsd:documentation>
          </xsd:annotation>
        </xsd:attribute>
      </xsd:extension>
    </xsd:simpleContent>
  </xsd:complexType>

  <xsd:element name="Image"
               type="s:ImageType"/>

  <xsd:complexType name="ItemType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An item appearing in a list.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:ListContent"/>
    </xsd:sequence>
    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the list item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Item"
               type="s:ItemType"/>

  <xsd:group name="ListContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The elements that may appear in list items.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Image"/>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Term"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="ListOrderedType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An ordered list.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Item"/>
    </xsd:sequence>
    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="ListOrdered"
               type="s:ListOrderedType"/>

  <xsd:complexType name="ListUnorderedType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An unordered list.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Item"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="ListUnordered"
               type="s:ListUnorderedType"/>

  <xsd:complexType name="ColumnType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A description of a column in a table.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the column.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Column"
               type="s:ColumnType"/>

  <xsd:complexType name="ColumnsType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A set of table column descriptions.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Column"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the columns.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Columns"
               type="s:ColumnsType"/>

  <xsd:group name="TableContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that may appear in table cells.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:Term"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="CellType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A cell in a table.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:TableContent"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the cell.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Cell"
               type="s:CellType"/>

  <xsd:complexType name="RowType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A row of cells in a table.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="1"
                  maxOccurs="unbounded">
      <xsd:element ref="s:Cell"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the row.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Row"
               type="s:RowType"/>

  <xsd:complexType name="TableType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A table. A table consists of a list of column definitions, followed by a sequence of rows consisting of the
        table cells.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:element ref="s:Columns"/>
      <xsd:sequence minOccurs="1"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Row"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the table.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Table"
               type="s:TableType"/>

  <xsd:complexType name="TermType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A term acts as a simple container of one or more words in a sentence. Term elements can be used to denote the
        semantics of words, such as wrapping the name of a mathematical function in a &lt;Term type="function"&gt;
        element.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="s:typeType"
                   name="type"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the term.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Term"
               type="s:TermType"/>

  <xsd:complexType name="LinkType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Link element describes a link to an element within the current document. Links may only refer to elements that
        contain an appropriate 'id' attribute.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="s:uuidType"
                   name="target"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The target of the link, which must be an element with an appropriate 'id' attribute.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the link.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Link"
               type="s:LinkType"/>

  <xsd:complexType name="LinkFootnoteType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A LinkFootnote element describes a link to a footnote within the current section.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="s:uuidType"
                   name="target"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The target of the link, which must be a Footnote with a matching 'id' attribute.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the link.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="LinkFootnote"
               type="s:LinkFootnoteType"/>

  <xsd:complexType name="LinkExternalType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A LinkExternal element describes a link to an external URI.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute type="xsd:anyURI"
                   name="target"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The target URI.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the link.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="LinkExternal"
               type="s:LinkExternalType"/>

  <xsd:complexType name="VerbatimType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Verbatim element contains text that should be reproduced exactly, with almost all whitespace intact. Renderers
        are permitted to trim leading and trailing whitespace.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the verbatim text.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Verbatim"
               type="s:VerbatimType"/>

  <xsd:group name="FormalItemContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that can appear in formal items.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Image"/>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Table"/>
      <xsd:element ref="s:Term"/>
      <xsd:element ref="s:Verbatim"/>
    </xsd:choice>
  </xsd:group>

  <xsd:group name="ParagraphContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that can appear in paragraphs.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Term"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="MetadataType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        An element containing document metadata.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:group ref="dc:elementsGroup"/>
    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
  </xsd:complexType>

  <xsd:element name="Metadata"
               type="s:MetadataType"/>

  <xsd:complexType name="ParagraphType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A paragraph denotes a self-contained series of sentences.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:ParagraphContent"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the paragraph.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional"/>
  </xsd:complexType>

  <xsd:element name="Paragraph"
               type="s:ParagraphType"/>

  <xsd:complexType name="FormalItemType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A formal item is analogous to a "figure" in printed text. Formal items are used to significant images, tables of
        data, code listings, and other important objects into texts. They are considered to be at the same level of
        structural significance as paragraphs.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:group ref="s:FormalItemContent"/>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the formal item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the formal item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="title"
                   type="xsd:string"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The title of the formal item.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="FormalItem"
               type="s:FormalItemType"/>

  <xsd:group name="SubsectionContent">
    <xsd:choice>
      <xsd:element ref="s:Paragraph"/>
      <xsd:element ref="s:FormalItem"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="SubsectionType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Subsection is a structural element that denotes a part of the document similar to a chapter.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:sequence minOccurs="1"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Subsection"/>
      </xsd:sequence>
      <xsd:sequence minOccurs="1"
                    maxOccurs="unbounded">
        <xsd:group ref="s:SubsectionContent"/>
      </xsd:sequence>
    </xsd:choice>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the subsection.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the subsection.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="title"
                   type="xsd:string"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The title of the subsection.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Subsection"
               type="s:SubsectionType"/>

  <xsd:group name="FootnoteContent">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The type of content that may appear in footnotes.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:choice>
      <xsd:element ref="s:Image"/>
      <xsd:element ref="s:Link"/>
      <xsd:element ref="s:LinkExternal"/>
      <xsd:element ref="s:LinkFootnote"/>
      <xsd:element ref="s:ListOrdered"/>
      <xsd:element ref="s:ListUnordered"/>
      <xsd:element ref="s:Table"/>
      <xsd:element ref="s:Term"/>
      <xsd:element ref="s:Verbatim"/>
    </xsd:choice>
  </xsd:group>

  <xsd:complexType name="FootnoteType"
                   mixed="true">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Footnote is a note of referenc or comment usually placed at the bottom of a page. Footnotes may be referenced
        by LinkFootnote elements.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence minOccurs="0"
                  maxOccurs="unbounded">
      <xsd:group ref="s:FootnoteContent"/>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the footnote.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Footnote"
               type="s:FootnoteType"/>

  <xsd:complexType name="SectionType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        A Section is a structural element that denotes a part of the document similar to a chapter. Renderers that
        produce multiple pages MUST insert whatever is analogous to a page break at the end of a section.
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:choice>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Section"/>
        </xsd:sequence>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Subsection"/>
        </xsd:sequence>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:group ref="s:SubsectionContent"/>
        </xsd:sequence>
      </xsd:choice>
      <xsd:sequence minOccurs="0"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Footnote"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attributeGroup ref="s:tableOfContentAttributes"/>

    <xsd:attribute name="type"
                   type="s:typeType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The type of the section.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="id"
                   type="s:uuidType"
                   use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The unique identifier of the section.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>

    <xsd:attribute name="title"
                   type="xsd:string"
                   use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          The title of the section.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:element name="Section"
               type="s:SectionType">

    <xsd:unique name="SectionFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnotes within a section must have unique identifiers.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:selector xpath="s:Footnote"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:keyref name="SectionFootnoteReferencesParagraph"
                refer="s:SectionFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnote links in paragraphs must refer to footnotes that exist in this section.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:selector xpath="s:Paragraph/*/s:LinkFootnote"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>

    <xsd:keyref name="SectionFootnoteReferencesSubsection"
                refer="s:SectionFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnote links in subsections must refer to footnotes that exist in this section.
        </xsd:documentation>
      </xsd:annotation>
      <xsd:selector xpath="s:Subsection/*/s:LinkFootnote"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>
  </xsd:element>

  <xsd:complexType name="DocumentType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">
        The Document element represents the top-level structure of a document. The name 'document' is somewhat of a
        misnomer, as nothing prevents the document from being structured as a book (with chapters, etc). The document
        begins with standard Dublin Core metadata, and contains _either_ a series of sections _or_ a series of
        subsections (but not both).
      </xsd:documentation>
    </xsd:annotation>

    <xsd:sequence>
      <xsd:element ref="s:Metadata"/>
      <xsd:choice>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Section"/>
        </xsd:sequence>
        <xsd:sequence minOccurs="1"
                      maxOccurs="unbounded">
          <xsd:element ref="s:Subsection"/>
        </xsd:sequence>
      </xsd:choice>
      <xsd:sequence minOccurs="0"
                    maxOccurs="unbounded">
        <xsd:element ref="s:Footnote"/>
      </xsd:sequence>
    </xsd:sequence>

    <xsd:attributeGroup ref="s:standardXMLAttributes"/>
    <xsd:attributeGroup ref="s:tableOfContentAttributes"/>
  </xsd:complexType>

  <xsd:element name="Document"
               type="s:DocumentType">
    <xsd:unique name="ItemIDsAreUnique">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All 'id' attributes specified on objects within the document must be unique.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath=".//s:FormalItem|.//s:Paragraph|.//s:Subsection|.//s:Section|.//s:Footnote"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:unique name="LinkReferencesAreUnique">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All 'id' attributes specified on objects within the document must be unique.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath=".//s:FormalItem|.//s:Paragraph|.//s:Subsection|.//s:Section"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:keyref name="LinkReferences"
                refer="s:LinkReferencesAreUnique">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All Link elements must refer to elements with existing 'id' attributes.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath=".//s:Link"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>

    <xsd:unique name="DocumentFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All 'id' attributes specified on footnotes within the document must be unique.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath="s:Footnote"/>
      <xsd:field xpath="@id"/>
    </xsd:unique>

    <xsd:keyref name="DocumentFootnoteReferences"
                refer="s:DocumentFootnoteKey">
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
          All footnote references must refer to footnotes that exist.
        </xsd:documentation>
      </xsd:annotation>

      <xsd:selector xpath="s:Subsection/*/s:LinkFootnote"/>
      <xsd:field xpath="@target"/>
    </xsd:keyref>
  </xsd:element>

</xsd:schema>
This documentation is placed into the public domain.

6.2. License

Copyright © 2021 Mark Raynsford <code@io7m.com> https://www.io7m.com

This book is placed into the public domain for free use by anyone
for any purpose. It may be freely used, modified, and distributed.

In jurisdictions that do not recognise the public domain this book
may be freely used, modified, and distributed without restriction.

This book comes with absolutely no warranty.
io7m | single-page | multi-page | epub | xstructural 1.8.0