File: xmlformat.html

package info (click to toggle)
xmlformat 1.04-3
links: PTS, VCS
area: main
in suites: bookworm, forky, sid, trixie
size: 1,012 kB
sloc: xml: 2,289; perl: 996; ruby: 831; makefile: 109; sh: 65
file content (1197 lines) | stat: -rw-r--r-- 55,829 bytes
parent folder | download | duplicates (3)
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>
The xmlformat XML Document Formatter
</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id755641"></a>
The <span><strong class="command">xmlformat</strong></span> XML Document Formatter
</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Paul</span> <span class="surname">DuBois</span></h3><code class="email">&lt;<a href="mailto:paul@kitebird.com">paul@kitebird.com</a>&gt;</code></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction">1. 
Introduction
</a></span></dt><dt><span class="sect1"><a href="#how-to-use">2. 
How to Use <span><strong class="command">xmlformat</strong></span>
</a></span></dt><dt><span class="sect1"><a href="#doc-processing-model">3. 
The Document Processing Model
</a></span></dt><dd><dl><dt><span class="sect2"><a href="#document-components">3.1. 
Document Components
</a></span></dt><dt><span class="sect2"><a href="#line-breaks-and-indentation">3.2. 
Line Breaks and Indentation
</a></span></dt><dt><span class="sect2"><a href="#text-handling">3.3. 
Text Handling
</a></span></dt></dl></dd><dt><span class="sect1"><a href="#using-config-files">4. 
Using Configuration Files
</a></span></dt><dd><dl><dt><span class="sect2"><a href="#config-file-syntax">4.1. 
Configuration File Syntax
</a></span></dt><dt><span class="sect2"><a href="#formatting-options">4.2. 
Formatting Options
</a></span></dt></dl></dd><dt><span class="sect1"><a href="#how-xmlformat-works">5. 
How <span><strong class="command">xmlformat</strong></span> Works
</a></span></dt><dt><span class="sect1"><a href="#prerequisites">6. 
Prerequisites
</a></span></dt><dt><span class="sect1"><a href="#references">7. 
References
</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>1.
Introduction
</h2></div></div></div><p>
<span><strong class="command">xmlformat</strong></span> is a formatter (or "pretty-printer") for
XML documents. It is useful when you want XML documents to have a
standard format. This includes situations such as the following:
</p><div class="itemizedlist"><ul type="disc"><li><p>
XML documents that are maintained in a version control system, where
people who use different XML editors work on the documents. XML editors
typically impose their own style conventions on files. The application
of different style conventions to successive document revisions can
result in large version diffs where most of the bulk is related only to
changes in format rather than content. This can be a problem if, for
example, the version control system automatically sends the diffs to a
committer's mailing list that people read. If documents are rewritten to
a common format before they are committed, these diffs become smaller.
They better reflect content changes and are easier for people to scan
and understand.
</p></li><li><p>
Similarly, if you send an XML document to someone who edits it and sends
it back, it's easier to see what was changed by putting the before and
after versions in a common format. This is a simple alternative to using
a more sophisticated semantic XML diff utility.
</p></li></ul></div><p>
Of course, these benefits can be obtained by using any XML pretty
printer. So why does <span><strong class="command">xmlformat</strong></span> exist? Because most
XML formatters reformat documents using a set of built-in rules that
determine the output style. Some allow you to select from one of several
predefined output styles. That's fine if the style you want is the style
produced by one of these tools. If not, you're stuck. That's where
<span><strong class="command">xmlformat</strong></span> comes in, because it's configurable. You
can specify formatting options in a file and
<span><strong class="command">xmlformat</strong></span> will apply them to your documents. If you
have different applications for which you want different styles, you can
select the style by using the appropriate configuration file.
</p><p>
<span><strong class="command">xmlformat</strong></span> has a default overall output style, but you
can redefine the default style, and you can override the default on a
per-element basis. For example, you can indicate whether the element
should be treated as a block element, an inline element, or a verbatim
element. For any block element, you can control several formatting
properties:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Spacing (line breaks) between nested sub-elements. You can also control
spacing between the element's opening and closing tags and its content.
(The general assumption is that if a block element has non-inline
sub-elements, you'll want to space those sub-elements evenly within the
enclosing block, though possibly with different spacing between the
opening tag and the first child, or between the last child and the
closing tag.)
</p></li><li><p>
Indentation of nested sub-elements.
</p></li><li><p>
Whitespace normalization and line-wrapping of text within the element.
</p></li></ul></div><p>
<span><strong class="command">xmlformat</strong></span> is free software. You can redistribute it
or modify it under the terms specified in the
<code class="filename">LICENSE</code> file.
</p><p>
For installation instructions, see the <code class="filename">INSTALL</code>
file.
</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-to-use"></a>2.
How to Use <span><strong class="command">xmlformat</strong></span>
</h2></div></div></div><p>
To format the file <code class="filename">mydoc.xml</code> using the default
formatting options, use the following command. (<code class="literal">%</code>
represents your shell prompt here; do not type it as part of the
command.)
</p><pre class="screen">
% <strong class="userinput"><code>xmlformat mydoc.xml</code></strong>
</pre><p>
(<span><strong class="command">xmlformat</strong></span> might be installed as
<span><strong class="command">xmlformat.pl</strong></span> or <span><strong class="command">xmlformat.rb</strong></span>,
depending on implementation language. In that case, you should invoke it
under the appropriate name.)
</p><p>
The built-in formatting options cause each element to begin a new line,
with sub-element indentation of one space, and no text normalization.
Suppose <code class="filename">mydoc.xml</code> looks like this:
</p><pre class="screen">
&lt;table&gt; &lt;row&gt; &lt;cell&gt; A &lt;/cell&gt; &lt;cell&gt; B &lt;/cell&gt; &lt;/row&gt;
&lt;row&gt; &lt;cell&gt; C &lt;/cell&gt; &lt;cell&gt; D &lt;/cell&gt; &lt;/row&gt; &lt;/table&gt;
</pre><p>
<span><strong class="command">xmlformat</strong></span> will produce this result by default:
</p><pre class="screen">
&lt;table&gt;
 &lt;row&gt;
  &lt;cell&gt; A &lt;/cell&gt;
  &lt;cell&gt; B &lt;/cell&gt;
 &lt;/row&gt;
 &lt;row&gt;
  &lt;cell&gt; C &lt;/cell&gt;
  &lt;cell&gt; D &lt;/cell&gt;
 &lt;/row&gt;
