Edit
kc3-lang/libxml2/doc/xmlcatalog.xml
Nick Wellnhofer
- doc/xmlcatalog.xml
-
<?xml version="1.0"?> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ <!ENTITY xmlcatalog "<command>xmlcatalog</command>"> ]> <refentry> <refentryinfo> <title>xmlcatalog Manual</title> <productname>libxml2</productname> <copyright> <year>2001</year> <year>2004</year> </copyright> <author> <firstname>John</firstname> <surname>Fleck</surname> <affiliation> <address> <email>jfleck@inkstain.net</email> </address> </affiliation> </author> <!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this --> <!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> --> <!-- <edition>0.3</edition> --> </refentryinfo> <refmeta> <refentrytitle>xmlcatalog</refentrytitle> <manvolnum>1</manvolnum> </refmeta> <refnamediv> <refname>xmlcatalog</refname> <refpurpose> Command line tool to parse and manipulate <acronym>XML</acronym> or <acronym>SGML</acronym> catalog files. </refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>xmlcatalog</command> <group choice="opt"> <arg choice="plain"><option>--sgml</option></arg> <arg choice="plain"><option>--shell</option></arg> <arg choice="plain"><option>--convert</option></arg> <arg choice="plain"><option>--create</option></arg> <arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg> <arg choice="plain"> <group choice="opt"> <arg choice="plain"> <option>--add <replaceable>TYPE</replaceable> <replaceable>ORIG</replaceable> <replaceable>REPLACE</replaceable> </option> </arg> <arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg> </group> </arg> <arg choice="plain"><option>--noout</option></arg> <arg choice="plain"><option>--no-super-update</option></arg> <arg choice="plain"> <group choice="opt"> <arg choice="plain"><option>-v</option></arg> <arg choice="plain"><option>--verbose</option></arg> </group> </arg> </group> <arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg> <arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> <refsect1 id="description"> <title>DESCRIPTION</title> <para> &xmlcatalog; is a command line application allowing users to monitor and manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It is included in <citerefentry> <refentrytitle>libxml</refentrytitle> <manvolnum>3</manvolnum> </citerefentry>. </para> <para> 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 <acronym>XML</acronym> and <acronym>SGML</acronym> files. </para> </refsect1> <refsect1 id="options"> <title>OPTIONS</title> <para> &xmlcatalog; accepts the following options (in alphabetical order): </para> <variablelist> <varlistentry> <term> <option>--add <replaceable>TYPE</replaceable> <replaceable>ORIG</replaceable> <replaceable>REPLACE</replaceable> </option> </term> <listitem> <para> Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable> indicates the type of entry. Possible types are: <simplelist type="inline"> <member><parameter>public</parameter></member> <member><parameter>system</parameter></member> <member><parameter>uri</parameter></member> <member><parameter>rewriteSystem</parameter></member> <member><parameter>rewriteURI</parameter></member> <member><parameter>delegatePublic</parameter></member> <member><parameter>delegateSystem</parameter></member> <member><parameter>delegateURI</parameter></member> <member><parameter>nextCatalog</parameter></member> </simplelist>. <replaceable>ORIG</replaceable> is the original reference to be replaced, and <replaceable>REPLACE</replaceable> is the <acronym>URI</acronym> of the replacement entity to be used. The <option>--add</option> option will not overwrite <filename>CATALOGFILE</filename>, outputting to <filename class="devicefile">stdout</filename>, unless <option>--noout</option> is used. The <option>--add</option> will always take three parameters even if some of the <acronym>XML</acronym> catalog constructs will have only a single argument. </para> <!-- FIXME - Is my list of possible types correct? Are SGML types the same? --> </listitem> </varlistentry> <varlistentry> <term><option>--add <replaceable>FILENAME</replaceable></option></term> <listitem> <para> If the <option>--add</option> option is used following the <option>--sgml</option> option, only a single argument, a <replaceable>FILENAME</replaceable>, is used. This is used to add the name of a catalog file to an <acronym>SGML</acronym> supercatalog, a file that contains references to other included <acronym>SGML</acronym> catalog files. </para> </listitem> </varlistentry> <varlistentry> <term><option>--convert</option></term> <listitem> <para> Convert SGML catalog to XML. </para> </listitem> </varlistentry> <varlistentry> <term><option>--create</option></term> <listitem> <para> Create a new <acronym>XML</acronym> catalog. Outputs to <filename class="devicefile">stdout</filename>, ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is used, in which case it creates a new catalog file <replaceable>filename</replaceable>. </para> </listitem> </varlistentry> <varlistentry> <term><option>--del <replaceable>VALUE(S)</replaceable></option></term> <listitem> <para> Remove entries from <replaceable>CATALOGFILE</replaceable> matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option> option will not overwrite <replaceable>CATALOGFILE</replaceable>, outputting to <filename class="devicefile">stdout</filename>, unless <option>--noout</option> is used. </para> </listitem> </varlistentry> <varlistentry> <term><option>--noout</option></term> <listitem> <para> Save output to the named file rather than outputting to <filename class="devicefile">stdout</filename>. </para> </listitem> </varlistentry> <varlistentry> <term><option>--no-super-update</option></term> <listitem> <para> Do not update the <acronym>SGML</acronym> super catalog. </para> </listitem> </varlistentry> <varlistentry> <term><option>--shell</option></term> <listitem> <para> Run a shell allowing interactive queries on catalog file <replaceable>CATALOGFILE</replaceable>. For the set of available commands see <xref linkend="shell"/>. </para> </listitem> </varlistentry> <varlistentry> <term><option>--sgml</option></term> <listitem> <para> Uses <acronym>SGML</acronym> super catalogs for <option>--add</option> and <option>--del</option> options. </para> </listitem> </varlistentry> <varlistentry> <term><option>-v</option></term> <term><option>--verbose</option></term> <listitem> <para>Output debugging information.</para> </listitem> </varlistentry> </variablelist> <para> Invoking &xmlcatalog; non-interactively without a designated action (imposed with options like <option>--add</option>) will result in a lookup of the catalog entry for <replaceable>ENTITIES</replaceable> in the catalog denoted with <replaceable>CATALOGFILE</replaceable>. The corresponding entries will be output to the command line. This mode of operation, together with <option>--shell</option> mode and non-modifying (i.e. without <option>--noout</option>) direct actions, allows for a special shortcut of the void <replaceable>CATALOGFILE</replaceable> 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. </para> </refsect1> <refsect1 id="shell"> <title>SHELL COMMANDS</title> <para> Invoking &xmlcatalog; with the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens a command line shell allowing interactive access to the catalog file identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell provides a command line prompt after which the following commands (described in alphabetical order) can be entered. </para> <variablelist> <varlistentry> <term> <option>add <replaceable>TYPE</replaceable> <replaceable>ORIG</replaceable> <replaceable>REPLACE</replaceable> </option> </term> <listitem> <para> Add an entry to the catalog file. <replaceable>TYPE</replaceable> indicates the type of entry. Possible types are: <simplelist type="inline"> <member><parameter>public</parameter></member> <member><parameter>system</parameter></member> <member><parameter>uri</parameter></member> <member><parameter>rewriteSystem</parameter></member> <member><parameter>rewriteURI</parameter></member> <member><parameter>delegatePublic</parameter></member> <member><parameter>delegateSystem</parameter></member> <member><parameter>delegateURI</parameter></member> <member><parameter>nextCatalog</parameter></member> </simplelist>. <replaceable>ORIG</replaceable> is the original reference to be replaced, and <replaceable>REPLACE</replaceable> is the <acronym>URI</acronym> of the replacement entity to be used. The <option>--add</option> option will not overwrite <filename>CATALOGFILE</filename>, outputting to <filename class="devicefile">stdout</filename>, unless <option>--noout</option> is used. The <option>--add</option> will always take three parameters even if some of the <acronym>XML</acronym> catalog constructs will have only a single argument. </para> </listitem> </varlistentry> <varlistentry> <term><option>debug</option></term> <listitem> <para> Print debugging statements showing the steps &xmlcatalog; is executing. </para> </listitem> </varlistentry> <varlistentry> <term><option>del <replaceable>VALUE(S)</replaceable></option></term> <listitem> <para> Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>. </para> </listitem> </varlistentry> <varlistentry> <term><option>dump</option></term> <listitem> <para>Print the current catalog.</para> </listitem> </varlistentry> <varlistentry> <term><option>exit</option></term> <listitem> <para>Quit the shell.</para> </listitem> </varlistentry> <varlistentry> <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term> <listitem> <para> Execute a Formal Public Identifier lookup of the catalog entry for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be output to the command line. </para> </listitem> </varlistentry> <varlistentry> <term><option>quiet</option></term> <listitem> <para>Stop printing debugging statements.</para> </listitem> </varlistentry> <varlistentry> <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term> <listitem> <para> Execute a Formal Public Identifier lookup of the catalog entry for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be output to the command line. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id="environment"> <title>ENVIRONMENT</title> <variablelist> <varlistentry> <term><envar>XML_CATALOG_FILES</envar></term> <listitem> <para><acronym>XML</acronym> catalog behavior can be changed by redirecting queries to the user's own set of catalogs. This can be done by setting the <envar>XML_CATALOG_FILES</envar> 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 <filename>/etc/xml/catalog</filename> or, more specifically, <filename>${sysconfdir}/xml/catalog</filename>. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id="diagnostics"> <title>DIAGNOSTICS</title> <para> &xmlcatalog; return codes provide information that can be used when calling it from scripts. </para> <variablelist> <varlistentry> <term><errorcode>0</errorcode></term> <listitem> <para>No error</para> </listitem> </varlistentry> <varlistentry> <term><errorcode>1</errorcode></term> <listitem> <para>Failed to remove an entry from the catalog</para> </listitem> </varlistentry> <varlistentry> <term><errorcode>2</errorcode></term> <listitem> <para>Failed to save to the catalog, check file permissions</para> </listitem> </varlistentry> <varlistentry> <term><errorcode>3</errorcode></term> <listitem> <para>Failed to add an entry to the catalog</para> </listitem> </varlistentry> <varlistentry> <term><errorcode>4</errorcode></term> <listitem> <para>Failed to look up an entry in the catalog</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id="seealso"> <title>SEE ALSO</title> <para><citerefentry> <refentrytitle>libxml</refentrytitle> <manvolnum>3</manvolnum> </citerefentry> </para> <para> More information can be found at <itemizedlist> <listitem> <para><citerefentry> <refentrytitle>libxml</refentrytitle> <manvolnum>3</manvolnum> </citerefentry> web page <ulink url="https://gitlab.gnome.org/GNOME/libxml2"/> </para> </listitem> <listitem> <para><citerefentry> <refentrytitle>libxml</refentrytitle> <manvolnum>3</manvolnum> </citerefentry> catalog support web page at <ulink url="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support"/> </para> </listitem> <listitem> <para>James Clark's <acronym>SGML</acronym> catalog page <ulink url="http://www.jclark.com/sp/catalog.htm"/> </para> </listitem> <listitem> <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/> </para> </listitem> </itemizedlist> </para> </refsect1> </refentry>