VirtualBox

source: vbox/trunk/src/libs/libxml2-2.9.14/doc/xmlcatalog_man.xml@ 103951

Last change on this file since 103951 was 95312, checked in by vboxsync, 3 years ago

libs/{curl,libxml2}: OSE export fixes, bugref:8515

File size: 13.9 KB
Line 
1<?xml version="1.0"?>
2<?xml-stylesheet type="text/xsl"
3 href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
4<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
5 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
6
7 <!ENTITY xmlcatalog "<command>xmlcatalog</command>">
8]>
9
10<refentry>
11
12<refentryinfo>
13 <title>xmlcatalog Manual</title>
14 <productname>libxml2</productname>
15 <copyright>
16 <year>2001</year>
17 <year>2004</year>
18 </copyright>
19 <author>
20 <firstname>John</firstname>
21 <surname>Fleck</surname>
22 <affiliation>
23 <address>
24 <email>[email protected]</email>
25 </address>
26 </affiliation>
27 </author>
28 <!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this -->
29 <!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> -->
30 <!-- <edition>0.3</edition> -->
31</refentryinfo>
32
33<refmeta>
34 <refentrytitle>xmlcatalog</refentrytitle>
35 <manvolnum>1</manvolnum>
36</refmeta>
37
38<refnamediv>
39 <refname>xmlcatalog</refname>
40 <refpurpose>
41 Command line tool to parse and manipulate <acronym>XML</acronym>
42 or <acronym>SGML</acronym> catalog files.
43 </refpurpose>
44</refnamediv>
45
46<refsynopsisdiv>
47 <cmdsynopsis>
48 <command>xmlcatalog</command>
49 <group choice="opt">
50 <arg choice="plain"><option>--sgml</option></arg>
51 <arg choice="plain"><option>--shell</option></arg>
52 <arg choice="plain"><option>--create</option></arg>
53 <arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg>
54 <arg choice="plain">
55 <group choice="opt">
56 <arg choice="plain">
57 <option>--add
58 <replaceable>TYPE</replaceable>
59 <replaceable>ORIG</replaceable>
60 <replaceable>REPLACE</replaceable>
61 </option>
62 </arg>
63 <arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg>
64 </group>
65 </arg>
66 <arg choice="plain"><option>--noout</option></arg>
67 <arg choice="plain"><option>--no-super-update</option></arg>
68 <arg choice="plain">
69 <group choice="opt">
70 <arg choice="plain"><option>-v</option></arg>
71 <arg choice="plain"><option>--verbose</option></arg>
72 </group>
73 </arg>
74 </group>
75 <arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg>
76 <arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg>
77 </cmdsynopsis>
78</refsynopsisdiv>
79
80<refsect1 id="description">
81 <title>DESCRIPTION</title>
82 <para>
83 &xmlcatalog; is a command line application allowing users to monitor and
84 manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It
85 is included in <citerefentry>
86 <refentrytitle>libxml</refentrytitle>
87 <manvolnum>3</manvolnum>
88 </citerefentry>.
89 </para>
90 <para>
91 Its functions can be invoked from a single command from the command line,
92 or it can perform multiple functions in interactive mode. It can operate
93 on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
94 </para>
95</refsect1>
96
97<refsect1 id="options">
98 <title>OPTIONS</title>
99 <para>
100 &xmlcatalog; accepts the following options (in alphabetical order):
101 </para>
102
103 <variablelist>
104
105 <varlistentry>
106 <term>
107 <option>--add
108 <replaceable>TYPE</replaceable>
109 <replaceable>ORIG</replaceable>
110 <replaceable>REPLACE</replaceable>
111 </option>
112 </term>
113 <listitem>
114 <para>
115 Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable>
116 indicates the type of entry. Possible types are: <simplelist type="inline">
117 <member><parameter>public</parameter></member>
118 <member><parameter>system</parameter></member>
119 <member><parameter>uri</parameter></member>
120 <member><parameter>rewriteSystem</parameter></member>
121 <member><parameter>rewriteURI</parameter></member>
122 <member><parameter>delegatePublic</parameter></member>
123 <member><parameter>delegateSystem</parameter></member>
124 <member><parameter>delegateURI</parameter></member>
125 <member><parameter>nextCatalog</parameter></member>
126 </simplelist>. <replaceable>ORIG</replaceable> is the original
127 reference to be replaced, and <replaceable>REPLACE</replaceable>
128 is the <acronym>URI</acronym> of the replacement entity to be
129 used. The <option>--add</option> option will not overwrite
130 <filename>CATALOGFILE</filename>, outputting
131 to <filename class="devicefile">stdout</filename>, unless
132 <option>--noout</option> is used. The <option>--add</option> will
133 always take three parameters even if some of the <acronym>XML</acronym>
134 catalog constructs will have only a single argument.
135 </para>
136 <!--
137 FIXME - Is my list of possible types correct? Are SGML types the same?
138 -->
139 </listitem>
140 </varlistentry>
141
142 <varlistentry>
143 <term><option>--add <replaceable>FILENAME</replaceable></option></term>
144 <listitem>
145 <para>
146 If the <option>--add</option> option is used following
147 the <option>--sgml</option> option, only a single argument,
148 a <replaceable>FILENAME</replaceable>, is used. This is used to add
149 the name of a catalog file to an <acronym>SGML</acronym> supercatalog,
150 a file that contains references to other included <acronym>SGML</acronym>
151 catalog files.
152 </para>
153 </listitem>
154 </varlistentry>
155
156 <varlistentry>
157 <term><option>--create</option></term>
158 <listitem>
159 <para>
160 Create a new <acronym>XML</acronym> catalog. Outputs
161 to <filename class="devicefile">stdout</filename>,
162 ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is
163 used, in which case it creates a new catalog
164 file <replaceable>filename</replaceable>.
165 </para>
166 </listitem>
167 </varlistentry>
168
169 <varlistentry>
170 <term><option>--del <replaceable>VALUE(S)</replaceable></option></term>
171 <listitem>
172 <para>
173 Remove entries from <replaceable>CATALOGFILE</replaceable>
174 matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option>
175 option will not overwrite <replaceable>CATALOGFILE</replaceable>,
176 outputting to <filename class="devicefile">stdout</filename>,
177 unless <option>--noout</option> is used.
178 </para>
179 </listitem>
180 </varlistentry>
181
182 <varlistentry>
183 <term><option>--noout</option></term>
184 <listitem>
185 <para>
186 Save output to the named file rather than outputting
187 to <filename class="devicefile">stdout</filename>.
188 </para>
189 </listitem>
190 </varlistentry>
191
192 <varlistentry>
193 <term><option>--no-super-update</option></term>
194 <listitem>
195 <para>
196 Do not update the <acronym>SGML</acronym> super catalog.
197 </para>
198 </listitem>
199 </varlistentry>
200
201 <varlistentry>
202 <term><option>--shell</option></term>
203 <listitem>
204 <para>
205 Run a shell allowing interactive queries on catalog
206 file <replaceable>CATALOGFILE</replaceable>. For the set of available
207 commands see <xref linkend="shell"/>.
208 </para>
209 </listitem>
210 </varlistentry>
211
212 <varlistentry>
213 <term><option>--sgml</option></term>
214 <listitem>
215 <para>
216 Uses <acronym>SGML</acronym> super catalogs for <option>--add</option>
217 and <option>--del</option> options.
218 </para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term><option>-v</option></term>
224 <term><option>--verbose</option></term>
225 <listitem>
226 <para>Output debugging information.</para>
227 </listitem>
228 </varlistentry>
229
230 </variablelist>
231
232 <para>
233 Invoking &xmlcatalog; non-interactively without a designated action
234 (imposed with options like <option>--add</option>) will result in a lookup
235 of the catalog entry for <replaceable>ENTITIES</replaceable> in the
236 catalog denoted with <replaceable>CATALOGFILE</replaceable>. The
237 corresponding entries will be output to the command line. This mode of
238 operation, together with <option>--shell</option> mode and non-modifying
239 (i.e. without <option>--noout</option>) direct actions, allows for
240 a special shortcut of the void <replaceable>CATALOGFILE</replaceable>
241 specification (possibly expressed as &quot;&quot; in the shell
242 environment) appointing the default system catalog. That simplifies the
243 handling when its exact location is irrelevant but the respective built-in
244 still needs to be consulted.
245 </para>
246</refsect1>
247
248<refsect1 id="shell">
249 <title>SHELL COMMANDS</title>
250 <para>
251 Invoking &xmlcatalog; with
252 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
253 a command line shell allowing interactive access to the catalog file
254 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
255 provides a command line prompt after which the following commands (described in
256 alphabetical order) can be entered.
257 </para>
258
259 <variablelist>
260
261 <varlistentry>
262 <term>
263 <option>add
264 <replaceable>TYPE</replaceable>
265 <replaceable>ORIG</replaceable>
266 <replaceable>REPLACE</replaceable>
267 </option>
268 </term>
269 <listitem>
270 <para>
271 Add an entry to the catalog file. <replaceable>TYPE</replaceable>
272 indicates the type of entry. Possible types are: <simplelist type="inline">
273 <member><parameter>public</parameter></member>
274 <member><parameter>system</parameter></member>
275 <member><parameter>uri</parameter></member>
276 <member><parameter>rewriteSystem</parameter></member>
277 <member><parameter>rewriteURI</parameter></member>
278 <member><parameter>delegatePublic</parameter></member>
279 <member><parameter>delegateSystem</parameter></member>
280 <member><parameter>delegateURI</parameter></member>
281 <member><parameter>nextCatalog</parameter></member>
282 </simplelist>. <replaceable>ORIG</replaceable> is the original
283 reference to be replaced, and <replaceable>REPLACE</replaceable>
284 is the <acronym>URI</acronym> of the replacement entity to be
285 used. The <option>--add</option> option will not overwrite
286 <filename>CATALOGFILE</filename>, outputting
287 to <filename class="devicefile">stdout</filename>, unless
288 <option>--noout</option> is used. The <option>--add</option> will
289 always take three parameters even if some of the <acronym>XML</acronym>
290 catalog constructs will have only a single argument.
291 </para>
292 </listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><option>debug</option></term>
297 <listitem>
298 <para>
299 Print debugging statements showing the steps &xmlcatalog; is executing.
300 </para>
301 </listitem>
302 </varlistentry>
303
304 <varlistentry>
305 <term><option>del <replaceable>VALUE(S)</replaceable></option></term>
306 <listitem>
307 <para>
308 Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
309 </para>
310 </listitem>
311 </varlistentry>
312
313 <varlistentry>
314 <term><option>dump</option></term>
315 <listitem>
316 <para>Print the current catalog.</para>
317 </listitem>
318 </varlistentry>
319
320 <varlistentry>
321 <term><option>exit</option></term>
322 <listitem>
323 <para>Quit the shell.</para>
324 </listitem>
325 </varlistentry>
326
327 <varlistentry>
328 <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
329 <listitem>
330 <para>
331 Execute a Formal Public Identifier lookup of the catalog entry
332 for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
333 output to the command line.
334 </para>
335 </listitem>
336 </varlistentry>
337
338 <varlistentry>
339 <term><option>quiet</option></term>
340 <listitem>
341 <para>Stop printing debugging statements.</para>
342 </listitem>
343 </varlistentry>
344
345 <varlistentry>
346 <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
347 <listitem>
348 <para>
349 Execute a Formal Public Identifier lookup of the catalog entry
350 for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
351 output to the command line.
352 </para>
353 </listitem>
354 </varlistentry>
355
356 </variablelist>
357</refsect1>
358
359<refsect1 id="environment">
360 <title>ENVIRONMENT</title>
361 <variablelist>
362
363 <varlistentry>
364 <term><envar>XML_CATALOG_FILES</envar></term>
365 <listitem>
366 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
367 queries to the user's own set of catalogs. This can be done by setting
368 the <envar>XML_CATALOG_FILES</envar> environment variable to a space-separated
369 list of catalogs. Use percent-encoding to escape spaces or other characters.
370 An empty variable should deactivate loading the default <filename>/etc/xml/catalog</filename> catalog.
371 </para>
372 </listitem>
373 </varlistentry>
374
375 </variablelist>
376</refsect1>
377
378<refsect1 id="diagnostics">
379 <title>DIAGNOSTICS</title>
380 <para>
381 &xmlcatalog; return codes provide information that can be used when
382 calling it from scripts.
383 </para>
384 <variablelist>
385
386 <varlistentry>
387 <term><errorcode>0</errorcode></term>
388 <listitem>
389 <para>No error</para>
390 </listitem>
391 </varlistentry>
392
393 <varlistentry>
394 <term><errorcode>1</errorcode></term>
395 <listitem>
396 <para>Failed to remove an entry from the catalog</para>
397 </listitem>
398 </varlistentry>
399
400 <varlistentry>
401 <term><errorcode>2</errorcode></term>
402 <listitem>
403 <para>Failed to save to the catalog, check file permissions</para>
404 </listitem>
405 </varlistentry>
406
407 <varlistentry>
408 <term><errorcode>3</errorcode></term>
409 <listitem>
410 <para>Failed to add an entry to the catalog</para>
411 </listitem>
412 </varlistentry>
413
414 <varlistentry>
415 <term><errorcode>4</errorcode></term>
416 <listitem>
417 <para>Failed to look up an entry in the catalog</para>
418 </listitem>
419 </varlistentry>
420
421 </variablelist>
422</refsect1>
423
424<refsect1 id="seealso">
425 <title>SEE ALSO</title>
426 <para><citerefentry>
427 <refentrytitle>libxml</refentrytitle>
428 <manvolnum>3</manvolnum>
429 </citerefentry>
430 </para>
431 <para>
432 More information can be found at
433 <itemizedlist>
434 <listitem>
435 <para><citerefentry>
436 <refentrytitle>libxml</refentrytitle>
437 <manvolnum>3</manvolnum>
438 </citerefentry> web page <ulink url="https://gitlab.gnome.org/GNOME/libxml2"/>
439 </para>
440 </listitem>
441 <listitem>
442 <para><citerefentry>
443 <refentrytitle>libxml</refentrytitle>
444 <manvolnum>3</manvolnum>
445 </citerefentry> catalog support web page
446 at <ulink url="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support"/>
447 </para>
448 </listitem>
449 <listitem>
450 <para>James Clark's <acronym>SGML</acronym> catalog
451 page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
452 </para>
453 </listitem>
454 <listitem>
455 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
456 <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
457 </para>
458 </listitem>
459 </itemizedlist>
460 </para>
461</refsect1>
462
463</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette