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>[email protected]</email> 25 </address> 26 </affiliation> 27 </author> 28 <!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this --> 29 <!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> --> 30 <!-- <edition>0.3</edition> --> 31</refentryinfo> 32 33<refmeta> 34 <refentrytitle>xmlcatalog</refentrytitle> 35 <manvolnum>1</manvolnum> 36</refmeta> 37 38<refnamediv> 39 <refname>xmlcatalog</refname> 40 <refpurpose> 41 Command line tool to parse and manipulate <acronym>XML</acronym> 42 or <acronym>SGML</acronym> catalog files. 43 </refpurpose> 44</refnamediv> 45 46<refsynopsisdiv> 47 <cmdsynopsis> 48 <command>xmlcatalog</command> 49 <group choice="opt"> 50 <arg choice="plain"><option>--sgml</option></arg> 51 <arg choice="plain"><option>--shell</option></arg> 52 <arg choice="plain"><option>--convert</option></arg> 53 <arg choice="plain"><option>--create</option></arg> 54 <arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg> 55 <arg choice="plain"> 56 <group choice="opt"> 57 <arg choice="plain"> 58 <option>--add 59 <replaceable>TYPE</replaceable> 60 <replaceable>ORIG</replaceable> 61 <replaceable>REPLACE</replaceable> 62 </option> 63 </arg> 64 <arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg> 65 </group> 66 </arg> 67 <arg choice="plain"><option>--noout</option></arg> 68 <arg choice="plain"><option>--no-super-update</option></arg> 69 <arg choice="plain"> 70 <group choice="opt"> 71 <arg choice="plain"><option>-v</option></arg> 72 <arg choice="plain"><option>--verbose</option></arg> 73 </group> 74 </arg> 75 </group> 76 <arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg> 77 <arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg> 78 </cmdsynopsis> 79</refsynopsisdiv> 80 81<refsect1 id="description"> 82 <title>DESCRIPTION</title> 83 <para> 84 &xmlcatalog; is a command line application allowing users to monitor and 85 manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It 86 is included in <citerefentry> 87 <refentrytitle>libxml</refentrytitle> 88 <manvolnum>3</manvolnum> 89 </citerefentry>. 90 </para> 91 <para> 92 Its functions can be invoked from a single command from the command line, 93 or it can perform multiple functions in interactive mode. It can operate 94 on both <acronym>XML</acronym> and <acronym>SGML</acronym> files. 95 </para> 96</refsect1> 97 98<refsect1 id="options"> 99 <title>OPTIONS</title> 100 <para> 101 &xmlcatalog; accepts the following options (in alphabetical order): 102 </para> 103 104 <variablelist> 105 106 <varlistentry> 107 <term> 108 <option>--add 109 <replaceable>TYPE</replaceable> 110 <replaceable>ORIG</replaceable> 111 <replaceable>REPLACE</replaceable> 112 </option> 113 </term> 114 <listitem> 115 <para> 116 Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable> 117 indicates the type of entry. Possible types are: <simplelist type="inline"> 118 <member><parameter>public</parameter></member> 119 <member><parameter>system</parameter></member> 120 <member><parameter>uri</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>delegateURI</parameter></member> 126 <member><parameter>nextCatalog</parameter></member> 127 </simplelist>. <replaceable>ORIG</replaceable> is the original 128 reference to be replaced, and <replaceable>REPLACE</replaceable> 129 is the <acronym>URI</acronym> of the replacement entity to be 130 used. The <option>--add</option> option will not overwrite 131 <filename>CATALOGFILE</filename>, outputting 132 to <filename class="devicefile">stdout</filename>, unless 133 <option>--noout</option> is used. The <option>--add</option> will 134 always take three parameters even if some of the <acronym>XML</acronym> 135 catalog constructs will have only a single argument. 136 </para> 137 <!-- 138 FIXME - Is my list of possible types correct? Are SGML types the same? 139 --> 140 </listitem> 141 </varlistentry> 142 143 <varlistentry> 144 <term><option>--add <replaceable>FILENAME</replaceable></option></term> 145 <listitem> 146 <para> 147 If the <option>--add</option> option is used following 148 the <option>--sgml</option> option, only a single argument, 149 a <replaceable>FILENAME</replaceable>, is used. This is used to add 150 the name of a catalog file to an <acronym>SGML</acronym> supercatalog, 151 a file that contains references to other included <acronym>SGML</acronym> 152 catalog files. 153 </para> 154 </listitem> 155 </varlistentry> 156 157 <varlistentry> 158 <term><option>--convert</option></term> 159 <listitem> 160 <para> 161 Convert SGML catalog to XML. 162 </para> 163 </listitem> 164 </varlistentry> 165 166 <varlistentry> 167 <term><option>--create</option></term> 168 <listitem> 169 <para> 170 Create a new <acronym>XML</acronym> catalog. Outputs 171 to <filename class="devicefile">stdout</filename>, 172 ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is 173 used, in which case it creates a new catalog 174 file <replaceable>filename</replaceable>. 175 </para> 176 </listitem> 177 </varlistentry> 178 179 <varlistentry> 180 <term><option>--del <replaceable>VALUE(S)</replaceable></option></term> 181 <listitem> 182 <para> 183 Remove entries from <replaceable>CATALOGFILE</replaceable> 184 matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option> 185 option will not overwrite <replaceable>CATALOGFILE</replaceable>, 186 outputting to <filename class="devicefile">stdout</filename>, 187 unless <option>--noout</option> is used. 188 </para> 189 </listitem> 190 </varlistentry> 191 192 <varlistentry> 193 <term><option>--noout</option></term> 194 <listitem> 195 <para> 196 Save output to the named file rather than outputting 197 to <filename class="devicefile">stdout</filename>. 198 </para> 199 </listitem> 200 </varlistentry> 201 202 <varlistentry> 203 <term><option>--no-super-update</option></term> 204 <listitem> 205 <para> 206 Do not update the <acronym>SGML</acronym> super catalog. 207 </para> 208 </listitem> 209 </varlistentry> 210 211 <varlistentry> 212 <term><option>--shell</option></term> 213 <listitem> 214 <para> 215 Run a shell allowing interactive queries on catalog 216 file <replaceable>CATALOGFILE</replaceable>. For the set of available 217 commands see <xref linkend="shell"/>. 218 </para> 219 </listitem> 220 </varlistentry> 221 222 <varlistentry> 223 <term><option>--sgml</option></term> 224 <listitem> 225 <para> 226 Uses <acronym>SGML</acronym> super catalogs for <option>--add</option> 227 and <option>--del</option> options. 228 </para> 229 </listitem> 230 </varlistentry> 231 232 <varlistentry> 233 <term><option>-v</option></term> 234 <term><option>--verbose</option></term> 235 <listitem> 236 <para>Output debugging information.</para> 237 </listitem> 238 </varlistentry> 239 240 </variablelist> 241 242 <para> 243 Invoking &xmlcatalog; non-interactively without a designated action 244 (imposed with options like <option>--add</option>) will result in a lookup 245 of the catalog entry for <replaceable>ENTITIES</replaceable> in the 246 catalog denoted with <replaceable>CATALOGFILE</replaceable>. The 247 corresponding entries will be output to the command line. This mode of 248 operation, together with <option>--shell</option> mode and non-modifying 249 (i.e. without <option>--noout</option>) direct actions, allows for 250 a special shortcut of the void <replaceable>CATALOGFILE</replaceable> 251 specification (possibly expressed as "" in the shell 252 environment) appointing the default system catalog. That simplifies the 253 handling when its exact location is irrelevant but the respective built-in 254 still needs to be consulted. 255 </para> 256</refsect1> 257 258<refsect1 id="shell"> 259 <title>SHELL COMMANDS</title> 260 <para> 261 Invoking &xmlcatalog; with 262 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens 263 a command line shell allowing interactive access to the catalog file 264 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell 265 provides a command line prompt after which the following commands (described in 266 alphabetical order) can be entered. 267 </para> 268 269 <variablelist> 270 271 <varlistentry> 272 <term> 273 <option>add 274 <replaceable>TYPE</replaceable> 275 <replaceable>ORIG</replaceable> 276 <replaceable>REPLACE</replaceable> 277 </option> 278 </term> 279 <listitem> 280 <para> 281 Add an entry to the catalog file. <replaceable>TYPE</replaceable> 282 indicates the type of entry. Possible types are: <simplelist type="inline"> 283 <member><parameter>public</parameter></member> 284 <member><parameter>system</parameter></member> 285 <member><parameter>uri</parameter></member> 286 <member><parameter>rewriteSystem</parameter></member> 287 <member><parameter>rewriteURI</parameter></member> 288 <member><parameter>delegatePublic</parameter></member> 289 <member><parameter>delegateSystem</parameter></member> 290 <member><parameter>delegateURI</parameter></member> 291 <member><parameter>nextCatalog</parameter></member> 292 </simplelist>. <replaceable>ORIG</replaceable> is the original 293 reference to be replaced, and <replaceable>REPLACE</replaceable> 294 is the <acronym>URI</acronym> of the replacement entity to be 295 used. The <option>--add</option> option will not overwrite 296 <filename>CATALOGFILE</filename>, outputting 297 to <filename class="devicefile">stdout</filename>, unless 298 <option>--noout</option> is used. The <option>--add</option> will 299 always take three parameters even if some of the <acronym>XML</acronym> 300 catalog constructs will have only a single argument. 301 </para> 302 </listitem> 303 </varlistentry> 304 305 <varlistentry> 306 <term><option>debug</option></term> 307 <listitem> 308 <para> 309 Print debugging statements showing the steps &xmlcatalog; is executing. 310 </para> 311 </listitem> 312 </varlistentry> 313 314 <varlistentry> 315 <term><option>del <replaceable>VALUE(S)</replaceable></option></term> 316 <listitem> 317 <para> 318 Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>. 319 </para> 320 </listitem> 321 </varlistentry> 322 323 <varlistentry> 324 <term><option>dump</option></term> 325 <listitem> 326 <para>Print the current catalog.</para> 327 </listitem> 328 </varlistentry> 329 330 <varlistentry> 331 <term><option>exit</option></term> 332 <listitem> 333 <para>Quit the shell.</para> 334 </listitem> 335 </varlistentry> 336 337 <varlistentry> 338 <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term> 339 <listitem> 340 <para> 341 Execute a Formal Public Identifier lookup of the catalog entry 342 for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be 343 output to the command line. 344 </para> 345 </listitem> 346 </varlistentry> 347 348 <varlistentry> 349 <term><option>quiet</option></term> 350 <listitem> 351 <para>Stop printing debugging statements.</para> 352 </listitem> 353 </varlistentry> 354 355 <varlistentry> 356 <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term> 357 <listitem> 358 <para> 359 Execute a Formal Public Identifier lookup of the catalog entry 360 for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be 361 output to the command line. 362 </para> 363 </listitem> 364 </varlistentry> 365 366 </variablelist> 367</refsect1> 368 369<refsect1 id="environment"> 370 <title>ENVIRONMENT</title> 371 <variablelist> 372 373 <varlistentry> 374 <term><envar>XML_CATALOG_FILES</envar></term> 375 <listitem> 376 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting 377 queries to the user's own set of catalogs. This can be done by setting 378 the <envar>XML_CATALOG_FILES</envar> environment variable to a space-separated 379 list of catalogs. Use percent-encoding to escape spaces or other characters. 380 An empty variable should deactivate loading the default catalog from 381 <filename>/etc/xml/catalog</filename> or, more specifically, 382 <filename>${sysconfdir}/xml/catalog</filename>. 383 </para> 384 </listitem> 385 </varlistentry> 386 387 </variablelist> 388</refsect1> 389 390<refsect1 id="diagnostics"> 391 <title>DIAGNOSTICS</title> 392 <para> 393 &xmlcatalog; return codes provide information that can be used when 394 calling it from scripts. 395 </para> 396 <variablelist> 397 398 <varlistentry> 399 <term><errorcode>0</errorcode></term> 400 <listitem> 401 <para>No error</para> 402 </listitem> 403 </varlistentry> 404 405 <varlistentry> 406 <term><errorcode>1</errorcode></term> 407 <listitem> 408 <para>Failed to remove an entry from the catalog</para> 409 </listitem> 410 </varlistentry> 411 412 <varlistentry> 413 <term><errorcode>2</errorcode></term> 414 <listitem> 415 <para>Failed to save to the catalog, check file permissions</para> 416 </listitem> 417 </varlistentry> 418 419 <varlistentry> 420 <term><errorcode>3</errorcode></term> 421 <listitem> 422 <para>Failed to add an entry to the catalog</para> 423 </listitem> 424 </varlistentry> 425 426 <varlistentry> 427 <term><errorcode>4</errorcode></term> 428 <listitem> 429 <para>Failed to look up an entry in the catalog</para> 430 </listitem> 431 </varlistentry> 432 433 </variablelist> 434</refsect1> 435 436<refsect1 id="seealso"> 437 <title>SEE ALSO</title> 438 <para><citerefentry> 439 <refentrytitle>libxml</refentrytitle> 440 <manvolnum>3</manvolnum> 441 </citerefentry> 442 </para> 443 <para> 444 More information can be found at 445 <itemizedlist> 446 <listitem> 447 <para><citerefentry> 448 <refentrytitle>libxml</refentrytitle> 449 <manvolnum>3</manvolnum> 450 </citerefentry> web page <ulink url="https://gitlab.gnome.org/GNOME/libxml2"/> 451 </para> 452 </listitem> 453 <listitem> 454 <para><citerefentry> 455 <refentrytitle>libxml</refentrytitle> 456 <manvolnum>3</manvolnum> 457 </citerefentry> catalog support web page 458 at <ulink url="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support"/> 459 </para> 460 </listitem> 461 <listitem> 462 <para>James Clark's <acronym>SGML</acronym> catalog 463 page <ulink url="http://www.jclark.com/sp/catalog.htm"/> 464 </para> 465 </listitem> 466 <listitem> 467 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification 468 <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/> 469 </para> 470 </listitem> 471 </itemizedlist> 472 </para> 473</refsect1> 474 475</refentry> 476