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 <!-- 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>--create</option></arg> 53 <arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg> 54 <arg choice="plain"> 55 <group choice="opt"> 56 <arg choice="plain"> 57 <option>--add 58 <replaceable>TYPE</replaceable> 59 <replaceable>ORIG</replaceable> 60 <replaceable>REPLACE</replaceable> 61 </option> 62 </arg> 63 <arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg> 64 </group> 65 </arg> 66 <arg choice="plain"><option>--noout</option></arg> 67 <arg choice="plain"><option>--no-super-update</option></arg> 68 <arg choice="plain"> 69 <group choice="opt"> 70 <arg choice="plain"><option>-v</option></arg> 71 <arg choice="plain"><option>--verbose</option></arg> 72 </group> 73 </arg> 74 </group> 75 <arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg> 76 <arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg> 77 </cmdsynopsis> 78</refsynopsisdiv> 79 80<refsect1 id="description"> 81 <title>DESCRIPTION</title> 82 <para> 83 &xmlcatalog; is a command line application allowing users to monitor and 84 manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It 85 is included in <citerefentry> 86 <refentrytitle>libxml</refentrytitle> 87 <manvolnum>3</manvolnum> 88 </citerefentry>. 89 </para> 90 <para> 91 Its functions can be invoked from a single command from the command line, 92 or it can perform multiple functions in interactive mode. It can operate 93 on both <acronym>XML</acronym> and <acronym>SGML</acronym> files. 94 </para> 95</refsect1> 96 97<refsect1 id="options"> 98 <title>OPTIONS</title> 99 <para> 100 &xmlcatalog; accepts the following options (in alphabetical order): 101 </para> 102 103 <variablelist> 104 105 <varlistentry> 106 <term> 107 <option>--add 108 <replaceable>TYPE</replaceable> 109 <replaceable>ORIG</replaceable> 110 <replaceable>REPLACE</replaceable> 111 </option> 112 </term> 113 <listitem> 114 <para> 115 Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable> 116 indicates the type of entry. Possible types are: <simplelist type="inline"> 117 <member><parameter>public</parameter></member> 118 <member><parameter>system</parameter></member> 119 <member><parameter>uri</parameter></member> 120 <member><parameter>rewriteSystem</parameter></member> 121 <member><parameter>rewriteURI</parameter></member> 122 <member><parameter>delegatePublic</parameter></member> 123 <member><parameter>delegateSystem</parameter></member> 124 <member><parameter>delegateURI</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 232 <para> 233 Invoking &xmlcatalog; non-interactively without a designated action 234 (imposed with options like <option>--add</option>) will result in a lookup 235 of the catalog entry for <replaceable>ENTITIES</replaceable> in the 236 catalog denoted with <replaceable>CATALOGFILE</replaceable>. The 237 corresponding entries will be output to the command line. This mode of 238 operation, together with <option>--shell</option> mode and non-modifying 239 (i.e. without <option>--noout</option>) direct actions, allows for 240 a special shortcut of the void <replaceable>CATALOGFILE</replaceable> 241 specification (possibly expressed as "" in the shell 242 environment) appointing the default system catalog. That simplifies the 243 handling when its exact location is irrelevant but the respective built-in 244 still needs to be consulted. 245 </para> 246</refsect1> 247 248<refsect1 id="shell"> 249 <title>SHELL COMMANDS</title> 250 <para> 251 Invoking &xmlcatalog; with 252 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens 253 a command line shell allowing interactive access to the catalog file 254 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell 255 provides a command line prompt after which the following commands (described in 256 alphabetical order) can be entered. 257 </para> 258 259 <variablelist> 260 261 <varlistentry> 262 <term> 263 <option>add 264 <replaceable>TYPE</replaceable> 265 <replaceable>ORIG</replaceable> 266 <replaceable>REPLACE</replaceable> 267 </option> 268 </term> 269 <listitem> 270 <para> 271 Add an entry to the catalog file. <replaceable>TYPE</replaceable> 272 indicates the type of entry. Possible types are: <simplelist type="inline"> 273 <member><parameter>public</parameter></member> 274 <member><parameter>system</parameter></member> 275 <member><parameter>uri</parameter></member> 276 <member><parameter>rewriteSystem</parameter></member> 277 <member><parameter>rewriteURI</parameter></member> 278 <member><parameter>delegatePublic</parameter></member> 279 <member><parameter>delegateSystem</parameter></member> 280 <member><parameter>delegateURI</parameter></member> 281 <member><parameter>nextCatalog</parameter></member> 282 </simplelist>. <replaceable>ORIG</replaceable> is the original 283 reference to be replaced, and <replaceable>REPLACE</replaceable> 284 is the <acronym>URI</acronym> of the replacement entity to be 285 used. The <option>--add</option> option will not overwrite 286 <filename>CATALOGFILE</filename>, outputting 287 to <filename class="devicefile">stdout</filename>, unless 288 <option>--noout</option> is used. The <option>--add</option> will 289 always take three parameters even if some of the <acronym>XML</acronym> 290 catalog constructs will have only a single argument. 291 </para> 292 </listitem> 293 </varlistentry> 294 295 <varlistentry> 296 <term><option>debug</option></term> 297 <listitem> 298 <para> 299 Print debugging statements showing the steps &xmlcatalog; is executing. 300 </para> 301 </listitem> 302 </varlistentry> 303 304 <varlistentry> 305 <term><option>del <replaceable>VALUE(S)</replaceable></option></term> 306 <listitem> 307 <para> 308 Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>. 309 </para> 310 </listitem> 311 </varlistentry> 312 313 <varlistentry> 314 <term><option>dump</option></term> 315 <listitem> 316 <para>Print the current catalog.</para> 317 </listitem> 318 </varlistentry> 319 320 <varlistentry> 321 <term><option>exit</option></term> 322 <listitem> 323 <para>Quit the shell.</para> 324 </listitem> 325 </varlistentry> 326 327 <varlistentry> 328 <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term> 329 <listitem> 330 <para> 331 Execute a Formal Public Identifier lookup of the catalog entry 332 for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be 333 output to the command line. 334 </para> 335 </listitem> 336 </varlistentry> 337 338 <varlistentry> 339 <term><option>quiet</option></term> 340 <listitem> 341 <para>Stop printing debugging statements.</para> 342 </listitem> 343 </varlistentry> 344 345 <varlistentry> 346 <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term> 347 <listitem> 348 <para> 349 Execute a Formal Public Identifier lookup of the catalog entry 350 for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be 351 output to the command line. 352 </para> 353 </listitem> 354 </varlistentry> 355 356 </variablelist> 357</refsect1> 358 359<refsect1 id="environment"> 360 <title>ENVIRONMENT</title> 361 <variablelist> 362 363 <varlistentry> 364 <term><envar>XML_CATALOG_FILES</envar></term> 365 <listitem> 366 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting 367 queries to the user's own set of catalogs. This can be done by setting 368 the <envar>XML_CATALOG_FILES</envar> environment variable to a space-separated 369 list of catalogs. Use percent-encoding to escape spaces or other characters. 370 An empty variable should deactivate loading the default <filename>/etc/xml/catalog</filename> catalog. 371 </para> 372 </listitem> 373 </varlistentry> 374 375 </variablelist> 376</refsect1> 377 378<refsect1 id="diagnostics"> 379 <title>DIAGNOSTICS</title> 380 <para> 381 &xmlcatalog; return codes provide information that can be used when 382 calling it from scripts. 383 </para> 384 <variablelist> 385 386 <varlistentry> 387 <term><errorcode>0</errorcode></term> 388 <listitem> 389 <para>No error</para> 390 </listitem> 391 </varlistentry> 392 393 <varlistentry> 394 <term><errorcode>1</errorcode></term> 395 <listitem> 396 <para>Failed to remove an entry from the catalog</para> 397 </listitem> 398 </varlistentry> 399 400 <varlistentry> 401 <term><errorcode>2</errorcode></term> 402 <listitem> 403 <para>Failed to save to the catalog, check file permissions</para> 404 </listitem> 405 </varlistentry> 406 407 <varlistentry> 408 <term><errorcode>3</errorcode></term> 409 <listitem> 410 <para>Failed to add an entry to the catalog</para> 411 </listitem> 412 </varlistentry> 413 414 <varlistentry> 415 <term><errorcode>4</errorcode></term> 416 <listitem> 417 <para>Failed to look up an entry in the catalog</para> 418 </listitem> 419 </varlistentry> 420 421 </variablelist> 422</refsect1> 423 424<refsect1 id="seealso"> 425 <title>SEE ALSO</title> 426 <para><citerefentry> 427 <refentrytitle>libxml</refentrytitle> 428 <manvolnum>3</manvolnum> 429 </citerefentry> 430 </para> 431 <para> 432 More information can be found at 433 <itemizedlist> 434 <listitem> 435 <para><citerefentry> 436 <refentrytitle>libxml</refentrytitle> 437 <manvolnum>3</manvolnum> 438 </citerefentry> web page <ulink url="https://gitlab.gnome.org/GNOME/libxml2"/> 439 </para> 440 </listitem> 441 <listitem> 442 <para><citerefentry> 443 <refentrytitle>libxml</refentrytitle> 444 <manvolnum>3</manvolnum> 445 </citerefentry> catalog support web page 446 at <ulink url="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support"/> 447 </para> 448 </listitem> 449 <listitem> 450 <para>James Clark's <acronym>SGML</acronym> catalog 451 page <ulink url="http://www.jclark.com/sp/catalog.htm"/> 452 </para> 453 </listitem> 454 <listitem> 455 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification 456 <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/> 457 </para> 458 </listitem> 459 </itemizedlist> 460 </para> 461</refsect1> 462 463</refentry> 464