io7m-jstructural 5.0.0 Documentationdocumentation.cssPackage InformationOrientationOverview
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.
Portability
The provided structural to XHTML
translator is written in pure Java and should be usable on any JVM
that supports Java 6 and newer.
Simplicity
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
There are various combinations of DocBook elements that are
valid according to the schema but cannot realistically be used due to
the resulting XHTML output..
InstallationSource compilation
The project can be compiled and installed with
Maven:
Command-line Tools
If only the command-line jsc tool
is required, it can be downloaded directly from
Maven Central
(PGP).
Platform Specific Issues
There are no known platform-specific issues.
License
All files distributed with the structural
package are placed under the following license:
http://io7m.com
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.]]>
Exceptions to the above are the files:
Schema filesio7m-jstructural-tests/src/test/resources/com/io7m/jstructural/tests/xhtml1-strict.xsdio7m-jstructural-tests/src/test/resources/com/io7m/jstructural/tests/xml.xsd
These files are the XSD schema for XHTML Strict 1.0
http://www.w3.org/TR/xhtml1-schema/
and are used by the test suite to validate the XHTML output produced by all
test documents. They are included to allow the test suite to execute
on machines that do not have network access (and therefore cannot fetch
the schema files from the w3 servers).
They are covered by at least one of the w3's
many licenses
http://www.w3.org/Consortium/Legal/. Unfortunately, we're not exactly sure which. No infringement
is intended.
API TutorialAPI TutorialOverview
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.
Usage
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.
Parsing
URI uri;
Log log;
InputStream stream;
final SDocument doc = SDocumentParser.fromStream(stream, uri, log);
Then, the resulting document is annotated with the included
annotator:
Annotation
Log log;
SDocument doc;
final SADocument adoc = SAnnotator.document (doc, log);
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.
Writing
Log log;
SADocument doc;
SDocumentXHTMLWriterCallbacks callbacks;
SDocumentXHTMLWriterSingle writer = new SDocumentXHTMLWriterSingle();
SortedMap<String, Document> pages = writer.writeDocuments(callbacks, doc);
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.
API ReferenceJavadoc
API documentation for the packages is provided via the
included Javadoc.
Tool ReferencejscOverview
The jsc tool transforms
structural documents into
XHTML 1.0 Strict.
Insert the given file into the resulting XHTML at the end of the document's body
--xhtml-body-start 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.
Packaging
The jsc tool is packaged into the
standalone io7m-jstructural-tools-5.0.0-jsc.jar
file distributed with jstructural.
Element ReferenceOverviewNamespace URI
All
structural
elements
are in the
http://schemas.io7m.com/structural/2.1.0
namespace.
Attributes
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:
documentformal-itemimagelist-itemlist-orderedlist-unorderedparagraphpartsectionsubsectiontermverbatim
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:
Hello]]>
The XHTML output will be similar to:
Hello]]>CSS
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.
Navigation Bar
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_cellst200_navbar_up_file_cellst200_navbar_next_file_cellst200_navbar_prev_title_cellst200_navbar_up_title_cellst200_navbar_next_title_celldocumentDescription
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.
Processing
The document
element creates a new output file when encountered.
Children
The following elements may occur as children of
document elements:
document-contentsdocument-styledocument-titlepartsectiondocument-contentsDescription
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.
Processing
The table of contents appears at the start of the
parent document
and contains references to all the children of that
element.
CSS
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.
document-styleDescription
The document-style
element specifies an additional CSS file for the
given document.
Processing
The document-style
element causes a link to the given CSS file to be
placed in all output files generated for the given
document.
Children
The document-style
element may only contain text.
document-titleDescription
The document-title
element specifies the title of the given
document.
CSS
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.
footnoteDescription
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.
Children
The following elements may occur as children of
footnote
elements:
footnoteimagelinklink-externallist-orderedlist-unorderedtabletermverbatimfootnote elements may also, obviously,
contain text.
CSS
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.
Example
This paragraph contains a footnote
This footnote also contains a footnote
This footnote does not contain a footnote..
.
formal-itemDescription
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.
Children
The following elements may occur as children of
formal-item elements:
formal-item-listimagelist-orderedlist-unorderedtableverbatimCSS
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.
ExampleExample Formal Itemformal-item-listDescription
The formal-item-list
element renders a list of all
formal-item
elements of the kind specified by the
kind attribute.
CSS
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.
Example
A formal-item-list placed inside
a formal-item:
Example Formal Item ListExample Formal Item List (Examples)formal-item-titleDescription
The formal-item-title
element specifies the title of the given
formal-item.
CSSformal-item-title
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_formal_item_titlest200_formal_item_title_numberExampleA Formal Item With An Unusual TitleimageDescription
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 loadedIn the alt
attribute of the resulting img..
CSSimage elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_imageExamplelinkDescription
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.
Children
The following elements may occur as children of
link elements:
imagelink elements may also contain
text.
CSSlink elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_linkExample
The following text:
paragraph]]>
Produces the following output in the context of this document:
paragraph.
The following text:
Strawberry]]>
Produces the following output in the context of this document:
The following text:
formal-item]]>
Produces the following output in the context of this document:
formal-item.
link-externalDescription
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.
Children
The following elements may occur as children of
link-external elements:
imagelink-external elements may also contain
text.
CSSlink-external elements are
assigned the following CSS classes in addition to any specified
by the type attribute:
st200_link_externalExample
The following text:
io7m]]>
Produces the following output in the context of this document:
io7m.
The following text:
Strawberry]]>
Produces the following output in the context of this document:
list-itemDescription
The list-item
element denotes an item in an
ordered
or unordered
list.
Children
The following elements may occur as children of
list-item
elements:
footnoteimagelinklink-externallist-orderedlist-unorderedtermverbatimlist-item
elements may also contain text.
CSSlist-item
elements are assigned the following CSS classes in addition to any
specified by the type
attribute:
st200_list_itemlist-orderedDescription
The list-ordered
element denotes a list of elements. The individual
list items are numbered.
Children
The following elements may occur as children of
list-ordered
elements:
list-itemCSSlist-ordered
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_list_orderedlist-unorderedDescription
The list-ordered
element denotes a list of elements. The individual
list items are bulleted.
Children
The following elements may occur as children of
list-unordered
elements:
list-itemCSSlist-unordered
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_list_unorderedparagraphDescription
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.
Children
The following elements may occur as children of
paragraph elements:
footnoteformal-item-listimagelinklink-externallist-orderedlist-unorderedtabletermverbatimparagraph
elements may also, obviously, contain text.
CSSparagraph
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_paragraphst200_paragraph_numberpartDescription
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.
Processing
For the multi-page stylesheets, the
part
element creates a new output file when encountered.
Children
The following elements may occur as children of
part elements:
part-contentspart-titlesectionCSSpart
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_partpart-contentsDescription
The part-contents
element specifies that a table of contents should
be generated for the given part.
Processing
The table of contents appears at the start of the
parent part
and contains references to all the children of that
element.
CSS
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.
part-titleDescription
The part-title
element specifies the title of the given
part.
CSSpart-title
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_part_titlest200_part_title_numbersectionDescription
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.
Processing
For the multi-page stylesheets, the
section
element creates a new output file when encountered.
Children
The following elements may occur as children of
section
elements:
paragraphsection-contentssection-titlesubsectionCSSsection
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_sectionExample
This page is contained within one
section element.
section-contentsDescription
The section-contents
element specifies that a table of contents should
be generated for the given
section.
Processing
The table of contents appears at the start of the
parent section
and contains references to all the children of that
element.
CSS
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.
Example
The table of contents above was generated by adding a
section-contents
element at the beginning of the section.
section-titleDescription
The section-title
element specifies the title of the given
section.
CSSsection-title
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_section_titlest200_section_title_numberExample
The 'section-title' text above was specified with the
section-title
element.
subsectionDescription
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.
Children
The following elements may occur as children of
subsection
elements:
paragraphsubsection-titleExample
This 'Example' section is a subsection containing one paragraph.
CSSsubsection
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_subsectionsubsection-titleDescription
The subsection-title
element specifies the title of the given
subsection.
CSSsubsection-title
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_subsection_titlest200_subsection_title_numberExample
The 'Example' title of this subsection was specified with:
Example]]>tableDescription
The table element allows the
specification of tabular data.
Children
The following elements may occur as children of
table
elements:
table-bodytable-headtable-summaryCSStable elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_tableExample
The following text:
SummaryFirstSecondThirdCell 1Cell 2Cell 3Cell 1Cell 2Cell 3
]]>
Produces the following output in the context of this document:
SummaryFirstSecondThirdCell 1Cell 2Cell 3Cell 1Cell 2Cell 3table-bodyDescription
The table-body element denotes
the rows and cells of the parent
table element.
Children
The following elements may occur as children of
table-body
elements:
table-rowCSStable-body elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_table_bodytable-cellDescription
The table-cell element denotes
a cell in a row of a table
element.
Children
The following elements may occur as children of
table-cell
elements:
footnoteimagelinklink-externallist-orderedlist-unorderedtermverbatimCSStable-cell elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_table_celltable-column-nameDescription
The table-column-name element allows
the specification of column names for
table elements.
CSStable-column-name elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_table_column_nametable-headDescription
The table-head element allows the
optional specification of column names for
table elements.
Children
The following elements may occur as children of
table-head
elements:
table-column-nameCSStable-head elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_table_headtable-rowDescription
The table-row element denotes
a row of cells in a table
element.
Children
The following elements may occur as children of
table-row
elements:
table-cellCSStable-row elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_table_rowtable-summaryDescription
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.
termDescription
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.
CSSterm elements are assigned the
following CSS classes in addition to any specified by the
type attribute:
st200_termExample
The following text:
ELEMENT]]>
Produces the following output in the context of this document:
ELEMENT.
verbatimDescription
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.
CSSverbatim
elements are assigned the following CSS classes in addition to any
specified by the type attribute:
st200_verbatim