doc/xmlcatalog_man.xml - platform/external/libxml2 - Git at Google

 <?xml version="1.0"?>
 <?xml-stylesheet type="text/xsl"
    href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

     <!ENTITY xmlcatalog "<command>xmlcatalog</command>">
 ]>

 <refentry>

 <refentryinfo>
 	<title>xmlcatalog Manual</title>
 	<productname>libxml2</productname>
 	<copyright>
 		<year>2001</year>
 		<year>2004</year>
 	</copyright>
 	<author>
 		<firstname>John</firstname>
 		<surname>Fleck</surname>
 		<affiliation>
 			<address>
 				<email>jfleck@inkstain.net</email>
 			</address>
 		</affiliation>
 	</author>
 	<!-- date should be the date of the latest change or the release version -->
 	<date>$Date$</date>
 	<!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this -->
 	<!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> -->
 	<!-- <edition>0.3</edition> -->
 </refentryinfo>

 <refmeta>
 	<refentrytitle>xmlcatalog</refentrytitle>
 	<manvolnum>1</manvolnum>
 </refmeta>

 <refnamediv>
 	<refname>xmlcatalog</refname>
 	<refpurpose>
 		Command line tool to parse and manipulate <acronym>XML</acronym>
 		or <acronym>SGML</acronym> catalog files.
 	</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
 	<cmdsynopsis>
 	<command>xmlcatalog</command>
 	<group choice="opt">
 		<arg choice="plain"><option>--sgml</option></arg>
 		<arg choice="plain"><option>--shell</option></arg>
 		<arg choice="plain"><option>--create</option></arg>
 		<arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg>
 		<arg choice="plain">
 			<group choice="opt">
 				<arg choice="plain">
 					<option>--add
 					 <replaceable>TYPE</replaceable>
 					 <replaceable>ORIG</replaceable>
 					 <replaceable>REPLACE</replaceable>
 					</option>
 				</arg>
 				<arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg>
 			</group>
 		</arg>
 		<arg choice="plain"><option>--noout</option></arg>
 		<arg choice="plain"><option>--no-super-update</option></arg>
 		<arg choice="plain">
 			<group choice="opt">
 				<arg choice="plain"><option>-v</option></arg>
 				<arg choice="plain"><option>--verbose</option></arg>
 			</group>
 		</arg>
 	</group>
 	<arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg>
 	<arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg>
 	</cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="description">
 	<title>DESCRIPTION</title>
 	<para>
 		&xmlcatalog; is a command line application allowing users to monitor and
 		manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It
 		is included in <citerefentry>
 			<refentrytitle>libxml</refentrytitle>
 			<manvolnum>3</manvolnum>
 		</citerefentry>.
 	</para>
 	<para>
 		Its functions can be invoked from a single command from the command line,
 		or it can perform multiple functions in interactive mode. It can operate
 		on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
 	</para>
 </refsect1>

 <refsect1 id="options">
 	<title>OPTIONS</title>
 	<para>
 		&xmlcatalog; accepts the following options (in alphabetical order):
 	</para>

 	<variablelist>

 		<varlistentry>
 	<term>
 		<option>--add
 		 <replaceable>TYPE</replaceable>
 		 <replaceable>ORIG</replaceable>
 		 <replaceable>REPLACE</replaceable>
 		</option>
 	</term>
 	<listitem>
 		<para>
 			Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable>
 			indicates the type of entry. Possible types are: <simplelist type="inline">
 				<member><parameter>public</parameter></member>
 				<member><parameter>system</parameter></member>
 				<member><parameter>uri</parameter></member>
 				<member><parameter>rewriteSystem</parameter></member>
 				<member><parameter>rewriteURI</parameter></member>
 				<member><parameter>delegatePublic</parameter></member>
 				<member><parameter>delegateSystem</parameter></member>
 				<member><parameter>delegateURI</parameter></member>
 				<member><parameter>nextCatalog</parameter></member>
 			</simplelist>. <replaceable>ORIG</replaceable> is the original
 			reference to be replaced, and <replaceable>REPLACE</replaceable>
 			is the <acronym>URI</acronym> of the replacement entity to be
 			used. The <option>--add</option> option will not overwrite
 			<filename>CATALOGFILE</filename>, outputting
 			to <filename class="devicefile">stdout</filename>, unless
 			<option>--noout</option> is used. The <option>--add</option> will
 			always take three parameters even if some of the <acronym>XML</acronym>
 			catalog constructs will have only a single argument.
 		</para>
 		<!--
 			FIXME - Is my list of possible types correct? Are SGML types the same?
 		-->
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--add <replaceable>FILENAME</replaceable></option></term>
 	<listitem>
 		<para>
 			If the <option>--add</option> option is used following
 			the <option>--sgml</option> option, only a single argument,
 			a <replaceable>FILENAME</replaceable>, is used. This is used to add
 			the name of a catalog file to an <acronym>SGML</acronym> supercatalog,
 			a file that contains references to other included <acronym>SGML</acronym>
 			catalog files.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--create</option></term>
 	<listitem>
 		<para>
 			Create a new <acronym>XML</acronym> catalog. Outputs
 			to <filename class="devicefile">stdout</filename>,
 			ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is
 			used, in which case it creates a new catalog
 			file <replaceable>filename</replaceable>.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--del <replaceable>VALUE(S)</replaceable></option></term>
 	<listitem>
 		<para>
 			Remove entries from <replaceable>CATALOGFILE</replaceable>
 			matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option>
 			option will not overwrite <replaceable>CATALOGFILE</replaceable>,
 			outputting to <filename class="devicefile">stdout</filename>,
 			unless <option>--noout</option> is used.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--noout</option></term>
 	<listitem>
 		<para>
 			Save output to the named file rather than outputting
 			to <filename class="devicefile">stdout</filename>.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--no-super-update</option></term>
 	<listitem>
 		<para>
 			Do not update the <acronym>SGML</acronym> super catalog.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--shell</option></term>
 	<listitem>
 		<para>
 			Run a shell allowing interactive queries on catalog
 			file <replaceable>CATALOGFILE</replaceable>. For the set of available
 			commands see <xref linkend="shell"/>.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>--sgml</option></term>
 	<listitem>
 		<para>
 			Uses <acronym>SGML</acronym> super catalogs for <option>--add</option>
 			and <option>--del</option> options.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>-v</option></term>
 	<term><option>--verbose</option></term>
 	<listitem>
 		<para>Output debugging information.</para>
 	</listitem>
 		</varlistentry>

 	</variablelist>

 	<para>
 		Invoking &xmlcatalog; non-interactively without a designated action
 		(imposed with options like <option>--add</option>) will result in a lookup
 		of the catalog entry for <replaceable>ENTITIES</replaceable> in the
 		catalog denoted with <replaceable>CATALOGFILE</replaceable>. The
 		corresponding entries will be output to the command line. This mode of
 		operation, together with <option>--shell</option> mode and non-modifying
 		(i.e. without <option>--noout</option>) direct actions, allows for
 		a special shortcut of the void <replaceable>CATALOGFILE</replaceable>
 		specification (possibly expressed as &quot;&quot; in the shell
 		environment) appointing the default system catalog. That simplifies the
 		handling when its exact location is irrelevant but the respective built-in
 		still needs to be consulted.
 	</para>
 </refsect1>

 <refsect1 id="shell">
 	<title>SHELL COMMANDS</title>
 	<para>
 		Invoking &xmlcatalog; with
 		the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
 		a command line shell allowing interactive access to the catalog file
 		identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
 		provides a command line prompt after which the following commands (described in
 		alphabetical order) can be entered.
 	</para>

 	<variablelist>

 		<varlistentry>
 	<term>
 		<option>add
 		 <replaceable>TYPE</replaceable>
 		 <replaceable>ORIG</replaceable>
 		 <replaceable>REPLACE</replaceable>
 		</option>
 	</term>
 	<listitem>
 		<para>
 			Add an entry to the catalog file. <replaceable>TYPE</replaceable>
 			indicates the type of entry. Possible types are: <simplelist type="inline">
 				<member><parameter>public</parameter></member>
 				<member><parameter>system</parameter></member>
 				<member><parameter>uri</parameter></member>
 				<member><parameter>rewriteSystem</parameter></member>
 				<member><parameter>rewriteURI</parameter></member>
 				<member><parameter>delegatePublic</parameter></member>
 				<member><parameter>delegateSystem</parameter></member>
 				<member><parameter>delegateURI</parameter></member>
 				<member><parameter>nextCatalog</parameter></member>
 			</simplelist>. <replaceable>ORIG</replaceable> is the original
 			reference to be replaced, and <replaceable>REPLACE</replaceable>
 			is the <acronym>URI</acronym> of the replacement entity to be
 			used. The <option>--add</option> option will not overwrite
 			<filename>CATALOGFILE</filename>, outputting
 			to <filename class="devicefile">stdout</filename>, unless
 			<option>--noout</option> is used. The <option>--add</option> will
 			always take three parameters even if some of the <acronym>XML</acronym>
 			catalog constructs will have only a single argument.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>debug</option></term>
 	<listitem>
 		<para>
 			Print debugging statements showing the steps &xmlcatalog; is executing.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>del <replaceable>VALUE(S)</replaceable></option></term>
 	<listitem>
 		<para>
 			Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>dump</option></term>
 	<listitem>
 		<para>Print the current catalog.</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>exit</option></term>
 	<listitem>
 		<para>Quit the shell.</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
 	<listitem>
 		<para>
 			Execute a Formal Public Identifier lookup of the catalog entry
 			for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
 			output to the command line.
 		</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>quiet</option></term>
 	<listitem>
 		<para>Stop printing debugging statements.</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
 	<listitem>
 		<para>
 			Execute a Formal Public Identifier lookup of the catalog entry
 			for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
 			output to the command line.
 		</para>
 	</listitem>
 		</varlistentry>

 	</variablelist>
 </refsect1>

 <refsect1 id="environment">
 	<title>ENVIRONMENT</title>
 	<variablelist>

 		<varlistentry>
 	<term><envar>XML_CATALOG_FILES</envar></term>
 	<listitem>
 		<para><acronym>XML</acronym> catalog behavior can be changed by redirecting
 			queries to the user's own set of catalogs. This can be done by setting
 			the <envar>XML_CATALOG_FILES</envar> environment variable to a list
 			of catalogs. An empty one should deactivate loading the
 			default <filename>/etc/xml/catalog</filename> catalog.
 		</para>
 	</listitem>
 		</varlistentry>

 	</variablelist>
 </refsect1>

 <refsect1 id="diagnostics">
 	<title>DIAGNOSTICS</title>
 	<para>
 		&xmlcatalog; return codes provide information that can be used when
 		calling it from scripts.
 	</para>
 	<variablelist>

 		<varlistentry>
 	<term><errorcode>0</errorcode></term>
 	<listitem>
 		<para>No error</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><errorcode>1</errorcode></term>
 	<listitem>
 		<para>Failed to remove an entry from the catalog</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><errorcode>2</errorcode></term>
 	<listitem>
 		<para>Failed to save to the catalog, check file permissions</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><errorcode>3</errorcode></term>
 	<listitem>
 		<para>Failed to add an entry to the catalog</para>
 	</listitem>
 		</varlistentry>

 		<varlistentry>
 	<term><errorcode>4</errorcode></term>
 	<listitem>
 		<para>Failed to look up an entry in the catalog</para>
 	</listitem>
 		</varlistentry>

 	</variablelist>
 </refsect1>

 <refsect1 id="seealso">
 	<title>SEE ALSO</title>
 	<para><citerefentry>
 			<refentrytitle>libxml</refentrytitle>
 			<manvolnum>3</manvolnum>
 		</citerefentry>
 	</para>
 	<para>
 		More information can be found at
 		<itemizedlist>
 			<listitem>
 				<para><citerefentry>
 						<refentrytitle>libxml</refentrytitle>
 						<manvolnum>3</manvolnum>
 					</citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
 				</para>
 			</listitem>
 			<listitem>
 				<para><citerefentry>
 						<refentrytitle>libxml</refentrytitle>
 						<manvolnum>3</manvolnum>
 					</citerefentry> catalog support web page
 					at <ulink url="http://www.xmlsoft.org/catalog.html"/>
 				</para>
 			</listitem>
 			<listitem>
 				<para>James Clark's <acronym>SGML</acronym> catalog
 					page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
 				</para>
 			</listitem>
 			<listitem>
 				<para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
 					<ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
 				</para>
 			</listitem>
 		</itemizedlist>
 	</para>
 </refsect1>

 </refentry>
	<?xml version="1.0"?>
	<?xml-stylesheet type="text/xsl"
	href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

	<!ENTITY xmlcatalog "<command>xmlcatalog</command>">
	]>

	<refentry>

	<refentryinfo>
	<title>xmlcatalog Manual</title>
	<productname>libxml2</productname>
	<copyright>
	<year>2001</year>
	<year>2004</year>
	</copyright>
	<author>
	<firstname>John</firstname>
	<surname>Fleck</surname>
	<affiliation>
	<address>
	<email>jfleck@inkstain.net</email>
	</address>
	</affiliation>
	</author>
	<!-- date should be the date of the latest change or the release version -->
	<date>$Date$</date>
	<!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this -->
	<!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> -->
	<!-- <edition>0.3</edition> -->
	</refentryinfo>

	<refmeta>
	<refentrytitle>xmlcatalog</refentrytitle>
	<manvolnum>1</manvolnum>
	</refmeta>

	<refnamediv>
	<refname>xmlcatalog</refname>
	<refpurpose>
	Command line tool to parse and manipulate <acronym>XML</acronym>
	or <acronym>SGML</acronym> catalog files.
	</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<cmdsynopsis>
	<command>xmlcatalog</command>
	<group choice="opt">
	<arg choice="plain"><option>--sgml</option></arg>
	<arg choice="plain"><option>--shell</option></arg>
	<arg choice="plain"><option>--create</option></arg>
	<arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg>
	<arg choice="plain">
	<group choice="opt">
	<arg choice="plain">
	<option>--add
	<replaceable>TYPE</replaceable>
	<replaceable>ORIG</replaceable>
	<replaceable>REPLACE</replaceable>
	</option>
	</arg>
	<arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg>
	</group>
	</arg>
	<arg choice="plain"><option>--noout</option></arg>
	<arg choice="plain"><option>--no-super-update</option></arg>
	<arg choice="plain">
	<group choice="opt">
	<arg choice="plain"><option>-v</option></arg>
	<arg choice="plain"><option>--verbose</option></arg>
	</group>
	</arg>
	</group>
	<arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg>
	<arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg>
	</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1 id="description">
	<title>DESCRIPTION</title>
	<para>
	&xmlcatalog; is a command line application allowing users to monitor and
	manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It
	is included in <citerefentry>
	<refentrytitle>libxml</refentrytitle>
	<manvolnum>3</manvolnum>
	</citerefentry>.
	</para>
	<para>
	Its functions can be invoked from a single command from the command line,
	or it can perform multiple functions in interactive mode. It can operate
	on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
	</para>
	</refsect1>

	<refsect1 id="options">
	<title>OPTIONS</title>
	<para>
	&xmlcatalog; accepts the following options (in alphabetical order):
	</para>

	<variablelist>

	<varlistentry>
	<term>
	<option>--add
	<replaceable>TYPE</replaceable>
	<replaceable>ORIG</replaceable>
	<replaceable>REPLACE</replaceable>
	</option>
	</term>
	<listitem>
	<para>
	Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable>
	indicates the type of entry. Possible types are: <simplelist type="inline">
	<member><parameter>public</parameter></member>
	<member><parameter>system</parameter></member>
	<member><parameter>uri</parameter></member>
	<member><parameter>rewriteSystem</parameter></member>
	<member><parameter>rewriteURI</parameter></member>
	<member><parameter>delegatePublic</parameter></member>
	<member><parameter>delegateSystem</parameter></member>
	<member><parameter>delegateURI</parameter></member>
	<member><parameter>nextCatalog</parameter></member>
	</simplelist>. <replaceable>ORIG</replaceable> is the original
	reference to be replaced, and <replaceable>REPLACE</replaceable>
	is the <acronym>URI</acronym> of the replacement entity to be
	used. The <option>--add</option> option will not overwrite
	<filename>CATALOGFILE</filename>, outputting
	to <filename class="devicefile">stdout</filename>, unless
	<option>--noout</option> is used. The <option>--add</option> will
	always take three parameters even if some of the <acronym>XML</acronym>
	catalog constructs will have only a single argument.
	</para>
	<!--
	FIXME - Is my list of possible types correct? Are SGML types the same?
	-->
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--add <replaceable>FILENAME</replaceable></option></term>
	<listitem>
	<para>
	If the <option>--add</option> option is used following
	the <option>--sgml</option> option, only a single argument,
	a <replaceable>FILENAME</replaceable>, is used. This is used to add
	the name of a catalog file to an <acronym>SGML</acronym> supercatalog,
	a file that contains references to other included <acronym>SGML</acronym>
	catalog files.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--create</option></term>
	<listitem>
	<para>
	Create a new <acronym>XML</acronym> catalog. Outputs
	to <filename class="devicefile">stdout</filename>,
	ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is
	used, in which case it creates a new catalog
	file <replaceable>filename</replaceable>.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--del <replaceable>VALUE(S)</replaceable></option></term>
	<listitem>
	<para>
	Remove entries from <replaceable>CATALOGFILE</replaceable>
	matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option>
	option will not overwrite <replaceable>CATALOGFILE</replaceable>,
	outputting to <filename class="devicefile">stdout</filename>,
	unless <option>--noout</option> is used.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--noout</option></term>
	<listitem>
	<para>
	Save output to the named file rather than outputting
	to <filename class="devicefile">stdout</filename>.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--no-super-update</option></term>
	<listitem>
	<para>
	Do not update the <acronym>SGML</acronym> super catalog.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--shell</option></term>
	<listitem>
	<para>
	Run a shell allowing interactive queries on catalog
	file <replaceable>CATALOGFILE</replaceable>. For the set of available
	commands see <xref linkend="shell"/>.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>--sgml</option></term>
	<listitem>
	<para>
	Uses <acronym>SGML</acronym> super catalogs for <option>--add</option>
	and <option>--del</option> options.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-v</option></term>
	<term><option>--verbose</option></term>
	<listitem>
	<para>Output debugging information.</para>
	</listitem>
	</varlistentry>

	</variablelist>

	<para>
	Invoking &xmlcatalog; non-interactively without a designated action
	(imposed with options like <option>--add</option>) will result in a lookup
	of the catalog entry for <replaceable>ENTITIES</replaceable> in the
	catalog denoted with <replaceable>CATALOGFILE</replaceable>. The
	corresponding entries will be output to the command line. This mode of
	operation, together with <option>--shell</option> mode and non-modifying
	(i.e. without <option>--noout</option>) direct actions, allows for
	a special shortcut of the void <replaceable>CATALOGFILE</replaceable>
	specification (possibly expressed as "" in the shell
	environment) appointing the default system catalog. That simplifies the
	handling when its exact location is irrelevant but the respective built-in
	still needs to be consulted.
	</para>
	</refsect1>

	<refsect1 id="shell">
	<title>SHELL COMMANDS</title>
	<para>
	Invoking &xmlcatalog; with
	the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
	a command line shell allowing interactive access to the catalog file
	identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
	provides a command line prompt after which the following commands (described in
	alphabetical order) can be entered.
	</para>

	<variablelist>

	<varlistentry>
	<term>
	<option>add
	<replaceable>TYPE</replaceable>
	<replaceable>ORIG</replaceable>
	<replaceable>REPLACE</replaceable>
	</option>
	</term>
	<listitem>
	<para>
	Add an entry to the catalog file. <replaceable>TYPE</replaceable>
	indicates the type of entry. Possible types are: <simplelist type="inline">
	<member><parameter>public</parameter></member>
	<member><parameter>system</parameter></member>
	<member><parameter>uri</parameter></member>
	<member><parameter>rewriteSystem</parameter></member>
	<member><parameter>rewriteURI</parameter></member>
	<member><parameter>delegatePublic</parameter></member>
	<member><parameter>delegateSystem</parameter></member>
	<member><parameter>delegateURI</parameter></member>
	<member><parameter>nextCatalog</parameter></member>
	</simplelist>. <replaceable>ORIG</replaceable> is the original
	reference to be replaced, and <replaceable>REPLACE</replaceable>
	is the <acronym>URI</acronym> of the replacement entity to be
	used. The <option>--add</option> option will not overwrite
	<filename>CATALOGFILE</filename>, outputting
	to <filename class="devicefile">stdout</filename>, unless
	<option>--noout</option> is used. The <option>--add</option> will
	always take three parameters even if some of the <acronym>XML</acronym>
	catalog constructs will have only a single argument.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>debug</option></term>
	<listitem>
	<para>
	Print debugging statements showing the steps &xmlcatalog; is executing.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>del <replaceable>VALUE(S)</replaceable></option></term>
	<listitem>
	<para>
	Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>dump</option></term>
	<listitem>
	<para>Print the current catalog.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>exit</option></term>
	<listitem>
	<para>Quit the shell.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
	<listitem>
	<para>
	Execute a Formal Public Identifier lookup of the catalog entry
	for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
	output to the command line.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>quiet</option></term>
	<listitem>
	<para>Stop printing debugging statements.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
	<listitem>
	<para>
	Execute a Formal Public Identifier lookup of the catalog entry
	for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
	output to the command line.
	</para>
	</listitem>
	</varlistentry>

	</variablelist>
	</refsect1>

	<refsect1 id="environment">
	<title>ENVIRONMENT</title>
	<variablelist>

	<varlistentry>
	<term><envar>XML_CATALOG_FILES</envar></term>
	<listitem>
	<para><acronym>XML</acronym> catalog behavior can be changed by redirecting
	queries to the user's own set of catalogs. This can be done by setting
	the <envar>XML_CATALOG_FILES</envar> environment variable to a list
	of catalogs. An empty one should deactivate loading the
	default <filename>/etc/xml/catalog</filename> catalog.
	</para>
	</listitem>
	</varlistentry>

	</variablelist>
	</refsect1>

	<refsect1 id="diagnostics">
	<title>DIAGNOSTICS</title>
	<para>
	&xmlcatalog; return codes provide information that can be used when
	calling it from scripts.
	</para>
	<variablelist>

	<varlistentry>
	<term><errorcode>0</errorcode></term>
	<listitem>
	<para>No error</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><errorcode>1</errorcode></term>
	<listitem>
	<para>Failed to remove an entry from the catalog</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><errorcode>2</errorcode></term>
	<listitem>
	<para>Failed to save to the catalog, check file permissions</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><errorcode>3</errorcode></term>
	<listitem>
	<para>Failed to add an entry to the catalog</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><errorcode>4</errorcode></term>
	<listitem>
	<para>Failed to look up an entry in the catalog</para>
	</listitem>
	</varlistentry>

	</variablelist>
	</refsect1>

	<refsect1 id="seealso">
	<title>SEE ALSO</title>
	<para><citerefentry>
	<refentrytitle>libxml</refentrytitle>
	<manvolnum>3</manvolnum>
	</citerefentry>
	</para>
	<para>
	More information can be found at
	<itemizedlist>
	<listitem>
	<para><citerefentry>
	<refentrytitle>libxml</refentrytitle>
	<manvolnum>3</manvolnum>
	</citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
	</para>
	</listitem>
	<listitem>
	<para><citerefentry>
	<refentrytitle>libxml</refentrytitle>
	<manvolnum>3</manvolnum>
	</citerefentry> catalog support web page
	at <ulink url="http://www.xmlsoft.org/catalog.html"/>
	</para>
	</listitem>
	<listitem>
	<para>James Clark's <acronym>SGML</acronym> catalog
	page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
	</para>
	</listitem>
	<listitem>
	<para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
	<ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
	</para>
	</listitem>
	</itemizedlist>
	</para>
	</refsect1>

	</refentry>