1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>2.
How to Use xmlformat
</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"><link rel="start" href="index.html" title="
The xmlformat XML Document Formatter
"><link rel="up" href="index.html" title="
The xmlformat XML Document Formatter
"><link rel="prev" href="introduction.html" title="1.
Introduction
"><link rel="next" href="doc-processing-model.html" title="3.
The Document Processing Model
"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.
How to Use <span><strong class="command">xmlformat</strong></span>
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="doc-processing-model.html">Next</a></td></tr></table><hr></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">
<table> <row> <cell> A </cell> <cell> B </cell> </row>
<row> <cell> C </cell> <cell> D </cell> </row> </table>
</pre><p>
<span><strong class="command">xmlformat</strong></span> will produce this result by default:
</p><pre class="screen">
<table>
<row>
<cell> A </cell>
<cell> B </cell>
</row>
<row>
<cell> C </cell>
<cell> D </cell>
</row>
</table>
</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.html" title="4.
Using Configuration Files
">Section 4, “
Using Configuration Files
”</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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="doc-processing-model.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.
Introduction
</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.
The Document Processing Model
</td></tr></table></div></body></html>
|
