Documenting Howtos with XSLT How to write a howto via XML/XSLT xml, xslt, starling Gan Uesli Starling 2003 - 2006, Ĝan Ŭesli Starling Documentation with XML & XSLT

An Easier Way to Author Markup

This page is not what it appears. It is not HTML. Rather it is XML/XSLT. XML is as much an improvement for documentation over XHTML as is XHTML over paper. Although an international standard, the format is new to the point of ultra-modernity. So as of the moment, certain lag-behind browsers don’t fully support it. But these (and any versions beyond) do: MSIE 6 SP1, Mozilla 1.2.1, Firefox 1.0.

How it works.

Composing all of this from scratch was a bit intimidating. But once done, to use it became a piece of cake. By way of example let me recount how this very document began as a mere follow-up demo for a job interview. Then I kept puttering away at the stylesheet, adding and refining features. And along the way this very page metamorphosed from a mere bit of show-off fluff into a right and proper howto. Such indecisive tinkering is feasible only with XML. Were it old-fashioned XHTML then I would have had to start over. The headaches of markup would have been too intimidating otherwise. That’s how it works: plain old text with only a minimum of tags go into the XML master doc; then XSLT does the markup drudge work.

The XML doc

The markup required to create a master document in XML is very simple. It has only a fraction the complexity of a corresponding XHTML file. The reason for this is all of that extra complexity has been handed off for automatic handling by the XSLT stylesheet.

In authoring this document for presentation I was able to cut and paste whole sections at will and never waste a moment’s effort to track the supporting links or even the table of contents.

So basically, all that needs to be written in the XML master is the body of the document itself. No worries over the table of contents, navigation links, CSS positioning, etc.

What about XML Schema?

Observe that in the root tag for the XML doc I assigned a namespace to a schema. Actually I have not yet written that schema, nor any schema, nor yet even a DTD for this XML. XSLT does not require either. Nor does the browser. These only care that the XML must be well-formed. Later on I plan to write a schema, once experimentation is finished so that the format is set in stone.

The XSLT stylesheet

The XSLT presently stands at 937 lines of code. That sounds like a lot. Yet I need only do it but once. Many more lines than that it will relieve me of later by handling tedious markup chores. For instance: this very page of XHTML which stands at 3392 lines was processed from an XML master of only 1098 lines. And those extra processed-in lines represent the most tedious, singlularly intimidating aspects of markup...the parts I hate. So it has more than paid for itself in just the first XML which it processed. And yet this single stylesheet may serve any number of such XML docs. Here is a link to my XSLT stylesheet which you may study as an example.

The XSLT reads in the XML master doc and processes it into XHTML. On the fly it creates the Table of Contents and all those little navigational arrow buttons. It also handles positioning of images, the ordination of lists, and so forth.

The XHTML output

Output is in XHTML comforming to the well-formedness rules of XML (aka XHTML). All modern browsers support this format. Processing occurs at the browser under Java. So as long as the browser is up to date and installed so as to include the Java Runtime Environment, then it will work regardless of operating system. I have tested it in these browsers:

MSIE 6 SP 1 on Win2K
Mozilla 1.2.1 on NetBSD Unix

Should you be viewing this page correctly on some other browser or OS, I would like to learn of it. Kindly email me. Thanks.

Special charcters

XML, being a markup language, must employ certain symbols. So there must be a work-around for when those symbols mean something else besides markup.

And for all the other symbols not used in markup, keys on the keyboard do not suffice. So there must be a work-around for that as well.

How it works

XML varies notably from XHTML. In sections below I will demonstrate by example rather than attempt to explain. But these two details need separate treatment.

Markup characters

These may not occur anywhere except as part of the script itself. That is to say, they must be escaped when they are content instead of markup. Below is the complete list and how to escape them.

< is escaped by <
> is escaped by >
& is escaped by &

Unicode characters

HTML had its own escapes for a number of useful symbols. Most of these were not carried over into XML. Instead XML uses Unicode. Here are some of the most common.

HTML (charsets vary)	meaning	XML (Unicode)
` `	non-breaking space	` `
’	apostrophe	`’`

Displaying Unicode in browsers

The XSLT stylesheet used here generates a meta tag in the XHTML header declaring content="text/html; charset=UTF-8" as a flag to all browsers that the character set is Unicode (ISO 10646 versus ISO 8859-1). So the Unicode charset herein had ought to display correctly on all modern browsers.

