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