The jstructural package implements a set of primitives for producing technical documentation. The package provides a RELAX-NG schema describing the format of structural documents and a set of Java tools for producing XHTML 1.0 Strict output.

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 document you are currently reading was defined in the structural language.

The provided structural to XHTML translator is written in pure Java and should be usable on any JVM that supports Java 6 and newer.

As the structural language focuses only on structural elements, it is far simpler than any of the other XML documentation formats. As an example, DocBook, which mixes structural and semantic elements, defines nearly 400 elements as opposed to the 30 or so defined by the structural language.

Given the small number of elements and the relatively strict schema, the number of possible permutations of elements is low and, as a result, the XHTML output is easily predictable [0].

The project can be compiled and installed with Maven:

$ mvn -C clean install

If only the command-line jsc tool is required, it can be downloaded directly from Maven Central (PGP).

The jstructural API is divided into core and annotated types. The core types have an (almost) 1:1 correspondence with the elements that a document author writes in XML. The parser included with the XOM backend, for example, produces a document consisting of elements of the core types from an XML file. The annotated types are, unsurprisingly, values of the core types with additional annotations and metadata required to actually produce documents in XHTML format.

Parsing documents and producing XHTML output is quite simple. First, a stream representing an XML file is given to the included parser, which parses and validates the document against the structural schema.

Then, the resulting document is annotated with the included annotator:

Finally, either the single-page writer or multi-page writer are used to produce a set of XHTML documents that can be serialized using the standard XOM serializer.

The map returned by the writeDocuments function is a set of mappings from file names to documents.

The writers take a set of callbacks as arguments that can be used to customize the resulting output. See the javadoc for details.

The jsc tool transforms structural documents into XHTML 1.0 Strict.

jsc: [options] --check        file
  or [options] --xhtml-single file outdir
  or [options] --xhtml-multi  file outdir
  or [options] --version

     --check                      Parse and validate all source files, but do not produce output
     --debug                      Enable debugging (debug messages, exception backtraces)
  -h,--help                       Show this help message
     --version                    Display version
     --xhtml-body-end <file>      Insert the given file into the resulting XHTML at the end of the document's body
     --xhtml-body-start <file>    Insert the given file into the resulting XHTML at the start of the document's body
     --xhtml-multi                Produce multiple XHTML files as output
     --xhtml-single               Produce a single XHTML file as output

When the --check argument is specified, the file file is parsed and validated according to the structural schema. XIncludes are understood by jsc and will be processed prior to validation.

When the --xhtml-single argument is specified, the given file is validated exactly as with --check, and then a single XHTML 1.0 Strict document is written to outdir/index.xhtml. The outdir directory is created iff it does not already exist.