Some older browsers may ingore that tag, however. Or the browser’s owner may have manually overridden it in favor of a local default charset. Lastly, it may happen that the web server is trying to enforce its own global default charset. Thus despite said meta tag it may still happen that appostrophes, arrow buttons, or other characters display incorrectly. I have a work-around for this. It consists of a Perl script to ex-post-facto replace bare, multi-byte Unicode strings with their XHTML-escaped equivalents. Here is a button that can take you there now: Re-escaping UTF-8 for XHTML via Perl .

Page Navigation

The XML master file for this page contains zero markup for the table of contents, nor yet any markup for the many navigation buttons at every section, topic, sub-topic and sub-sub-topic. None whatever. XSLT has calculated these on-the-fly while the page loaded into the browser

How it works

An XML document branches out just like a family tree diagram. It starts with an all-enclosing tag termed the root. From there it forks into smaller branches. And those forks will often fork yet again...and so forth. Wherever the document tree might branch, from that fork leafward is called a node. So each node might have sub-nodes...and so forth. From leaves to root, tags mark the boundary of each such node, sub-node, sub-sub-node, etc. These tags might be named anything. Arbitrarily, I chose to name them: <section>, <topic>, <subtopic> and <subsubtopic>. From right to left, each node must nest inside the node preceding it, just like branches on a tree. It is thereby easy to map.

A table of contents

In composing an on-the-fly table of contents all XSLT need do is start from the root and follow the branches out to a pre-defined number of forks. It then composes a list with named branches just like those found in the document. Lastly it populates that list with the title from each mapped-out branch surrounding these with hypertext links.

List link style & the ToC

Note how the Table of Contents shows a sequence of different list styles for each nested level: section, topic, sub-topic and sub-sub-topic. Such is the style favored by outlines written on paper, and so for good reason. To follow suit in XHTML requires special effort (so that few ever bother). But with XSLT one may arrange that a single set of variables controls for all lists. And this I have done.

How it works is that the stylesheet expects ordered lists to group together within a block. So for any list or sub-list, XSLT merely counts upward toward the first block. The same counting technique applies to both ordered and un-ordered lists. To defeat this behavior locally enclose the sub-list within its own block. To defeat it globally just redefine the variables to be all alike.

Syndication feed link

Syndication feeds, particularly the Atom protocol, are the very latest thing. Post a link to your feed in the table of contents as follows.

Navigation buttons

Each major node (section, topic, etc.) will display adorned by XSLT with from one to four navigational links apearing as square CSS buttons. In a document of complexity their number may run into hundreds. Try marking that up in XHTML!

What this affords to authors is total freedom to sub-divide their treatment of any subject matter. Convenience and logic may now hold sway without inhibition due to the lurking spectre of markup complexity.

Four arrows versus three, two or one

The XSLT stylesheet checks as to whether a given node may have children, siblings or a parent. Thus an button will link left, right, up or down only if that relation exists.

Arrow styles

The nav buttons are set by variables near the head of the XSLT. By default these hold Unicode arrow characters as would seem intuitive for outline-structured documents, which these are.

Vertical arrows

The upward pointing arrow (or double leftward) links up-page to the next higher level (rootward node). Thus from a sub-sub-topic it ascends to the sub-topic. From a sub-topic it ascends to the topic. From a topic it ascends to the section. From any section it ascends to the table of contents. If none such exit no link will appear.

The downward pointing arrow (or double rightward) links down-page into the next sub-level (leafward node). Thus from a section it descends to the first topic. From a topic it descends to the first sub-topic. From a sub-topic it descends to the first sub-sub-topic. If none such exit no link will appear.

Horizontal arrows

The left- and right-ward pointing arrows link up- and down-page to adjacent levels (sibling nodes). Thus from a section they conduct to adjacent sections. From a topic they conduct to adjacent topics. From a sub-topics they conduct to adjacent sub-topics. From a sub-sub-topic they conduct to adjacent sub-sub-topics. If none such exit no link will appear.

Unobtrusive style

Instead of splashy anims or graphics, the nav links here are deliberately plain. They are simple CSS buttons of regular Unicode characters (as selected by XSLT variaable...arrow glyphs by default). Thus the master document is free from the baggage of extraneaous image files.

