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