path: root/doc/xmlcatalog.1

.\" ** You probably do not want to edit this file directly **
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
.TH "XMLCATALOG" "1" "2006\-03\-05" "libxml2" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
xmlcatalog \- Command line tool to parse and manipulate XML or SGML catalog files.
.SH "SYNOPSIS"
.HP 11
\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...}
.SH "DESCRIPTION"
.PP
\fBxmlcatalog\fR
is a command line application allowing users to monitor and manipulate
XML
and
SGML
catalogs. It is included in
\fBlibxml\fR(3).
.PP
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
XML
and
SGML
files.
.PP
More information can be found at
.TP 3
\(bu
\fBlibxml\fR(3)
web page
\fI\%http://www.xmlsoft.org/\fR
.TP
\(bu
\fBlibxml\fR(3)
catalog support web page at
\fI\%http://www.xmlsoft.org/catalog.html\fR
.TP
\(bu
James Clark's
SGML
catalog page
\fI\%http://www.jclark.com/sp/catalog.htm\fR
.TP
\(bu
OASISXML
catalog specification
\fI\%http://www.oasis\-open.org/committees/entity/spec.html\fR
.SH "OPTIONS"
.PP
\fBxmlcatalog\fR
accepts the following options (in alphabetical order):
.TP
\fB\-\-add \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR
Add an entry to
\fICATALOGFILE\fR.
\fITYPE\fR
indicates the type of entry. Possible types are:
\fIpublic\fR, \fIsystem\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fInextCatalog\fR.
\fIORIG\fR
is the original reference to be replaced, and
\fIREPLACE\fR
is the
URI
of the replacement entity to be used. The
\fB\-\-add\fR
option will not overwrite
\fICATALOGFILE\fR, outputting to
\fIstdout\fR, unless
\fB\-\-noout\fR
is used. The
\fB\-\-add\fR
will always take three parameters even if some of the
XML
catalog constructs will have only a single argument.
.TP
\fB\-\-add \fR\fB\fIFILENAME\fR\fR
If the
\fB\-\-add\fR
option is used following the
\fB\-\-sgml\fR
option, only a single argument, a
\fIFILENAME\fR, is used. This is used to add the name of a catalog file to an
SGML
supercatalog, a file that contains references to other included
SGML
catalog files.
.TP
\fB\-\-create\fR
Create a new
XML
catalog. Outputs to
\fIstdout\fR, ignoring
\fIfilename\fR
unless
\fB\-\-noout\fR
is used, in which case it creates a new catalog file
\fIfilename\fR.
.TP
\fB\-\-del \fR\fB\fIVALUE(S)\fR\fR
Remove entries from
\fICATALOGFILE\fR
matching
\fIVALUE(S)\fR. The
\fB\-\-del\fR
option will not overwrite
\fICATALOGFILE\fR, outputting to
\fIstdout\fR, unless
\fB\-\-noout\fR
is used.
.TP
\fB\-\-noout\fR
Save output to the named file rather than outputting to
\fIstdout\fR.
.TP
\fB\-\-no\-super\-update\fR
Do not update the
SGML
super catalog.
.TP
\fB\-\-shell\fR
Run a shell allowing interactive queries on catalog file
\fICATALOGFILE\fR. For the set of available commands see
the section called \(lqSHELL COMMANDS\(rq.
.TP
\fB\-\-sgml\fR
Uses
SGML
super catalogs for
\fB\-\-add\fR
and
\fB\-\-del\fR
options.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Output debugging information.
.SH "SHELL COMMANDS"
.PP
Invoking
\fBxmlcatalog\fR
with the
\fB\-\-shell \fR\fB\fICATALOGFILE\fR\fR
option opens a command line shell allowing interactive access to the catalog file identified by
\fICATALOGFILE\fR. Invoking the shell provides a command line prompt after which the following commands (described in alphabetical order) can be entered.
.TP
\fBadd \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR
Add an entry to the catalog file.
\fITYPE\fR
indicates the type of entry. Possible types are:
\fIpublic\fR, \fIsystem\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fInextCatalog\fR.
\fIORIG\fR
is the original reference to be replaced, and
\fIREPLACE\fR
is the
URI
of the replacement entity to be used. The
\fB\-\-add\fR
option will not overwrite
\fICATALOGFILE\fR, outputting to
\fIstdout\fR, unless
\fB\-\-noout\fR
is used. The
\fB\-\-add\fR
will always take three parameters even if some of the
XML
catalog constructs will have only a single argument.
.TP
\fBdebug\fR
Print debugging statements showing the steps
\fBxmlcatalog\fR
is executing.
.TP
\fBdel \fR\fB\fIVALUE(S)\fR\fR
Remove the catalog entry corresponding to
\fIVALUE(S)\fR.
.TP
\fBdump\fR
Print the current catalog.
.TP
\fBexit\fR
Quit the shell.
.TP
\fBpublic \fR\fB\fIPUBLIC\-ID\fR\fR
Execute a public identifier lookup of the catalog entry for
\fIPUBLIC\-ID\fR. The corresponding entry will be output to the command line.
.TP
\fBquiet\fR
Stop printing debugging statements.
.TP
\fBsystem \fR\fB\fISYSTEM\-ID\fR\fR
Execute a public identifier lookup of the catalog entry for
\fISYSTEM\-ID\fR. The corresponding entry will be output to the command line.
.SH "ENVIRONMENT"
.TP
\fBXML_CATALOG_FILES\fR
Catalog behavior can be changed by redirecting queries to the user's own set of catalogs. This can be done by setting the
\fBXML_CATALOG_FILES\fR
environment variable to a list of catalogs. An empty one should deactivate loading the default
\fI/etc/xml/catalog\fR
default catalog.
.SH "DIAGNOSTICS"
.PP
\fBxmlcatalog\fR's return codes provide information that can be used when calling it from scripts.
.TP
\fB0\fR
No error
.TP
\fB1\fR
Failed to remove an entry from the catalog
.TP
\fB2\fR
Failed to save to the catalog, check file permissions
.TP
\fB3\fR
Failed to add an entry to the catalog
.TP
\fB4\fR
Failed to lookup an entry in the catalog
.SH "SEE ALSO"
.PP
\fBlibxml\fR(3)
.SH "AUTHOR"
John Fleck <jfleck@inkstain.net>.