Major tags

The purpose of required major tags is to enforce both structure and style.

The XML structure expected by this XSLT is as follows: head , body, section, topic, subtopic and subsubtopic.

Required are the first three: without them all structure is absent such that there is nothing to view. Required are the first three: without them structure is wholly absent such that there is nothing to view. Optional are the latter three: but lacking them structure is very simplistic.

How they work

The whole of an XML document is called the root node. This wholeness is delimited by opening and closing root tags. Inside of that are lesser nodes, each bounded by its own pair of tags. And so on and so forth, deeper and deeper.

XSLT first enters the root node. There it applies a list of templates...one at a time. Each template sifts all tags within that node, matching only one kind. The template then performs its function on those tags alone, ignoring all others. Any other templates must wait their turn. Thus it is that sequential elements all must share the same kind of tag.

Thus between the surrounding root tags a template will process first the <head> tag. Next it will process the <body> tag.

Head & Body

Head is analagous to the head of an XHTML doc. The head may contain only a title.

Head is analagous to the head of an XHTML doc. Body is likewise analagous to the body of an XHTML doc. The body may have titles, blocks and sections, in that order.

Markup

Shown is a mostly empty markup for the head and a typical body. Not-so-obvious things you may change are shown in bold. Hints from me which you had ought not to include are shown in teal. Other empty elements you may fill with any text as seems obvious to you.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml-stylesheet type="text/xsl" href="./gus_xslt.xsl"?>
<gus_xslt
  xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://starling.ws/XML/howto.xsd">
  <head>
    <navigation 
      ToC="Table of Contents"    <-- Leave empty to omit the ToC. Edit to label the ToC differently. -- >
      section="yes" topic="yes" subtopic="yes" subsubtopic="yes" links="yes"/>    <-- Fill with "no" to omit navigation for given level. -- >
    <syndication atom="http://your_domain.com/your_atom_feed.xml" />    <-- Omit this node to forego an Atom feed link. -- >
    <title></title>
    <description></description>
    <keywords></keywords>
    <author></author>
    <copyright></copyright>
  </head>
  <body>
  <title></title> 
    <foo></foo> 
    <foo></foo>
    <section></section>
    <section></section>
  </body>
</gus_xslt>

Sections

Sections are the major division of subject matter. XSLT will automatically display these in XHTML segregated vertically by <hr/> tags (horizontal rules). Attributes embeded into the opening <section> tag (such as style="clear:both", etc.) will carry through to the resultant <hr/> tag. Within the <section> node, XSLT will parse the <title> tags from each sub-node to create a Table of Contents as top-level list items. A section may contain titles, blocks and topics.

Markup

Shown is empty markup for a typical secion.

      <section>
        <inlink></inlink>
        <title></title>
        <foo></foo>
        <topic>
          <title></title>
          <foo></foo>
          <subtopic>
            <title></title>
            <foo></foo>
            <subsubtopic>
              <title></title>
              <foo></foo>
            </subsubtopic>
          </subtopic>
        </topic>
      </section>

Topics, sub-topics & sub-sub-topics

In the XHTML output these display as nested list-items within a section. In the Table of Contents their display as descending list items for that section. Each may contain titles and blocks.

Markup

Shown is empty markup for a typical topic and its descendents.

        <topic>
          <inlink></inlink>
          <title></title>
          <foo></foo>
          <subtopic>
            <inlink></inlink>
            <title></title>
            <foo></foo>
            <foo></foo>
            <subsubtopic>
              <inlink></inlink>
              <title></title>
              <foo></foo>
              <foo></foo>
            </subsubtopic>
          </subtopic>
        </topic>

Titles

Titles may contain <foo> text nodes.

Sometimes the most appropriate title for a section is too long to fit neatly into the ToC. You can flag that a shorter title appear in the ToC by embeding an attribute, like so...

<title toc="Short Name">Too Long for TOC Title Name</title> .

Inlinks

Inlinks may contain foo_bar text sans any whitespace. They are for named, inbound anchor tags. Inlink nodes transform as HTML <a id="foo_bar"> tags.

Stylesheet defaults

Many of the appearance defaults enforced by the XSLT stylesheet are controlled by variables.

User-redefinable defaults

