← Back to branch summary

~ubuntu-branches/ubuntu/raring/wxwidgets2.8/raring

« back to all changes in this revision

Viewing changes to src/expat/doc/xmlwf.sgml

  • Committer: Package Import Robot
  • Author(s): Stéphane Graber
  • Date: 2012-01-07 13:59:25 UTC
  • mfrom: (1.1.9) (5.1.10 sid)
  • Revision ID: package-import@ubuntu.com-20120107135925-2601miy9ullcon9j
Tags: 2.8.12.1-6ubuntu1
https://launchpad.net/bugs/632984
* Resync from Debian, changes that were kept:
  - debian/rules: re-enable mediactrl. This allows libwx_gtk2u_media-2.8 to be
    built, as this is required by some applications (LP: #632984)
  - debian/control: Build-dep on libxt-dev for mediactrl.
  - Patches
    + fix-bashism-in-example
* Add conflict on python-wxgtk2.8 (<< 2.8.12.1-6ubuntu1~) to python-wxversion
  to guarantee upgrade ordering when moving from pycentral to dh_python2.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/expat/doc/xmlwf.sgml
1
 
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2
 
 
3
 
<!-- Process this file with docbook-to-man to generate an nroff manual
4
 
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
5
 
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
6
 
     less'.  A typical entry in a Makefile or Makefile.am is:
7
 
 
8
 
manpage.1: manpage.sgml
9
 
        docbook-to-man $< > $@
10
 
  -->
11
 
 
12
 
  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
13
 
  <!ENTITY dhfirstname "<firstname>Scott</firstname>">
14
 
  <!ENTITY dhsurname   "<surname>Bronson</surname>">
15
 
  <!-- Please adjust the date whenever revising the manpage. -->
16
 
  <!ENTITY dhdate      "<date>December  5, 2001</date>">
17
 
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
18
 
       allowed: see man(7), man(1). -->
19
 
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
20
 
  <!ENTITY dhemail     "<email>bronson@rinspin.com</email>">
21
 
  <!ENTITY dhusername  "Scott Bronson">
22
 
  <!ENTITY dhucpackage "<refentrytitle>XMLWF</refentrytitle>">
23
 
  <!ENTITY dhpackage   "xmlwf">
24
 
 
25
 
  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
26
 
  <!ENTITY gnu         "<acronym>GNU</acronym>">
27
 
]>
28
 
 
29
 
<refentry>
30
 
  <refentryinfo>
31
 
    <address>
32
 
      &dhemail;
33
 
    </address>
34
 
    <author>
35
 
      &dhfirstname;
36
 
      &dhsurname;
37
 
    </author>
38
 
    <copyright>
39
 
      <year>2001</year>
40
 
      <holder>&dhusername;</holder>
41
 
    </copyright>
42
 
    &dhdate;
43
 
  </refentryinfo>
44
 
  <refmeta>
45
 
    &dhucpackage;
46
 
 
47
 
    &dhsection;
48
 
  </refmeta>
49
 
  <refnamediv>
50
 
    <refname>&dhpackage;</refname>
51
 
 
52
 
    <refpurpose>Determines if an XML document is well-formed</refpurpose>
53
 
  </refnamediv>
54
 
  <refsynopsisdiv>
55
 
    <cmdsynopsis>
56
 
      <command>&dhpackage;</command>
57
 
          <arg><option>-s</option></arg>
58
 
          <arg><option>-n</option></arg>
59
 
          <arg><option>-p</option></arg>
60
 
          <arg><option>-x</option></arg>
61
 
 
62
 
          <arg><option>-e <replaceable>encoding</replaceable></option></arg>
63
 
          <arg><option>-w</option></arg>
64
 
 
65
 
          <arg><option>-d <replaceable>output-dir</replaceable></option></arg>
66
 
          <arg><option>-c</option></arg>
67
 
          <arg><option>-m</option></arg>
68
 
 
69
 
          <arg><option>-r</option></arg>
