doc/xmlcatalog_man.xml

<?xml version="1.0"?>
<!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>
    <author>
      <firstname>John</firstname>
      <surname>Fleck</surname>
    </author>
    <address><email>jfleck@inkstain.net</email></address>
    
    <releaseinfo>This is release 0.2 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', 'delegatePublic', 'delegateSystem'amd
	    'rewriteURI'. <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>, outputing 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>, outputing 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
	    outputing 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',
	    'delegatePublic' and 'delegateSystem'. <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>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>