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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>3.
Using a Configuration File
</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"><link rel="start" href="index.html" title="
xmlformat Tutorial
"><link rel="up" href="index.html" title="
xmlformat Tutorial
"><link rel="prev" href="formatting-document.html" title="2.
Formatting a Document
"><link rel="next" href="inherited-formatting.html" title='4.
Discovering "Inherited" Formatting Options
'></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">3.
Using a Configuration File
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="formatting-document.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="inherited-formatting.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="using-config-file"></a>3.
Using a Configuration File
</h2></div></div></div><p>
In the preceding example, the desired output style for
<code class="filename">doc1.xml</code> was the same as what
<span><strong class="command">xmlformat</strong></span> produces by default. But what if the
default style is <span class="emphasis"><em>not</em></span> what you want? In that case,
you must tell <span><strong class="command">xmlformat</strong></span> how to handle your document.
This is at once both the weakness and strength of
<span><strong class="command">xmlformat</strong></span>. The weakness is that it is extra work to
instruct <span><strong class="command">xmlformat</strong></span> 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.
</p><p>
Suppose <code class="filename">doc2.xml</code> looks like this:
</p><pre class="screen">
<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>
</pre><p>
That's ugly, and you want it to rewrite it like this:
</p><pre class="screen">
<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>
</pre><p>
The key characteristics of this rewrite are as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Child elements of the <code class="literal"><example></code> element are
separated by blank lines, but not indented within it.
</p></li><li><p>
The text inside the <code class="literal"><para></code> element is
reformatted, adjusted to 60 characters per line and indented.
</p></li><li><p>
The contents of the <code class="literal"><screen></code> element are left
alone.
</p></li></ul></div><p>
Unfortunately, if you run <code class="filename">doc2.xml</code> through
<span><strong class="command">xmlformat</strong></span>, it comes out like this:
</p><pre class="screen">
<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>
</pre><p>
This output is unsuitable. Among the offenses committed by
<span><strong class="command">xmlformat</strong></span>, two are most notable:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The text of the <code class="literal"><para></code> element has been left
alone, not reformatted.
</p></li><li><p>
The <code class="literal"><screen></code> element content has been
reformatted, not left intact.
</p></li></ul></div><p>
In these respects, it appears that <span><strong class="command">xmlformat</strong></span> has done
exactly the <span class="emphasis"><em>opposite</em></span> of what was wanted!
Furthermore, had you used the <code class="option">-i</code> option to reformat the
file in place without using <code class="option">-b</code> to make a backup, at
this point you would have a file containing a
<code class="literal"><screen></code> element that you'd have to fix up by
hand to restore it to its original condition.
</p><p>
What a worthless, worthless program!
</p><p>
The rewriting of the <code class="literal"><screen></code> element points to
an important lesson: Before trusting <span><strong class="command">xmlformat</strong></span> 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
<code class="literal"><screen></code> or
<code class="literal"><programlisting></code> that should be copied
verbatim, without change.
</p><p>
Configuring <span><strong class="command">xmlformat</strong></span> amounts to writing a
configuration file that instructs it what to do. For
<code class="filename">doc2.xml</code>, that means telling
<span><strong class="command">xmlformat</strong></span> to leave the
<code class="literal"><screen></code> 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
<code class="literal"><example></code> element.
</p><p>
Let's begin by creating a very basic configuration file. What should we
call it? <span><strong class="command">xmlformat</strong></span> can read configuration settings
from a file named on the command line with a <code class="option">-f</code> or
<code class="option">--config-file</code> option. This means you can name the file
whatever you want. However, if you put the settings in a file named
<code class="filename">xmlformat.conf</code> in the current directory,
<span><strong class="command">xmlformat</strong></span> 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
<code class="filename">xmlformat.conf</code> that contains the following two
lines:
</p><pre class="screen">
screen
format = verbatim
</pre><p>
These lines specify that <code class="literal"><screen></code> elements
should be formatted as verbatim elements. That is,
<span><strong class="command">xmlformat</strong></span> 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 <span><strong class="command">xmlformat</strong></span> distinguish
the names of elements to be formatted from the instructions that
indicate <span class="emphasis"><em>how</em></span> to format them.
</p><p>
After creating <code class="filename">xmlformat.conf</code>, run
<span><strong class="command">xmlformat</strong></span> again to process
<code class="filename">doc2.xml</code>. It reads the newly created configuration
file and produces this result:
</p><pre class="screen">
<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>
</pre><p>
That's a little better: <span><strong class="command">xmlformat</strong></span> has not destroyed
the <code class="literal"><screen></code> element by reformatting it. But
problems remain: The paragraph content has not been reformatted, and
there are no blank lines between sub-elements.
</p><p>
Let's take care of the paragraph next. To set up its formatting, add a
section to <code class="filename">xmlformat.conf</code> for
<code class="literal"><para></code> elements:
</p><pre class="screen">
para
format = block
normalize = yes
wrap-length = 60
subindent = 1
screen
format = verbatim
</pre><p>
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.
</p><p>
The first two options in the <code class="literal">para</code> section specify
that the <code class="literal"><para></code> element is a block element, and
that text within it should be normalized. Turning on the
<code class="literal">normalize</code> option tells <span><strong class="command">xmlformat</strong></span>
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 <code class="literal">wrap-length</code>
option specifies the maximum number of characters per line, and
<code class="literal">subindent</code> specifies the indenting of text and
sub-elements, relative to the element's own tags. Note that when
<span><strong class="command">xmlformat</strong></span> 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 <code class="literal">wrap-length</code>
value is <code class="literal">60</code>, lines will contain at most 40 characters
following the indentation.)
</p><p>
After adding the <code class="literal">para</code> section to
<code class="filename">xmlformat.conf</code>, <span><strong class="command">xmlformat</strong></span>
produces this result:
</p><pre class="screen">
<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>
</pre><p>
The paragraph now is wrapped and indented. However, it doesn't seem to
be wrapped <span class="emphasis"><em>quite</em></span> correctly, because the
<code class="literal"><replaceable></code> element actually would fit on the
previous line. This happens because no formatting options were specified
for <code class="literal"><replaceable></code> in the configuration file. As
a result, it is treated as having the default element type of
<code class="literal">block</code>, using the default behavior that block elements
are written out beginning on a new line.
</p><p>
To fix this problem, we should configure
<code class="literal"><replaceable></code> 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
<code class="literal">replaceable</code> section: this:
</p><pre class="screen">
para
format = block
normalize = yes
wrap-length = 60
subindent = 1
replaceable
format = inline
screen
format = verbatim
</pre><p>
The resulting output after making this change is as follows:
</p><pre class="screen">
<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>
</pre><p>
We're getting close now. All we need to do is space out the
<code class="literal"><example></code> child elements with a blank line in
between. Sub-element spacing is controlled by three formatting
properties:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">entry-break</code> controls spacing after the opening tag of
an element (that is, the spacing upon entry into the element's content).
</p></li><li><p>
<code class="literal">element-break</code> controls the spacing between
sub-elements.
</p></li><li><p>
<code class="literal">exit-break</code> controls spacing before the closing tag of
an element (that is, the spacing upon exit from the element's content).
</p></li></ul></div><p>
The value for each of these formatting options should be an integer
indicating the number of newlines to write. A value of
<code class="literal">1</code> causes one newline, which acts simply to break to
the next line. To get a blank line, the break value needs to be
<code class="literal">2</code>. Modify the configuration file by adding a section
for <code class="literal"><example></code> elements:
</p><pre class="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
</pre><p>
The resulting output is:
</p><pre class="screen">
<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>
</pre><p>
We're done!
</p><p>
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.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="formatting-document.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="inherited-formatting.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
Formatting a Document
</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.
Discovering "Inherited" Formatting Options
</td></tr></table></div></body></html>
|
