xmlcatalog

## Name

xmlcatalog — Command line tool to parse and manipulate XML or SGML catalog files.

## Synopsis

`xmlcatalog` [ `--sgml` | `--shell` | `--convert` | `--create` | `--del `VALUE(S)`` | [ `--add `TYPE` `ORIG` `REPLACE`` | `--add `FILENAME`` ] | `--noout` | `--no-super-update` | [ `-v` | `--verbose` ] ] {`CATALOGFILE`} {`ENTITIES`...}

## DESCRIPTION

xmlcatalog is a command line application allowing users to monitor and manipulate XML and SGML catalogs. It is included in libxml(3).

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.

## OPTIONS

xmlcatalog accepts the following options (in alphabetical order):

`--add `TYPE` `ORIG` `REPLACE``

  Add an entry to `CATALOGFILE`. `TYPE` indicates the type of entry. Possible types are: `public`, `system`, `uri`, `rewriteSystem`, `rewriteURI`, `delegatePublic`, `delegateSystem`, `delegateURI`, `nextCatalog`. `ORIG` is the original reference to be replaced, and `REPLACE` is the URI of the replacement entity to be used. The `--add` option will not overwrite `CATALOGFILE`, outputting to `stdout`, unless `--noout` is used. The `--add` will always take three parameters even if some of the XML catalog constructs will have only a single argument.

`--add `FILENAME``

  If the `--add` option is used following the `--sgml` option, only a single argument, a `FILENAME`, 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.

`--convert`

  Convert SGML catalog to XML.

`--create`

  Create a new XML catalog. Outputs to `stdout`, ignoring `filename` unless `--noout` is used, in which case it creates a new catalog file `filename`.

`--del `VALUE(S)``

  Remove entries from `CATALOGFILE` matching `VALUE(S)`. The `--del` option will not overwrite `CATALOGFILE`, outputting to `stdout`, unless `--noout` is used.

`--noout`

  Save output to the named file rather than outputting to `stdout`.

`--no-super-update`

  Do not update the SGML super catalog.

`--shell`

  Run a shell allowing interactive queries on catalog file `CATALOGFILE`. For the set of available commands see the section called “SHELL COMMANDS”.

`--sgml`

  Uses SGML super catalogs for `--add` and `--del` options.

`-v`, `--verbose`

  Output debugging information.

Invoking xmlcatalog non-interactively without a designated action (imposed with options like `--add`) will result in a lookup of the catalog entry for `ENTITIES` in the catalog denoted with `CATALOGFILE`. The corresponding entries will be output to the command line. This mode of operation, together with `--shell` mode and non-modifying (i.e. without `--noout`) direct actions, allows for a special shortcut of the void `CATALOGFILE` 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.

## SHELL COMMANDS

Invoking xmlcatalog with the `--shell `CATALOGFILE`` option opens a command line shell allowing interactive access to the catalog file identified by `CATALOGFILE`. Invoking the shell provides a command line prompt after which the following commands (described in alphabetical order) can be entered.

`add `TYPE` `ORIG` `REPLACE``

  Add an entry to the catalog file. `TYPE` indicates the type of entry. Possible types are: `public`, `system`, `uri`, `rewriteSystem`, `rewriteURI`, `delegatePublic`, `delegateSystem`, `delegateURI`, `nextCatalog`. `ORIG` is the original reference to be replaced, and `REPLACE` is the URI of the replacement entity to be used. The `--add` option will not overwrite `CATALOGFILE`, outputting to `stdout`, unless `--noout` is used. The `--add` will always take three parameters even if some of the XML catalog constructs will have only a single argument.

`debug`

  Print debugging statements showing the steps xmlcatalog is executing.

`del `VALUE(S)``

  Remove the catalog entry corresponding to `VALUE(S)`.

`dump`

  Print the current catalog.

`exit`

  Quit the shell.

`public `PUBLIC-ID``

  Execute a Formal Public Identifier lookup of the catalog entry for `PUBLIC-ID`. The corresponding entry will be output to the command line.

`quiet`

  Stop printing debugging statements.

`system `SYSTEM-ID``

  Execute a Formal Public Identifier lookup of the catalog entry for `SYSTEM-ID`. The corresponding entry will be output to the command line.

## ENVIRONMENT

`XML_CATALOG_FILES`

  XML catalog behavior can be changed by redirecting queries to the user's own set of catalogs. This can be done by setting the `XML_CATALOG_FILES` environment variable to a space-separated list of catalogs. Use percent-encoding to escape spaces or other characters. An empty variable should deactivate loading the default catalog from `/etc/xml/catalog` or, more specifically, `${sysconfdir}/xml/catalog`.

## DIAGNOSTICS

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

0

  No error

1

  Failed to remove an entry from the catalog

2

  Failed to save to the catalog, check file permissions

3

  Failed to add an entry to the catalog

4

  Failed to look up an entry in the catalog

## SEE ALSO

libxml(3)

More information can be found at

- libxml(3) web page https://gitlab.gnome.org/GNOME/libxml2

- libxml(3) catalog support web page at https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support

- James Clark's SGML catalog page http://www.jclark.com/sp/catalog.htm

- OASIS XML catalog specification http://www.oasis-open.org/committees/entity/spec.html