# xstructural 3.0.0-beta0002 | Property | Value | | --- | --- | | 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 3.0.0-beta0002 | ## Table Of Contents - [1. Language](#d0e37) - [1.1. Description](#d0e39) - [1.2. Document](#id_a49dac27-48f0-4504-8e03-8f0b73cd9c46) - [1.3. Metadata](#id_027296c3-c406-4191-a444-5b10873094e8) - [1.4. Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) - [1.5. Subsection](#id_55ae1912-9aec-402a-babe-ed7778e76599) - [1.6. Paragraph](#id_01d0fde7-7742-47a9-864c-b9c55e2e9980) - [1.7. FormalItem](#id_13029feb-2126-4d72-9151-63607152b7db) - [1.8. Footnote](#id_8abc7eeb-c828-4307-a64d-0d8d6ae25e98) - [1.9. Inline Elements](#id_8e536f96-16e1-4f4a-bc3a-6613e20cb504) - [2. Types](#id_26f17f0a-f486-4722-ad6d-8504c3bb1ad6) - [2.1. Overview](#d0e1083) - [2.2. Schema](#d0e1103) - [3. Command-Line Interface](#id_41890668-2d97-42e1-aa10-7efc4f36297f) - [3.1. Overview](#d0e1120) - [3.2. EPUB](#d0e1137) - [3.3. Format](#d0e1264) - [3.4. Markdown](#d0e1341) - [3.5. Schema](#d0e1459) - [3.6. Validate](#d0e1535) - [3.7. Validate-XHTML](#d0e1606) - [3.8. XHTML](#d0e1676) - [4. Maven Plugin](#d0e1831) - [4.1. Overview](#d0e1833) - [4.2. Usage](#d0e1842) - [4.3. Skipping](#d0e1856) - [4.4. Format](#d0e1868) - [5. API](#d0e1893) - [5.1. Usage](#d0e1895) - [5.2. JavaDoc](#d0e1903) - [6. Schema](#id_3c28e89e-a225-46ba-bbc5-5c989425a509) - [7. License](#id_b3169e89-019a-41b8-89e5-49b985fd25df) ## 1. Language ## 1.1. Description ### 1.1.1. Overview The **xstructural** package provides an [XSLT 2.0](https://www.w3.org/TR/xslt20/) implementation of the **structural** documentation language. In contrast to other systems such as [DocBook](http://www.docbook.org/), 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. ### 1.1.2. Schema The following sections provide informative descriptions of the available language elements. The actual language is defined as an [XSD](https://www.w3.org/TR/xmlschema-1/) schema, and this is provided in the [Schema](#id_3c28e89e-a225-46ba-bbc5-5c989425a509) section. ### 1.1.3. Versioning The **structural** language is designed in a manner that is intended to conform to [Semantic Versioning 2.0.0](https://semver.org/). 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. ## 1.2. Document ### 1.2.1. Description The **Document** element describes the top-level structure of a document. A document consists of [metadata](#id_027296c3-c406-4191-a444-5b10873094e8), and a set of top-level [sections](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) or [subsections](#id_55ae1912-9aec-402a-babe-ed7778e76599) (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 conform. This is achieved with the use of an [xmlns](https://www.w3.org/TR/REC-xml-names/) 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 | | Structural 9.0 | urn:com.io7m.structural:9:0 | ### 1.2.2. Tables Of Content 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](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) or [subsections](#id_55ae1912-9aec-402a-babe-ed7778e76599) 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"**. ### 1.2.3. Identities Many elements within a **Document** may be assigned **unique identifiers**. A **unique identifier** is a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) value specified using the **id** attribute. It is possible to then link to those elements from within the document text using the [Link](#id_88660fca-74ea-4a3b-bb59-32d750a515a3) element, and the schema will guarantee the integrity of internal links at validation time. ### 1.2.4. Links As described in the [Identities](#id_39506c3e-1361-4f81-be32-8c110a19d9bb) section, many significant elements in a document may be the target of the [Link](#id_88660fca-74ea-4a3b-bb59-32d750a515a3) 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](#id_88660fca-74ea-4a3b-bb59-32d750a515a3) - a link to a document element. Subject to integrity checks at validation time. - [LinkExternal](#id_217b1f13-a98b-4fe7-a701-700073818f33) - a link to an external document such as a web site. Not subject to integrity checks. - [LinkFootnote](#id_b611d66f-e82d-4afd-b908-f27340718651) - a link to a footnote. Subject to integrity checks at validation time. ### 1.2.5. Types 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](https://en.wikipedia.org/wiki/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](#id_8265ab1b-7524-4af9-8415-3dc787bd959f) 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. Examples #### 1.2.6.1. Document Example ``` ... ``` ## 1.3. Metadata ### 1.3.1. Description The **Metadata** element describes the metadata of a document. The element consists of a sequence of zero or more [Dublin Core](http://dublincore.org/) elements [1](#id_7c66cd52-4ace-4fd6-a05d-fd0255e441bb), followed by a sequence of zero or more **MetaProperty** elements [2](#id_9977adf0-b726-46e6-bc98-11176e1d2916). 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](https://en.wikipedia.org/wiki/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)**. ### 1.3.2. EPUB ### 1.3.2.1. Package This section documents the property names used by the EPUB renderer included with **xstructural 1.3.0** and newer. ### 1.3.2.2. com.io7m.xstructural.epub.cover 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. ### 1.3.2.3. com.io7m.xstructural.epub.colophon 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. ### 1.3.2.4. com.io7m.xstructural.epub.resource 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. ### 1.3.2.5. com.io7m.xstructural.epub.resource-list 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 ``` extra-files.txt ``` #### 1.3.2.5.5. Example Files ``` file0.txt file1.txt file2.txt ``` ### 1.3.2.6. Examples #### 1.3.2.6.1. EPUB Example ``` Example Document colophon_extra.xml cover.jpg file0.txt file1.txt file2.txt extra-files.txt ... ``` ### 1.3.3. Web ### 1.3.3.1. Package This section documents the property names used by the web renderer included with **xstructural 1.3.0** and newer. ### 1.3.3.2. com.io7m.xstructural.web.branding.header 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. ### 1.3.3.3. com.io7m.xstructural.web.branding.footer 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. ### 1.3.3.4. com.io7m.xstructural.web.cover The contents of this property denote the relative (to the input document) filename of the cover image that will be used for the book. ### 1.3.4. Markdown ### 1.3.4.1. Package This section documents the property names used by the Markdown renderer. ### 1.3.4.2. com.io7m.xstructural.markdown.header The contents of this property denote the relative (to the input document) filename of a Markdown file **f** that will be inserted verbatim at the very beginning of the generated Markdown output, before the document title. ### 1.3.4.3. com.io7m.xstructural.markdown.footer The contents of this property denote the relative (to the input document) filename of a Markdown file **f** that will be inserted verbatim at the very end of the generated Markdown output, after the document footnotes. ## 1.4. Section ### 1.4.1. Description The **Section** element describes the most structurally significant division of a document. A **Section** is analogous to a [chapter](https://en.wikipedia.org/wiki/Chapter_(books)) 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](#id_55ae1912-9aec-402a-babe-ed7778e76599) 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](#id_39506c3e-1361-4f81-be32-8c110a19d9bb). **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](#id_8430e3b6-3327-4390-a19f-e315d7dcf3d8). ### 1.4.2. 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](#id_55ae1912-9aec-402a-babe-ed7778e76599) elements up to a maximum depth of **tableOfContentsDepth**. ### 1.4.3. Examples #### 1.4.3.1. Section Example ```
...
...
``` ## 1.5. Subsection ### 1.5.1. Description The **Subsection** element describes a subdivision of a [Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140). 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](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) 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](#id_39506c3e-1361-4f81-be32-8c110a19d9bb). **Subsection** elements may be nested recursively, and are numbered recursively with respect to other [Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) and **Subsection** elements. **Subsection** elements must include titles, and renderers use these titles when populating [tables of content](#id_8430e3b6-3327-4390-a19f-e315d7dcf3d8). ### 1.5.2. Examples #### 1.5.2.1. Subsection Example ``` ... ... ``` ## 1.6. Paragraph ### 1.6.1. Description The **Paragraph** element describes a subdivision of a [Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) or [Subsection](#id_55ae1912-9aec-402a-babe-ed7778e76599). **Paragraph** elements consist entirely of [inline content](#id_8e536f96-16e1-4f4a-bc3a-6613e20cb504). **Paragraph** elements are numbered with respect to other **Paragraph** and [FormalItem](#id_13029feb-2126-4d72-9151-63607152b7db) elements within the same [Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) or [Subsection](#id_55ae1912-9aec-402a-babe-ed7778e76599). ### 1.6.2. Examples #### 1.6.2.1. Paragraph Example ``` 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. 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. ``` ## 1.7. FormalItem ### 1.7.1. Description The **FormalItem** element is analogous to a [Paragraph](#id_01d0fde7-7742-47a9-864c-b9c55e2e9980) 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](#id_8e536f96-16e1-4f4a-bc3a-6613e20cb504). **FormalItem** elements are numbered with respect to other **FormalItem** and [Paragraph](#id_01d0fde7-7742-47a9-864c-b9c55e2e9980) elements within the same [Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) or [Subsection](#id_55ae1912-9aec-402a-babe-ed7778e76599). ### 1.7.2. Examples This example is, itself, a **FormalItem** element. #### 1.7.2.2. FormalItem Example ``` An example image. ``` #### 1.7.2.3. FormalItem Table ``` Language Identifier Structural 7.0 urn:com.io7m.structural:7:0 Structural 8.0 urn:com.io7m.structural:8:0 Structural 9.0 urn:com.io7m.structural:9:0
``` #### 1.7.2.4. FormalItem Table (Rendered) | Language | Identifier | | --- | --- | | Structural 7.0 | urn:com.io7m.structural:7:0 | | Structural 8.0 | urn:com.io7m.structural:8:0 | | Structural 9.0 | urn:com.io7m.structural:9:0 | Note that it is possible to [link to table rows](#d0e891). ## 1.8. Footnote ### 1.8.1. Description The **Footnote** element describes a [footnote](https://en.wikipedia.org/wiki/Note_(typography)). Footnotes a rendered at the end of the [Section](#id_cc5514e1-dc68-4b88-9374-fe09b8741140) within which they are declared, and may be referenced using [LinkFootnote](#id_b611d66f-e82d-4afd-b908-f27340718651) elements. ### 1.8.2. Examples #### 1.8.2.1. Footnote Example ``` 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. ``` ## 1.9. Inline Elements ### 1.9.1. Link The **Link** element describes a link to an element that was assigned a [unique identifier](#id_39506c3e-1361-4f81-be32-8c110a19d9bb). The text contents of the **Link** element are used as the [anchor text](https://en.wikipedia.org/wiki/HTML_element#Anchor) 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. ### 1.9.2. LinkExternal 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](https://en.wikipedia.org/wiki/HTML_element#Anchor) when generating hyperlinks in rendered documents. ### 1.9.3. LinkFootnote The **LinkFootnote** element describes a link to a [Footnote](#id_8abc7eeb-c828-4307-a64d-0d8d6ae25e98) 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. ### 1.9.4. ListOrdered The **ListOrdered** element describes a list within which the order of the [items](#id_c8d7692d-1871-4332-92df-bcb8196e9fa8) is significant. ### 1.9.5. ListUnordered The **ListUnordered** element describes a list within which the order of the [items](#id_c8d7692d-1871-4332-92df-bcb8196e9fa8) is not significant. ### 1.9.6. Item The **Item** element describes an item within a [ListUnordered](#id_7eed6ef8-aeba-45cd-8f72-0b016593aed2) or [ListOrdered](#id_90ba0e6b-5bf9-4ece-beba-de6c01083ee9) element. ### 1.9.7. Table 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. ### 1.9.8. Term The **Term** element denotes a single word or sentence as being significant. ## 2. Types ### 2.1. Overview The **xstructural** package provides a simple checker for [type](#id_09b89d86-aed4-4d4b-805d-d8aec81206e1) attributes. Given a file of **type declarations**, the checker will ensure that all type attributes that appear in a document refer to declared types. If a type attribute refers to a nonexistent type, the document will fail to validate. #### 2.1.2. Example ``` A name of a software package. Le nom d'un logiciel de service. Ein Name eines Softwarepakets. ``` ### 2.2. Schema A **type declaration file** must conform to the following schema: #### 2.2.2. Type Declaration Schema ``` The type of package (semantic) versions. The type of package names. 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. A human-readable description of the meaning of a type. The type of types. ``` ## 3. Command-Line Interface ## 3.1. Overview 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. #### 3.1.2. Command-Line Overview ``` xstructural: usage: xstructural [command] [arguments ...] The xstructural structural document format command-line application. Use the "help" command to examine specific commands: $ xstructural help help. Command-line arguments can be placed one per line into a file, and the file can be referenced using the @ symbol: $ echo help > file.txt $ echo help >> file.txt $ xstructural @file.txt Commands: epub Transform a structural document to an EPUB file format Format one or more structural files in place help Show usage information for a command. markdown Transform a structural document to Markdown schema Export the structural schemas to files validate Validate a structural document validate-xhtml Validate an XHTML file version Show the application version. xhtml Transform a structural document to XHTML Documentation: https://www.io7m.com/software/xstructural/ ``` ## 3.2. EPUB ### 3.2.1. Name **epub** - Produce an EPUB file ### 3.2.2. Description The **epub** command produces a self-contained EPUB file for the given input document. The produced EPUB file is unconditionally checked with [EPUBCheck](https://github.com/w3c/epubcheck). #### 3.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. | | **--typeFile** | Path | false | The path to the type description file. | | **--outputDirectory** | Path | true | The directory to which output files will be written. | | **--outputFileName** | String | false | The name of the output file. | ### 3.2.3. Examples #### 3.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) /home/user/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 ``` ## 3.3. Format ### 3.3.1. Name **format** - Format one or more structural files in place ### 3.3.2. Description The **format** command reformats one or more structural files in place. The logical content of each file is unchanged; only the whitespace layout is altered. One or more files must be provided, either as positional parameters or through the **--sourceFile** parameter, or a combination of both. #### 3.3.2.3. Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | **file** | Path | true | One or more source files to be formatted in place, given as positional parameters. | | **--sourceFile** | Path | false | One or more source files to be formatted in place, given as an alternative to the positional parameters. | ### 3.3.3. Examples #### 3.3.3.1. Example ``` $ xstructural format file.xml other.xml $ echo $? 0 $ xstructural format --sourceFile file.xml $ echo $? 0 ``` ## 3.4. Markdown ### 3.4.1. Name **markdown** - Transform a structural document to Markdown ### 3.4.2. Description The **markdown** command transforms the given input document into a single Markdown document, written to **index.md** in the output directory. Files referenced by the document, such as images, are copied into the output directory so that the image links in the produced document are resolvable. The rendered document places all footnotes in a single trailing section at the end of the file, with footnote numbering that is global across the whole document. #### 3.4.2.4. 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. | | **--typeFile** | Path | false | The path to the type description file. | | **--outputDirectory** | Path | true | The directory to which output files will be written. | ### 3.4.3. Examples #### 3.4.3.1. Example ``` $ xstructural markdown \ --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml \ --outputDirectory out xstructural: XSValidator: INFO: validate (xstructural) /home/user/xstructural/com.io7m.xstructural.documentation/target/documentation/main.xml xstructural: XSTransformer: INFO: document uses namespace urn:com.io7m.structural:9:0 $ ls -alF out/ total 440 drwxr-xr-x 2 xs xs 60 Oct 2 16:25 ./ drwxr-xr-x 15 xs xs 320 Oct 2 16:25 ../ -rw-r--r-- 1 xs xs 149120 Oct 2 16:25 index.md -rw-r--r-- 1 xs xs 515 Oct 2 16:25 messages.log -rw-r--r-- 1 xs xs 287760 Oct 2 16:25 trace.xml ``` ## 3.5. Schema ### 3.5.1. Name **schema** - Export schemas ### 3.5.2. Description The **schema** command exports the Structural schema files into a specified directory. #### 3.5.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. | ### 3.5.3. Examples #### 3.5.3.1. Example ``` $ xstructural schema --outputDirectory xsd $ ls -alF xsd/ total 120 drwxr-xr-x 2 xs xs 141 Apr 28 09:59 ./ drwxr-xr-x 13 xs xs 17 Apr 28 09:59 ../ -rw-r--r-- 1 xs xs 4949 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 31534 Apr 28 09:59 xstructural-7.xsd -rw-r--r-- 1 xs xs 2174 Apr 28 09:59 xstructural-8-index.xsd -rw-r--r-- 1 xs xs 32555 Apr 28 09:59 xstructural-8.xsd -rw-r--r-- 1 xs xs 32868 Apr 28 09:59 xstructural-9.xsd $ xstructural schema --outputDirectory xsd xstructural: XSCommandSchema: INFO: output file /home/user/xstructural/xsd/dc.xsd already exists, ignoring xstructural: XSCommandSchema: INFO: output file /home/user/xstructural/xsd/xml.xsd already exists, ignoring xstructural: XSCommandSchema: INFO: output file /home/user/xstructural/xsd/xstructural-7.xsd already exists, ignoring xstructural: XSCommandSchema: INFO: output file /home/user/xstructural/xsd/xstructural-8.xsd already exists, ignoring xstructural: XSCommandSchema: INFO: output file /home/user/xstructural/xsd/xstructural-9.xsd already exists, ignoring xstructural: XSCommandSchema: INFO: output file /home/user/xstructural/xsd/xstructural-8-index.xsd already exists, ignoring $ echo hello > xsd/xstructural-9.xsd $ ls -alF xsd/ total 120 drwxr-xr-x 2 xs xs 141 Apr 28 09:59 ./ drwxr-xr-x 13 xs xs 17 Apr 28 09:59 ../ -rw-r--r-- 1 xs xs 4949 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 31534 Apr 28 09:59 xstructural-7.xsd -rw-r--r-- 1 xs xs 2174 Apr 28 09:59 xstructural-8-index.xsd -rw-r--r-- 1 xs xs 32555 Apr 28 09:59 xstructural-8.xsd -rw-r--r-- 1 xs xs 6 Apr 28 10:13 xstructural-9.xsd $ xstructural schema --outputDirectory xsd --replace true $ ls -alF xsd/ total 120 drwxr-xr-x 2 xs xs 141 Apr 28 10:14 ./ drwxr-xr-x 13 xs xs 17 Apr 28 10:10 ../ -rw-r--r-- 1 xs xs 4949 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 31534 Apr 28 10:14 xstructural-7.xsd -rw-r--r-- 1 xs xs 2174 Apr 28 10:14 xstructural-8-index.xsd -rw-r--r-- 1 xs xs 32555 Apr 28 10:14 xstructural-8.xsd -rw-r--r-- 1 xs xs 32868 Apr 28 10:14 xstructural-9.xsd ``` ## 3.6. Validate ### 3.6.1. Name **validate** - Validate input documents ### 3.6.2. Description The **validate** command validates a given document against the Structural schema. #### 3.6.2.2. Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | **--sourceFile** | Path | true | The path to the input document. | | **--typeFile** | Path | false | The path to the type description file. | ### 3.6.3. Examples #### 3.6.3.1. Example ``` $ xstructural validate --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml xstructural: XSValidator: INFO: validate (xstructural) /home/user/xstructural/com.io7m.xstructural.documentation/target/documentation/main.xml $ echo $? 0 $ xstructural validate --sourceFile README-CHANGES.xml xstructural: XSValidator: INFO: validate (xstructural) /home/user/xstructural/README-CHANGES.xml xstructural: validation: ERROR: file:///home/user/xstructural/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 /home/user/xstructural/README-CHANGES.xml is not a valid structural document $ echo $? 1 ``` ## 3.7. Validate-XHTML ### 3.7.1. Name **validate-xhtml** - Validate XHTML ### 3.7.2. Description 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. #### 3.7.2.2. Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | **--sourceDirectory** | Path | true | The directory containing XHTML files. | ### 3.7.3. Examples #### 3.7.3.1. Example ``` $ xstructural validate-xhtml \ --sourceDirectory out xstructural: XSXHTMLValidator: INFO: validate (xhtml 1.1) out/index.xhtml ``` ### 3.7.4. History The **validate-xhtml** command was added in **xstructural 1.3.0**. ## 3.8. XHTML ### 3.8.1. Name **xhtml** - Produce XHTML ### 3.8.2. Description The **xhtml** command produces XHTML pages for the given input document. #### 3.8.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. | | **--typeFile** | Path | false | The path to the type description file. | | **--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. | ### 3.8.3. Examples #### 3.8.3.1. Example ``` $ xstructural xhtml \ --sourceFile com.io7m.xstructural.documentation/target/documentation/main.xml \ --stylesheet SINGLE_FILE \ --outputDirectory out xstructural: XSValidator: INFO: validate (xstructural) /home/user/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) /home/user/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 ``` ## 4. Maven Plugin ### 4.1. Overview The **xstructural** package provides a Maven plugin for transforming documents as part of a Maven build. ### 4.2. Usage The Maven plugin has a simple interface that mostly matches the [command-line](#id_41890668-2d97-42e1-aa10-7efc4f36297f) interface. #### 4.2.2. POM Definitions ``` ... com.io7m.xstructural com.io7m.xstructural.maven_plugin 3.0.0-beta0002 xhtml-single package xhtml-single src/main/xml/brand.xml src/main/xml/main.xml target/documentation xhtml-multi package xhtml-multi src/main/xml/brand.xml src/main/xml/main.xml target/documentation src/main/xml/types.xml epub package epub src/main/xml/brand.xml src/main/xml/main.xml target/epub documentation.epub markdown package markdown src/main/xml/main.xml target/markdown ``` ### 4.3. Skipping Execution of the plugin may be skipped by setting the **xstructural.skip** system property to **true**. ### 4.4. Format The **format** goal formats structural files in place. Files are selected with an Ant-style **glob** pattern, matched relative to the **baseDirectory** (defaulting to the project basedir). The maximum line width is configurable with **maxWidth** (defaulting to 120). #### 4.4.2. Example ``` com.io7m.xstructural com.io7m.xstructural.maven_plugin 3.0.0-beta0002 format format **/*.xml ``` ## 5. API ### 5.1. Usage #### 5.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(); ``` ### 5.2. JavaDoc Please see the included [JavaDoc](https://www.io7m.com/software/xstructural/documentation/apidocs) for API reference documentation. ## 6. Schema The **structural** language is defined by a strict XSD schema. Documents not conforming to the schema MUST be rejected by renderers. #### 6.2. xstructural 9.0 Schema ``` A UUID value. 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. 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. The standard elements expected to appear in XML texts. The attributes used to describe tables of content. If the value of the attribute is 'true', then a table of contents will be generated in the respective element. The maximum relative depth of sections and subsections that will appear in a generated table of contents. 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. The type of the image. The width of the image. The height of the image. The source location of the image. An item appearing in a list. The type of the list item. The elements that may appear in list items. An ordered list. The type of the list. An unordered list. The type of the list. A description of a column in a table. The type of the column. A set of table column descriptions. The type of the columns. The type of content that may appear in table cells. A cell in a table. The type of the cell. A row of cells in a table. The type of the row. The unique identifier of the table row. A table. A table consists of a list of column definitions, followed by a sequence of rows consisting of the table cells. The type of the table row. 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 <Term type="function"> element. The type of the term. 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. The target of the link, which must be an element with an appropriate 'id' attribute. The type of the link. A LinkFootnote element describes a link to a footnote within the current section. The target of the link, which must be a Footnote with a matching 'id' attribute. The type of the link. A LinkExternal element describes a link to an external URI. The target URI. The type of the link. A Verbatim element contains text that should be reproduced exactly, with almost all whitespace intact. Renderers are permitted to trim leading and trailing whitespace. The type of the verbatim text. The type of content that can appear in formal items. The type of content that can appear in paragraphs. The type of meta property names. A metadata property. An element containing document metadata. A paragraph denotes a self-contained series of sentences. The type of the paragraph. 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. The type of the formal item. The unique identifier of the formal item. The title of the formal item. A Subsection is a structural element that denotes a part of the document similar to a chapter. The type of the subsection. The unique identifier of the subsection. The title of the subsection. The type of content that may appear in footnotes. A Footnote is a note of referenc or comment usually placed at the bottom of a page. Footnotes may be referenced by LinkFootnote elements. The unique identifier of the footnote. 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. The type of the section. The unique identifier of the section. The title of the section. All footnotes within a section must have unique identifiers. All footnote links in paragraphs must refer to footnotes that exist in this section. All footnote links in subsections must refer to footnotes that exist in this section. 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). All 'id' attributes specified on objects within the document must be unique. All 'id' attributes specified on objects within the document must be unique. All Link elements must refer to elements with existing 'id' attributes. All 'id' attributes specified on footnotes within the document must be unique. All footnote references must refer to footnotes that exist. ``` #### 6.3. xstructural 8.0 Schema ``` A UUID value. 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. 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. The standard elements expected to appear in XML texts. The attributes used to describe tables of content. If the value of the attribute is 'true', then a table of contents will be generated in the respective element. The maximum relative depth of sections and subsections that will appear in a generated table of contents. 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. The type of the image. The width of the image. The height of the image. The source location of the image. An item appearing in a list. The type of the list item. The elements that may appear in list items. An ordered list. The type of the list. An unordered list. The type of the list. A description of a column in a table. The type of the column. A set of table column descriptions. The type of the columns. The type of content that may appear in table cells. A cell in a table. The type of the cell. A row of cells in a table. The type of the row. A table. A table consists of a list of column definitions, followed by a sequence of rows consisting of the table cells. The type of the table. 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 <Term type="function"> element. The type of the term. 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. The target of the link, which must be an element with an appropriate 'id' attribute. The type of the link. A LinkFootnote element describes a link to a footnote within the current section. The target of the link, which must be a Footnote with a matching 'id' attribute. The type of the link. A LinkExternal element describes a link to an external URI. The target URI. The type of the link. A Verbatim element contains text that should be reproduced exactly, with almost all whitespace intact. Renderers are permitted to trim leading and trailing whitespace. The type of the verbatim text. The type of content that can appear in formal items. The type of content that can appear in paragraphs. The type of meta property names. A metadata property. An element containing document metadata. A paragraph denotes a self-contained series of sentences. The type of the paragraph. 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. The type of the formal item. The unique identifier of the formal item. The title of the formal item. A Subsection is a structural element that denotes a part of the document similar to a chapter. The type of the subsection. The unique identifier of the subsection. The title of the subsection. The type of content that may appear in footnotes. A Footnote is a note of referenc or comment usually placed at the bottom of a page. Footnotes may be referenced by LinkFootnote elements. The unique identifier of the footnote. 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. The type of the section. The unique identifier of the section. The title of the section. All footnotes within a section must have unique identifiers. All footnote links in paragraphs must refer to footnotes that exist in this section. All footnote links in subsections must refer to footnotes that exist in this section. 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). All 'id' attributes specified on objects within the document must be unique. All 'id' attributes specified on objects within the document must be unique. All Link elements must refer to elements with existing 'id' attributes. All 'id' attributes specified on footnotes within the document must be unique. All footnote references must refer to footnotes that exist. ``` #### 6.4. xstructural 7.0 Schema ``` A UUID value. 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. 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. The standard elements expected to appear in XML texts. The attributes used to describe tables of content. If the value of the attribute is 'true', then a table of contents will be generated in the respective element. The maximum relative depth of sections and subsections that will appear in a generated table of contents. 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. The type of the image. The width of the image. The height of the image. The source location of the image. An item appearing in a list. The type of the list item. The elements that may appear in list items. An ordered list. The type of the list. An unordered list. The type of the list. A description of a column in a table. The type of the column. A set of table column descriptions. The type of the columns. The type of content that may appear in table cells. A cell in a table. The type of the cell. A row of cells in a table. The type of the row. A table. A table consists of a list of column definitions, followed by a sequence of rows consisting of the table cells. The type of the table. 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 <Term type="function"> element. The type of the term. 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. The target of the link, which must be an element with an appropriate 'id' attribute. The type of the link. A LinkFootnote element describes a link to a footnote within the current section. The target of the link, which must be a Footnote with a matching 'id' attribute. The type of the link. A LinkExternal element describes a link to an external URI. The target URI. The type of the link. A Verbatim element contains text that should be reproduced exactly, with almost all whitespace intact. Renderers are permitted to trim leading and trailing whitespace. The type of the verbatim text. The type of content that can appear in formal items. The type of content that can appear in paragraphs. An element containing document metadata. A paragraph denotes a self-contained series of sentences. The type of the paragraph. 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. The type of the formal item. The unique identifier of the formal item. The title of the formal item. A Subsection is a structural element that denotes a part of the document similar to a chapter. The type of the subsection. The unique identifier of the subsection. The title of the subsection. The type of content that may appear in footnotes. A Footnote is a note of referenc or comment usually placed at the bottom of a page. Footnotes may be referenced by LinkFootnote elements. The unique identifier of the footnote. 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. The type of the section. The unique identifier of the section. The title of the section. All footnotes within a section must have unique identifiers. All footnote links in paragraphs must refer to footnotes that exist in this section. All footnote links in subsections must refer to footnotes that exist in this section. 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). All 'id' attributes specified on objects within the document must be unique. All 'id' attributes specified on objects within the document must be unique. All Link elements must refer to elements with existing 'id' attributes. All 'id' attributes specified on footnotes within the document must be unique. All footnote references must refer to footnotes that exist. ``` ## 7. License This documentation is placed into the public domain. #### 7.2. License ``` Copyright © 2021 Mark Raynsford 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. ``` ## 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](#id_a49dac27-48f0-4504-8e03-8f0b73cd9c46) is specified using the [dc:title](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/title) element, for example. 2. The **MetaProperty** elements were added in version **8.0** of the **structural** language.