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>
    <legalnotice id="legalnotice">
      <para>Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU Free Documentation
	    License, Version 1.1 or any later version 
	published by the Free Software Foundation with no Invariant Sections, 
	no Front-Cover Texts, and no Back-Cover Texts.
      </para>
      <para>Many of the names used by companies to distinguish their products and
	services are claimed as trademarks. Where those names appear in any
	GNOME documentation, and those trademarks are made aware to the members
	of the GNOME Documentation Project, the names have been printed in caps
	or initial caps.
      </para>
    </legalnotice>
    <releaseinfo>This is release 0.1 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' 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. 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>-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="references">
    <title>References</title>
    <variablelist>
   

      <varlistentry>
	<term>libxml web page:</term>
	<listitem>
	  <simpara>
	  <ulink
	  url="http://www.xmlsoft.org/">http://www.xmlsoft.org/</ulink>
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><application>libxml</application> catalog support web page:</term>
	<listitem>
	<simpara>
	    <ulink url="http://www.xmlsoft.org/catalog.html">http://www.xmlsoft.org/catalog.html</ulink>
	  </simpara>
	</listitem>
      </varlistentry>

 
      <varlistentry>
	<term>James Clark's <acronym>SGML</acronym> catalog page:</term>
	<listitem>
	 <simpara>
	     <ulink
								       url="http://www.jclark.com/sp/catalog.htm">http://www.jclark.com/sp/catalog.htm</ulink>
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification:</term>
	<listitem>
	  <simpara>
	     <ulink
				  url="http://www.oasis-open.org/committees/entity/spec.html">http://www.oasis-open.org/committees/entity/spec.html</ulink>
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>
    
  </refsect1>

</refentry>