The following variables are defined at the top of the stylesheet. The purpose of each is self-evidently by its name, as follows:

Various colors:

page_background_color ― the page itself.
dark_background_color ― darker shade of two-tone pair.
lite_background_color ― lighter shade of two-tone pair.
- In changing either of the two-tone pair, be sure to test both on CRT and LCD screens. Results can vary significantly.
text_bold_color ― for <bold> text nodes.
text_note_color ― for <warn> text nodes.
text_warn_color ― for <note> text nodes.
text_cmd_color ― for <cmd> children of <pre> text nodes.
- Used in blocks of example code to distinguish command entries burried in prompts and system feedback.

Navigation buttons:

button_style ― size, color, etc.
button_char_left ― Unicode character.
button_char_up ― Unicode character.
button_char_down ― Unicode character.
button_char_right ― Unicode character.

Background image URL:

background_image_left ― path to image.

Borders for ToC, tables:

border_color ― color of borders.
border_style ― style of borders.

By-passing defaults

In preparing the above defaults, I will of course have neglected something I’m sure to need later. So as a hedge, two tags will pass both their XML attributes and child nodes un-altered to the XHTML output.

How it works

The XSLT stylesheet enforces a number of built-in defaults. By passing through both the attributes and the child nodes, all built-in defaults are escaped.

Carry-over XHTML tag

The following tags and attributes are no different than for XHTML.

<div foo="bar"> and </div>
<span foo="bar"> and </span>

Examples

These show how XHTML may be passed through via a <div> node.

Markup custom <h1> tag

Shown is markup for sample below.

<div>
  <div style="width:300px;margin-left:auto;margin-right:auto;">
    <h1 style="text-align:center;line-height:150%;
      font-weight:800;font-style:italic;border:solid violet;
      color:yellow;background-color:purple;">
      XHTML custom <h1> tag
    </h1>
  </div>
</div>

Sample custom <h1> tag

Shown is result of markup above.

XHTML custom <h1> tag

Markup custom <img> button

Shown is markup for sample below.

<div>
  <a href="../images/tet_name.png" rel="external">
    <p style="text-align:center;
      margin-left:35%;margin-right:35%;
      border:outset black;
      background-color: olive;">
      <br />
      <img s="img" src="../images/araneo_100.png" alt="button"/>
      <br />
      <br />
    </p>
  </a>
</div>

Sample custom <img> button

Shown is result of markup above.

Text

XSLT here handles some of the druge work by allowing for custom tags and so avoiding excessive use of <span> nodes.

How it works

Between surrounding <p> and </p> tags, XSLT will apply templtes for most of the usual XHTML nodes plus a few extras.

Custom XML tags

The following tags and attributes are different from XHTML.

<note> and </note> take the place of <span style="color:teal;"> together with its closing tag.
<warn> and </warn> take the place of <span style="color:red;"> together with its closing tag.

Carry-over XHTML tags

The following tags work the same as in XHTML.

<b> and </b> pass through.
<i> and </i> pass through.
<sup> and </sup> pass through.
<sub> and </sub> pass through.
<a> and </a> pass through complete with attributes.
<span> and </span> pass through complete with attributes, etc.

Examples Markup

Shown is for sample text below.

<p>
  <a class="button" href="#foo" id="bar">Sample two-way link to button below</a>
  <br />Sample plain text
  <br /><i>Sample italic text</i>
  <br /><b>Sample bold text</b>
  <br /><code>Sample code style text</code>
  <br /><note>Sample note style text</note>
  <br /><warn>Sample warning style text</warn>
  <br /><a class="button"  href="#bar" id="foo">Sample two-way link to button above</a>
</p>

Sample text

Shown is result of markup above.

Sample two-way link to button below
Sample plain text
Sample italic text
Sample bold text
Sample code text
Sample note text
Sample warn text
Sample two-way link to button above

Images

Here XSLT again handles all the drudge work: placing, linking, and captioning image multiple files.

How it works

The XSLT creates a one-row table with a <td> cell for each separate image. Within this cell the image and caption are centered using a <p style="text-align:center;"> tag pair. If an optional href="foo" attribute is included, a hypertext link will be templated into the output.

Why not pure CSS?