&lt;/table&gt;
</pre><p>
The default style is perhaps suitable for data-oriented XML documents
that contain no mixed-content elements. For more control over output,
specify a configuration file.
</p><p>
If the formatting options are stored in a file named
<code class="filename">xf-opts.conf</code>, you can apply them to the document by
specifying a <code class="option">--config-file</code> option:
</p><pre class="screen">
% <strong class="userinput"><code>xmlformat --config-file=xf-opts.conf mydoc.xml</code></strong>
</pre><p>
If you do not specify a configuration file using a
<code class="option">--config-file</code> (or <code class="option">--f</code>) option,
<span><strong class="command">xmlformat</strong></span> uses the following rules to determine what
formatting options to use:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If the environment variable <code class="literal">XMLFORMAT_CONF</code> is
defined, <span><strong class="command">xmlformat</strong></span> uses its value as the name of the
configuration file.
</p></li><li><p>
Otherwise, if a file named <code class="filename">xmlformat.conf</code> exists in
the current directory, <span><strong class="command">xmlformat</strong></span> uses it as the
configuration file.
</p></li><li><p>
Otherwise, <span><strong class="command">xmlformat</strong></span> uses a set of built-in
formatting options.
</p></li></ul></div><p>
Configuration options and configuration file syntax are described in
<a href="#using-config-files" title="4.
Using Configuration Files
">Section4, &#8220;
Using Configuration Files
&#8221;</a>.
</p><p>
To see the command-line options that <span><strong class="command">xmlformat</strong></span>
supports, invoke it with the <code class="option">--help</code> or
<code class="option">--h</code> option:
</p><pre class="screen">
% <strong class="userinput"><code>xmlformat --help</code></strong>
Usage: xmlformat [options] xml-file

Options:
--help, -h
    Print this message
--backup suffix -b suffix
    Back up the input document, adding suffix to the input
    filename to create the backup filename.
--canonized-output
    Proceed only as far as the document canonization stage,
    printing the result.
--check-parser
    Parse the document into tokens and verify that their
    concatenation is identical to the original input document.
    This option suppresses further document processing.
--config-file file_name, -f file_name
    Specify the configuration filename. If no file is named,
    xmlformat uses the file named by the environment variable
    XMLFORMAT_CONF, if it exists, or ./xmlformat.conf, if it
    exists. Otherwise, xmlformat uses built-in formatting
    options.
--in-place, -i
    Format the document in place, replacing the contents of
    the input file with the reformatted document. (It's a
    good idea to use --backup along with this option.)
--show-config
    Show configuration options after reading configuration
    file. This option suppresses document processing.
--show-unconfigured-elements
    Show elements that are used in the document but for
    which no options were specified in the configuration
    file. This option suppresses document output.
--verbose, -v
    Be verbose about processing stages.
--version, -V
    Show version information and exit.
