'\" t

.\"     Title: xmlcatalog

.\"    Author: John Fleck <jfleck@inkstain.net>

.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>

.\"      Date: $Date$

.\"    Manual: xmlcatalog Manual

.\"    Source: libxml2

.\"  Language: English

.\"

.TH "XMLCATALOG" "1" "$Date$" "libxml2" "xmlcatalog Manual"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

xmlcatalog \- Command line tool to parse and manipulate XML or SGML catalog files\&.

.SH "SYNOPSIS"

.HP \w'\fBxmlcatalog\fR\ 'u

\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\&.

.SH "OPTIONS"

.PP

\fBxmlcatalog\fR

accepts the following options (in alphabetical order):

.PP

\fB\-\-add \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR

.RS 4

Add an entry to

CATALOGFILE\&.

\fITYPE\fR

indicates the type of entry\&. Possible types are:

\fIpublic\fR, \fIsystem\fR, \fIuri\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fIdelegateURI\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

CATALOGFILE, outputting to

stdout, 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\&.

.RE

.PP

\fB\-\-add \fR\fB\fIFILENAME\fR\fR

.RS 4

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\&.

.RE

.PP

\fB\-\-create\fR

.RS 4

Create a new

XML

catalog\&. Outputs to

stdout, ignoring

\fIfilename\fR

unless

\fB\-\-noout\fR

is used, in which case it creates a new catalog file

\fIfilename\fR\&.

.RE

.PP

\fB\-\-del \fR\fB\fIVALUE(S)\fR\fR

.RS 4

Remove entries from

\fICATALOGFILE\fR

matching

\fIVALUE(S)\fR\&. The

\fB\-\-del\fR

option will not overwrite

\fICATALOGFILE\fR, outputting to

stdout, unless

\fB\-\-noout\fR

is used\&.

.RE

.PP

\fB\-\-noout\fR

.RS 4

Save output to the named file rather than outputting to

stdout\&.

.RE

.PP

\fB\-\-no\-super\-update\fR

.RS 4

Do not update the

SGML

super catalog\&.

.RE

.PP

\fB\-\-shell\fR

.RS 4

Run a shell allowing interactive queries on catalog file

\fICATALOGFILE\fR\&. For the set of available commands see

the section called \(lqSHELL COMMANDS\(rq\&.

.RE

.PP

\fB\-\-sgml\fR

.RS 4

Uses

SGML

super catalogs for

\fB\-\-add\fR

and

\fB\-\-del\fR

options\&.

.RE

.PP

\fB\-v\fR, \fB\-\-verbose\fR

.RS 4

Output debugging information\&.

.RE

.PP

Invoking

\fBxmlcatalog\fR

non\-interactively without a designated action (imposed with options like

\fB\-\-add\fR) will result in a lookup of the catalog entry for

\fIENTITIES\fR

in the catalog denoted with

\fICATALOGFILE\fR\&. The corresponding entries will be output to the command line\&. This mode of operation, together with

\fB\-\-shell\fR

mode and non\-modifying (i\&.e\&. without

\fB\-\-noout\fR) direct actions, allows for a special shortcut of the void

\fICATALOGFILE\fR

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\&.

.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\&.

.PP

\fBadd \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIORIG\fR\fR\fB \fR\fB\fIREPLACE\fR\fR\fB \fR

.RS 4

Add an entry to the catalog file\&.

\fITYPE\fR

indicates the type of entry\&. Possible types are:

\fIpublic\fR, \fIsystem\fR, \fIuri\fR, \fIrewriteSystem\fR, \fIrewriteURI\fR, \fIdelegatePublic\fR, \fIdelegateSystem\fR, \fIdelegateURI\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

CATALOGFILE, outputting to

stdout, 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\&.

.RE

.PP

\fBdebug\fR

.RS 4

Print debugging statements showing the steps

\fBxmlcatalog\fR

is executing\&.

.RE

.PP

\fBdel \fR\fB\fIVALUE(S)\fR\fR

.RS 4

Remove the catalog entry corresponding to

\fIVALUE(S)\fR\&.

.RE

.PP

\fBdump\fR

.RS 4

Print the current catalog\&.

.RE

.PP

\fBexit\fR

.RS 4

Quit the shell\&.

.RE

.PP

\fBpublic \fR\fB\fIPUBLIC\-ID\fR\fR

.RS 4

Execute a Formal Public Identifier lookup of the catalog entry for

\fIPUBLIC\-ID\fR\&. The corresponding entry will be output to the command line\&.

.RE

.PP

\fBquiet\fR

.RS 4

Stop printing debugging statements\&.

.RE

.PP

\fBsystem \fR\fB\fISYSTEM\-ID\fR\fR

.RS 4

Execute a Formal Public Identifier lookup of the catalog entry for

\fISYSTEM\-ID\fR\&. The corresponding entry will be output to the command line\&.

.RE

.SH "ENVIRONMENT"

.PP

\fBXML_CATALOG_FILES\fR

.RS 4

XML

catalog behavior can be changed by redirecting queries to the user\*(Aqs 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

/etc/xml/catalog

catalog\&.

.RE

.SH "DIAGNOSTICS"

.PP

\fBxmlcatalog\fR

return codes provide information that can be used when calling it from scripts\&.

.PP

\fB0\fR

.RS 4

No error

.RE

.PP

\fB1\fR

.RS 4

Failed to remove an entry from the catalog

.RE

.PP

\fB2\fR

.RS 4

Failed to save to the catalog, check file permissions

.RE

.PP

\fB3\fR

.RS 4

Failed to add an entry to the catalog

.RE

.PP

\fB4\fR

.RS 4

Failed to look up an entry in the catalog

.RE

.SH "SEE ALSO"

.PP

\fBlibxml\fR(3)

.PP

More information can be found at

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fBlibxml\fR(3)

web page

\m[blue]\fB\%http://www.xmlsoft.org/\fR\m[]

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fBlibxml\fR(3)

catalog support web page at

\m[blue]\fB\%http://www.xmlsoft.org/catalog.html\fR\m[]

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

James Clark\*(Aqs

SGML

catalog page

\m[blue]\fB\%http://www.jclark.com/sp/catalog.htm\fR\m[]

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

OASIS

XML

catalog specification

\m[blue]\fB\%http://www.oasis-open.org/committees/entity/spec.html\fR\m[]

.RE

.sp

.SH "AUTHOR"

.PP

\fBJohn Fleck\fR <\&jfleck@inkstain\&.net\&>

.RS 4

Author.

.RE

.SH "COPYRIGHT"

.br

Copyright \(co 2001, 2004

.br