A somewhat more elegant approach to image placement would be to use <div> tags and the CSS float property. And in fact I tried that first. I did not mind that CSS it required the dimensions for each separate image. But the float characteristic did not work predictably for every image. Thus I fell back on the tried and true XHTML table option. XSLT does all the work, so complexity is not an issue?

Custom XML tags

The following tags and attributes are different from XHTML.

Enclose all image tags between <images s="img"> and </images> tags.
<img src="../path/thumbnail.gif" href="../path/bigger.png"> is the opening image tag.
</img> is the closing image tags.
Image captions are placed between the tags.

Examples Markup

Shown is for sample images below.

<images>
  <img src="../images/S_Apache_Logo.gif" 
    href="../images/Apache_Logo.gif">
    Apache logo.
   </img>
  <img src="../images/trailing_edge_50x39.png" 
    href="../images/trailing_edge_wht.png">
    My own logo.
  </img>
  <img src="../images/S_NetBSD_Logo.gif" 
    href="../images/NetBSD_Logo.gif">
    NetBSD logo.
  </img>
</images>

Sample images

Shown is result of markup above. All three images are hypertext links.

Apache logo.

My own logo.

NetBSD logo.

Lists

Lists work the same in this XML/XSLT as they do for XHTML. The only difference is auto-configuration of list-style-types.

How it works

The list tags themselves, on passing through XSLT, are adorned with list-style-type attributes from CSS. The order in which they are chosen is fixed by a set of eight variables near the head of the XSLT. These are named list-style-1 and so forth. Ordination is calcuated by counting nodes backward toward the nearest enclosing <section>, <topic>, <subtopic> or <subsubtopic> node.

Carry-over XHTML tags

The following tags are carried over from XHTML. Closing tags are required for each.

The <ol> tag.
The <ul> tag.
The <li> tag.

Style attributes

Styles for both kinds of lists are fixed by the XSLT. The ordination of list style types is controlled by eight variables near the head of the XSLT. Each level of sub-nesting will display a 5% reduction in font-size and line-height until the 6th sub-level.

Examples

Details about lists are delt with in the examples themselves.

Markup for ordered list

Shown is for sample ordered list below.

<ol>
  <li>Item 1</li>
  <li>Item 2
    <ol>
      <li>Item 2-1</li>
      <li>Item 2-2
        <ol>
          <li>Item 2-2-1</li>
          <li>Item 2-2-2</li>
        </ol>
      </li>
    </ol>
  </li>
  <li>Item 3</li>
</ol>

Sample ordered list

Shown is result from markup above.

Item 1
Item 2
1. Item 2-1
2. Item 2-2
  1. Item 2-2-1
  2. Item 2-2-2
Item 3

Sample unordered list

Shown is an unordered twin to the ordered list above.

Item 1
Item 2
- Item 2-1
- Item 2-2
  - Item 2-2-1
  - Item 2-2-2
Item 3

Tables

Tables work the same in this XML/XSLT as they do for XHTML. The only difference is auto-configuration of styles. That and differentiation of styles for nested sub-tables.

How it works

The table tags, on passing through XSLT, are adorned with style attributes from CSS.

Carry-over XHTML tags

The following tags and attributes are carried over from XHTML. Closing tags are required for each.

The <table> tag.
The <tr> tag.
The <th> tag with attributes.
The <td> tag with attributes.

Examples Markup

Shown is for the sample table below.

<table>
  <tr>
    <th>header</th>
    <th>header</th>
    <th>header</th>
  </tr>
  <tr>
    <td rowspan="2">rowspan = 2</td>
    <td colspan="2">colspan = 2</td>
  </tr>
  <tr>
    <td>foobar</td>
    <td>
      <table>
        <tr>
          <th colspan="2">Nested Table</th>
        </tr>
        <tr>
          <td>foo</td>
          <td>bar</td>
        </tr>
      </table>
    </td>
  </tr>
</table>

Sample table

Shown is result of the markup above. Note: an apparent bug in Mozilla 1.2.1 mis-renders the table caption. Suggest a paragraph to hold the caption instead.

header

rowspan = 2

colspan = 2

foobar

Nested Table
foo	bar

Forms

Tables work the same in this XML/XSLT as they do for XHTML.

How it works

Form tags will pass both their XML attributes and child nodes un-altered to the XHTML output. Forms vary to such a degree that any default attributes would need to be escaped more often than otherwise. Thus only CSS defaults are enforced.

