<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
>
<article>

<title>
<command>xmlformat</command> Tutorial
</title>

<articleinfo>
 <author>
  <surname>DuBois</surname>
  <firstname>Paul</firstname>
  <email>paul@kitebird.com</email>
 </author>
</articleinfo>

<sect1 id="introduction">

<title>
Introduction
</title>

<para>
This document is a user guide that provides a tutorial introduction to
the <command>xmlformat</command> program. Another document,
<citetitle>The <command>xmlformat</command> Document
Formatter</citetitle>, describes the capabilities of
<command>xmlformat</command> in more detail.
</para>

</sect1>

<sect1 id="formatting-document">

<title>
Formatting a Document
</title>

<para>
Suppose you have an XML document named <filename>doc1.xml</filename>
that looks like this:
</para>

<!-- xmlize -t screen -C examples/doc1.xml -->

<screen>
<![CDATA[<event>
<description>I bought a new coffee cup!</description>
<date><year>2004</year><month>2</month><day>1</day></date>
</event>]]>
</screen>

<para>
Suppose further that you want it to look like this:
</para>

<!-- ../xmlformat.rb -f /dev/null examples/doc1.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<event>
 <description>I bought a new coffee cup!</description>
 <date>
  <year>2004</year>
  <month>2</month>
  <day>1</day>
 </date>
</event>]]>
</screen>

<para>
By happy coincidence, that happens to be exactly the default output
style produced by <command>xmlformat</command>. To reformat your
document, all you have to do is run <command>xmlformat</command> with
the document filename as the argument, saving the output in another
file:
</para>

<screen>
% <userinput>xmlformat doc1.xml &gt; output</userinput>
</screen>

<para>
Note: <literal>%</literal> represents your shell prompt; do not type it
as part of the command.
</para>

<para>
If you are confident that the output style produced by
<command>xmlformat</command> will be as you desire, you can be reckless
and perform an in-place conversion:
</para>

<screen>
% <userinput>xmlformat -i doc1.xml</userinput>
</screen>

<para>
In this case, <command>xmlformat</command> reads the document from the
input file, reformats it, and writes it back out to the same file,
replacing the file's original contents. If you are not quite so
reckless, use <option>-i</option> in conjunction with a
<option>-b</option> option to make a backup file that contains the
original document. <option>-b</option> takes an argument that specifies
the suffix to add to the original filename to create the backup
filename. For example, to back up the original
<filename>doc1.xml</filename> file in a file named
<filename>doc1.xml.bak</filename>, use this command:
</para>

<screen>
% <userinput>xmlformat -i -b .bak doc1.xml</userinput>
</screen>

</sect1>

<sect1 id="using-config-file">

<title>
Using a Configuration File
</title>

<para>
In the preceding example, the desired output style for
<filename>doc1.xml</filename> was the same as what
<command>xmlformat</command> produces by default. But what if the
default style is <emphasis>not</emphasis> what you want? In that case,
you must tell <command>xmlformat</command> how to handle your document.
This is at once both the weakness and strength of
<command>xmlformat</command>. The weakness is that it is extra work to
instruct <command>xmlformat</command> how you want it to format a
document. The strength is that it's possible to do so. Other XML
formatters do not require any extra work, but that's because they are
not configurable.
</para>

<para>
Suppose <filename>doc2.xml</filename> looks like this:
</para>

<!-- xmlize -t screen -C examples/doc2.xml -->

<screen>
<![CDATA[<example><title>Compiling and Running a Program</title>
<para>To compile and run the program,
use the following commands, where
<replaceable>source-file</replaceable>
is the name of the source file:</para><screen>
<userinput>cc</userinput> <replaceable>source-file</replaceable>
<userinput>./a.out</userinput>
</screen>
</example>]]>
</screen>

<para>
That's ugly, and you want it to rewrite it like this:
</para>

<!-- ../xmlformat.rb -f examples/doc2.conf4 examples/doc2.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<example>

<title>Compiling and Running a Program</title>

<para>
 To compile and run the program, use the following commands,
 where <replaceable>source-file</replaceable> is the name of
 the source file:
</para>

<screen>
<userinput>cc</userinput> <replaceable>source-file</replaceable>
<userinput>./a.out</userinput>
</screen>

</example>]]>
</screen>

<para>
The key characteristics of this rewrite are as follows:
</para>

<itemizedlist>

