Add documentation, fix schema

This adds language documentation, and fixes a bug in the schema that effectively rejected footnote references that were referring to footnotes in the wrong scope. The schema now accurately reflects the fact that footnote references can only reference footnotes in the containing section, as was intended all along. Affects: #13
io7m-com · Jun 27, 2021 · 18a1965 · 18a1965
1 parent 23a8a4a
commit 18a1965
Show file tree

Hide file tree

Showing 24 changed files with 754 additions and 38 deletions.
diff --git a/README-CHANGES.xml b/README-CHANGES.xml
@@ -24,8 +24,15 @@
         <c:change date="2020-12-19T00:00:00+00:00" summary="Slightly improve the CSS for table elements"/>
       </c:changes>
     </c:release>
-    <c:release date="2020-12-20T11:13:41+00:00" is-open="true" ticket-system="com.github.io7m.xstructural" version="1.3.0">
-      <c:changes/>
+    <c:release date="2021-06-27T16:34:56+00:00" is-open="true" ticket-system="com.github.io7m.xstructural" version="1.3.0">
+      <c:changes>
+        <c:change date="2021-06-27T00:00:00+00:00" summary="Add EPUB support">
+          <c:tickets>
+            <c:ticket id="13"/>
+          </c:tickets>
+        </c:change>
+        <c:change date="2021-06-27T16:34:56+00:00" summary="Fix a schema bug that rejected valid footnotes in documents"/>
+      </c:changes>
     </c:release>
   </c:releases>
   <c:ticket-systems>

diff --git a/com.io7m.xstructural.documentation/pom.xml b/com.io7m.xstructural.documentation/pom.xml
@@ -172,7 +172,10 @@
             </goals>
             <configuration>
               <excludes>module-info.java</excludes>
-              <includes>com/io7m/xstructural/xml/xstructural-7.xsd</includes>
+              <includes>
+                com/io7m/xstructural/xml/xstructural-7.xsd,
+                com/io7m/xstructural/xml/xstructural-7_1.xsd
+              </includes>
               <includeGroupIds>${project.groupId}</includeGroupIds>
               <includeArtifactIds>com.io7m.xstructural.xml</includeArtifactIds>
               <classifier>sources</classifier>

diff --git a/...ural.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-epub.xml b/...ural.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-epub.xml
@@ -17,7 +17,7 @@
       <LinkExternal target="https://github.com/w3c/epubcheck">EPUBCheck</LinkExternal>.
     </Paragraph>
     <FormalItem title="Parameters">
-      <Table type="parametersTable">
+      <Table type="genericTable">
         <Columns>
           <Column>Parameter</Column>
           <Column>Type</Column>
@@ -58,7 +58,7 @@
     </FormalItem>
   </Subsection>
 
-  <Subsection title="Example">
+  <Subsection title="Examples">
     <FormalItem title="Example" type="example">
       <Verbatim>
         <xi:include parse="text"

diff --git a/...al.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-schema.xml b/...al.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-schema.xml
@@ -14,7 +14,7 @@
       The <Term type="command">schema</Term> command exports the Structural schema files into a specified directory.
     </Paragraph>
     <FormalItem title="Parameters">
-      <Table type="parametersTable">
+      <Table type="genericTable">
         <Columns>
           <Column>Parameter</Column>
           <Column>Type</Column>
@@ -36,7 +36,7 @@
       </Table>
     </FormalItem>
   </Subsection>
-  <Subsection title="Example">
+  <Subsection title="Examples">
     <FormalItem title="Example">
       <Verbatim>
         <xi:include parse="text"

diff --git a/....documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-validate.xml b/....documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-validate.xml
@@ -14,7 +14,7 @@
       The <Term type="command">validate</Term> command validates a given document against the Structural schema.
     </Paragraph>
     <FormalItem title="Parameters">
-      <Table type="parametersTable">
+      <Table type="genericTable">
         <Columns>
           <Column>Parameter</Column>
           <Column>Type</Column>
@@ -30,7 +30,7 @@
       </Table>
     </FormalItem>
   </Subsection>
-  <Subsection title="Example">
+  <Subsection title="Examples">
     <FormalItem title="Example">
       <Verbatim>
         <xi:include parse="text"

diff --git a/...ral.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-xhtml.xml b/...ral.documentation/src/main/resources/com/io7m/xstructural/documentation/cmdline-xhtml.xml
@@ -15,7 +15,7 @@
       The <Term type="command">xhtml</Term> command produces XHTML pages for the given input document.
     </Paragraph>
     <FormalItem title="Parameters">
-      <Table type="parametersTable">
+      <Table type="genericTable">
         <Columns>
           <Column>Parameter</Column>
           <Column>Type</Column>
@@ -69,7 +69,7 @@
     </FormalItem>
   </Subsection>
 
-  <Subsection title="Example">
+  <Subsection title="Examples">
     <FormalItem title="Example" type="example">
       <Verbatim>
         <xi:include parse="text"

