xmlcatalog_man.xml revision bf95fd2390eaee24fdf9661343d2551c97237ef4
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>2006-03-05</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 <para>More information can be found at 98 <itemizedlist> 99 <listitem> 100 <para><citerefentry> 101 <refentrytitle>libxml</refentrytitle> 102 <manvolnum>3</manvolnum> 103 </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/> 104 </para> 105 </listitem> 106 <listitem> 107 <para><citerefentry> 108 <refentrytitle>libxml</refentrytitle> 109 <manvolnum>3</manvolnum> 110 </citerefentry> catalog support web page 111 at <ulink url="http://www.xmlsoft.org/catalog.html"/> 112 </para> 113 </listitem> 114 <listitem> 115 <para>James Clark's <acronym>SGML</acronym> catalog 116 page <ulink url="http://www.jclark.com/sp/catalog.htm"/> 117 </para> 118 </listitem> 119 <listitem> 120 <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification 121 <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/> 122 </para> 123 </listitem> 124 </itemizedlist> 125 </para> 126</refsect1> 127 128<refsect1 id="options"> 129 <title>OPTIONS</title> 130 <para> 131 &xmlcatalog; accepts the following options (in alphabetical order): 132 </para> 133 134 <variablelist> 135 136 <varlistentry> 137 <term> 138 <option>--add 139 <replaceable>TYPE</replaceable> 140 <replaceable>ORIG</replaceable> 141 <replaceable>REPLACE</replaceable> 142 </option> 143 </term> 144 <listitem> 145 <para> 146 Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable> 147 indicates the type of entry. Possible types are: <simplelist type="inline"> 148 <member><parameter>public</parameter></member> 149 <member><parameter>system</parameter></member> 150 <member><parameter>rewriteSystem</parameter></member> 151 <member><parameter>rewriteURI</parameter></member> 152 <member><parameter>delegatePublic</parameter></member> 153 <member><parameter>delegateSystem</parameter></member> 154 <member><parameter>nextCatalog</parameter></member> 155 </simplelist>. <replaceable>ORIG</replaceable> is the original 156 reference to be replaced, and <replaceable>REPLACE</replaceable> 157 is the <acronym>URI</acronym> of the replacement entity to be 158 used. The <option>--add</option> option will not overwrite 159 <filename>CATALOGFILE</filename>, outputting 160 to <filename class="devicefile">stdout</filename>, unless 161 <option>--noout</option> is used. The <option>--add</option> will 162 always take three parameters even if some of the <acronym>XML</acronym> 163 catalog constructs will have only a single argument. 164 </para> 165 <!-- 166 FIXME - Is my list of possible types correct? Are SGML types the same? 167 --> 168 </listitem> 169 </varlistentry> 170 171 <varlistentry> 172 <term><option>--add <replaceable>FILENAME</replaceable></option></term> 173 <listitem> 174 <para> 175 If the <option>--add</option> option is used following 176 the <option>--sgml</option> option, only a single argument, 177 a <replaceable>FILENAME</replaceable>, is used. This is used to add 178 the name of a catalog file to an <acronym>SGML</acronym> supercatalog, 179 a file that contains references to other included <acronym>SGML</acronym> 180 catalog files. 181 </para> 182 </listitem> 183 </varlistentry> 184 185 <varlistentry> 186 <term><option>--create</option></term> 187 <listitem> 188 <para> 189 Create a new <acronym>XML</acronym> catalog. Outputs 190 to <filename class="devicefile">stdout</filename>, 191 ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is 192 used, in which case it creates a new catalog 193 file <replaceable>filename</replaceable>. 194 </para> 195 </listitem> 196 </varlistentry> 197 198 <varlistentry> 199 <term><option>--del <replaceable>VALUE(S)</replaceable></option></term> 200 <listitem> 201 <para> 202 Remove entries from <replaceable>CATALOGFILE</replaceable> 203 matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option> 204 option will not overwrite <replaceable>CATALOGFILE</replaceable>, 205 outputting to <filename class="devicefile">stdout</filename>, 206 unless <option>--noout</option> is used. 207 </para> 208 </listitem> 209 </varlistentry> 210 211 <varlistentry> 212 <term><option>--noout</option></term> 213 <listitem> 214 <para> 215 Save output to the named file rather than outputting 216 to <filename class="devicefile">stdout</filename>. 217 </para> 218 </listitem> 219 </varlistentry> 220 221 <varlistentry> 222 <term><option>--no-super-update</option></term> 223 <listitem> 224 <para> 225 Do not update the <acronym>SGML</acronym> super catalog. 226 </para> 227 </listitem> 228 </varlistentry> 229 230 <varlistentry> 231 <term><option>--shell</option></term> 232 <listitem> 233 <para> 234 Run a shell allowing interactive queries on catalog 235 file <replaceable>CATALOGFILE</replaceable>. 236 </para> 237 </listitem> 238 </varlistentry> 239 240 <varlistentry> 241 <term><option>--sgml</option></term> 242 <listitem> 243 <para> 244 Uses <acronym>SGML</acronym> super catalogs for <option>--add</option> 245 and <option>--del</option> options. 246 </para> 247 </listitem> 248 </varlistentry> 249 250 <varlistentry> 251 <term><option>-v</option></term> 252 <term><option>--verbose</option></term> 253 <listitem> 254 <para>Output debugging information.</para> 255 </listitem> 256 </varlistentry> 257 258 </variablelist> 259</refsect1> 260 261<refsect1 id="shell"> 262 <title>SHELL COMMANDS</title> 263 <para> 264 Invoking &xmlcatalog; with 265 the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens 266 a command line shell allowing interactive access to the catalog file 267 identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell 268 provides a command line prompt after which the following commands (described in 269 alphabetical order) can be entered. 270 </para> 271 272 <variablelist> 273 274 <varlistentry> 275 <term> 276 <option>add 277 <replaceable>TYPE</replaceable> 278 <replaceable>ORIG</replaceable> 279 <replaceable>REPLACE</replaceable> 280 </option> 281 </term> 282 <listitem> 283 <para> 284 Add an entry to the catalog file. <replaceable>TYPE</replaceable> 285 indicates the type of entry. Possible types are: <simplelist type="inline"> 286 <member><parameter>public</parameter></member> 287 <member><parameter>system</parameter></member> 288 <member><parameter>rewriteSystem</parameter></member> 289 <member><parameter>rewriteURI</parameter></member> 290 <member><parameter>delegatePublic</parameter></member> 291 <member><parameter>delegateSystem</parameter></member> 292 <member><parameter>nextCatalog</parameter></member> 293 </simplelist>. <replaceable>ORIG</replaceable> is the original 294 reference to be replaced, and <replaceable>REPLACE</replaceable> 295 is the <acronym>URI</acronym> of the replacement entity to be 296 used. The <option>--add</option> option will not overwrite 297 <filename>CATALOGFILE</filename>, outputting 298 to <filename class="devicefile">stdout</filename>, unless 299 <option>--noout</option> is used. The <option>--add</option> will 300 always take three parameters even if some of the <acronym>XML</acronym> 301 catalog constructs will have only a single argument. 302 </para> 303 </listitem> 304 </varlistentry> 305 306 <varlistentry> 307 <term><option>debug</option></term> 308 <listitem> 309 <para> 310 Print debugging statements showing the steps &xmlcatalog; is executing. 311 </para> 312 </listitem> 313 </varlistentry> 314 315 <varlistentry> 316 <term><option>del <replaceable>VALUE(S)</replaceable></option></term> 317 <listitem> 318 <para> 319 Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>. 320 </para> 321 </listitem> 322 </varlistentry> 323 324 <varlistentry> 325 <term><option>dump</option></term> 326 <listitem> 327 <para>Print the current catalog.</para> 328 </listitem> 329 </varlistentry> 330 331 <varlistentry> 332 <term><option>exit</option></term> 333 <listitem> 334 <para>Quit the shell.</para> 335 </listitem> 336 </varlistentry> 337 338 <varlistentry> 339 <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term> 340 <listitem> 341 <para> 342 Execute a public identifier lookup of the catalog entry 343 for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be 344 output to the command line. 345 </para> 346 </listitem> 347 </varlistentry> 348 349 <varlistentry> 350 <term><option>quiet</option></term> 351 <listitem> 352 <para>Stop printing debugging statements.</para> 353 </listitem> 354 </varlistentry> 355 356 <varlistentry> 357 <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term> 358 <listitem> 359 <para> 360 Execute a public identifier lookup of the catalog entry 361 for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be 362 output to the command line. 363 </para> 364 </listitem> 365 </varlistentry> 366 367 </variablelist> 368</refsect1> 369 370<refsect1 id="environment"> 371 <title>ENVIRONMENT</title> 372 <variablelist> 373 374 <varlistentry> 375 <term><envar>XML_CATALOG_FILES</envar></term> 376 <listitem> 377 <para> 378 Catalog behavior can be changed by redirecting queries to the user's 379 own set of catalogs. This can be done by setting 380 the <envar>XML_CATALOG_FILES</envar> environment variable to a list 381 of catalogs. An empty one should deactivate loading the 382 default <filename>/etc/xml/catalog</filename> default catalog. 383 </para> 384 </listitem> 385 </varlistentry> 386 387 </variablelist> 388</refsect1> 389 390<refsect1 id="diagnostics"> 391 <title>DIAGNOSTICS</title> 392 <para> 393 &xmlcatalog;'s return codes provide information that can be used when 394 calling it from scripts. 395 </para> 396 <segmentedlist> 397 <!-- <title>Error codes</title> --> 398 <segtitle>Errorcode</segtitle> 399 <segtitle>Error</segtitle> 400 <seglistitem> 401 <seg><errorcode>0</errorcode></seg> 402 <seg>No error</seg> 403 </seglistitem> 404 <seglistitem> 405 <seg><errorcode>1</errorcode></seg> 406 <seg>Failed to remove an entry from the catalog</seg> 407 </seglistitem> 408 <seglistitem> 409 <seg><errorcode>2</errorcode></seg> 410 <seg>Failed to save to the catalog, check file permissions</seg> 411 </seglistitem> 412 <seglistitem> 413 <seg><errorcode>3</errorcode></seg> 414 <seg>Failed to add an entry to the catalog</seg> 415 </seglistitem> 416 <seglistitem> 417 <seg><errorcode>4</errorcode></seg> 418 <seg>Failed to lookup and entry in the catalog</seg> 419 </seglistitem> 420 </segmentedlist> 421</refsect1> 422 423<refsect1 id="seealso"> 424 <title>SEE ALSO</title> 425 <para> 426 <citerefentry> 427 <refentrytitle>libxml</refentrytitle> 428 <manvolnum>3</manvolnum> 429 </citerefentry> 430 </para> 431</refsect1> 432 433</refentry> 434