<listitem><para>
Child elements of the <literal>&lt;example&gt;</literal> element are
separated by blank lines, but not indented within it.
</para></listitem>

<listitem><para>
The text inside the <literal>&lt;para&gt;</literal> element is
reformatted, adjusted to 60 characters per line and indented.
</para></listitem>

<listitem><para>
The contents of the <literal>&lt;screen&gt;</literal> element are left
alone.
</para></listitem>

</itemizedlist>

<para>
Unfortunately, if you run <filename>doc2.xml</filename> through
<command>xmlformat</command>, it comes out like this:
</para>

<!-- ../xmlformat.rb -f /dev/null examples/doc2.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<example>
 <title>Compiling and Running a Program</title>
 <para>To compile and run the program,
use the following commands, where
<replaceable>source-file</replaceable>
is the name of the source file:</para>
 <screen>
  <userinput>cc</userinput>
  <replaceable>source-file</replaceable>
  <userinput>./a.out</userinput>
 </screen>
</example>]]>
</screen>

<para>
This output is unsuitable. Among the offenses committed by
<command>xmlformat</command>, two are most notable:
</para>

<itemizedlist>

<listitem><para>
The text of the <literal>&lt;para&gt;</literal> element has been left
alone, not reformatted.
</para></listitem>

<listitem><para>
The <literal>&lt;screen&gt;</literal> element content has been
reformatted, not left intact.
</para></listitem>

</itemizedlist>

<para>
In these respects, it appears that <command>xmlformat</command> has done
exactly the <emphasis>opposite</emphasis> of what was wanted!
Furthermore, had you used the <option>-i</option> option to reformat the
file in place without using <option>-b</option> to make a backup, at
this point you would have a file containing a
<literal>&lt;screen&gt;</literal> element that you'd have to fix up by
hand to restore it to its original condition.
</para>

<para>
What a worthless, worthless program!
</para>

<para>
The rewriting of the <literal>&lt;screen&gt;</literal> element points to
an important lesson: Before trusting <command>xmlformat</command> with
your documents, it's best to run some tests and tune your configuration
as necessary to make sure it will produce the results you want.
Otherwise, you may produce changes that affect the integrity of your
documents. This is particularly true when they contain elements such as
<literal>&lt;screen&gt;</literal> or
<literal>&lt;programlisting&gt;</literal> that should be copied
verbatim, without change.
</para>

<para>
Configuring <command>xmlformat</command> amounts to writing a
configuration file that instructs it what to do. For
<filename>doc2.xml</filename>, that means telling
<command>xmlformat</command> to leave the
<literal>&lt;screen&gt;</literal> element alone, to normalize the text
of the paragraph to fill lines and wrap them to a given length, and to
put blank lines around sub-elements of the
<literal>&lt;example&gt;</literal> element.
</para>

<para>
Let's begin by creating a very basic configuration file. What should we
call it? <command>xmlformat</command> can read configuration settings
from a file named on the command line with a <option>-f</option> or
<option>--config-file</option> option. This means you can name the file
whatever you want. However, if you put the settings in a file named
<filename>xmlformat.conf</filename> in the current directory,
<command>xmlformat</command> will read the file automatically. That's an
easier approach, because you won't need to use a command-line option to
specify the configuration file. So create a file named
<filename>xmlformat.conf</filename> that contains the following two
lines:
</para>

<screen>
screen
  format = verbatim
</screen>

<para>
These lines specify that <literal>&lt;screen&gt;</literal> elements
should be formatted as verbatim elements. That is,
<command>xmlformat</command> should reproduce their content in the
output exactly as it appears in the input, without modification. The
first line must begin in column 1 (no preceding spaces or tabs). The
second line must begin with at least one space or tab. Presence or
absence of whitespace is how <command>xmlformat</command> distinguish
the names of elements to be formatted from the instructions that
indicate <emphasis>how</emphasis> to format them.
</para>

<para>
After creating <filename>xmlformat.conf</filename>, run
<command>xmlformat</command> again to process
<filename>doc2.xml</filename>. It reads the newly created configuration
file and produces this result:
</para>

<!-- ../xmlformat.rb -f examples/doc2.conf1 examples/doc2.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<example>
 <title>Compiling and Running a Program</title>
 <para>To compile and run the program,
use the following commands, where
<replaceable>source-file</replaceable>
is the name of the source file:</para>
<screen>
<userinput>cc</userinput> <replaceable>source-file</replaceable>
<userinput>./a.out</userinput>
</screen>
</example>]]>
</screen>

