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     <!ENTITY xmlcatalog "<command>xmlcatalog</command>">
   8 ]>
   9
  10 <refentry>
  11
  12 <refentryinfo>
  13         <title>xmlcatalog Manual</title>
  14         <productname>libxml2</productname>
  15         <copyright>
  16                 <year>2001</year>
  17                 <year>2004</year>
  18         </copyright>
  19         <author>
  20                 <firstname>John</firstname>
  21                 <surname>Fleck</surname>
  22                 <affiliation>
  23                         <address>
  24                                 <email>jfleck@inkstain.net</email>
  25                         </address>
  26                 </affiliation>
  27         </author>
  28         <!-- date should be the date of the latest change or the release version -->
  29         <date>$Date$</date>
  30         <!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this -->
  31         <!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> -->
  32         <!-- <edition>0.3</edition> -->
  33 </refentryinfo>
  34
  35 <refmeta>
  36         <refentrytitle>xmlcatalog</refentrytitle>
  37         <manvolnum>1</manvolnum>
  38 </refmeta>
  39
  40 <refnamediv>
  41         <refname>xmlcatalog</refname>
  42         <refpurpose>
  43                 Command line tool to parse and manipulate <acronym>XML</acronym>
  44                 or <acronym>SGML</acronym> catalog files.
  45         </refpurpose>
  46 </refnamediv>
  47
  48 <refsynopsisdiv>
  49         <cmdsynopsis>
  50         <command>xmlcatalog</command>
  51         <group choice="opt">
  52                 <arg choice="plain"><option>--sgml</option></arg>
  53                 <arg choice="plain"><option>--shell</option></arg>
  54                 <arg choice="plain"><option>--create</option></arg>
  55                 <arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg>
  56                 <arg choice="plain">
  57                         <group choice="opt">
  58                                 <arg choice="plain">
  59                                         <option>--add
  60                                          <replaceable>TYPE</replaceable>
  61                                          <replaceable>ORIG</replaceable>
  62                                          <replaceable>REPLACE</replaceable>
  63                                         </option>
  64                                 </arg>
  65                                 <arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg>
  66                         </group>
  67                 </arg>
  68                 <arg choice="plain"><option>--noout</option></arg>
  69                 <arg choice="plain"><option>--no-super-update</option></arg>
  70                 <arg choice="plain">
  71                         <group choice="opt">
  72                                 <arg choice="plain"><option>-v</option></arg>
  73                                 <arg choice="plain"><option>--verbose</option></arg>
  74                         </group>
  75                 </arg>
  76         </group>
  77         <arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg>
  78         <arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg>
  79         </cmdsynopsis>
  80 </refsynopsisdiv>
  81
  82 <refsect1 id="description">
  83         <title>DESCRIPTION</title>
  84         <para>
  85                 &xmlcatalog; is a command line application allowing users to monitor and
  86                 manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It
  87                 is included in <citerefentry>
  88                         <refentrytitle>libxml</refentrytitle>
  89                         <manvolnum>3</manvolnum>
  90                 </citerefentry>.
  91         </para>
  92         <para>
  93                 Its functions can be invoked from a single command from the command line,
  94                 or it can perform multiple functions in interactive mode. It can operate
  95                 on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
  96         </para>
  97 </refsect1>
  98
  99 <refsect1 id="options">
 100         <title>OPTIONS</title>
 101         <para>
 102                 &xmlcatalog; accepts the following options (in alphabetical order):
 103         </para>
 104
 105         <variablelist>
 106
 107                 <varlistentry>
 108         <term>
 109                 <option>--add
 110                  <replaceable>TYPE</replaceable>
 111                  <replaceable>ORIG</replaceable>
 112                  <replaceable>REPLACE</replaceable>
 113                 </option>
 114         </term>
 115         <listitem>
 116                 <para>
 117                         Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable>
 118                         indicates the type of entry. Possible types are: <simplelist type="inline">
 119                                 <member><parameter>public</parameter></member>
 120                                 <member><parameter>system</parameter></member>
 121                                 <member><parameter>uri</parameter></member>
 122                                 <member><parameter>rewriteSystem</parameter></member>
 123                                 <member><parameter>rewriteURI</parameter></member>
 124                                 <member><parameter>delegatePublic</parameter></member>
 125                                 <member><parameter>delegateSystem</parameter></member>
 126                                 <member><parameter>delegateURI</parameter></member>
 127                                 <member><parameter>nextCatalog</parameter></member>
 128                         </simplelist>. <replaceable>ORIG</replaceable> is the original
 129                         reference to be replaced, and <replaceable>REPLACE</replaceable>
 130                         is the <acronym>URI</acronym> of the replacement entity to be
 131                         used. The <option>--add</option> option will not overwrite
 132                         <filename>CATALOGFILE</filename>, outputting
 133                         to <filename class="devicefile">stdout</filename>, unless
 134                         <option>--noout</option> is used. The <option>--add</option> will
 135                         always take three parameters even if some of the <acronym>XML</acronym>
 136                         catalog constructs will have only a single argument.
 137                 </para>
 138                 <!--
 139                         FIXME - Is my list of possible types correct? Are SGML types the same?
 140                 -->
 141         </listitem>
 142                 </varlistentry>
 143
 144                 <varlistentry>
 145         <term><option>--add <replaceable>FILENAME</replaceable></option></term>
 146         <listitem>
 147                 <para>
 148                         If the <option>--add</option> option is used following
 149                         the <option>--sgml</option> option, only a single argument,
 150                         a <replaceable>FILENAME</replaceable>, is used. This is used to add
 151                         the name of a catalog file to an <acronym>SGML</acronym> supercatalog,
 152                         a file that contains references to other included <acronym>SGML</acronym>
 153                         catalog files.
 154                 </para>
 155         </listitem>
 156                 </varlistentry>
 157
 158                 <varlistentry>
 159         <term><option>--create</option></term>
 160         <listitem>
 161                 <para>
 162                         Create a new <acronym>XML</acronym> catalog. Outputs
 163                         to <filename class="devicefile">stdout</filename>,
 164                         ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is
 165                         used, in which case it creates a new catalog
 166                         file <replaceable>filename</replaceable>.
 167                 </para>
 168         </listitem>
 169                 </varlistentry>
 170
 171                 <varlistentry>
 172         <term><option>--del <replaceable>VALUE(S)</replaceable></option></term>
 173         <listitem>
 174                 <para>
 175                         Remove entries from <replaceable>CATALOGFILE</replaceable>
 176                         matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option>
 177                         option will not overwrite <replaceable>CATALOGFILE</replaceable>,
 178                         outputting to <filename class="devicefile">stdout</filename>,
 179                         unless <option>--noout</option> is used.
 180                 </para>
 181         </listitem>
 182                 </varlistentry>
 183
 184                 <varlistentry>
 185         <term><option>--noout</option></term>
 186         <listitem>
 187                 <para>
 188                         Save output to the named file rather than outputting
 189                         to <filename class="devicefile">stdout</filename>.
 190                 </para>
 191         </listitem>
 192                 </varlistentry>
 193
 194                 <varlistentry>
 195         <term><option>--no-super-update</option></term>
 196         <listitem>
 197                 <para>
 198                         Do not update the <acronym>SGML</acronym> super catalog.
 199                 </para>
 200         </listitem>
 201                 </varlistentry>
 202
 203                 <varlistentry>
 204         <term><option>--shell</option></term>
 205         <listitem>
 206                 <para>
 207                         Run a shell allowing interactive queries on catalog
 208                         file <replaceable>CATALOGFILE</replaceable>. For the set of available
 209                         commands see <xref linkend="shell"/>.
 210                 </para>
 211         </listitem>
 212                 </varlistentry>
 213
 214                 <varlistentry>
 215         <term><option>--sgml</option></term>
 216         <listitem>
 217                 <para>
 218                         Uses <acronym>SGML</acronym> super catalogs for <option>--add</option>
 219                         and <option>--del</option> options.
 220                 </para>
 221         </listitem>
 222                 </varlistentry>
 223
 224                 <varlistentry>
 225         <term><option>-v</option></term>
 226         <term><option>--verbose</option></term>
 227         <listitem>
 228                 <para>Output debugging information.</para>
 229         </listitem>
 230                 </varlistentry>
 231
 232         </variablelist>
 233
 234         <para>
 235                 Invoking &xmlcatalog; non-interactively without a designated action
 236                 (imposed with options like <option>--add</option>) will result in a lookup
 237                 of the catalog entry for <replaceable>ENTITIES</replaceable> in the
 238                 catalog denoted with <replaceable>CATALOGFILE</replaceable>. The
 239                 corresponding entries will be output to the command line. This mode of
 240                 operation, together with <option>--shell</option> mode and non-modifying
 241                 (i.e. without <option>--noout</option>) direct actions, allows for
 242                 a special shortcut of the void <replaceable>CATALOGFILE</replaceable>
 243                 specification (possibly expressed as &quot;&quot; in the shell
 244                 environment) appointing the default system catalog. That simplifies the
 245                 handling when its exact location is irrelevant but the respective built-in
 246                 still needs to be consulted.
 247         </para>
 248 </refsect1>
 249
 250 <refsect1 id="shell">
 251         <title>SHELL COMMANDS</title>
 252         <para>
 253                 Invoking &xmlcatalog; with
 254                 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
 255                 a command line shell allowing interactive access to the catalog file
 256                 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
 257                 provides a command line prompt after which the following commands (described in
 258                 alphabetical order) can be entered.
 259         </para>
 260
 261         <variablelist>
 262
 263                 <varlistentry>
 264         <term>
 265                 <option>add
 266                  <replaceable>TYPE</replaceable>
 267                  <replaceable>ORIG</replaceable>
 268                  <replaceable>REPLACE</replaceable>
 269                 </option>
 270         </term>
 271         <listitem>
 272                 <para>
 273                         Add an entry to the catalog file. <replaceable>TYPE</replaceable>
 274                         indicates the type of entry. Possible types are: <simplelist type="inline">
 275                                 <member><parameter>public</parameter></member>
 276                                 <member><parameter>system</parameter></member>
 277                                 <member><parameter>uri</parameter></member>
 278                                 <member><parameter>rewriteSystem</parameter></member>
 279                                 <member><parameter>rewriteURI</parameter></member>
 280                                 <member><parameter>delegatePublic</parameter></member>
 281                                 <member><parameter>delegateSystem</parameter></member>
 282                                 <member><parameter>delegateURI</parameter></member>
 283                                 <member><parameter>nextCatalog</parameter></member>
 284                         </simplelist>. <replaceable>ORIG</replaceable> is the original
 285                         reference to be replaced, and <replaceable>REPLACE</replaceable>
 286                         is the <acronym>URI</acronym> of the replacement entity to be
 287                         used. The <option>--add</option> option will not overwrite
 288                         <filename>CATALOGFILE</filename>, outputting
 289                         to <filename class="devicefile">stdout</filename>, unless
 290                         <option>--noout</option> is used. The <option>--add</option> will
 291                         always take three parameters even if some of the <acronym>XML</acronym>
 292                         catalog constructs will have only a single argument.
 293                 </para>
 294         </listitem>
 295                 </varlistentry>
 296
 297                 <varlistentry>
 298         <term><option>debug</option></term>
 299         <listitem>
 300                 <para>
 301                         Print debugging statements showing the steps &xmlcatalog; is executing.
 302                 </para>
 303         </listitem>
 304                 </varlistentry>
 305
 306                 <varlistentry>
 307         <term><option>del <replaceable>VALUE(S)</replaceable></option></term>
 308         <listitem>
 309                 <para>
 310                         Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
 311                 </para>
 312         </listitem>
 313                 </varlistentry>
 314
 315                 <varlistentry>
 316         <term><option>dump</option></term>
 317         <listitem>
 318                 <para>Print the current catalog.</para>
 319         </listitem>
 320                 </varlistentry>
 321
 322                 <varlistentry>
 323         <term><option>exit</option></term>
 324         <listitem>
 325                 <para>Quit the shell.</para>
 326         </listitem>
 327                 </varlistentry>
 328
 329                 <varlistentry>
 330         <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
 331         <listitem>
 332                 <para>
 333                         Execute a Formal Public Identifier lookup of the catalog entry
 334                         for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
 335                         output to the command line.
 336                 </para>
 337         </listitem>
 338                 </varlistentry>
 339
 340                 <varlistentry>
 341         <term><option>quiet</option></term>
 342         <listitem>
 343                 <para>Stop printing debugging statements.</para>
 344         </listitem>
 345                 </varlistentry>
 346
 347                 <varlistentry>
 348         <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
 349         <listitem>
 350                 <para>
 351                         Execute a Formal Public Identifier lookup of the catalog entry
 352                         for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
 353                         output to the command line.
 354                 </para>
 355         </listitem>
 356                 </varlistentry>
 357
 358         </variablelist>
 359 </refsect1>
 360
 361 <refsect1 id="environment">
 362         <title>ENVIRONMENT</title>
 363         <variablelist>
 364
 365                 <varlistentry>
 366         <term><envar>XML_CATALOG_FILES</envar></term>
 367         <listitem>
 368                 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
 369                         queries to the user's own set of catalogs. This can be done by setting
 370                         the <envar>XML_CATALOG_FILES</envar> environment variable to a list
 371                         of catalogs. An empty one should deactivate loading the
 372                         default <filename>/etc/xml/catalog</filename> catalog.
 373                 </para>
 374         </listitem>
 375                 </varlistentry>
 376
 377         </variablelist>
 378 </refsect1>
 379
 380 <refsect1 id="diagnostics">
 381         <title>DIAGNOSTICS</title>
 382         <para>
 383                 &xmlcatalog; return codes provide information that can be used when
 384                 calling it from scripts.
 385         </para>
 386         <variablelist>
 387
 388                 <varlistentry>
 389         <term><errorcode>0</errorcode></term>
 390         <listitem>
 391                 <para>No error</para>
 392         </listitem>
 393                 </varlistentry>
 394
 395                 <varlistentry>
 396         <term><errorcode>1</errorcode></term>
 397         <listitem>
 398                 <para>Failed to remove an entry from the catalog</para>
 399         </listitem>
 400                 </varlistentry>
 401
 402                 <varlistentry>
 403         <term><errorcode>2</errorcode></term>
 404         <listitem>
 405                 <para>Failed to save to the catalog, check file permissions</para>
 406         </listitem>
 407                 </varlistentry>
 408
 409                 <varlistentry>
 410         <term><errorcode>3</errorcode></term>
 411         <listitem>
 412                 <para>Failed to add an entry to the catalog</para>
 413         </listitem>
 414                 </varlistentry>
 415
 416                 <varlistentry>
 417         <term><errorcode>4</errorcode></term>
 418         <listitem>
 419                 <para>Failed to look up an entry in the catalog</para>
 420         </listitem>
 421                 </varlistentry>
 422
 423         </variablelist>
 424 </refsect1>
 425
 426 <refsect1 id="seealso">
 427         <title>SEE ALSO</title>
 428         <para><citerefentry>
 429                         <refentrytitle>libxml</refentrytitle>
 430                         <manvolnum>3</manvolnum>
 431                 </citerefentry>
 432         </para>
 433         <para>
 434                 More information can be found at
 435                 <itemizedlist>
 436                         <listitem>
 437                                 <para><citerefentry>
 438                                                 <refentrytitle>libxml</refentrytitle>
 439                                                 <manvolnum>3</manvolnum>
 440                                         </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
 441                                 </para>
 442                         </listitem>
 443                         <listitem>
 444                                 <para><citerefentry>
 445                                                 <refentrytitle>libxml</refentrytitle>
 446                                                 <manvolnum>3</manvolnum>
 447                                         </citerefentry> catalog support web page
 448                                         at <ulink url="http://www.xmlsoft.org/catalog.html"/>
 449                                 </para>
 450                         </listitem>
 451                         <listitem>
 452                                 <para>James Clark's <acronym>SGML</acronym> catalog
 453                                         page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
 454                                 </para>
 455                         </listitem>
 456                         <listitem>
 457                                 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
 458                                         <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
 459                                 </para>
 460                         </listitem>
 461                 </itemizedlist>
 462         </para>
 463 </refsect1>
 464
 465 </refentry>