Dmitry Kirsanov looks at how source definition rules can be applied to real-world source XML documents of a typical web site. Kirsanov covers markup constructs commonly used in page documents and presents complete summary examples of a page document, a master document, and a Schematron schema to validate them.

This chapter is from the book

This chapter is from the book

River and bridge and street and square
Lay mine, as much at my beck and call,
Through the live translucent bath of air,
As the sights in a magic crystal ball.

Robert Browning, Old Pictures in Florence

This chapter is a practical complement for Chapter 2, "The source definition."
Having discussed the ins and outs of building a comprehensive and useful
source definition, we'll now look at how these rules can be applied to real-world
source XML documents of a typical web site.

I cannot claim to cover everything: Your web site may well contain unique
elements that won't fit common schemes. Here, only the most general and
frequently used constructs are covered, and the approaches described in
this chapter may not be optimal for all situations. Many examples are given,
but rather than copy them over, try to use the reasoning behind these examples
to analyze your own constraints and requirements.

The first part of the chapter deals with markup constructs commonly used
in page documents, including headings, paragraphs and paragraph-like elements,
links, images and other non-XML objects, tables, and forms. Then we will
analyze the master document (3.9) to find out what data it needs to store
and what is the best XML representation for this data. The last section
(3.10) presents complete summary examples of a page document, a master document,
and a Schematron schema to validate them.

3.1 Page documents: top-level structures

In this and subsequent sections, we look at the informational core of
a web page, stored in its own source document (page document). Peripheral
components such as navigation, parameters of the site environment, and metadata
are stored in the master document, the subject of 3.9.

3.1.1 Page metadata

Every XML document has a root element, and since we're talking about page
documents here, there's no reason not to call this element page.
Its attributes and children are the natural place to store the page's metadata.

In addition to its primary content, each page document includes certain
metadata. Some of it may end up as a visible part of the web page, some
may be hidden in HTML metadata constructs (keywords and descriptions in
meta elements), some may be used during transformation but
not included in the resulting HTML code, and some may not be used at all
except for reference or source annotation purposes. Common examples of metadata
include page creation date, change log, author(s) and editor(s), copyright
and licensing information, and the language of the page.

Note that only information specific to this particular page must be stored
in it; if some metadata bits are shared by more than one page, their proper
place is in the master document (3.9) and not in any of the page documents.

Page ID. The most important piece of metadata is the page's unique
identifier used to resolve internal links (3.5.3). However, we cannot store
this identifier in the page itself, or we'll have a catch-22 situation:
We can get from the id to the page location, but to obtain
the id we must access the page - that is, we must already know
its location. Because of this, the proper place for the ids
of all pages is in the site's master document. stylesheetsaccessing
source documentspage documentsaccessingsite directory

Page coordinates.The same applies to the information on the position
occupied by this page in the site's hierarchy. As we'll see later (3.9.1.1),
the branch of the site's tree that this page is a leaf of is most naturally
deduced from the site directory in the master document. Duplicating this
information in the page document itself is unnecessary and prone to errors.

Everything else.Any other page metadata is normally stored in the
page document. Simple values can be stored in attributes of the page's root
element. More complex constructs that require their own elements can be
placed either directly under the root or inside an umbrella parent element
(e.g., metadata) that is a child of the root element.

Existing vocabularies. RDF (), besides
being the cornerstone of the Semantic Web, can be used as a powerful tool
for representing metadata in the traditional Web. It allows you to use standardized
descriptors for common values such as author and date, but you can just
as well define your own semantics for your unique metadata.

3.1.2 Sections and blocks

You'll likely need some intermediate structural layers between the root
element, page, and text markup constructs such as paragraphs
and headings.

Sections or blocks? The traditional document hierarchy - sections,
subsections, subsubsections, and so on - is not often seen on the Web. Instead,
information is more commonly broken into relatively small blocks
with few or no hierarchical relations between them. Different sites may
call these blocks "stories," "blurbs," "columns," "modules," "writeups,"
and myriad other names.

Among these names, one which appears to be the most intuitive is the one
you should use for your block construct's element type name. Contentwise,
a block is a unit with mostly fixed structure that may include both obligatory
(e.g., heading and body) and optional (e.g., icon, heading links, author
byline) components in both parallel and sequential (2.3.7) arrangements.
Here's an example:

Block types. It is likely that you will have more than one type
of block construct - for example, front page news blocks, subpage body blocks,
and ad blocks. In the simplest case, everything on the page can be treated
as one big block, so the page's root element can be considered the root
element of a block.

Different types of blocks will likely have many common structural features
- in part because they all belong to one site with its common information
architecture and visual design. Only if different types of blocks have clearly
distinct structures can you use different element types for them; otherwise
it is best to use the same generic element type (e.g., block)
with different values of the type attribute. This provides
two major benefits:

Your validation code will be simpler to write and maintain.

Management of orthogonal content (2.1.2.2) will be much easier to
implement - for example, you may be able to reuse blocks
from regular pages as orthogonals on other pages, or turn documents
storing orthogonal content into regular pages.

In general, analogous but different structures should only differ by a
minimum number of obvious features; avoid random, meaningless differences.