<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>
Xport Brochure
</title>
<style type='text/css'>
body {
margin: 0px;
font: 9pt Verdana, Times, Sans-serif;
line-height: 130%;
background-color: #ffeeff;
}
#content {
width: 800px;
margin-left: auto;
margin-right: auto;
margin-top: 10px;
padding-bottom: 0px;
border: 5px outset #333333;
background-color: #ffffee;
}
p {
margin-left: 10px;
margin-right: 10px;
margin-bottom: 7px;
margin-top: 10px;
}
table {
margin-left: 10px;
margin-right: 10px;
}
#heading {
padding-top: 15px;
height: 50px;
background-color: #99ffff;
border-bottom: 6px solid #cc0000;
}
#heading h1 {
color: #cc0000;
margin-left: 10px;
margin-top: 0px;
margin-bottom: 12px;
}
#heading h4 {
color: #000033;
margin-left: 50px;
margin-top: 5px;
font-size: 11pt;
}
h5 {
color: #000066;
margin-left: 10px;
margin-bottom: 3px;
font-size: 10pt;
}
h6 {
text-align: right;
margin-right: 30px;
margin-top: 5px;
}
h4 {
margin-left: 10px;
color: #660000;
font-size: 12pt;
}
code {
color: #330099;
font-size: 10pt;
font-family: monospace;
}
em {
font-weight: 700;
}
p.class_descr {
margin-left: 25px;
margin-top: 5px;
}
.code_block {
margin-left: 25px;
margin-top: 5px;
background-color: #cccccc;
border: 2px solid #777777;
padding: 4px;
}
#doc_type_list {
color: maroon;
margin-top: 2px;
margin-bottom: 2px;
}
#class_categories {
color: #660066;
margin-top: 2px;
margin-bottom: 2px;
}
table.type_alias {
border-collapse: collapse;
border: thin solid black;
font-size: 9pt;
width: 97%;
background-color: #ffdddd;
}
table.type_alias td {
border: thin solid gray;
text-align: center;
}
table.type_alias .alias_hdr {
background-color: #cccccc;
}
table.type_alias th {
border: thin solid black;
background-color: #eeeeee;
}
table.type_alias .default_type {
color: blue;
}
.tbl_div {
width: 60%;
float: left;
margin-right: 10px;
}
#iter_tbl_div {
width: 90%;
}
.clear_left {
clear: left;
}
#footer {
height: 40px;
background-color: #99ff66;
width: 100%;
border-top: 5px outset #333333;
margin-bottom: 0px;
padding-bottom: 0px;
}
#footer p {
text-align: center;
vertical-align: middle;
color: #000066;
}
</style>
</head>
<body>
<div id='content'>
<div id='heading'>
<h1>
Xport
</h1>
<h4>
xhtml Parsing & Objective Reporting Toolkit
</h4>
</div>
<p>
Xport is a C++ toolkit library, which allows users to easily generate
and parse xhtml documents and stylesheets. With Xport, and some (x)html
knowledge, users can create rich xhtml documents for reporting purposes
or any other purpose.
</p>
<p>
Xport includes the ability to generate and parse the three most popular
types of xhtml documents.
</p>
<ul id='doc_type_list'>
<li>
xhtml strict
</li>
<li>
xhtml transitional
</li>
<li>
xhtml frameset
</li>
</ul>
<p>
Of the three document types listed above, <em>xhtml strict</em> is
considered to be the default document type in Xport.
</p>
<p>
Xport consists entirely of template classes. Xport also supports both
standard (narrow) and wide <em>character types</em>.
</p>
<p>
Xport's template classes can be grouped in three categories.
</p>
<ul id='class_categories'>
<li>
xhtml template classes
</li>
<li>
stylesheet template classes
</li>
<li>
iterator template classes
</li>
</ul>
<p>
Although all classes in Xport are class templates, users of the library
do not have to work directly with these template classes, as Xport
declares <em>type aliases</em> for all classes, document types, and
character types. The three categories of interface types in Xport are
discussed below.
</p>
<h4>
xhtml classes
</h4>
<p>
Xport's xhtml classes support the functionality of creating and parsing
xhtml documents. As mentioned above, Xport consists entirely of class
templates, but type aliases are declared for all the interface classes
for user convenience. The xhtml template classes are paramatized on two
types, the <em>document type</em> and the <em>character type</em>. The
list below reveals all Xports xhtml interface class templates, and the
type aliases available for those classes.
</p>
<table class='type_alias'>
<colgroup>
<col class='template_col'/>
</colgroup>
<tr>
<th class='alias_hdr' rowspan='2'>
class template
</th>
<th class='alias_hdr' colspan='6'>
type alias
</th>
</tr>
<tr>
<th>
xhtml strict
</th>
<th>
wchar xhtml strict
</th>
<th>
xhtml transitional
</th>
<th>
wchar xhtml transitional
</th>
<th>
xhtml frameset
</th>
<th>
wchar xhtml frameset
</th>
</tr>
<tr>
<th>
xhtml_doc
</th>
<td class='default_type'>
document
</td>
<td>
wdocument
</td>
<td>
tdocument
</td>
<td>
wtdocument
</td>
<td>
fdocument
</td>
<td>
wfdocument
</td>
</tr>
<tr>
<th>
xhtml_markup
</th>
<td class='default_type'>
markup
</td>
<td>
wmarkup
</td>
<td>
tmarkup
</td>
<td>
wtmarkup
</td>
<td>
fmarkup
</td>
<td>
wfmarkup
</td>
</tr>
<tr>
<th>
xhtml_element
</th>
<td class='default_type'>
element
</td>
<td>
welement
</td>
<td>
telement
</td>
<td>
wtelement
</td>
<td>
felement
</td>
<td>
wfelement
</td>
</tr>
<tr>
<th>
xhtml_pcdata
</th>
<td class='default_type'>
pcdata
</td>
<td>
wpcdata
</td>
<td>
tpcdata
</td>
<td>
wtpcdata
</td>
<td>
fpcdata
</td>
<td>
wfpcdata
</td>
</tr>
<tr>
<th>
xhtml_comment
</th>
<td class='default_type'>
comment
</td>
<td>
wcomment
</td>
<td>
tcomment
</td>
<td>
wtcomment
</td>
<td>
fcomment
</td>
<td>
wfcomment
</td>
</tr>
<tr>
<th>
xhtml_processing_instruction
</th>
<td class='default_type'>
procinstr
</td>
<td>
wprocinstr
</td>
<td>
tprocinstr
</td>
<td>
wtprocinstr
</td>
<td>
fprocinstr
</td>
<td>
wfprocinstr
</td>
</tr>
<tr>
<th>
xhtml_formatter
</th>
<td class='default_type'>
formatter
</td>
<td>
wformatter
</td>
<td>
tformatter
</td>
<td>
wtformatter
</td>
<td>
fformatter
</td>
<td>
wfformatter
</td>
</tr>
<tr>
<th>
xhtml_parser
</th>
<td class='default_type'>
parser
</td>
<td>
wparser
</td>
<td>
tparser
</td>
<td>
wtparser
</td>
<td>
fparser
</td>
<td>
wfparser
</td>
</tr>
</table>
<h6>
Table 1: Xport's xhtml class templates and type aliases
</h6>
<p>
Xport's default document type is xhtml strict, which is colored blue in
the table above. Most of the example reports will reflect this document
type. Thus, users of the library will normally use only the type aliases
in blue above to create documents.
</p>
<p>
A brief description of Xport's xhtml types is given below. The default
type alias names will be used to describe the different xhtml types
available.
</p>
<h5>
document
</h5>
<p class='class_descr'>
In Xport, the <em>document</em> type encapsulates an xhtml document. The <code>
document</code> object is one of the most important objects you'll
utilize. The <code>document</code> object organizes it's content in a
tree structure, or <em>document tree</em>. A standard xhtml document
normally contains the elements <code>html</code>, <code>head</code>, <code>
title</code>, and <code>body</code> elements. These elements are known
in Xport as the <em>root elements</em> and a <code>document</code> which
contain these root elements is considered a <em>root document</em>.
When you create a <code>document</code> object, you can optionally
create it as a root document, with those root elements included. Those
root elements, and all other elements contained within, form the
document tree. Once content has been added to the <code>document</code>
, the <code>document</code> can be written to a file or stream. <code>
document</code> objects can also parse xhtml files, as well as html
files. The results of parsing html files will vary, depending on the
form of the html file.
</p>
<h5>
markup
</h5>
<p class='class_descr'>
<code>markup</code> is the base type for <code>element</code>, <code>
comment</code>, and <code>procinstr</code>. <code>markup</code> is
used mainly with the use of Xport's <em>markup iterators</em>, which
are discussed further below. All markup iterators return references and
pointers to <code>markup</code> objects, which are actually objects
derived from <code>markup</code>. So, the interface of <code>markup
</code> is very important indeed, as it is only through <code>markup
</code>'s interface that we're able to access those objects derived from <code>
markup</code>, when working with markup iterators.
</p>
<h5>
element
</h5>
<p class='class_descr'>
Xport's <code>element</code> type encapsulates an xhtml element. <code>
element</code> objects are used more frequently than any other object
type when creating content for the document. An <code>element</code>
object is the only <code>markup</code> object which can contain other <code>
markup</code> objects, giving <code>element</code> objects the
responsibility of making up the document tree. There are a number of
ways to add and insert other <code>markup</code> objects into <code>
element</code> objects, which are all detailed in the documentation and
examples. Xport will only allow elements to be inserted in other
elements which do not violate the document type specifications for the
document type used. For instance, Xport will not allow a <code>p</code>
element to be inserted in another <code>p</code> element, because that
would be an xhtml violation for all document types. Each document type
has specific rules, or document type definitions, which is enforced by
Xport.
</p>
<p class='class_descr'>
The <code>element</code> accepts three arguments in it's constructor.
The first argument is required, and specifies the tag name of the
element to create. In Xport, tag names are enumerated for convenience.
The second optional argument specifies the <em>id</em> attribute for the
element, and the optional third argument specifies the <em>class</em>
attribute for the element.
</p>
<p class='class_descr'>
An <code>element</code> can also be assigned <em>attributes</em>, which
are also enumerated for convenience. The document type definitions
specify which attributes can be assigned to which elements, and Xport
also enforces these rules. Xport also provides an easy way to assign
styles to particular elements through style attributes, but since
stylesheets are supported in Xport, the use of stylesheets is encouraged
over the use of style attributes.
</p>
<h5>
pcdata
</h5>
<p class='class_descr'>
Xport's <code>pcdata</code> type encapsulates PCDATA (parsable character
data) in an xhtml docuement. <code>pcdata</code> objects are mostly used
implicitly in Xport. Whenever text is inserted into an element, Xport
places the text in a <code>pcdata</code> object. When an <code>element
</code> contains PCDATA, the <code>element</code> will contain one or
more <code>pcdata</code> objects, which include the PCDATA. The number
of <code>pcdata</code> objects which comprise the PCDATA within an
element depends on how the PCDATA was inserted into the
<code>element</code>.
</p>
<p class='class_descr'>
In Xport, all parsable character data is placed within <code>pcdata
</code> objects. xhtml elements can also be placed in <code>pcdata</code>
objects, if the elements are included as part of the character data
rather than as <code>element</code> objects. For instance, the following
code snippit will insert the <code>i</code> element and it's contents
within a <code>pcdata</code> object along with it's surrounding text.
</p>
<p class='code_block'>
<code>element elem;<br/>
elem.insert("The included <i>italic</i> element is placed
within a pcdata object.");</code>
</p>
<p class='class_descr'>
In the next code snippet, however, the italic element will be seperate
from the pcdata, as it's inserted as an object.<br/>
</p>
<p class='code_block'>
<code>element elem;<br/>
elem << "The included " << (element(i) << "italic")
<< " element will not be part of the pcdata object.";</code>
</p>
<p class='class_descr'>
In the second snippet, there will be three markup objects contained in
the paragraph element, a <code>pcdata</code> object containing the text
<i>The included</i>, then an italic <code>element</code> object, which
contains the text <i>italic</i>, then another <code>pcdata</code>
object, which contains the remainder of the text.
</p>
<p class='class_descr'>
Regardless of whether elements are represented as an
<code>element</code> object, or as part of a <code>pcdata</code> object,
when an (x)html document is parsed by Xport, the <code>parser</code>
will always parse elements, including <i>inline</i> elements, as
<code>element</code> objects rather than include them in
<code>pcdata</code> objects. This means that if a paragraph element, for
example, would contain content which includes inline elements and
PCDATA, the paragraph element will be parsed into multiple separate
<code>pcdata</code> objects and <code>element</code> objects.
</p>
<h5>
comment
</h5>
<p class='class_descr'>
Xport's <code>comment</code> is a very simple type, which encapsulates
an xhtml comment. Comments are not a necessary item in xhtml, but they
can be useful to document the xhtml source. Like <code>element</code>s, <code>
comment</code>s are also derived from <code>markup</code>, and are
also considered <code>markup</code> objects.
</p>
<h5>
procinstr
</h5>
<p class='class_descr'>
Xport's <code>procinstr</code> encapsulates an xhtml processing
instruction. There are many forms of processing instructions in xhtml,
but all are delimeted by <strong><?</strong> and <strong>?>
</strong>. One of the more popular types of processing instructions are
PHP processing instructions. <code>procinstr</code> is also derived from <code>
markup</code> and is also considered a <code>markup</code> object.
</p>
<h5>
formatter
</h5>
<p class='class_descr'>
Xport's <code>formatter</code> is used to format the output of
documents, whether to a file or to a stream. A <code>formatter</code>
object provides detailed control of the xhtml output. With the <code>
formatter</code>, you can specify the layout style of any element in
the document. You can also specify the maximum line length, and the way <em>
entities</em> are presented in the document. Indeed, with Xport's <code>
parser</code> along with Xport's <code>formatter</code>, you may use
the toolkit to simply reformat current xhtml documents to your liking.
</p>
<h5>
parser
</h5>
<p class='class_descr'>
Xport's <code>parser</code> allows the parsing of xhtml and html
documents. If the xhtml is properly formed, the <code>parser</code>
object will parse the document with no problems. If the document is
mal-formed, the <code>parser</code> object will do it's best to parse
the document with it's errors. The <code>parser</code> object will parse
the file or stream into an Xport <code>document</code> object. No matter
how mal-formed the document being parsed, the resulting <code>document
</code> object will always be well formed, because Xport does not allow
for invalid xhtml. The <code>parser</code> object also allows users to
specify options on how documents are parsed, giving users control over
such things as newline preservation, entity transformations, and byte
order mark preservation. A log can optionally be generated by the <code>
parser</code> object on it's progress.
</p>
<h4>
stylesheet classes
</h4>
<p>
Xport's stylesheet functionality is implemented in another set of
template classes, which are parametized only by the character type. As
with the xhtml template classes, there are type alias declared for the
stylesheet template classes to make them easier to work with. The table
below illustrates the stylesheet template classes, and their type
aliases.
</p>
<div class='tbl_div'>
<table class='type_alias' id='ss_type_alias'>
<colgroup>
<col class='template_col'/>
</colgroup>
<tr>
<th class='alias_hdr' rowspan='2'>
class template
</th>
<th class='alias_hdr' colspan='2'>
type alias
</th>
</tr>
<tr>
<th>
narrow character
</th>
<th>
wide character
</th>
</tr>
<tr>
<th>
xhtml_stylesheet
</th>
<td class='default_type'>
stylesheet
</td>
<td>
wstylesheet
</td>
</tr>
<tr>
<th>
xhtml_stylesheet_rule
</th>
<td class='default_type'>
stylesheet_rule
</td>
<td>
wstylesheet_rule
</td>
</tr>
<tr>
<th>
xhtml_stylesheet_import
</th>
<td class='default_type'>
stylesheet_import
</td>
<td>
wstylesheet_import
</td>
</tr>
<tr>
<th>
xhtml_stylesheet_comment
</th>
<td class='default_type'>
stylesheet_comment
</td>
<td>
wstylesheet_comment
</td>
</tr>
<tr>
<th>
stylesheet_declaration
</th>
<td class='default_type'>
declaration
</td>
<td>
wdeclaration
</td>
</tr>
</table>
<h6 id='ss_tbl_footnote'>
Table 2: Xport's stylesheet class templates and type aliases
</h6>
</div>
<p>
Xport's default character type for stylesheet type aliases is the
standard narrow character type. Using standard narrow characters,
library users will use only those type aliases in blue, displayed in the
table to the left. Xport's <code>stylesheet</code> object encapsulates a
cascading style sheet. The <code>stylesheet</code> object can easily be
written to a file, or embedded in a document. Xport's <code>stylesheet
</code> object can also parse existing stylesheets, from a file or from a
stream.
</p>
<p class='clear_left'>
A brief description of Xport's stylesheet types is given below. The
default type alias names will be used to describe the different
stylesheet types available.
</p>
<h5>
stylesheet
</h5>
<p class='class_descr'>
Xport's <code>stylesheet</code> encapsulates an cascading style sheet. <code>
stylesheet</code>'s interface is small, but very important. It's three
operations, <code>add_item()</code>, <code>write()</code>, and <code>
parse()</code> give <code>stylesheet</code> it's main functionality.
There are three types of objects which can be added to a <code>
stylesheet</code> object, a <code>stylesheet_rule</code>, <code>
stylesheet_comment</code>, and <code>stylesheet_import</code>. This
makes the <code>stylesheet</code> object simpler than the <code>document
</code> object. Most of the work for adding a stylesheet to a document
involves the <code>stylesheet_rule</code> detailed further below.
</p>
<h5>
stylesheet_rule
</h5>
<p class='class_descr'>
Xport's <code>stylesheet_rule</code> encapsulates a CSS rule. When
creating stylesheets in Xport, <code>stylesheet_rule</code> objects are
used more than any other stylesheet types. Since a stylesheet rule
always contains a <em>selector</em> which specifies the parts of the
document to which the rule applies, the <code>stylesheet_rule</code>
takes a mandatory string argument in it's constructor, which specifies
the selector for the rule. After creating a <code>stylesheet_rule
</code> object, declarations are added to it with the <code>
add_declaration()</code> operation. This is the primary operation in <code>
stylesheet_rule</code> and there are two forms of it. The first form
accepts a <code>declaration</code> object, which is described below. The
second form of the operation accepts two arguments. The first argument
specifies the css <code>property</code>, and the second argument
specifies that properties <em>value</em>. The css property names are
enumerated for convenience. The properties value is specified as a
string argument.
</p>
<h5>
stylesheet_import
</h5>
<p class='class_descr'>
Xport's <code>stylesheet_import</code> has one basic purpose, to allow
the import of another stylesheet into the current stylesheet.
</p>
<h5>
stylesheet_comment
</h5>
<p class='class_descr'>
Xport's <code>stylesheet_comment</code> encapsulates a stylesheet
comment. This type allows users to add comments to stylesheets.
</p>
<h5>
declaration
</h5>
<p class='class_descr'>
Xport's <code>declaration</code> encapsulates a CSS declaration. Once a <code>
declaration</code> object is created, it can be added to a <code>
stylesheet_rule</code>. The <code>declaration</code> expects two
mandatory arguments in it's constructor. The first argument specifies
the css <code>property</code>, and the second argument specifies that
properties <em>value</em>.
</p>
<h4>
iterator classes
</h4>
<p>
Xport's iterator functionality is available for both xhtml markup and
stylesheets. There are two types of iterators available for markup,
child markup iterators and descendant markup iterators. As the names
imply, <i>child</i> iterators traverse over the immediate children of an
element or document, whereas <i>descendant</i> iterators traverse over
all descendants of an element or the document.
</p>
<p>
The table below displays the types of iterators available in Xport.
</p>
<div class='iter_tbl_div'>
<table class='type_alias' id='iterators'>
<colgroup>
<col class='type_col'/>
</colgroup>
<tr>
<th class='alias_hdr' rowspan='2'>
iterator type
</th>
<th class='alias_hdr' colspan='2'>
iterator variety
</th>
</tr>
<tr>
<th>
non-const
</th>
<th>
const
</th>
</tr>
<tr>
<th>
child markup iterators
</th>
<td>
markup::iterator
</td>
<td>
markup::const_iterator
</td>
</tr>
<tr>
<th>
reverse child markup iterators
</th>
<td>
markup::reverse_iterator
</td>
<td>
markup::const_reverse_iterator
</td>
</tr>
<tr>
<th>
descendant markup iterators
</th>
<td>
markup::descendant_iterator
</td>
<td>
markup::const_descendant_iterator
</td>
</tr>
<tr>
<th>
stylesheet iterators
</th>
<td>
stylesheet::iterator
</td>
<td>
stylesheet::const_iterator
</td>
</tr>
<tr>
<th>
stylesheet rule iterators
</th>
<td>
stylesheet_item::iterator
</td>
<td>
stylesheet_item::const_iterator
</td>
</tr>
</table>
<h6 id='ss_tbl_footnote'>
Table 3: Xport's iterator types and type aliases
</h6>
</div>
<p class='clear_left'>
A brief description of Xport's iterator types is given below.
</p>
<h5>
markup::iterator and markup::const_iterator
</h5>
<p class='class_descr'>
Xport's <i>child markup iterators</i>, <code>iterator</code> and <code>
const_iterator</code> are very useful for both creating and parsing
xhtml documents. Not only do these iterators allow the traversal of
child markup objects, but they can also be used to insert, add, and
erase child markup objects. The <code>iterator</code> in particular, is
so useful, that an <code>iterator</code> is returned from an elements <code>
insert()</code> operation. The returned <code>iterator</code> in turn
can be used to insert additional markup in the element to which the <code>
iterator</code> points. Users are encouraged to make heavy use of <code>
iterator</code>s when generating content in a document.
</p>
<h5>
markup::descendant_iterator and markup::const_descendant_iterator
</h5>
<p class='class_descr'>
Xport's <i>descendant markup iterators</i>, <code>descendant_iterator
</code> and <code>const_descendant_iterator</code> are used when it's
necessary to traverse <em>descendants</em> of a document or particular
element in the document. These iterators traverse in a <em>pre-order
</em> fashion. A descendant iterator of a document object can traverse
every markup object in the whole document, which can be very handy. Like <code>
iterators</code>, descendant iterators can also be used for inserting,
adding, and erasing markup in the document.
</p>
<h5>
stylesheet::iterator and stylesheet::const_iterator
</h5>
<p class='class_descr'>
Xport's <i>stylesheet iterators</i>, <code>iterator</code> and <code>
const_iterator</code> are very useful for both creating and parsing
stylesheets. Not only do these iterators allow the traversal of
stylesheet items, but they can also be used to insert, add, and erase
stylesheet items, which include stylesheet rules, import rules, and
comments. The <code>iterator</code> in particular, is so useful, that an <code>
iterator</code> is returned from a stylesheet <code>insert()</code>
operation. When a stylesheet rule is inserted, the returned <code>
iterator</code> in turn can be used to insert declarations in the
stylesheet_rule to which the <code>iterator</code> points. Users are
encouraged to make heavy use of <code>iterator</code>s when generating
stylesheet items in a stylesheet.
</p>
<h5>
stylesheet_item::iterator and stylesheet_item::const_iterator
</h5>
<p class='class_descr'>
Xport's <i>stylesheet rule iterators</i>, <code>iterator</code> and <code>
const_iterator</code> are very useful for both creating and parsing
stylesheet rules. Although these iterators traverse declarations which
are embedded in stylesheet_rule objects, this iterator is declared and
defined in stylesheet_rule's base class, stylesheet_item.
</p>
<p>
This concludes the discussion of Xport's interface types. You are
encouraged to read Xport's documentation, and inspect the numerous
examples to get a better idea on how you can use Xport to generate and
parse xhtml documents.
</p>
<div id='footer'>
<p>
This document was created in full by Xport
</p>
</div>
</div>
</body>
</html>