<para>
That's a little better: <command>xmlformat</command> has not destroyed
the <literal>&lt;screen&gt;</literal> element by reformatting it. But
problems remain: The paragraph content has not been reformatted, and
there are no blank lines between sub-elements.
</para>

<para>
Let's take care of the paragraph next. To set up its formatting, add a
section to <filename>xmlformat.conf</filename> for
<literal>&lt;para&gt;</literal> elements:
</para>

<screen>
para
  format = block
  normalize = yes
  wrap-length = 60
  subindent = 1

screen
  format = verbatim
</screen>

<para>
The order of sections in the configuration file doesn't matter. Put them
in the order that makes most sense to you. The order of option lines
under the initial section line doesn't matter, either.
</para>

<para>
The first two options in the <literal>para</literal> section specify
that the <literal>&lt;para&gt;</literal> element is a block element, and
that text within it should be normalized. Turning on the
<literal>normalize</literal> option tells <command>xmlformat</command>
that it's okay to reformat the text within the element. This means that
runs of whitespace within the text are collapsed to single spaces, and
that whitespace at the beginning and end of the text can be adjusted
(typically to put the text on different lines than the element's opening
and closing tags). Enabling normalization also allows you to perform
text line-wrapping and indenting. The <literal>wrap-length</literal>
option specifies the maximum number of characters per line, and
<literal>subindent</literal> specifies the indenting of text and
sub-elements, relative to the element's own tags. Note that when
<command>xmlformat</command> performs line-wrapping, it includes the
currently prevailing indent as part of the line length. (For example, if
the prevailing indent is 20 spaces and <literal>wrap-length</literal>
value is <literal>60</literal>, lines will contain at most 40 characters
following the indentation.)
</para>

<para>
After adding the <literal>para</literal> section to
<filename>xmlformat.conf</filename>, <command>xmlformat</command>
produces this result:
</para>

<!-- ../xmlformat.rb -f examples/doc2.conf2 examples/doc2.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<example>
 <title>Compiling and Running a Program</title>
 <para>
  To compile and run the program, use the following
  commands, where
  <replaceable>source-file</replaceable>
  is the name of the source file:
 </para>
<screen>
<userinput>cc</userinput> <replaceable>source-file</replaceable>
<userinput>./a.out</userinput>
</screen>
</example>]]>
</screen>

<para>
The paragraph now is wrapped and indented. However, it doesn't seem to
be wrapped <emphasis>quite</emphasis> correctly, because the
<literal>&lt;replaceable&gt;</literal> element actually would fit on the
previous line. This happens because no formatting options were specified
for <literal>&lt;replaceable&gt;</literal> in the configuration file. As
a result, it is treated as having the default element type of
<literal>block</literal>, using the default behavior that block elements
are written out beginning on a new line.
</para>

<para>
To fix this problem, we should configure
<literal>&lt;replaceable&gt;</literal> as an inline element. That will
cause it to be formatted inline with the other text (and thus
line-wrapped along with it). Modify the configuration file to include a
<literal>replaceable</literal> section: this:
</para>

<screen>
para
  format = block
  normalize = yes
  wrap-length = 60
  subindent = 1

replaceable
  format = inline

screen
  format = verbatim
</screen>

<para>
The resulting output after making this change is as follows:
</para>

<!-- ../xmlformat.rb -f examples/doc2.conf3 examples/doc2.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<example>
 <title>Compiling and Running a Program</title>
 <para>
  To compile and run the program, use the following
  commands, where <replaceable>source-file</replaceable> is
  the name of the source file:
 </para>
<screen>
<userinput>cc</userinput> <replaceable>source-file</replaceable>
<userinput>./a.out</userinput>
</screen>
</example>]]>
</screen>

<para>
We're getting close now. All we need to do is space out the
<literal>&lt;example&gt;</literal> child elements with a blank line in
between. Sub-element spacing is controlled by three formatting
properties:
</para>

<itemizedlist>

