doc/xmlcatalog.1

   1 '\" t
   2 .\"     Title: xmlcatalog
   3 .\"    Author: John Fleck <jfleck@inkstain.net>
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: $Date$
   6 .\"    Manual: xmlcatalog Manual
   7 .\"    Source: libxml2
   8 .\"  Language: English
   9 .\"
  10 .TH "XMLCATALOG" "1" "$Date$" "libxml2" "xmlcatalog Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 xmlcatalog \- Command line tool to parse and manipulate XML or SGML catalog files\&.
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBxmlcatalog\fR\ 'u
  34 \fBxmlcatalog\fR [\fB\-\-sgml\fR | \fB\-\-shell\fR | \fB\-\-create\fR | \fB\-\-del\ \fR\fB\fIVALUE(S)\fR\fR | [\ \fB\-\-add\ \fR\fB\fITYPE\fR\fR\fB\ \fR\fB\fIORIG\fR\fR\fB\ \fR\fB\fIREPLACE\fR\fR\fB\ \fR\ |\ \fB\-\-add\ \fR\fB\fIFILENAME\fR\fR] | \fB\-\-noout\fR | \fB\-\-no\-super\-update\fR | [\fB\-v\fR\ |\ \fB\-\-verbose\fR]] {\fICATALOGFILE\fR} {\fIENTITIES\fR...}
  35 .SH "DESCRIPTION"
  36 .PP
  37 \fBxmlcatalog\fR
  38 is a command line application allowing users to monitor and manipulate
  39 XML
  40 and
  41 SGML
  42 catalogs\&. It is included in
  43 \fBlibxml\fR(3)\&.
  44 .PP
  45 Its functions can be invoked from a single command from the command line, or it can perform multiple functions in interactive mode\&. It can operate on both
  46 XML
  47 and
  48 SGML
  49 files\&.
  50 .SH "OPTIONS"
  51 .PP
  52 \fBxmlcatalog\fR
  53 accepts the following options (in alphabetical order):
  54 .PP
  55 \fB\-\-add \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR
  56 .RS 4
  57 Add an entry to
  58 CATALOGFILE\&.
  59 \fITYPE\fR
  60 indicates the type of entry\&. Possible types are:
  61 \fIpublic\fR, \fIsystem\fR, \fIuri\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fIdelegateURI\fR, \fInextCatalog\fR\&.
  62 \fIORIG\fR
  63 is the original reference to be replaced, and
  64 \fIREPLACE\fR
  65 is the
  66 URI
  67 of the replacement entity to be used\&. The
  68 \fB\-\-add\fR
  69 option will not overwrite
  70 CATALOGFILE, outputting to
  71 stdout, unless
  72 \fB\-\-noout\fR
  73 is used\&. The
  74 \fB\-\-add\fR
  75 will always take three parameters even if some of the
  76 XML
  77 catalog constructs will have only a single argument\&.
  78 .RE
  79 .PP
  80 \fB\-\-add \fR\fB\fIFILENAME\fR\fR
  81 .RS 4
  82 If the
  83 \fB\-\-add\fR
  84 option is used following the
  85 \fB\-\-sgml\fR
  86 option, only a single argument, a
  87 \fIFILENAME\fR, is used\&. This is used to add the name of a catalog file to an
  88 SGML
  89 supercatalog, a file that contains references to other included
  90 SGML
  91 catalog files\&.
  92 .RE
  93 .PP
  94 \fB\-\-create\fR
  95 .RS 4
  96 Create a new
  97 XML
  98 catalog\&. Outputs to
  99 stdout, ignoring
 100 \fIfilename\fR
 101 unless
 102 \fB\-\-noout\fR
 103 is used, in which case it creates a new catalog file
 104 \fIfilename\fR\&.
 105 .RE
 106 .PP
 107 \fB\-\-del \fR\fB\fIVALUE(S)\fR\fR
 108 .RS 4
 109 Remove entries from
 110 \fICATALOGFILE\fR
 111 matching
 112 \fIVALUE(S)\fR\&. The
 113 \fB\-\-del\fR
 114 option will not overwrite
 115 \fICATALOGFILE\fR, outputting to
 116 stdout, unless
 117 \fB\-\-noout\fR
 118 is used\&.
 119 .RE
 120 .PP
 121 \fB\-\-noout\fR
 122 .RS 4
 123 Save output to the named file rather than outputting to
 124 stdout\&.
 125 .RE
 126 .PP
 127 \fB\-\-no\-super\-update\fR
 128 .RS 4
 129 Do not update the
 130 SGML
 131 super catalog\&.
 132 .RE
 133 .PP
 134 \fB\-\-shell\fR
 135 .RS 4
 136 Run a shell allowing interactive queries on catalog file
 137 \fICATALOGFILE\fR\&. For the set of available commands see
 138 the section called \(lqSHELL COMMANDS\(rq\&.
 139 .RE
 140 .PP
 141 \fB\-\-sgml\fR
 142 .RS 4
 143 Uses
 144 SGML
 145 super catalogs for
 146 \fB\-\-add\fR
 147 and
 148 \fB\-\-del\fR
 149 options\&.
 150 .RE
 151 .PP
 152 \fB\-v\fR, \fB\-\-verbose\fR
 153 .RS 4
 154 Output debugging information\&.
 155 .RE
 156 .PP
 157 Invoking
 158 \fBxmlcatalog\fR
 159 non\-interactively without a designated action (imposed with options like
 160 \fB\-\-add\fR) will result in a lookup of the catalog entry for
 161 \fIENTITIES\fR
 162 in the catalog denoted with
 163 \fICATALOGFILE\fR\&. The corresponding entries will be output to the command line\&. This mode of operation, together with
 164 \fB\-\-shell\fR
 165 mode and non\-modifying (i\&.e\&. without
 166 \fB\-\-noout\fR) direct actions, allows for a special shortcut of the void
 167 \fICATALOGFILE\fR
 168 specification (possibly expressed as "" in the shell environment) appointing the default system catalog\&. That simplifies the handling when its exact location is irrelevant but the respective built\-in still needs to be consulted\&.
 169 .SH "SHELL COMMANDS"
 170 .PP
 171 Invoking
 172 \fBxmlcatalog\fR
 173 with the
 174 \fB\-\-shell \fR\fB\fICATALOGFILE\fR\fR
 175 option opens a command line shell allowing interactive access to the catalog file identified by
 176 \fICATALOGFILE\fR\&. Invoking the shell provides a command line prompt after which the following commands (described in alphabetical order) can be entered\&.
 177 .PP
 178 \fBadd \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR
 179 .RS 4
 180 Add an entry to the catalog file\&.
 181 \fITYPE\fR
 182 indicates the type of entry\&. Possible types are:
 183 \fIpublic\fR, \fIsystem\fR, \fIuri\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fIdelegateURI\fR, \fInextCatalog\fR\&.
 184 \fIORIG\fR
 185 is the original reference to be replaced, and
 186 \fIREPLACE\fR
 187 is the
 188 URI
 189 of the replacement entity to be used\&. The
 190 \fB\-\-add\fR
 191 option will not overwrite
 192 CATALOGFILE, outputting to
 193 stdout, unless
 194 \fB\-\-noout\fR
 195 is used\&. The
 196 \fB\-\-add\fR
 197 will always take three parameters even if some of the
 198 XML
 199 catalog constructs will have only a single argument\&.
 200 .RE
 201 .PP
 202 \fBdebug\fR
 203 .RS 4
 204 Print debugging statements showing the steps
 205 \fBxmlcatalog\fR
 206 is executing\&.
 207 .RE
 208 .PP
 209 \fBdel \fR\fB\fIVALUE(S)\fR\fR
 210 .RS 4
 211 Remove the catalog entry corresponding to
 212 \fIVALUE(S)\fR\&.
 213 .RE
 214 .PP
 215 \fBdump\fR
 216 .RS 4
 217 Print the current catalog\&.
 218 .RE
 219 .PP
 220 \fBexit\fR
 221 .RS 4
 222 Quit the shell\&.
 223 .RE
 224 .PP
 225 \fBpublic \fR\fB\fIPUBLIC\-ID\fR\fR
 226 .RS 4
 227 Execute a Formal Public Identifier lookup of the catalog entry for
 228 \fIPUBLIC\-ID\fR\&. The corresponding entry will be output to the command line\&.
 229 .RE
 230 .PP
 231 \fBquiet\fR
 232 .RS 4
 233 Stop printing debugging statements\&.
 234 .RE
 235 .PP
 236 \fBsystem \fR\fB\fISYSTEM\-ID\fR\fR
 237 .RS 4
 238 Execute a Formal Public Identifier lookup of the catalog entry for
 239 \fISYSTEM\-ID\fR\&. The corresponding entry will be output to the command line\&.
 240 .RE
 241 .SH "ENVIRONMENT"
 242 .PP
 243 \fBXML_CATALOG_FILES\fR
 244 .RS 4
 245 XML
 246 catalog behavior can be changed by redirecting queries to the user\*(Aqs own set of catalogs\&. This can be done by setting the
 247 \fBXML_CATALOG_FILES\fR
 248 environment variable to a list of catalogs\&. An empty one should deactivate loading the default
 249 /etc/xml/catalog
 250 catalog\&.
 251 .RE
 252 .SH "DIAGNOSTICS"
 253 .PP
 254 \fBxmlcatalog\fR
 255 return codes provide information that can be used when calling it from scripts\&.
 256 .PP
 257 \fB0\fR
 258 .RS 4
 259 No error
 260 .RE
 261 .PP
 262 \fB1\fR
 263 .RS 4
 264 Failed to remove an entry from the catalog
 265 .RE
 266 .PP
 267 \fB2\fR
 268 .RS 4
 269 Failed to save to the catalog, check file permissions
 270 .RE
 271 .PP
 272 \fB3\fR
 273 .RS 4
 274 Failed to add an entry to the catalog
 275 .RE
 276 .PP
 277 \fB4\fR
 278 .RS 4
 279 Failed to look up an entry in the catalog
 280 .RE
 281 .SH "SEE ALSO"
 282 .PP
 283 \fBlibxml\fR(3)
 284 .PP
 285 More information can be found at
 286 .sp
 287 .RS 4
 288 .ie n \{\
 289 \h'-04'\(bu\h'+03'\c
 290 .\}
 291 .el \{\
 292 .sp -1
 293 .IP \(bu 2.3
 294 .\}
 295 \fBlibxml\fR(3)
 296 web page
 297 \m[blue]\fB\%http://www.xmlsoft.org/\fR\m[]
 298 .RE
 299 .sp
 300 .RS 4
 301 .ie n \{\
 302 \h'-04'\(bu\h'+03'\c
 303 .\}
 304 .el \{\
 305 .sp -1
 306 .IP \(bu 2.3
 307 .\}
 308 \fBlibxml\fR(3)
 309 catalog support web page at
 310 \m[blue]\fB\%http://www.xmlsoft.org/catalog.html\fR\m[]
 311 .RE
 312 .sp
 313 .RS 4
 314 .ie n \{\
 315 \h'-04'\(bu\h'+03'\c
 316 .\}
 317 .el \{\
 318 .sp -1
 319 .IP \(bu 2.3
 320 .\}
 321 James Clark\*(Aqs
 322 SGML
 323 catalog page
 324 \m[blue]\fB\%http://www.jclark.com/sp/catalog.htm\fR\m[]
 325 .RE
 326 .sp
 327 .RS 4
 328 .ie n \{\
 329 \h'-04'\(bu\h'+03'\c
 330 .\}
 331 .el \{\
 332 .sp -1
 333 .IP \(bu 2.3
 334 .\}
 335 OASIS
 336 XML
 337 catalog specification
 338 \m[blue]\fB\%http://www.oasis-open.org/committees/entity/spec.html\fR\m[]
 339 .RE
 340 .sp
 341 .SH "AUTHOR"
 342 .PP
 343 \fBJohn Fleck\fR <\&jfleck@inkstain\&.net\&>
 344 .RS 4
 345 Author.
 346 .RE
 347 .SH "COPYRIGHT"
 348 .br
 349 Copyright \(co 2001, 2004
 350 .br