Annotation of embedaddon/libxml2/doc/xmlcatalog_man.xml, revision 1.1
1.1 ! misho 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>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>