<listitem><para>
<literal>entry-break</literal> controls spacing after the opening tag of
an element (that is, the spacing upon entry into the element's content).
</para></listitem>

<listitem><para>
<literal>element-break</literal> controls the spacing between
sub-elements.
</para></listitem>

<listitem><para>
<literal>exit-break</literal> controls spacing before the closing tag of
an element (that is, the spacing upon exit from the element's content).
</para></listitem>

</itemizedlist>

<para>
The value for each of these formatting options should be an integer
indicating the number of newlines to write. A value of
<literal>1</literal> causes one newline, which acts simply to break to
the next line. To get a blank line, the break value needs to be
<literal>2</literal>. Modify the configuration file by adding a section
for <literal>&lt;example&gt;</literal> elements:
</para>

<screen>
example
  format = block
  entry-break = 2
  element-break = 2
  exit-break = 2
  subindent = 0

para
  format = block
  normalize = yes
  wrap-length = 60
  subindent = 1

replaceable
  format = inline

screen
  format = verbatim
</screen>

<para>
The resulting output is:
</para>

<!-- ../xmlformat.rb -f examples/doc2.conf4 examples/doc2.xml | xmlize -t screen -C -->

<screen>
<![CDATA[<example>

<title>Compiling and Running a Program</title>

<para>
 To compile and run the program, use the following commands,
 where <replaceable>source-file</replaceable> is the name of
 the source file:
</para>

<screen>
<userinput>cc</userinput> <replaceable>source-file</replaceable>
<userinput>./a.out</userinput>
</screen>

</example>]]>
</screen>

<para>
We're done!
</para>

<para>
You may be thinking, "Wow, that's a lot of messing around just to format
that tiny little document." That's true. However, the effort of setting
up configuration files tends to be "reusable," in the sense that you can
use the same file to format multiple documents that all should be
written using the same style. Also, if you have different projects
requiring different styles, it tends to be easiest to begin setting up
the configuration file for one project by beginning with a copy of the
file from another project.
</para>

</sect1>

<sect1 id="inherited-formatting">

<title>
Discovering "Inherited" Formatting Options
</title>

<para>
In the final formatting of <filename>doc2.xml</filename>, note that the
paragraph tags appear on separate lines preceding and following the
paragraph content. This occurs despite the fact that the configuration
file specifies no break values in the <literal>para</literal> section,
because if you omit formatting options for an element, it "inherits" the
default properties. In the case of the <literal>&lt;para&gt;</literal>
element, the relevant unspecified properties are the
<literal>entry-break</literal> and <literal>exit-break</literal> values.
For block elements, both have a value of <literal>1</literal> by default
(that is, one newline), which causes a line break after the opening tag
and before the closing tag.
</para>

<para>
If you want to see all the formatting options
<command>xmlformat</command> will use, run it with the
<option>--show-config</option> option. For example:
</para>

<screen>
% <userinput>xmlformat --show-config</userinput>
*DEFAULT
  format = block
  entry-break = 1
  element-break = 1
  exit-break = 1
  subindent = 1
  normalize = no
  wrap-length = 0

*DOCUMENT
  format = block
  entry-break = 0
  element-break = 1
  exit-break = 1
  subindent = 0
  normalize = no
  wrap-length = 0

example
  format = block
  entry-break = 2
  element-break = 2
  exit-break = 2
  subindent = 0
  normalize = no
  wrap-length = 0

para
  format = block
  entry-break = 1
  element-break = 1
  exit-break = 1
  subindent = 1
  normalize = yes
  wrap-length = 60

replaceable
  format = inline

screen
  format = verbatim
</screen>

<para>
No configuration file is specified on the command line, so
<command>xmlformat</command> reads the default configuration file,
<filename>xmlformat.conf</filename>. Then it displays the resulting
configuration options. You can see that the <literal>para</literal>
section has inherited break values from the <literal>*DEFAULT</literal>
section.
</para>

</sect1>

<sect1 id="unconfigured-elements">

<title>
Checking for Unconfigured Elements
</title>

<para>
Any elements appearing in the input document that are not named in the
configuration file are formatted using the values of the
<literal>*DEFAULT</literal> section. If the file contains no
<literal>*DEFAULT</literal> section, <command>xmlformat</command> uses
built-in default values.
</para>

<para>
If you want to see whether there are any elements in the document for
which you haven't specified any formatting options, run
<command>xmlformat</command> with the
<option>--show-unconfigured-elements</option> option. For example:
</para>

<screen>
% <userinput>xmlformat --show-unconfigured-elements doc2.xml</userinput>
The following document elements were assigned no formatting options:
title
</screen>

<para>
As it happens, the title already formats in the desired fashion, so
there's no necessity of adding anything more to the configuration file.
</para>

</sect1>

</article>