</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
Do not use the <code class="option">--in-place</code> or <code class="option">-i</code>
reformatting option until you are certain your configuration options are
set up the way you want. Unpleasant consequences may occur otherwise.
For example, if you have verbatim elements that you have forgotten to
declare as verbatim, they will be reformatted and you will have to
restore them to their original state later. Use of the
<code class="option">--backup</code> or <code class="option">-b</code> option can help you
recover from this kind of problem.
</p></div><p>
<span><strong class="command">xmlformat</strong></span> writes the result to the standard output by
default. To perform an "in-place" conversion that writes the reformatted
document back to the original file, use the <code class="option">--in-place</code>
or <code class="option">-i</code> option. This is useful when you want to format
multiple documents with a single command; streaming multiple output
documents to the standard output concatenates them, which is likely not
what you want.
</p><p>
Because in-place formatting replaces the original document, it's prudent
to make a backup of the original using the <code class="option">--backup</code> (or
<code class="option">-b</code>) option. This option takes a suffix value to be
added to each input filename to produce the backup filename.
</p><p>
To inspect the default (built-in) configuration options, use this
command:
</p><pre class="screen">
% <strong class="userinput"><code>xmlformat --config-file=/dev/null --show-config</code></strong>
</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="doc-processing-model"></a>3.
The Document Processing Model
</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="#document-components">3.1. 
Document Components
</a></span></dt><dt><span class="sect2"><a href="#line-breaks-and-indentation">3.2. 
Line Breaks and Indentation
</a></span></dt><dt><span class="sect2"><a href="#text-handling">3.3. 
Text Handling
</a></span></dt></dl></div><p>
XML documents consist primarily of elements arranged in nested fashion.
Elements may also contain text. <span><strong class="command">xmlformat</strong></span> acts to
rearrange elements by removing or adding line breaks and indentation,
and to reformat text.
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="document-components"></a>3.1.
Document Components
</h3></div></div></div><p>
XML elements within input documents may be of three types:
</p><div class="itemizedlist"><ul type="disc"><li><p>
block elements
</p><p>
This is the default element type. The DocBook
<code class="literal">&lt;chapter&gt;</code>, <code class="literal">&lt;sect1&gt;</code>,
and <code class="literal">&lt;para&gt;</code> elements are examples of block
elements.
</p><p>
Typically a block element will begin a new line. (That is the default
formatting behavior, although <span><strong class="command">xmlformat</strong></span> allows you to
override it.)
</p><p>
Spacing between sub-elements can be controlled, and sub-elements can be
indented. Whitespace in block element text may be normalized. If
normalization is in effect, line-wrapping may be applied as well.
Normalization and line-wrapping may be appropriate for a block element
with mixed content (such as <code class="literal">&lt;para&gt;</code>).
</p></li><li><p>
inline elements
</p><p>
These are elements that are contained within a block or within other
inlines. The DocBook <code class="literal">&lt;emphasis&gt;</code> and
<code class="literal">&lt;literal&gt;</code> elements are examples of inline
elements.
</p><p>
Normalization and line-wrapping of inline element tags and content is
handled the same way as for the enclosing block element. In essence, an
inline element is treated as part of parent's "text" content.
</p></li><li><p>
verbatim elements
</p><p>
No formatting is done for verbatim elements. The DocBook
<code class="literal">&lt;programlisting&gt;</code> and
<code class="literal">&lt;screen&gt;</code> elements are examples of verbatim
elements.
</p><p>
Verbatim element content is written out exactly as it appears in the
input document. This also applies to child elements. Any formatting that
would otherwise be performed on them is suppressed when they occur
within a verbatim element.
</p></li></ul></div><p>
<span><strong class="command">xmlformat</strong></span> never reformats element tags. In
particular, it does not change whitespace betweeen attributes or which
attribute values. This is true even for inline tags within line-wrapped
block elements.
</p><p>
<span><strong class="command">xmlformat</strong></span> handles empty elements as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If an element appears as <code class="literal">&lt;abc/&gt;</code> in the input
document, it is written as <code class="literal">&lt;abc/&gt;</code>.
</p></li><li><p>
If an element appears as <code class="literal">&lt;abc&gt;&lt;/abc&gt;</code>, it
is written as <code class="literal">&lt;abc&gt;&lt;/abc&gt;</code>. No line break
is placed between the two tags.
</p></li></ul></div><p>
XML documents may contain other constructs besides elements and text:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Processing instructions
</p></li><li><p>
Comments
</p></li><li><p>
<code class="literal">DOCTYPE</code> declaration
</p></li><li><p>
<code class="literal">CDATA</code> sections
</p></li></ul></div><p>
<span><strong class="command">xmlformat</strong></span> handles these constructs much the same way
as verbatim elements. It does not reformat them.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="line-breaks-and-indentation"></a>3.2.
Line Breaks and Indentation
</h3></div></div></div><p>
Line breaks within block elements are controlled by the
<code class="literal">entry-break</code>, <code class="literal">element-break</code>, and
<code class="literal">exit-break</code> formatting options. A break value of
<em class="replaceable"><code>n</code></em> means <em class="replaceable"><code>n</code></em>
newlines. (This produces <em class="replaceable"><code>n</code></em>-1 blank lines.)
</p><p>
Example. Suppose input text looks like this:
</p><pre class="screen">
&lt;elt&gt;
&lt;subelt/&gt; &lt;subelt/&gt; &lt;subelt/&gt;
&lt;/elt&gt;
</pre><p>
Here, an <code class="literal">&lt;elt&gt;</code> element contains three nested
<code class="literal">&lt;subelt&gt;</code> elements, which for simplicity are
empty.
</p><p>
This input can be formatted several ways, depending on the configuration
options. The following examples show how to do this.
</p><div class="orderedlist"><ol type="1"><li><p>
To produce output with all sub-elements are on the same line as the
<code class="literal">&lt;elt&gt;</code> element, add a section to the
configuration file that defines <code class="literal">&lt;elt&gt;</code> as a
block element and sets all its break values to 0:
</p><pre class="screen">
elt
  format          block
  entry-break     0
  exit-break      0
  element-break   0
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;&lt;subelt/&gt;&lt;subelt/&gt;&lt;subelt/&gt;&lt;/elt&gt;
</pre></li><li><p>
To leave the sub-elements together on the same line, but on a separate
line between the <code class="literal">&lt;elt&gt;</code> tags, leave the
<code class="literal">element-break</code> value set to 0, but set the
<code class="literal">entry-break</code> and <code class="literal">exit-break</code> values
to 1. To suppress sub-element indentation, set
<code class="literal">subindent</code> to 0.
</p><pre class="screen">
elt
  format          block
  entry-break     1
  exit-break      1
  element-break   0
  subindent       0
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;
&lt;subelt/&gt;&lt;subelt/&gt;&lt;subelt/&gt;
&lt;/elt&gt;
</pre></li><li><p>
To indent the sub-elements, make the <code class="literal">subindent</code> value
greater than zero.
</p><pre class="screen">
elt
  format          block
  entry-break     1
  exit-break      1
  element-break   0
  subindent       2
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;
  &lt;subelt/&gt;&lt;subelt/&gt;&lt;subelt/&gt;
&lt;/elt&gt;
</pre></li><li><p>
To cause the each sub-element begin a new line, change the
<code class="literal">element-break</code> to 1.
</p><pre class="screen">
elt
  format          block
  entry-break     1
  exit-break      1
  element-break   1
  subindent       2
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;
  &lt;subelt/&gt;
  &lt;subelt/&gt;
  &lt;subelt/&gt;
&lt;/elt&gt;
</pre></li><li><p>
To add a blank line between sub-elements, increase the
<code class="literal">element-break</code> from 1 to 2.
</p><pre class="screen">
elt
  format          block
  entry-break     1
  exit-break      1
  element-break   2
  subindent       2
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;
  &lt;subelt/&gt;

  &lt;subelt/&gt;

  &lt;subelt/&gt;
&lt;/elt&gt;
</pre></li><li><p>
To also produce a blank line after the <code class="literal">&lt;elt&gt;</code>
opening tag and before the closing tag, increase the
<code class="literal">entry-break</code> and <code class="literal">exit-break</code> values
from 1 to 2.
</p><pre class="screen">
elt
  format          block
  entry-break     2
  exit-break      2
  element-break   2
  subindent       2
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;

  &lt;subelt/&gt;

  &lt;subelt/&gt;

  &lt;subelt/&gt;

&lt;/elt&gt;
</pre></li><li><p>
To have blank lines only after the opening tag and before the closing
tag, but not have blank lines between the sub-elements, decrease the
<code class="literal">element-break</code> from 2 to 1.
</p><pre class="screen">
elt
  format          block
  entry-break     2
  exit-break      2
  element-break   1
  subindent       2
</pre><p>
Result:
</p><pre class="screen">
&lt;elt&gt;

  &lt;subelt/&gt;
  &lt;subelt/&gt;
  &lt;subelt/&gt;

