xmlcatalog_man.xml revision 3fc555e520e33464081c31b529cc24aac86d7852 
1<?xml version="1.0"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4]>
5<refentry>
6  <refentryinfo>
7    <title>xmlcatalog Manual</title>
8    <copyright>
9      <year>2001</year>
10    </copyright>
11    <author>
12      <firstname>John</firstname>
13      <surname>Fleck</surname>
14    </author>
15    <address><email>jfleck@inkstain.net</email></address>
16    
17    <releaseinfo>This is release 0.2 of the xmlcatalog Manual.</releaseinfo>
18  </refentryinfo>
19
20 <refmeta>
21    <refentrytitle>xmlcatalog</refentrytitle>
22    <manvolnum>1</manvolnum>
23  </refmeta>
24  <refnamediv>
25    <refname>xmlcatalog</refname>
26    <refpurpose>Command line tool to parse and manipulate <acronym>XML</acronym> or
27      <acronym>SGML</acronym> catalog files.</refpurpose>
28  </refnamediv>
29
30  <refsynopsisdiv>
31    <cmdsynopsis>
32      <command>xmlcatalog</command>
33      <group>
34	<arg>--shell</arg>
35	<arg>--create</arg>
36	<arg>--add <replaceable>type</replaceable>
37	  <replaceable>orig</replaceable> <replaceable>replace</replaceable></arg>
38	<arg>--del <replaceable>values</replaceable></arg>
39	<arg>--noout</arg>
40	<arg>--verbose</arg>
41      </group>
42      <arg><option><replaceable>catalogfile</replaceable></option></arg>
43      <arg><option><replaceable>entities</replaceable></option></arg>
44    </cmdsynopsis>
45  </refsynopsisdiv>
46
47  <refsect1 id="introduction">
48    <title>Introduction</title>
49    <para>
50      <application>xmlcatalog</application> is a command line application
51      allowing users to monitor and manipulate <acronym>XML</acronym> and
52      <acronym>SGML</acronym> catalogs. It is included in
53      <application>libxml2</application>.
54    </para>
55
56    <para>
57      Its functions can be invoked from a single command from the command line,
58      or it can perform multiple functions in interactive mode. It can operate
59      on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
60    </para>
61  </refsect1>
62  
63  <refsect1 id="cloptions">
64    <title>Command Line Options</title>
65    <variablelist>
66      <varlistentry>
67	<term><option>--shell</option> <replaceable>filename</replaceable></term>
68	<listitem>
69	  <simpara>
70	    Run a shell
71	    allowing interactive queries on catalog file
72	    <replaceable>filename</replaceable>.
73	  </simpara>
74	</listitem>
75      </varlistentry>
76      <varlistentry>
77	<term><option>--create</option> <replaceable>filename</replaceable></term>
78	<listitem>
79	  <simpara>
80	    Create a new
81	    <acronym>XML</acronym> catalog. Outputs to stdout, ignoring
82	    <replaceable>filename</replaceable> unless <option>--noout</option> is
83	    used, in which case it creates a new catalog file
84	    <replaceable>filename</replaceable>.
85	  </simpara>
86	</listitem>
87      </varlistentry>
88
89      <varlistentry>
90	<term><option>--add</option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable> <replaceable>filename</replaceable></term>
91	<listitem>
92	  <simpara>
93	    Add an entry to catalog file
94	    <filename>filename</filename>. <replaceable>type</replaceable> indicates
95	    the type of entry. Possible types are 'public', 'system', 'rewriteSystem',
96	    'delegatePublic' and 'delegateSystem'. <replaceable>'orig'</replaceable>
97	    is the original reference to 
98	    be replaced, and <replaceable>'replace'</replaceable> is the
99	    <acronym>URI</acronym> of the replacement entity to be used. The
100	    <option>--add</option> option will not overwrite
101	    <replaceable>filename</replaceable>, outputing to stdout, unless
102	    <option>--noout</option> is used. The <option>--add</option> will always
103	    take three parameters even if some of the <acronym>XML</acronym> catalog
104	    constructs will have only a single argument.
105<!--
106FIXME - Is my list of possible types correct? Are SGML types the same? 
107-->
108	  </simpara>
109	  <simpara>
110	    If the <option>--add</option> option is used following the
111	    <option>--sgml</option> option, only a single argument, a
112	    <replaceable>filename</replaceable>, is used. This is used to add
113	    the name of a catalog file to an <acronym>SGML</acronym>
114	    supercatalog, a file that contains references to other included
115	    <acronym>SGML</acronym> catalog files.
116	  </simpara>
117	</listitem>
118      </varlistentry>
119      <varlistentry>
120	<term><option>--del</option> <replaceable>'values'</replaceable> <replaceable>filename</replaceable></term>
121	<listitem>
122	 <simpara>
123	    Remove entries from the catalog file
124	    <replaceable>filename</replaceable> matching
125	    <replaceable>'values'</replaceable>. The <option>--del</option> option
126	    will not overwrite <replaceable>filename</replaceable>, outputing to
127	    stdout, unless <option>--noout</option> is used.
128	  </simpara>
129	</listitem>
130      </varlistentry>
131      <varlistentry>
132	<term><option>--noout</option></term>
133	<listitem>
134	  <simpara>
135	    Save output to the named file rather than
136	    outputing to stdout.
137	  </simpara>
138	</listitem>
139      </varlistentry>
140      <varlistentry>
141	<term><option>-v</option> or <option>--verbose</option></term>
142	<listitem>
143	  <simpara>
144	    output debugging
145	    information.
146	  </simpara>
147	</listitem>
148      </varlistentry>
149    </variablelist>
150  </refsect1>
151
152  <refsect1 id="shell">
153    <title>Shell Commands</title>
154    <para>Invoking <application>xmlcatalog</application> with the
155      <option>--shell</option> <replaceable>filename</replaceable> option opens
156    a command line shell allowing interactive access to the catalog file
157      identified by <replaceable>filename</replaceable>. Invoking the shell
158    provides a command line prompt after which commands can be entered.
159    </para>
160
161    <variablelist>
162      <varlistentry>
163	<term><option>public</option> <replaceable>'PublicID'</replaceable></term>
164	<listitem>
165	  <simpara>
166	    Execute a
167	    public identifier lookup of the catalog entry for
168	    <replaceable>'PublicID'</replaceable>. The corresponding entry will be
169	    output to the command line.
170	  </simpara>
171	</listitem>
172      </varlistentry>
173    
174      <varlistentry>
175	<term><option>system</option> <replaceable>'SystemID'</replaceable></term>
176	<listitem>
177	 <simpara>
178	    Execute a
179	    public identifier lookup of the catalog entry for
180	    <replaceable>'SystemID'</replaceable>. The corresponding entry will be
181	    output to the command line.
182	  </simpara>
183	</listitem>
184      </varlistentry>
185      <varlistentry>
186	<term><option>add </option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable></term>
187	<listitem>
188	  <simpara>
189	    Add an entry to the catalog
190	    file. <replaceable>type</replaceable> indicates the type of
191	    entry. Possible types are 'public', 'system', 'rewriteSystem',
192	    'delegatePublic' and 'delegateSystem'. <replaceable>'orig'</replaceable>
193	    is the original reference to  be replaced, and
194	    <replaceable>'replace'</replaceable> is the <acronym>URI</acronym> of the
195	    replacement entity to be used.
196	  </simpara>
197	</listitem>
198      </varlistentry>
199      <varlistentry>
200	<term><option>del</option> <replaceable>'values'</replaceable></term>
201	<listitem>
202	  <simpara>
203	    Remove the
204	    catalog entry corresponding to <replaceable>'values'</replaceable>.
205	  </simpara>
206	</listitem>
207      </varlistentry>
208
209      <varlistentry>
210	<term><option>dump</option></term>
211	<listitem>
212	   <simpara>
213	    Print the current catalog.
214	  </simpara> 
215	</listitem>
216      </varlistentry>
217
218      <varlistentry>
219	<term><option>debug</option></term>
220	<listitem>
221	  <simpara>
222	    Print debugging statements showing the steps
223	    <application>xmlcatalog</application> is executing.
224	  </simpara>
225	</listitem>
226      </varlistentry>
227    
228      <varlistentry>
229	<term><option>quiet</option></term>
230	<listitem>
231	<simpara>
232	    Stop printing debugging statements.
233	  </simpara>
234	</listitem>
235      </varlistentry>
236    
237      <varlistentry>
238	<term><option>exit</option></term>
239	<listitem>
240	  <simpara>
241	    Quit the shell.
242	  </simpara>
243	</listitem>
244      </varlistentry>
245    </variablelist>
246
247  </refsect1>
248
249  <refsect1>
250    <title>References</title>
251    <para><ulink url="http://www.xmlsoft.org/">libxml web page</ulink></para>
252
253    <para><ulink url="http://www.xmlsoft.org/catalog.html"><application>libxml</application>
254    catalog support web page:</ulink></para>
255
256    <para><ulink url="http://www.jclark.com/sp/catalog.htm">James Clark's
257    <acronym>SGML</acronym> catalog page:</ulink></para>
258  
259    <para><ulink
260    url="http://www.oasis-open.org/committees/entity/spec.html"><acronym>OASIS</acronym>
261    <acronym>XML</acronym> catalog specification: </ulink></para>
262</refsect1>
263
264
265</refentry>