libxml2/doc/xmlcatalog_man.xml

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