libxml2/doc/xmlcatalog_man.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <refentry>
   6   <refentryinfo>
   7     <title>xmlcatalog Manual</title>
   8     <copyright>
   9       <year>2001</year>
  10     </copyright>
  11     <author>
  12       <firstname>John</firstname>
  13       <surname>Fleck</surname>
  14     </author>
  15     <address><email>jfleck@inkstain.net</email></address>
  16
  17     <releaseinfo>This is release 0.2 of the xmlcatalog Manual.</releaseinfo>
  18   </refentryinfo>
  19
  20  <refmeta>
  21     <refentrytitle>xmlcatalog</refentrytitle>
  22     <manvolnum>1</manvolnum>
  23   </refmeta>
  24   <refnamediv>
  25     <refname>xmlcatalog</refname>
  26     <refpurpose>Command line tool to parse and manipulate <acronym>XML</acronym> or
  27       <acronym>SGML</acronym> catalog files.</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <cmdsynopsis>
  32       <command>xmlcatalog</command>
  33       <group>
  34         <arg>--shell</arg>
  35         <arg>--create</arg>
  36         <arg>--add <replaceable>type</replaceable>
  37           <replaceable>orig</replaceable> <replaceable>replace</replaceable></arg>
  38         <arg>--del <replaceable>values</replaceable></arg>
  39         <arg>--noout</arg>
  40         <arg>--verbose</arg>
  41       </group>
  42       <arg><option><replaceable>catalogfile</replaceable></option></arg>
  43       <arg><option><replaceable>entities</replaceable></option></arg>
  44     </cmdsynopsis>
  45   </refsynopsisdiv>
  46
  47   <refsect1 id="introduction">
  48     <title>Introduction</title>
  49     <para>
  50       <application>xmlcatalog</application> is a command line application
  51       allowing users to monitor and manipulate <acronym>XML</acronym> and
  52       <acronym>SGML</acronym> catalogs. It is included in
  53       <application>libxml2</application>.
  54     </para>
  55
  56     <para>
  57       Its functions can be invoked from a single command from the command line,
  58       or it can perform multiple functions in interactive mode. It can operate
  59       on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
  60     </para>
  61   </refsect1>
  62
  63   <refsect1 id="cloptions">
  64     <title>Command Line Options</title>
  65     <variablelist>
  66       <varlistentry>
  67         <term><option>--shell</option> <replaceable>filename</replaceable></term>
  68         <listitem>
  69           <simpara>
  70             Run a shell
  71             allowing interactive queries on catalog file
  72             <replaceable>filename</replaceable>.
  73           </simpara>
  74         </listitem>
  75       </varlistentry>
  76       <varlistentry>
  77         <term><option>--create</option> <replaceable>filename</replaceable></term>
  78         <listitem>
  79           <simpara>
  80             Create a new
  81             <acronym>XML</acronym> catalog. Outputs to stdout, ignoring
  82             <replaceable>filename</replaceable> unless <option>--noout</option> is
  83             used, in which case it creates a new catalog file
  84             <replaceable>filename</replaceable>.
  85           </simpara>
  86         </listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><option>--add</option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable> <replaceable>filename</replaceable></term>
  91         <listitem>
  92           <simpara>
  93             Add an entry to catalog file
  94             <filename>filename</filename>. <replaceable>type</replaceable>
  95             indicates the type of entry. Possible types are 'public', 'system',
  96             'rewriteSystem', 'delegatePublic', 'delegateSystem'amd
  97             'rewriteURI'. <replaceable>'orig'</replaceable> is the original
  98             reference to be replaced, and <replaceable>'replace'</replaceable>
  99             is the <acronym>URI</acronym> of the replacement entity to be
 100             used. The <option>--add</option> option will not overwrite
 101             <replaceable>filename</replaceable>, outputing to stdout, unless
 102             <option>--noout</option> is used. The <option>--add</option> will
 103             always take three parameters even if some of the
 104             <acronym>XML</acronym> catalog constructs will have only a single
 105             argument.
 106 <!--
 107 FIXME - Is my list of possible types correct? Are SGML types the same?
 108 -->
 109           </simpara>
 110           <simpara>
 111             If the <option>--add</option> option is used following the
 112             <option>--sgml</option> option, only a single argument, a
 113             <replaceable>filename</replaceable>, is used. This is used to add
 114             the name of a catalog file to an <acronym>SGML</acronym>
 115             supercatalog, a file that contains references to other included
 116             <acronym>SGML</acronym> catalog files.
 117           </simpara>
 118         </listitem>
 119       </varlistentry>
 120       <varlistentry>
 121         <term><option>--del</option> <replaceable>'values'</replaceable> <replaceable>filename</replaceable></term>
 122         <listitem>
 123          <simpara>
 124             Remove entries from the catalog file
 125             <replaceable>filename</replaceable> matching
 126             <replaceable>'values'</replaceable>. The <option>--del</option> option
 127             will not overwrite <replaceable>filename</replaceable>, outputing to
 128             stdout, unless <option>--noout</option> is used.
 129           </simpara>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><option>--noout</option></term>
 134         <listitem>
 135           <simpara>
 136             Save output to the named file rather than
 137             outputing to stdout.
 138           </simpara>
 139         </listitem>
 140       </varlistentry>
 141       <varlistentry>
 142         <term><option>--sgml</option></term>
 143         <listitem>
 144           <simpara>
 145             Uses SGML Super catalogs for --add and --del options
 146           </simpara>
 147         </listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term><option>-v</option> or <option>--verbose</option></term>
 151         <listitem>
 152           <simpara>
 153             output debugging
 154             information.
 155           </simpara>
 156         </listitem>
 157       </varlistentry>
 158     </variablelist>
 159   </refsect1>
 160
 161   <refsect1 id="shell">
 162     <title>Shell Commands</title>
 163     <para>Invoking <application>xmlcatalog</application> with the
 164       <option>--shell</option> <replaceable>filename</replaceable> option opens
 165     a command line shell allowing interactive access to the catalog file
 166       identified by <replaceable>filename</replaceable>. Invoking the shell
 167     provides a command line prompt after which commands can be entered.
 168     </para>
 169
 170     <variablelist>
 171       <varlistentry>
 172         <term><option>public</option> <replaceable>'PublicID'</replaceable></term>
 173         <listitem>
 174           <simpara>
 175             Execute a
 176             public identifier lookup of the catalog entry for
 177             <replaceable>'PublicID'</replaceable>. The corresponding entry will be
 178             output to the command line.
 179           </simpara>
 180         </listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term><option>system</option> <replaceable>'SystemID'</replaceable></term>
 185         <listitem>
 186          <simpara>
 187             Execute a
 188             public identifier lookup of the catalog entry for
 189             <replaceable>'SystemID'</replaceable>. The corresponding entry will be
 190             output to the command line.
 191           </simpara>
 192         </listitem>
 193       </varlistentry>
 194       <varlistentry>
 195         <term><option>add </option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable></term>
 196         <listitem>
 197           <simpara>
 198             Add an entry to the catalog
 199             file. <replaceable>type</replaceable> indicates the type of
 200             entry. Possible types are 'public', 'system', 'rewriteSystem',
 201             'delegatePublic' and 'delegateSystem'. <replaceable>'orig'</replaceable>
 202             is the original reference to  be replaced, and
 203             <replaceable>'replace'</replaceable> is the <acronym>URI</acronym> of the
 204             replacement entity to be used.
 205           </simpara>
 206         </listitem>
 207       </varlistentry>
 208       <varlistentry>
 209         <term><option>del</option> <replaceable>'values'</replaceable></term>
 210         <listitem>
 211           <simpara>
 212             Remove the
 213             catalog entry corresponding to <replaceable>'values'</replaceable>.
 214           </simpara>
 215         </listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><option>dump</option></term>
 220         <listitem>
 221            <simpara>
 222             Print the current catalog.
 223           </simpara>
 224         </listitem>
 225       </varlistentry>
 226
 227       <varlistentry>
 228         <term><option>debug</option></term>
 229         <listitem>
 230           <simpara>
 231             Print debugging statements showing the steps
 232             <application>xmlcatalog</application> is executing.
 233           </simpara>
 234         </listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><option>quiet</option></term>
 239         <listitem>
 240         <simpara>
 241             Stop printing debugging statements.
 242           </simpara>
 243         </listitem>
 244       </varlistentry>
 245
 246       <varlistentry>
 247         <term><option>exit</option></term>
 248         <listitem>
 249           <simpara>
 250             Quit the shell.
 251           </simpara>
 252         </listitem>
 253       </varlistentry>
 254     </variablelist>
 255
 256   </refsect1>
 257
 258   <refsect1 id="return">
 259     <title>Return values</title>
 260     <para><application>xmlcatalog</application>'s return codes provide
 261     information that can be used when calling it from scripts.</para>
 262
 263     <para>0: normal</para>
 264     <para>1: Failed to remove an entry from the catalog</para>
 265     <para>2: Failed to save to the catalog, check file permissions</para>
 266     <para>3: Failed to add an entry to the catalog</para>
 267     <para>4: Failed to lookup and entry in the catalog</para>
 268   </refsect1>
 269
 270   <refsect1>
 271     <title>References</title>
 272     <para><ulink url="http://www.xmlsoft.org/">libxml web page</ulink></para>
 273
 274     <para><ulink url="http://www.xmlsoft.org/catalog.html"><application>libxml</application>
 275     catalog support web page:</ulink></para>
 276
 277     <para><ulink url="http://www.jclark.com/sp/catalog.htm">James Clark's
 278     <acronym>SGML</acronym> catalog page:</ulink></para>
 279
 280     <para><ulink
 281     url="http://www.oasis-open.org/committees/entity/spec.html"><acronym>OASIS</acronym>
 282     <acronym>XML</acronym> catalog specification: </ulink></para>
 283 </refsect1>
 284
 285
 286 </refentry>