70
 
          <arg><option>-t</option></arg>
71
 
 
72
 
          <arg><option>-v</option></arg>
73
 
 
74
 
          <arg>file ...</arg>
75
 
    </cmdsynopsis>
76
 
  </refsynopsisdiv>
77
 
 
78
 
  <refsect1>
79
 
    <title>DESCRIPTION</title>
80
 
 
81
 
    <para>
82
 
        <command>&dhpackage;</command> uses the Expat library to
83
 
        determine if an XML document is well-formed.  It is
84
 
        non-validating.
85
 
        </para>
86
 
 
87
 
        <para>
88
 
        If you do not specify any files on the command-line, and you
89
 
        have a recent version of <command>&dhpackage;</command>, the
90
 
        input file will be read from standard input.
91
 
        </para>
92
 
 
93
 
  </refsect1>
94
 
 
95
 
  <refsect1>
96
 
    <title>WELL-FORMED DOCUMENTS</title>
97
 
 
98
 
        <para>
99
 
          A well-formed document must adhere to the
100
 
          following rules:
101
 
        </para>
102
 
 
103
 
        <itemizedlist>
104
 
      <listitem><para>
105
 
            The file begins with an XML declaration.  For instance,
106
 
                <literal>&lt;?xml version="1.0" standalone="yes"?&gt;</literal>.
107
 
                <emphasis>NOTE:</emphasis>
108
 
                <command>&dhpackage;</command> does not currently
109
 
                check for a valid XML declaration.
110
 
      </para></listitem>
111
 
      <listitem><para>
112
 
                Every start tag is either empty (&lt;tag/&gt;)
113
 
                or has a corresponding end tag.
114
 
      </para></listitem>
115
 
      <listitem><para>
116
 
            There is exactly one root element.  This element must contain
117
 
                all other elements in the document.  Only comments, white
118
 
                space, and processing instructions may come after the close
119
 
                of the root element.
120
 
      </para></listitem>
121
 
      <listitem><para>
122
 
                All elements nest properly.
123
 
      </para></listitem>
124
 
      <listitem><para>
125
 
                All attribute values are enclosed in quotes (either single
126
 
                or double).
127
 
      </para></listitem>
128
 
    </itemizedlist>
129
 
 
130
 
        <para>
131
 
          If the document has a DTD, and it strictly complies with that
132
 
          DTD, then the document is also considered <emphasis>valid</emphasis>.
133
 
          <command>&dhpackage;</command> is a non-validating parser --
134
 
          it does not check the DTD.  However, it does support
135
 
          external entities (see the <option>-x</option> option).
136
 
        </para>
137
 
  </refsect1>
138
 
 
139
 
  <refsect1>
140
 
    <title>OPTIONS</title>
141
 
 
142
 
<para>
143
 
When an option includes an argument, you may specify the argument either
144
 
separately ("<option>-d</option> output") or concatenated with the
145
 
option ("<option>-d</option>output").  <command>&dhpackage;</command>
146
 
supports both.
147
 
</para>
148
 
 
149
 
    <variablelist>
150
 
 
151
 
      <varlistentry>
152
 
        <term><option>-c</option></term>
153
 
        <listitem>
154
 
                <para>
155
 
  If the input file is well-formed and <command>&dhpackage;</command>
156
 
  doesn't encounter any errors, the input file is simply copied to
157
 
  the output directory unchanged.
158
 
  This implies no namespaces (turns off <option>-n</option>) and
159
 
  requires <option>-d</option> to specify an output file.
160
 
                </para>
161
 
        </listitem>
162
 
      </varlistentry>
163
 
 
164
 
      <varlistentry>
165
 
        <term><option>-d output-dir</option></term>
166
 
        <listitem>
167
 
                <para>
168
 
  Specifies a directory to contain transformed
169
 
  representations of the input files.
170
 
  By default, <option>-d</option> outputs a canonical representation
171
 
  (described below).
