xmlcatalog_man.xml
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>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 </refsect1> 234 235 <refsect1 id="shell"> 236 <title>SHELL COMMANDS</title> 237 <para> 238 Invoking &xmlcatalog; with 239 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens 240 a command line shell allowing interactive access to the catalog file 241 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell 242 provides a command line prompt after which the following commands (described in 243 alphabetical order) can be entered. 244 </para> 245 246 <variablelist> 247 248 <varlistentry> 249 <term> 250 <option>add 251 <replaceable>TYPE</replaceable> 252 <replaceable>ORIG</replaceable> 253 <replaceable>REPLACE</replaceable> 254 </option> 255 </term> 256 <listitem> 257 <para> 258 Add an entry to the catalog file. <replaceable>TYPE</replaceable> 259 indicates the type of entry. Possible types are: <simplelist type="inline"> 260 <member><parameter>public</parameter></member> 261 <member><parameter>system</parameter></member> 262 <member><parameter>uri</parameter></member> 263 <member><parameter>rewriteSystem</parameter></member> 264 <member><parameter>rewriteURI</parameter></member> 265 <member><parameter>delegatePublic</parameter></member> 266 <member><parameter>delegateSystem</parameter></member> 267 <member><parameter>delegateURI</parameter></member> 268 <member><parameter>nextCatalog</parameter></member> 269 </simplelist>. <replaceable>ORIG</replaceable> is the original 270 reference to be replaced, and <replaceable>REPLACE</replaceable> 271 is the <acronym>URI</acronym> of the replacement entity to be 272 used. The <option>--add</option> option will not overwrite 273 <filename>CATALOGFILE</filename>, outputting 274 to <filename class="devicefile">stdout</filename>, unless 275 <option>--noout</option> is used. The <option>--add</option> will 276 always take three parameters even if some of the <acronym>XML</acronym> 277 catalog constructs will have only a single argument. 278 </para> 279 </listitem> 280 </varlistentry> 281 282 <varlistentry> 283 <term><option>debug</option></term> 284 <listitem> 285 <para> 286 Print debugging statements showing the steps &xmlcatalog; is executing. 287 </para> 288 </listitem> 289 </varlistentry> 290 291 <varlistentry> 292 <term><option>del <replaceable>VALUE(S)</replaceable></option></term> 293 <listitem> 294 <para> 295 Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>. 296 </para> 297 </listitem> 298 </varlistentry> 299 300 <varlistentry> 301 <term><option>dump</option></term> 302 <listitem> 303 <para>Print the current catalog.</para> 304 </listitem> 305 </varlistentry> 306 307 <varlistentry> 308 <term><option>exit</option></term> 309 <listitem> 310 <para>Quit the shell.</para> 311 </listitem> 312 </varlistentry> 313 314 <varlistentry> 315 <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term> 316 <listitem> 317 <para> 318 Execute a Formal Public Identifier look-up of the catalog entry 319 for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be 320 output to the command line. 321 </para> 322 </listitem> 323 </varlistentry> 324 325 <varlistentry> 326 <term><option>quiet</option></term> 327 <listitem> 328 <para>Stop printing debugging statements.</para> 329 </listitem> 330 </varlistentry> 331 332 <varlistentry> 333 <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term> 334 <listitem> 335 <para> 336 Execute a Formal Public Identifier look-up of the catalog entry 337 for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be 338 output to the command line. 339 </para> 340 </listitem> 341 </varlistentry> 342 343 </variablelist> 344 </refsect1> 345 346 <refsect1 id="environment"> 347 <title>ENVIRONMENT</title> 348 <variablelist> 349 350 <varlistentry> 351 <term><envar>XML_CATALOG_FILES</envar></term> 352 <listitem> 353 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting 354 queries to the user's own set of catalogs. This can be done by setting 355 the <envar>XML_CATALOG_FILES</envar> environment variable to a list 356 of catalogs. An empty one should deactivate loading the 357 default <filename>/etc/xml/catalog</filename> catalog. 358 </para> 359 </listitem> 360 </varlistentry> 361 362 </variablelist> 363 </refsect1> 364 365 <refsect1 id="diagnostics"> 366 <title>DIAGNOSTICS</title> 367 <para> 368 &xmlcatalog; return codes provide information that can be used when 369 calling it from scripts. 370 </para> 371 <variablelist> 372 373 <varlistentry> 374 <term><errorcode>0</errorcode></term> 375 <listitem> 376 <para>No error</para> 377 </listitem> 378 </varlistentry> 379 380 <varlistentry> 381 <term><errorcode>1</errorcode></term> 382 <listitem> 383 <para>Failed to remove an entry from the catalog</para> 384 </listitem> 385 </varlistentry> 386 387 <varlistentry> 388 <term><errorcode>2</errorcode></term> 389 <listitem> 390 <para>Failed to save to the catalog, check file permissions</para> 391 </listitem> 392 </varlistentry> 393 394 <varlistentry> 395 <term><errorcode>3</errorcode></term> 396 <listitem> 397 <para>Failed to add an entry to the catalog</para> 398 </listitem> 399 </varlistentry> 400 401 <varlistentry> 402 <term><errorcode>4</errorcode></term> 403 <listitem> 404 <para>Failed to look up an entry in the catalog</para> 405 </listitem> 406 </varlistentry> 407 408 </variablelist> 409 </refsect1> 410 411 <refsect1 id="seealso"> 412 <title>SEE ALSO</title> 413 <para><citerefentry> 414 <refentrytitle>libxml</refentrytitle> 415 <manvolnum>3</manvolnum> 416 </citerefentry> 417 </para> 418 <para> 419 More information can be found at 420 <itemizedlist> 421 <listitem> 422 <para><citerefentry> 423 <refentrytitle>libxml</refentrytitle> 424 <manvolnum>3</manvolnum> 425 </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/> 426 </para> 427 </listitem> 428 <listitem> 429 <para><citerefentry> 430 <refentrytitle>libxml</refentrytitle> 431 <manvolnum>3</manvolnum> 432 </citerefentry> catalog support web page 433 at <ulink url="http://www.xmlsoft.org/catalog.html"/> 434 </para> 435 </listitem> 436 <listitem> 437 <para>James Clark's <acronym>SGML</acronym> catalog 438 page <ulink url="http://www.jclark.com/sp/catalog.htm"/> 439 </para> 440 </listitem> 441 <listitem> 442 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification 443 <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/> 444 </para> 445 </listitem> 446 </itemizedlist> 447 </para> 448 </refsect1> 449 450 </refentry>