diff --git a/...ructural.documentation/src/main/resources/com/io7m/xstructural/documentation/document.css b/...ructural.documentation/src/main/resources/com/io7m/xstructural/documentation/document.css
@@ -20,34 +20,37 @@
 }
 
 .command,
+.constant,
+.element,
 .package,
-.parameter
+.parameter,
+.term
 {
   font-family: monospace;
 }
 
-.parametersTable
+.genericTable
 {
   border:          1px solid #dddddd;
   width:           100%;
   border-collapse: collapse;
 }
-.parametersTable th
+.genericTable th
 {
   text-align: left;
   padding-right: 1em;
   padding-bottom: 1em;
   font-size: var(--stFontSize);
 }
-.parametersTable td
+.genericTable td
 {
   border:         1px solid #dddddd;
   padding-right:  1em;
   padding-bottom: 0.5em;
   vertical-align: top;
   font-size: var(--stFontSize);
 }
-.parametersTable td:nth-child(1)
+.genericTable td:nth-child(1)
 {
   width: 12em;
 }
diff --git a/...ural.documentation/src/main/resources/com/io7m/xstructural/documentation/language-doc.xml b/...ural.documentation/src/main/resources/com/io7m/xstructural/documentation/language-doc.xml
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Section xmlns="urn:com.io7m.structural:7:0"
+         id="a49dac27-48f0-4504-8e03-8f0b73cd9c46"
+         title="Document">
+
+  <Subsection title="Description">
+    <Paragraph>
+      The <Term type="element">Document</Term> element describes the top-level structure of a document. A document
+      consists of <Link target="027296c3-c406-4191-a444-5b10873094e8">metadata</Link>, and a set of top-level
+      <Link target="cc5514e1-dc68-4b88-9374-fe09b8741140">sections</Link>
+      or
+      <Link target="55ae1912-9aec-402a-babe-ed7778e76599">subsections</Link>
+      (but not both).
+    </Paragraph>
+    <Paragraph>
+      A <Term type="element">Document</Term> must carry a <Term type="term">schema version declaration</Term> that
+      indicates to which version of the <Term type="term">structural</Term> language the document is expected to
+      confirm. This is achieved with the use of an <LinkExternal target="https://www.w3.org/TR/REC-xml-names/">xmlns
+    </LinkExternal> attribute on the <Term type="element">Document</Term> element. The currently published language
+      versions are:
+    </Paragraph>
+    <FormalItem title="Language Versions">
+      <Table type="genericTable">
+        <Columns>
+          <Column>Language</Column>
+          <Column>Identifier</Column>
+        </Columns>
+        <Row>
+          <Cell>Structural 7.0</Cell>
+          <Cell>urn:com.io7m.structural:7:0</Cell>
+        </Row>
+        <Row>
+          <Cell>Structural 7.1</Cell>
+          <Cell>urn:com.io7m.structural:7:1</Cell>
+        </Row>
+      </Table>
+    </FormalItem>
+  </Subsection>
+
+  <Subsection title="Tables Of Content">
+    <Paragraph>
+      Renderers encountering a <Term type="element">Document</Term> element will typically generate a table of contents
+      for the entire document. The <Term type="parameter">tableOfContentsDepth</Term> attribute on the <Term type="element">
+      Document
+    </Term> instructs renderers as to how far into the list of
+      <Link target="cc5514e1-dc68-4b88-9374-fe09b8741140">sections</Link>
+      or
+      <Link target="55ae1912-9aec-402a-babe-ed7778e76599">subsections</Link>
+      the rendering algorithm should recurse in order to generate the table of contents. For example, an author may
+      choose to only include top-level <Term type="element">Section</Term> elements in the table of contents and would
+      therefore specify <Term type="expression">tableOfContentsDepth="1"</Term>.
+    </Paragraph>
+  </Subsection>
+
+  <Subsection title="Identities" id="39506c3e-1361-4f81-be32-8c110a19d9bb">
+    <Paragraph>
+      Many elements within a <Term type="element">Document</Term> may be assigned <Term type="term">unique 
+      identifiers</Term>. A <Term type="term">unique identifier</Term> is a
+      <LinkExternal target="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</LinkExternal>
+      value specified using the <Term type="parameter">id</Term> attribute. It is possible to then link to
+      those elements from within the document text using the <Link
+      target="88660fca-74ea-4a3b-bb59-32d750a515a3">Link</Link>, and the schema will guarantee the
+      integrity of internal links at validation time.
+    </Paragraph>
+  </Subsection>
+
+  <Subsection title="Links">
+    <Paragraph>
+      As described in the <Link target="39506c3e-1361-4f81-be32-8c110a19d9bb">Identities</Link> section,
+      many significant elements in a document may be the target of the <Link
+      target="88660fca-74ea-4a3b-bb59-32d750a515a3">Link</Link> element. The <Term type="term">structural</Term> 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:
+    </Paragraph>
+    <FormalItem title="Link Types">
+      <ListUnordered>
+        <Item>
+          <Link target="88660fca-74ea-4a3b-bb59-32d750a515a3">Link</Link> - a link to a document element. Subject
+          to integrity checks at validation time.
+        </Item>
+        <Item>
+          <Link target="217b1f13-a98b-4fe7-a701-700073818f33">LinkExternal</Link> - a link to an external document
+          such as a web site. Not subject to integrity checks.
+        </Item>
+        <Item>
+          <Link target="b611d66f-e82d-4afd-b908-f27340718651">LinkFootnote</Link> - a link to a footnote.
+          Subject to integrity checks at validation time.
+        </Item>
+      </ListUnordered>
+    </FormalItem>
+  </Subsection>
+
+  <Subsection title="Types">
+    <Paragraph>
+      Most elements within documents allow for the specification of
+      <Term type="parameter">type</Term> attributes. The <Term type="parameter">type</Term> attribute is
+      used to add semantic tags to elements that can be interpreted by renderers in various ways. Typically,
+      the <Term type="parameter">type</Term> attribute is translated directly to a
+      <LinkExternal target="https://en.wikipedia.org/wiki/CSS">CSS</LinkExternal> 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 <Term type="package">xstructural</Term>
+      is always expressed as a <Link target="8265ab1b-7524-4af9-8415-3dc787bd959f">Term</Link> element
+      with a <Term type="parameter">type</Term> attribute set to <Term type="constant">package</Term>. 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
+      <Term type="parameter">type</Term> attribute purely for formatting, or alternatively can ignore it entirely.
+    </Paragraph>
+  </Subsection>
+
+  <Subsection title="Examples">
+    <FormalItem title="Document Example">
+      <Verbatim><![CDATA[
+<Document xmlns="urn:com.io7m.structural:7:0" tableOfContentsDepth="2" id="14ab90da-7947-420c-a5f8-d9c9c87fbddc">
+  ...
+</Document>
+]]></Verbatim>
+    </FormalItem>
+  </Subsection>
+</Section>
diff --git a/...documentation/src/main/resources/com/io7m/xstructural/documentation/language-footnote.xml b/...documentation/src/main/resources/com/io7m/xstructural/documentation/language-footnote.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Section xmlns="urn:com.io7m.structural:7:0"
+         id="8abc7eeb-c828-4307-a64d-0d8d6ae25e98"
+         title="Footnote">
+
+  <Subsection title="Description">
+    <Paragraph>
+      The <Term type="element">Footnote</Term> element describes a
+      <LinkExternal target="https://en.wikipedia.org/wiki/Note_(typography)">footnote</LinkExternal>.
+    </Paragraph>
+    <Paragraph>
+      Footnotes a rendered at the end of the <Link target="cc5514e1-dc68-4b88-9374-fe09b8741140">Section</Link>
+      within which they are declared, and may be referenced using
+      <Link target="b611d66f-e82d-4afd-b908-f27340718651">LinkFootnote</Link> elements.
+    </Paragraph>
+  </Subsection>
+
+  <Subsection title="Examples">
+    <FormalItem title="Footnote Example">
+      <Verbatim><![CDATA[
+<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>
+]]></Verbatim>
+    </FormalItem>
+  </Subsection>
+</Section>
diff --git a/...umentation/src/main/resources/com/io7m/xstructural/documentation/language-formal-item.xml b/...umentation/src/main/resources/com/io7m/xstructural/documentation/language-formal-item.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Section xmlns="urn:com.io7m.structural:7:0"
+         id="13029feb-2126-4d72-9151-63607152b7db"
+         title="FormalItem">
+
+  <Subsection title="Description">
+    <Paragraph>
+      The <Term type="element">FormalItem</Term> element is analogous to
+      a <Link target="01d0fde7-7742-47a9-864c-b9c55e2e9980">Paragraph</Link>
+      except that it has a defined title. A <Term type="element">FormalItem</Term> element
+      is commonly used to represent an object similar to a
+      <Term type="term">figure</Term> in printed books.
+    </Paragraph>
+    <Paragraph>
+      <Term type="element">FormalItem</Term> elements consist entirely of
+      <Link target="8e536f96-16e1-4f4a-bc3a-6613e20cb504">inline content</Link>.
+    </Paragraph>
+    <Paragraph>
+      <Term type="element">FormalItem</Term> elements are numbered with respect
+      to other <Term type="element">FormalItem</Term> and
+      <Link target="01d0fde7-7742-47a9-864c-b9c55e2e9980">Paragraph</Link>
+      elements within the same
+      <Link target="cc5514e1-dc68-4b88-9374-fe09b8741140">Section</Link>
+      or
+      <Link target="55ae1912-9aec-402a-babe-ed7778e76599">Subsection</Link>.
+    </Paragraph>
+  </Subsection>
+
+  <Subsection title="Examples">
+    <Paragraph>
+      This example is, itself, a <Term type="element">FormalItem</Term> element.
+    </Paragraph>
+    <FormalItem title="FormalItem Example">
+      <Verbatim><![CDATA[
+<Subsection xmlns="urn:com.io7m.structural:7: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>
+]]></Verbatim>
+    </FormalItem>
+  </Subsection>
+</Section>