172
 
  You can select different output formats using <option>-c</option>
173
 
  and <option>-m</option>.
174
 
          </para>
175
 
          <para>
176
 
  The output filenames will
177
 
  be exactly the same as the input filenames or "STDIN" if the input is
178
 
  coming from standard input.  Therefore, you must be careful that the
179
 
  output file does not go into the same directory as the input
180
 
  file.  Otherwise, <command>&dhpackage;</command> will delete the
181
 
  input file before it generates the output file (just like running
182
 
  <literal>cat &lt; file &gt; file</literal> in most shells).
183
 
          </para>
184
 
          <para> 
185
 
  Two structurally equivalent XML documents have a byte-for-byte
186
 
  identical canonical XML representation.
187
 
  Note that ignorable white space is considered significant and
188
 
  is treated equivalently to data.
189
 
  More on canonical XML can be found at
190
 
  http://www.jclark.com/xml/canonxml.html .
191
 
          </para>
192
 
        </listitem>
193
 
      </varlistentry>
194
 
 
195
 
      <varlistentry>
196
 
        <term><option>-e encoding</option></term>
197
 
        <listitem>
198
 
                <para>
199
 
   Specifies the character encoding for the document, overriding
200
 
   any document encoding declaration.  <command>&dhpackage;</command>
201
 
   supports four built-in encodings:
202
 
        <literal>US-ASCII</literal>,
203
 
        <literal>UTF-8</literal>,
204
 
        <literal>UTF-16</literal>, and
205
 
        <literal>ISO-8859-1</literal>.
206
 
   Also see the <option>-w</option> option.
207
 
           </para>
208
 
        </listitem>
209
 
      </varlistentry>
210
 
 
211
 
      <varlistentry>
212
 
        <term><option>-m</option></term>
213
 
        <listitem>
214
 
                <para>
215
 
  Outputs some strange sort of XML file that completely
216
 
  describes the the input file, including character postitions.
217
 
  Requires <option>-d</option> to specify an output file.
218
 
           </para>
219
 
        </listitem>
220
 
      </varlistentry>
221
 
 
222
 
      <varlistentry>
223
 
        <term><option>-n</option></term>
224
 
        <listitem>
225
 
                <para>
226
 
  Turns on namespace processing.  (describe namespaces)
227
 
  <option>-c</option> disables namespaces.
228
 
           </para>
229
 
        </listitem>
230
 
      </varlistentry>
231
 
 
232
 
      <varlistentry>
233
 
        <term><option>-p</option></term>
234
 
        <listitem>
235
 
                <para>
236
 
    Tells xmlwf to process external DTDs and parameter
237
 
    entities.
238
 
         </para>
239
 
         <para>
240
 
   Normally <command>&dhpackage;</command> never parses parameter
241
 
   entities.  <option>-p</option> tells it to always parse them.
242
 
   <option>-p</option> implies <option>-x</option>.
243
 
           </para>
244
 
        </listitem>
245
 
      </varlistentry>
246
 
 
247
 
      <varlistentry>
248
 
        <term><option>-r</option></term>
249
 
        <listitem>
250
 
                <para>
251
 
   Normally <command>&dhpackage;</command> memory-maps the XML file
252
 
   before parsing; this can result in faster parsing on many
253
 
   platforms.
254
 
   <option>-r</option> turns off memory-mapping and uses normal file
255
 
   IO calls instead.
256
 
   Of course, memory-mapping is automatically turned off
257
 
   when reading from standard input.
258
 
           </para>
259
 
                <para>
260
 
   Use of memory-mapping can cause some platforms to report
261
 
   substantially higher memory usage for
262
 
   <command>&dhpackage;</command>, but this appears to be a matter of
263
 
   the operating system reporting memory in a strange way; there is
264
 
   not a leak in <command>&dhpackage;</command>.
265
 
           </para>
266
 
        </listitem>
267
 
      </varlistentry>
268
 
 
269
 
      <varlistentry>