Examples Form with nested table.

Here XSLT merely passes the XHTML straight through.

Markup

Shown is for sample below.

<form method="post" action="../foo/bar.cgi">
  <fieldset>
    <legend>Foobar</legend>
      <table class="layout">
        <tr>
          <td margin="5" align="right" valign="middle">
            <label>A Label</label>
          </td>
          <td margin="5" align="left" valign="middle">
            <input type="text" name="foo"/>
          </td>
        </tr>
        <tr>
          <td margin="5" align="right" valign="top">
            <label>Another Label</label>
          </td>
          <td margin="5" align="left" valign="middle">
            <textarea cols="40" rows="5">Text inside textarea tag.</textarea>
          </td>
        </tr>
      </table>
  </fieldset>
</form>

Sample form

Shown is for sample above.

Form with nested CSS

Here again XSLT merely passes the XHTML straight through.

Markup

Shown is for sample below.

<form action="../cgi-bin/">
  <div style="float:left;width:50%;margin-bottom:.5em;">
    <fieldset style="float:right;
      margin-right:.5em;width:14em;">
      <legend>Alpha</legend>
      <input style="float:right;" type="text" name="goo"/>
      <label style="float:right;margin-right:.5em;">Label</label>
      <br />
      <input style="float:right;" type="text" name="car"/>
      <label style="float:right;margin-right:.5em;">Longer Label</label>
    </fieldset> 
  </div>
  <div style="float:right;width:50%;margin-bottom:em;">
    <fieldset style="float:left;
      margin-left:.5em;width:14em;">
      <legend>Bravo</legend>
      <input style="float:right;" type="text" name="goo"/>
      <label style="float:right;margin-right:.5em;">Foo</label>
      <br />
      <input style="float:right;" type="text" name="car"/>
      <label style="float:right;margin-right:.5em;">Foobar</label>
    </fieldset>
  </div>
  <fieldset style="clear:both;
    margin-left:auto;margin-right:auto;
    width:14em;">
    <legend>Charlie</legend>
    <input style="float:right;margin-right:6em;" type="radio" name="bar"/>
    <label style="float:right;margin-right:.5em;">short</label>
    <br />
    <input style="float:right;margin-right:6em;" type="radio" name="bar"/>
    <label style="float:right;margin-right:.5em;">Longer</label>
    <br />
    <input style="float:right;margin-right:6em;" type="radio" name="bar"/>
    <label style="float:right;margin-right:.5em;">Longer Yet</label>
  </fieldset>
</form>

Sample form

Shown is for sample above.

XML editing tools

The only absolutely required tool for editing XML is a plain, old-fashioned ASCII text editor: Notepad, TextPad, Nedit, etc. Likewise the only absolutely required tool for checking and viewing pages like this is an ultra-modern browser. These are hammer and tongs of the format. Still, one or two finer tools, equally free and cross-platform, have long been available. And several more are in the pipe. Here are what uses I have made of them upon occasion.

Xalan

This is how I used to generate XHTML from XML in the days before all major browsers had built-in support XML/XSLT. Now you can just do without conversion to XHTML and simply publish your plain XML/XSLT instead. And that is what I always do now. Still, though, you might have a specific need. So...

Know that Xalan is the XSLT processor from Apache. And as most people know, Apache is the original, and still premier, web-server on the Internet. Just like Apache, Xalan is free and open source.

xalan-j for NetBSD

I used the Java version of Xalan. No particular reason for choosing that other than it came recommended in the O’Reilly book XSLT which got me started. All examples in the book use it, so I did too. It works for me.

How to install

I insalled for like so...

baal: {666} cd /usr/pkgsrc/textproc/xalan-j
baal: {667} make && make install  
baal: {668}

How to configure

In my file ~/.cshrc I first added this to my path...

 /usr/pkg/java/jdk-1.1.8/bin

Then I made for a Java classpath like so (all one line, not wrapped)...

setenv CLASSPATH /usr/pkg/java/jdk-1.1.8/lib/classes.zip:
/usr/pkg/lib/java/xalan.jar:/usr/pkg/lib/java/xerces.jar:
/usr/pkg/lib/java/bsf.jar

How to use

Pretty much, all I ever need do is run two commands like this...