&lt;/elt&gt;
</pre></li></ol></div><p>
Breaks within block elements are suppressed in certain cases:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Breaks apply to nested block or verbatim elements, but not to inline
elements, which are, after all, inline. (If you really want an inline to
begin a new line, define it as a block element.)
</p></li><li><p>
Breaks are not applied to text within non-normalized blocks.
Non-normalized text should not be changed, and adding line breaks
changes the text.
</p><p>
For example if <code class="literal">&lt;x&gt;</code> elements are normalized, you
might elect to format this:
</p><pre class="screen">
&lt;x&gt;This is a sentence.&lt;/x&gt;
</pre><p>
Like this:
</p><pre class="screen">
&lt;x&gt;
This is a sentence.
&lt;/x&gt;
</pre><p>
Here, breaks are added before and after the text to place it on a
separate line. But if <code class="literal">&lt;x&gt;</code> is not normalized,
the text content will be written as it appears in the input, to avoid
changing it.
</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="text-handling"></a>3.3.
Text Handling
</h3></div></div></div><p>
The XML standard considers whitespace nodes insignificant in elements
that contain only other elements. In other words, for elements that have
element content, sub-elements may optionally be separated by whitespace,
but that whitespace is insignificant and may be ignored.
</p><p>
An element that has mixed content may have text
(<code class="literal">#PCDATA</code>) content, optionally interspersed with
sub-elements. In this case, whitespace-only nodes may be significant.
</p><p>
<span><strong class="command">xmlformat</strong></span> treats only literal whitespace as
whitespace. This includes the space, tab, newline (linefeed), and
carriage return characters. <span><strong class="command">xmlformat</strong></span> does not
resolve entity references, so entities such as
<code class="literal">&amp;#32;</code> or <code class="literal">&amp;#x20;</code> that
represent whitespace characters are seen as non-whitespace text, not as
whitespace.
</p><p>
<span><strong class="command">xmlformat</strong></span> doesn't know whether a block element has
element content or mixed content. It handles text content as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If an element has element content, it will have only sub-elements and
possibly all-whitespace text nodes. In this case, it is assumed that
you'll want to control line-break behavior between sub-elements, so that
the (all-whitespace) text nodes can be discarded and replaced with the
proper number of newlines, and possibly indentation.
</p></li><li><p>
If an element has mixed content, you may want to leave text nodes alone,
or you may want to normalize (and possibly line-wrap) them. In
<span><strong class="command">xmlformat</strong></span>, normalization converts runs of whitespace
characters to single spaces, and discards leading and trailing
whitespace.
</p></li></ul></div><p>
To achieve this kind of formatting, <span><strong class="command">xmlformat</strong></span>
recognizes <code class="literal">normalize</code> and
<code class="literal">wrap-length</code> configuration options for block elements.
They affect text formatting as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
You can enable or disable text normalization by setting the
<code class="literal">normalize</code> option to <code class="literal">yes</code> or
<code class="literal">no</code>.
</p></li><li><p>
Within a normalized block, runs of whitespace are converted to single
spaces. Leading and trailing whitespace is discarded. Line-wrapping and
indenting may be applied.
</p></li><li><p>
In a non-normalized block, text nodes are not changed as long as they
contain any non-whitespace characters. No line-wrapping or indenting is
applied. However, if a text node contains only whitespace (for example,
a space or newline between sub-elements), it is assumed to be
insignficant and is discarded. It may be replaced by line breaks and
indentation when output formatting occurs.
</p></li></ul></div><p>
Consider the following input:
</p><pre class="screen">
&lt;row&gt; &lt;cell&gt; A &lt;/cell&gt; &lt;cell&gt; B &lt;/cell&gt; &lt;/row&gt;
</pre><p>
Suppose that the <code class="literal">&lt;row&gt;</code> and
<code class="literal">&lt;cell&gt;</code> elements both are to be treated as
non-normalized. The contents of the <code class="literal">&lt;cell&gt;</code>
elements are text nodes that contain non-whitespace characters, so they
would not be reformatted. On the other hand, the spaces between tags are
all-whitespace text nodes and are not significant. This means that you
could reformat the input like this:
</p><pre class="screen">
&lt;row&gt;&lt;cell&gt; A &lt;/cell&gt;&lt;cell&gt; B &lt;/cell&gt;&lt;/row&gt;
</pre><p>
Or like this:
</p><pre class="screen">
&lt;row&gt;
&lt;cell&gt; A &lt;/cell&gt;&lt;cell&gt; B &lt;/cell&gt;
&lt;/row&gt;
</pre><p>
Or like this:
</p><pre class="screen">
&lt;row&gt;
  &lt;cell&gt; A &lt;/cell&gt;
  &lt;cell&gt; B &lt;/cell&gt;
&lt;/row&gt;
</pre><p>
In each of those cases, the whitespace between tags was subject to
reformatting, but the text content of the
<code class="literal">&lt;cell&gt;</code> elements was not.
</p><p>
The input would <span class="emphasis"><em>not</em></span> be formatted like this:
</p><pre class="screen">
&lt;row&gt;&lt;cell&gt;A&lt;/cell&gt;&lt;cell&gt;B&lt;/cell&gt;&lt;/row&gt;
</pre><p>
Or like this:
</p><pre class="screen">
&lt;row&gt;
  &lt;cell&gt;
    A
  &lt;/cell&gt;
  &lt;cell&gt;
   B
  &lt;/cell&gt;
&lt;/row&gt;
</pre><p>
In both of those cases, the text content of the
<code class="literal">&lt;cell&gt;</code> elements has been modified, which is not
allowed within non-normalized blocks. You would have to declare
<code class="literal">&lt;cell&gt;</code> to have a <code class="literal">normalize</code>
value of <code class="literal">yes</code> to achieve either of those output
styles.
</p><p>
Now consider the following input:
</p><pre class="screen">
&lt;para&gt; This is a        sentence. &lt;/para&gt;
</pre><p>
Suppose that <code class="literal">&lt;para&gt;</code> is to be treated as a
normalized element. It could be reformatted like this:
</p><pre class="screen">
&lt;para&gt;This is a sentence.&lt;/para&gt;
</pre><p>
Or like this:
</p><pre class="screen">
&lt;para&gt;
This is a sentence.
&lt;/para&gt;
</pre><p>
Or like this:
</p><pre class="screen">
&lt;para&gt;
  This is a sentence.
&lt;/para&gt;
</pre><p>
Or even (with line-wrapping) like this:
</p><pre class="screen">
&lt;para&gt;
  This is a
  sentence.
&lt;/para&gt;
</pre><p>
The preceding description of normalization is a bit oversimplified.
Normalization is complicated by the possibility that non-normalized
elements may occur as sub-elements of a normalized block. In the
following example, a verbatim block occurs in the middle of a normalized
block:
</p><pre class="screen">
&lt;para&gt;This is a paragraph that contains
&lt;programlisting&gt;
a code listing
&lt;/programlisting&gt;
in the middle.
&lt;/para&gt;
</pre><p>
In general, when this occurs, any whitespace in text nodes adjacent to
non-reformatted nodes is discarded.
</p><p>
There is no "preserve all whitespace as is" mode for block elements.
Even if normalization is disabled for a block, any all-whitespace text
nodes are considered dispensible. If you really want all text within an
element to be preserved intact, you should declare it as a verbatim
element. (Within verbatim elements, nothing is ever reformatted, so
whitespace is significant as a result.)
</p><p>
If you want to see how <span><strong class="command">xmlformat</strong></span> handles whitespace
nodes and text normalization, invoke it with the
<code class="option">--canonized-output</code> option. This option causes
<span><strong class="command">xmlformat</strong></span> to display the document after it has been
canonized by removing whitespace nodes and performing text
normalization, but before it has been reformatted in final form. By
examining the canonized document, you can see what effect your
configuration options have on treatment of the document before
line-wrapping and indentation is performed and line breaks are added.
</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="using-config-files"></a>4.
Using Configuration Files
</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="#config-file-syntax">4.1. 
Configuration File Syntax
</a></span></dt><dt><span class="sect2"><a href="#formatting-options">4.2. 
Formatting Options
</a></span></dt></dl></div><p>
An <span><strong class="command">xmlformat</strong></span> configuration file specifies formatting
options to be associated with particular elements in XML documents. For
example, you can format <code class="literal">&lt;itemizedlist&gt;</code> elements
differently than <code class="literal">&lt;orderedlist&gt;</code> elements.
(However, you cannot format <code class="literal">&lt;listitem&gt;</code> elements
differentially depending on the type of list in which they occur.) You
can also specify options for a "pseudo-element" named
<code class="literal">*DEFAULT</code>. These options are applied to any element
for which the options are not specified explicitly.
</p><p>
The following sections describe the general syntax of configuration
files, then discuss the allowable formatting options that can be
assigned to elements.
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="config-file-syntax"></a>4.1.
Configuration File Syntax
</h3></div></div></div><p>
A configuration file consists of sections. Each section begins with a
line that names one or more elements. (Element names do not include the
"&lt;" and "&gt;" angle brackets.) The element line is followed by
option lines that each name a formatting option and its value. Each
option is applied to every element named on its preceding element line.
</p><p>
Element lines and option lines are distinguished based on leading
whitespace (space or tab characters):
</p><div class="itemizedlist"><ul type="disc"><li><p>
Element lines have no leading whitespace.
</p></li><li><p>
Option lines begin with at least one whitespace character.
</p></li></ul></div><p>
On element lines that name multiple elements, the names should be
separated by spaces or commas. These are legal element lines:
</p><pre class="screen">
para title
para,title
para, title
</pre><p>
On option lines, the option name and value should be separated by
whitespace and/or an equal sign. These are legal option lines:
</p><pre class="screen">
normalize yes
normalize=yes
normalize = yes
</pre><p>
Blank lines are ignored.
</p><p>
Lines that begin "#" as the first non-white character are taken as
comments and ignored. Comments beginning with "#" may also follow the
last element name on an element line or the option value on an option
line.
</p><p>
Example configuration file:
</p><pre class="screen">
para
  format        block
  entry-break   1
  exit-break    1
  normalize     yes
  wrap-length   72

literal replaceable userinput command option emphasis
  format        inline

programlisting
  format        verbatim
</pre><p>
It is not necessary to specify all of an element's options at the same
time. Thus, this configuration file:
</p><pre class="screen">
para, title
  format block
  normalize yes
title
  wrap-length 50
para
  wrap-length 72
</pre><p>
Is equivalent to this configuration file:
</p><pre class="screen">
para
  format block
  normalize yes
  wrap-length 72
title
  format block
  normalize yes
  wrap-length 50
</pre><p>
If an option is specified multiple times for an element, the last value
is used. For the following configuration file, <code class="literal">para</code>
ends up with a <code class="literal">wrap-length</code> value of 68:
</p><pre class="screen">
para
  format        block
  wrap-length   60
  wrap-length   72
para
  wrap-length   68
</pre><p>
To continue an element line onto the next line, end it with a backslash
character. <span><strong class="command">xmlformat</strong></span> will interpret the next line as
containing more element names for the current section:
</p><pre class="screen">
chapter appendix article \
section simplesection \
sect1 sect2 sect3 \
sect4 sect5
  format        block
  entry-break   1
  element-break 2
  exit-break    1
  normalize     no
  subindent     0
</pre><p>
Continuation can be useful when you want to apply a set of formatting
options to a large number of elements. Continuation lines are allowed to
begin with whitespace (though it's possible they may appear to the
casual observer to be option lines if they do).
</p><p>
Continuation is not allowed for option lines.
</p><p>
A configuration file may contain options for two special
"pseudo-element" names: <code class="literal">*DOCUMENT</code> and
<code class="literal">*DEFAULT</code>. (The names begin with a "*" character so as
not to conflict with valid element names.)
</p><p>
<code class="literal">*DEFAULT</code> options apply to any element that appears in
the input document but that was not configured explicitly in the
configuration file.
</p><p>
<code class="literal">*DOCUMENT</code> options are used primarily to control line
breaking between top-level nodes of the document, such as the XML
declaration, the <code class="literal">DOCTYPE</code> declaration, the root
element, and any comments or processing instructions that occur outside
the root element.
</p><p>
It's common to supply <code class="literal">*DEFAULT</code> options in a
configuration file to override the built-in values. However, it's
normally best to leave the <code class="literal">*DOCUMENT</code> options alone,
except possibly to change the <code class="literal">element-break</code> value.
</p><p>
Before reading the input document, <span><strong class="command">xmlformat</strong></span> sets up
formatting options as follows:
</p><div class="orderedlist"><ol type="1"><li><p>
It initializes the built-in <code class="literal">*DOCUMENT</code> and
<code class="literal">*DEFAULT</code> options,
</p></li><li><p>
It reads the contents of the configuration file, assigning formatting
options to elements as listed in the file.
</p><p>
Note that although <code class="literal">*DOCUMENT</code> and
<code class="literal">*DEFAULT</code> have built-in default values, the defaults
they may be overridden in the configuration file.
</p></li><li><p>
After reading the configuration file, any missing formatting options for
each element are filled in using the options from the
<code class="literal">*DEFAULT</code> pseudo-element. For example, if
<code class="literal">para</code> is defined as a block element but no
<code class="literal">subindent</code> value is defined, <code class="literal">para</code>
"inherits" the <code class="literal">subindent</code> value from the
<code class="literal">*DEFAULT</code> settings.
</p></li></ol></div><p>
Missing options are filled in from the <code class="literal">*DEFAULT</code>
options only <span class="emphasis"><em>after</em></span> reading the entire configuration
file. For the settings below, <code class="literal">*DEFAULT</code> has a
<code class="literal">subindent</code> value of 2 (not 0) after the file has been
read. Thus, <code class="literal">para</code> also is assigned a
<code class="literal">subindent</code> value of 2.
</p><pre class="screen">
*DEFAULT
  subindent 0
para
  format block
  normalize yes
*DEFAULT
  subindent 2
</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="formatting-options"></a>4.2.
Formatting Options
</h3></div></div></div><p>
The allowable formatting options are as follows:
</p><pre class="screen">
format {block | inline | verbatim}
entry-break <em class="replaceable"><code>n</code></em>
element-break <em class="replaceable"><code>n</code></em>
exit-break <em class="replaceable"><code>n</code></em>
subindent <em class="replaceable"><code>n</code></em>
normalize {no | yes}
wrap-length <em class="replaceable"><code>n</code></em>
</pre><p>
A value list shown as <code class="literal">{ value1 | value2 | ... }</code>
indicates that the option must take one of the values in the list. A
value shown as <em class="replaceable"><code>n</code></em> indicates that the option
must have a numeric value.
</p><p>
Details for each of the formatting options follow.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">format {block | inline | verbatim}</code>
</p><p>
This option is the most important, because it determines the general way
in which the element is formatted, and it determines whether the other
formatting options are used or ignored:
</p><div class="itemizedlist"><ul type="circle"><li><p>
For block elements, all other formatting options are significant.
</p></li><li><p>
For inline elements, all other formatting options are ignored. Inline
elements are normalized, wrapped, and indented according to the
formatting options of the enclosing block element.
</p></li><li><p>
For verbatim elements, all other formatting options are ignored. The
element content is written out verbatim (literally), without change,
even if it contains other sub-elements. This means no normalization of
the contents, no indenting, and no line-wrapping. Nor are any breaks
added within the element.
</p></li></ul></div><p>
A configuration file may <span class="emphasis"><em>specify</em></span> any option for
elements of any type, but <span><strong class="command">xmlformat</strong></span> will ignore
inapplicable options. One reason for this is to allow you to experiment
with changing an element's format type without having to disable other
options.
</p><p>
If you use the <code class="option">--show-config</code> command-line option to see
the configuration that <span><strong class="command">xmlformat</strong></span> will use for
processing a document, it displays only the applicable options for each
element.
</p></li><li><p>
<code class="literal">entry-break <em class="replaceable"><code>n</code></em></code>
</p><p>
<code class="literal">element-break <em class="replaceable"><code>n</code></em></code>
</p><p>
<code class="literal">exit-break <em class="replaceable"><code>n</code></em></code>
</p><p>
These options indicate the number of newlines (line breaks) to write
after the element opening tag, between child sub-elements, and before
the element closing tag. They apply only to block elements.
</p><p>
A value of 0 means "no break". A value of 1 means one newline, which
causes the next thing to appear on the next line with no intervening
blank line. A value <em class="replaceable"><code>n</code></em> greater than 1 produces
<em class="replaceable"><code>n</code></em>-1 intervening blank lines. Some examples:
</p><div class="itemizedlist"><ul type="circle"><li><p>
An <code class="literal">entry-break</code> value of 0 means the next token will
appear on same line immediately after the opening tag.
</p></li><li><p>
An <code class="literal">exit-break</code> value of 0 means the closing tag will
appear on same line immediately after the preceding token.
</p></li></ul></div></li><li><p>
<code class="literal">subindent <em class="replaceable"><code>n</code></em></code>
</p><p>
This option indicates the number of spaces by which to indent child
sub-elements, relative to the indent of the enclosing parent. It applies
only to block elements. The value may be 0 to suppress indenting, or a
number <em class="replaceable"><code>n</code></em> greater than 0 to produce indenting.
</p><p>
This option does not affect the indenting of the element itself. That is
determined by the <code class="literal">subindent</code> value of the element's
own parent.
</p><p>
Note: <code class="literal">subindent</code> does not apply to text nodes in
non-normalized blocks, which are written as is without reformatting.
<code class="literal">subindent</code> also does not apply to verbatim elements or
to the following non-element constructs, all of which are written with
no indent:
</p><div class="itemizedlist"><ul type="circle"><li><p>
Processing instructions
</p></li><li><p>
Comments
</p></li><li><p>
<code class="literal">DOCTYPE</code> declarations
</p></li><li><p>
<code class="literal">CDATA</code> sections
</p></li></ul></div></li><li><p>
<code class="literal">normalize {no | yes}</code>
</p><p>
This option indicates whether or not to perform whitespace normalization
in text. This option is used for block elements, but it also affects
inline elements because their content is normalized the same way as
their enclosing block element.
</p><p>
If the value is <code class="literal">no</code>, whitespace-only text nodes are
not considered significant and are discarded, possibly to be replaced
with line breaks and indentation.
</p><p>
If the value is <code class="literal">yes</code>, normalization causes removal of
leading and trailing whitespace within the element, and conversion of
runs of whitespace characters (including line-ending characters) to
single spaces.
</p><p>
Text normalization is discussed in more detail in
<a href="#text-handling" title="3.3.
Text Handling
">Section3.3, &#8220;
Text Handling
&#8221;</a>.
</p></li><li><p>
<code class="literal">wrap-length <em class="replaceable"><code>n</code></em></code>
</p><p>
Line-wrapping length. This option is used only for block elements and
line-wrapping occurs only if normalization is enabled. The option
affects inline elements because they are line-wrapped the same way as
their enclosing block element.
</p><p>
Setting the <code class="literal">wrap-length</code> option to 0 disables
wrapping. Setting it to a value <em class="replaceable"><code>n</code></em> greater
than 0 enables wrapping to lines at most <em class="replaceable"><code>n</code></em>
characters long. (Exception: If a word longer than
<em class="replaceable"><code>n</code></em> characters occurs in text to be wrapped, it
is placed on a line by itself. A word will never be broken into pieces.)
The line length is adjusted by the current indent when wrapping is
performed to keep the right margin of wrapped text constant. For example
if the <code class="literal">wrap-length</code> value is 60 and the current indent
is 10, lines are wrapped to a maximum of 50 characters.
</p><p>
Any prevailing indent is added to the beginning of each line, unless the
text will be written immediately following a tag on the same line. This
can occur if the text occurs after the opening tag of the block and the
<code class="literal">entry-break</code> is 0, or the text occurs after the
closing tag of a sub-element and the <code class="literal">element-break</code> is
0.
</p></li></ul></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-xmlformat-works"></a>5.
How <span><strong class="command">xmlformat</strong></span> Works
</h2></div></div></div><p>
Briefly, <span><strong class="command">xmlformat</strong></span> processes an XML document using
the following steps:
</p><div class="orderedlist"><ol type="1"><li><p>
Read the document into memory as a single string.
</p></li><li><p>
Parse the document into a list of tokens.
</p></li><li><p>
Convert the list of tokens into nodes in a tree structure, tagging each
node according to the token type.
</p></li><li><p>
Discard extraneous whitespace nodes and normalize text nodes. (The
meaning of "normalize" is described in <a href="#text-handling" title="3.3.
Text Handling
">Section3.3, &#8220;
Text Handling
&#8221;</a>.)
</p></li><li><p>
Process the tree to produce a single string representing the reformatted
document.
</p></li><li><p>
Print the string.
</p></li></ol></div><p>
<span><strong class="command">xmlformat</strong></span> is not an XSLT processor. In essence, all
it does is add or delete whitespace to control line breaking,
indentation, and text normalization.
</p><p>
<span><strong class="command">xmlformat</strong></span> uses the REX parser developed by Robert D.
Cameron (see <a href="#references" title="7.
References
">Section7, &#8220;
References
&#8221;</a>). REX performs a parse based
on a regular expression that operates on a string representing the XML
document. The parse produces a list of tokens. REX does a pure lexical
scan that performs no alteration of the text except to tokenize it. In
particular:
</p><div class="itemizedlist"><ul type="disc"><li><p>
REX doesn't normalize any whitespace, including line endings. This is
true for text elements, and for whitespace within tags (including
between attributes and within attribute values). Any normalization or
reformatting to be done is performed in later stages of
<span><strong class="command">xmlformat</strong></span> operation.
</p></li><li><p>
REX leaves entity references untouched. It doesn't try to resolve them.
This means it doesn't complain about undefined entities, which to my
mind is an advantage. (A pretty printer shouldn't have to read a DTD or
a schema.)
</p></li><li><p>
If the XML is malformed, errors can be detected easily: REX produces
error tokens that begin with "&lt;" but do not end with "&gt;".
</p></li></ul></div><p>
<span><strong class="command">xmlformat</strong></span> expects its input documents to be legal
XML. It does not consider fixing broken documents to be its job, so if
<span><strong class="command">xmlformat</strong></span> finds error tokens in the result produced
by REX, it lists them and exits.
</p><p>
Assuming the document contains no error tokens,
<span><strong class="command">xmlformat</strong></span> uses the token list to construct a tree
structure. It categorizes each token based on its initial characters:
</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Initial Characters</th><th>Token Type</th></tr></thead><tbody><tr><td><code class="literal">&lt;!--</code></td><td>comment</td></tr><tr><td><code class="literal">&lt;?</code></td><td>processing instruction (this includes the <code class="literal">&lt;?xml?&gt;</code> instruction)</td></tr><tr><td><code class="literal">&lt;!DOCTYPE</code></td><td><code class="literal">DOCTYPE</code> declaration</td></tr><tr><td><code class="literal">&lt;![</code></td><td><code class="literal">CDATA</code> section</td></tr><tr><td><code class="literal">&lt;/</code></td><td>element closing tag</td></tr><tr><td><code class="literal">&lt;</code></td><td>element opening tag</td></tr></tbody></table></div><p>
Anything token not beginning with one of the sequences shown in the
preceding table is a text token.
</p><p>
The token categorization determineas the node types of nodes in the
document tree. Each node has a label that identifies the node type:
</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Label</th><th>Node Type</th></tr></thead><tbody><tr><td><code class="literal">comment</code></td><td>comment node</td></tr><tr><td><code class="literal">pi</code></td><td>processing instruction node</td></tr><tr><td><code class="literal">DOCTYPE</code></td><td><code class="literal">DOCTYPE</code> declaration node</td></tr><tr><td><code class="literal">CDATA</code></td><td><code class="literal">CDATA</code> section node</td></tr><tr><td><code class="literal">elt</code></td><td>element node</td></tr><tr><td><code class="literal">text</code></td><td>text node</td></tr></tbody></table></div><p>
If the document is not well-formed, tree construction will fail. In this
case, <span><strong class="command">xmlformat</strong></span> displays one or more error messages
and exits. For example, this document is invalid:
</p><pre class="screen">
&lt;p&gt;This is a &lt;strong&gt;malformed document.&lt;/p&gt;
</pre><p>
Running that document through <span><strong class="command">xmlformat</strong></span> produces the
following result:
</p><pre class="screen">
MISMATCH open (strong), close (p); malformed document?
Non-empty tag stack; malformed document?
Non-empty children stack; malformed document?
Cannot continue.
</pre><p>
That is admittedly cryptic, but remember that it's not
<span><strong class="command">xmlformat</strong></span>'s job to repair (or even diagnose) bad XML.
If a document is not well-formed, you may find Tidy a useful tool for
fixing it up.
</p><p>
Tokens of each type except element tokens correspond to single distinct
nodes in the document. Elements are more complex. They may consist of
multiple tokens, and may contain children:
</p><div class="itemizedlist"><ul type="disc"><li><p>
An element with a combined opening/closing tag (such as
<code class="literal">&lt;abc/&gt;</code>) consists of a single token.
</p></li><li><p>
An element with separate opening and closing tags (such as
<code class="literal">&lt;abc&gt;...&lt;/abc&gt;</code>) consists of at least the
two tags, plus any children that appear between the tags.
</p></li></ul></div><p>
Element opening tag tokens include any attributes that are present,
because <span><strong class="command">xmlformat</strong></span> performs no tag reformatting. Tags
are preserved intact in the output, including any whitespace between
attributes or within attribute values.
</p><p>
In addition to the type value that labels a node as a given node type,
each node has content:
</p><div class="itemizedlist"><ul type="disc"><li><p>
For all node types except elements, the content is the text of the token
from which the node was created.
</p></li><li><p>
For element nodes, the content is the list of child nodes that appear
within the element. An empty element has an empty child node list. In
addition to the content, element nodes contain other information:
</p><div class="itemizedlist"><ul type="circle"><li><p>
The literal text of the opening and closing tags. If an element is
written in single-tag form (<code class="literal">&lt;abc/&gt;</code>), the
closing tag is empty.
</p></li><li><p>
The element name that is present in the opening tag. (This is maintained
separately from the opening tag so that a pattern match need not be done
on the opening tag each time it's necessary to determine the element
name.)
</p></li></ul></div></li></ul></div><p>
After constructing the node tree, <span><strong class="command">xmlformat</strong></span> performs
two operations on it:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The tree is "canonized" to normalize text nodes and to discard
extraneous whitespace nodes. A whitespace node is a text node consisting
of nothing but whitespace characters (space, tab, carriage return,
linefeed (newline)). Decisions about which whitespace nodes are
extraneous are based on the configuration options supplied to
<span><strong class="command">xmlformat</strong></span>.
</p></li><li><p>
The canonized tree is used to produce formatted output.
<span><strong class="command">xmlformat</strong></span> performs line-wrapping of element content,
and adds indentation and line breaks. Decisions about how to apply these
operations are based on the configuration options.
</p></li></ul></div><p>
Here's an example input document, representing a single-row table:
</p><pre class="screen">
&lt;table&gt;
  &lt;row&gt;
    &lt;cell&gt;1&lt;/cell&gt;&lt;cell&gt;2&lt;/cell&gt;
    &lt;cell&gt;3&lt;/cell&gt;
  &lt;/row&gt;&lt;/table&gt;
</pre><p>
After reading this in and constructing the tree, the canonized output
looks like this:
</p><pre class="screen">
&lt;table&gt;&lt;row&gt;&lt;cell&gt;1&lt;/cell&gt;&lt;cell&gt;2&lt;/cell&gt;&lt;cell&gt;3&lt;/cell&gt;&lt;/row&gt;&lt;/table&gt;
</pre><p>
The output after applying the default formatting options looks like
this:
</p><pre class="screen">
&lt;table&gt;
 &lt;row&gt;
  &lt;cell&gt;1&lt;/cell&gt;
  &lt;cell&gt;2&lt;/cell&gt;
  &lt;cell&gt;3&lt;/cell&gt;
 &lt;/row&gt;
&lt;/table&gt;
</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prerequisites"></a>6.
Prerequisites
</h2></div></div></div><p>
<span><strong class="command">xmlformat</strong></span> has very few prerequisites. It requires no
extra modules other than an option-processing module. In particular:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<span><strong class="command">xmlformat</strong></span> requires no XML processing modules. XML
parsing is done with a single (rather complex) regular expression
developed by Robert D. Cameron. A paper that discusses development of
this parsing expression is available; see <a href="#references" title="7.
References
">Section7, &#8220;
References
&#8221;</a>.
</p></li><li><p>
<span><strong class="command">xmlformat</strong></span> requires no text-processing modules such as
Text::Wrap. I tested Text::Wrap to see if it was suitable for
<span><strong class="command">xmlformat</strong></span>. It was not, for the following reasons:
</p><div class="itemizedlist"><ul type="circle"><li><p>
If Text::Wrap encounters an individual word that is longer than the line
length, older versions of Text::Wrap invoke die(). In newer versions,
you can have long words left intact.
</p></li><li><p>
Text::Wrap converts runs of spaces in the leading indent to tabs.
(Though this can be suppressed.)
</p></li><li><p>
Text::Wrap reformats inline tags (and may change attribute values).
<span><strong class="command">xmlformat</strong></span> preserves tags intact.
</p></li></ul></div><p>
In addition, the simple algorithm used by <span><strong class="command">xmlformat</strong></span>
appears to be about twice as fast as Text::Wrap (at least on Mac OS X).
</p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="references"></a>7.
References
</h2></div></div></div><div class="orderedlist"><ol type="1"><li><p>
Original REX paper by Robert D. Cameron:
</p><pre class="screen">
<a href="http://www.cs.sfu.ca/~cameron/REX.html" target="_top">http://www.cs.sfu.ca/~cameron/REX.html</a>
<a href="ftp://fas.sfu.ca/pub/cs/TR/1998/CMPT1998-17.html" target="_top">ftp://fas.sfu.ca/pub/cs/TR/1998/CMPT1998-17.html</a>
</pre><p>
</p><p>
This paper contains REX implementations in Perl, JavaScript, and LEX.
The Perl implementation was used as the basis of XML parsing in
<span><strong class="command">xmlformat.pl</strong></span> and <span><strong class="command">xmlformat.rb</strong></span>.
</p></li><li><p>
A Python implementation of REX:
</p><pre class="screen">
<a href="http://mail.python.org/pipermail/xml-sig/1999-November/001628.html" target="_top">http://mail.python.org/pipermail/xml-sig/1999-November/001628.html</a>
</pre><p>
</p></li><li><p>
A PHP implementation of REX:
</p><pre class="screen">
<a href="http://traumwind.de/computer/php/REX/" target="_top">http://traumwind.de/computer/php/REX/</a>
</pre><p>
</p></li></ol></div></div></div></body></html>