270
 
        <term><option>-s</option></term>
271
 
        <listitem>
272
 
                <para>
273
 
  Prints an error if the document is not standalone. 
274
 
  A document is standalone if it has no external subset and no
275
 
  references to parameter entities.
276
 
           </para>
277
 
        </listitem>
278
 
      </varlistentry>
279
 
 
280
 
      <varlistentry>
281
 
        <term><option>-t</option></term>
282
 
        <listitem>
283
 
                <para>
284
 
  Turns on timings.  This tells Expat to parse the entire file,
285
 
  but not perform any processing.
286
 
  This gives a fairly accurate idea of the raw speed of Expat itself
287
 
  without client overhead.
288
 
  <option>-t</option> turns off most of the output options
289
 
  (<option>-d</option>, <option>-m</option>, <option>-c</option>,
290
 
  ...).
291
 
           </para>
292
 
        </listitem>
293
 
      </varlistentry>
294
 
 
295
 
      <varlistentry>
296
 
        <term><option>-v</option></term>
297
 
        <listitem>
298
 
                <para>
299
 
  Prints the version of the Expat library being used, including some
300
 
  information on the compile-time configuration of the library, and
301
 
  then exits.
302
 
           </para>
303
 
        </listitem>
304
 
      </varlistentry>
305
 
 
306
 
      <varlistentry>
307
 
        <term><option>-w</option></term>
308
 
        <listitem>
309
 
                <para>
310
 
  Enables support for Windows code pages.
311
 
  Normally, <command>&dhpackage;</command> will throw an error if it
312
 
  runs across an encoding that it is not equipped to handle itself.  With
313
 
  <option>-w</option>, &dhpackage; will try to use a Windows code
314
 
  page.  See also <option>-e</option>.
315
 
           </para>
316
 
        </listitem>
317
 
      </varlistentry>
318
 
 
319
 
      <varlistentry>
320
 
        <term><option>-x</option></term>
321
 
        <listitem>
322
 
                <para>
323
 
  Turns on parsing external entities.
324
 
  </para>
325
 
<para>
326
 
  Non-validating parsers are not required to resolve external
327
 
  entities, or even expand entities at all.
328
 
  Expat always expands internal entities (?),
329
 
  but external entity parsing must be enabled explicitly.
330
 
  </para>
331
 
  <para>
332
 
  External entities are simply entities that obtain their
333
 
  data from outside the XML file currently being parsed.
334
 
  </para>
335
 
  <para>
336
 
  This is an example of an internal entity:
337
 
<literallayout>
338
 
&lt;!ENTITY vers '1.0.2'&gt;
339
 
</literallayout>
340
 
  </para>
341
 
  <para>
342
 
  And here are some examples of external entities:
343
 
 
344
 
<literallayout>
345
 
&lt;!ENTITY header SYSTEM "header-&amp;vers;.xml"&gt;  (parsed)
346
 
&lt;!ENTITY logo SYSTEM "logo.png" PNG&gt;         (unparsed)
347
 
</literallayout>
348
 
 
349
 
           </para>
350
 
        </listitem>
351
 
      </varlistentry>
352
 
 
353
 
      <varlistentry>
354
 
        <term><option>--</option></term>
355
 
        <listitem>
356
 
                <para>
357
 
    (Two hyphens.)
358
 
    Terminates the list of options.  This is only needed if a filename
359
 
    starts with a hyphen.  For example:
360
 
           </para>
361
 
<literallayout>
362
 
&dhpackage; -- -myfile.xml
363
 
</literallayout>
364
 
                <para>
365
 
    will run <command>&dhpackage;</command> on the file
366
 
    <filename>-myfile.xml</filename>.
367
 
           </para>
368
 
        </listitem>
369
 
      </varlistentry>
370
 
    </variablelist>
371
 
 
372
 
        <para>
373
 
    Older versions of <command>&dhpackage;</command> do not support
374
 
    reading from standard input.
