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>rewriteSystem</parameter></member>
 122                                 <member><parameter>rewriteURI</parameter></member>
 123                                 <member><parameter>delegatePublic</parameter></member>
 124                                 <member><parameter>delegateSystem</parameter></member>
 125                                 <member><parameter>nextCatalog</parameter></member>
 126                         </simplelist>. <replaceable>ORIG</replaceable> is the original
 127                         reference to be replaced, and <replaceable>REPLACE</replaceable>
 128                         is the <acronym>URI</acronym> of the replacement entity to be
 129                         used. The <option>--add</option> option will not overwrite
 130                         <filename>CATALOGFILE</filename>, outputting
 131                         to <filename class="devicefile">stdout</filename>, unless
 132                         <option>--noout</option> is used. The <option>--add</option> will
 133                         always take three parameters even if some of the <acronym>XML</acronym>
 134                         catalog constructs will have only a single argument.
 135                 </para>
 136                 <!--
 137                         FIXME - Is my list of possible types correct? Are SGML types the same?
 138                 -->
 139         </listitem>
 140                 </varlistentry>
 141
 142                 <varlistentry>
 143         <term><option>--add <replaceable>FILENAME</replaceable></option></term>
 144         <listitem>
 145                 <para>
 146                         If the <option>--add</option> option is used following
 147                         the <option>--sgml</option> option, only a single argument,
 148                         a <replaceable>FILENAME</replaceable>, is used. This is used to add
 149                         the name of a catalog file to an <acronym>SGML</acronym> supercatalog,
 150                         a file that contains references to other included <acronym>SGML</acronym>
 151                         catalog files.
 152                 </para>
 153         </listitem>
 154                 </varlistentry>
 155
 156                 <varlistentry>
 157         <term><option>--create</option></term>
 158         <listitem>
 159                 <para>
 160                         Create a new <acronym>XML</acronym> catalog. Outputs
 161                         to <filename class="devicefile">stdout</filename>,
 162                         ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is
 163                         used, in which case it creates a new catalog
 164                         file <replaceable>filename</replaceable>.
 165                 </para>
 166         </listitem>
 167                 </varlistentry>
 168
 169                 <varlistentry>
 170         <term><option>--del <replaceable>VALUE(S)</replaceable></option></term>
 171         <listitem>
 172                 <para>
 173                         Remove entries from <replaceable>CATALOGFILE</replaceable>
 174                         matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option>
 175                         option will not overwrite <replaceable>CATALOGFILE</replaceable>,
 176                         outputting to <filename class="devicefile">stdout</filename>,
 177                         unless <option>--noout</option> is used.
 178                 </para>
 179         </listitem>
 180                 </varlistentry>
 181
 182                 <varlistentry>
 183         <term><option>--noout</option></term>
 184         <listitem>
 185                 <para>
 186                         Save output to the named file rather than outputting
 187                         to <filename class="devicefile">stdout</filename>.
 188                 </para>
 189         </listitem>
 190                 </varlistentry>
 191
 192                 <varlistentry>
 193         <term><option>--no-super-update</option></term>
 194         <listitem>
 195                 <para>
 196                         Do not update the <acronym>SGML</acronym> super catalog.
 197                 </para>
 198         </listitem>
 199                 </varlistentry>
 200
 201                 <varlistentry>
 202         <term><option>--shell</option></term>
 203         <listitem>
 204                 <para>
 205                         Run a shell allowing interactive queries on catalog
 206                         file <replaceable>CATALOGFILE</replaceable>. For the set of available
 207                         commands see <xref linkend="shell"/>.
 208                 </para>
 209         </listitem>
 210                 </varlistentry>
 211
 212                 <varlistentry>
 213         <term><option>--sgml</option></term>
 214         <listitem>
 215                 <para>
 216                         Uses <acronym>SGML</acronym> super catalogs for <option>--add</option>
 217                         and <option>--del</option> options.
 218                 </para>
 219         </listitem>
 220                 </varlistentry>
 221
 222                 <varlistentry>
 223         <term><option>-v</option></term>
 224         <term><option>--verbose</option></term>
 225         <listitem>
 226                 <para>Output debugging information.</para>
 227         </listitem>
 228                 </varlistentry>
 229
 230         </variablelist>
 231 </refsect1>
 232
 233 <refsect1 id="shell">
 234         <title>SHELL COMMANDS</title>
 235         <para>
 236                 Invoking &xmlcatalog; with
 237                 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
 238                 a command line shell allowing interactive access to the catalog file
 239                 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
 240                 provides a command line prompt after which the following commands (described in
 241                 alphabetical order) can be entered.
 242         </para>
 243
 244         <variablelist>
 245
 246                 <varlistentry>
 247         <term>
 248                 <option>add
 249                  <replaceable>TYPE</replaceable>
 250                  <replaceable>ORIG</replaceable>
 251                  <replaceable>REPLACE</replaceable>
 252                 </option>
 253         </term>
 254         <listitem>
 255                 <para>
 256                         Add an entry to the catalog file. <replaceable>TYPE</replaceable>
 257                         indicates the type of entry. Possible types are: <simplelist type="inline">
 258                                 <member><parameter>public</parameter></member>
 259                                 <member><parameter>system</parameter></member>
 260                                 <member><parameter>rewriteSystem</parameter></member>
 261                                 <member><parameter>rewriteURI</parameter></member>
 262                                 <member><parameter>delegatePublic</parameter></member>
 263                                 <member><parameter>delegateSystem</parameter></member>
 264                                 <member><parameter>nextCatalog</parameter></member>
 265                         </simplelist>. <replaceable>ORIG</replaceable> is the original
 266                         reference to be replaced, and <replaceable>REPLACE</replaceable>
 267                         is the <acronym>URI</acronym> of the replacement entity to be
 268                         used. The <option>--add</option> option will not overwrite
 269                         <filename>CATALOGFILE</filename>, outputting
 270                         to <filename class="devicefile">stdout</filename>, unless
 271                         <option>--noout</option> is used. The <option>--add</option> will
 272                         always take three parameters even if some of the <acronym>XML</acronym>
 273                         catalog constructs will have only a single argument.
 274                 </para>
 275         </listitem>
 276                 </varlistentry>
 277
 278                 <varlistentry>
 279         <term><option>debug</option></term>
 280         <listitem>
 281                 <para>
 282                         Print debugging statements showing the steps &xmlcatalog; is executing.
 283                 </para>
 284         </listitem>
 285                 </varlistentry>
 286
 287                 <varlistentry>
 288         <term><option>del <replaceable>VALUE(S)</replaceable></option></term>
 289         <listitem>
 290                 <para>
 291                         Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
 292                 </para>
 293         </listitem>
 294                 </varlistentry>
 295
 296                 <varlistentry>
 297         <term><option>dump</option></term>
 298         <listitem>
 299                 <para>Print the current catalog.</para>
 300         </listitem>
 301                 </varlistentry>
 302
 303                 <varlistentry>
 304         <term><option>exit</option></term>
 305         <listitem>
 306                 <para>Quit the shell.</para>
 307         </listitem>
 308                 </varlistentry>
 309
 310                 <varlistentry>
 311         <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
 312         <listitem>
 313                 <para>
 314                         Execute a Formal Public Identifier look-up of the catalog entry
 315                         for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
 316                         output to the command line.
 317                 </para>
 318         </listitem>
 319                 </varlistentry>
 320
 321                 <varlistentry>
 322         <term><option>quiet</option></term>
 323         <listitem>
 324                 <para>Stop printing debugging statements.</para>
 325         </listitem>
 326                 </varlistentry>
 327
 328                 <varlistentry>
 329         <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
 330         <listitem>
 331                 <para>
 332                         Execute a Formal Public Identifier look-up of the catalog entry
 333                         for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
 334                         output to the command line.
 335                 </para>
 336         </listitem>
 337                 </varlistentry>
 338
 339         </variablelist>
 340 </refsect1>
 341
 342 <refsect1 id="environment">
 343         <title>ENVIRONMENT</title>
 344         <variablelist>
 345
 346                 <varlistentry>
 347         <term><envar>XML_CATALOG_FILES</envar></term>
 348         <listitem>
 349                 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
 350                         queries to the user's own set of catalogs. This can be done by setting
 351                         the <envar>XML_CATALOG_FILES</envar> environment variable to a list
 352                         of catalogs. An empty one should deactivate loading the
 353                         default <filename>/etc/xml/catalog</filename> catalog.
 354                 </para>
 355         </listitem>
 356                 </varlistentry>
 357
 358         </variablelist>
 359 </refsect1>
 360
 361 <refsect1 id="diagnostics">
 362         <title>DIAGNOSTICS</title>
 363         <para>
 364                 &xmlcatalog; return codes provide information that can be used when
 365                 calling it from scripts.
 366         </para>
 367         <variablelist>
 368
 369                 <varlistentry>
 370         <term><errorcode>0</errorcode></term>
 371         <listitem>
 372                 <para>No error</para>
 373         </listitem>
 374                 </varlistentry>
 375
 376                 <varlistentry>
 377         <term><errorcode>1</errorcode></term>
 378         <listitem>
 379                 <para>Failed to remove an entry from the catalog</para>
 380         </listitem>
 381                 </varlistentry>
 382
 383                 <varlistentry>
 384         <term><errorcode>2</errorcode></term>
 385         <listitem>
 386                 <para>Failed to save to the catalog, check file permissions</para>
 387         </listitem>
 388                 </varlistentry>
 389
 390                 <varlistentry>
 391         <term><errorcode>3</errorcode></term>
 392         <listitem>
 393                 <para>Failed to add an entry to the catalog</para>
 394         </listitem>
 395                 </varlistentry>
 396
 397                 <varlistentry>
 398         <term><errorcode>4</errorcode></term>
 399         <listitem>
 400                 <para>Failed to look up an entry in the catalog</para>
 401         </listitem>
 402                 </varlistentry>
 403
 404         </variablelist>
 405 </refsect1>
 406
 407 <refsect1 id="seealso">
 408         <title>SEE ALSO</title>
 409         <para><citerefentry>
 410                         <refentrytitle>libxml</refentrytitle>
 411                         <manvolnum>3</manvolnum>
 412                 </citerefentry>
 413         </para>
 414         <para>
 415                 More information can be found at
 416                 <itemizedlist>
 417                         <listitem>
 418                                 <para><citerefentry>
 419                                                 <refentrytitle>libxml</refentrytitle>
 420                                                 <manvolnum>3</manvolnum>
 421                                         </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
 422                                 </para>
 423                         </listitem>
 424                         <listitem>
 425                                 <para><citerefentry>
 426                                                 <refentrytitle>libxml</refentrytitle>
 427                                                 <manvolnum>3</manvolnum>
 428                                         </citerefentry> catalog support web page
 429                                         at <ulink url="http://www.xmlsoft.org/catalog.html"/>
 430                                 </para>
 431                         </listitem>
 432                         <listitem>
 433                                 <para>James Clark's <acronym>SGML</acronym> catalog
 434                                         page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
 435                                 </para>
 436                         </listitem>
 437                         <listitem>
 438                                 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
 439                                         <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
 440                                 </para>
 441                         </listitem>
 442                 </itemizedlist>
 443         </para>
 444 </refsect1>
 445
 446 </refentry>