marduk: {666} cd /usr/pkg/share/httpd/htdocs/XML
marduk: {667} java org.apache.xalan.xslt.Process \
-in howto.xml -xsl howto.xsl -out howto.html
========= Parsing file:/usr/pkg/share/httpd/htdocs/XML/howto.xsl ==========
Parse of file:/usr/pkg/share/httpd/htdocs/XML/howto.xsl took 4466 milliseconds
========= Parsing file:/usr/pkg/share/httpd/htdocs/XML/howto.xml ==========
Parse of file:/usr/pkg/share/httpd/htdocs/XML/howto.xml took 1330 milliseconds
=============================
Transforming...
transform took 10083 milliseconds
XSLProcessor: done
marduk: {668}

If there are errors, Xalan gives far more informative output than I might read from either browser. And this is the main reason I use it.

The second reason is to make use of the output XHTML in support of all those out-dated browsers not yet up to speed for XSLT. So not only can we have our cake and eat it too, but we can force-feed it to others as well. The only problem with this solution is the presence of bare, un-escaped Unicode characters in the XHTML file. Read below on how to overcome this little difficulty by ex-post-facto editing with Perl.

Perl

Perl is so ubiquitous that it hardly needs introduction. It is available for every single OS that I know of.

How to install

On my NetBSD Unix box, I installed Perl like so...

baal: {666} cd /usr/pkgsrc/lang/perl58
baal: {667} make && make-install

How to configure

There is nothing to configure for Perl itself. And any given Perl script requires only what any script does: ownership, permissions and a shebang line.

<a id="2002-03-22-09-43">Re-escaping UTF-8 for XHTML via Perl</a>

One glitch which I thought I ran into with XSLT turned out instead to be a problem with the web server. This script is for addressing that problem.

Troubleshooting

Symptom: When viewing the output from XSLT as *.xml all is well. But when viewing identical content from Xalan as *.html both Mozilla and MSIE cosistently trip over multi-byte Unicode character strings (apostrophe, directional arrows, etc.). In short, the meta tag declaring for UTF-8 is ignored equally by both browsers. Then once the page has loaded, to manually select UTF-8 from pull-down menus restores those characters.

Diagnosis: The web server is over-riding browser defaults with its own charset declartion. In my case an argument in Apache 2’s httpd.conf file was declaring AddDefaultCharset ISO-8859-1 for all files to visiting browsers, thus overriding the meta tag. I changed that to UTF-8 and the problem went away. Not everyone has this option however.

Workaround

What to do when you don’t own the webserver and so lack permission make corrections? Perl to the rescue! Before obtaining the Apache solution I hammered out this work-around. I found that if I ex-post-facto re-escape any Unicode characters then both browsers display correctly despite that contrary flag from the web server. I have not done for all Unicode characters, only for certain punctuation, arrow glyphs and diacritical marks from the language Esperanto. If these do not suffice for you, just add in more.

The Perl script

Here is a link to my Perl script: gus_escape_UTF-8.pl . Open this in your browser, select all, then save as as *.pl rather than *.txt. Know that there is bare Unicode inside it. So make sure to copy and paste with your mouse into a Unicode-capible text editor like GEdit, Nedit, Yudit or mined. If you are not sure, then just try it and see. The script failing is all the harm that should result.

How to use

The Perl script gus_escape_UTF-8.pl will edit all XHTML files in its resident directory. It will overwrite those in place, escaping certain bare Unicode chars. It works this way because I assume that said directory contains mostly *.xml files except for a few *.html files generated by Xalan. So if anything bad should happen to them, then I just re-generate them. On my NetBSD Unix system, to run this script I type like so...

baal: {16} cd /some/path
baal: {667}  ./gus_escape_UTF-8.pl
Re-escaping chars for UTF-8...
Done. In all, 3 files were processed.
marduk: {668}

Observe as how I ran it in the directory for Apache where I have my XML files. It outputs to XHTML, but I leave them there afterward because some of the links may be relative. I keep the XML as master, but publish links mainly to their XHTML offspring. That way nearly any browser can view them.

Webmaster

E-Mail This page is composed in XML format using a plain ASCII text editor. I last updated it on 2007-02-11 at 11:29 hours testing in the Firefox 1.5.0.1 browser. Please email to report any problems (other than MSIE’s CSS shortcomings).