375
 
        </para>
376
 
  </refsect1>
377
 
 
378
 
  <refsect1>
379
 
  <title>OUTPUT</title>
380
 
    <para>
381
 
        If an input file is not well-formed,
382
 
        <command>&dhpackage;</command> prints a single line describing
383
 
        the problem to standard output.  If a file is well formed,
384
 
        <command>&dhpackage;</command> outputs nothing.
385
 
        Note that the result code is <emphasis>not</emphasis> set.
386
 
        </para>
387
 
  </refsect1>
388
 
  
389
 
  <refsect1>
390
 
    <title>BUGS</title>
391
 
        <para>
392
 
        According to the W3C standard, an XML file without a
393
 
        declaration at the beginning is not considered well-formed.
394
 
        However, <command>&dhpackage;</command> allows this to pass.
395
 
        </para>
396
 
        <para>
397
 
        <command>&dhpackage;</command> returns a 0 - noerr result,
398
 
        even if the file is not well-formed.  There is no good way for
399
 
        a program to use <command>&dhpackage;</command> to quickly
400
 
        check a file -- it must parse <command>&dhpackage;</command>'s
401
 
        standard output.
402
 
        </para>
403
 
        <para>
404
 
        The errors should go to standard error, not standard output.
405
 
        </para>
406
 
        <para>
407
 
        There should be a way to get <option>-d</option> to send its
408
 
        output to standard output rather than forcing the user to send
409
 
        it to a file.
410
 
        </para>
411
 
        <para>
412
 
        I have no idea why anyone would want to use the
413
 
        <option>-d</option>, <option>-c</option>, and
414
 
        <option>-m</option> options.  If someone could explain it to
415
 
        me, I'd like to add this information to this manpage.
416
 
        </para>
417
 
  </refsect1>
418
 
 
419
 
  <refsect1>
420
 
    <title>ALTERNATIVES</title>
421
 
        <para>
422
 
          Here are some XML validators on the web:
423
 
 
424
 
<literallayout>
425
 
http://www.hcrc.ed.ac.uk/~richard/xml-check.html
426
 
http://www.stg.brown.edu/service/xmlvalid/
427
 
http://www.scripting.com/frontier5/xml/code/xmlValidator.html
428
 
http://www.xml.com/pub/a/tools/ruwf/check.html
429
 
</literallayout>
430
 
 
431
 
                 </para>
432
 
  </refsect1>
433
 
 
434
 
  <refsect1>
435
 
    <title>SEE ALSO</title>
436
 
        <para>
437
 
 
438
 
<literallayout>
439
 
The Expat home page:        http://www.libexpat.org/
440
 
The W3 XML specification:   http://www.w3.org/TR/REC-xml
441
 
</literallayout>
442
 
 
443
 
        </para>
444
 
  </refsect1>
445
 
 
446
 
  <refsect1>
447
 
    <title>AUTHOR</title>
448
 
    <para>
449
 
          This manual page was written by &dhusername; &dhemail; for
450
 
      the &debian; system (but may be used by others).  Permission is
451
 
      granted to copy, distribute and/or modify this document under
452
 
      the terms of the <acronym>GNU</acronym> Free Documentation
453
 
      License, Version 1.1.
454
 
        </para>
455
 
  </refsect1>
456
 
</refentry>
457
 
 
458
 
<!-- Keep this comment at the end of the file
459
 
Local variables:
460
 
mode: sgml
461
 
sgml-omittag:t
462
 
sgml-shorttag:t
463
 
sgml-minimize-attributes:nil
464
 
sgml-always-quote-attributes:t
465
 
sgml-indent-step:2
466
 
sgml-indent-data:t
467
 
sgml-parent-document:nil
468
 
sgml-default-dtd-file:nil
469
 
sgml-exposed-tags:nil
470
 
sgml-local-catalogs:nil
471
 
sgml-local-ecat-files:nil
472
 
End:
473
 
-->