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: 2006-08-21 10:34:11 +0200 (Mon, 21 Aug 2006) $</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> 447