href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

    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>$Date$</date>

</refentryinfo>

<refmeta>

	<refentrytitle>xmlcatalog</refentrytitle>

	<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

	<refname>xmlcatalog</refname>

	<refpurpose>

		Command line tool to parse and manipulate XML

		or SGML 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 XML and SGML 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 XML and SGML 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 URI 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 XML

			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 SGML supercatalog,

			a file that contains references to other included SGML

			catalog files.

		</para>

	</listitem>

		</varlistentry>

		<varlistentry>

	<term><option>--create</option></term>

	<listitem>

		<para>

			Create a new XML 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 SGML 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 SGML 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 URI 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 XML

			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>XML 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 SGML catalog

					page <ulink url="http://www.jclark.com/sp/catalog.htm"/>

				</para>

			</listitem>

			<listitem>

				<para>OASIS XML catalog specification

					<ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>

				</para>

			</listitem>

		</itemizedlist>

	</para>

</refsect1>

</refentry>