release/src/router/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     <!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 </refsect1>
 234
 235 <refsect1 id="shell">
 236         <title>SHELL COMMANDS</title>
 237         <para>
 238                 Invoking &xmlcatalog; with
 239                 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
 240                 a command line shell allowing interactive access to the catalog file
 241                 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
 242                 provides a command line prompt after which the following commands (described in
 243                 alphabetical order) can be entered.
 244         </para>
 245
 246         <variablelist>
 247
 248                 <varlistentry>
 249         <term>
 250                 <option>add
 251                  <replaceable>TYPE</replaceable>
 252                  <replaceable>ORIG</replaceable>
 253                  <replaceable>REPLACE</replaceable>
 254                 </option>
 255         </term>
 256         <listitem>
 257                 <para>
 258                         Add an entry to the catalog file. <replaceable>TYPE</replaceable>
 259                         indicates the type of entry. Possible types are: <simplelist type="inline">
 260                                 <member><parameter>public</parameter></member>
 261                                 <member><parameter>system</parameter></member>
 262                                 <member><parameter>uri</parameter></member>
 263                                 <member><parameter>rewriteSystem</parameter></member>
 264                                 <member><parameter>rewriteURI</parameter></member>
 265                                 <member><parameter>delegatePublic</parameter></member>
 266                                 <member><parameter>delegateSystem</parameter></member>
 267                                 <member><parameter>delegateURI</parameter></member>
 268                                 <member><parameter>nextCatalog</parameter></member>
 269                         </simplelist>. <replaceable>ORIG</replaceable> is the original
 270                         reference to be replaced, and <replaceable>REPLACE</replaceable>
 271                         is the <acronym>URI</acronym> of the replacement entity to be
 272                         used. The <option>--add</option> option will not overwrite
 273                         <filename>CATALOGFILE</filename>, outputting
 274                         to <filename class="devicefile">stdout</filename>, unless
 275                         <option>--noout</option> is used. The <option>--add</option> will
 276                         always take three parameters even if some of the <acronym>XML</acronym>
 277                         catalog constructs will have only a single argument.
 278                 </para>
 279         </listitem>
 280                 </varlistentry>
 281
 282                 <varlistentry>
 283         <term><option>debug</option></term>
 284         <listitem>
 285                 <para>
 286                         Print debugging statements showing the steps &xmlcatalog; is executing.
 287                 </para>
 288         </listitem>
 289                 </varlistentry>
 290
 291                 <varlistentry>
 292         <term><option>del <replaceable>VALUE(S)</replaceable></option></term>
 293         <listitem>
 294                 <para>
 295                         Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
 296                 </para>
 297         </listitem>
 298                 </varlistentry>
 299
 300                 <varlistentry>
 301         <term><option>dump</option></term>
 302         <listitem>
 303                 <para>Print the current catalog.</para>
 304         </listitem>
 305                 </varlistentry>
 306
 307                 <varlistentry>
 308         <term><option>exit</option></term>
 309         <listitem>
 310                 <para>Quit the shell.</para>
 311         </listitem>
 312                 </varlistentry>
 313
 314                 <varlistentry>
 315         <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
 316         <listitem>
 317                 <para>
 318                         Execute a Formal Public Identifier look-up of the catalog entry
 319                         for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
 320                         output to the command line.
 321                 </para>
 322         </listitem>
 323                 </varlistentry>
 324
 325                 <varlistentry>
 326         <term><option>quiet</option></term>
 327         <listitem>
 328                 <para>Stop printing debugging statements.</para>
 329         </listitem>
 330                 </varlistentry>
 331
 332                 <varlistentry>
 333         <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
 334         <listitem>
 335                 <para>
 336                         Execute a Formal Public Identifier look-up of the catalog entry
 337                         for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
 338                         output to the command line.
 339                 </para>
 340         </listitem>
 341                 </varlistentry>
 342
 343         </variablelist>
 344 </refsect1>
 345
 346 <refsect1 id="environment">
 347         <title>ENVIRONMENT</title>
 348         <variablelist>
 349
 350                 <varlistentry>
 351         <term><envar>XML_CATALOG_FILES</envar></term>
 352         <listitem>
 353                 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
 354                         queries to the user's own set of catalogs. This can be done by setting
 355                         the <envar>XML_CATALOG_FILES</envar> environment variable to a list
 356                         of catalogs. An empty one should deactivate loading the
 357                         default <filename>/etc/xml/catalog</filename> catalog.
 358                 </para>
 359         </listitem>
 360                 </varlistentry>
 361
 362         </variablelist>
 363 </refsect1>
 364
 365 <refsect1 id="diagnostics">
 366         <title>DIAGNOSTICS</title>
 367         <para>
 368                 &xmlcatalog; return codes provide information that can be used when
 369                 calling it from scripts.
 370         </para>
 371         <variablelist>
 372
 373                 <varlistentry>
 374         <term><errorcode>0</errorcode></term>
 375         <listitem>
 376                 <para>No error</para>
 377         </listitem>
 378                 </varlistentry>
 379
 380                 <varlistentry>
 381         <term><errorcode>1</errorcode></term>
 382         <listitem>
 383                 <para>Failed to remove an entry from the catalog</para>
 384         </listitem>
 385                 </varlistentry>
 386
 387                 <varlistentry>
 388         <term><errorcode>2</errorcode></term>
 389         <listitem>
 390                 <para>Failed to save to the catalog, check file permissions</para>
 391         </listitem>
 392                 </varlistentry>
 393
 394                 <varlistentry>
 395         <term><errorcode>3</errorcode></term>
 396         <listitem>
 397                 <para>Failed to add an entry to the catalog</para>
 398         </listitem>
 399                 </varlistentry>
 400
 401                 <varlistentry>
 402         <term><errorcode>4</errorcode></term>
 403         <listitem>
 404                 <para>Failed to look up an entry in the catalog</para>
 405         </listitem>
 406                 </varlistentry>
 407
 408         </variablelist>
 409 </refsect1>
 410
 411 <refsect1 id="seealso">
 412         <title>SEE ALSO</title>
 413         <para><citerefentry>
 414                         <refentrytitle>libxml</refentrytitle>
 415                         <manvolnum>3</manvolnum>
 416                 </citerefentry>
 417         </para>
 418         <para>
 419                 More information can be found at
 420                 <itemizedlist>
 421                         <listitem>
 422                                 <para><citerefentry>
 423                                                 <refentrytitle>libxml</refentrytitle>
 424                                                 <manvolnum>3</manvolnum>
 425                                         </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
 426                                 </para>
 427                         </listitem>
 428                         <listitem>
 429                                 <para><citerefentry>
 430                                                 <refentrytitle>libxml</refentrytitle>
 431                                                 <manvolnum>3</manvolnum>
 432                                         </citerefentry> catalog support web page
 433                                         at <ulink url="http://www.xmlsoft.org/catalog.html"/>
 434                                 </para>
 435                         </listitem>
 436                         <listitem>
 437                                 <para>James Clark's <acronym>SGML</acronym> catalog
 438                                         page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
 439                                 </para>
 440                         </listitem>
 441                         <listitem>
 442                                 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
 443                                         <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
 444                                 </para>
 445                         </listitem>
 446                 </itemizedlist>
 447         </para>
 448 </refsect1>
 449
 450 </refentry>