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 (a] 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 "" 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> 466
