MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 1 | <?xml version="1.0"?> |
Daniel Veillard | fd58341 | 2003-04-25 13:22:10 +0000 | [diff] [blame] | 2 | <?xml-stylesheet type="text/xsl" |
| 3 | href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 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 | <refentry> |
| 8 | <refentryinfo> |
| 9 | <title>xmlcatalog Manual</title> |
| 10 | <copyright> |
| 11 | <year>2001</year> |
| 12 | </copyright> |
| 13 | <author> |
| 14 | <firstname>John</firstname> |
| 15 | <surname>Fleck</surname> |
| 16 | </author> |
| 17 | <address><email>jfleck@inkstain.net</email></address> |
MST 2001 John Fleck | 3fc555e | 2001-12-11 04:41:24 +0000 | [diff] [blame] | 18 | |
| 19 | <releaseinfo>This is release 0.2 of the xmlcatalog Manual.</releaseinfo> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 20 | </refentryinfo> |
| 21 | |
| 22 | <refmeta> |
| 23 | <refentrytitle>xmlcatalog</refentrytitle> |
| 24 | <manvolnum>1</manvolnum> |
| 25 | </refmeta> |
| 26 | <refnamediv> |
| 27 | <refname>xmlcatalog</refname> |
| 28 | <refpurpose>Command line tool to parse and manipulate <acronym>XML</acronym> or |
| 29 | <acronym>SGML</acronym> catalog files.</refpurpose> |
| 30 | </refnamediv> |
| 31 | |
| 32 | <refsynopsisdiv> |
| 33 | <cmdsynopsis> |
| 34 | <command>xmlcatalog</command> |
| 35 | <group> |
| 36 | <arg>--shell</arg> |
| 37 | <arg>--create</arg> |
| 38 | <arg>--add <replaceable>type</replaceable> |
| 39 | <replaceable>orig</replaceable> <replaceable>replace</replaceable></arg> |
| 40 | <arg>--del <replaceable>values</replaceable></arg> |
| 41 | <arg>--noout</arg> |
| 42 | <arg>--verbose</arg> |
| 43 | </group> |
| 44 | <arg><option><replaceable>catalogfile</replaceable></option></arg> |
| 45 | <arg><option><replaceable>entities</replaceable></option></arg> |
| 46 | </cmdsynopsis> |
| 47 | </refsynopsisdiv> |
| 48 | |
| 49 | <refsect1 id="introduction"> |
| 50 | <title>Introduction</title> |
| 51 | <para> |
| 52 | <application>xmlcatalog</application> is a command line application |
| 53 | allowing users to monitor and manipulate <acronym>XML</acronym> and |
| 54 | <acronym>SGML</acronym> catalogs. It is included in |
| 55 | <application>libxml2</application>. |
| 56 | </para> |
| 57 | |
| 58 | <para> |
| 59 | Its functions can be invoked from a single command from the command line, |
| 60 | or it can perform multiple functions in interactive mode. It can operate |
| 61 | on both <acronym>XML</acronym> and <acronym>SGML</acronym> files. |
| 62 | </para> |
| 63 | </refsect1> |
| 64 | |
| 65 | <refsect1 id="cloptions"> |
| 66 | <title>Command Line Options</title> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 67 | <variablelist> |
| 68 | <varlistentry> |
| 69 | <term><option>--shell</option> <replaceable>filename</replaceable></term> |
| 70 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 71 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 72 | Run a shell |
| 73 | allowing interactive queries on catalog file |
| 74 | <replaceable>filename</replaceable>. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 75 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 76 | </listitem> |
| 77 | </varlistentry> |
| 78 | <varlistentry> |
| 79 | <term><option>--create</option> <replaceable>filename</replaceable></term> |
| 80 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 81 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 82 | Create a new |
| 83 | <acronym>XML</acronym> catalog. Outputs to stdout, ignoring |
| 84 | <replaceable>filename</replaceable> unless <option>--noout</option> is |
| 85 | used, in which case it creates a new catalog file |
| 86 | <replaceable>filename</replaceable>. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 87 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 88 | </listitem> |
| 89 | </varlistentry> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 90 | |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 91 | <varlistentry> |
| 92 | <term><option>--add</option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable> <replaceable>filename</replaceable></term> |
| 93 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 94 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 95 | Add an entry to catalog file |
MST 2003 John Fleck | 937362d | 2003-01-27 00:04:32 +0000 | [diff] [blame] | 96 | <filename>filename</filename>. <replaceable>type</replaceable> |
| 97 | indicates the type of entry. Possible types are 'public', 'system', |
| 98 | 'rewriteSystem', 'delegatePublic', 'delegateSystem'amd |
| 99 | 'rewriteURI'. <replaceable>'orig'</replaceable> is the original |
| 100 | reference to be replaced, and <replaceable>'replace'</replaceable> |
| 101 | is the <acronym>URI</acronym> of the replacement entity to be |
| 102 | used. The <option>--add</option> option will not overwrite |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 103 | <replaceable>filename</replaceable>, outputing to stdout, unless |
MST 2003 John Fleck | 937362d | 2003-01-27 00:04:32 +0000 | [diff] [blame] | 104 | <option>--noout</option> is used. The <option>--add</option> will |
| 105 | always take three parameters even if some of the |
| 106 | <acronym>XML</acronym> catalog constructs will have only a single |
| 107 | argument. |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 108 | <!-- |
| 109 | FIXME - Is my list of possible types correct? Are SGML types the same? |
| 110 | --> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 111 | </simpara> |
MDT 2001 John Fleck | 60416fa | 2001-10-09 02:41:50 +0000 | [diff] [blame] | 112 | <simpara> |
| 113 | If the <option>--add</option> option is used following the |
| 114 | <option>--sgml</option> option, only a single argument, a |
| 115 | <replaceable>filename</replaceable>, is used. This is used to add |
| 116 | the name of a catalog file to an <acronym>SGML</acronym> |
| 117 | supercatalog, a file that contains references to other included |
| 118 | <acronym>SGML</acronym> catalog files. |
| 119 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 120 | </listitem> |
| 121 | </varlistentry> |
| 122 | <varlistentry> |
| 123 | <term><option>--del</option> <replaceable>'values'</replaceable> <replaceable>filename</replaceable></term> |
| 124 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 125 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 126 | Remove entries from the catalog file |
| 127 | <replaceable>filename</replaceable> matching |
| 128 | <replaceable>'values'</replaceable>. The <option>--del</option> option |
| 129 | will not overwrite <replaceable>filename</replaceable>, outputing to |
| 130 | stdout, unless <option>--noout</option> is used. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 131 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 132 | </listitem> |
| 133 | </varlistentry> |
| 134 | <varlistentry> |
| 135 | <term><option>--noout</option></term> |
| 136 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 137 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 138 | Save output to the named file rather than |
| 139 | outputing to stdout. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 140 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 141 | </listitem> |
| 142 | </varlistentry> |
| 143 | <varlistentry> |
Daniel Veillard | 0351754 | 2002-02-11 13:54:40 +0000 | [diff] [blame] | 144 | <term><option>--sgml</option></term> |
| 145 | <listitem> |
| 146 | <simpara> |
| 147 | Uses SGML Super catalogs for --add and --del options |
| 148 | </simpara> |
| 149 | </listitem> |
| 150 | </varlistentry> |
| 151 | <varlistentry> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 152 | <term><option>-v</option> or <option>--verbose</option></term> |
| 153 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 154 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 155 | output debugging |
| 156 | information. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 157 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 158 | </listitem> |
| 159 | </varlistentry> |
| 160 | </variablelist> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 161 | </refsect1> |
| 162 | |
| 163 | <refsect1 id="shell"> |
| 164 | <title>Shell Commands</title> |
| 165 | <para>Invoking <application>xmlcatalog</application> with the |
| 166 | <option>--shell</option> <replaceable>filename</replaceable> option opens |
| 167 | a command line shell allowing interactive access to the catalog file |
| 168 | identified by <replaceable>filename</replaceable>. Invoking the shell |
| 169 | provides a command line prompt after which commands can be entered. |
| 170 | </para> |
| 171 | |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 172 | <variablelist> |
| 173 | <varlistentry> |
| 174 | <term><option>public</option> <replaceable>'PublicID'</replaceable></term> |
| 175 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 176 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 177 | Execute a |
| 178 | public identifier lookup of the catalog entry for |
| 179 | <replaceable>'PublicID'</replaceable>. The corresponding entry will be |
| 180 | output to the command line. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 181 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 182 | </listitem> |
| 183 | </varlistentry> |
| 184 | |
| 185 | <varlistentry> |
| 186 | <term><option>system</option> <replaceable>'SystemID'</replaceable></term> |
| 187 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 188 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 189 | Execute a |
| 190 | public identifier lookup of the catalog entry for |
| 191 | <replaceable>'SystemID'</replaceable>. The corresponding entry will be |
| 192 | output to the command line. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 193 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 194 | </listitem> |
| 195 | </varlistentry> |
| 196 | <varlistentry> |
| 197 | <term><option>add </option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable></term> |
| 198 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 199 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 200 | Add an entry to the catalog |
| 201 | file. <replaceable>type</replaceable> indicates the type of |
| 202 | entry. Possible types are 'public', 'system', 'rewriteSystem', |
| 203 | 'delegatePublic' and 'delegateSystem'. <replaceable>'orig'</replaceable> |
| 204 | is the original reference to be replaced, and |
| 205 | <replaceable>'replace'</replaceable> is the <acronym>URI</acronym> of the |
| 206 | replacement entity to be used. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 207 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 208 | </listitem> |
| 209 | </varlistentry> |
| 210 | <varlistentry> |
| 211 | <term><option>del</option> <replaceable>'values'</replaceable></term> |
| 212 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 213 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 214 | Remove the |
| 215 | catalog entry corresponding to <replaceable>'values'</replaceable>. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 216 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 217 | </listitem> |
| 218 | </varlistentry> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 219 | |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 220 | <varlistentry> |
| 221 | <term><option>dump</option></term> |
| 222 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 223 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 224 | Print the current catalog. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 225 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 226 | </listitem> |
| 227 | </varlistentry> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 228 | |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 229 | <varlistentry> |
| 230 | <term><option>debug</option></term> |
| 231 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 232 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 233 | Print debugging statements showing the steps |
| 234 | <application>xmlcatalog</application> is executing. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 235 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 236 | </listitem> |
| 237 | </varlistentry> |
| 238 | |
| 239 | <varlistentry> |
| 240 | <term><option>quiet</option></term> |
| 241 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 242 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 243 | Stop printing debugging statements. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 244 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 245 | </listitem> |
| 246 | </varlistentry> |
| 247 | |
| 248 | <varlistentry> |
| 249 | <term><option>exit</option></term> |
| 250 | <listitem> |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 251 | <simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 252 | Quit the shell. |
MDT 2001 John Fleck | 0e22993 | 2001-10-07 22:46:00 +0000 | [diff] [blame] | 253 | </simpara> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 254 | </listitem> |
| 255 | </varlistentry> |
| 256 | </variablelist> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 257 | |
| 258 | </refsect1> |
| 259 | |
Daniel Veillard | 0f5f162 | 2002-01-20 12:42:06 +0000 | [diff] [blame] | 260 | <refsect1 id="return"> |
| 261 | <title>Return values</title> |
| 262 | <para><application>xmlcatalog</application>'s return codes provide |
| 263 | information that can be used when calling it from scripts.</para> |
| 264 | |
| 265 | <para>0: normal</para> |
| 266 | <para>1: Failed to remove an entry from the catalog</para> |
| 267 | <para>2: Failed to save to the catalog, check file permissions</para> |
| 268 | <para>3: Failed to add an entry to the catalog</para> |
| 269 | <para>4: Failed to lookup and entry in the catalog</para> |
| 270 | </refsect1> |
| 271 | |
MST 2001 John Fleck | 3fc555e | 2001-12-11 04:41:24 +0000 | [diff] [blame] | 272 | <refsect1> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 273 | <title>References</title> |
MST 2001 John Fleck | 3fc555e | 2001-12-11 04:41:24 +0000 | [diff] [blame] | 274 | <para><ulink url="http://www.xmlsoft.org/">libxml web page</ulink></para> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 275 | |
MST 2001 John Fleck | 3fc555e | 2001-12-11 04:41:24 +0000 | [diff] [blame] | 276 | <para><ulink url="http://www.xmlsoft.org/catalog.html"><application>libxml</application> |
| 277 | catalog support web page:</ulink></para> |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 278 | |
MST 2001 John Fleck | 3fc555e | 2001-12-11 04:41:24 +0000 | [diff] [blame] | 279 | <para><ulink url="http://www.jclark.com/sp/catalog.htm">James Clark's |
| 280 | <acronym>SGML</acronym> catalog page:</ulink></para> |
| 281 | |
| 282 | <para><ulink |
| 283 | url="http://www.oasis-open.org/committees/entity/spec.html"><acronym>OASIS</acronym> |
| 284 | <acronym>XML</acronym> catalog specification: </ulink></para> |
| 285 | </refsect1> |
MDT 2001 John Fleck | ac941e3 | 2001-10-06 22:30:16 +0000 | [diff] [blame] | 286 | |
MDT 2001 John Fleck | 5bd39dc | 2001-09-03 15:14:19 +0000 | [diff] [blame] | 287 | |
Daniel Veillard | 0f5f162 | 2002-01-20 12:42:06 +0000 | [diff] [blame] | 288 | </refentry> |