xmlcatalog_man.xml [plain text]
<?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" [
]>
<refentry>
<refentryinfo>
<title>xmlcatalog Manual</title>
<copyright>
<year>2001</year>
</copyright>
<copyright>
<year>2004</year>
</copyright>
<author>
<firstname>John</firstname>
<surname>Fleck</surname>
</author>
<address><email>jfleck@inkstain.net</email></address>
<releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo>
</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>
<arg>--shell</arg>
<arg>--create</arg>
<arg>--add <replaceable>type</replaceable>
<replaceable>orig</replaceable> <replaceable>replace</replaceable></arg>
<arg>--del <replaceable>values</replaceable></arg>
<arg>--noout</arg>
<arg>--verbose</arg>
</group>
<arg><option><replaceable>catalogfile</replaceable></option></arg>
<arg><option><replaceable>entities</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="introduction">
<title>Introduction</title>
<para>
<application>xmlcatalog</application> is a command line application
allowing users to monitor and manipulate <acronym>XML</acronym> and
<acronym>SGML</acronym> catalogs. It is included in
<application>libxml2</application>.
</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="cloptions">
<title>Command Line Options</title>
<variablelist>
<varlistentry>
<term><option>--shell</option> <replaceable>filename</replaceable></term>
<listitem>
<simpara>
Run a shell
allowing interactive queries on catalog file
<replaceable>filename</replaceable>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--create</option> <replaceable>filename</replaceable></term>
<listitem>
<simpara>
Create a new
<acronym>XML</acronym> catalog. Outputs to stdout, ignoring
<replaceable>filename</replaceable> unless <option>--noout</option> is
used, in which case it creates a new catalog file
<replaceable>filename</replaceable>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--add</option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable> <replaceable>filename</replaceable></term>
<listitem>
<simpara>
Add an entry to catalog file
<filename>filename</filename>. <replaceable>type</replaceable>
indicates the type of entry. Possible types are 'public', 'system',
'rewriteSystem', 'rewriteURI', 'delegatePublic', 'delegateSystem',
and 'nextCatalog'. <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
<replaceable>filename</replaceable>, outputting to stdout, 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.
<!--
FIXME - Is my list of possible types correct? Are SGML types the same?
-->
</simpara>
<simpara>
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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--del</option> <replaceable>'values'</replaceable> <replaceable>filename</replaceable></term>
<listitem>
<simpara>
Remove entries from the catalog file
<replaceable>filename</replaceable> matching
<replaceable>'values'</replaceable>. The <option>--del</option> option
will not overwrite <replaceable>filename</replaceable>, outputting to
stdout, unless <option>--noout</option> is used.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--noout</option></term>
<listitem>
<simpara>
Save output to the named file rather than
outputting to stdout.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--sgml</option></term>
<listitem>
<simpara>
Uses SGML Super catalogs for --add and --del options
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option> or <option>--verbose</option></term>
<listitem>
<simpara>
output debugging
information.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="shell">
<title>Shell Commands</title>
<para>Invoking <application>xmlcatalog</application> with the
<option>--shell</option> <replaceable>filename</replaceable> option opens
a command line shell allowing interactive access to the catalog file
identified by <replaceable>filename</replaceable>. Invoking the shell
provides a command line prompt after which commands can be entered.
</para>
<variablelist>
<varlistentry>
<term><option>public</option> <replaceable>'PublicID'</replaceable></term>
<listitem>
<simpara>
Execute a
public identifier lookup of the catalog entry for
<replaceable>'PublicID'</replaceable>. The corresponding entry will be
output to the command line.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>system</option> <replaceable>'SystemID'</replaceable></term>
<listitem>
<simpara>
Execute a
public identifier lookup of the catalog entry for
<replaceable>'SystemID'</replaceable>. The corresponding entry will be
output to the command line.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>add </option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable></term>
<listitem>
<simpara>
Add an entry to the catalog
file. <replaceable>type</replaceable> indicates the type of
entry. Possible types are 'public', 'system', 'rewriteSystem',
'rewriteURI', 'delegatePublic', 'delegateSystem', and
'nextCatalog'. <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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>del</option> <replaceable>'values'</replaceable></term>
<listitem>
<simpara>
Remove the
catalog entry corresponding to <replaceable>'values'</replaceable>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>dump</option></term>
<listitem>
<simpara>
Print the current catalog.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>debug</option></term>
<listitem>
<simpara>
Print debugging statements showing the steps
<application>xmlcatalog</application> is executing.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>quiet</option></term>
<listitem>
<simpara>
Stop printing debugging statements.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>exit</option></term>
<listitem>
<simpara>
Quit the shell.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="return">
<title>Return values</title>
<para><application>xmlcatalog</application>'s return codes provide
information that can be used when calling it from scripts.</para>
<para>0: normal</para>
<para>1: Failed to remove an entry from the catalog</para>
<para>2: Failed to save to the catalog, check file permissions</para>
<para>3: Failed to add an entry to the catalog</para>
<para>4: Failed to lookup and entry in the catalog</para>
</refsect1>
<refsect1>
<title>Catalogs</title>
<para>Catalog behavior can be changed by redirecting
queries to the user's own set of catalogs. This can be done by setting the
<varname>XML_CATALOG_FILES</varname> environment variable to a list of
catalogs. An empty one should deactivate loading the default
<filename>/etc/xml/catalog</filename> default catalog.</para>
</refsect1>
<refsect1>
<title>References</title>
<para><ulink url="http://www.xmlsoft.org/">libxml web page</ulink></para>
<para><ulink url="http://www.xmlsoft.org/catalog.html"><application>libxml</application>
catalog support web page</ulink></para>
<para><ulink url="http://www.jclark.com/sp/catalog.htm">James Clark's
<acronym>SGML</acronym> catalog page</ulink></para>
<para><ulink
url="http://www.oasis-open.org/committees/entity/spec.html"><acronym>OASIS</acronym>
<acronym>XML</acronym> catalog specification</ulink></para>
</refsect1>
</refentry>