Annotation of embedaddon/libxml2/doc/xmlcatalog_man.xml, revision 1.1.1.1
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>
121: <member><parameter>rewriteSystem</parameter></member>
122: <member><parameter>rewriteURI</parameter></member>
123: <member><parameter>delegatePublic</parameter></member>
124: <member><parameter>delegateSystem</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: </refsect1>
232:
233: <refsect1 id="shell">
234: <title>SHELL COMMANDS</title>
235: <para>
236: Invoking &xmlcatalog; with
237: the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
238: a command line shell allowing interactive access to the catalog file
239: identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
240: provides a command line prompt after which the following commands (described in
241: alphabetical order) can be entered.
242: </para>
243:
244: <variablelist>
245:
246: <varlistentry>
247: <term>
248: <option>add
249: <replaceable>TYPE</replaceable>
250: <replaceable>ORIG</replaceable>
251: <replaceable>REPLACE</replaceable>
252: </option>
253: </term>
254: <listitem>
255: <para>
256: Add an entry to the catalog file. <replaceable>TYPE</replaceable>
257: indicates the type of entry. Possible types are: <simplelist type="inline">
258: <member><parameter>public</parameter></member>
259: <member><parameter>system</parameter></member>
260: <member><parameter>rewriteSystem</parameter></member>
261: <member><parameter>rewriteURI</parameter></member>
262: <member><parameter>delegatePublic</parameter></member>
263: <member><parameter>delegateSystem</parameter></member>
264: <member><parameter>nextCatalog</parameter></member>
265: </simplelist>. <replaceable>ORIG</replaceable> is the original
266: reference to be replaced, and <replaceable>REPLACE</replaceable>
267: is the <acronym>URI</acronym> of the replacement entity to be
268: used. The <option>--add</option> option will not overwrite
269: <filename>CATALOGFILE</filename>, outputting
270: to <filename class="devicefile">stdout</filename>, unless
271: <option>--noout</option> is used. The <option>--add</option> will
272: always take three parameters even if some of the <acronym>XML</acronym>
273: catalog constructs will have only a single argument.
274: </para>
275: </listitem>
276: </varlistentry>
277:
278: <varlistentry>
279: <term><option>debug</option></term>
280: <listitem>
281: <para>
282: Print debugging statements showing the steps &xmlcatalog; is executing.
283: </para>
284: </listitem>
285: </varlistentry>
286:
287: <varlistentry>
288: <term><option>del <replaceable>VALUE(S)</replaceable></option></term>
289: <listitem>
290: <para>
291: Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
292: </para>
293: </listitem>
294: </varlistentry>
295:
296: <varlistentry>
297: <term><option>dump</option></term>
298: <listitem>
299: <para>Print the current catalog.</para>
300: </listitem>
301: </varlistentry>
302:
303: <varlistentry>
304: <term><option>exit</option></term>
305: <listitem>
306: <para>Quit the shell.</para>
307: </listitem>
308: </varlistentry>
309:
310: <varlistentry>
311: <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
312: <listitem>
313: <para>
314: Execute a Formal Public Identifier look-up of the catalog entry
315: for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
316: output to the command line.
317: </para>
318: </listitem>
319: </varlistentry>
320:
321: <varlistentry>
322: <term><option>quiet</option></term>
323: <listitem>
324: <para>Stop printing debugging statements.</para>
325: </listitem>
326: </varlistentry>
327:
328: <varlistentry>
329: <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
330: <listitem>
331: <para>
332: Execute a Formal Public Identifier look-up of the catalog entry
333: for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
334: output to the command line.
335: </para>
336: </listitem>
337: </varlistentry>
338:
339: </variablelist>
340: </refsect1>
341:
342: <refsect1 id="environment">
343: <title>ENVIRONMENT</title>
344: <variablelist>
345:
346: <varlistentry>
347: <term><envar>XML_CATALOG_FILES</envar></term>
348: <listitem>
349: <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
350: queries to the user's own set of catalogs. This can be done by setting
351: the <envar>XML_CATALOG_FILES</envar> environment variable to a list
352: of catalogs. An empty one should deactivate loading the
353: default <filename>/etc/xml/catalog</filename> catalog.
354: </para>
355: </listitem>
356: </varlistentry>
357:
358: </variablelist>
359: </refsect1>
360:
361: <refsect1 id="diagnostics">
362: <title>DIAGNOSTICS</title>
363: <para>
364: &xmlcatalog; return codes provide information that can be used when
365: calling it from scripts.
366: </para>
367: <variablelist>
368:
369: <varlistentry>
370: <term><errorcode>0</errorcode></term>
371: <listitem>
372: <para>No error</para>
373: </listitem>
374: </varlistentry>
375:
376: <varlistentry>
377: <term><errorcode>1</errorcode></term>
378: <listitem>
379: <para>Failed to remove an entry from the catalog</para>
380: </listitem>
381: </varlistentry>
382:
383: <varlistentry>
384: <term><errorcode>2</errorcode></term>
385: <listitem>
386: <para>Failed to save to the catalog, check file permissions</para>
387: </listitem>
388: </varlistentry>
389:
390: <varlistentry>
391: <term><errorcode>3</errorcode></term>
392: <listitem>
393: <para>Failed to add an entry to the catalog</para>
394: </listitem>
395: </varlistentry>
396:
397: <varlistentry>
398: <term><errorcode>4</errorcode></term>
399: <listitem>
400: <para>Failed to look up an entry in the catalog</para>
401: </listitem>
402: </varlistentry>
403:
404: </variablelist>
405: </refsect1>
406:
407: <refsect1 id="seealso">
408: <title>SEE ALSO</title>
409: <para><citerefentry>
410: <refentrytitle>libxml</refentrytitle>
411: <manvolnum>3</manvolnum>
412: </citerefentry>
413: </para>
414: <para>
415: More information can be found at
416: <itemizedlist>
417: <listitem>
418: <para><citerefentry>
419: <refentrytitle>libxml</refentrytitle>
420: <manvolnum>3</manvolnum>
421: </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
422: </para>
423: </listitem>
424: <listitem>
425: <para><citerefentry>
426: <refentrytitle>libxml</refentrytitle>
427: <manvolnum>3</manvolnum>
428: </citerefentry> catalog support web page
429: at <ulink url="http://www.xmlsoft.org/catalog.html"/>
430: </para>
431: </listitem>
432: <listitem>
433: <para>James Clark's <acronym>SGML</acronym> catalog
434: page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
435: </para>
436: </listitem>
437: <listitem>
438: <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
439: <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
440: </para>
441: </listitem>
442: </itemizedlist>
443: </para>
444: </refsect1>
445:
446: </refentry>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>