When the --xhtml-multi argument is specified, the given file is validated exactly as with --check, and then a single XHTML 1.0 Strict document is written to outdir/index-m.xhtml, which represents the front page of the document, and a series of files are written to outdir/*.xhtml, representing the parts and sections of the document. The outdir directory is created iff it does not already exist.

When either --xhtml-multi or --xhtml-single are specified, the files outdir/jstructural-5.0.0-layout.css and outdir/jstructural-5.0.0-colour.css are created iff they do not already exist. These files contain CSS controlling the visual presentation of the XHTML.

The --xhtml-body-start option causes the contents of the given XML file to be inserted as the first child of the resulting XHTML body element on each page. It is the user's responsibility to ensure that the resulting document is valid XHTML 1.0 Strict.

The --xhtml-body-end option causes the contents of the given XML file to be inserted as the last child of the resulting XHTML body element on each page. It is the user's responsibility to ensure that the resulting document is valid XHTML 1.0 Strict.

The jsc tool is packaged into the standalone io7m-jstructural-tools-5.0.0-jsc.jar file distributed with jstructural.

All structural elements are in the http://schemas.io7m.com/structural/2.1.0 namespace.

All elements may have the standard xml:lang and xml:base attributes.

The following elements may have a type attribute and an xml:id attribute:

• document
• formal-item
• image
• list-item
• list-ordered
• list-unordered
• paragraph
• part
• section
• subsection
• term
• verbatim

The contents of the type attribute are appended to the resulting CSS class attribute of the element in the XHTML output.

Elements with an xml:id attribute can be linked to using the link element.

When the XSLT stylesheet encounters an xml:id attribute on an element, it generates an XHTML anchor with an id attribute consisting of the original xml:id attribute contents prefixed with "ref_". This allows linking to specific elements in the resulting XHTML documents from external locations. As an example, given an element:

<s:term s:type="something" xml:id="a_term">Hello</s:term>

The XHTML output will be similar to:

<a id="ref_a_term"></a>
<span class="st200_term something">Hello</span>

The XHTML elements resulting from each structural element are assigned specific CSS classes for easy styling of the output. The CSS classes are documented with each element.

A navigation bar is placed at the top and bottom each generated page.

For pages generated from section or part elements, the navigation bar contains links to the previous and next pages, and the enclosing section or part. The navigation bar also displays the titles of the destination pages above each link. For pages generated from document elements, only a link to the first section or part element is generated.

The navigation bar itself is assigned the CSS class st200_navbar in addition to the class st200_navbar_top or st200_navbar_bottom depending on where the bar in question appears on the page.

The bar is a table structure with each cell being assigned one of the following CSS classes:

• st200_navbar_prev_file_cell
• st200_navbar_up_file_cell
• st200_navbar_next_file_cell
• st200_navbar_prev_title_cell
• st200_navbar_up_title_cell
• st200_navbar_next_title_cell

The document element denotes a structural document. It must appear as the root node of an XML document. The element may contain either a series of sections or a series of parts.

document elements appear in table of contents entries (usually as the root), labelled with their respective document-title.

The document element creates a new output file when encountered.

The following elements may occur as children of document elements:

• document-contents
• document-style
• document-title
• part
• section

The document-contents element specifies that a table of contents should be generated for the given document.

Iff the document in question contains part elements, subsection elements are omitted from the list.

The table of contents appears at the start of the parent document and contains references to all the children of that element.

In addition to any classes specified by the type attribute, the main XHTML structure is assigned the class st200_document_contents in addition to st200_contents.

Each element of the list is assigned the class st200_contents_item in addition to one of st200_contents_item1, st200_contents_item2 or st200_contents_item3 depending on the depth of the item in the list.

All part and section elements appearing in the list are assigned the classes st200_contents_part and st200_contents_section, respectively.

The document-style element specifies an additional CSS file for the given document.

The document-style element causes a link to the given CSS file to be placed in all output files generated for the given document.

The document-style element may only contain text.

The document-title element specifies the title of the given document.

The XHTML element generated by the document-title element is assigned the CSS st200_document_title in addition to any specified by the type attribute.

The footnote element denotes sections of text that will appear at the bottom of the current page with numbered hyperlink references placed in the original text. footnote elements are numbered relative to the ancestor document. footnote elements may themselves contain footnotes.

The following elements may occur as children of footnote elements:

• footnote
• image
• link
• link-external
• list-ordered
• list-unordered
• table
• term
• verbatim

footnote elements may also, obviously, contain text.

The footnote element causes a section to be generated at the bottom of the page. This section is assigned the class st200_footnotes. Each footnote is displayed as a form of numbered list. The number is assigned the class st200_footnote_number and the body of each footnote appears in a section with the class st200_footnote_body.

This paragraph contains a footnote [4].

The formal-item element provides a means to mark certain other elements as significant. formal-item elements are numbered relative to the containing section or subsection and rendered with the given formal-item-title.

formal-item elements must be classified by specifying a value for the kind attribute. This allows rendering of lists of formal-item elements of a given kind using the formal-item-list element.

The following elements may occur as children of formal-item elements:

• formal-item-list
• image
• list-ordered
• list-unordered
• table
• verbatim

The XHTML elements generated by the formal-item element is assigned the CSS class st200_formal_item in addition to any specified by the type attribute.

The title element of the generated element is assigned the class st200_formal_item_title.

The formal-item-list element renders a list of all formal-item elements of the kind specified by the kind attribute.

The XHTML element generated by the formal-item-list element is assigned the CSS class st200_formal_item_list in addition to any specified by the type attribute.

Each element of the list is assigned the class st200_formal_item_list_item.

The title of the element is assigned the class st200_formal_item_list_title.

A formal-item-list placed inside a formal-item:

The formal-item-title element specifies the title of the given formal-item.

formal-item-title elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_formal_item_title
• st200_formal_item_title_number

The image element inserts the image specified by the source attribute into the XHTML output. The width and height may optionally be specified with the width and height attributes, respectively. The text contents of the element are used in the XHTML if the image cannot be loaded[5].

image elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_image

The link element generates a hyperlink to the element with the given xml:id attribute (specified by the given target attribute) using the text enclosed by the link element as the hyperlink text.

The link element depends on the XML validator to check link integrity. The XSLT stylesheets make no attempt to verify the validity or existence of link targets.

The following elements may occur as children of link elements:

• image

link elements may also contain text.

link elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_link

The following text:

<link s:target="elem_paragraph">paragraph</link>

Produces the following output in the context of this document: paragraph.

The following text:

<paragraph><link s:target="elem_paragraph"><image s:source="strawberry.png">Strawberry</image></paragraph></link>

Produces the following output in the context of this document:

The following text:

<s:link s:target="elem_formal-item.example">formal-item</s:link>

Produces the following output in the context of this document: formal-item.

The link-external element generates a hyperlink to an external WWW address specified by the given target attribute, using the text enclosed by the element as the hyperlink text.

The following elements may occur as children of link-external elements:

• image

link-external elements may also contain text.

link-external elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_link_external

The following text:

<link-external s:target="http://www.io7m.com">io7m</link-external>

Produces the following output in the context of this document: io7m.

The following text:

<paragraph><link-external s:target="http://www.io7m.com"><image s:source="strawberry.png">Strawberry</image></paragraph></link-external>

Produces the following output in the context of this document:

The list-item element denotes an item in an ordered or unordered list.

The following elements may occur as children of list-item elements:

• footnote
• image
• link
• link-external
• list-ordered
• list-unordered
• term
• verbatim

list-item elements may also contain text.

list-item elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_list_item

The list-ordered element denotes a list of elements. The individual list items are numbered.

The following elements may occur as children of list-ordered elements:

• list-item

list-ordered elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_list_ordered

The list-ordered element denotes a list of elements. The individual list items are bulleted.

The following elements may occur as children of list-unordered elements:

• list-item

list-unordered elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_list_unordered

The paragraph element denotes sections of text within a section or subsection. paragraph elements are numbered relative to the enclosing element but do not have titles.

The following elements may occur as children of paragraph elements:

• footnote
• formal-item-list
• image
• link
• link-external
• list-ordered
• list-unordered
• table
• term
• verbatim

paragraph elements may also, obviously, contain text.

paragraph elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_paragraph
• st200_paragraph_number

The part element denotes a significant section of a document element, of which it may appear as a child. The element must contain a series of sections.

part elements appear in table of contents entries, labelled with their respective part-title.

For the multi-page stylesheets, the part element creates a new output file when encountered.

The following elements may occur as children of part elements:

• part-contents
• part-title
• section

part elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_part

The part-contents element specifies that a table of contents should be generated for the given part.

The table of contents appears at the start of the parent part and contains references to all the children of that element.

In addition to any classes specified by the type attribute, the main list structure is assigned the class st200_part_contents.

The XHTML lists that are generated as children of the lists generated for document-contents elements are assigned CSS as if they were generated from part-contents elements. In order to correctly indent elements in CSS, it's necessary to be able to distinguish between lists that were generated as part of a part-contents element, and lists that were generated as children of those generated as part of a document-contents element. In other words, it's desirable to be able to indent the list differently if it is the "outermost" list. Therefore, the main list structure is also assigned the class st200_part_contents_outer if it is appearing in XHTML due to a part-contents element.

Each element of the list is assigned the class st200_contents_item in addition to one of st200_contents_item1, st200_contents_item2 or st200_contents_item3 depending on the depth of the item in the list. The root part element of the list is assigned the class st200_contents_part and all section and subsection elements appearing in the list are assigned the classes st200_contents_section and st200_contents_subsection, respectively.

The part-title element specifies the title of the given part.

part-title elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_part_title
• st200_part_title_number

The section element denotes a less significant section of the document than the part element, of which it may appear as a child. The element may contain either a series of subsections or a series of paragraphs.

section elements appear in table of contents entries, labelled with their respective section-title.

For the multi-page stylesheets, the section element creates a new output file when encountered.

The following elements may occur as children of section elements:

• paragraph
• section-contents
• section-title
• subsection

section elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_section

This page is contained within one section element.

The section-contents element specifies that a table of contents should be generated for the given section.

The table of contents appears at the start of the parent section and contains references to all the children of that element.

In addition to any classes specified by the type attribute, the main list structure is assigned the classes st200_section_contents and st200_contents.

The XHTML lists that are generated as children of the lists generated for part-contents elements are assigned CSS as if they were generated from section-contents elements. In order to correctly indent elements in CSS, it's necessary to be able to distinguish between lists that were generated as part of a section-contents element, and lists that were generated as children of those generated as part of a part-contents element. In other words, it's desirable to be able to indent the list differently if it is the "outermost" list. Therefore, the main list structure is also assigned the class st200_section_contents_outer if it is appearing in XHTML due to a section-contents element.

Each element of the list is assigned the class st200_contents_item in addition to st200_contents_item1. All subsection elements appearing in the list are assigned the class st200_contents_subsection.

The table of contents above was generated by adding a section-contents element at the beginning of the section.

The section-title element specifies the title of the given section.

section-title elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_section_title
• st200_section_title_number

The 'section-title' text above was specified with the section-title element.

The subsection element denotes a less significant section of the document than the section element, of which it may appear as a child.

subsection elements appear in table of contents entries, labelled with their respective subsection-title.

The following elements may occur as children of subsection elements:

• paragraph
• subsection-title

This 'Example' section is a subsection containing one paragraph.

subsection elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_subsection

The subsection-title element specifies the title of the given subsection.

subsection-title elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_subsection_title
• st200_subsection_title_number

The 'Example' title of this subsection was specified with:

<s:subsection-title>Example</s:subsection-title>

The table element allows the specification of tabular data.

The following elements may occur as children of table elements:

• table-body
• table-head
• table-summary

table elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_table

The following text:

<table>
  <table-summary>Summary</table-summary>
  <table-head>
    <table-column-name>First</table-column-name>
    <table-column-name>Second</table-column-name>
    <table-column-name>Third</table-column-name>
  </table-head>
  <table-body>
    <table-row>
      <table-cell>Cell 1</table-cell>
      <table-cell>Cell 2</table-cell>
      <table-cell>Cell 3</table-cell>
    </table-row>
    <table-row>
      <table-cell>Cell 1</table-cell>
      <table-cell>Cell 2</table-cell>
      <table-cell>Cell 3</table-cell>
    </table-row>
  </table-body>
</table>

Produces the following output in the context of this document:

First	Second	Third
Cell 1	Cell 2	Cell 3
Cell 1	Cell 2	Cell 3

The table-body element denotes the rows and cells of the parent table element.

The following elements may occur as children of table-body elements:

• table-row

table-body elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_table_body

The table-cell element denotes a cell in a row of a table element.

The following elements may occur as children of table-cell elements:

• footnote
• image
• link
• link-external
• list-ordered
• list-unordered
• term
• verbatim

table-cell elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_table_cell

The table-column-name element allows the specification of column names for table elements.

table-column-name elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_table_column_name

The table-head element allows the optional specification of column names for table elements.

The following elements may occur as children of table-head elements:

• table-column-name

table-head elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_table_head

The table-row element denotes a row of cells in a table element.

The following elements may occur as children of table-row elements:

• table-cell

table-row elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_table_row

The table-summary element allows the specification of a summary for table elements.

The summary is required to pass XHTML Strict validity checks; it is otherwise invisible in the output.

The term element denotes a significant element of a section of text. It is usually used to highlight or mark individual words in order to assign them a particular CSS class.

term elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_term

The following text:

<term s:type="element">ELEMENT</term>

Produces the following output in the context of this document: ELEMENT.

The verbatim element denotes a section of text in which whitespace should be preserved exactly as it was written. It is analogous to the XHTML pre element.

For best results, the contents of the verbatim element should be contained within an XML <![CDATA[...]]> element to prevent possible interference from the XML processor.

verbatim elements are assigned the following CSS classes in addition to any specified by the type attribute:

• st200_verbatim